fix: degrade SendMessage shutdown handshake gracefully outside agent teams (#645)

[halindrome]

What

The teammate shutdown_request/shutdown_response handshake requires the SendMessage tool, which only exists inside a live Claude Code agent team (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). This makes that dependency conditional on actually being in a team, delivered through channels that know the runtime mode.

• agents/vbw-{dev,qa,scout,lead,debugger,docs}.md — removed the static "Shutdown Handling" section (the unconditional "you MUST call the SendMessage tool" mandate).
• references/execute-protocol.md — the orchestrator now appends the teammate shutdown-response protocol to each teammate's spawn prompt in the true-team-mode branch only (gated by construction, reliably delivered). Added a hard precondition that team mode is never requested unless CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
• scripts/compaction-instructions.sh — the post-compaction shutdown reminder is now gated on a live team marker (delegated-workflow.sh status-json: live && delegation_mode=team && team_name). Also fixes a latent bug where snapshot-resume.sh's stdout (the snapshot path) corrupted the PreCompact hook JSON whenever .execution-state.json existed.
• references/handoff-schemas.md — repointed the conditional-refusal note to the new protocol location.
• tests/shutdown-protocol.bats — rewritten to assert the new design.

Why

Reported in #645: in subagent mode (e.g. prefer_teams=never) or when agent teams are disabled, SendMessage is not in the toolset, so the agent prompts' mandatory "you MUST call the SendMessage tool" instruction could not be followed. VBW's orchestrator already degrades to subagent mode correctly; the gap was the static agent prompts (and the unconditional compaction reminder) issuing an un-followable directive.

Chosen approach is option (b) from the issue — graceful degradation — implemented so the instruction is only ever issued when a real team exists, rather than adding no-op conditional text to every spawn.

How

• Detection signal is the live VBW delegation marker (status-json: live + delegation_mode=team + team_name), which subsumes the env flag (VBW only writes a team marker after TeamCreate succeeds). The env flag is additionally checked up front as a hard precondition before team mode is even requested.
• The teammate-side handshake is delivered via the orchestrator's team-mode spawn prompt (reliable — SubagentStart is known-unreliable for team-spawned teammates) and re-injected after compaction only when the live team marker is present.

Testing

• bash testing/run-all.sh: lint 1/1, contract 51/51. tests/shutdown-protocol.bats 71/71.
• The 22 failures observed in a parallel run are pre-existing parallel-worker flakiness in files this PR does not touch (agent-shutdown-integration, hooks-bash-classifier, hooks-isolation-lifecycle, role-isolation-runtime) — each passes 0 failures when run serially.
• shellcheck -S warning + bash -n clean on compaction-instructions.sh.

Fixes #645

[halindrome]

QA Round 1

- Model used: Claude Opus 4.8

- What was tested
  - Full diff origin/main...HEAD across all changed files.
  - Repo-wide sweep for lingering "Shutdown Handling" / now-inconsistent SendMessage wording.
  - Architect parity; compaction-instructions.sh set -u / SCRIPT_DIR / gate fail-closed / snapshot redirect.
  - Whether vibe.md/debug.md/map.md still deliver coherent shutdown guidance to spawned teammates.
  - bats meaningfulness + sed-range bounding; ran shutdown-protocol.bats serially (71/71), shellcheck, contract.

- Findings

  1. /vbw:map and /vbw:debug teammates no longer receive the teammate-side shutdown handler — REGRESSION
     Expected: every agent spawned into a real TeamCreate team knows to respond to shutdown_request by calling SendMessage (orchestrator teardown waits for a tool-call response). Previously delivered by the static "## Shutdown Handling" sections.
     Actual: the spawn-time handler was added ONLY to execute-protocol.md's true-team branch. map.md (duo/quad Scout teams) and debug.md (3 debugger investigators) create real teams via TeamCreate but do NOT read execute-protocol.md and do NOT inject the teammate block. Those teammates now have zero instruction to call SendMessage on shutdown_request — the stuck-team/credit-burn scenario the protocol guards against.
     Severity: major. Confirmed.

  2. execute-protocol.md:1025 stale enforcement claim
     Still says enforcement relies on "(1) mechanical SendMessage instructions in all 6 agent prompts" — this PR removed those. Severity: minor. Confirmed.

  3. handoff-schemas.md:330/332 describes the handler as a standing agent obligation
     Reads as if intrinsic to agents; should note it is delivered at spawn in team mode. Severity: minor. Confirmed.

  4. compaction-instructions.sh changes correct — SCRIPT_DIR resolves on hook-wrapper exec path; gate fails CLOSED on error (right direction); snapshot >/dev/null is a genuine root-cause fix, not error-hiding. (no action)
  5. Architect parity intact. (no action)
  6. bats meaningful, not tautological; sed ranges correctly bounded (minor brittleness if "Explicit non-team mode" heading is reworded). 
  7. Env-var precondition is self-contained; no broken cross-reference. (no action)

- Overall verdict
  REQUEST CHANGES. Execute path is correct and tested. Finding 1 is a real behavioral regression for /vbw:map and /vbw:debug. Append the teammate shutdown block to map.md and debug.md team-spawn prompts (gated to real team mode), and reconcile the stale enforcement claims in execute-protocol.md:1025 and handoff-schemas.md:330/332.

[halindrome]

QA Round 2

Model used: Claude Opus 4.8

WHAT WAS TESTED
- Full PR diff vs origin/main (base fix + round-1 fix).
- Round-1 completeness sweep: every TeamCreate/team_name teammate-spawn path across commands/ and references/.
- Scoping of the new map.md/debug.md handler insertions (team-only).
- Escaped-quote/markdown correctness of inserted handler text.
- compaction-instructions.sh gate (set -u, fail-open vs fail-closed, SCRIPT_DIR) + snapshot redirect.
- Stale-reference sweep across docs/, README, CHANGELOG, hooks/.
- Ran serially: shutdown-protocol.bats (71/71), verify-commands-contract, verify-bash-scripts-contract, shellcheck.

FINDINGS
1. Team-spawn coverage complete — only debug.md/map.md/vibe.md use TeamCreate; vibe.md Execute delegates to execute-protocol.md (carries the gated block); research/fix/qa use non-team subagents only (correctly no handler). n/a, confirmed.
2. compaction gate is fail-CLOSED and correct (live && team && team_name; errors → no injection). n/a, confirmed.
3. snapshot-resume stdout redirect is a root-cause fix, not a mask. n/a, confirmed.
4. [minor] map.md handler sits under shared "Scout communication" section rather than inline like debug.md — consistent with map.md's existing deferred-task-body structure; low risk. confirmed (style).
5. [minor/cosmetic] handler JSON used escaped quotes inside an inline code span. confirmed.
6. No stale references remain (only intentional architect exemption section). n/a, confirmed.

OVERALL VERDICT: clean (approve). The two MINOR items are optional polish, not blockers. All affected tests/contracts pass.

Round-2 fixes applied: unescaped the JSON quotes (item #5). Item #4 left as-is per reviewer (consistent with map.md structure).

[halindrome]

QA Round 3 (final)

Model used: Claude Opus 4.8

What was tested
- Full PR diff, all 3 commits (base fix, round 1, round 2).
- Round-2 quote-unescaping: 1-line change per file; unescaped JSON parses via jq; no markdown/contract regression.
- Field-consistency across all three handler copies (execute-protocol.md blockquote, map.md, debug.md): all specify type/approved/request_id/final_status + complete|idle|in_progress + "call SendMessage / plain text not sufficient". No drift.
- Team-spawn coverage: only debug.md/map.md/execute-protocol.md create teams (vibe.md delegates). All carry the handler; architect retains its intentional exemption section; no non-team path received it.
- compaction-instructions.sh: SCRIPT_DIR single-defined at line 15 before use; live-team gate with safe fallbacks under set -u; snapshot stdout leak fixed.
- Ran serially: shutdown-protocol 71/71, verify-commands-contract 521/521, verify-bash-scripts-contract 669/669, verify-lsp-first-policy 49/49, verify-plugin-root-resolution 19/19, verify-claude-bootstrap 58/58, agent-shutdown-integration 26/26, two-phase-completion 20/20, crash-recovery 20/20, event-type-validation 5/5; shellcheck + bash -n clean.
- Vacuous-pass audit of rewritten bats: schema-field test derives fields dynamically; live/non-team form a real positive+negative pair around the gate; recovery-guidance test correctly scoped to debug.md+map.md.

Findings
- None. No critical, major, or minor issues.

Overall verdict: CLEAN (approve). Rounds 1 and 2 fixes complete and correct; no new issues across the three commits.

[dpearson2699]

Verdict: REQUEST_CHANGES

Blocking findings are inline where GitHub could anchor them.

Unanchored blockers:

• None.

Additional non-blocking finding:

• VBW-PR-003: README.md:118 still says all six team-participating agents have explicit shutdown handlers with mechanical SendMessage instructions, but this PR moves those handlers to true-team spawn prompts. Reason not inline: README.md is not in the changed diff.

Evidence:

• Linked issue: #645.
• Tests: bash testing/run-all.sh passed locally: lint 1/1, contract 53/53, BATS 3583 passed / 0 failed.
• Blind baseline: complete; expected /vbw:debug Path A to fall back or gate team mode when SendMessage is unavailable.
• QA: complete; independent QA verdict FAIL for the same /vbw:debug Path A gap.
• QA evidence comments: stale. QA rounds are present and align with earlier QA-round commits, but they predate later ci: and merge commits/current head.

[dpearson2699]

VBW-PR-001 (blocker): Path A still reaches team creation and teardown based only on prefer_teams/effort/ambiguity. The issue explicitly includes /vbw:debug --competing; in an environment without SendMessage, this prompt still appends a SendMessage-only shutdown handler and later waits for SendMessage responses. Gate Path A on real team messaging availability or fall back to Path B/serialized non-team before emitting this task body.

[dpearson2699]

VBW-PR-002 (blocker): The focused shutdown tests now prove the execute-protocol team-mode gate, but they do not cover the /vbw:debug Path A reproduction path. Add a contract test that Path A does not use TeamCreate/SendMessage when Agent Teams/SendMessage are unavailable and falls back to non-team mode.

[halindrome]

Addressed the review feedback in a48c0d8f.

VBW-PR-001 — gate /vbw:debug Path A on team-tooling availability. Path A is a real agent team (TeamCreate, team_name teammates, and a teardown HARD GATE that waits for SendMessage shutdown_response calls). Routing previously selected it purely on prefer_teams/effort/ambiguity, so with agent teams unavailable (the default — CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is 0/unset) it would emit a TeamCreate/SendMessage body and then hang at teardown waiting for responses that can never arrive. Added a hard team-tooling precondition evaluated before the prefer_teams tree: require the Agent Teams flag plus TeamCreate/SendMessage in the live tool set, else force Path B (single debugger) with a ⚠ Agent Teams not enabled notice. Surfaced the flag in the command Context (mirrors map.md) and tightened the Path A header condition.

VBW-PR-002 — contract coverage for the Path A reproduction. Added three tests in tests/shutdown-protocol.bats asserting debug.md surfaces the flag, gates Path A on the precondition (requiring SendMessage/TeamCreate and forcing Path B when unavailable), and that the Path A header carries the precondition.

VBW-PR-003 — stale README. README.md "Shutdown coordination" said all six agents carry explicit SendMessage shutdown handlers; reworded to reflect that handlers are delivered at spawn time (team mode only) and deliberately not baked into the static agent prompts.

bash testing/run-all.sh is green (lint 1/1, contracts 51/51, BATS 3586/0). Rebased onto the latest branch tip before pushing.