@chllming/wave-orchestration 0.8.5 → 0.8.7

package/docs/plans/end-state-architecture.md

@@ -1,6 +1,6 @@
 # End-State Architecture
 
-This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped `0.8.5` surface now follows.
+This document describes the canonical architecture for the current Wave runtime. It is the authoritative reference for the engine boundaries, canonical authority set, and artifact ownership model that the shipped `0.8.7` surface now follows.
 
 The thesis is unchanged: bounded waves, closure roles, proof artifacts, selective rerun, and delivery discipline. What changes is the internal authority model. The launcher stops being the decision engine and becomes a thin orchestrator that reads decisions from canonical state, sequences the engines, and delegates process work to the session supervisor.
 
@@ -41,10 +41,10 @@ The system uses **Model B: canonical authority set**, not a single event log. Th
 | Source | Kind | Authority Over |
 |--------|------|----------------|
 | Wave definitions (`docs/plans/waves/`) | Parsed declarations, read-only after parse | Goals, agent roles, component promotions, exit contracts, proof artifact requirements, eval targets, skill bindings |
-| Control-plane event log (`.tmp/<lane>-wave-launcher/control-plane/wave-<N>.jsonl`) | Append-only JSONL | Lifecycle state: tasks, attempts, proof bundles, rerun requests, gates, contradictions, facts, human inputs, wave runs, agent runs, artifacts, benchmarks, verifications, reviews |
+| Control-plane event log (`.tmp/<lane>-wave-launcher/control-plane/wave-<N>.jsonl`) | Append-only JSONL | Lifecycle state: tasks, attempts, proof bundles, rerun requests, gates, contradictions, facts, human inputs, wave runs, agent runs, signal updates, artifacts, benchmarks, verifications, reviews |
 | Coordination log (`.tmp/<lane>-wave-launcher/coordination/wave-<N>.jsonl`) | Append-only JSONL | Conversational/workflow state: requests, acks, claims, evidence, decisions, blockers, handoffs, clarifications, human feedback, escalations, orchestrator guidance, integration summaries |
 
-**Everything else is a projection.** Shared summaries, dashboards, inboxes, proof registries, retry overrides, relaunch plans, assignment snapshots, dependency snapshots, ledgers, docs queues, security summaries, integration summaries, markdown boards, and trace bundles are all derived from these three canonical sources plus immutable agent result envelopes.
+**Everything else is a projection.** Shared summaries, dashboards, inboxes, signal snapshots, proof registries, retry overrides, relaunch plans, assignment snapshots, dependency snapshots, ledgers, docs queues, security summaries, integration summaries, markdown boards, and trace bundles are all derived from these three canonical sources plus immutable agent result envelopes.
 
 The reducer consumes all three canonical sources plus result envelopes to rebuild state. No other input is read for decision-making.
 
@@ -153,7 +153,7 @@ wave-state-reducer.mjs     Rebuilds full wave state from canonical authority set
 
 The supervisor is the only module that interacts with the outside world: launching processes, managing terminals, and monitoring sessions. It reads decisions from phase engines and executes them. It is the only module that writes observed lifecycle events.
 
-The projection writer is the single module responsible for projection writes. Workflow-owned compatibility state, clarification triage, and canonical coordination/control-plane mutations stay in their own modules.
+`projection-writer.mjs` owns the operator-facing projection writes family: dashboards, traces, summaries, inboxes, ledgers, docs queues, board projections, and assignment or dependency snapshots. `signals.mjs` owns the separate versioned signal projections used by long-running agents and operator wrappers. Workflow-owned compatibility state, clarification triage, and canonical coordination/control-plane mutations stay in their own modules.
 
 ```
 session-supervisor.mjs     Launches and monitors agent sessions
@@ -188,6 +188,16 @@ projection-writer.mjs      Writes projection outputs
                            Rule:    never reads its own outputs,
                                     always writes atomically,
                                     labels every artifact with its class
+
+signals.mjs                Writes versioned signal projections
+                           Inputs:  materialized control status for a wave,
+                                    logical-agent state, feedback state
+                           Outputs: wave-level signal snapshot,
+                                    per-agent signal snapshots,
+                                    resident-orchestrator signal snapshot
+                           Rule:    versions snapshots only when the normalized
+                                    wake payload changes and tracks ack state
+                                    for long-running watcher loops
 ```
 
 ### Layer 4 — Launcher Orchestrator
@@ -564,6 +574,8 @@ Projections materialized from Class 1 and Class 2 sources. Can be deleted and re
 | Run state | `.tmp/<lane>-wave-launcher/run-state.json` | JSON |
 | Quality metrics | `.tmp/<lane>-wave-launcher/traces/wave-<N>/attempt-<A>/quality.json` | JSON |
 | Reducer snapshot | `.tmp/<lane>-wave-launcher/reducer/wave-<N>.json` | JSON |
+| Wave signal snapshot | `.tmp/<lane>-wave-launcher/signals/wave-<N>.json` | JSON |
+| Agent signal snapshot | `.tmp/<lane>-wave-launcher/signals/wave-<N>/<agentId>.json` | JSON |
 
 ### Class 4 — Human-Facing Projections
 

package/docs/plans/examples/wave-example-design-handoff.md

@@ -1,6 +1,6 @@
 # Wave 12 - Optional Design Steward Handoff
 
-This is a showcase-first sample wave for the shipped `design` worker role in `0.8.5`.
+This is a showcase-first sample wave for the shipped `design` worker role in `0.8.7`.
 
 This example demonstrates the docs-first design-steward path where a design packet is published before code-owning implementation begins.
 

package/docs/plans/examples/wave-example-live-proof.md

@@ -2,7 +2,7 @@
 
 This is a showcase-first sample wave.
 
-Use it as the single reference example for the current `0.8.5` Wave surface.
+Use it as the single reference example for the current `0.8.7` Wave surface.
 
 It intentionally combines more sections than a normal production wave so one file can demonstrate:
 

package/docs/plans/migration.md

@@ -1,6 +1,6 @@
 # Migration
 
-This page is the practical repo-upgrade guide for the current `0.8.5` surface.
+This page is the practical repo-upgrade guide for the current `0.8.7` surface.
 
 Use it when you are:
 
@@ -10,21 +10,33 @@ Use it when you are:
 
 For the completed internal architecture cutover record, see [architecture-hardening-migration.md](./architecture-hardening-migration.md). That document is historical. This one is the operator-facing upgrade checklist.
 
-## What `0.8.5` Changes
+## What `0.8.7` Changes
 
-`0.8.5` ships a new authored and runtime surface, not just a patch-level hardening change.
+The current `0.8.7` surface adds policy consistency and stable per-wave session reuse on top of the `0.8.6` signal-driven operator model.
+
+The practical changes are:
+
+- generic `budget.turns` stays advisory metadata unless the runtime-specific ceiling is set explicitly with `claude.maxTurns` or `opencode.steps`
+- capability-targeted helper routing now treats demonstrated same-wave success as capability-specific evidence; unrelated completed work no longer makes an agent the preferred helper owner
+- advisory or stale clarification and human-input records remain visible in coordination history and reducer blocker views, but they no longer reopen `clarifying` or blocked reducer state by themselves
+- wave-agent and resident-orchestrator tmux sessions now reuse stable per-wave session names, so relaunches and stale launcher exits stop accumulating extra tmux sessions for the same wave
+
+If your repo copied starter docs, shell automation, or operator runbooks, these are the areas most likely to need a sync before the `0.8.7` package cut.
+
+## What `0.8.6` Changes
+
+`0.8.6` keeps the `0.8.5` design-role surface and adds a new signal-driven operator and long-running-agent model.
 
 The biggest additions are:
 
-- the optional `design` worker role is now part of the published package surface
-- starter design bundles now ship in `docs/agents/wave-design-role.md`, `skills/role-design/`, and `skills/tui-design/`
-- design stewards are docs-first by default, but a wave may explicitly give one implementation ownership
-- hybrid design stewards now run in two phases:
-  - design packet first
-  - implementation follow-through second
-- gates, retry or resume planning, reducer state, prompts, local smoke execution, and result envelopes now all agree on that hybrid-design contract
+- the optional `design` worker role remains part of the published package surface
+- starter design bundles still ship in `docs/agents/wave-design-role.md`, `skills/role-design/`, and `skills/tui-design/`
+- starter signal bundles now also ship in `skills/signal-hygiene/`, `scripts/wave-status.sh`, and `scripts/wave-watch.sh`
+- long-running agents and resident orchestrators now receive prompt-visible signal-state and signal-ack paths
+- canonical versioned wave and agent signal snapshots now live under `.tmp/<lane>-wave-launcher/signals/`
+- wrapper and signal semantics now treat `completed` and `failed` as truly terminal, with wrapper exit `40` for failed terminal state
 
-There are no new top-level CLI commands for `0.8.5`.
+There are no new top-level CLI commands for `0.8.6`. The wrapper scripts are starter utilities layered over `wave control status --json`, not a new top-level CLI family.
 
 ## Upgrade Contract
 
@@ -39,6 +51,9 @@ Treat these as package-owned starter surface unless your repo intentionally copi
 
 - `docs/agents/*.md`
 - `skills/*`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/signal-wrappers.md`
 - `docs/plans/current-state.md`
 - `docs/plans/end-state-architecture.md`
 - `docs/plans/wave-orchestrator.md`
@@ -73,7 +88,7 @@ pnpm exec wave upgrade
 
 ### 3. Sync repo-owned starter surface only if you copied it
 
-The most common sync set for `0.8.5` is:
+The most common sync set for `0.8.6` is:
 
 - `docs/agents/wave-launcher-role.md`
 - `docs/agents/wave-orchestrator-role.md`
@@ -82,17 +97,25 @@ The most common sync set for `0.8.5` is:
 - `skills/wave-core/`
 - `skills/role-planner/`
 - `skills/role-design/`
-- `skills/tui-design/` when your repo wants the terminal or operator-surface design reference
+- `skills/tui-design/`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/author-and-run-waves.md`
+- `docs/guides/planner.md`
+- `docs/guides/terminal-surfaces.md`
+- `docs/guides/signal-wrappers.md`
 - `docs/context7/planner-agent/`
 - `docs/reference/wave-planning-lessons.md`
+- `docs/reference/cli-reference.md`
+- `docs/reference/skills.md`
+- `docs/reference/sample-waves.md`
 - `docs/plans/current-state.md`
 - `docs/plans/end-state-architecture.md`
 - `docs/plans/wave-orchestrator.md`
 - `docs/plans/migration.md`
-- `docs/reference/skills.md`
-- `docs/reference/sample-waves.md`
 
-If your repo copied starter `wave.config.json` defaults, also sync the design-role entries:
+If your repo copied starter `wave.config.json` defaults, also sync:
 
 - `roles.designRolePromptPath`
 - `skills.byRole.design`
@@ -106,29 +129,63 @@ Run these from the repo root:
 pnpm exec wave doctor --json
 pnpm exec wave launch --lane main --dry-run --no-dashboard
 pnpm exec wave control status --lane main --wave 0 --json
+scripts/wave-status.sh --lane main --wave 0
+scripts/wave-watch.sh --lane main --wave 0 --until-change --refresh-ms 500
 pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run
 ```
 
 Use `pnpm exec wave dashboard --lane <lane> --attach current` or `--attach global` when you need to reattach to a tmux-backed dashboard after the upgrade.
 
-## `0.8.5` Design-Steward Model
+## `0.8.7` Release Model
+
+The current `0.8.7` surface is three changes together:
+
+- the shipped `design` worker role and hybrid design-steward flow introduced in `0.8.5`
+- the signal-driven long-running-agent and wrapper model introduced in `0.8.6`
+- the policy-consistency, targeted-recovery, capability-specific routing, and stable per-wave session reuse hardening introduced in `0.8.7`
+
+### Signal-driven waiting and wrapper model
+
+This is the main new behavior in `0.8.6`.
+
+Starter repos now include:
 
-This is the main new behavior in the current `0.8.5` surface.
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
 
-### Docs-first design stewards
+Use that model when:
 
-Default design stewards:
+- an external shell loop or CI job should wait for a wave or agent to change state
+- a non-resident agent is intentionally long-running and should wake only on orchestrator-written signal changes
+- a resident orchestrator should explicitly acknowledge that it observed a reroute, answered feedback, or terminal transition
+
+The contract is:
+
+- the runtime publishes versioned signal snapshots under `.tmp/<lane>-wave-launcher/signals/`
+- long-running watchers receive a signal-state path and signal-ack path in the prompt
+- the watcher writes the ack file immediately after it observes a new signal version
+- wrapper exit codes are now:
+  - `0` completed
+  - `10` still active or waiting
+  - `20` input required
+  - `30` signal changed while still active from `wave-watch.sh --until-change`
+  - `40` failed
+
+If your repo copied operator docs, shell automation, or starter scripts, this is the main sync set to apply from `0.8.6`.
+
+### `0.8.5` design-steward model
+
+Docs-first design stewards:
 
 - import `docs/agents/wave-design-role.md`
 - own at least one packet path such as `docs/plans/waves/design/wave-<n>-<agentId>.md`
 - stay docs or spec-first
 - finish with `[wave-design] state=<ready-for-implementation|needs-clarification|blocked> ...`
 
-### Hybrid design stewards
-
 If the wave explicitly assigns non-packet ownership to a design agent, that agent becomes a hybrid design steward.
 
-The runtime now treats that as:
+The runtime treats that as:
 
 1. a design pass first
 2. then the same agent rejoins implementation with normal proof obligations
@@ -143,72 +200,58 @@ For a hybrid design steward, make sure the wave still includes:
 
 The second pass must still re-emit `[wave-design]`, and it must also satisfy the normal implementation proof, doc-delta, and component-marker contract.
 
-### Planner note
-
-The interactive `wave draft` flow now supports `design` as a worker role and scaffolds the docs-first default path.
-
-If you want a hybrid design steward today, the safest authoring paths are:
-
-- edit the drafted wave manually
-- or use an agentic planner payload that already declares the design agent's explicit implementation ownership
+The interactive `wave draft` flow supports `design` as a worker role and scaffolds the docs-first default path. If you want a hybrid design steward today, the safest authoring paths are manual edits or an agentic planner payload that already declares the design agent's explicit implementation ownership.
 
 ## Version-Specific Upgrade Guidance
 
-## Upgrading From `0.8.3` To `0.8.5`
+## Upgrading From `0.8.5` To `0.8.6`
 
-This is the most common one-step package upgrade path.
+This is the smallest upgrade, but it changes the live wait-loop contract for external automation and intentionally long-running agents.
 
-### What changed across that range
+### What changed
 
-- `0.8.4` tightened contradiction replay, component-promotion threshold handling, and projection persistence boundaries
-- `0.8.5` ships the `design` worker role, the `role-design` and `tui-design` starter bundles, and the hybrid design-steward runtime model as part of the published package
-- current operator and planner docs now describe the shipped surface directly instead of splitting behavior between a published package and newer `main`-only additions
+- versioned signal snapshots are now published under `.tmp/<lane>-wave-launcher/signals/`
+- starter repos now include `skills/signal-hygiene/`, `scripts/wave-status.sh`, and `scripts/wave-watch.sh`
+- the runtime injects signal-state plus signal-ack paths into long-running agent and resident-orchestrator prompts
+- `completed` and `failed` now override stale feedback or coordination wakeups in agent signal state
+- wrapper scripts now treat `failed` as terminal with exit `40`
 
 ### Required repo changes
 
-Usually none if the repo does not copy starter prompts, skills, or planning docs.
+Usually none if the repo did not copy starter scripts, operator docs, or skill bundles.
 
 ### Strongly recommended sync
 
 If the repo copied starter surface, sync:
 
-- `docs/agents/wave-design-role.md`
-- `skills/role-design/`
-- `skills/tui-design/`
-- `docs/guides/author-and-run-waves.md`
-- `docs/guides/planner.md`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/signal-wrappers.md`
+- `docs/guides/terminal-surfaces.md`
+- `docs/reference/cli-reference.md`
 - `docs/reference/skills.md`
-- `docs/reference/sample-waves.md`
 - `docs/plans/current-state.md`
-- `docs/plans/wave-orchestrator.md`
 - `docs/plans/end-state-architecture.md`
-
-If the repo copied starter `wave.config.json` defaults, also sync:
-
-- `roles.designRolePromptPath`
-- `skills.byRole.design`
-- `executors.profiles.design-pass`
+- `docs/plans/wave-orchestrator.md`
 
 ### Validation focus
 
-- confirm contradiction-blocked replay cases still compare cleanly if the repo keeps replay fixtures
-- if the repo uses design stewards, confirm packet-only design waves still block implementation until `ready-for-implementation`
-- if the repo uses hybrid design stewards, confirm the same agent rejoins implementation only when the authored wave explicitly gives it code ownership
-
-## Upgrading From `0.8.4` To `0.8.5`
+- confirm any existing shell automation treats wrapper exit `40` as terminal failure
+- if the repo uses long-running watchers, confirm they can write the ack file where the prompt tells them to
+- reroute one targeted feedback or coordination request and confirm the resident signal version changes even when the signal kind stays the same
 
-This is the smallest upgrade that still changes authored behavior.
+## Upgrading From `0.8.4` To `0.8.6`
 
 ### What changed
 
-- the optional `design` worker role is now part of the published package surface
-- `role-design` and `tui-design` starter bundles now ship with the release
+- `0.8.5` added the optional `design` worker role plus the `role-design` and `tui-design` starter bundles
 - design stewards can now be docs-first or explicit hybrid design stewards
-- prompts, gates, retry or resume planning, reducer state, and local smoke execution now honor that hybrid-design contract consistently
+- `0.8.6` adds signal-driven waiting, `signal-hygiene`, and the seeded wrapper scripts
 
 ### Required repo changes
 
-None if your repo does not use design stewards.
+None if your repo does not use design stewards, long-running watcher agents, or copied starter scripts.
 
 ### Strongly recommended sync
 
@@ -217,7 +260,11 @@ If your repo copied starter prompts, skills, or authoring docs, sync:
 - `docs/agents/wave-design-role.md`
 - `skills/role-design/`
 - `skills/tui-design/`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
 - `docs/guides/author-and-run-waves.md`
+- `docs/guides/signal-wrappers.md`
 - `docs/guides/planner.md`
 - `docs/reference/skills.md`
 - `docs/reference/sample-waves.md`
@@ -226,17 +273,62 @@ If your repo copied starter config defaults, also sync the `designRolePromptPath
 
 ### Validation focus
 
-If the repo uses design stewards, dry-run at least one wave that proves:
-
 - the design packet path resolves inside the repo
 - design runs before implementation
 - implementation does not start until every design packet is `ready-for-implementation`
 - hybrid design stewards rejoin implementation when they explicitly own code
-- downstream implementation prompts read the same-wave design packet context
+- long-running prompts receive signal-state and ack paths when the repo uses the new waiting model
 
-## Upgrading From `0.8.0`-`0.8.4` To `0.8.5`
+## Upgrading From `0.8.3` To `0.8.6`
 
-Treat this as one move to the current `0.8.5` surface.
+This is the most common one-step package upgrade path.
+
+### What changed across that range
+
+- `0.8.4` tightened contradiction replay, component-promotion threshold handling, and projection persistence boundaries
+- `0.8.5` ships the `design` worker role, the `role-design` and `tui-design` starter bundles, and the hybrid design-steward runtime model as part of the published package
+- `0.8.6` adds versioned signal snapshots, `signal-hygiene`, prompt-injected signal ack loops, and the seeded operator wrappers
+- current operator and planner docs now describe the shipped surface directly instead of splitting behavior between a published package and newer `main`-only additions
+
+### Required repo changes
+
+Usually none if the repo does not copy starter prompts, skills, planning docs, or wrapper scripts.
+
+### Strongly recommended sync
+
+If the repo copied starter surface, sync:
+
+- `docs/agents/wave-design-role.md`
+- `skills/role-design/`
+- `skills/tui-design/`
+- `skills/signal-hygiene/`
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+- `docs/guides/author-and-run-waves.md`
+- `docs/guides/signal-wrappers.md`
+- `docs/guides/planner.md`
+- `docs/reference/skills.md`
+- `docs/reference/sample-waves.md`
+- `docs/plans/current-state.md`
+- `docs/plans/wave-orchestrator.md`
+- `docs/plans/end-state-architecture.md`
+
+If the repo copied starter `wave.config.json` defaults, also sync:
+
+- `roles.designRolePromptPath`
+- `skills.byRole.design`
+- `executors.profiles.design-pass`
+
+### Validation focus
+
+- confirm contradiction-blocked replay cases still compare cleanly if the repo keeps replay fixtures
+- if the repo uses design stewards, confirm packet-only design waves still block implementation until `ready-for-implementation`
+- if the repo uses hybrid design stewards, confirm the same agent rejoins implementation only when the authored wave explicitly gives it code ownership
+- if the repo uses long-running agents or shell automation, confirm the new wrapper exit contract and ack-loop semantics before relying on an older polling script
+
+## Upgrading From `0.8.3` To `0.8.7`
+
+Treat this as one move to the current `0.8.7` surface.
 
 ### What changed across that range
 
@@ -245,6 +337,7 @@ Treat this as one move to the current `0.8.5` surface.
 - contradiction replay and component-threshold handling were tightened
 - projection persistence centralized under `projection-writer.mjs`
 - the design-role surface is now shipped instead of living only on source `main`
+- versioned signal snapshots, wrapper scripts, and long-running signal ack loops are now part of the shipped operator surface
 
 ### Required repo changes
 
@@ -257,6 +350,7 @@ If your repo copied starter docs or skills, sync:
 - current operator runbook and architecture docs
 - planner starter corpus
 - design-role starter prompt and skill bundles
+- signal-wrapper starter scripts and docs
 - any repo-local docs that still describe design as “main only” or “future”
 
 ### Validation focus
@@ -265,8 +359,9 @@ If your repo copied starter docs or skills, sync:
 - answer at least one human-feedback ticket in a test lane and confirm the linked clarification or escalation chain closes cleanly
 - replay one contradiction-blocked trace if your repo relies on replay regression coverage
 - dry-run one design-steward wave if the repo wants the new authored surface
+- if the repo uses long-running watcher agents or shell automation, validate `scripts/wave-status.sh` and `scripts/wave-watch.sh` against a live or staged lane
 
-## Upgrading From `0.6.x` Or `0.7.x` To `0.8.5`
+## Upgrading From `0.6.x` Or `0.7.x` To `0.8.7`
 
 This is the main migration path for older adopted repos.
 
@@ -278,6 +373,7 @@ This is the main migration path for older adopted repos.
 - live closure depends on validated result envelopes plus canonical state
 - control-plane state, reducer state, and replay are first-class runtime surfaces
 - optional design stewards are now a supported authored shape
+- signal-driven long-running watchers are now a supported operator shape
 
 ### Required repo changes
 
@@ -292,6 +388,7 @@ This is the main migration path for older adopted repos.
    - the `planner-agentic` entry in `docs/context7/bundles.json`
 5. Review any repo-owned docs or runbooks that still describe summary-era closure, pre-control-plane retry or proof behavior, or a single overloaded evaluator role.
 6. If the repo wants design stewards, sync the design starter surface listed above and update local authoring docs accordingly.
+7. If the repo wants signal-driven long-running watchers or shell automation, sync `skills/signal-hygiene/`, `scripts/wave-status.sh`, `scripts/wave-watch.sh`, and the wrapper docs before relying on local polling scripts.
 
 ### Additional validation
 
@@ -305,7 +402,7 @@ pnpm exec wave control proof get --lane main --wave 0 --json
 
 If the repo carries proof-first waves, verify that required proof artifacts still exist locally and not only in historical summaries.
 
-## Upgrading From `0.5.x` Or Earlier To `0.8.5`
+## Upgrading From `0.5.x` Or Earlier To `0.8.7`
 
 Do not treat this as a tiny patch bump.
 
@@ -314,7 +411,7 @@ Do not treat this as a tiny patch bump.
 1. Read [docs/reference/migration-0.2-to-0.5.md](../reference/migration-0.2-to-0.5.md) first if the repo still looks pre-`0.5`.
 2. Run `pnpm exec wave init --adopt-existing` on a branch so the workspace records install state without overwriting repo-owned material.
 3. Move the repo onto the `0.6.x` and later surface using the section above.
-4. Sync the planner corpus and, if needed, the design starter surface.
+4. Sync the planner corpus and, if needed, the design starter surface plus the signal-wrapper starter surface.
 5. Re-run the full validation checklist before any live executor run.
 
 ### Why
@@ -326,6 +423,7 @@ Older repos often differ in:
 - runtime config keys
 - planner starter corpus
 - proof and retry operator surfaces
+- wrapper and signal-monitoring expectations
 - generated state layout under `.tmp/`
 
 Trying to jump directly with ad hoc edits usually leaves hidden drift in prompts, docs, or config.
@@ -345,6 +443,7 @@ Trying to jump directly with ad hoc edits usually leaves hidden drift in prompts
 - `docs/plans/wave-orchestrator.md`
 - `docs/plans/end-state-architecture.md`
 - `docs/plans/migration.md`
+- `docs/guides/signal-wrappers.md`
 - `docs/reference/cli-reference.md`
 - `docs/reference/wave-control.md`
 - `docs/reference/sample-waves.md`
@@ -366,6 +465,8 @@ Use this exact sequence unless your repo has a better repo-specific smoke suite.
 pnpm exec wave doctor --json
 pnpm exec wave launch --lane main --dry-run --no-dashboard
 pnpm exec wave control status --lane main --wave 0 --json
+scripts/wave-status.sh --lane main --wave 0
+scripts/wave-watch.sh --lane main --wave 0 --until-change --refresh-ms 500
 pnpm exec wave coord show --lane main --wave 0 --dry-run --json
 pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run
 ```
@@ -394,15 +495,21 @@ For repos that depend on replay parity, replay at least:
 ### A live lane looks blocked after the bump
 
 - use `wave control status --lane <lane> --wave <n> --json`
-- confirm whether the blocker is canonical coordination, dependency, proof, human-input, or design-gate state
+- confirm whether the blocker is canonical coordination, dependency, proof, human-input, design-gate, or signal-ready state
 - do not trust generated markdown alone
 
+### External automation hangs after the upgrade
+
+- confirm your wrapper loop treats exit `40` as terminal failure
+- confirm `wave-watch.sh --until-change` expects exit `30` only for non-terminal signal changes
+- if a long-running agent never wakes, inspect its ack file under `.tmp/<lane>-wave-launcher/signals/wave-<n>/acks/`
+
 ### Replay differs from old expectations
 
 - verify whether the trace declares promoted components
 - compare `storedOutcome.gateSnapshot` against recomputed replay output before changing live policy
-- if the repo copied local replay docs, update them to the current reducer and envelope model
+- if the repo copied local replay docs, update them to the current reducer, envelope, and signal model
 
 ## Summary
 
-The current `0.8.5` surface keeps the same authority-set and phase-engine architecture, but it now ships the design-role starter surface and the hybrid design-steward runtime model as part of the published package. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, and runbooks so they describe the runtime the package now ships.
+The current `0.8.7` surface keeps the same authority-set and phase-engine architecture, ships both the design-role starter surface and the signal-driven long-running-agent starter surface, and now also hardens policy consistency, targeted recovery, capability-specific routing, and stable per-wave tmux session reuse. For most repos already on `0.8.x`, the upgrade is package bump plus validation. For older adopted repos, the real work is syncing repo-owned prompts, skills, planner corpus, wrapper scripts, and runbooks so they describe the runtime the package now ships.

package/docs/plans/wave-orchestrator.md

@@ -55,6 +55,8 @@ The live runtime is organized around explicit modules:
 - performs a closure sweep so optional `cont-EVAL`, optional security review, integration, documentation, and cont-QA gates reflect final landed state through the wave's effective closure-role bindings
 - treats design packets as a first-class pre-implementation gate when a wave declares `design` workers
 - rebuilds contradiction blockers from canonical control-plane events during replay and materializes human-blocked waves as `clarifying` plus blocked `waveState`
+- distinguishes hard, soft, stale, advisory, proof-critical, and closure-critical blockers instead of treating every open coordination record as equally blocking
+- turns recoverable timeout, max-turn, rate-limit, and missing-status failures into targeted recovery intent plus bounded repair work when proof-critical barriers are not present
 
 ## Main Commands
 
@@ -77,6 +79,8 @@ The live runtime is organized around explicit modules:
 - `pnpm exec wave feedback list --lane main --pending`
 - `pnpm exec wave control status --lane main --wave 0 --json`
 - `pnpm exec wave control status --lane main --wave 0 --agent A1 --json`
+- `scripts/wave-status.sh --lane main --wave 0 --agent A1`
+- `scripts/wave-watch.sh --lane main --wave 0 --agent A1 --until-change --refresh-ms 500`
 - `pnpm exec wave coord inbox --lane main --wave 0 --agent A1 --dry-run`
 - `pnpm exec wave control task create --lane main --wave 0 --agent A1 --kind blocker --summary "Need repository decision"`
 - `pnpm exec wave control task act reassign --lane main --wave 0 --id <task-id> --to A2`
@@ -159,11 +163,13 @@ pnpm exec wave launch --lane main --start-wave 0 --end-wave 0 --executor codex -
 ## Coordination Surfaces
 
 - `wave control status` is the read-only projection for "why blocked / why retrying" at wave or agent scope. It returns blocking edges, logical agent state, tasks, dependencies, rerun intent, active proof bundles, and next timers from one materialized control-plane view.
-- `wave control task create|get|list|act` is the operator task surface for blocking requests, blockers, clarification chains, human-input tickets, escalations, and informative handoffs, evidence, claims, and decisions. `wave control status` only treats requests, blockers, clarifications, human-input, escalations, helper assignments, and required dependencies as blocking edges.
+- `wave control task create|get|list|act` is the operator task surface for blocking requests, blockers, clarification chains, human-input tickets, escalations, and informative handoffs, evidence, claims, and decisions. `wave control status` only treats requests, blockers, clarifications, human-input, escalations, helper assignments, and required dependencies as candidate blocking edges, and then only when their current task or record metadata still marks them blocking.
+- Tasks now carry explicit `blocking` and `blockerSeverity` semantics. Operators can keep work visible while removing it from the active blocking edge with `defer`, `mark-advisory`, `mark-stale`, or `resolve-policy` when repo policy allows.
 - A fresh live `wave launch --start-wave <n> --end-wave <n>` now clears the previous auto-generated relaunch plan for that wave before selecting the initial implementation fan-out. Pass `--resume-control-state` only when you intentionally want to keep that persisted relaunch selection.
-- `wave control rerun request|get|clear` manages targeted rerun intent under `.tmp/<lane>-wave-launcher/control-plane/` and projects compatible retry overrides under `.tmp/<lane>-wave-launcher/control/`, including selected agents, reuse selectors, invalidated components, and clear or preserve reuse lists.
+- `wave control rerun request|get|clear` manages targeted rerun intent under `.tmp/<lane>-wave-launcher/control-plane/` and projects compatible retry overrides under `.tmp/<lane>-wave-launcher/control/`, including selected agents, reuse selectors, invalidated components, and clear or preserve reuse lists. The launcher can also queue one automatically after recoverable timeout, max-turn, rate-limit, or missing-status failures.
 - `wave control proof register|get|supersede|revoke` manages authoritative proof bundles in the same control-plane log and projects compatible proof registries under `.tmp/<lane>-wave-launcher/proof/`.
 - `wave control telemetry status|flush` inspects and delivers the local Wave Control event queue. Pass `--no-telemetry` on `wave launch` to disable event publication for a single run.
+- `scripts/wave-status.sh` and `scripts/wave-watch.sh` are thin wrapper readers over `wave control status --json` for shell automation and long-running watcher loops. Use [guides/signal-wrappers.md](../guides/signal-wrappers.md) for the exit-code and ack-loop contract.
 - `wave coord render` regenerates the markdown board projection from the canonical coordination log.
 - `wave coord inbox` writes the compiled shared summary plus the selected agent inbox.
 
@@ -175,7 +181,7 @@ The canonical conversational state is the JSONL log under `.tmp/<lane>-wave-laun
 
 Control-plane facts that drive reruns, proof, attempt state, contradictions, facts, human-input workflow, and operator tasks are appended separately under `.tmp/<lane>-wave-launcher/control-plane/`. Result envelopes live under `.tmp/<lane>-wave-launcher/results/wave-<n>/attempt-<a>/<agent>.json`. Legacy proof and retry files remain derived projections for compatibility, not decision inputs.
 
-Capability-targeted requests now become deterministic helper assignments. The runtime resolves the assignee from explicit targets, `capabilityRouting.preferredAgents`, then least-busy matching capability owners, writes that assignment into `.tmp/<lane>-wave-launcher/assignments/`, mirrors the decision into coordination state, and keeps the wave blocked until the linked follow-up resolves.
+Capability-targeted requests now become deterministic helper assignments. The runtime resolves the assignee from explicit targets, `capabilityRouting.preferredAgents`, then matching capability owners with demonstrated same-wave completions, then least-busy fallback, writes that assignment into `.tmp/<lane>-wave-launcher/assignments/`, mirrors the decision into coordination state, and keeps the wave blocked until the linked follow-up resolves or is explicitly downgraded by policy.
 
 Clarification flow is orchestrator-first:
 
@@ -185,7 +191,7 @@ Clarification flow is orchestrator-first:
 4. Routed clarification follow-up requests remain blocking until they resolve.
 5. Human escalations are written back into coordination state, the ledger, and trace artifacts.
 
-During live runs, the orchestrator now keeps an active supervision and state-refresh loop while agents are still running. It refreshes the derived coordination surfaces on cadence, surfaces overdue acknowledgements and stale clarification chains in dashboards and traces, and can reroute clarification follow-up requests inside the same attempt when the routed owner never acknowledges them.
+During live runs, the orchestrator now keeps an active supervision and state-refresh loop while agents are still running. It refreshes the derived coordination surfaces on cadence, surfaces overdue acknowledgements and stale clarification chains in dashboards and traces, can reroute clarification follow-up requests inside the same attempt when the routed owner never acknowledges them, and can leave non-critical advisory or stale records visible without forcing the whole wave into terminal failure.
 
 If you opt into `--resident-orchestrator`, the launcher also starts a long-running non-owning orchestrator session for the wave. That session can inspect the same coordination artifacts and intervene through coordination records, but it does not override reducer, gate, or closure decisions.
 
@@ -363,7 +369,7 @@ For the complete syntax of every command, flag, and subcommand, see [docs/refere
 - Skills resolve only after that executor choice is known. Runtime-specific skill overlays are regenerated whenever retry-time fallback changes the selected executor.
 - Runtime mix targets are enforced before launch and again before any retry-time fallback reassignment.
 - Fallbacks are declared in profiles or lane policy, can be applied automatically on retry when the next executor is available and still satisfies mix targets, and are recorded in the ledger, integration summary, and traces when used.
-- Generic `budget.minutes` caps per-agent attempt timeouts. Generic `budget.turns` seeds `claude.maxTurns` and `opencode.steps` when executor-specific values are not set; Codex turn ceilings remain external to Wave and show up in preview metadata as opaque when Wave cannot inspect them, though live previews now record an observed ceiling if the Codex runtime later logs one explicitly.
+- Generic `budget.minutes` caps per-agent attempt timeouts. Generic `budget.turns` remains advisory metadata unless the runtime-specific ceiling is declared explicitly through `claude.maxTurns` or `opencode.steps`; Codex turn ceilings remain external to Wave and show up in preview metadata as opaque when Wave cannot inspect them, though live previews now record an observed ceiling if the Codex runtime later logs one explicitly.
 - The launcher writes runtime overlay files under `.tmp/<lane>-wave-launcher/executors/`; these should stay ignored and local.
 
 Runtime authoring examples: