feat(orchestration): phase-aware Baton composition (v1.2.0)

[Nanako0129]

What changed

Prepare pilotfish v1.2.0 as a phase-aware orchestration release instead of a one-size-fits-all dispatch brake.

Area	Change
Discovery	Stabilize question, scope, evidence format, and stop condition; permit only bounded read-only work that reduces Plan uncertainty
Plan and approval	Keep synthesis in the main session; add tool-enforced read-only plan-verifier (READY / REVISE) and require explicit approval before writes
Execution	Preserve the strict stable-scope, exclusive-ownership, done-criteria, integration, and verification brake
Verification	Keep outcome verifier read-and-run after implementation (CONFIRMED / REFUTED); separate it from the pre-approval role
Model routing	Existing named roles continue to omit invocation-level model; frontmatter remains the sole model source
Security	Add tool-enforced read-only security-reviewer before approval; write-capable security-executor accepts only approved implementation contracts
Long processes	Remove detach-and-yield across all four Bash-capable leaf roles; hand back command plus absolute worktree/cwd, environment, and inputs for tracked main-session execution
Runtime safety	Require Claude Code 2.1.207+, the verified baseline that enforces the pre-approval roles' tools allowlists; older or unidentifiable builds stop before writes
Evidence	Publish the complete bilingual Baton Gate, exact prompts, rejected harness run, exact tested policy/agents snapshot, normalized routing evidence, hashes, metrics, and machine-readable results

The release also preserves the original dispatch experiment and re-scopes its early Baton probes as incomplete discovery-only observations rather than a compatibility failure.

Why

The earlier brake conflated two different questions. Discovery needs a stable research contract but may happen before the implementation outcome is known; writing agents need a stable execution contract and required approval. Treating both phases alike either suppresses useful evidence gathering or dispatches executors before the main session can own a coherent Plan.

A dual-mode verifier prompt was insufficient because Plan readiness happens before approval but the outcome verifier needs Bash after implementation. The final design separates capability: plan-verifier has only Read/Glob/Grep, while outcome verifier retains Bash but no write tools. Security analysis and implementation use the same reviewer/executor split.

Separately, four direct harness trials from @dromsak showed that nohup / setsid escape task tracking, while a timeout-promoted command under a foreground-spawned agent is terminated shortly after the agent returns. The minimal prose fix from fix-subagent-detach is included without adopting PR #11's plugin/hook replatform.

This was initially prepared under a v1.1.6 working stamp, then reclassified as v1.2.0 before release because it changes orchestration behavior and adds roles and capability boundaries rather than delivering a patch-only fix.

Live Gate

The corrected fresh-session Gate used native first-party Claude routing with the installed Baton skill and the PR candidate policy.

Turn	Wall time	Client-reported cost	API turns	Result
Discovery + Plan	221.661 s	$1.763515	18	Baton loaded; direct discovery; zero writes; read-only Opus plan-verifier used only Glob/Read and returned READY
Approved execution + verification	226.487 s	$2.025533	4	Sonnet mech-executor wrote only REPORT.md; npm test passed; fresh Opus outcome verifier returned CONFIRMED
Total	448.148 s	$3.789048	22	Full lifecycle passed without resend

All three named-role calls omitted invocation-level model. Baton chose direct main-session Discovery, then delegated the stable approved writing contract to mech-executor; this validates phase-dependent topology rather than mandatory fan-out.

The exact runtime policy and eight-role --agents JSON are committed under benchmarks/baton-compatibility/final-gate-snapshot/. That evidence retains the v1.1.6 candidate stamp used during the run. The v1.2.0 release policy differs only in the inert version comment; results.json records both raw hashes and tests lock the normalized policies together.

The first isolation attempt is disclosed but rejected: excluding the user setting source hid the installed Baton skill, so no approval turn was run. An earlier complete dual-mode-verifier Gate is also preserved but superseded after review found its no-write boundary was prompt-only. Raw transcript hashes, snapshots, and exact prompts remain under benchmarks/baton-compatibility/.

The final fixture did not trigger long work or invoke security-reviewer. Long-process evidence remains the contributor's four dedicated direct trials plus regression coverage across every Bash-capable role; the security reviewer boundary is its positive tool allowlist plus policy tests. No extra edge-case Claude run is claimed as coverage.

Other controls

Control	Observed result
Stable 12-file edit	Opus 4.8 main session → mech-executor; 12/12 pass; in the execution-only segment, reported cost field down 36.01% with wall time up 7.92%; neither comparison included the required outcome verifier, so this proves route reachability rather than full-lifecycle savings
Small task-local audit	Direct pass beat two scouts by 11.71% wall time and 15.61% reported cost in one comparison
Tightly coupled bug	Main session retained diagnosis/fix; fresh verification remained intact

These are single-run observations. Client-reported cost is not a provider invoice and no population-performance claim is made.

Checks

python3 -m unittest discover -s tests -v
13 tests passed

all repository JSON parsed successfully
all changed Markdown relative links resolved
published historical and release-candidate hashes matched
privacy scan passed
research fixture npm test passed
fresh shallow-clone pinned-worktree replay passed
git diff --check passed

This PR is ready for review. It does not create the v1.2.0 tag or release.

[dromsak]

Flagging a separate finding that surfaced while I was working in this area — it's orthogonal to the dispatch brake (this PR answers whether delegation is worth it; the finding below is a bug in how the long-running-process handoff behaves), so it doesn't conflict with the direction here. But it touches the same policy file, and it means the current detach-and-yield rule is actively harmful, so I wanted it in front of you before v1.1.6.

The finding

The rule in executor/mech-executor ("launch it detached with nohup + log, end your turn") and the orchestrator-side rule I added in #7 ("arm a background wait on the yielded PID") are both compensating for a harness behaviour that, tested directly, works differently than either rule assumes.

A foreground Bash command that exceeds its timeout is not killed — it's promoted to a background task ("Command running in background with ID: … You will be notified when it completes"). Whether that promise is kept depends on how the orchestrator spawned the agent:

Subagent spawned with	Promoted command's fate
run_in_background: true	Survives. Runs to completion, stdout captured throughout, completion notification re-invokes the agent. Observed surviving 59s / 69s / 81s past a turn boundary and 141s past the agent returning its final result — zero signals, across 4 trials.
run_in_background: false (foreground)	SIGTERMed ~4s after the agent returns. Work destroyed, captured output truncated mid-stream. Reproduced exactly: heartbeat ends at SIGNAL SIGTERM, task output file truncated at the same tick.

nohup/setsid dodge that SIGTERM by escaping the process group — which is exactly why the pattern looks like it works — but they also escape the harness's task tracking: no task id, no captured output, no completion notification. So detaching doesn't rescue the handoff; it converts a destroyed result into an orphaned one, and #7 exists to hand-roll a recovery for the tracking that nohup threw away.

I chased three wrong mechanisms before this held up (killed-at-turn-boundary, SIGPIPE-on-stdout, stranded-but-uncollected) — each reproduced cleanly and then failed a control. The decisive variable turned out to be foreground-vs-background spawn, nothing in the command itself.

The correction

• No role is told to detach. Subagents run in the foreground with an explicit timeout and hand back anything that can't finish in one.
• Long-running processes belong to the orchestrator — the only context whose background tasks are both tracked and reliably notified.
• This makes run_in_background: true on agent spawns load-bearing for correctness, not just cost — worth stating so it isn't "optimized" back to a foreground spawn to grab a result inline. (That intersects your net-benefit wording here: a foreground spawn to wait idle isn't only wasteful, for a long command it's destructive.)

This supersedes my own #7, which the evidence now shows was patching a self-inflicted wound.

If useful

• Minimal v1.x-shaped fix (no version bump), matching the current architecture: dromsak:fix-subagent-detach — replaces the detach instruction in the two executors and the policy: give the long-running-process handoff an orchestrator side #7 bullet, plus a regression test.
• The same rule enforced by a PreToolUse hook rather than requested in prose (subagents can't run_in_background or nohup at all; the main session keeps both): Repackage pilotfish as a Claude Code plugin #11.

Happy to fold the prose fix into this PR instead if you'd rather keep v1.1.6 as one changeset — your call on sequencing. Raw traces/fixtures available if you want to reproduce the SIGTERM.

[Nanako0129]

Integrated the minimal long-process correction in ff9f118: executor roles no longer detach, the main orchestrator owns tracked background commands, and a regression test locks the boundary. The v1.1.6 changelog credits @dromsak and the commit carries a Co-authored-by trailer. PR #11's plugin/hook replatform remains separate.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ff9f118b71

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16b9650774

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9b7e4d684e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 40b9b7fd4f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 32e89b85ef

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".