trackrun git:20261004.700fa9dA

Immutable. This exact content never changes and is served at /api/v1/blob/3a6b591ff9fb78ee.

---
name: trackrun
description: Execute explicitly selected TODO track IDs with replaceable workers, durable filesystem handoffs and separate worktrees. Prefer visible terminals when available. Use for trackrun id1 id2 requests after dashboard or track-picks selection.
---

# trackrun — run selected tracks

Workers have no default wall-clock limit. Existing explicit `worker_timeout` settings still apply; JSON `null` disables the limit. Cancellation, ownership checks and driver-loss cleanup remain active. The native viewer projects host-observed lifecycle through Orca's managed status hook into the worktree's sidebar. Check `native-sidebar.json` and the launch receipt's `sidebar.status`; only `confirmed` establishes observed sidebar registration. Terminal acceptance alone does not. A sidebar row describes the worker; it never establishes track completion or authorizes effects.

Read installed `project.json` for STATE and primary language, then STATE's `config/1.json`. Use the project language for reports unless the user requests another; default to English. Preserve identifiers and commands.

`trackrun ID1 ID2` is the execution entrypoint. State defaults to `todo/` in the current project; use `--state /absolute/STATE` for a different location. During source development, use `uv run trackrun ...`.

Use `--worker-mode auto|codex-only|claude-only` for the user’s request constraint and `--worker-roles FILE.json` for explicit role selections. See the [selection guide](../todo/worker-routing.md). Omission preserves an existing request; explicit reselection replaces the role override map for future attempts only. A provider-only mode also constrains review, triage, watch and repair/retry workers. Independent review uses a fresh session, which may use the same provider. If no allowed selection exists, resolve the concrete configuration wait; never switch to the prohibited provider. Do not resend an uncertain launch after changing modes. Inspect canonical `execution.routing` and `worker.claimed` events plus `attempts/ATTEMPT/worker-selection.json`; selected values are not provider confirmation.

Read selected tracks' documents and `state.json`, and the project configuration. Respect the user's selected scope, configured verification and previously granted landing authority. Do not ask for the same authorization again. Recommendations alone do not authorize execution.

Keep follow-up work within the selected goal and conditions, interpreted with the user's recorded decisions. New discoveries do not authorize additional features. A required correction must address that outcome or an existing invariant affected by the change; optional improvements remain findings. Reconcile a necessary scope change explicitly instead of expanding the agenda under the same track ID.

Keep verification proportional to the selected change. Resolve cheap lint, formatting and focused failures before requesting expensive final verification. Consume current exact-head verification and independent-review receipts instead of scheduling duplicate checks or reviews without changed inputs, a failure or a concrete evidence gap. Preserve configured gates, explain which are required, and stop after the authorized outcome, required triage, verified cleanup and local synchronization of this run; do not append exploratory audits or cleanup campaigns.

Own the decision to stop. Continue only when the next action resolves a specific unmet user requirement or concrete correctness issue within the authorized scope. Once the requested result and required evidence are sufficient, finish without asking the user to choose whether to pursue optional work. For ordinary ambiguity, choose the narrower scope. Do not add runtime mechanisms, review rounds, or process changes merely to defer this judgment.

Report additional work separately to the user, including its purpose, whether it blocks the original request, and whether it has started. Reporting is not authorization: leave out-of-scope work unstarted until explicitly requested. Disclose any unrequested work already performed rather than hiding it inside the selected track.

The command persists requests, starts a driver and processes currently runnable work. Each assessment, implementation, review and triage uses a fresh worker with a workspace and evidence paths; the worker searches and reads what it needs. Outcomes and follow-up intent live in files. It exits when no work can currently run, including decision waits. The default task concurrency is two; `--jobs N` is optional. There is no separate terminal-count limit or historical-terminal admission audit. Preserve old launch records and ledgers as evidence; do not require migration or cleanup of those records before starting another worker. There is no resident supervisor agent.

For every current and future agent provider, prefer a visible Orca agent session in the task's own managed worktree. Headless is fallback only when the Orca session route is demonstrably unavailable or cannot preserve the required execution contract, unless the user explicitly requests headless. This policy applies equally to Codex, Claude and future providers. A print-mode command such as `claude -p` remains headless even inside an Orca terminal; a visible wrapper or `backend=orca` is not proof of an interactive session. Inspect actual argv, session receipts and the terminal's worktree identity before describing the route. Record and explain the concrete fallback reason; do not silently select headless solely by provider or treat missing provider integration as the intended default. Preserve read-only workers, host-owned writes, complete proposals and ownership checks on every route. Source: the user's 2026-10-04 provider-independent Orca-first instruction, recorded with a counterexample and verification method in `AGENTS.md`.

With an owned Orca worktree and a Claude CLI supporting the isolation flags, `auto` starts Claude interactively in that worktree, without `-p`, output redirection or disabled session persistence. Each role gets a new session ID. `claude-session.json` binds the initial prompt and completed turn to the task, claim and candidate; `claude-transcript.jsonl` retains the bounded proposal evidence. Screen text and an idle prompt do not establish completion. The bridge retains a live process-group owner, stops the interactive process after collection, and uses the existing exit/terminal retirement receipts. Cancellation and driver loss stop that same group. After launch, a missing or unsupported transcript, authentication failure or interrupted turn is a visible failure, never permission to replay through headless. Before launch, missing Orca ownership or unsupported CLI isolation flags retain a compatibility route with a recorded reason. Compatibility terminals show automatic command-worker progress. On the supported native route, a Codex terminal client observes the exact host-owned read-only session in its managed workspace. The host submits the task and collects the complete proposal; do not manually resend a prompt or reuse that client for another task. Use `--launcher headless` only when explicitly requested or when the documented fallback condition above is met; `--launcher orca` requires Orca; inspect the recorded execution mode because a documented compatibility fallback can still use a print-mode worker inside a terminal. Inspect `attempts/ATTEMPT/launch.json` for the actual backend and terminal handle. An accepted terminal launch is not proof of worker execution or completion; compatibility terminal workers record their PID and exit in `terminal-process.json`. Native attempts additionally preserve `native-session.json`, per-request receipts and the supervising process inventory; terminal acceptance alone still does not establish work completion. An uncertain launch must not be retried as a second headless worker. Native reconnect reads the same live owned server/thread/turn history without resubmitting input; unknown server or history identity remains blocked. Native workers reuse the existing Codex login without checking a version allowlist or credential-file shape. Actual startup/authentication/protocol errors remain visible and never trigger a duplicate launch. Explicit headless and legacy candidates retain an explained compatibility route.

If a separate `todo-flow --state STATE run --daemon` driver already runs, `--request-only` can submit without starting another. Reaching `--max-tasks` preserves pending work; continue with `todo-flow --state STATE run`. Its default remains 100 tasks per driver invocation. A task limit is not a completion verdict.

When the user selects a request limit, pass `--worker-attempt-limit N` to `trackrun` or `todo-flow start`, with a positive integer. It applies separately to each selected track's request and persists in `budgets/` across drivers and failures. Omitting it preserves unlimited requests; do not invent a default or interpret `--max-tasks` as this budget. Worker attempts reserve usage atomically at claim time, including failures before launch. Assessment, work, review, triage and watch count; host verification, landing and completion do not. Budget exhaustion preserves candidate HEAD, results and queued obligations and opens one decision; it is not completion.

Only explicit approval of extra attempts permits budget resumption: `todo-flow --state STATE answer DECISION_ID --text TEXT --additional-worker-attempts N`, followed by `todo-flow --state STATE run` if needed. The positive increment extends the total limit and retains cumulative usage. Plain answers, pause/resume and repeated start/trackrun must not reset it. Use the CLI for this approval; existing dashboard answers handle ordinary decisions. Inspect driver output, `status`, the budget decision and `execution.budget-exhausted` / `execution.budget-extended` events for usage, candidate HEAD and remaining obligations.

After completion, the runtime cleans owned, clean and remotely included worktrees plus confirmed exited worker terminals. Documents, branches, results and attempt logs remain. Never set `cleanup_on_complete=false`, pass `--no-auto-cleanup`, or suppress cleanup in a temporary driver unless the user explicitly requests retaining those resources. Debugging convenience or a plan to clean later is not authorization; keep any requested exception scoped and report it. Inspect `cleanup/` and cleanup events for deferred resources; `cleanup TRACK_ID --dry-run` explains the plan, and `cleanup TRACK_ID` retries. Confirm actual removal through receipts and the relevant Git/Orca inventory before reporting cleanup complete. A trackrun is incomplete while any of its owned temporary workspaces or terminals remain pending cleanup, even if track state says `done`. Resolve recoverable deferrals as part of this same run: inspect and close unused creation shells, recover interrupted retirement only from matching original exit/close receipts and fresh complete inventories, and retry cleanup. Do not substitute a deferral report for completion or require another user cleanup request. If actual user changes or reused sessions prevent safe removal, report the run as incomplete with the concrete blocker. Cleanup failure does not mean the delivered track needs to run again. Never force-remove user changes or a reused terminal.

After confirmed landing, synchronize the configured base branch in the primary local checkout with the landing remote using `git pull --ff-only`. This is part of trackrun, not a separate user task, and must finish before reporting the run complete. Verify that local HEAD includes the landed commit (`git merge-base --is-ancestor`) and that the local base branch is not behind the fetched remote base (`git rev-list --left-right --count` and `git status`). Report remote landing, local synchronization and cleanup separately. Preserve user changes and branch choice: never force a checkout, reset, rebase or stash to complete synchronization. If safe fast-forward synchronization is blocked, keep the run incomplete and report the concrete blocker. If the user has already pulled, verify the synchronized state without repeating the pull. Remote landing and removed worktrees are insufficient while the primary local checkout remains behind.

Check `tasks/` and `attempt-records/` for execution, `results/` for outcomes, `decisions/` for questions and `effects/` for external receipts. No SQL query is required. Unknown file state is not success.

Use `todo-flow --state STATE pause|resume|cancel ID` when requested. Record decisions with `answer DECISION_ID --text TEXT` and restart a driver if needed. Preserve requests, handoffs, receipts and failure history; distinguish recovery with intervention from an uninterrupted run.

For authorized landing, [track-triage](../track-triage/SKILL.md) automatically assesses residue, findings and related watches. Original-scope defects return to work, review and landing on a fresh repair branch. Separate follow-ups become HTML TODO documents awaiting selection. A current cleared triage receipt is required before issue closure and completion. Questions resume the same role; independent tracks can continue.