orchestrate: continuous out-of-band progress reporting for multi-hour runs (status command + durable milestone markers)

[TBarregren]

Context — field experience (kntnt-extractor, 2026-07-22, orchestrate 0.16.1)

An orchestrate run is a 6–12 hour unattended process, but the only live views of its progress are inside the Claude Code TUI: the /workflows progress tree and the agent view (arrow-left). In the field this is worse than inconvenient — entering the agent view to check on progress and leaving it again is precisely the interaction that has repeatedly killed the background workflow mid-run (a compaction prompt appears on exit; by then the run is already dead — see the companion resume ticket). So today the maintainer must choose between flying blind for hours and risking the run by peeking.

What the maintainer actually needs, continuously and out of band (no TUI interaction): which issues are done, which issue is in flight, and where in its lifecycle it stands (implement / verify / fix round k of N / reconcile / integrate / parked), plus coarse run-level facts (agents spent, waves remaining).

What exists today

• The engine log()s wave/fix-round events — but those render only in the in-session progress tree, the exact place peeking is dangerous.
• The Workflow harness already persists journal.jsonl in the run's transcript dir, with one started/result line per agent — durable, on disk, updated live. In the 2026-07-22 recovery this journal was sufficient to reconstruct the full run state by hand (which issue landed at which SHA, which lens was outstanding).
• Workflow scripts have no filesystem access, so the engine cannot write a progress file itself; sub-agents, however, run with full tools.

Decision R1 — reporting channel(s)

(a) Deterministic status command (recommended core). A new orchestrate.py status mode that reads the run's journal.jsonl (plus the plan) and renders the current per-issue lifecycle position, timestamps, and agent counts. Zero tokens, pure code, watchable from any plain terminal (watch -n 60 …) with no TUI interaction. Requires the engine's journal entries to be self-describing — today the journal records agentId + result but the human-readable label/phase lives only in the per-agent meta.json; either the harness journals labels or status joins against the meta files.

(b) Durable GitHub milestone comments (recommended complement). Post one comment per lifecycle milestone on the issue itself — "implementation green on branch X", "verification cleared", "integrated at SHA". Visible from a phone, survives any crash, and doubles as the machine-readable landed-marker the companion resume ticket needs (shared mechanism — coordinate the format there). Sub-agents are forbidden outward writes by the operating contract, so these would be posted by the integrate step (already the authorized mutator) and/or a dedicated mechanical-tier reporter dispatch.

(c) Push notification at coarse milestones (optional). One notification per landed/parked issue and at run end.

Acceptance criteria

• During a run, the maintainer can see, from a plain terminal with zero Claude Code TUI interaction, each issue's lifecycle position (implement / verify / fix round k / reconcile / integrate / done / parked) and which issues have landed at which SHA.
• Each landed issue leaves a durable, machine-readable marker (format shared with the companion resume ticket).
• No documented progress-checking path requires opening the agent view or /workflows.
• The status rendering is deterministic (code, not an LLM) and covered by tests/test_orchestrate.py.

---

🤖 Generated with Claude Code

[TBarregren]

Companion ticket: #49 (interrupt-safe restart). The durable landed-marker/milestone-comment mechanism in Decision R1(b) is shared with #49's preflight guard — whichever lands first defines the marker format.

[TBarregren]

This was generated by AI during triage.

Triage Notes

Category/state: enhancement (confirmed) · staying in needs-triage, parked behind #49.

What we've established so far:

• Not redundant. scripts/orchestrate.py today exposes only plan / redgreen / report; report renders the final verdict set, and nothing reads journal.jsonl. The proposed status mode (R1a) is genuinely new and slots beside the existing subcommands.
• R1a is feasible in the right place. The Workflow engine (orchestrate.workflow.js) has no filesystem access, but the deterministic, Python-tested CLI (scripts/orchestrate.py + tests/test_orchestrate.py) is exactly where a code-not-LLM status command belongs — matching the acceptance criteria.
• One genuine unknown (to settle in grilling): status needs self-describing journal entries, but the human-readable label/phase lives in per-agent meta.json, not journal.jsonl — and the journal is a Workflow-harness artifact this repo doesn't control. The design must commit to either joining journal.jsonl against the meta.json files, or depending on the harness journaling labels (fragile). This should be pinned before dispatch.

Sequencing decision: the durable landed-marker format (R1b) is shared with #49, whose preflight guard is the marker's consumer and therefore the tighter constraint. Per the maintainer, #49 is being grilled first to define the marker format; #48's R1b will then emit that agreed format. #48 returns to triage once #49 fixes the format.

[TBarregren]

This was generated by AI during triage.

Marker format resolved by #49 (now ready-for-agent)

#49 was grilled first and now owns the shared substrate. The landed-marker format #48's R1b and status depend on is settled — build on it, don't redefine it:

• Canonical marker grammar (single-line, fixed-prefix, positional):
  • merge mode: orchestrate: landed <sha> on <branch>, run <runId>
  • PR mode: orchestrate: opened PR #<pr>, run <runId>
• Parser is the source of truth: orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49 adds format_landed_marker / parse_landed_marker to orchestrate.py, designed to be extensible — orchestrate: continuous out-of-band progress reporting for multi-hour runs (status command + durable milestone markers) #48's status command and richer milestone vocabulary reuse parse_landed_marker rather than parsing ad hoc.
• Writer: the integrate step posts the marker and (merge mode) closes the issue at integrate time (Decision D1, ADR-0005). orchestrate: continuous out-of-band progress reporting for multi-hour runs (status command + durable milestone markers) #48's additional milestone comments (implementation-green, verification-cleared, integrated) extend the same helper/grammar.

What #48 still owns (its grilling targets when it returns to triage):

• The orchestrate.py status subcommand and the journal.jsonl ↔ meta.json join — the one genuine feasibility unknown (the human-readable label/phase lives in per-agent meta.json, not the journal). This must be pinned before orchestrate: continuous out-of-band progress reporting for multi-hour runs (status command + durable milestone markers) #48 is ready-for-agent.
• Which reporting channels are in scope: R1a status + R1b milestone comments (recommended core), R1c push notifications (optional).

State: staying in needs-triage until #49 lands the marker helper (so #48's brief can reference the real parse_landed_marker signature), then grill R1 + the journal/meta join and promote.

[TBarregren]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Give a multi-hour orchestrate run a continuous, out-of-band, per-issue lifecycle heartbeat — durable GitHub milestone comments posted by a new mechanical-tier reporter writer at each phase boundary — so the maintainer can see which issue is in flight and where it stands without ever touching the Claude Code TUI.

Scope note — what #49 already ships, and what this issue adds

#49 (ADR-0005, merged) already makes the terminal landing durable: the integrate step posts orchestrate: landed <sha> on <branch>, run <runId> and closes the issue (merge mode), or posts orchestrate: opened PR #<pr>, run <runId> (PR mode). So which issues finished is already visible out of band. This issue adds the within-ticket heartbeat #49 does not provide: which issue is in flight right now and where inside its lifecycle it stands, plus a durable marker when an issue parks (dies) rather than lands. Build on #49's grammar and helpers — do not redefine them.

Current behavior:
During a 6–12 hour run the only per-issue signal that reaches the maintainer out of band is #49's terminal landed/opened-PR marker + close. Between landings there is nothing: an issue churning in fix-round 3 for two hours is indistinguishable from steady progress until it finally lands or parks, and a parked/failed issue leaves no durable marker at all. The engine log()s wave/fix-round events, but those render only in the in-session progress tree — the exact place peeking has repeatedly killed the background run. Per ADR-0005 §3 / ADR-0001 §7, the integrate step is the sole sub-agent authorized to write outward, and it runs only once, at the end of each issue.

Desired behavior:
At each lifecycle boundary of an issue the engine actually reaches, a durable, machine-readable comment is posted on that issue, giving a phone-visible narrative:

orchestrate: started #47, run <runId>
orchestrate: implementation green #47, run <runId>
orchestrate: verification cleared #47, run <runId>
orchestrate: fix round 2 #47, run <runId>          (only when a fix round runs)
orchestrate: landed <sha> on main, run <runId>     (#49, unchanged)
[issue closed]                                       (#49, unchanged)

and, when an issue fails instead of landing:

orchestrate: parked #47 (<short reason>), run <runId>

Rules:

• started is posted only for an issue preflight decided to dispatch — never for one preflight skips as already-landed / already-open, so a resumed/fresh restart does not emit started for work it correctly skips.
• The heartbeat applies in both merge and PR modes (the mid-run boundaries are mode-agnostic; only the terminal marker differs, and that stays orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49's).
• Reporting is auxiliary and best-effort: a failed or absent reporter dispatch must never block, park, or fail an issue's progress. Visibility is never a correctness gate (mirroring ADR-0005's "a dead preflight decodes to dispatch" philosophy).

The architectural decision this issue must record — ADR-0006

This introduces a second authorized outward writer, which amends ADR-0005 §3 / ADR-0001 §7. Author docs/adr/0006-*.md as part of this change (as #49 landed ADR-0005 with its implementation), in the house style of ADR-0005. The decided content:

• Title: mid-run milestone heartbeat and the reporter writer role.
• Amends ADR-0005 §3 and ADR-0001 §7 — widening the single outward-write exception to admit a second, strictly weaker writer. Everything else in ADR-0001/0002/0003/0004/0005 is untouched.
• Decision 1 — milestone vocabulary. Extend orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49's single-source-of-truth grammar with the verbs above, keeping the exact fixed-prefix positional discipline (orchestrate: <verb> …, run <runId>). Same format_*/parse source of truth; extend the Marker dataclass's verb domain. Machine-readable so the deferred status command can read them.
• Decision 2 — the reporter role. A dedicated mechanical-tier sub-agent dispatched at each phase boundary whose sole authorized outward write is to post one milestone comment — never close, push, or merge. It is to milestones what orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49's preflight is to idempotence: a mechanical-tier sub-agent with one narrow job. Forced by the same run-shape constraint as ADR-0005 §3 (the engine has no shell/FS I/O; the orchestrator is blocked on the single Workflow call for the whole run), but its write is strictly weaker than integrate's — a comment mutates no shared state — so the posture widens less than ADR-0005 already did.
• Decision 3 — boundary of the exception. The reporter posts status comments only. Integrate remains the sole mutating writer and still owns the terminal landed/opened-PR marker and the close, at integrate time (ADR-0005 §3 unchanged). The reporter owns started / implementation green / verification cleared / fix round k / parked. No other sub-agent (implement, fix, verify, reconcile, preflight, teardown) gains any write.
• Consequences / accepted costs: ~4–5 extra cheap mechanical reporter dispatches per issue (mechanical tier, folded into overhead, not the judgment cost factor); a chattier issue timeline; the outward-write surface widens from one writer to two — kept as tight as possible (mechanical tier, comment-only, never mutating). Invariants preserved: the §7 floor (close only after independent verification and integration) is untouched — the reporter never closes; integrate stays the sole mutating writer.

Key interfaces

• scripts/orchestrate.py — the milestone grammar. Add format_* helpers for the new milestone verbs, symmetric with the existing format_landed_marker / format_pr_marker, each emitting the canonical orchestrate: <verb> …, run <runId> form. Extend the Marker dataclass's verb to cover the new verbs (carrying number, fix_round where applicable, and a reason for parked; unused fields stay None as the docstring already anticipates). Extend parse_landed_marker (or a shared parser it delegates to) to read the new verbs back.
• Preflight must not regress. orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49's preflight idempotence decision keys specifically on a landed marker whose SHA is an ancestor of the default tip. The new verbs carry no SHA and a different verb, so they must never be mistaken for a landed marker and must never trigger a false already-landed skip. This is a hard correctness constraint on the parser extension.
• skills/orchestrate/orchestrate.workflow.js — the reporter dispatch. Add a reporter agent (mechanical-tier roleTuning, its own minimal schema) dispatched at each wave-loop boundary: after a dispatched preflight → started; after implement goes green → implementation green; after the verifier panel clears → verification cleared; entering each fix round → fix round <k>; when an issue fails to integrate / is blocked / exhausts its fix rounds → parked with a short reason. The reporter's prompt must forbid close/push/merge exactly as the operating-contract bullet forbids the workers, and its failure must be swallowed (best-effort, never gates progress).
• skills/orchestrate/SKILL.md — add the reporter to the lifecycle description, document the milestone vocabulary, add the widened operating-contract bullet (two authorized writers now: integrate — mutating; reporter — comment-only), and add the out-of-band progress watching doc (watch the issue's comments / GitHub notifications; no TUI interaction).

Acceptance criteria

• For an issue the engine dispatches and drives to a landing, its comment timeline carries, in order: started, implementation green, verification cleared, (any fix round k), then orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49's landed + close — each a well-formed orchestrate: <verb> …, run <runId> comment.
• An issue that fails to integrate / is blocked / exhausts its fix rounds gets a durable orchestrate: parked #<n> (<reason>), run <runId> comment.
• started is not posted for an issue preflight skips (already-landed / already-open).
• The heartbeat is emitted in both merge and PR modes.
• A reporter dispatch that errors or is skipped does not block, park, or fail the issue — progress is identical to a run with reporting disabled.
• The milestone grammar round-trips (format → parse) and malformed milestone comments parse to None, covered in tests/test_orchestrate*.py; the SKILL↔parser consistency test is extended to the new verbs.
• orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49's four preflight verdicts are unchanged in the presence of the new milestone comments (no false already-landed skip from a non-landed verb).
• docs/adr/0006-*.md records the decision above and is referenced from the existing ADR index/prose where ADRs are cross-linked.

Out of scope

• The orchestrate.py status terminal renderer (the deterministic journal.jsonl reader / watch-able dashboard, R1a) — deferred to orchestrate: deterministic status command + push notifications (deferred R1a/R1c from #48) #50. Note: the earlier premise that lifecycle labels live in per-agent meta.json was verified false (the sidecars carry only agentType/worktreePath/spawnDepth/model); the follow-up must decide its own attribution source, which is why it is separated out.
• R1c push notifications — deferred to orchestrate: deterministic status command + push notifications (deferred R1a/R1c from #48) #50.
• Any change to orchestrate: interrupt-safe restart — detect a dead cross-session resume, never re-implement landed work #49's landed / opened-PR terminal markers, the close-at-integrate behavior, or the preflight guard beyond the non-regression constraint above.
• Changing integrate's authority: it remains the sole mutating writer and the sole closer.

[TBarregren]

This was generated by AI during triage.

Brief amendment — reporter dispatch ordering (binding)

#50 derives each issue's state from the latest milestone comment within the scoped run. If the engine dispatched reporters fire-and-forget, comments could post out of lifecycle order (e.g. verification cleared landing after fix round 2), and the status board would render the wrong phase.

Requirement: the engine must await each reporter dispatch before proceeding to the next phase boundary of that issue — or, equivalently, guarantee per-issue sequencing of reporter dispatches. Reporters for different issues may still run concurrently; only the per-issue milestone order must match the lifecycle order. This does not weaken the best-effort rule: a reporter that errors is still swallowed and never blocks the issue — awaiting governs ordering, not success.

Additional acceptance criterion:

• For any single issue, its milestone comments are posted in lifecycle order (the engine awaits or sequences reporter dispatches per issue); a reporter failure still never blocks, parks, or fails the issue.