@welluable/orch 1.1.0 → 1.3.0

package/README.md

@@ -51,7 +51,10 @@ npm install -g @welluable/orch
 
 Make sure an agent CLI is on your `PATH` — orch defaults to `--agent cursor`
 (the Cursor Agent CLI, command `agent`); `claude` and `agn` are also
-supported. See [Requirements](#requirements) for details.
+supported. Pin a default with `orch config --agent <name>` so you don't need
+`--agent` on every run (local `.orch/config` overrides global
+`~/.orch/config`; CLI `--agent` still wins). See [Requirements](#requirements)
+for details.
 
 ```bash
 orch "fix the typo in the README"
@@ -123,6 +126,8 @@ you invoked `orch`, plus a persistent sibling git worktree and branch:
   research.md
   task.md
   status.md
+  run.json                            # job state (state, phase, pid, ...); written for every run
+  orch.log                            # full stdout/stderr of the run; --detach only
 
 <parent-of-repo>/<repo-name>-<slug>   # worktree
 orch/<slug>                           # branch
@@ -134,6 +139,11 @@ test-runner) run inside the worktree instead. The worktree is never deleted
 automatically — it's left in place after the run so you can inspect,
 continue, or merge the work whenever you're ready.
 
+`run.json` is written for every invocation — default, `--quick`, `--ask`, and
+`--detach` alike — so `orch list`/`status` always have something to show; see
+[Headless runs](#headless-runs). `orch.log` is only written for `--detach`
+runs, since foreground runs already stream their output to your terminal.
+
 ## Architecture
 
 ```text
@@ -161,14 +171,22 @@ agent CLI does all the actual reading and writing of files.
 | `--quick` | Skips triage, runs `quick-fix` directly in the current tree; no artifacts, worktree, or commits. | You already know it's a small, direct edit. |
 | `--ask` | Skips triage and all write pipelines; one read-only agent answers and orch prints the reply. | You want an answer about the codebase, not a change. |
 | `--dry-run` | Checks the selected agent CLI is on `PATH` and exits without running the pipeline. | You want to sanity-check your setup before a real run. |
+| `--detach` | Runs the pipeline in a background process and returns immediately, printing the run slug. Manage it with `orch list/status/pause/resume/stop/logs`. | You want to kick off a run and keep using your shell, or run several tasks concurrently. |
 
 For `--ask`, Cursor uses `--mode ask`, Claude uses `--permission-mode plan`,
 and `agn` is prompt-only best-effort (it has no dedicated read-only flag).
 
+`--detach` only controls backgrounding, not whether a job record exists —
+every non-`--dry-run` invocation gets one. Combining `--detach` with
+`--ask`, `--quick`, or `--dry-run` is rejected outright (non-zero exit)
+because there's no way to background those modes, not because they'd lack a
+job record. Multiple `--detach` runs can execute concurrently in the same
+directory, each with its own slug.
+
 ## CLI Reference
 
 ```text
-Usage: orch [options] <task...>
+Usage: orch [options] [command] <task...>
 ```
 
 - `<task...>` — task description to use as the prompt (mention a file path
@@ -182,12 +200,50 @@ Usage: orch [options] <task...>
   and exits (skips triage and all write pipelines).
 - `--quick` — skips triage, runs `quick-fix` directly in the current working
   tree; creates no artifacts, worktrees, or commits.
+- `--detach` — runs the pipeline in the background and returns immediately,
+  printing `started <slug> (pid <pid>)`; rejects `--ask`/`--quick`/`--dry-run`.
 - `--max-rounds <n>` — max writer⇄critic and writer⇄runner iterations per
   implementer loop; defaults to `5`, ignored with `--ask` and `--quick`.
+- `--fan-out` — decomposes the task into parallel workers coordinated by this
+  process instead of running the single-worktree pipeline (see
+  [Fan-out](#fan-out)); rejects `--ask`/`--quick`/`--dry-run`.
+- `--max-workers <n>` — max number of parallel fan-out workers; defaults to
+  `4`; only meaningful with `--fan-out`.
+- `--max-concurrency <n>` — optional hard ceiling on in-flight fan-out workers
+  at once; omit to let the coordinator choose (typically the current layer's
+  size); only meaningful with `--fan-out`.
 - `--agent <cursor|claude|agn>` — selects the backend for the whole pipeline;
-  defaults to `cursor`.
+  when omitted, uses local `.orch/config`, then global `~/.orch/config`, else
+  `cursor`.
 - `-h, --help` — displays help for the command.
 
+Config:
+
+- `orch config` — prints the effective agent and which file(s) contributed
+  (local / global / default). Does not prompt.
+- `orch config --agent <cursor|claude|agn> [--global|--local]` — writes the
+  default agent. Bare `--agent` (and `--global`) write `~/.orch/config`;
+  `--local` writes `<cwd>/.orch/config`. There is no `orch init`.
+
+Job-control subcommands (see [Headless runs](#headless-runs)):
+
+- `orch list` — lists all runs tracked under `.orch/` in the current directory.
+- `orch status [slug]` — shows full status for a run; defaults to the most
+  recently started run.
+- `orch pause <slug>` — requests a pause at the run's next stage-boundary
+  checkpoint.
+- `orch resume <slug>` — unpauses a paused (or pausing) run.
+- `orch continue <slug> "new task"` — starts a new complex pipeline on a
+  finished run's existing worktree/branch (same slug). Carries prior
+  stage/failure outcome into research/plan. For fan-out workers, continue the
+  worker slug, then `orch --integrate <parent>`. Not the same as `resume`.
+- `orch stop <slug>` — sends `SIGTERM` to a running job (or reconciles a dead
+  one to `crashed`).
+- `orch logs <slug> [-f]` — prints a run's `orch.log`; `-f` follows it until
+  the job reaches a terminal state.
+- `orch jobs clean` — deletes every run tracked under `.orch/` in the current
+  directory, after a `y/N` confirmation prompt.
+
 Examples:
 
 ```bash
@@ -197,8 +253,167 @@ orch "implement the local spec" --agent agn -v
 orch --ask "where is the CLI entrypoint?" --agent claude
 orch --quick "fix the typo in the README" --agent claude
 orch "noop" --dry-run --agent cursor
+orch config
+orch config --agent claude
+orch config --agent agn --local
+```
+
+## Headless runs
+
+`--detach` starts the full pipeline in a background process and returns your
+shell immediately:
+
+```bash
+orch "implement the local spec" --agent claude --detach
+# started swift-lagoon-49ea (pid 12345)
 ```
 
+The parent process validates the agent binary and flag combination, eagerly
+allocates `.orch/<slug>/`, writes an initial `run.json`, then re-invokes
+itself (without `--detach`) as a detached child with `ORCH_JOB_SLUG` set; the
+child runs the actual pipeline and keeps `run.json` up to date as it
+progresses. Manage it with the subcommands below, all scoped to the current
+directory's `.orch/`:
+
+```bash
+orch list                     # SLUG  ROLE  STATE  PHASE  AGENT  STARTED  DURATION  PID
+orch status swift-lagoon-49ea # full record: state, phase, branch, worktree, exit code, ...
+orch pause swift-lagoon-49ea  # request a pause at the next stage-boundary checkpoint
+orch resume swift-lagoon-49ea # unpause a paused/pausing run
+orch continue swift-lagoon-49ea "follow-up polish"  # new work on the same worktree
+orch logs swift-lagoon-49ea -f # follow orch.log until the run finishes
+orch stop swift-lagoon-49ea   # SIGTERM the run
+orch jobs clean                # delete every tracked run under .orch/ (asks to confirm)
+```
+
+Pausing is cooperative and happens at stage boundaries (before the first
+agent stage, and after each individual agent invocation) — it is not an OS
+suspend, and a pause requested mid-stage takes effect only once that stage's
+agent finishes. This means pause is not atomic across a writer⇄critic or
+writer⇄runner pair: e.g. pausing during `test-writer` still lets
+`test-writer` finish before the run actually pauses, ahead of `test-critic`.
+
+`--detach` is rejected outright when combined with `--ask`, `--quick`, or
+`--dry-run` — those modes have nothing to background — but that's a
+restriction on backgrounding, not on job records: every non-`--dry-run`
+invocation gets a `run.json`, `--detach` or not. Multiple `--detach` runs can
+execute concurrently against the same directory, each tracked under its own
+slug.
+
+## Fan-out
+
+`--fan-out` decomposes a complex task into independent workers that each run
+the full pipeline (minus triage) in their own worktree, then hands the green
+branches to a dedicated integration session:
+
+```bash
+orch "implement the billing module" --fan-out --agent claude
+```
+
+```text
+triage: complex — fan-out requested
+boundaries: partitionable into billing scaffold + 3 endpoint workers
+decomposer: split into 4 workers (1 scaffold, 3 parallel)
+schedule: concurrency 3
+
+[01-scaffold rapid-fox-x7q2] done — commit b2c3d4e
+[02-invoices merry-elk-r4b1] running
+[03-charges  wise-owl-k1a8] running
+[02-invoices merry-elk-r4b1] done — commit c3d4e5f
+[04-webhooks quirky-cedar-p8w3] done — commit d4e5f60
+
+overlaps: none
+[integrate tidy-heron-m2p9] merged 3 branches, full suite passed
+commit: e5f6071 on orch/wise-pine-e904
+merge:  git merge orch/wise-pine-e904
+```
+
+The flow, in order:
+
+1. **Triage** runs once, same as any run. If it routes to quick-fix, fan-out
+   is skipped entirely — triage never opts into fan-out on its own.
+2. **`boundaries`** (new agent) researches only how the work can be split —
+   what can run in parallel, where the coarse boundaries are, whether shared
+   scaffolding (types, registries, barrels) needs to land first — and writes
+   `boundaries.md`. It never plans implementation steps.
+3. **`decomposer`** (new agent) reads `boundaries.md` and the task and emits
+   a worker list (or declines with a reason). orch validates the decomposition
+   itself — worker count, ownership, dependency graph, layer overlap, at most
+   one `scaffold` worker — and feeds validation failures back to the
+   decomposer for up to two repair attempts before giving up.
+4. **Decline path.** If the decomposer declines, or validation still fails
+   after repairs, orch falls through to today's single-worktree pipeline
+   (research → plan → worktree → test loop → code loop → commit) — no
+   `fanout.json`, no workers scheduled.
+5. **Scaffold first.** If one worker is marked `scaffold`, it runs alone to
+   completion before anything else starts; its commit becomes the base SHA
+   every other worker (and the integration session) branches from. A failed
+   scaffold aborts the whole fan-out before any parallel worker spawns.
+6. **Parallel workers.** Each remaining worker is a full, cold orch pipeline
+   (research → plan → worktree → test loop → code loop → commit) running as
+   its own detached process in its own `.orch/<worker-slug>/` directory and
+   worktree — a sibling `orch` invocation, not in-process work. The
+   coordinator chooses how many run at once (capped by `--max-concurrency`
+   when set) based on the dependency layer currently in flight; a worker
+   whose dependency failed is recorded `skipped` and never started.
+7. **Integration.** Once every worker has settled, the coordinator detects
+   file overlaps between the `done` workers and spawns a specialized
+   integration session (`--integrate`, a hidden flag) that merges their
+   branches in order, resolves any conflicts with a dedicated `integrator`
+   agent, then runs a runner-first verify loop (test-runner first,
+   code-writer only on failure) before committing to `orch/<parent-slug>`. If
+   no worker reached `done`, integration is skipped and the run exits
+   non-zero.
+
+Artifacts, in addition to the coordinator's own `run.json`/`orch.log`:
+
+```text
+<invocation-cwd>/.orch/<parent-slug>/
+  boundaries.md    # partitionability research only
+  fanout.json      # decomposition + scheduling state
+
+<invocation-cwd>/.orch/<worker-slug>/
+  research.md, task.md, status.md, run.json, orch.log   # a normal run, per worker
+
+<invocation-cwd>/.orch/<integration-slug>/
+  integration.md   # merge log, overlaps, conflict repairs, final verdict
+```
+
+The coordinator never creates its own worktree and never runs the
+implementer stages itself outside of the decline path — after decomposition
+it is pure orchestration: spawn, poll, report. Exit code is `0` only when
+every worker succeeded and integration committed; any worker failure forces a
+non-zero exit even if integration still commits on the green subset.
+
+`orch list` renders an indented job tree: top-level rows are jobs with no
+`parent` (coordinators and ordinary runs), children indent two spaces under
+their coordinator with a `ROLE` column (`coordinator` / `worker` /
+`integrate` / `-`). `orch status <parent>` expands each child's
+state/phase/branch in the same tree order; `orch status <child>` shows a
+`parent:` line and does not list siblings. Default `orch status` (no slug)
+still picks the most recent job and uses the parent-vs-child view as
+appropriate. `orch logs <parent>` tails the coordinator log only.
+
+Cascade control is parent → children only: `orch pause|resume|stop <parent>`
+applies to the coordinator and every live child (pause reports how many
+children were signaled). `orch pause|resume|stop <child>` is leaf-only — no
+upward cascade. While a parent is paused, the coordinator stops spawning at
+its schedule checkpoints and does not kill live children; on resume it
+re-attaches to still-live workers and spawns only still-pending ones (never
+re-decomposing or duplicating finished/live work). A paused leaf is waited
+on without failing it or starting dependents; a stopped/crashed/failed leaf
+is marked `failed` in `fanout.json`, its dependents are skipped, and the
+schedule continues. `SIGINT`/`SIGHUP`/`SIGTERM` on the coordinator (and
+`orch stop <parent>`) cascade a `SIGTERM` to every live child it recorded —
+the same as [Headless runs](#headless-runs)'s interrupt handling, just
+extended to the whole fan-out tree; worktrees and branches are never
+removed automatically.
+
+Depth is capped at 1: every worker and the integration session run with
+`ORCH_FANOUT_DEPTH=1` set, and `--fan-out` is rejected outright when that
+variable is already present — a worker or integration session never fans out
+again.
+
 ## Project structure
 
 Complex runs create a run directory and a sibling worktree, reusing the
@@ -209,13 +424,16 @@ layout shown in [Artifacts and worktrees](#artifacts-and-worktrees):
   research.md
   task.md
   status.md
+  run.json                            # written for every run
+  orch.log                            # --detach only
 
 <parent-of-repo>/<repo-name>-<slug>   # worktree
 orch/<slug>                           # branch
 ```
 
-Default quick fixes, `--quick`, and `--ask` runs create none of this — no
-`.orch/` directory, no worktree, and no commits.
+Default quick-fixes, `--quick`, and `--ask` runs still get a `.orch/<slug>/`
+directory with a `run.json` job record (so `orch list`/`status` can see them),
+but no `research.md`/`task.md`/`status.md`, no worktree, and no commits.
 
 ## Interrupts
 
@@ -234,7 +452,7 @@ pkill -f 'agn '        # --agent agn
 
 | Backend | `--agent` value | Status | Notes |
 | --- | --- | --- | --- |
-| Cursor Agent CLI | `cursor` | Supported (default) | Command `agent` on `PATH`. |
+| Cursor Agent CLI | `cursor` | Supported (builtin default) | Command `agent` on `PATH`. Override via `orch config` or `--agent`. |
 | Claude Code CLI | `claude` | Supported | Command `claude` on `PATH`. |
 | agn | `agn` | Supported | Requires `npm install -g @welluable/agn-cli` (`>= 0.0.12`) and `agn init`. |
 

package/agents/boundaries.js

@@ -0,0 +1,26 @@
+export function boundariesAgentArgs({ prompt, cwd, boundariesPath }) {
+    return {
+        name: 'boundaries',
+        instructions: `
+                    You are a Boundaries Agent.
+
+                    * Research the codebase rooted at ${cwd} enough to answer: what pieces of
+                      the user's request can be worked on in parallel, where the coarse
+                      boundaries between them are, and whether shared scaffolding (types,
+                      registries, barrels) must land before parallel work can start.
+                    * Do not plan implementation steps and do not write a task checklist —
+                      forbid implementation planning entirely. That is each worker's own job
+                      later in the pipeline.
+                    * Do not write any code. Write your findings only to the exact path:
+                      ${boundariesPath}
+                    * Before the summary marker below, your message must contain only the
+                      exact path: ${boundariesPath}
+                    * After the path above, on a new line write the exact marker
+                      \`<<<SUMMARY>>>\`, followed by one paragraph in natural, human-readable
+                      language explaining what you did in this step and what happened — no
+                      lists, no headers, just prose.
+                `,
+        prompt,
+        options: { cwd },
+    };
+}

package/agents/code-writer.js

@@ -47,6 +47,11 @@ export function codeWriterAgentArgs({
                       characters, with no spaces), followed by one paragraph in natural,
                       human-readable language explaining what you did in this step and
                       what happened — no lists, no headers, just prose.
+                    * If you changed any files, after that paragraph add a line reading
+                      exactly "Files:" followed by one line per changed file formatted
+                      as "<path>: <one-line description>" (e.g. "lib/agent.js: wired the
+                      file tracker into onToolEvent"). Omit this section if you changed
+                      nothing.
                     ${feedbackBlock}
                 `,
         prompt,

package/agents/decomposer.js

@@ -0,0 +1,62 @@
+function feedbackBlock(feedback) {
+    if (!Array.isArray(feedback) || feedback.length === 0) return '';
+    const violations = feedback.map((violation) => `- ${violation}`).join('\n');
+    return `
+
+                    [Validation Feedback]
+                    Your previous decomposition was rejected for these reasons. Fix them and
+                    try again:
+                    ${violations}
+                    [/Validation Feedback]`;
+}
+
+export function decomposerAgentArgs({ prompt, cwd, boundariesOutput, maxWorkers, feedback }) {
+    return {
+        name: 'decomposer',
+        instructions: `
+                    You are a Decomposer Agent.
+
+                    * Read the boundaries research below and the original task, then decide
+                      whether the work can be split into independent workers.
+                    * At most ${maxWorkers} workers — that is a hard ceiling, not a target.
+                    * "decomposable": false (with a "why") is a valid, expected answer when
+                      you cannot find independent seams — do not force a split.
+                    * Your final message MUST be valid JSON only — no markdown, no prose
+                      outside JSON:
+
+                      {
+                        "decomposable": true,
+                        "why": "short reason",
+                        "workers": [
+                          {
+                            "id": "01-scaffold",
+                            "title": "short title",
+                            "subtask": "what this worker implements",
+                            "area": "coarse directory or feature name",
+                            "owns": ["path/prefix/or/file"],
+                            "dependsOn": [],
+                            "scaffold": true
+                          }
+                        ]
+                      }
+
+                      or, when declining:
+
+                      {
+                        "decomposable": false,
+                        "why": "short reason"
+                      }
+                    * After the JSON above, on a new line write the exact marker
+                      \`<<<SUMMARY>>>\`, followed by one paragraph in natural, human-readable
+                      language explaining what you did in this step and what happened — no
+                      lists, no headers, just prose. The JSON itself must stay exactly as
+                      specified above, before the summary marker.
+
+                    [Boundaries Agent Output]
+                    ${boundariesOutput}
+                    [/Boundaries Agent Output]${feedbackBlock(feedback)}
+                `,
+        prompt,
+        options: { cwd },
+    };
+}

package/agents/index.js

@@ -7,3 +7,6 @@ export { testWriterAgentArgs } from './test-writer.js';
 export { testCriticAgentArgs } from './test-critic.js';
 export { codeWriterAgentArgs } from './code-writer.js';
 export { testRunnerAgentArgs } from './test-runner.js';
+export { integratorAgentArgs } from './integrator.js';
+export { boundariesAgentArgs } from './boundaries.js';
+export { decomposerAgentArgs } from './decomposer.js';

package/agents/integrator.js

@@ -0,0 +1,41 @@
+/** Conflict-repair-only agent for the `--integrate` driver: resolves merge conflict
+ * markers in the given files using the merge output and involved workers' subtask/area
+ * as context. Never touches git itself — orch owns the merge commit. */
+export function integratorAgentArgs({ prompt, cwd, conflictedFiles, mergeOutput, involvedWorkers }) {
+    const fileList = (conflictedFiles || []).map((file) => `- ${file}`).join('\n');
+    const workerContext = (involvedWorkers || [])
+        .map((worker) => `- ${worker.title ?? worker.id}: ${worker.subtask} (area: ${worker.area})`)
+        .join('\n');
+
+    return {
+        name: 'integrator',
+        instructions: `
+                    You are an Integrator Agent.
+
+                    * A merge is in progress in this worktree with unresolved conflict
+                      markers in exactly these files — resolve markers only in these
+                      files, and touch no other files:
+                    ${fileList}
+                    * Combine what the involved workers already built; do not redesign or
+                      reimplement anything beyond what is strictly needed to resolve the
+                      conflict.
+                    * Workers involved in this conflict:
+                    ${workerContext}
+                    * Do not run \`git\` yourself — no \`git add\`, \`git commit\`,
+                      \`git merge --continue\`, \`git merge --abort\`, or any other git
+                      command. orch completes the merge commit itself; you only edit files.
+                    * Do not report a pass/fail judgment of any kind; orch checks whether
+                      the conflict markers are gone itself.
+                    * After you finish editing, on a new line write the exact marker
+                      \`<<<SUMMARY>>>\`, followed by one paragraph in natural,
+                      human-readable language explaining what you did in this step and
+                      what happened — no lists, no headers, just prose.
+
+                    [Merge Output]
+                    ${mergeOutput}
+                    [/Merge Output]
+                `,
+        prompt,
+        options: { cwd },
+    };
+}

package/agents/quick-fix.js

@@ -22,6 +22,10 @@ export function quickFixAgentArgs({ prompt, cwd, fix_plan }) {
                           characters, with no spaces), followed by one paragraph in
                           natural, human-readable language explaining what you did in this
                           step and what happened — no lists, no headers, just prose.
+                        * If you changed any files, after that paragraph add a line reading
+                          exactly "Files:" followed by one line per changed file formatted
+                          as "<path>: <one-line description>" (e.g. "README.md: documented
+                          the new --files flag"). Omit this section if you changed nothing.
                         ${fixPlan}
                     `,
         prompt,

package/agents/test-writer.js

@@ -42,6 +42,10 @@ export function testWriterAgentArgs({
                       characters, with no spaces), followed by one paragraph in natural,
                       human-readable language explaining what you did in this step and
                       what happened — no lists, no headers, just prose.
+                    * If you changed any files, after that paragraph add a line reading
+                      exactly "Files:" followed by one line per changed file formatted
+                      as "<path>: <one-line description>" (e.g. "test/agent.test.js:
+                      added the dedupe case"). Omit this section if you changed nothing.
                     ${criticBlock}
                 `,
         prompt,

package/lib/agent.js

@@ -2,6 +2,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import ora from 'ora';
 import { formatActiveTools } from './tool-status.js';
+import { patchJob, buildLastOutcome } from './jobs.js';
 
 /**
  * Every child process spawned by an agent, tracked so we can reap them all
@@ -29,6 +30,19 @@ function killChildGroup(child, signal) {
 
 let shuttingDown = false;
 
+/**
+ * The in-process active job slug for foreground (non-detached) runs, which
+ * never spawn a separate process to carry `ORCH_JOB_SLUG` as an env var. Set
+ * by main.js via `setJobSlug(slug)` once the Commander action allocates a
+ * job for a non-detached invocation.
+ */
+let activeJobSlug = null;
+
+/** Sets the in-process active job slug (see `activeJobSlug`). */
+export function setJobSlug(slug) {
+    activeJobSlug = slug;
+}
+
 /** Conventional shell status: 128 + signal number. */
 export function exitCodeForSignal(signal) {
     if (signal === 'SIGINT') return 130;
@@ -38,12 +52,44 @@ export function exitCodeForSignal(signal) {
 
 /**
  * Reap every tracked child group, then exit. `exit` is injectable so tests can
- * assert without tearing down the runner.
+ * assert without tearing down the runner. Persists terminal job state to
+ * `run.json` for whichever job is active — `process.env.ORCH_JOB_SLUG` (set
+ * on a detached child's own env) or the in-process `activeJobSlug` (set for a
+ * foreground run via `setJobSlug`), env taking precedence when both are set —
+ * before reaping children, so a concurrent `orch pause`/`resume`/`status`
+ * write stays lock-safe. `jobCwd` is a test seam only; real callers never
+ * pass it — it always resolves to the actual `process.cwd()`.
  */
-export function shutdown(signal, { exit = (code) => process.exit(code) } = {}) {
+export function shutdown(signal, { exit = (code) => process.exit(code), jobCwd = process.cwd() } = {}) {
     if (shuttingDown) return;
     shuttingDown = true;
 
+    const jobSlug = process.env.ORCH_JOB_SLUG ?? activeJobSlug;
+    if (jobSlug) {
+        try {
+            const exitCode = exitCodeForSignal(signal);
+            const finishedAt = new Date().toISOString();
+            patchJob(jobCwd, jobSlug, (current) => ({
+                state: 'stopped',
+                exitCode,
+                finishedAt,
+                lastOutcome: buildLastOutcome({
+                    state: 'stopped',
+                    phase: current.phase,
+                    stage: current.stage,
+                    round: current.round,
+                    exitCode,
+                    finishedAt,
+                    task: current.task,
+                    summary: '',
+                    error: null,
+                }),
+            }));
+        } catch {
+            // Best-effort: don't let a job-state write failure block shutdown.
+        }
+    }
+
     for (const child of liveChildren) killChildGroup(child, 'SIGTERM');
 
     const exitCode = exitCodeForSignal(signal);
@@ -74,10 +120,11 @@ export function trackLiveChild(child) {
     child.once('error', () => liveChildren.delete(child));
 }
 
-/** Reset shutdown latch + child set between tests. */
+/** Reset shutdown latch + child set + in-process active job slug between tests. */
 export function resetShutdownState() {
     shuttingDown = false;
     liveChildren.clear();
+    activeJobSlug = null;
 }
 
 /**
@@ -124,21 +171,30 @@ function registerShutdownHandlers() {
     });
 }
 
-/** Format milliseconds as `{s}s` or `{m}m {s}s` (whole seconds, no leading 0m). */
+/** Format milliseconds as `{s}s`, `{m}m {s}s`, or `{h}h {m}m` (whole seconds, no leading 0m/0h). */
 export function formatElapsed(ms) {
     const totalSec = Math.floor(ms / 1000);
-    const m = Math.floor(totalSec / 60);
+    const h = Math.floor(totalSec / 3600);
+    const m = Math.floor((totalSec % 3600) / 60);
     const s = totalSec % 60;
+    if (h > 0) return `${h}h ${m}m`;
     return m > 0 ? `${m}m ${s}s` : `${s}s`;
 }
 
 export class Agent {
-    constructor(name, instructions, prompt, { cwd, readOnly = false } = {}) {
+    constructor(name, instructions, prompt, {
+        cwd,
+        readOnly = false,
+        fileTracker = null,
+        onFileChange = null,
+    } = {}) {
         this.name = name;
         this.instructions = instructions;
         this.prompt = prompt;
         this.cwd = cwd ? path.resolve(cwd) : process.cwd();
         this.readOnly = Boolean(readOnly);
+        this.fileTracker = fileTracker;
+        this.onFileChange = onFileChange;
         this.process = null;
         this.spinner = null;
         this.startedAt = 0;
@@ -157,8 +213,28 @@ export class Agent {
     onToolEvent({ name, args, phase, callId }) {
         if (phase === 'started') {
             this.activeTools.set(callId, { name, args });
+            this.fileTracker?.record({ name, args, phase, callId });
         } else if (phase === 'completed') {
+            // Recall before delete — Claude/agn completions often have empty args.
+            const prior = this.activeTools.get(callId);
             this.activeTools.delete(callId);
+
+            if (this.fileTracker) {
+                const hasPath = Boolean(args?.path || args?.file_path);
+                const entry = this.fileTracker.record({
+                    name: name || prior?.name || '',
+                    args: hasPath ? args : (prior?.args ?? args ?? {}),
+                    phase,
+                    callId,
+                });
+                if (entry?.isNew) {
+                    const wasSpinning = this.spinner?.isSpinning;
+                    if (wasSpinning) this.spinner.stop();
+                    console.log(`  ${entry.marker} ${entry.path}`);
+                    if (wasSpinning) this.spinner.start();
+                    this.onFileChange?.(entry);
+                }
+            }
         }
         this.refreshToolStatus();
     }