Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / automation-services

Automation services

Automation services run scheduled, manual, and event-triggered agent work against a saved workspace and host. They validate the target, apply safe readiness and ownership checks, invoke a terminal or chat agent through an agent-capable runtime service, and keep durable run history. See Agent workspaces for the workspace model. Related pages cover Agent integrations and hooks, Agent protocol client sessions, Workspace and worktree lifecycle, AI vault sessions, and Native agent conversations.

Automation definitions

Automation records

An automation record is the saved plan for repeated or event-driven agent work. It stores the prompt, agent, schedule, time zone, launch surface, workspace mode, target context, and optional precheck. Bot automations can also store event rules and a one-run wait.

The launch surface selects how the agent receives work:

  • Terminal: start or reuse an agent in a terminal that the automation can observe.
  • Chat: send the prompt to an agent conversation through the runtime chat service.

The record selects one of two workspace modes:

  • Existing workspace: use the selected workspace. A run can reuse a compatible idle agent session when the surface and workspace allow it.
  • New workspace per run: create a separate managed worktree for each run. The new workspace stays linked to the automation and run that created it.

Task-source context remains separate from the execution target when a prompt came from an external task provider. This lets the source account and the workspace run on different authorities without changing the run target. Extra agent arguments are validated for the selected agent and apply only to a fresh launch.

References: src/…/automation-definition.ts• L19-104 src/…/task-source-context.ts• L29-47 src/…/automation-event-triggers.ts• L87-92 src/…/bot-automation-place-refs.ts• L80-155

Event triggers and waits

Event triggers start bot automations when a matching connector event, webhook call, Gmail event, or Calendar event arrives. Filters can limit the place, subject, text, person, or event kind. The source event key prevents duplicate runs, while later events on the same subject can fold into an unfinished run.

A one-run wait starts on its first accepted event or at its deadline. The first winner claims the wait. The wait then ends after its run, or expires without launching when it has no deadline.

Event text is treated as outside information, not as agent instructions. The prompt keeps service facts outside a quote and places text from the source inside a bounded quote. A manual run of an event automation replays its latest event so it has the same context as a new event.

References: src/…/automation-event-triggers.ts• L191-265 src/…/automation-event-triggers.ts• L287-370 src/…/automation-trigger-runs.ts• L102-177 src/…/automation-due-runs.ts• L43-95 src/…/automation-event-prompt.ts• L96-150

Run records

A run record is the durable history of one scheduled occurrence, manual launch, or source event. It preserves the target workspace, launch surface, session or terminal identity, precheck result, output snapshot, error, usage data, and event context after live runtime state changes.

Run history separates work that still needs observation from final results. Repeated unavailable occurrences and repeated event refusals can share one history record with an occurrence count and latest occurrence time. Usage may be known or unavailable; unavailable usage is not treated as zero.

Launch acceptance also has a durable receipt. The receipt lets a restarted runtime recover a launch that succeeded even when the original reply was lost, without sending the prompt a second time.

References: src/…/automation-run.ts• L6-18 src/…/automation-run.ts• L113-167 src/…/run-writer.ts• L20-77 src/…/automation-run-receipt.ts• L7-73

Schedule and ownership

Schedule evaluation

The automation service checks enabled records on a regular tick. It gates evaluation on service readiness and a settled wake window, then handles each due record without allowing one malformed schedule to block later records. For each due record it finds the latest schedule occurrence, applies the missed-run grace window, records at most one run for that occurrence, and advances the next occurrence after the decision.

Schedules use cron or recurrence rules. A bad schedule is isolated to its own record. A target that is temporarily unavailable produces a durable skip or a folded unavailable result instead of repeated dispatch attempts. A one-run wait is claimed in the same automation lane as an event, so a deadline and an event cannot both start it.

This diagram shows how a due occurrence becomes a skip, a dispatch, or a one-run expiry.

flowchart TD
    A[Enabled automation] --> B{Due occurrence or event?}
    B -- No --> A
    B -- Yes --> C{Inside grace window?}
    C -- No --> D[Record missed run]
    C -- Yes --> E{Wait already claimed?}
    E -- Yes --> F[Ignore occurrence]
    E -- No --> G[Resolve owner and target]
    G --> H{Target and service ready?}
    H -- No --> I[Record or fold unavailable run]
    H -- Yes --> J[Persist dispatch intent]
    D --> K[Advance next occurrence]
    I --> K
    J --> L[Invoke agent runtime]
    L --> K

References: src/…/automation-service.ts• L123-139 src/…/automation-due-runs.ts• L8-41 src/…/automation-trigger-runs.ts• L46-77 src/…/automation-wake-settle.ts• L43-100 src/…/dispatch-refusal.ts• L110-186

Execution targets

An execution target identifies the project setup, workspace path, and host where the agent runs. The automation’s destination host stores and schedules the record; the saved run context identifies the host and setup that must execute the work.

The target is checked again before dispatch. The saved host, project setup, repository, and path must still match the current state. A workspace that maps to more than one host is refused because the service cannot choose a safe execution host.

Bot targets resolve to the bot’s folder workspace and agent identity. The service refuses a missing bot, paused bot, disabled bot service, or missing folder before it starts work.

References: src/…/run-target-resolution.ts• L168-230 src/…/bot-run-target.ts• L24-59 src/…/automation-dispatch-request.ts• L103-116

Owner fencing

Owner fencing binds an automation to a particular host incarnation. A host incarnation means the registered or paired instance that currently owns the target, not only its stable host identifier.

SSH targets carry a registration generation. Runtime targets carry a pairing revision or authority identity. The service compares the saved owner with the current projection before it reads, changes, or dispatches an automation. A stale, removed, ambiguous, or orphaned record is refused instead of being silently adopted by a replacement host.

The same owner precondition travels from a list or detail view into a mutation. This prevents an action from applying to a record whose host changed after the user saw it. Owner migration stamps missing generations but does not overwrite a captured generation that may identify a replacement target.

References: src/…/automation-owner-migration.ts• L24-53 src/…/automation-owner-migration.ts• L93-107 src/…/automation-owner-migration.ts• L152-185 src/…/automation-dispatch-request.ts• L103-116 src/…/dispatch-refusal.ts• L76-106

Workspace preparation

Workspace modes

An existing-workspace run uses the workspace saved in the automation. A new-per-run run creates a fresh worktree from the selected project and base state, then records that worktree as part of the run.

Session reuse applies only to an existing workspace. New-per-run work receives a new execution context so two runs do not share a worktree by accident. A new worktree records automation provenance with the project, host, automation, and run that created it.

References: src/…/automation-definition.ts• L19-23 src/…/automation-terminal-launch.ts• L66-121 src/…/automation-chat-agent-launch.ts• L60-99

Setup decisions

Workspace setup is an explicit run-or-skip choice saved with the automation. The save flow resolves setup trust before a scheduled run so headless execution does not stop for a human prompt.

The setup decision is scoped to the selected project host. If setup information cannot be checked, the automation fails closed and skips inherited setup. This favors a predictable scheduled run over an unattended action with unknown setup behavior.

References: src/…/automation-setup-decision.ts• L46-96 src/…/automation-orca-save.ts• L99-120 src/…/automation-chat-agent-launch.ts• L80-96

Agent argument policy

Extra agent arguments let an automation select safe agent options such as model, effort, or an allowed directory. The shared parser rejects shell syntax, control characters, unknown options, duplicate single-use options, and values outside the selected agent’s allowlist.

The host must support the extra-argument capability. Older hosts fail closed rather than dropping the field and launching with different behavior. Validated values merge with host defaults only for the fresh terminal or workspace launch.

References: src/…/automation-extra-agent-args.ts• L30-46 src/…/automation-extra-agent-args.ts• L158-225 src/…/automation-extra-agent-args.ts• L251-291 src/…/automation-terminal-launch.ts• L132-158

Service prechecks

Precheck gate

A precheck is an optional command that tests whether a scheduled target is ready. The service runs it in the target working directory on the local host or through the selected SSH connection before it starts the agent.

The precheck passes only when it exits with code zero without an error or timeout. A non-zero exit, launch error, or timeout records a bounded result and changes the scheduled run to skipped_precheck. Manual and event runs do not use this gate.

The service resolves the target before running the command. A stale project setup therefore cannot cause a command to test a path that no longer represents the saved target.

References: src/…/automation-dispatch-request.ts• L244-271 src/…/automation-launch-runner.ts• L54-66 src/…/automation-dispatch-request.ts• L173-224

Dispatch services

Desktop dispatch

The desktop path sends a signed dispatch request to a ready renderer for terminal automations. The renderer prepares the selected workspace, restores the needed host connection, applies the scheduled precheck, and starts the agent in a background terminal.

Chat automations use the runtime chat dispatcher even when the renderer is ready. This keeps the saved launch surface authoritative and prevents a chat automation from being redirected to a terminal because of the current view.

The user’s current view does not need to change for a background run. The dispatch records the session, pane, and PTY identities that belong to the run so later observation and history use the process or conversation that actually received the prompt.

References: src/…/automation-dispatch-request.ts• L234-241 src/…/automation-service.ts• L305-331 src/…/automation-launch-runner.ts• L91-124

Headless dispatch

The headless path runs schedules without a renderer. The runtime service launches a terminal agent, a structured chat agent, or a bot run in the resolved target.

Terminal launches are terminal-only because automation completion depends on terminal identity and terminal evidence. Chat launches use the structured agent session host. Bot runs use the bot’s own folder and structured conversation services, so they do not need a desktop window.

Scheduled runs do not take an interactive WSL action. A manual run may start a stopped WSL distribution because it represents an explicit user action. The runtime publishes the terminal or chat surface before later prompt delivery or completion work settles.

References: src/…/runtime-automation-service.ts• L35-218 src/…/automation-terminal-launch.ts• L37-183 src/…/automation-chat-agent-launch.ts• L31-125 src/…/bot-automation-launch.ts• L161-289

Dispatch durability

Dispatch persists the run’s intent before it starts work outside the service. This makes the run visible as dispatching even if the process ends while the runtime is creating a terminal or sending the prompt.

After the claim, the service reads the run and automation again. It compares the saved automation definition and execution destination with the values used to create the run. The headless path repeats this check after a precheck that may take time, so a changed instruction, workspace, host, or path becomes a refusal instead of a stale launch.

Each fresh launch and chat reuse send has a stable operation ID. A runtime receipt distinguishes a published launch from an accepted prompt, so recovery can report the true outcome without resending work.

A launcher can publish a terminal or chat session before prompt delivery finishes. The run stays dispatching until delivery succeeds or fails. If delivery fails after a surface opens, the run keeps that target and its launch time so an engineer can inspect the partial start.

The service serializes work for one automation while it claims a run, performs the precheck, selects a session, and records its target. It releases that lane while the agent works. A stop, deletion, instruction change, host move, or unavailable dispatch surface can cancel or refuse the launch rather than dispatch an action based on stale state.

References: src/…/automation-dispatch-request.ts• L76-224 src/…/automation-launch-runner.ts• L68-160 src/…/automation-run-operation.ts• L4-15 src/…/automation-run-receipt.ts• L23-73 src/…/automation-service.ts• L300-331

Execution lifecycle

Run states

The run moves from a durable pending record to dispatching and then to dispatched after the runtime accepts the agent surface. The service observes the terminal, chat journal, or bot turn and writes a final result only when it has enough evidence to support that result.

The shared lifecycle is:

  1. Create and persist the run.
  2. Resolve the target and run the scheduled precheck when one applies.
  3. Claim dispatch and recheck the automation and target.
  4. Start or reuse the terminal, chat session, or bot conversation.
  5. Confirm prompt acceptance and observe agent evidence.
  6. Save the final status, output snapshot, and usage data.

This diagram shows the durable records and live services involved in one run.

sequenceDiagram
    participant S as Automation service
    participant P as Precheck
    participant R as Desktop or runtime service
    participant A as Terminal, chat, or bot agent
    participant H as Run history

    S->>H: Persist pending run
    S->>P: Check scheduled target
    P-->>S: Pass or skip result
    S->>R: Dispatch with target and run identity
    R->>A: Start or reuse agent surface
    R-->>S: Publish target and receipt
    S->>A: Observe status, journal, or turn
    A-->>S: Completion, failure, or lost contact
    S->>H: Persist final result

References: src/…/automation-service.ts• L149-191 src/…/automation-launch-runner.ts• L54-162 src/…/automation-dispatch-request.ts• L132-241 src/…/runtime-automation-service.ts• L86-160 src/…/run-writer.ts• L52-77

Completion evidence

Terminal completion evidence combines agent status, terminal state, and process output. A reused pane must show evidence from the current run before an idle state can complete it; an earlier done state or a ready shell is not enough.

Chat completion evidence comes from the accepted run submission and its journal turn. A queued, rejected, withdrawn, interrupted, or incomplete turn remains a failed or unfinished run rather than a success. Bot completion follows the turn that received the automation prompt and delivers the result to its configured chat or external thread.

The watcher keeps a bounded output snapshot and records a truthful failure when it reaches its observation limit without completion evidence. It does not claim success from lost contact alone.

References: src/…/run-completion-watcher.ts• L10-23 src/…/runtime-chat-run-observer.ts• L16-80 src/…/bot-automation-launch.ts• L240-287 src/…/runtime-automation-service.ts• L129-160

Headless terminal retention

Headless hosts have no renderer to close completed run terminals. Their runtime service keeps recent terminals viewable, waits through a grace period, and closes older terminals only when it can show that the run is safe to release.

Retention never closes a terminal that a client used or whose use state is unknown. It also keeps a failed or unfinished run while an agent may still be alive. A terminal is released only after a completed result or proof that the PTY contains an idle shell. The run keeps its status, error, and output after its live terminal identity is removed.

Retention and dispatch share the automation lane. This prevents cleanup from closing a pane while a new run is selecting or reusing it.

References: src/…/runtime-automation-service.ts• L221-297 src/…/automation-terminal-launch.ts• L297-309

Run history access

The run view opens the live terminal or chat session when its recorded identity still exists. If the workspace remains but the live surface is gone, it opens the workspace or shows the saved output snapshot with the run metadata.

Remote runs use the paired runtime’s recorded identity. The client opens a mirrored surface only after it confirms that the pane, PTY, or session belongs to the run’s owner environment. A failed history read stays visible as unavailable; it is not shown as an empty history.

The run page can rerun dispatch failures and selected unavailable outcomes. It presents translated failure reasons when a newer run has a known failure code, while older or unknown records keep their stored error text.

References: src/…/automation-run-view-state.ts• L35-150 src/…/AutomationRunDetailsPage.tsx• L43-103 src/…/AutomationRunHistory.tsx• L215-375 src/…/automation-run-open-target.ts• L1

Agent runtime services

Terminal launches

Terminal automation launches use the shared agent-capable runtime boundary. The automation supplies the agent, prompt, run title, workspace target, and validated extra arguments; the runtime supplies the terminal and host-specific execution context.

The terminal path is deliberately terminal-only because automation completion depends on terminal identity and terminal evidence. The runtime can create the workspace and startup terminal together or launch a terminal in an existing workspace. A compatible existing terminal can receive a new prompt only after its workspace, host, PTY, and live state match the run.

References: src/…/automation-terminal-launch.ts• L37-183 src/…/automation-terminal-launch.ts• L201-264 src/…/automation-launch.ts• L14-45

Chat launches

Chat automation launches use the runtime’s structured agent session host. A reuse launch first tries a compatible existing conversation. If reuse does not accept the work, a fresh launch creates the requested workspace and agent surface through the common launch service.

The launch records the published terminal or chat target as soon as the runtime exposes it. It then requires a prompt outcome that is journaled or handed to a terminal. A started agent without confirmed prompt delivery is a launch failure that keeps the published target available for inspection.

The saved surface controls this choice. A chat launch is not an accidental fallback from a missing renderer, and a terminal launch is not silently converted into a structured session. A launch that waits too long expires rather than being reported as accepted.

References: src/…/automation-chat-agent-launch.ts• L48-125 src/…/automation-chat-session-reuse.ts• L17-119 src/…/automation-launch.ts• L14-31

Bot launches

Bot automations use the runtime’s structured conversation services instead of a desktop terminal. The bot target supplies the bot identity, folder workspace, and run mode. The dispatcher selects a new conversation, the bot’s Chat, a selected bot chat, or an existing session.

For an event run, the dispatcher adds the checked event context to the prompt and records the run message for later display. Results can remain in the bot’s Chat, answer the owning external thread, post to a linked thread, or become a Linear issue comment. A run that answers in an existing conversation waits for that conversation’s turn rather than marking another turn as its own.

References: src/…/bot-run-target.ts• L32-59 src/…/bot-automation-launch.ts• L161-289 src/…/bot-automation-service-wiring.ts• L12-53 src/…/automation-event-prompt.ts• L101-150

Launch receipts

Launch publication and prompt acceptance are separate facts. The runtime records an operation receipt for each fresh launch or chat reuse send, and the automation service reads that receipt after a lost reply or restart.

When the receipt says that the prompt was accepted, recovery rebuilds the terminal or chat target from the receipt. It does not send the prompt again. If no accepted receipt exists, the service keeps a known published target for the error when possible, or returns the original launch error.

The target can gain optional display metadata after publication. Missing workspace names or terminal presentation data do not erase the workspace, pane, PTY, or session identity that identifies the accepted run.

References: src/…/automation-run-operation.ts• L4-15 src/…/automation-run-receipt.ts• L23-73 src/…/automation-agent-run-result.ts• L10-92 src/…/runtime-automation-service.ts• L60-128

Runtime observation

The runtime service converts terminal status, chat journal state, or bot turn state into the automation result. Terminal observation checks the run’s pane and PTY identity before it trusts process evidence. Chat observation follows the accepted submission until its journal turn reaches a final outcome. Bot observation follows the turn watcher until the bot result is delivered.

This boundary keeps scheduling concerns separate from prompt execution. The automation service owns timing, target choice, fencing, and run history. The agent runtime owns launch, prompt delivery, session state, and agent evidence.

Other runtime orchestration can deliver work to structured sessions or terminal workers. Those worker Run and Dispatch records are not the automation run record; automation keeps its own receipt and history while using the runtime’s agent-capable services.

References: src/…/runtime-automation-service.ts• L86-160 src/…/runtime-chat-run-observer.ts• L16-217 src/…/run-completion-watcher.ts• L74-195 src/…/bot-automation-launch.ts• L61-72

Automation host catalog

Host projections

The automation page projects local, paired runtime, SSH, and orphan scopes into one host catalog. A stable catalog key names the authority and selector, while an owner reference adds the pairing revision or SSH registration generation needed for safe actions.

The catalog uses mirrored state only. Rendering it does not probe runtimes or open SSH sessions. A target without a verified registration generation stays view-only. A removed or unhydrated target stays visible as unavailable or unknown, so missing data is not mistaken for an empty host.

Equal SSH target IDs under different authorities remain separate. A runtime-owned ephemeral target is hidden from normal choices, while a saved removed target can remain as a ghost so the user can understand why its automation is unavailable.

References: src/…/automation-host-catalog.ts• L23-43 src/…/automation-host-catalog.ts• L139-207 src/…/automation-host-catalog.ts• L240-303 src/…/automation-host-catalog-order.ts• L21-73

Host availability

Host availability distinguishes loading, disconnected, removed, unverified, unsupported, and ready states. The page offers recovery actions such as reconnecting a runtime or SSH target, but it does not claim that a host has no automations until the relevant catalog and query state is settled.

The same rule applies to external managers. A failed host query appears as unchecked or unavailable rather than as an empty manager list. Partial host failures are announced without replacing valid data from other hosts.

References: src/…/AutomationHostFilterNotice.tsx• L16-32 src/…/AutomationHostFilterNotice.tsx• L68-155 src/…/external-automation-unchecked-hosts.ts• L8-59

External automation managers

Host-scoped managers

The automation surface can show jobs owned by an external manager beside native automations. An external manager ID is unique only inside its host scope, so the UI carries the authority and host selector captured during discovery into later reads and actions.

Before the desktop contacts a relay or starts a provider command, it checks the provider, authority, target visibility, and captured SSH generation again. A hidden or changed target fails closed without probing it. A runtime must also advertise the host-scoped list capability before its scoped results are trusted.

References: src/…/automations-types.ts• L260-326 src/…/ExternalAutomationManagers.tsx• L30-41 src/…/automation-capability-probe.ts• L65-105 src/…/external-automation-owner-guard.ts• L46-94

External action lifecycle

External jobs support provider actions such as run, pause or resume, and delete. The page disables actions while the manager is unavailable, while a host is connecting, or while another action is active. After an action it refreshes the same host-scoped manager view.

Host query errors distinguish a temporary authority or timeout problem from a permission error, an unsupported contract, an invalid response, or an owner conflict. Only temporary failures use the bounded retry budget. A host that was not checked is shown as unavailable or unknown rather than as an empty job list.

References: src/…/ExternalAutomationManagers.tsx• L77-145 src/…/AutomationListExternalRow.tsx• L70-89 src/…/external-automation-source-availability.ts• L10-64

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the saved launch surface aligned across editor state, dispatch routing, runtime launch, receipts, observation, and run-view opening.
  • Keep destination authority and execution host distinct. A storage or scheduler move must not silently change the workspace host.
  • Keep owner generations and pairing revisions aligned across host projection, saved records, mutations, target resolution, and dispatch.
  • Keep scheduled and manual WSL rules aligned. A scheduled run must not start an unverifiable stopped distro as a side effect.
  • Keep precheck target resolution, run fencing, late target rechecks, and per-automation serialization aligned.
  • Keep event keys, subject folding, grace handling, one-run claims, and event-in-turn records aligned across event delivery and run history.
  • Keep event text quoting and asker labels aligned with the connector event contract. Source text must not become agent instructions.
  • Keep bot target checks aligned with bot service settings, pause state, folder workspace, and bot launch routing.
  • Keep fresh-launch and reuse operation IDs aligned with receipt lookup. Recovery must never resend a prompt after an accepted operation.
  • Keep terminal, chat, and bot completion evidence tied to the current run. An old terminal status or unrelated journal turn must not settle a new run.
  • Keep new-per-run workspace provenance aligned with automation, run, project, and host attribution.
  • Keep headless terminal retention behind the same automation lane as dispatch and protect terminals whose client-use state is unknown.
  • Keep unavailable history and unavailable usage distinct from true empty history or zero usage.
  • Keep published launch targets separate from prompt acceptance. A visible surface must not be treated as accepted until the prompt outcome or receipt confirms it.
  • Keep launch error recovery attached to the published target when available. Optional display metadata must not replace the identity needed to inspect the run.
  • Keep the dispatching state and launch time when delivery fails after a terminal or chat surface has opened.

Important failure modes

TriggerConsequenceGuard
Saved host generation or pairing identity no longer matches the live ownerThe run or action is refused instead of using a replacement hostOwner fence and target recheck
Destination host and execution host are treated as one identityThe automation can be stored or scheduled by the wrong authoritySeparate destination selector from run-context execution host
Project setup or workspace path changes before a scheduled runThe precheck and agent do not run against the wrong pathTarget resolution before precheck and dispatch
Scheduled precheck exits non-zero or times outThe agent is not started and the run becomes skipped_precheckZero-exit pass rule and bounded execution
Automation definition or destination changes after dispatch claimThe run becomes unavailable instead of launching with stale instructionsDefinition and destination comparison before launch and after a long precheck
Saved surface routes to an unavailable dispatch pathThe run skips or fails instead of silently changing from chat to terminal or vice versaSurface-specific dispatcher selection
Launch reply is lost after the runtime accepted the promptA retry could duplicate the agent workStable operation ID and durable launch receipt
Reused pane contains only an earlier done or an idle shellThe run waits or fails instead of claiming the earlier run completed itCurrent-run terminal identity and evidence window
Chat submission is queued, rejected, withdrawn, or interruptedThe run does not claim successful prompt deliveryAccepted submission and journal turn observation
Event source resends the same keyThe automation does not start duplicate workEvent-key deduplication and subject folding
Event text contains agent-like instructionsSource content can redirect the agent if treated as a promptBounded quoted event text and service-owned header
Event and one-run deadline arrive togetherTwo agents could start for one waitShared automation lane and one-run claim
Bot is paused, removed, disabled, or its folder is missingThe run is skipped without opening a conversationBot target resolution before dispatch
PTY or chat contact is lost without completion evidenceThe run becomes a truthful failure instead of a false successRuntime observer and retained-run reconciliation
Headless terminal is used by a client or its use is unknownRetention leaves it openClient-use check with unknown treated as protected
Extra arguments are invalid or the host lacks supportThe run does not launch with silently changed agent behaviorShared argument parser and capability gate
Run history or usage cannot be readThe UI shows unavailable data instead of zero or false successExplicit failure and usage status in projections
Runtime starts an agent but cannot confirm a journaled, terminal-handled, or bot-handled promptThe run is reported as an unconfirmed launch instead of accepted workPrompt outcome gate and published-target error
Launch operation waits past its expiryThe run fails without treating a late or unknown result as acceptedExplicit operation-expired result
A stopped WSL distribution holds a scheduled launchThe run is skipped as unavailable and can be retried later instead of being treated as a crashWSL hold detection and wslDistroStopped failure mapping
Prompt delivery fails after a terminal or chat surface opensThe run records a dispatch failure while keeping the opened target and launch timeDelivery-stage transition and partial-launch target capture

Key files

FileWhy to read it
src/…/automation-definition.tsDefines automation plans, launch surfaces, workspace modes, targets, event rules, waits, and schedules
src/…/automation-event-triggers.tsDefines event sources, event identity, event folding, and event-only automation rules
src/…/automation-run.tsDefines run triggers, states, target identities, output, precheck, usage, and event history
src/…/automation-service.tsCoordinates schedule evaluation, manual and event runs, target checks, lanes, dispatch, and final results
src/…/automation-trigger-runs.tsShows event admission, deduplication, folding, grace handling, and one-run behavior
src/…/run-target-resolution.tsShows how a saved project, workspace, host, and setup become a runnable target
src/…/bot-run-target.tsShows bot settings, pause, folder, and workspace checks
src/…/automation-dispatch-request.tsShows durable claim, target rechecks, precheck entry, and dispatch routing
src/…/automation-launch-runner.tsShows precheck gating, partial launch state, delivery outcomes, and completion handoff
src/…/automation-wake-settle.tsShows why scheduled work waits for a settled host wake
src/…/dispatch-refusal.tsShows missed-run, unavailable-target, and stopped-WSL refusal rules
src/…/automation-terminal-launch.tsShows terminal-only agent launches, workspace creation, and safe session reuse
src/…/automation-chat-agent-launch.tsShows structured chat launch, prompt acceptance, and launch recovery
src/…/automation-chat-session-reuse.tsShows fenced reuse of an existing structured agent conversation
src/…/bot-automation-launch.tsShows bot conversation selection, event prompt context, and result routing
src/…/bot-automation-service-wiring.tsConnects bot waits, event-related services, and bot launch to the scheduler
src/…/automation-run-receipt.tsShows recovery from accepted launches without prompt resends
src/…/runtime-automation-service.tsConnects the runtime host to scheduling, terminal and chat launch, observation, and retention
src/…/run-completion-watcher.tsShows how retained terminal or chat runs become final results
src/…/run-writer.tsShows durable run writes and change publication after persistence
src/…/AutomationDestinationField.tsxShows that the selected host stores and schedules the automation
src/…/AutomationSurfaceField.tsxShows the saved terminal or chat launch choice
src/…/automation-host-catalog.tsProjects authorities, targets, generations, and unavailable scopes for the automation page
src/…/AutomationRunHistory.tsxShows durable history, folded occurrences, usage state, and unavailable reads