trackrun · diff
git:20260928.7b48077 to git:20260930.61c72e9
6 added, 12 removed. Audit A to A.
---
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 ...`.
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 and required triage; 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.
+ 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 concurrency is two; `--jobs N` is optional. There is no resident supervisor agent.
- 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.
+ Default launcher `auto` prefers an available Orca project terminal, then a configured terminal command or an existing tmux session, and falls back to headless when none is available. 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 requested or appropriate for the environment; `--launcher orca` requires Orca. 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. Explicit headless, unsupported Codex versions/auth storage and legacy candidates retain an explained compatibility route.
- 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.
+ 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.
- Default launcher `auto` prefers an available Orca project terminal, then a configured terminal command or an existing tmux session, and falls back to headless when none is available. 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 requested or appropriate for the environment; `--launcher orca` requires Orca. 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.
+ 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.
- 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`. A task limit is not a completion verdict.
+ 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. Cleanup failure does not mean the delivered track needs to run again. Never force-remove user changes or a reused terminal.
+ After completion, the runtime cleans owned, clean and remotely included worktrees plus confirmed exited worker terminals. Documents, branches, results and attempt logs remain. Use `--no-auto-cleanup` only when resources need to remain for inspection. Inspect `cleanup/` and cleanup events for deferred resources; `cleanup TRACK_ID --dry-run` explains the plan, and `cleanup TRACK_ID` retries. Cleanup failure does not mean the delivered track needs to run again. Never force-remove user changes or a reused terminal.
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.