feat: parallel delegation — natural-language best-of-N + experimental cooperative waves (+ fixes found by live runs)

[krimvp]

What & why

Three commits of parallel-delegation capability plus three real bugs found (and reproduced) by doing live runs.

1. Natural-language delegation → best-of-N (competing)

A delegation directive in the goal — "fix the flaky test, work with 4 subagents", "… using 3 parallel attempts", "use subagents" (⇒ 3) — maps onto the existing best-of-N tournament (--candidates, issue #85). Mid-run, the same grammar reads a --resume note (--note "try 4 parallel attempts") and lifts the directive into a new candidates field on the RUN_EXTENDED overlay (ADR 0012).

• Deterministic grammar, never an LLM parse (src/cli/delegation.ts); deliberately narrow vocabulary — app-domain goals ("a queue with 4 parallel workers") never match, pinned by tests.
• The directive is stripped from the goal before compile (a leftover "use 4 subagents" would become an unverifiable criterion the approver vetoes on — observed live). Loudly logged; explicit flags always win; above-16 fails closed.

2. EXPERIMENTAL: cooperative parallel waves (--parallel-phases, opt-in)

The cooperating shape best-of-N deliberately isn't: consecutive plan phases sharing a group value (new optional SubGoal field, frozen into planHash; groupless plans keep their legacy hash byte-for-byte) execute as one concurrent wave, then merge — without weakening a single guarantee (ADR 0017):

• Fork — each wave member is a FULL goaly child run (drive() embedded) in an isolated git worktree: its own compiled + frozen contract, iterations, ladder, veto-only Sign-off (both keys per child), its own write-ahead log — all children on the ONE shared --budget-tokens meter and the parent's interrupt probe.
• Merge — DONE children merge in phase order via real 3-way git merge-tree --write-tree plumbing (objects only, no commits/HEAD/index movement); a textual conflict applies nothing of that child. Compiler-authored (git-excluded) verification files are carried over so frozen commands keep their inputs.
• Re-verify — a merge is never trusted: each merged child's frozen DETERMINISTIC rungs re-run on the combined tree (two individually-green changes can still break each other).
• Fail-closed to sequential — a conflict, a red re-verify, a child that never reaches DONE, a thrown wave runner, or a missing wave seam all downgrade that phase to the classic sequential run on the merged tree (fresh frozen contract, same sub-goal — the bar never moves, only the starting tree). The worst case of the feature is byte-for-byte today's --phased. The cumulative ACCEPTANCE contract still gates the whole run.
• Fenced (v1): requires --phased --autonomous (children seal concurrently — still frozen + loudly logged); groups via --plan-file only; grouped plans run strictly sequentially without the flag; crash mid-wave re-runs the whole wave on --resume; wave-child spend bucketed under the parent harness layer (totals + budget cap exact).

3. Fixes from live runs (each reproduced first, each with a regression test)

1. No-diff veto excuse never expired with a real LLM approver (decide.ts) — keyed on veto reason text, which an LLM rewords every round: a no-op worker burned 10 iterations / 340k approver tokens. Now keyed on the feedback's source (verifier vs veto) in LoopCtx; same scenario aborts at iteration 2.
2. Harness seam trusted the ambient CLAUDE_CODE_SESSION_ID (codec.ts) — a nested run recorded the outer Claude Code session as the worker's session (observed live in AGENT_RAN + the resume hint). Guard now lives once in the shared codec core, covering surfacing and resuming.
3. Foreign sentinels threaded into --resume + silent harness switch on resume — observed live as claude --resume noop-session crashing every candidate of a resumed fake-harness run. Resume now adopts the run's recorded harness (explicit --harness overrides, with a printed notice); the sentinel skip-list moved to the id domain (gaining the missing best-of-error); the codec refuses every sentinel.

Type of change

• Bug fix
• Feature (new capability)
• Enhancement (improve existing behavior)
• Harness adapter
• Docs / chore / refactor

Definition of done

• npm run typecheck clean
• npm test green (139 files, 1764 tests)
• New behavior covered by tests — delegation grammar (20 cases incl. false-positive guards) + args wiring; wave reducer table tests (fan-out, opt-in, partial/total downgrade, skip bookkeeping, never-re-fan-out, acceptance advance); wave-runner unit tests (incl. a worktree-leak regression it caught); driver fail-closed missing-seam test; real-git merge-primitive tests (clean disjoint / typed conflict); two end-to-end pipeline tests on real git with a content-routed fake LLM (clean wave → DONE; conflicted wave → sequential downgrade → DONE); regression tests for all three bug fixes
• None of the eight invariants weakened
• Docs synced in this change: README.md (new waves section + best-of-N/NL delegation + operator control), docs/index.html (new wave card + best-of-N and operator-control cards), CLI usage text, ADR 0017

Invariant impact

Touches src/orchestrator/ and the RUN/EVENT vocabulary, so explicitly:

• feat: rename to goaly and add interactive landing page #1 zero-LLM reducer: startPhaseCompile emits ONE RUN_WAVE command (per-phase configs derived by the same pure phaseConfigFor) and folds ONE WAVE_RAN; PhaseCtx gains optional pure skip/waved bookkeeping. Children are separate pure folds over separate logs — they never enter the parent's state machine. The earlier decide.ts change adds a pure feedbackSource field.
• ci: add GitHub Actions pipeline to test and publish to npm #2 freeze: wave grouping is canonicalized into planHash (legacy hashes unchanged); every child contract is frozen at its own Seal; merge/re-verify cannot rewrite anything; RUN_EXTENDED still has no field for goal/verifier/rubric.
• ci: GitHub-driven releases (publish on Release) + MIT license #3 two keys: per child AND at acceptance, unchanged.
• ci: auto-sync package.json after publish (Option B) + bump to 0.1.1 #4 fail-closed: every wave failure shape is a typed unmerged downgrade to sequential — never a crash, never a skipped phase, never an unverified merge; NL directives never guess (no match ⇒ classic run); sentinel/ambient session ids refused at the resume seam.
• feat: structured logging with file output and rotation #6 parse at seams: WAVE_RAN outcomes and RUN_EXTENDED.candidates are Zod schemas; plan group validated.
• feat: UI to operate the workflow (plan, revise, approve) [future idea] #7 write-ahead + resume: WAVE_RAN carries the post-merge checkpoint tree and replay re-points baselines like PHASE_ADVANCED; children keep their own write-ahead logs; the candidates overlay rides the existing extendedRunConfig fold.
• feat: side-LLM observer that explains what's being planned/verified #8 stuck purity: detectStuck unchanged.

Demo

Live run (real claude harness, grouped 2-phase plan, --parallel-phases):

INFO  wave: forking children phases=0,1 base=5b69e3c2…
INFO  wave child starting phase=0 root=/tmp/goaly-wt-L2kJF1
INFO  wave child starting phase=1 root=/tmp/goaly-wt-CsHkRM     ← concurrent, isolated
…child p1: run finished status=DONE iterations=1                ← both keys, in its worktree
…child p0: ABORTED (approver veto → excused turn → no-diff)     ← the earlier fix, working live
INFO  wave: merged + re-verified merged=1 total=2 tree=cb3a4637…
# WAVE_RAN outcomes: [{unmerged, index 0, reason "child run ABORTED…"}, {merged, index 1}]
→ phase 0 downgraded to the classic sequential run on the merged tree; zero stray worktrees after.

Nothing crashed, nothing was greened unverified, and the deterministic e2e tests cover the all-merged → acceptance → DONE path.

Notes for reviewers

• The biggest design question was conflict resolution: there is deliberately no merge agent. A conflicted/red phase becomes ordinary verified work (sequential re-run under a frozen contract) — LLM-free recombination keeps unverified writes off the DONE path.
• Judge rungs are not re-run post-merge (each child already turned both keys in isolation; acceptance still gates with LLM keys) — the merged-tree guard is the ungameable deterministic bar in between. Trade-off documented in ADR 0017.
• Commit order tells the story: harness/session fixes → NL delegation → waves.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GQyZKAfKCeAkQZHvKv8EEa