@chllming/wave-orchestration 0.8.5 → 0.8.7

package/docs/reference/cli-reference.md

@@ -96,7 +96,7 @@ Unified operator control surface. Preferred over legacy `wave coord`, `wave retr
 
 ### wave control status
 
-Read-only view: blocking edges, logical agent state, tasks, dependencies, rerun intent, proof bundles, and next timers.
+Read-only view: blocking edges, logical agent state, tasks, dependencies, rerun intent, proof bundles, next timers, and derived wave or agent signal snapshots.
 
 When a launcher attempt is already running, `wave control status` treats that active attempt as the authoritative current fan-out. Older relaunch plans or unrelated closure blockers remain visible in the payload, but they do not override the live attempt view.
 
@@ -104,6 +104,15 @@ When a launcher attempt is already running, `wave control status` treats that ac
 wave control status --lane <lane> --wave <n> [--agent <id>] [--run <id>] [--json]
 ```
 
+The JSON payload now includes:
+
+- `signals.wave`
+  Versioned wave-level signal state for wrappers and external operators.
+- `signals.agents`
+  Versioned per-agent signal state, including `shouldWake` plus any observed ack metadata.
+
+Starter repos also include `scripts/wave-status.sh` and `scripts/wave-watch.sh` as thin readers over this JSON payload. They use exit `0` for completed, `20` for input-required, `40` for failed, and `30` from `wave-watch.sh --until-change` when the signal changed but the wave stayed active. For the full wrapper contract, read [../guides/signal-wrappers.md](../guides/signal-wrappers.md).
+
 ### wave control telemetry
 
 Inspect and deliver the local Wave Control event queue.
@@ -124,13 +133,15 @@ wave control task create \
   --lane <lane> --wave <n> --agent <id> \
   --kind <kind> --summary "<text>" \
   [--detail "<text>"] [--target <agent-or-capability>] \
-  [--priority normal|high] [--depends-on <id>] \
+  [--priority normal|high] [--blocking true|false] \
+  [--severity hard|soft|stale|advisory|proof-critical|closure-critical] \
+  [--depends-on <id>] \
   [--artifact <ref>] [--operator <name>] [--json]
 ```
 
 Valid `--kind` values: `request`, `blocker`, `clarification`, `handoff`, `evidence`, `claim`, `decision`, `human-input`.
 
-Only `request`, `blocker`, `clarification`, `human-input`, and `escalation` are treated as blocking edges by `wave control status`. The rest (`handoff`, `evidence`, `claim`, `decision`) are informational.
+`wave control status` only treats `request`, `blocker`, `clarification`, `human-input`, and `escalation` as potentially blocking. Tasks of those kinds can still be downgraded with `blocking=false` or non-blocking severities such as `advisory` and `stale`, so they remain visible without owning the active blocking edge.
 
 **List tasks:**
 
@@ -163,6 +174,10 @@ Actions:
 | `reassign` | `--to <agent>` | Supersede the original, reroute to a new agent |
 | `answer` | `--response "<text>"` | Answer a human-input or escalation task |
 | `escalate` | `[--detail]` | Escalate to human feedback queue |
+| `defer` | `[--detail]` | Keep the task open but mark it non-blocking soft work |
+| `mark-advisory` | `[--detail]` | Keep the task visible but non-blocking with advisory severity |
+| `mark-stale` | `[--detail]` | Keep the task as historical context without blocking closure |
+| `resolve-policy` | `[--detail]` | Close the task by operator policy and downgrade linked clarification follow-up when applicable |
 
 **Operator answer example** (responding to a human-input escalation):
 
@@ -193,6 +208,8 @@ wave control rerun request \
 
 `--agent` is repeatable or comma-separated. At least one of `--agent` or `--resume-cursor` is required.
 
+The launcher may also write a rerun request automatically after recoverable failures such as timeout, max-turn, rate-limit, or missing-status outcomes. Those requests still appear through `wave control rerun get`, so operators can inspect or replace the targeted recovery plan before the next attempt.
+
 **Get active rerun request:**
 
 ```
@@ -544,7 +561,7 @@ Interactive draft currently offers worker role kinds:
 - `research`
 - `security`
 
-Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.8.5` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
+Agentic planner payloads also accept `workerAgents[].roleKind = "design"`. The shipped `0.8.7` surface uses `design-pass` as the default executor profile for that role and typically assigns a packet path like `docs/plans/waves/design/wave-<n>-<agentId>.md`. Interactive draft scaffolds the docs-first default; hybrid design stewards are authored by explicitly adding implementation-owned paths and the normal implementation contract sections.
 
 ## Ad-Hoc Task Commands
 

package/docs/reference/coordination-and-closure.md

@@ -108,14 +108,31 @@ Wave treats these coordination statuses as open:
 - `acknowledged`
 - `in_progress`
 
-It treats these as non-blocking:
+It treats these statuses as closed:
 
 - `resolved`
 - `closed`
 - `superseded`
 - `cancelled`
 
-That means a targeted helper request keeps blocking until the request leaves the open set in coordination state.
+But "open" and "blocking" are now different questions.
+
+Open records can carry a blocker severity:
+
+- `hard`
+- `soft`
+- `stale`
+- `advisory`
+- `proof-critical`
+- `closure-critical`
+
+Practical rule:
+
+- `proof-critical`, `closure-critical`, and hard required barriers still stop the wave outright
+- `soft` blockers stay visible and may still drive repair work or retry targeting
+- `stale` and `advisory` records remain in coordination history without owning the active blocking edge
+
+That means a targeted helper request only blocks while it remains open *and* still has blocking severity in coordination state.
 
 This page is documenting runtime semantics first. The important contract is that closure follows the durable coordination state, not that a particular human or agent used one exact command path to mutate it.
 
@@ -181,7 +198,7 @@ What happens next:
 - that assignment is written into the assignment snapshot
 - the shared summary and A8 inbox now show the open helper work
 
-`wave control task list` and `wave control task get` surface both blocking and informative coordination kinds. `wave control status` only turns `request`, `blocker`, `clarification-request`, `human-feedback`, and `human-escalation` into blocking task edges; plain `handoff`, `evidence`, `claim`, and `decision` records stay visible without falsely blocking the owner. When a launcher attempt is already running, status scopes the top-level blocking edge to that active attempt instead of letting stale relaunch metadata or unrelated closure tasks dominate the wave-level view.
+`wave control task list` and `wave control task get` surface both blocking and informative coordination kinds. `wave control status` only turns `request`, `blocker`, `clarification-request`, `human-feedback`, and `human-escalation` into candidate blocking task edges, and then only if the current record still has `blocking=true` plus a blocking severity. Plain `handoff`, `evidence`, `claim`, and `decision` records stay visible without falsely blocking the owner. When a launcher attempt is already running, status scopes the top-level blocking edge to that active attempt instead of letting stale relaunch metadata or unrelated closure tasks dominate the wave-level view.
 
 ### Step 3: Why A1 Can Be Done But The Wave Is Still Blocked
 
@@ -253,15 +270,19 @@ Important implication:
 
 - even if code is landed, an open clarification chain can still block the wave
 - a routed clarification that stays `open` past the acknowledgement policy can be rerouted during the same live attempt instead of waiting for a full retry cycle
-- operators can now inspect and intervene through one command surface:
+- operators can now inspect and intervene through one command surface, including downgrade or policy-close actions when the remaining issue is no longer proof-critical:
 
 ```bash
 pnpm exec wave control status --lane main --wave 10 --agent A7 --json
 pnpm exec wave control task act reassign --lane main --wave 10 --id clarify-a7-rollout --to A1
+pnpm exec wave control task act mark-stale --lane main --wave 10 --id clarify-a7-rollout
+pnpm exec wave control task act mark-advisory --lane main --wave 10 --id request-clarify-a7-rollout
+pnpm exec wave control task act defer --lane main --wave 10 --id blocker-doc-follow-up
+pnpm exec wave control task act resolve-policy --lane main --wave 10 --id clarify-a7-rollout --detail "Policy already covered in the published rollout guide."
 pnpm exec wave control task act resolve --lane main --wave 10 --id escalation-clarify-a7-rollout --detail "Published command surface covers this question."
 ```
 
-That keeps clarification routing, dismissal, escalation, and human-answer handling inside the canonical coordination state instead of forcing ad hoc file edits.
+That keeps clarification routing, downgrade, dismissal, escalation, policy closure, and human-answer handling inside the canonical coordination state instead of forcing ad hoc file edits.
 
 When the operator answers through the feedback queue directly, the answer path now repairs the same canonical state:
 

package/docs/reference/live-proof-waves.md

@@ -40,6 +40,7 @@ For live-proof owners:
 - declare `### Proof artifacts` for machine-visible local evidence
 - keep the executor sticky unless fallback is explicitly required
 - prefer wall-clock budgets over tiny hard turn caps
+- treat generic `budget.turns` as advisory; only set runtime-specific turn ceilings when you want a true hard stop
 
 Example:
 
@@ -118,6 +119,12 @@ For proof-bearing owners, default to sticky retry:
 
 Only enable cross-executor retry when there is a deliberate reason to do so.
 
+Budget guidance:
+
+- `budget.minutes` is the primary attempt budget and should be the normal control for live-proof owners
+- generic `budget.turns` is now advisory metadata for Claude and OpenCode unless you also set the runtime-specific limit
+- use `claude.max_turns` or `opencode.steps` only when a hard per-attempt ceiling is intentional
+
 If you do allow fallback, declare it explicitly:
 
 ```md
@@ -172,6 +179,8 @@ pnpm exec wave control proof register \
 4. any stale integration or closure owner reruns if needed
 5. already-valid implementation slices stay reused
 
+For non-proof-centric owners elsewhere in the wave, recoverable timeout, max-turn, rate-limit, or missing-status outcomes can now queue targeted recovery automatically. For proof-bearing owners, the safer default is still to keep the same executor sticky and make the operator decision explicit once the new proof bundle exists.
+
 Authoritative proof registration is the supported way to make operator-produced evidence visible to A8, A0, rerun control, and hermetic traces without forcing an implementation agent to rediscover the same local artifacts in a fresh session. The canonical proof bundle now lands in `.tmp/<lane>-wave-launcher/control-plane/` and is projected into `.tmp/<lane>-wave-launcher/proof/` for compatibility.
 
 ## Suggested Eval Targets For Live-Proof Waves

package/docs/reference/npmjs-trusted-publishing.md

@@ -2,7 +2,7 @@
 
 This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
 
-The current `0.8.5` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.8.7` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
 
 ## What This Repo Already Does
 
@@ -48,6 +48,6 @@ If this repo later needs private npm dependencies during CI, consider a separate
 2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
 3. Confirm the package version has been bumped and committed.
 4. Confirm `README.md`, `CHANGELOG.md`, `releases/manifest.json`, and `docs/plans/migration.md` all describe the same release surface.
-5. Push the release commit and release tag, for example `v0.8.5`.
+5. Push the release commit and release tag, for example `v0.8.7`.
 6. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
 7. Verify the npmjs publish completes successfully for the tagged source.

package/docs/reference/runtime-config/README.md

@@ -66,8 +66,14 @@ These fields are shared across runtimes:
 | Model | `model` in profile, `executors.claude.model`, `executors.opencode.model` | `model` | Codex uses shared `model` from profile or agent only |
 | Fallbacks | `fallbacks` in profile | `fallbacks` | Runtime ids used for retry-time reassignment |
 | Tags | `tags` in profile | `tags` | Stored in resolved executor state for policy and traces |
-| Budget turns | `budget.turns` in profile | `budget.turns` | Seeds Claude `maxTurns` and OpenCode `steps` when runtime-specific values are absent; it does not set a Codex turn limit |
-| Budget minutes | `budget.minutes` in profile | `budget.minutes` | Caps attempt timeout |
+| Budget turns | `budget.turns` in profile | `budget.turns` | Advisory generic turn budget. Wave records it in resolved metadata, but only runtime-specific settings such as `claude.maxTurns` or `opencode.steps` emit hard turn-limit flags. It does not set a Codex turn limit. |
+| Budget minutes | `budget.minutes` in profile | `budget.minutes` | Primary wall-clock attempt budget |
+
+Practical guidance:
+
+- prefer `budget.minutes` for normal synthesis, integration, and closure work
+- use generic `budget.turns` as a planning hint, not a hard failure trigger
+- only set `claude.maxTurns` or `opencode.steps` when you deliberately want a hard ceiling for that runtime
 
 ## Runtime Pages
 
@@ -161,7 +167,7 @@ Runtime-specific delivery:
 - OpenCode injects the compact catalog into `opencode.json` and attaches `skill.json`, `SKILL.md`, the selected adapter, and recursive `references/**` files through `--file`.
 - Local keeps skills prompt-only.
 
-`launch-preview.json` also records the resolved skill metadata plus a `limits` section. For Claude and OpenCode, that section reports the known turn ceiling and whether it came from the runtime-specific setting or generic `budget.turns`. For Codex, it explicitly records that Wave emitted no turn-limit flag and that any effective ceiling may come from the selected Codex profile or upstream runtime. If a live Codex run later terminates with a visible `Reached max turns (N)` log line, Wave appends that observed ceiling back into the live `launch-preview.json` as runtime evidence rather than pretending Wave set it.
+`launch-preview.json` also records the resolved skill metadata plus a `limits` section. For Claude and OpenCode, that section reports the runtime-specific turn ceiling when one was actually configured; when only generic `budget.turns` exists, the preview keeps it as advisory metadata and notes that Wave emitted no hard turn-limit flag. For Codex, it explicitly records that Wave emitted no turn-limit flag and that any effective ceiling may come from the selected Codex profile or upstream runtime. If a live Codex run later terminates with a visible `Reached max turns (N)` log line, Wave appends that observed ceiling back into the live `launch-preview.json` as runtime evidence rather than pretending Wave set it.
 
 ## Recommended Validation Path
 

package/docs/reference/sample-waves.md

@@ -1,11 +1,11 @@
 ---
 title: "Sample Waves"
-summary: "Showcase-first sample waves that demonstrate the shipped 0.8.5 authored surface, including the optional design-role path."
+summary: "Showcase-first sample waves that demonstrate the shipped 0.8.7 authored surface, including the optional design-role path."
 ---
 
 # Sample Waves
 
-This guide points to showcase-first sample waves that demonstrate the shipped `0.8.5` authored Wave surface.
+This guide points to showcase-first sample waves that demonstrate the shipped `0.8.7` authored Wave surface.
 
 The examples are intentionally denser than typical production waves. Their job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready files.
 
@@ -15,7 +15,7 @@ The examples are intentionally denser than typical production waves. Their job i
   Shows what a good `repo-landed` outcome looks like when one promoted component only closes honestly if desired-state records, reconcile-loop substrate, and cluster-view surfaces land together. It emphasizes maturity discipline, explicit deliverables, and shared-plan closure without drifting into `pilot-live` claims.
 
 - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
-  Shows the combined `0.8.5` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+  Shows the combined `0.8.7` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
 
 - [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md)
   Shows the shipped design-role surface: one pre-implementation design steward publishes a design packet, downstream implementation owners read that packet before coding, and normal closure roles still decide final completion. For terminal or operator-surface work, pair that shape with explicit `tui-design` in the design steward's `### Skills`. For the hybrid variant, explicitly give that same design agent implementation-owned paths and the normal implementation contract sections.
@@ -42,7 +42,7 @@ The examples are intentionally denser than typical production waves. Their job i
 
 ## Feature Coverage Map
 
-Together these samples cover the main surfaces added or hardened through `0.8.5`:
+Together these samples cover the main surfaces added or hardened through `0.8.7`:
 
 - repo-landed maturity discipline and anti-overclaim framing
 - explicit shared-plan closure for future-wave safety
@@ -89,7 +89,7 @@ Adapt more aggressively when:
 ## Suggested Reading Order
 
 1. Start with [High-fidelity repo-landed rollout wave](../plans/examples/wave-example-rollout-fidelity.md) if you want the clearest example of good closure-ready wave fidelity for a repo-only outcome.
-2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.8.5` surface.
+2. Read [Full modern sample wave](../plans/examples/wave-example-live-proof.md) if you want the denser proof-first and eval-heavy `0.8.7` surface.
 3. Read [Optional design-steward handoff wave](../plans/examples/wave-example-design-handoff.md) if the task needs a design packet before implementation fan-out.
 4. Read [docs/evals/README.md](../evals/README.md) if you want more background on benchmark target selection.
 5. Read [docs/reference/live-proof-waves.md](./live-proof-waves.md) if you want more detail on proof-first `pilot-live` authoring.

package/docs/reference/skills.md

@@ -124,7 +124,9 @@ Top-level and lane-local skill attachment use the same shape:
 
 Lane-local `lanes.<lane>.skills` extends the global config instead of replacing it.
 
-Optional design workers in the shipped `0.8.5` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
+Optional design workers in the shipped `0.8.7` surface normally attach `role-design`. That bundle is intended for docs/spec-first design packets and explicit implementation handoff work before implementation starts. When the design packet covers terminal UX, dashboards, or other operator surfaces, add `tui-design` explicitly in the wave's `### Skills`.
+
+Long-running agents that should stay resident and react only to orchestrator signal changes can add `signal-hygiene` explicitly in `### Skills`. That bundle is not auto-attached and is not meant for normal one-shot implementation agents.
 
 ## Resolution Order
 
@@ -204,6 +206,12 @@ For the optional `design` worker role, the default pattern is:
 - `tui-design` only when the packet covers terminal UX, dashboards, or other operator surfaces
 - no runtime-specific coding bundle unless the wave explicitly gives the design steward code ownership and makes it a hybrid design steward
 
+For long-running watcher agents, the default pattern is:
+
+- no special bundle by default
+- add `signal-hygiene` only when the agent should stay alive and wait for signal-version changes
+- use the provided signal state path plus signal ack path instead of inventing a second wakeup loop
+
 ## Generated Artifacts
 
 Executor overlay directories can contain:

package/docs/reference/wave-control.md

@@ -19,6 +19,8 @@ Wave Control normalizes these entity types:
 
 - `wave_run`
 - `agent_run`
+- `wave_signal`
+- `agent_signal`
 - `coordination_record`
 - `task`
 - `attempt`
@@ -40,6 +42,8 @@ This lets the control plane answer:
 - which proof and benchmark artifacts back a claim
 - whether a benchmark result is comparison-valid or only diagnostic
 - which coordination failures blocked closure
+- which blockers were hard, soft, stale, or advisory
+- whether a blocked wave is terminal or recoverable and which targeted rerun request was queued
 
 ## Run Identity
 
@@ -90,6 +94,20 @@ Signals to preserve:
 - benchmark trust:
   every benchmark item should distinguish capability from validity
 
+## Blocker And Recovery Metadata
+
+Wave Control should preserve the softer runtime policy, not flatten it away.
+
+In practice that means `coordination_record`, `task`, `gate`, `wave_run`, and `rerun_request` payloads should keep fields such as:
+
+- `blocking`
+- `blockerSeverity`
+- `recoverable`
+- `recoveryReason`
+- queued rerun request ids or resume targets
+
+That distinction matters because a wave that is `blocked` by a proof-critical gate is different from a wave that is `blocked` only long enough to surface a targeted recovery after timeout, max-turn, rate-limit, or missing-status failure. The control plane should let operators ask which barriers still stop closure outright and which ones were intentionally downgraded to advisory or stale context.
+
 ## Artifact Contract
 
 Selected artifacts are described with typed descriptors:

package/docs/reference/wave-planning-lessons.md

@@ -74,11 +74,15 @@ runtime setup, and the closure artifacts all describe the same truth.
 ## 7. Runtime setup matters as much as wave prose
 
 - Do not use small fixed turn caps for synthesis-heavy or closure-heavy agents.
-  Bound them with `budget.minutes`, not `budget.turns`.
+  Bound them with `budget.minutes`, not generic `budget.turns`.
+- Treat generic `budget.turns` as advisory unless you intentionally set a
+  runtime-specific hard stop such as `claude.max_turns` or `opencode.steps`.
 - Pin exact model and reasoning settings for each runtime. Ambiguous profiles
   create unclear failure modes.
 - Avoid cross-runtime fallback on live-proof or deploy-sensitive slices unless
   there is a very good reason.
+- For non-proof-centric owners, prefer targeted recovery and reuse over broad
+  relaunch when a timeout or max-turn event leaves partial artifacts behind.
 - Context7 should be explicit and real; unresolved bundles create noise instead
   of help.
 
@@ -121,6 +125,8 @@ runtime setup, and the closure artifacts all describe the same truth.
 - Are A8 and A0 told what would make the wave fail honestly?
 - Are runtime pins, Context7 bundles, and budgets specific enough to avoid
   preventable execution failures?
+- Can any non-proof coordination ask be authored as `soft`, `stale`, or
+  `advisory` instead of silently becoming a hard closure blocker?
 - Would a reviewer understand the difference between “code landed” and
   “component promoted” just by reading the wave file?
 

package/docs/research/coordination-failure-review.md

@@ -229,16 +229,16 @@ This is the central failure highlighted by `HiddenBench` and `Silo-Bench`, and t
 
 ### 3. Expertise routing is explicit, but shallow
 
-[scripts/wave-orchestrator/routing-state.mjs](../../scripts/wave-orchestrator/routing-state.mjs) is better than unconstrained self-organization, but it still routes mostly by:
+[scripts/wave-orchestrator/routing-state.mjs](../../scripts/wave-orchestrator/routing-state.mjs) is better than unconstrained self-organization, and it now has a light same-wave success preference, but it still routes mostly by:
 
 - explicit target
 - configured preferred agents
 - declared capability ownership
+- demonstrated same-wave completions on the capability
 - least-busy fallback
 
-It does not yet weight:
+Beyond that light historical-success preference, it still does not weight:
 
-- historical success on a capability
 - evidence quality by agent
 - confidence calibration
 - expert-leverage metrics
@@ -247,14 +247,14 @@ So the repo partially addresses the concern from `Multi-Agent Teams Hold Experts
 
 ### 4. Clarification and contradiction handling are still somewhat heuristic
 
-Clarification triage and integration evidence aggregation are real safeguards, but they still lean heavily on:
+Clarification triage, blocker taxonomy, operator downgrade controls, and integration evidence aggregation are real safeguards, but they still lean heavily on:
 
 - ownership mappings
 - artifact references
 - structured markers
 - text-level summaries and conflict extraction
 
-That is enough to make the runtime operationally safer, but it is not yet a richer semantic evidence-integration layer. Subtle contradictions or latent information asymmetries may still be missed.
+That is enough to make the runtime operationally safer. The newer hard-vs-soft blocker split also removes some unnecessary terminal failures by letting stale or advisory coordination remain visible without owning closure. But it is not yet a richer semantic evidence-integration layer, and subtle contradictions or latent information asymmetries may still be missed.
 
 ### 5. DPBench-style simultaneous coordination is only indirectly addressed
 
@@ -283,7 +283,7 @@ So the design points in the right direction, but the claim is not yet validated.
 
 If the standard is "does this repo merely claim multi-agent coordination," the answer is no. It has real machinery for blackboard-like state sharing, evidence-based closure, clarification handling, and coordination diagnostics.
 
-If the standard is "has this repo already demonstrated that its design beats the core failure modes isolated by HiddenBench, Silo-Bench, DPBench, and related work," the answer is also no. The design is substantially more credible than most MAS stacks, but the empirical proof is still missing.
+If the standard is "has this repo already demonstrated that its design beats the core failure modes isolated by HiddenBench, Silo-Bench, DPBench, and related work," the answer is also no. The design is substantially more credible than most MAS stacks, and it now also reduces avoidable failure through targeted recovery, blocker severity, and policy-safe downgrade paths, but the empirical proof is still missing.
 
 The most accurate claim today is:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chllming/wave-orchestration",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "license": "MIT",
   "description": "Generic wave-based multi-agent orchestration for repository work.",
   "repository": {

package/releases/manifest.json

@@ -2,6 +2,44 @@
   "schemaVersion": 1,
   "packageName": "@chllming/wave-orchestration",
   "releases": [
+    {
+      "version": "0.8.7",
+      "date": "2026-03-27",
+      "summary": "Policy-consistency hardening, capability-specific same-wave routing, stable per-wave tmux session reuse, and 0.8.7 release-surface alignment.",
+      "features": [
+        "Generic `budget.turns` is now documented and tested consistently as advisory metadata only; hard runtime turn ceilings come only from runtime-specific settings such as `claude.maxTurns` or `opencode.steps`.",
+        "Capability-targeted helper routing now prefers demonstrated same-wave success for the requested capability before falling back to the least-busy matching capability owner, and unrelated completed work no longer counts as routing evidence.",
+        "Advisory, stale, and other non-blocking clarification or human-input records stay visible in control and reducer projections without reopening hard blocked reducer state by themselves.",
+        "Wave-agent, resident-orchestrator, and per-wave dashboard tmux sessions now reuse stable per-wave session names, so stale launcher exits stop accumulating extra sessions for the same wave.",
+        "Structured signal extraction now also recognizes markers embedded inside JSON log lines, so wrapped executor transcripts still produce proof, doc-delta, and component evidence."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.7` routing, blocker-severity, signal-wrapper, and stable-session behavior.",
+        "If your repo copied starter scripts or operator docs, sync `scripts/wave-status.sh`, `scripts/wave-watch.sh`, `docs/guides/signal-wrappers.md`, `docs/guides/terminal-surfaces.md`, `docs/reference/cli-reference.md`, and any local tmux/session runbooks that still assume run-tagged session names.",
+        "If your repo copied planner or routing guidance, sync `docs/guides/planner.md`, `docs/reference/wave-planning-lessons.md`, `docs/plans/wave-orchestrator.md`, the `planner-agentic` bundle entry in `docs/context7/bundles.json`, and any local helper-assignment policy docs so they describe capability-specific same-wave routing evidence instead of generic prior completion.",
+        "If your repo relies on advisory `budget.turns` as if it were a hard ceiling, move that limit to the runtime-specific executor config (`claude.maxTurns` or `opencode.steps`) before you depend on deterministic turn enforcement."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.8.6",
+      "date": "2026-03-25",
+      "summary": "Signal-hygiene starter surface, versioned signal wrappers, terminal watcher hardening, and 0.8.6 release-surface alignment.",
+      "features": [
+        "Versioned wave and agent signal snapshots now ship as part of the operator surface under `.tmp/<lane>-wave-launcher/signals/`, with resident-orchestrator and long-running-agent ack loops built on the same model.",
+        "Starter repos now include `skills/signal-hygiene/`, `scripts/wave-status.sh`, and `scripts/wave-watch.sh` for long-running watcher agents plus shell-friendly operator automation.",
+        "Wrapper exit semantics now expose terminal failure with exit `40`, while `wave-watch.sh --until-change` still returns `30` only when a signal changed and the wave stayed active.",
+        "Agent signal materialization now treats completed and failed as terminal even when stale answered feedback or old coordination tasks still exist in the materialized status payload.",
+        "The migration guide now covers fresh adoption plus upgrades from `0.8.5`, `0.8.4`, `0.8.3`, `0.8.0`-`0.8.4`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier, including repo-owned sync guidance for `skills/signal-hygiene/`, the wrapper scripts, and the `planner-agentic` corpus."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave doctor` and `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading so the repo validates against the `0.8.6` signal-hygiene, wrapper, and design-role behavior.",
+        "If your repo copied starter prompts, skills, scripts, or runbooks, sync `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`, and any local operator docs that describe waiting or failure handling.",
+        "If your repo uses planner workflows and copied the planner starter corpus, keep `docs/agents/wave-planner-role.md`, `skills/role-planner/`, `docs/context7/planner-agent/`, `docs/reference/wave-planning-lessons.md`, and the `planner-agentic` bundle entry in sync before relying on local planner docs.",
+        "If your repo uses long-running watcher agents or shell automation, update local loops so wrapper exit `40` is treated as terminal failure and confirm watchers can write their signal ack files under `.tmp/<lane>-wave-launcher/signals/`."
+      ],
+      "breaking": false
+    },
     {
       "version": "0.8.5",
       "date": "2026-03-25",

package/scripts/context7-api-check.sh

@@ -1,5 +1,4 @@
 #!/usr/bin/env bash
-# Minimal Context7 API smoke test (expects CONTEXT7_API_KEY in the environment).
 set -euo pipefail
 
 if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then
@@ -7,15 +6,60 @@ if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then
   exit 1
 fi
 
-URL='https://context7.com/api/v2/libs/search?libraryName=temporal&query=go%20workflow'
-echo "GET $URL" >&2
-RESP="$(curl -fsS "$URL" -H "Authorization: Bearer ${CONTEXT7_API_KEY}" -H "Accept: application/json")"
-RESP_JSON="$RESP" node -e "
-const j = JSON.parse(process.env.RESP_JSON || '{}');
-const list = Array.isArray(j) ? j : (j.results ?? j.items ?? []);
-const first = list[0];
-if (!first) { console.error('Unexpected response shape:', Object.keys(j)); process.exit(1); }
-const id = first.id ?? first.libraryId;
-const name = first.title ?? first.name;
-console.log('ok — first library:', id || name || JSON.stringify(first).slice(0, 120));
-"
+node <<'NODE'
+const fs = require("fs");
+const path = require("path");
+
+const apiKey = process.env.CONTEXT7_API_KEY || "";
+const repoRoot = process.cwd();
+const bundlePath = path.join(repoRoot, "docs/context7/bundles.json");
+const payload = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
+
+const entries = [];
+for (const [bundleId, bundle] of Object.entries(payload.bundles || {})) {
+  for (const library of bundle.libraries || []) {
+    if (!library.libraryId) {
+      throw new Error(
+        `Bundle "${bundleId}" must pin exact Context7 libraryId values. Found libraryName=${JSON.stringify(library.libraryName || "")}.`,
+      );
+    }
+    entries.push({
+      bundleId,
+      libraryId: String(library.libraryId),
+      queryHint: String(library.queryHint || "overview"),
+    });
+  }
+}
+
+const uniqueEntries = [...new Map(entries.map((entry) => [entry.libraryId, entry])).values()];
+
+async function validate(entry) {
+  const url = new URL("https://context7.com/api/v2/context");
+  url.searchParams.set("libraryId", entry.libraryId);
+  url.searchParams.set("query", entry.queryHint);
+  url.searchParams.set("type", "txt");
+  const response = await fetch(url, {
+    headers: {
+      Authorization: "Bearer " + apiKey,
+      Accept: "text/plain, application/json",
+    },
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`Context7 ${entry.libraryId} failed (${response.status}): ${text.slice(0, 200)}`);
+  }
+  if (text.trim().length === 0) {
+    throw new Error(`Context7 ${entry.libraryId} returned empty context.`);
+  }
+  console.log(`ok -- ${entry.libraryId} (${entry.bundleId})`);
+}
+
+(async () => {
+  for (const entry of uniqueEntries) {
+    await validate(entry);
+  }
+})().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+NODE

package/scripts/wave-orchestrator/agent-state.mjs

@@ -160,6 +160,44 @@ function appendParsedStructuredSignalCandidates(lines, candidates, { requireAll
   candidates.push(...parsedCandidates);
 }
 
+function collectEmbeddedStructuredSignalTexts(value, texts) {
+  if (!value || typeof value !== "object") {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectEmbeddedStructuredSignalTexts(item, texts);
+    }
+    return;
+  }
+  if (typeof value.text === "string") {
+    texts.push(value.text);
+  }
+  if (typeof value.aggregated_output === "string") {
+    texts.push(value.aggregated_output);
+  }
+  for (const nestedValue of Object.values(value)) {
+    if (nestedValue && typeof nestedValue === "object") {
+      collectEmbeddedStructuredSignalTexts(nestedValue, texts);
+    }
+  }
+}
+
+function extractEmbeddedStructuredSignalTextsFromJsonLine(line) {
+  const trimmed = String(line || "").trim();
+  if (!trimmed || !/^[{\[]/.test(trimmed)) {
+    return [];
+  }
+  try {
+    const payload = JSON.parse(trimmed);
+    const texts = [];
+    collectEmbeddedStructuredSignalTexts(payload, texts);
+    return texts.filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 function collectStructuredSignalCandidates(text) {
   if (!text) {
     return [];
@@ -167,6 +205,10 @@ function collectStructuredSignalCandidates(text) {
   const candidates = [];
   let fenceLines = null;
   for (const rawLine of String(text || "").split(/\r?\n/)) {
+    const embeddedTexts = extractEmbeddedStructuredSignalTextsFromJsonLine(rawLine);
+    for (const embeddedText of embeddedTexts) {
+      candidates.push(...collectStructuredSignalCandidates(embeddedText));
+    }
     const trimmed = rawLine.trim();
     if (/^```/.test(trimmed)) {
       if (fenceLines === null) {