Advanced Trigger Execution

Advanced reference for how Overcut manages multiple triggers, prevents conflicts, and handles complex execution scenarios.

For basic trigger setup, see Triggers and Workflow Execution Control.

Multiple Trigger Behavior

Mention Triggers

Any @overcut mention triggers ALL workflows with mention trigger type.

Slash Commands

Each slash command triggers only its specific workflow and can terminate active agent steps.

Sequential Execution

All workflows for the same PR/issue run one at a time, ordered by priority.

Event Merging

Multiple triggers of the same queued workflow merge into a single execution.

Key Concepts

Trigger Specificity

Mention (@overcut): Triggers ALL mention workflows regardless of text after mention
Slash Command (/review): Triggers only the specific workflow registered for that command
Event Triggers: Each workflow has one primary trigger type (e.g., pull_request_opened)

Slash Command Termination

Slash commands have special power to interrupt active work:

Graceful Termination

Active agent steps (both agent.run and agent.session) receive termination signal

Grace Period

Agents get 5 minutes to complete current operation before stopping

Session Cleanup

Active sessions are cleared immediately and stop receiving new comments

New Workflow

Slash command workflow queues or starts normally

Example:

User: "@overcut help with this bug"  → Session starts
User: "Can you explain line 45?"     → Routes to session
User: "/review"                      → Terminates session, starts review

Parallel Execution & Locking

Resource-Based Locking

Overcut ensures workflows don’t conflict by locking execution per resource:

Sequential per Resource

Only one workflow runs per issue/PR at a time to prevent conflicts

Parallel Across Resources

Different issues/PRs can run workflows simultaneously

How Locking Works

Same Resource = Sequential Execution:

# All workflows for PR #123 run one at a time
PR #123 opened     → Starts immediately
Comment on PR #123 → Queued (waits for first to finish)
Label on PR #123   → Queued (waits in line)
Review on PR #123  → Queued (waits in line)

Different Resources = Parallel Execution:

# These run simultaneously
PR #123 workflow   ✅ Running
Issue #456 workflow ✅ Running  
PR #789 workflow   ✅ Running

Queue Management & Deduplication

Intelligent Event Merging

When the same workflow is triggered multiple times while queued, events automatically merge to prevent redundant executions:

Duplicate Detection

System checks if the same workflow is already queued for the same lock key

Event Merging

New trigger merges with existing queued workflow instead of creating duplicate

Priority-Based Processing

Queued workflows are processed by priority, then first-in-first-out:

Priority	Description	Processing Order
`1` (High)	Critical workflows	Processed first
`5` (Default)	Standard workflows	Default priority
`10` (Low)	Background tasks	Processed last

Automatic Deduplication

When the same workflow is triggered multiple times while queued, events automatically merge:

# Example: Auto-triage workflow with issue_labeled trigger
01 - Label "bug" added     → Execution starts (running)
02 - Label "critical" added → Queued (first still running)  
03 - Label "security" added → Merged with queued execution
05 - First completes       → Queued execution runs with all labels

Advanced Queue Features

Delayed Execution

Workflows can be configured with delays to batch rapid events:

name: "Batch Comment Analysis"
trigger:
  type: "issue_commented"
  settings:
    delaySeconds: 30  # Wait 30 seconds before processing

steps:
  - name: "analyze-comments"
    type: "agent"
    instruction: "Analyze recent comment activity"

Benefits:

Batches rapid-fire events (multiple comments, labels)
Reduces redundant executions
Allows time for related events to merge

Priority Configuration

Control execution order with priority settings (1-100 scale):

Priority	Use Case	Example
1-3	Critical workflows	Security scans, incident response
4-6	Normal workflows	Code reviews, standard automation
7-100	Background tasks	Documentation, metrics collection

name: "Security Scan"
priority: 1  # Runs first
trigger:
  type: "pull_request_opened"

Multiple Mention Workflows

If you have multiple workflows with mention trigger, all will be triggered by any @overcut mention:

# Both triggered by "@overcut help me"
- name: "Quick Help" (priority: 5)
- name: "Full Analysis" (priority: 8)

Solution: Use slash commands for specificity:

/help → triggers only Quick Help
/analyze → triggers only Full Analysis

Event Sequence Example

01 - PR opened           → "Initial Review" starts (priority: 5)
02 - Label "security"    → "Security Scan" queued (priority: 1)  
03 - Comment "@overcut"  → "Help" queued (priority: 5)
05 - Initial Review done → Security Scan starts (highest priority)
07 - Security Scan done  → Help starts

Custom Event Lock Keys

Custom Events share the same dispatcher queue and merging behavior as built-in triggers, but the caller controls the lock scope via the optional ?lockKey= query parameter.

Caller URL	Lock key the dispatcher uses
No `lockKey`	`custom:<eventId>:<requestId>` (unique per call, never merges)
`?lockKey=X`	`custom:<eventId>:X`
`?projectId=P&lockKey=X`	`custom:<eventId>:P:X`
`?projectId=P` (no `lockKey`)	`custom:<eventId>:P:<requestId>`

Two implications:

Two calls to different projects with the same lockKey run in parallel: the project ID is folded into the key.
When projectId is omitted (workspace-wide fan-out from a single inbound call), the matched workflows across all allowed projects serialize together under the shared scope, because they represent a single real-world occurrence.

lockKey must match ^[A-Za-z0-9_.\-:]{1,128}$. Invalid values return 400 lockkey_invalid from the dispatcher.

Best Practices

Use Priorities Wisely

Reserve 1-3 for critical workflows, use default (5) for most cases.

Design for Interruption

Expect users to use slash commands to change direction mid-workflow.

Leverage Merging

Trust automatic event merging to reduce redundant executions.

Choose Right Triggers

Use slash commands for specific actions, mentions for general help.

FAQ

Can workflows run in parallel on different PRs?

Yes! Sequential execution only applies to the same PR or issue. Different resources can have workflows running simultaneously.

When does event merging happen?

Only when a workflow is queued (waiting to run), not while it’s running. If workflow A is running and triggered twice more, the second trigger queues and the third merges with it.

How do I stop an agent step early?

You can terminate agent steps using either comments or UI controls:Via Comments:

/done: Completes the current agent session step and continues to the next workflow step
/quit: Terminates the entire workflow immediately

Via UI (Execution Logs):

Complete Step button: Requests the agent to complete and return results ASAP
Quit Workflow button: Terminates all running steps and marks the workflow as canceled

Comment commands are processed immediately before the agent receives them, while UI buttons send termination requests to the running agent.

What's the difference between mentions and slash commands?

Mentions (@overcut): Trigger all mention workflows, route to active sessions
Slash commands (/review): Trigger specific workflow, terminate active agent steps

Interactive Sessions

Session behavior and comment routing mechanics

Slash Commands

Setting up and using slash command triggers

Basic Triggers

Trigger types and basic configuration

Execution Control

Resource locking and queue management

​Multiple Trigger Behavior

Mention Triggers

Slash Commands

Sequential Execution

Event Merging

​Key Concepts

​Trigger Specificity

​Slash Command Termination

​Parallel Execution & Locking

​Resource-Based Locking

Sequential per Resource

Parallel Across Resources

​How Locking Works

​Queue Management & Deduplication

​Intelligent Event Merging

​Priority-Based Processing

​Automatic Deduplication

​Advanced Queue Features

​Delayed Execution

​Priority Configuration

​Multiple Mention Workflows

​Event Sequence Example

​Custom Event Lock Keys

​Best Practices

Use Priorities Wisely

Design for Interruption

Leverage Merging

Choose Right Triggers

​FAQ

​Related Documentation

Interactive Sessions

Slash Commands

Basic Triggers

Execution Control

Multiple Trigger Behavior

Key Concepts

Trigger Specificity

Slash Command Termination

Parallel Execution & Locking

Resource-Based Locking

How Locking Works

Queue Management & Deduplication

Intelligent Event Merging

Priority-Based Processing

Automatic Deduplication

Advanced Queue Features

Delayed Execution

Priority Configuration

Multiple Mention Workflows

Event Sequence Example

Custom Event Lock Keys

Best Practices

FAQ

Related Documentation