Have orchestrated-coder write change-summary incrementally for interruption resilience

[williamthorsen]

Problem

When orchestrated-coder is interrupted mid-dispatch — most commonly on max_turns exhaustion for a multi-task plan — no change-summary artifact is produced. The coder writes its single summary file only at the end of the invocation, so a cutoff response leaves the orchestrator with:

• a partially-modified working tree,
• no durable record of which plan tasks the coder had completed vs. abandoned,
• no structured handoff to a continuation coder or a recovering orchestrator.

Observed during orchestrated run 20260420-044834Z (ticket williamthorsen/node-monorepo-tools#245): two orchestrated-coder dispatches each hit ~114–124 tool_uses against max_turns: 80, returned an agentId: marker rather than a structured return block, and burned ~229K tokens of work that produced no artifact. The orchestrator recovered by direct tree inspection — reliable here because the run happened to complete the code changes before the cutoff, but in general the recovery path is fragile and expensive.

The same interruption pattern applies to the coder's review-response mode, where a cutoff leaves reviewers and the orchestrator with no record of which findings were addressed.

Context

• The summary is the orchestrator's primary state-transfer channel. Review cycles, holistic review, and re-dispatched coders all read the change-summary. Losing it forces the orchestrator into ad-hoc recovery.
• max_turns can legitimately be hit. Raising the ceiling helps at the margin, but it does not eliminate the failure mode — plans can always grow. The artifact-write policy must be robust to it.
• Partial summaries are strictly more useful than no summaries — even a summary listing tasks 0–4 complete, task 5 in-progress, tasks 6–7 unstarted gives a human reviewer or a continuation coder enough to act on.
• The coder's Write/Edit tools can overwrite or patch the summary file at any time. There is no technical constraint against flushing incrementally.
• Per-task boundaries are already named in plans (Task 0, Task 1, …) and per-finding IDs are already used in review response (F1, F2, W1, …). Both modes have natural scaffold boundaries.
• Both modes write to the same {NN}_coder_change-summary.md path. Implementation and review-response share the artifact slot; only the content shape differs.
• Churn is acceptable. Writing the summary file N times during a dispatch is cheap; the artifact store is not performance-sensitive.

Approaches considered

A. Status quo — coder writes full summary at end

Pros: simple. Cons: all-or-nothing against interruption.

B. Scratch progress log, synthesize summary at end

Pros: append-only progress log is interruption-safe. Cons: two artifacts; consumers of the change-summary still see nothing on interruption.

C. Write summary after each task, overwriting in place (chosen)

Coder writes the change-summary file immediately with a scaffold (one section per plan task or per finding, all marked "pending"). After each unit, it overwrites with updated sections. At the end, it fleshes out aggregate sections.

Pros: a valid, useful change-summary exists after every transition. Interruption at any point leaves a partial but structurally-complete artifact. No new artifact types. Cons: coder prompt needs restructuring.

D. Emit explicit task_progress MCP events

Pros: machine-readable progress stream. Cons: doesn't solve the summary-file interruption problem; adds a new event type.

Solution

Adopt approach C — incremental in-place writes of the change-summary by the coder — and apply it to both operating modes (implementation and review response). Bundled with this change, raise orchestrated-coder's turn budget from 80 to 150 to reduce the frequency of hitting the ceiling.

Coder agent changes — packages/agents/content/subagents/orchestrated-coder.md

Turn budget

• Frontmatter: maxTurns: 80 → maxTurns: 150
• Body prose "You have 80 turns" → "You have 150 turns"
• Keep the "Reserve your last 3 turns" gate, but reframe: the reserved turns finalize Quality gates, Deferred items, and the aggregate status line in the already-written scaffold — not a full artifact from scratch.

Implementation mode (multi-task plans only)

1. First tool use after reading the plan is a Write of the change-summary scaffold:

   # Change summary — ticket #{N}
   
   ## Status
   
   In progress — task 0 of {K}
   
   ## Per-task summary
   
   ### Task 0: {title} — pending
   ### Task 1: {title} — pending
   ...
   
   ## Files changed
   
   (pending)
   
   ## Quality gates
   
   (pending)
   
   ## Deferred items
   
   (pending)
   

2. After each plan task completes, overwrite the file: update that task's section (files changed, outcome, notes) and bump ## Status.

3. Before the final return block, flesh out Quality gates, Deferred items, and set the final aggregate status.

Single-task plans keep the existing "write once at the end" behavior.

Review-response mode

Same pattern, scaffolded by finding IDs:

1. First tool use is a Write of a scaffold listing all findings (F1, F2, W1, …), each marked — pending.
2. After each finding is addressed, overwrite the file with that finding's Status (FIXED | NOT_FIXED | ALREADY_RESOLVED) and Action.
3. Before the final return block, finalize Quality gates.

Orchestrator changes — packages/agents/content/skills/orchestrate/SKILL.md

• Turn budgets table: orchestrated-coder row 80 → 150.
• Phase 3 (Implementation) dispatch: max_turns: 80 → max_turns: 150.
• Add a Recovery from coder interruption subsection: when a coder Task returns without a structured return block, the orchestrator reads the partial change-summary at the canonical path and uses it to seed continuation or populate the run summary — no working-tree inspection fallback.

Review-cycle module changes — packages/agents/content/skills/orchestrate/modules/review-cycle.md

• Both coder dispatches (initial fix round and simplifier fix cycle): max_turns: 80 → max_turns: 150.

Out of scope

• Changes to the {NN}_coder_change-summary.md naming pattern.
• New event types or MCP artifacts.
• Orchestrator-side assertion that the scaffold file exists before Phase 4 (redundant once the scaffold write is the first tool use).
• SendMessage-based resumption of interrupted coder dispatches — tracked in Enable SendMessage-based resumption for interrupted orchestrated-coder dispatches #450. Incremental writes (this ticket) provide durable state recovery for all failure modes; SendMessage is a cheaper recovery path when the agent is still resumable.
• Incremental-write discipline for reviewer artifacts — tracked in Have reviewers write findings incrementally for interruption resilience #452. Reviewers have the same interruption problem but a structurally different scaffold (findings are discovered, not enumerated upfront), so they warrant their own ticket.

Acceptance criteria

• Implementation-mode incremental write is specified in orchestrated-coder.md: scaffold as first tool use (multi-task plans), overwrite per plan task, finalize aggregate sections at end.
• Review-response-mode incremental write is specified in orchestrated-coder.md: scaffold listing all finding IDs as first tool use, overwrite per finding.
• Example scaffolds for both modes are present in the agent definition.
• orchestrated-coder turn budget is 150 in all six locations: agent frontmatter, agent body prose, SKILL.md Turn budgets table, SKILL.md Phase 3 dispatch, review-cycle.md initial fix round, review-cycle.md simplifier fix cycle.
• SKILL.md documents the recovery path for missing structured return blocks: read the partial summary rather than inspect the working tree.
• Test criterion: N/A — all changes are to agent instruction content (prose consumed by Claude at runtime); no code paths with existing test coverage are modified. Falls under the testing-conventions carve-out for content/prose updates.

References

• Run that surfaced the issue: ~/ai-artifacts/projects/node-monorepo-tools/tickets/245/20260420-044834Z/ (see 17_orchestrator_run-summary.md Insights and 18_analyst_savings-analysis.md for quantified impact).
• Affected files: packages/agents/content/subagents/orchestrated-coder.md, packages/agents/content/skills/orchestrate/SKILL.md, packages/agents/content/skills/orchestrate/modules/review-cycle.md.