@chllming/wave-orchestration 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## Unreleased
+
+## 0.8.7 - 2026-03-27
+
+### Changed
+
+- Generic `budget.turns` is now treated consistently as advisory metadata unless a runtime-specific ceiling such as `claude.maxTurns` or `opencode.steps` is declared; `budget.minutes` remains the primary attempt budget and the release docs/tests now match that runtime behavior.
+- The blocker-severity model is now consistent across coordination, control status, and reducer-backed closure state, so open work can stay visible as `soft`, `stale`, or `advisory` without automatically reopening hard blocking state.
+- The expanded `wave control task act` repair surface now supports deferral, advisory or stale downgrade, and policy resolution inside canonical control state instead of manual file edits.
+
+### Fixed And Hardened
+
+- Recoverable execution failures such as timeout, max-turn, rate-limit, and missing-status outcomes now prefer targeted rerun or resume paths plus bounded repair work instead of broad wave failure when proof-critical blockers are not present.
+- Autonomous and retry flows now keep moving when only non-blocking human or clarification records remain, while proof-centric owners still default to sticky executor behavior.
+- Capability routing now prefers demonstrated same-wave success for the requested capability before falling back to the least-busy matching capability owner; unrelated completed work no longer counts as routing evidence.
+- Structured marker extraction now also recognizes proof, doc-delta, and component markers embedded inside JSON log lines, so wrapped executor transcripts no longer hide valid closure evidence.
+- Wave agent and resident-orchestrator tmux sessions now reuse stable per-wave session names instead of appending a run tag, which prevents stale launcher exits from accumulating extra tmux sessions for the same wave.
+
+### Testing And Validation
+
+- Added regression coverage around advisory blockers, targeted recovery, autonomous non-blocking human-input handling, advisory turn-budget behavior, capability-specific same-wave routing preference, non-blocking clarification/human-input reducer behavior, and stable per-wave tmux session naming.
+
+## 0.8.6 - 2026-03-25
+
+### Added
+
+- Added canonical wave and per-agent signal projections under `.tmp/<lane>-wave-launcher/signals/`, plus the `signal-hygiene` starter skill for long-running agents that should wait on versioned wake signals instead of exiting after a one-shot pass.
+- Added seeded operator wrappers `scripts/wave-status.sh` and `scripts/wave-watch.sh` as thin readers over `wave control status --json`, including `--agent <id>` targeting and `--until-change` polling for external automation.
+- Added [docs/guides/signal-wrappers.md](./docs/guides/signal-wrappers.md), a dedicated operator guide for signal snapshots, wrapper exit codes, and the ack-loop contract used by long-running agents and the resident orchestrator.
+
+### Changed
+
+- Updated the shipped package metadata, README, current-state notes, migration guide, terminal and CLI docs, architecture docs, sample-wave docs, and npm publishing instructions to advertise `0.8.6` as the current release surface.
+- Documented the long-running signal model explicitly: prompt-level signal-state plus ack-path injection, versioned signal snapshots for both waves and agents, and wrapper-driven monitoring for external operator scripts.
+
+### Fixed And Hardened
+
+- Agent signal materialization now treats wave-level `completed` and `failed` as terminal, so stale answered feedback or pending coordination tasks cannot keep long-running agents in a non-terminal wait state after the wave has already closed.
+- Resident orchestrator signal versions now bump when only `targetAgentIds` change, so reroutes that keep the same signal kind still wake long-running residents and watchers correctly.
+- Wrapper exit semantics now treat `failed` as terminal with exit code `40`, so external monitors and `signal-hygiene` loops stop waiting when the wave fails instead of hanging on the generic active path.
+
+### Testing And Validation
+
+- Added regression coverage for terminal signal precedence, resident reroute versioning, and terminal-failure wrapper exits.
+- Re-ran the full Vitest suite, `wave doctor --json`, and `wave launch --lane main --dry-run --no-dashboard`.
+
 ## 0.8.5 - 2026-03-25
 
 ### Added

package/README.md

@@ -103,18 +103,18 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.8.5`
-- Release tag: [`v0.8.5`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.5)
+- `@chllming/wave-orchestration@0.8.7`
+- Release tag: [`v0.8.7`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.7)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.5`:
+Highlights in `0.8.7`:
 
-- The optional `design` worker role is now part of the shipped release surface, including `docs/agents/wave-design-role.md`, `skills/role-design/`, and `skills/tui-design/`.
-- Design stewards are docs-first by default, but waves can now explicitly assign code ownership and get a hybrid two-pass flow: design packet first, implementation follow-through second.
-- Gates, retry or resume planning, reducer state, prompts, local-executor smoke behavior, and result envelopes now all agree on that hybrid design-steward contract.
-- The migration guide is now a practical upgrade document for fresh adoption plus upgrades from `0.8.3`, `0.8.4`, `0.8.0`-`0.8.4`, `0.6.x`-`0.7.x`, and `0.5.x` or earlier.
-- Release docs, sample waves, current-state notes, and publishing instructions now point at the `0.8.5` surface.
+- The shipped starter surface now includes `skills/signal-hygiene/` plus seeded `scripts/wave-status.sh` and `scripts/wave-watch.sh` wrappers for long-running-agent and operator wait loops.
+- Long-running agents and resident orchestrators now get prompt-level signal-state and signal-ack paths, so wakeups are edge-triggered by versioned signal changes instead of relying on terminal injection.
+- Versioned wave or agent signal snapshots are now a first-class operator surface under `.tmp/<lane>-wave-launcher/signals/`, with failure treated as terminal in both the runtime and the wrapper exit contract.
+- `0.8.5` design-role and hybrid design-steward behavior remains part of the shipped release surface, and `0.8.7` adds capability-specific same-wave helper routing, blocker-severity consistency across reducer state, and stable per-wave tmux session reuse.
+- Release docs, current-state notes, migration guidance, and publishing instructions now point at the `0.8.7` surface.
 
 Requirements:
 
@@ -148,10 +148,14 @@ The starter surface includes:
 - `docs/agents/wave-design-role.md`
 - `skills/role-design/`
 - `skills/tui-design/` for terminal and operator-surface design work
+- `skills/signal-hygiene/` for intentionally long-running watcher agents
+- `scripts/wave-status.sh` and `scripts/wave-watch.sh` for external wait loops
 - `wave.config.json` defaults for `roles.designRolePromptPath`, `skills.byRole.design`, and the `design-pass` executor profile
 
 Interactive `wave draft` scaffolds the docs-first design-steward path. If you want a hybrid design steward, author that wave explicitly or use an agentic planner payload that gives the same design agent implementation-owned paths plus the normal implementation contract sections.
 
+If a non-resident agent should stay alive and react only to orchestrator-written signal changes, add `signal-hygiene` explicitly in `### Skills`. That bundle uses the prompt-injected signal-state and ack paths instead of inventing a second wakeup surface. For shell automation and the wrapper contract, see [docs/guides/signal-wrappers.md](./docs/guides/signal-wrappers.md).
+
 When runtime launch commands detect a newer npmjs release, Wave prints a non-blocking update notice on stderr. The fast path is `pnpm exec wave self-update`, which updates the dependency, prints the changelog delta, and then records the workspace upgrade report.
 
 ## Common Commands
@@ -183,7 +187,7 @@ pnpm exec wave self-update
 - `wave launch` and `wave autonomous`
   Live execution, dry-run validation, retry cadence, terminal surfaces, and orchestrator options.
 - `wave control`
-  Read-only live status plus operator task, rerun, proof, and telemetry control surfaces.
+  Read-only live status plus operator task, rerun, proof, telemetry, and versioned signal surfaces. Seeded helper scripts `scripts/wave-status.sh` and `scripts/wave-watch.sh` are thin readers over `wave control status --json`.
 - `wave coord` and `wave dep`
   Coordination-log and cross-lane dependency utilities. `wave control` is the preferred operator surface; `wave coord` remains useful for direct log inspection and rendering.
 - `wave project`, `wave draft`, and `wave adhoc`
@@ -226,6 +230,7 @@ codex mcp list
 - [docs/guides/planner.md](./docs/guides/planner.md): `wave project` and `wave draft` workflow
 - [docs/agents/wave-design-role.md](./docs/agents/wave-design-role.md): standing prompt for the optional pre-implementation design steward
 - [docs/guides/terminal-surfaces.md](./docs/guides/terminal-surfaces.md): tmux, VS Code terminal registry, and dry-run surfaces
+- [docs/guides/signal-wrappers.md](./docs/guides/signal-wrappers.md): versioned signal snapshots, wrapper scripts, and long-running-agent ack loops
 - [docs/reference/sample-waves.md](./docs/reference/sample-waves.md): showcase-first authored waves, including a high-fidelity repo-landed rollout example
 - [docs/plans/examples/wave-example-design-handoff.md](./docs/plans/examples/wave-example-design-handoff.md): optional design-steward example that hands a validated design packet to downstream implementation owners
 - [docs/plans/examples/wave-example-rollout-fidelity.md](./docs/plans/examples/wave-example-rollout-fidelity.md): concrete example of what good wave fidelity looks like for a narrow, closure-ready outcome

package/docs/README.md

@@ -36,7 +36,9 @@ The useful path is journey-first:
 - Drafting or revising waves:
   Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then use [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) as the operator runbook.
 - Adding an optional pre-implementation design steward:
-  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.8.5` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
+  Read [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then the standing prompt in [agents/wave-design-role.md](./agents/wave-design-role.md). The shipped `0.8.7` surface includes `role-design` plus `tui-design`, with docs-first design stewards by default and explicit hybrid design stewards when a wave also gives that same agent code ownership.
+- Want signal-driven automation or long-running watcher loops:
+  Read [guides/signal-wrappers.md](./guides/signal-wrappers.md). It covers the seeded `wave-status.sh` and `wave-watch.sh` wrappers, the versioned signal snapshot files, and the ack-loop contract behind `signal-hygiene`.
 - Adding a security review pass:
   Read [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) and the standing reviewer prompt in [agents/wave-security-role.md](./agents/wave-security-role.md).
 - Upgrading an existing repo:

package/docs/context7/bundles.json

@@ -13,33 +13,28 @@
       "description": "Node.js and TypeScript runtime docs for JavaScript service and tooling work.",
       "libraries": [
         {
-          "libraryName": "nodejs",
+          "libraryId": "/nodejs/node",
           "queryHint": "runtime APIs, child processes, streams, filesystem behavior, and process lifecycle"
         },
         {
-          "libraryName": "typescript",
+          "libraryId": "/microsoft/typescript",
           "queryHint": "types, declarations, module resolution, tsconfig, and compiler behavior"
         }
       ]
     },
     "planner-agentic": {
-      "description": "Repo-curated planning research published as a custom Context7 library for the agentic planner.",
-      "libraries": [
-        {
-          "libraryName": "wave-planner-agentic",
-          "queryHint": "wave planning best practices, maturity alignment, closure gates, proof surfaces, rollout evidence, and coordination failure prevention"
-        }
-      ]
+      "description": "Placeholder bundle for a repo-published planner corpus. Keep this empty until the planner corpus is published to Context7 and the exact libraryId is known.",
+      "libraries": []
     },
     "react-web": {
       "description": "React and Next.js docs for frontend work.",
       "libraries": [
         {
-          "libraryName": "react",
+          "libraryId": "/reactjs/react.dev",
           "queryHint": "components, hooks, rendering, forms, and data flow"
         },
         {
-          "libraryName": "nextjs",
+          "libraryId": "/websites/nextjs",
           "queryHint": "routing, server components, data fetching, and app router behavior"
         }
       ]
@@ -48,11 +43,11 @@
       "description": "Python backend docs for API and worker services.",
       "libraries": [
         {
-          "libraryName": "python",
+          "libraryId": "/websites/python_3",
           "queryHint": "language features, packaging, typing, and standard library behavior"
         },
         {
-          "libraryName": "fastapi",
+          "libraryId": "/fastapi/fastapi",
           "queryHint": "routing, request validation, dependency injection, and OpenAPI behavior"
         }
       ]
@@ -61,11 +56,15 @@
       "description": "Go service and workflow docs for backend work.",
       "libraries": [
         {
-          "libraryName": "golang",
-          "queryHint": "packages, testing, concurrency, errors, and module layout"
+          "libraryId": "/websites/go_dev_ref_spec",
+          "queryHint": "language syntax, testing, concurrency, errors, and module semantics"
+        },
+        {
+          "libraryId": "/websites/pkg_go_dev",
+          "queryHint": "standard packages, modules, package layout, and reference behavior"
         },
         {
-          "libraryName": "temporal",
+          "libraryId": "/temporalio/documentation",
           "queryHint": "workflow setup, activities, schedules, retries, and worker bootstrap"
         }
       ]
@@ -74,11 +73,11 @@
       "description": "Database and storage docs for persistence work.",
       "libraries": [
         {
-          "libraryName": "postgresql",
+          "libraryId": "/websites/postgresql_current",
           "queryHint": "schema changes, indexes, transactions, constraints, and query behavior"
         },
         {
-          "libraryName": "sqlite",
+          "libraryId": "/websites/sqlite_docs",
           "queryHint": "local persistence, fts, schema migration, and durability patterns"
         }
       ]
@@ -87,11 +86,11 @@
       "description": "Infrastructure and service-manager docs for deployment and operations work.",
       "libraries": [
         {
-          "libraryName": "docker",
+          "libraryId": "/docker/docs",
           "queryHint": "images, builds, volumes, networking, and runtime configuration"
         },
         {
-          "libraryName": "systemd",
+          "libraryId": "/websites/systemd_io",
           "queryHint": "units, dependencies, restart policies, readiness, and service management"
         }
       ]

package/docs/context7/planner-agent/README.md

@@ -13,7 +13,10 @@ Why it exists:
 Publish target:
 
 - bundle id: `planner-agentic`
-- library name: `wave-planner-agentic`
+- committed repo config should stay empty until the planner corpus is published
+  and Context7 returns an exact `libraryId`
+- once published, record that returned `libraryId` in
+  `docs/context7/bundles.json` instead of committing a guessed library name
 
 Refresh the copied corpus after updating the agent-context cache:
 

package/docs/guides/author-and-run-waves.md

@@ -47,6 +47,7 @@ When you review the generated wave, tighten the parts the planner cannot fully i
 - `cont-EVAL` targets when needed
 - security review expectations when needed
 - explicit `### Skills` only where defaults are not enough
+- `signal-hygiene` only when an agent is intentionally long-running and should wait for orchestrator-written signal changes instead of exiting after a one-shot pass
 
 If you want examples of denser hand-authored waves, read [docs/reference/sample-waves.md](../reference/sample-waves.md).
 
@@ -60,7 +61,7 @@ Good fits:
 - multi-owner waves where downstream implementers need the same decisions and assumptions
 - ambiguous tasks where open questions should become explicit before code owners fan out
 
-The starter contract in `0.8.5` is:
+The starter contract in `0.8.7` is:
 
 - import `docs/agents/wave-design-role.md`
 - own one packet such as `docs/plans/waves/design/wave-<n>-<agentId>.md`
@@ -72,6 +73,8 @@ When a wave includes one or more design agents, the runtime runs them before cod
 
 If a wave explicitly gives a design steward source-code ownership, that agent becomes a hybrid design steward. The runtime still runs its design pass first, then includes the same agent in the later implementation fan-out with normal proof obligations. Interactive `wave draft` scaffolds the docs-first default; use manual edits or an agentic planner payload when you want the hybrid path.
 
+For long-running non-design agents that should stay alive and react only to feedback or coordination changes, add `signal-hygiene` explicitly in `### Skills`. That skill is not for normal one-shot implementation work.
+
 ## 3. Choose The Execution Posture
 
 Every wave should be authored with an explicit operating posture in mind:

package/docs/guides/planner.md

@@ -6,7 +6,7 @@ If you want the full author-to-launch workflow, start with [author-and-run-waves
 
 It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
 
-The published `0.8.5` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
+The published `0.8.7` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
 
 ## What Ships Today
 
@@ -90,6 +90,8 @@ The planner agent reads repo-local planning sources directly, and it can also
 prefetch a planner-specific Context7 bundle when
 `planner.agentic.context7Bundle` points at a published library. The tracked
 source corpus for that library lives under `docs/context7/planner-agent/`.
+The starter repo keeps that bundle as a placeholder until the planner corpus is
+actually published and the exact `libraryId` is known.
 
 Supported templates today:
 

package/docs/guides/signal-wrappers.md

@@ -0,0 +1,165 @@
+# Signal Wrappers And Long-Running Wake Loops
+
+Use this guide when you want shell-friendly monitoring, external automation hooks, or intentionally long-running agents that should wake only when the orchestrator publishes a new signal version.
+
+If you want the broader tmux or VS Code operator flow, read [terminal-surfaces.md](./terminal-surfaces.md). This page stays focused on the signal snapshots, wrapper scripts, and ack-loop contract.
+
+## What The Runtime Writes
+
+Wave now publishes versioned signal snapshots under:
+
+- `.tmp/<lane>-wave-launcher/signals/wave-<n>.json`
+  Wave-level signal for the whole wave.
+- `.tmp/<lane>-wave-launcher/signals/wave-<n>/<agentId>.json`
+  Per-agent signal state.
+- `.tmp/<lane>-wave-launcher/signals/wave-<n>/acks/<agentId>.json`
+  Per-agent acknowledgement file written by a long-running watcher after it observes a new signal version.
+
+The resident orchestrator uses the same pattern with `resident-orchestrator` as the agent id.
+
+Signal snapshots are derived projections, not canonical decision state. They are machine-friendly wake surfaces built from `wave control status --json`.
+
+## Signal Kinds
+
+The shipped signal vocabulary is:
+
+- `stable`
+- `waiting`
+- `feedback-requested`
+- `feedback-answered`
+- `coordination-action`
+- `resume-ready`
+- `completed`
+- `failed`
+
+`completed` and `failed` are terminal. Long-running watchers should stop waiting once either one appears.
+
+## Wrapper Scripts
+
+Starter repos now include two thin helper scripts:
+
+- `scripts/wave-status.sh`
+- `scripts/wave-watch.sh`
+
+They read `wave control status --json`. They do not recompute status independently.
+
+### `wave-status.sh`
+
+Examples:
+
+```bash
+scripts/wave-status.sh --lane main --wave 3
+scripts/wave-status.sh --lane main --wave 3 --agent A1
+scripts/wave-status.sh --lane main --wave 3 --agent A1 --json
+```
+
+Exit codes:
+
+- `0`
+  Terminal success (`signal=completed`)
+- `10`
+  Still active or waiting (`stable`, `waiting`, `feedback-answered`, `coordination-action`, `resume-ready`)
+- `20`
+  Input required (`signal=feedback-requested`)
+- `40`
+  Terminal failure (`signal=failed`)
+
+The printed machine line includes `signal`, `phase`, `status`, `version`, `blocking`, and `should_wake`.
+
+### `wave-watch.sh`
+
+Examples:
+
+```bash
+scripts/wave-watch.sh --lane main --wave 3 --agent A1 --follow
+scripts/wave-watch.sh --lane main --wave 3 --agent A1 --until-change --refresh-ms 500
+```
+
+Modes:
+
+- `--follow`
+  Keep polling until the signal becomes terminal or input-required.
+- `--until-change`
+  Exit as soon as the watched signal version changes.
+
+Exit codes:
+
+- `0`
+  Terminal success
+- `20`
+  Input required
+- `30`
+  The watched signal version changed, but the wave is still active
+- `40`
+  Terminal failure
+
+Use `--until-change` when an outer supervisor or CI job should re-enter only after a new signal is published.
+
+## Long-Running Agents
+
+For non-resident agents, opt in explicitly with:
+
+```md
+### Skills
+
+- signal-hygiene
+```
+
+That skill is only for intentionally long-running agents. Do not attach it to normal one-shot implementation agents.
+
+When `signal-hygiene` is active, the runtime injects two prompt-visible paths:
+
+- the signal-state JSON path
+- the signal-ack JSON path
+
+The watcher loop is:
+
+1. Read the signal state.
+2. Compare its `version` with the version already recorded in the ack file.
+3. If the version did not change, stay idle.
+4. If the version increased, write the ack file immediately.
+5. Re-read the inbox, shared summary, message board, and any referenced artifacts.
+6. Act once for that version.
+7. Stop entirely when the signal becomes `completed` or `failed`.
+
+Ack payload shape:
+
+```json
+{
+  "agentId": "A1",
+  "version": 4,
+  "signal": "coordination-action",
+  "observedAt": "2026-03-25T19:00:00.000Z"
+}
+```
+
+## Resident Orchestrator Behavior
+
+The resident orchestrator does not need the `signal-hygiene` skill. It always receives the same signal-state and ack-path contract when `--resident-orchestrator` is enabled.
+
+That lets the launcher know whether the resident monitor actually observed a reroute, feedback answer, or terminal state change.
+
+## External Automation Pattern
+
+Typical shell loop:
+
+```bash
+while true; do
+  scripts/wave-watch.sh --lane main --wave 3 --agent A1 --until-change --refresh-ms 500
+  code=$?
+  if [ "$code" -eq 0 ]; then
+    echo "wave completed"
+    break
+  fi
+  if [ "$code" -eq 20 ]; then
+    echo "human input required"
+    break
+  fi
+  if [ "$code" -eq 40 ]; then
+    echo "wave failed"
+    break
+  fi
+done
+```
+
+Use `wave control status --json` directly when you need the full structured payload. Use the wrapper scripts when you want stable exit codes and a single machine-readable line.

package/docs/guides/terminal-surfaces.md

@@ -47,6 +47,8 @@ By default the launcher can start per-wave dashboard sessions in tmux.
 
 Wave now maintains stable tmux attach targets for both the current-wave dashboard and the global dashboard on the lane socket.
 
+Wave-agent sessions and the resident orchestrator now also use stable per-wave tmux session names. A relaunch reuses the same session identity for that wave instead of creating a new run-tagged session name each time, which reduces stale session buildup after launcher crashes or interrupted retries.
+
 Use:
 
 ```bash
@@ -78,6 +80,19 @@ Important flags:
 - Pair `--keep-sessions` with incident review or deep debugging, not as a default steady-state mode.
 - Pair `--no-dashboard` with scripted dry-runs or when the board and summaries are sufficient.
 
+## Operator Wrappers
+
+Starter repos now include two thin helper scripts:
+
+- `scripts/wave-status.sh`
+  Reads `wave control status --json`, prints a single machine-friendly line, and exits `0` for completed, `10` for waiting/running, `20` for input-required, and `40` for failed.
+- `scripts/wave-watch.sh`
+  Polls the same status JSON until the watched signal version changes. `--until-change` exits `30` when the signal changed but the wave is still active, and both follow mode and until-change mode terminate immediately with `40` on failed terminal signals.
+
+Both wrappers are convenience readers only. The canonical surface is the versioned signal projection under `.tmp/<lane>-wave-launcher/signals/`.
+
+For the full wrapper contract, long-running-agent ack loop, and external automation patterns, read [signal-wrappers.md](./signal-wrappers.md).
+
 ## Suggested Defaults
 
 - Local development:

package/docs/plans/context7-wave-orchestrator.md

@@ -34,11 +34,12 @@ pnpm context7:api-check
 ```
 
 4. Review [docs/context7/bundles.json](../context7/bundles.json) and trim it to the external libraries your repository actually uses.
+5. Prefer exact `libraryId` values. Use `libraryName` only during one-off discovery, then replace it with the pinned id returned by Context7 before committing the bundle.
 
 ## Planner Bundle
 
-The shipped bundle index includes `planner-agentic`, which expects a published
-Context7 library named `wave-planner-agentic`.
+The shipped bundle index includes `planner-agentic`, but it is intentionally a
+local-only placeholder by default.
 
 The source files for that library live under `docs/context7/planner-agent/`.
 Refresh that folder from the ignored agent-context cache with:
@@ -47,8 +48,8 @@ Refresh that folder from the ignored agent-context cache with:
 pnpm research:sync-planner-context7
 ```
 
-After you publish the folder to Context7, the agentic planner will prefetch that
-bundle through `planner.agentic.context7Bundle`.
+After you publish the folder to Context7, replace the placeholder bundle entry
+with the exact published `libraryId`. Do not commit a guessed `libraryName`.
 
 ## Resolution Order
 
@@ -59,7 +60,8 @@ bundle through `planner.agentic.context7Bundle`.
 
 ## Bundle Authoring
 
-Each bundle should be small and task-shaped. A bundle entry can name libraries by `libraryName` and optionally add a `queryHint` to keep fetched docs focused.
+Each bundle should be small and task-shaped. Prefer exact `libraryId` values and
+add a `queryHint` to keep fetched docs focused.
 
 Example:
 
@@ -70,11 +72,11 @@ Example:
       "description": "Node.js and TypeScript runtime docs.",
       "libraries": [
         {
-          "libraryName": "nodejs",
+          "libraryId": "/nodejs/node",
           "queryHint": "child processes, streams, filesystem, process lifecycle"
         },
         {
-          "libraryName": "typescript",
+          "libraryId": "/microsoft/typescript",
           "queryHint": "module resolution, declarations, compiler behavior"
         }
       ]
@@ -105,6 +107,20 @@ Agent-level override:
 - query: "TypeScript declarations and module resolution"
 ````
 
+## Making Attachment Explicit
+
+If you want Context7 attachment to be reviewable instead of implied, make all of
+these explicit:
+
+1. The wave or agent selects a concrete bundle id in `## Context7 defaults` or
+   `### Context7`.
+2. `docs/context7/bundles.json` pins the bundle's libraries by exact
+   `libraryId`, not a guessed `libraryName`.
+3. Placeholder bundles stay empty until the real published `libraryId` exists.
+4. `pnpm context7:api-check` succeeds against the committed ids.
+5. The launcher log shows `Context7 bundle <bundle-id> attached (...)` for the
+   run, or a fail-open warning if the API was unavailable.
+
 ## Injection
 
 When a bundle is active, the launcher injects:
@@ -150,3 +166,4 @@ Those inbox artifacts are repository-state summaries. Context7 stays reserved fo
 - Do not use Context7 for repository architecture, plan decisions, ownership rules, or internal contracts.
 - Prefer one active backend family in a bundle instead of mixing competing frameworks.
 - Keep queries specific enough that the prefetched block stays small and useful.
+- Run `pnpm context7:api-check` after editing bundle ids to verify every pinned library still resolves and returns promptable context.

package/docs/plans/current-state.md

@@ -1,6 +1,6 @@
 # Current State
 
-- The published package is `0.8.5`, and that release now includes the optional pre-implementation `design` worker role plus the `role-design` and `tui-design` starter bundles.
+- The published package is `0.8.7`, and that release now includes the optional pre-implementation `design` worker role, the `role-design`, `tui-design`, and `signal-hygiene` starter bundles, plus the seeded signal-wrapper scripts for long-running-agent and operator wait loops.
 - The canonical shipped runtime architecture is documented in `docs/plans/end-state-architecture.md`; historical cutover notes remain in `docs/plans/architecture-hardening-migration.md`.
 - The repository contains the published `@chllming/wave-orchestration` package plus the starter scaffold used by `wave init`.
 - The runtime is package-first and non-destructive for adopting repos: `wave init --adopt-existing` records existing repo-owned plans, waves, prompts, and config without overwriting them, and `wave upgrade` writes only `.wave/install-state.json` plus `.wave/upgrade-history/`.
@@ -26,12 +26,13 @@
   - lane config can attach skills by base, role, runtime, and deploy kind
   - wave agents can add explicit `### Skills`
   - runtime projections are generated for Codex, Claude, OpenCode, and local execution
-  - the starter surface includes `skills/role-design/`, `skills/tui-design/`, `roles.designRolePromptPath`, and `executors.profiles.design-pass`
+  - the starter surface includes `skills/role-design/`, `skills/tui-design/`, `skills/signal-hygiene/`, `roles.designRolePromptPath`, and `executors.profiles.design-pass`
 - The runtime now includes:
   - a canonical authority set built from wave definitions, coordination JSONL logs, and control-plane JSONL events
   - immutable attempt-scoped result envelopes for structured role outcomes under `.tmp/<lane>-wave-launcher/results/wave-<n>/attempt-<a>/<agent>.json`
   - a generated markdown board projection
   - compiled shared summaries and per-agent inboxes
+  - canonical versioned signal projections under `.tmp/<lane>-wave-launcher/signals/` for waves, per-agent wake state, and resident-orchestrator acknowledgement loops
   - active live-wave orchestration refresh that keeps summaries, inboxes, clarification triage, and dashboard coordination metrics current while agents are still running
   - a per-wave ledger
   - docs queues
@@ -43,8 +44,9 @@
   - orchestrator-first clarification triage plus human escalation artifacts
   - answered human-feedback responses that reconcile canonical coordination state, helper assignments, and safe continuation intent even when the launcher is no longer active
   - optional `--resident-orchestrator` support for a long-running, non-owning orchestrator session during live waves
+  - seeded operator wrappers `scripts/wave-status.sh` and `scripts/wave-watch.sh` that expose machine-friendly wait, completion, failure, and input-required status by reading `wave control status --json`
   - persisted relaunch plans under `.tmp/<lane>-wave-launcher/status/` so targeted retry intent can survive a launcher restart
-  - a canonical control-plane event log under `.tmp/<lane>-wave-launcher/control-plane/` that records operator tasks, rerun requests, proof bundles, contradictions, facts, human-input workflow, and observed `wave_run`, `attempt`, and `agent_run` lifecycle events as append-only JSONL; `wave control` materializes state from this log
+  - a canonical control-plane event log under `.tmp/<lane>-wave-launcher/control-plane/` that records operator tasks, rerun requests, proof bundles, contradictions, facts, human-input workflow, observed `wave_run`, `attempt`, and `agent_run` lifecycle events, plus `wave_signal` and `agent_signal` update events as append-only JSONL; `wave control` materializes state from this log
   - operator-applied retry overrides projected to `.tmp/<lane>-wave-launcher/control/` for compatibility with selected reruns, explicit reuse selectors, reuse clearing or preservation, and explicit resume targets
   - authoritative proof registries projected to `.tmp/<lane>-wave-launcher/proof/` for compatibility, while preserving proof bundle lifecycle state so revoked or superseded operator evidence cannot keep satisfying closure
   - optional Wave Control telemetry under `.tmp/<lane>-wave-launcher/control-plane/telemetry/` for local-first, best-effort reporting to the Railway-hosted analysis plane
@@ -79,6 +81,8 @@
   - helper assignments are written into coordination state, the ledger, summaries, and traces
   - helper assignments remain blocking until the linked follow-up resolves
 - Waves with a `design` worker role now run that design pass before code-owning implementation starts; implementation resumes only after every design packet is `ready-for-implementation`.
+- Long-running non-resident agents can opt into `signal-hygiene` through explicit `### Skills`; that skill makes them wait on signal-version changes, acknowledge a new version through an ack file, and only then resume work.
+- Terminal signal state now dominates stale answered feedback or coordination wakeups, so `completed` and `failed` actually stop long-running watcher loops instead of leaving them on a non-terminal signal.
 - Closure now runs in staged order through the wave's effective closure roles: implementation and proof, then optional `cont-EVAL`, then optional security review, then integration, then documentation, then `cont-QA`. Starter defaults remain `E0`, security reviewer, `A8`, `A9`, and `A0` when a wave does not override them.
 - `E0` is hybrid: planner-generated waves keep it report-only, while hand-authored waves may assign explicit tuning files and thereby make `E0` participate in implementation proof gating.
 - Live closure is strict: `cont-EVAL` must prove the declared eval contract with exact target and benchmark ids, and `cont-QA` must provide both final verdict and final gate artifacts. Legacy evaluator-era shapes remain replay-only compatibility inputs.