@chllming/wave-orchestration 0.8.5 → 0.8.6

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 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.6`
+- Release tag: [`v0.8.6`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.6)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.5`:
+Highlights in `0.8.6`:
 
-- 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 the current migration guide now covers the new signal-wrapper model on top of that design-first runtime.
+- Release docs, current-state notes, and publishing instructions now point at the `0.8.6` 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.6` 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.6` 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.6` 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

@@ -78,6 +78,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.6`, 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.

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.6` 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.6`.
 
 This example demonstrates the docs-first design-steward path where a design packet is published before code-owning implementation begins.