@welluable/orch 1.3.0 → 1.4.0

package/README.md

@@ -34,7 +34,7 @@ orch: commit: a1b2c3d on orch/verbose-flag-x7q2
   worktree on an `orch/<slug>` branch, so your working tree stays untouched
   until you decide to merge.
 - **Agent-agnostic backends.** Pick the CLI you already trust with
-  `--agent cursor|claude|agn` — orch owns the pipeline, the agent CLI does
+  `--agent cursor|claude|agn|opencode` — orch owns the pipeline, the agent CLI does
   the reading and writing.
 - **Readable runs.** Every stage prints a one-paragraph natural-language
   summary of what it did; add `-v` if you also want the raw thinking/output
@@ -50,7 +50,7 @@ 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
+(the Cursor Agent CLI, command `agent`); `claude`, `agn`, and `opencode` are also
 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)
@@ -156,7 +156,8 @@ runs, since foreground runs already stream their output to your terminal.
                                ▼
                     ┌──────────────────────┐
                     │ agent backend adapter │
-                    │ (cursor / claude / agn)│
+                    │ (cursor/claude/agn/   │
+                    │  opencode)            │
                     └──────────────────────┘
 ```
 
@@ -174,7 +175,8 @@ agent CLI does all the actual reading and writing of files.
 | `--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).
+`agn` is prompt-only best-effort (it has no dedicated read-only flag), and
+OpenCode uses `--agent plan` with `edit`/`bash` denied via `OPENCODE_PERMISSION`.
 
 `--detach` only controls backgrounding, not whether a job record exists —
 every non-`--dry-run` invocation gets one. Combining `--detach` with
@@ -206,24 +208,36 @@ Usage: orch [options] [command] <task...>
   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`.
+  [Fan-out](#fan-out)); rejects `--ask`/`--quick`/`--dry-run`/`--seq`.
+- `--seq` — decomposes into ordered units, merges each into `orch/<slug>`,
+  then adjusts the near-term backlog (see
+  [Sequential multi-unit (`--seq`)](#sequential-multi-unit---seq)); rejects
+  `--fan-out`/`--ask`/`--quick`/`--dry-run`.
 - `--max-workers <n>` — max number of parallel fan-out workers; defaults to
   `4`; only meaningful with `--fan-out`.
+- `--max-units <n>` — max number of sequential units; defaults to `8`; only
+  meaningful with `--seq`.
 - `--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;
+- `--agent <cursor|claude|agn|opencode>` — selects the backend for the whole pipeline;
   when omitted, uses local `.orch/config`, then global `~/.orch/config`, else
   `cursor`.
+- `--notify` / `--no-notify` — enable or disable a desktop notification when a
+  job reaches a terminal state (`done` / `failed` / `stopped` / `crashed`).
+  Default is on; config key `notify` and these flags share precedence
+  CLI > local > global > on. Dry-run never notifies.
 - `-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
+- `orch config` — prints the effective agent and notify settings and which
+  file(s) contributed (local / global / default). Does not prompt.
+- `orch config --agent <cursor|claude|agn|opencode> [--global|--local]` — writes the
   default agent. Bare `--agent` (and `--global`) write `~/.orch/config`;
   `--local` writes `<cwd>/.orch/config`. There is no `orch init`.
+- `orch config --notify` / `--no-notify` `[--local|--global]` — set desktop
+  notify on or off without wiping `agent` (keys merge on write).
 
 Job-control subcommands (see [Headless runs](#headless-runs)):
 
@@ -232,17 +246,21 @@ Job-control subcommands (see [Headless runs](#headless-runs)):
   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 resume <slug>` — unpauses a paused/pausing run, or recovers a
+  failed/stopped/crashed complex job at its unfinished stage (thin recover +
+  reentry; see failure resume). Not the same as continue.
 - `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`.
+  **done** run's existing worktree/branch (same slug). Carries prior outcome
+  into research/plan. For crash recovery use `orch resume` instead. For fan-out
+  workers that finished, continue the worker slug, then `orch --integrate <parent>`.
 - `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.
+  directory, after a `y/N` confirmation prompt. Refuses (without prompting)
+  if any job is still live (`running`/`pausing`/`paused` with an alive pid);
+  run `orch stop <slug>` first, then clean.
 
 Examples:
 
@@ -250,12 +268,16 @@ Examples:
 orch "fix the typo in the README" --agent claude
 orch "fix the bug described in task.md" --agent cursor -v
 orch "implement the local spec" --agent agn -v
+orch "fix the typo in the README" --agent opencode
 orch --ask "where is the CLI entrypoint?" --agent claude
+orch --ask "where is package.json?" --agent opencode
 orch --quick "fix the typo in the README" --agent claude
 orch "noop" --dry-run --agent cursor
+orch "noop" --dry-run --agent opencode
 orch config
 orch config --agent claude
 orch config --agent agn --local
+orch config --agent opencode
 ```
 
 ## Headless runs
@@ -279,11 +301,11 @@ directory's `.orch/`:
 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 resume swift-lagoon-49ea # unpause, or recover failed/stopped/crashed
+orch continue swift-lagoon-49ea "follow-up polish"  # new work on a done run
 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)
+orch jobs clean                # delete every tracked run under .orch/ (asks to confirm; refuses if live)
 ```
 
 Pausing is cooperative and happens at stage boundaries (before the first
@@ -414,6 +436,58 @@ Depth is capped at 1: every worker and the integration session run with
 variable is already present — a worker or integration session never fans out
 again.
 
+## Sequential multi-unit (`--seq`)
+
+Big features fail in one context window. orch splits them into units agents
+can finish. `--fan-out` runs independent units in parallel; `--seq` runs
+ordered units one-by-one, merging each into `orch/<slug>` before adjusting
+the next.
+
+| | `--fan-out` | `--seq` |
+|---|---|---|
+| Split reason | Parallel independence | Finishable unit size + order |
+| Boundaries | Yes | **No** |
+| Unit shape | Workers + `dependsOn` / `owns` / layers | **Flat ordered list** |
+| Schedule | Parallel (layers / concurrency) | **Strictly one unit at a time** |
+| Base SHA | One shared base for all workers | **Advances after each merge** |
+| Integrate | One session at the end | **Merge + verify after every unit** |
+| Replan | Frozen after decompose | **Hybrid adjust** after each merge |
+
+```bash
+orch "implement the billing module" --seq --agent claude
+orch "implement X" --seq --max-units 6
+```
+
+```text
+triage: complex — seq requested
+decomposer: 5 units
+[01-types …] done — merged into orch/wise-pine-e904
+adjust: rewrote 02-api against tip; dropped 05-legacy-path
+[02-api …] done — merged
+[03-ui …] failed at code-loop / test-runner (round 3)
+stopped: 2/5 merged; next: orch resume <unit-slug>
+```
+
+The flow, in order:
+
+1. **Triage** runs once. If it routes to quick-fix, seq is skipped entirely —
+   triage never opts into `--seq` on its own.
+2. **`seq-decomposer`** (no boundaries agent) emits an ordered `units[]`
+   backlog, or declines → today's single-worktree pipeline with no `seq.json`.
+3. **Schedule** runs concurrency 1: spawn the first pending unit at the current
+   tip → wait → on failure stop the chain → on success merge into
+   `orch/<parent-slug>`, runner-first verify, advance tip, hybrid-adjust the
+   next 1–2 pending units (or drop obsolete ones), continue.
+4. **Continue / resume.** Fix a failed unit with `orch resume <unit-slug>`,
+   then `orch --seq-continue <parent>` (or `orch resume <parent>` when paused).
+   Use `orch continue <unit-slug>` only for new follow-up work on a done unit.
+   Do not `orch continue` the coordinator.
+
+`--max-units` (default `8`) caps both the initial backlog and adjust growth.
+Unit children set `ORCH_SEQ_DEPTH=1` and `ORCH_FANOUT_DEPTH=1` so they cannot
+nest `--seq` or `--fan-out`. Deliverable stays on `orch/<parent-slug>` until
+you merge it yourself.
+
 ## Project structure
 
 Complex runs create a run directory and a sibling worktree, reusing the
@@ -446,6 +520,7 @@ manually if that happens:
 pkill -f 'agent -p'    # --agent cursor
 pkill -f 'claude '     # --agent claude, adjust to local argv
 pkill -f 'agn '        # --agent agn
+pkill -f 'opencode run' # --agent opencode
 ```
 
 ## Agent compatibility
@@ -455,12 +530,13 @@ pkill -f 'agn '        # --agent agn
 | 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`. |
+| OpenCode CLI | `opencode` | Supported | Command `opencode` on `PATH` (`>= 1.17.18`). Install from https://opencode.ai; first-time setup: `opencode auth login`. Read-only/`--ask` uses `--agent plan` with edit/bash denied. |
 
 ## Requirements
 
 - A modern Node.js runtime.
 - One supported agent CLI on your `PATH`: `agent` (Cursor), `claude` (Claude
-  Code), or `agn`.
+  Code), `agn`, or `opencode` (OpenCode `>= 1.17.18`).
 - Git, for any run that isn't `--ask` or `--quick` (worktrees and commits
   need it).
 

package/agents/adjust.js

@@ -0,0 +1,66 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
+function feedbackBlock(feedback) {
+    if (!Array.isArray(feedback) || feedback.length === 0) return '';
+    const violations = feedback.map((violation) => `- ${violation}`).join('\n');
+    return `
+
+                    [Validation Feedback]
+                    Your previous adjust result was rejected for these reasons. Fix them and
+                    try again:
+                    ${violations}
+                    [/Validation Feedback]`;
+}
+
+function formatUnits(units) {
+    if (!Array.isArray(units) || units.length === 0) return '(none)';
+    return units
+        .map((u) => `- ${u.id}: ${u.title} — ${u.subtask}${u.sha ? ` (sha ${u.sha})` : ''}`)
+        .join('\n');
+}
+
+export function adjustAgentArgs({
+    originalTask,
+    doneUnits,
+    pendingUnits,
+    tip,
+    cwd,
+    maxUnits,
+    feedback,
+}) {
+    return {
+        name: 'adjust',
+        instructions: `
+                    You are an Adjust Agent for a sequential orch run.
+
+                    * The original task is the hard fence — do not expand product scope past it:
+                      ${originalTask}
+                    * Current tip SHA of the integration branch: ${tip}
+                    * Done units (do not rewrite or drop these):
+${formatUnits(doneUnits)}
+                    * Pending units in schedule order:
+${formatUnits(pendingUnits)}
+                    * You may rewrite at most the next two pending units' title/subtask texts
+                      so they match the tip. You may drop obsolete pending units. Do not invent
+                      new ids. Do not resurrect done/failed work as new ids. Respect maxUnits
+                      ${maxUnits} (rewrite/drop only — do not grow the backlog).
+                    * Your final message MUST be valid JSON only — no markdown, no prose
+                      outside JSON:
+
+                      {
+                        "rewrites": [
+                          { "id": "02-api", "title": "optional new title", "subtask": "optional new subtask" }
+                        ],
+                        "drops": ["04-obsolete"]
+                      }
+
+                      Use empty arrays when you have no rewrites or drops.
+                    * Before the summary marker below, the JSON itself must stay exactly as
+                      specified above.
+                    ${summaryTrailerInstructions({ before: 'the JSON verdict only' })}
+                    ${feedbackBlock(feedback)}
+                `,
+        prompt: originalTask,
+        options: { cwd },
+    };
+}

package/agents/ask.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function askAgentArgs({ prompt, cwd }) {
     return {
         name: 'ask',
@@ -10,11 +12,7 @@ export function askAgentArgs({ prompt, cwd }) {
                 * Put the full answer in your final message.
                 * Before the summary marker below, your message should only have the
                   answer, no other text.
-                * After the answer above, on a new line write the summary marker (three
-                  '<' characters, then SUMMARY, then three '>' 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.
+                ${summaryTrailerInstructions({ before: 'the answer' })}
             `,
         prompt,
         options: { cwd, readOnly: true },

package/agents/boundaries.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function boundariesAgentArgs({ prompt, cwd, boundariesPath }) {
     return {
         name: 'boundaries',
@@ -15,10 +17,7 @@ export function boundariesAgentArgs({ prompt, cwd, boundariesPath }) {
                       ${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.
+                    ${summaryTrailerInstructions({ before: `the exact path: ${boundariesPath}` })}
                 `,
         prompt,
         options: { cwd },

package/agents/code-writer.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function codeWriterAgentArgs({
     prompt,
     cwd,
@@ -42,11 +44,7 @@ export function codeWriterAgentArgs({
                     * Do not run \`git add\`, \`git commit\`, or any other git branch/commit
                       command. Leave changes unstaged — orch commits after the pipeline finishes.
                     * Once implementation is done, the task is complete.
-                    * After your final message above, on a new line write the summary
-                      marker (three '<' characters, then SUMMARY, then three '>'
-                      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.
+                    ${summaryTrailerInstructions({ before: 'your final message' })}
                     * 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

package/agents/decomposer.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 function feedbackBlock(feedback) {
     if (!Array.isArray(feedback) || feedback.length === 0) return '';
     const violations = feedback.map((violation) => `- ${violation}`).join('\n');
@@ -46,11 +48,9 @@ export function decomposerAgentArgs({ prompt, cwd, boundariesOutput, maxWorkers,
                         "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.
+                    * Before the summary marker below, the JSON itself must stay exactly as
+                      specified above.
+                    ${summaryTrailerInstructions({ before: 'the JSON verdict only' })}
 
                     [Boundaries Agent Output]
                     ${boundariesOutput}

package/agents/index.js

@@ -10,3 +10,5 @@ export { testRunnerAgentArgs } from './test-runner.js';
 export { integratorAgentArgs } from './integrator.js';
 export { boundariesAgentArgs } from './boundaries.js';
 export { decomposerAgentArgs } from './decomposer.js';
+export { seqDecomposerAgentArgs } from './seq-decomposer.js';
+export { adjustAgentArgs } from './adjust.js';

package/agents/integrator.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 /** 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. */
@@ -26,10 +28,7 @@ export function integratorAgentArgs({ prompt, cwd, conflictedFiles, mergeOutput,
                       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.
+                    ${summaryTrailerInstructions({ before: 'your conflict-resolution work' })}
 
                     [Merge Output]
                     ${mergeOutput}

package/agents/planner.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function plannerAgentArgs({ prompt, cwd, researchPath, taskPath, researchOutput }) {
     return {
         name: 'planner',
@@ -10,11 +12,7 @@ export function plannerAgentArgs({ prompt, cwd, researchPath, taskPath, research
                       the exact path: ${taskPath}
                     * Before the summary marker below, your message must contain only the
                       exact path: ${taskPath}
-                    * After the path above, on a new line write the summary marker (three
-                      '<' characters, then SUMMARY, then three '>' 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.
+                    ${summaryTrailerInstructions({ before: `the exact path: ${taskPath}` })}
 
                     [Research Agent Output]
                     ${researchOutput}

package/agents/quick-fix.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function quickFixAgentArgs({ prompt, cwd, fix_plan }) {
     const fixPlan = fix_plan
         ? `
@@ -17,11 +19,7 @@ export function quickFixAgentArgs({ prompt, cwd, fix_plan }) {
                         * Apply changes in the current working tree.
                         * Do not write research.md or task.md.
                         * Do not create a git worktree.
-                        * After your final message above, on a new line write the summary
-                          marker (three '<' characters, then SUMMARY, then three '>'
-                          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.
+                        ${summaryTrailerInstructions({ before: 'your final message' })}
                         * 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

package/agents/research.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function researchAgentArgs({ prompt, cwd, researchPath }) {
     return {
         name: 'research',
@@ -11,11 +13,7 @@ export function researchAgentArgs({ prompt, cwd, researchPath }) {
                       findings only to the exact path: ${researchPath}
                     * Before the summary marker below, your message must contain only the
                       exact path: ${researchPath}
-                    * After the path above, on a new line write the summary marker (three
-                      '<' characters, then SUMMARY, then three '>' 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.
+                    ${summaryTrailerInstructions({ before: `the exact path: ${researchPath}` })}
                 `,
         prompt,
         options: { cwd },

package/agents/seq-decomposer.js

@@ -0,0 +1,58 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
+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 seqDecomposerAgentArgs({ prompt, cwd, maxUnits, feedback }) {
+    return {
+        name: 'seq-decomposer',
+        instructions: `
+                    You are a Seq-Decomposer Agent.
+
+                    * Read the original task and decide whether the work can be split into an
+                      ordered backlog of finishable units. Order is the schedule — a flat
+                      list only, not a parallel dependency graph.
+                    * At most ${maxUnits} units — that is a hard ceiling, not a target.
+                    * Each unit object must contain only id, title, and subtask.
+                    * "decomposable": false (with a "why") is a valid answer when you cannot
+                      find a useful ordered split — do not force a split. That is the
+                      not decomposable / decomposable: false path.
+                    * Your final message MUST be valid JSON only — no markdown, no prose
+                      outside JSON:
+
+                      {
+                        "decomposable": true,
+                        "why": "short reason",
+                        "units": [
+                          {
+                            "id": "01-types",
+                            "title": "short title",
+                            "subtask": "what this unit implements"
+                          }
+                        ]
+                      }
+
+                      or, when declining:
+
+                      {
+                        "decomposable": false,
+                        "why": "short reason"
+                      }
+                    * Before the summary marker below, the JSON itself must stay exactly as
+                      specified above.
+                    ${summaryTrailerInstructions({ before: 'the JSON verdict only' })}
+                    ${feedbackBlock(feedback)}
+                `,
+        prompt,
+        options: { cwd },
+    };
+}

package/agents/summary-footer.js

@@ -0,0 +1,23 @@
+/**
+ * Shared `<<<SUMMARY>>>` trailer instructions for every stage agent.
+ * @param {{ before?: string }} [opts]
+ */
+export function summaryTrailerInstructions({ before = 'required stage output' } = {}) {
+    return `
+* Your final message MUST end with a summary trailer. After ${before}, on its
+  own line write exactly this marker (copy it verbatim — do not put it inside
+  a code fence):
+
+  \`<<<SUMMARY>>>\`
+
+* On the next line, write one paragraph in natural, human-readable language
+  explaining what you did in this step and what happened — no lists, no headers.
+* Shape:
+
+  <${before}>
+  <<<SUMMARY>>>
+  One short paragraph of what you did and what happened.
+
+* Omitting the marker makes the reply invalid for this pipeline.
+`;
+}

package/agents/test-critic.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function testCriticAgentArgs({
     prompt,
     cwd,
@@ -23,12 +25,9 @@ export function testCriticAgentArgs({
                     * Your final message MUST include a JSON verdict:
                       {"passed": true|false, "summary": "short reason", "failures": ["optional"]}
                     * Set passed: true only when verification is adequate to freeze for implementation.
-                    * After the JSON above, on a new line write the summary marker (three
-                      '<' characters, then SUMMARY, then three '>' 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. The JSON itself must stay exactly as specified
-                      above, before the summary marker.
+                    * Before the summary marker below, the JSON itself must stay exactly as
+                      specified above.
+                    ${summaryTrailerInstructions({ before: 'the JSON verdict only' })}
 
                     [Test Writer Output]
                     ${testWriterOutput}

package/agents/test-runner.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function testRunnerAgentArgs({
     prompt,
     cwd,
@@ -22,12 +24,9 @@ export function testRunnerAgentArgs({
                     * Your final message MUST include a JSON verdict:
                       {"passed": true|false, "summary": "short reason", "failures": ["optional"]}
                     * Set passed: true only when the verification gate is green.
-                    * After the JSON above, on a new line write the summary marker (three
-                      '<' characters, then SUMMARY, then three '>' 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. The JSON itself must stay exactly as specified
-                      above, before the summary marker.
+                    * Before the summary marker below, the JSON itself must stay exactly as
+                      specified above.
+                    ${summaryTrailerInstructions({ before: 'the JSON verdict only' })}
 
                     [Code Writer Output]
                     ${codeWriterOutput}

package/agents/test-writer.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function testWriterAgentArgs({
     prompt,
     cwd,
@@ -37,11 +39,7 @@ export function testWriterAgentArgs({
                     * Your final message must include test file paths / run command, if
                       applicable, so it can be handed to the next stage.
                     * Later rounds must address critic feedback; do not write production code.
-                    * After your final message above, on a new line write the summary
-                      marker (three '<' characters, then SUMMARY, then three '>'
-                      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.
+                    ${summaryTrailerInstructions({ before: 'your final message' })}
                     * 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:

package/agents/triage.js

@@ -1,3 +1,5 @@
+import { summaryTrailerInstructions } from './summary-footer.js';
+
 export function triageAgentArgs({ prompt, cwd }) {
     return {
         name: 'triage',
@@ -18,12 +20,9 @@ export function triageAgentArgs({ prompt, cwd }) {
                 Set "simple": true only when a quick fix in the current working tree is enough.
                 Set "simple": false when research, planning, or a worktree is needed.
 
-                After the JSON above, on a new line write the summary marker (three
-                '<' characters, then SUMMARY, then three '>' 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. The JSON itself must stay exactly as specified
-                above, before the summary marker.
+                Before the summary marker below, the JSON itself must stay exactly as
+                specified above.
+                ${summaryTrailerInstructions({ before: 'the JSON verdict only' })}
             `,
         prompt,
         options: { cwd },

package/lib/agent-agn.js

@@ -1,4 +1,4 @@
-import { Agent } from './agent.js';
+import { Agent, appendVerbose } from './agent.js';
 import { normalizeAgnToolEvent } from './tool-status.js';
 
 export class AgentAgn extends Agent {
@@ -24,8 +24,10 @@ export class AgentAgn extends Agent {
             }
             case 'assistant': {
                 if (event.subtype === 'delta') {
+                    const text = event.text ?? '';
+                    appendVerbose(text);
                     if (verbose) {
-                        process.stderr.write(event.text ?? '');
+                        process.stderr.write(text);
                     } else if (this.activeTools.size === 0) {
                         this.setStatus('thinking…');
                     }