@chllming/wave-orchestration 0.8.9 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 ## Unreleased
 
+## 0.9.1 - 2026-03-29
+
+### Added
+
+- A dedicated sandbox setup guide at `docs/guides/sandboxed-environments.md` covering LEAPclaw/OpenClaw-style short-lived exec sandboxes, Nemoshell, and Docker or containerized operator setups.
+- Starter-surface and install coverage for the renamed recommendations guide `docs/guides/recommendations-0.9.1.md`, plus seeded docs that now point fresh workspaces at the sandbox-safe submit or supervise path.
+
+### Changed
+
+- Live agent execution now defaults to detached process runners instead of per-agent tmux execution sessions. Tmux remains an optional dashboard and operator projection surface only, which reduces session churn and lowers memory pressure during wider fan-outs.
+- The sandbox-facing runtime path is now `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach`, with read-side reconciliation and log-follow attach behavior designed for short-lived clients and long-running daemon ownership.
+- README, migration guidance, current-state notes, coordination docs, runtime-config docs, package publishing docs, install fixtures, and the versioned recommendations guide now all point at the `0.9.1` surface.
+
+### Fixed And Hardened
+
+- Supervisor recovery now relies on run-owned terminal artifacts and finalized progress instead of lane-global completion history, preventing false completion during reruns and improving read-side reconciliation after daemon loss.
+- Multi-wave recovery and terminal attribution now preserve the correct remaining wave range and final active wave, even when launcher progress metadata is partial or missing.
+- Ordinary runs, closure runs, and resident orchestrator runs now all preserve process-runtime metadata for timeout, cleanup, and degraded-run handling, and process-backed resident orchestrators are terminated correctly during final cleanup.
+- Rate-limit retry detection is now attempt-local, closure-role overlap is rejected earlier, custom security-review role paths classify consistently, and explicit terminal-surface choices no longer depend on argv ordering.
+- Agent and launcher execution paths now behave better in constrained sandboxes by avoiding tmux-backed agent execution, preserving configured Codex sandbox defaults, and demoting tmux loss from a liveness authority to projection-only telemetry.
+
+### Testing And Validation
+
+- `pnpm test`
+- `pnpm test -- test/wave-orchestrator/release-surface.test.ts test/wave-orchestrator/install.test.ts test/wave-orchestrator/supervisor-cli.test.ts`
+- `node scripts/wave.mjs doctor --json`
+- `node scripts/wave.mjs launch --lane main --dry-run --no-dashboard`
+
+## 0.9.0 - 2026-03-28
+
+### Added
+
+- First-class monorepo project support through `defaultProject` and `projects.<projectId>` in `wave.config.json`, including project-owned lane roots, docs roots, planner defaults, and Wave Control identity.
+- A dedicated setup guide at `docs/guides/monorepo-projects.md` that documents explicit project configuration, project-scoped state paths, cross-project dependency wiring, and telemetry defaults.
+- Project-aware regression coverage for shared paths, coordination telemetry, dashboard parsing, and release-surface docs alignment.
+
+### Changed
+
+- Lane-scoped CLI surfaces now accept `--project`, including `launch`, `autonomous`, `dashboard`, `project`, `draft`, `adhoc`, `control`, `coord`, `feedback`, `dep`, `retry`, `proof`, and benchmark commands.
+- Planner defaults are now project-scoped: the implicit default project keeps `.wave/project-profile.json`, while explicit monorepo projects use `.wave/projects/<projectId>/project-profile.json`.
+- Ad-hoc runs, launcher state, tmux naming, dependency tickets, and benchmark identity are now project-aware, so duplicate lane names can coexist across monorepo projects without state collisions.
+- The shipped release surface now points consistently at `0.9.0`, including the README, current-state notes, migration guide, coordination docs, runtime-config docs, release manifest, tracked install-state fixtures, and the versioned recommendations guide `docs/guides/recommendations-0.9.0.md`.
+
+### Fixed And Hardened
+
+- Coordination telemetry, benchmark telemetry, and dashboard attach flows now preserve the selected project instead of falling back to the implicit default project.
+- Package defaults now report metadata to Wave Control through `https://wave-control.up.railway.app/api/v1` with `reportMode: "metadata-only"`, while preserving explicit repo and one-off operator opt-out paths.
+- Documentation and examples now describe the shipped project-aware runtime rather than the old lane-only or unscoped ad-hoc layout.
+
+### Testing And Validation
+
+- `pnpm test -- test/wave-orchestrator/release-surface.test.ts test/wave-orchestrator/shared.test.ts test/wave-orchestrator/dashboard-renderer.test.ts test/wave-orchestrator/coordination-store.test.ts`
+- `pnpm test`
+- `node scripts/wave.mjs doctor --json`
+- `node scripts/wave.mjs launch --lane main --dry-run --no-dashboard`
+- `node scripts/wave.mjs dashboard --help`
+
 ## 0.8.9 - 2026-03-27
 
 ### Changed

package/README.md

@@ -2,6 +2,10 @@
 
 Wave Orchestration is my framework for "vibe-coding." It keeps the speed of agentic coding, but makes the runtime, coordination, and context model explicit enough to inspect, replay, and improve.
 
+Wave is meant to be operated through an agent that uses the Wave runtime, not as a command-first workflow where a human manually drives every step from the shell.
+
+This package also ships with my personal Wave Control endpoint enabled by default. A repo using the packaged defaults will emit project, lane, wave, run, proof, and benchmark metadata to `https://wave-control.up.railway.app/api/v1` unless you actively opt out.
+
 The framework does three things:
 
 1. It abstracts the agent runtime away without flattening everything to the lowest common denominator. The same waves, skills, planning, evaluation, proof, and traces can run across Claude, Codex, and OpenCode while still preserving runtime-native features through executor adapters.
@@ -51,7 +55,7 @@ The framework does three things:
 - `wave-state-reducer.mjs`
   Rebuilds deterministic wave state from canonical inputs for live queries and replay.
 - `session-supervisor.mjs`
-  Owns launches, waits, tmux sessions, lock handling, resident orchestrator sessions, and observed `wave_run`, `attempt`, and `agent_run` lifecycle facts.
+  Owns detached agent launches, waits, dashboard tmux sessions, lock handling, resident orchestrator sessions, and observed `wave_run`, `attempt`, and `agent_run` lifecycle facts.
 - `projection-writer.mjs`
   Persists dashboards, traces, summaries, inboxes, board projections, assignment/dependency snapshots, ledgers, docs queues, and integration/security summaries.
 
@@ -103,38 +107,105 @@ Wave is built to mitigate those failures with a canonical authority set, generat
 
 Current release:
 
-- `@chllming/wave-orchestration@0.8.9`
-- Release tag: [`v0.8.9`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.8.9)
+- `@chllming/wave-orchestration@0.9.1`
+- Release tag: [`v0.9.1`](https://github.com/chllming/agent-wave-orchestrator/releases/tag/v0.9.1)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.8.9`:
+Highlights in `0.9.1`:
 
-- Reducer snapshots now preserve design packet report paths when they rebuild summaries from result envelopes, so successful design passes no longer get replayed as `missing-design-packet`.
-- Launcher transitions after design-only passes now stop on the real design-gate failure and record a design-specific blocker instead of falling through to a misleading downstream implementation `missing-result-envelope` error.
-- Trace bundle summary reconstruction now also preserves design packet report paths, so copied summary artifacts stay aligned when a trace has to rebuild a design summary from logs.
-- Release docs, current-state notes, migration guidance, publishing instructions, the packaged operator recommendations guide, and the tracked install-state fixtures now all point at the `0.8.9` surface.
+- Live agent execution now uses detached process runners by default, which reduces tmux churn and memory pressure during wider orchestration bursts. Tmux is now optional and dashboard-only.
+- The sandbox-safe runtime path is now `wave submit`, `wave supervise`, `wave status`, `wave wait`, and `wave attach`, which behaves better under short-lived exec clients such as LEAPclaw, OpenClaw, and Nemoshell.
+- Supervisor recovery, launcher progress journaling, and exact-context reads are now hardier for multi-wave runs, reruns, and daemon/client loss in containerized or sandboxed environments.
+- Release docs, migration guidance, sandbox setup guides, the versioned recommendations guide, the manifest, and the tracked install-state fixtures now all point at the `0.9.1` surface.
 
 Requirements:
 
 - Node.js 22+
 - `pnpm`
-- `tmux` on `PATH` for dashboarded runs
+- optional: `tmux` on `PATH` for dashboarded runs
 - at least one executor on `PATH`: `codex`, `claude`, or `opencode`
 - optional: `CONTEXT7_API_KEY` for launcher-side prefetch
 - optional: `WAVE_CONTROL_AUTH_TOKEN` for remote Wave Control reporting
 
+Telemetry defaults:
+
+- packaged default endpoint: `https://wave-control.up.railway.app/api/v1`
+- packaged default mode: `metadata-only`
+- default identity fields include `projectId`, `lane`, `wave`, `runKind`, and related benchmark ids
+- opt out explicitly with `waveControl.enabled: false`, `waveControl.reportMode: "disabled"`, or `wave launch --no-telemetry`
+
+## Recommended Setup
+
+The easiest way to set up Wave in any repo is:
+
+1. install the package
+2. point a coding agent at the repo
+3. paste one setup prompt
+
+Use direct CLI commands as a manual fallback, debugging surface, or validation aid. The intended interface is an agent using Wave, not a human memorizing the full command set.
+
 Install into another repo:
 
 ```bash
 pnpm add -D @chllming/wave-orchestration
-pnpm exec wave init
-pnpm exec wave doctor
-pnpm exec wave launch --lane main --dry-run --no-dashboard
-pnpm exec wave coord show --lane main --wave 0 --dry-run --json
 ```
 
-If the repo already has Wave config, plans, or waves you want to keep:
+Then give your coding agent this copy-paste prompt:
+
+```text
+Set up and operate Wave Orchestration in this repository.
+
+Start by inspecting the repo before changing anything.
+
+Your job:
+- determine whether this should be a fresh setup, an adopt-existing setup, or a migration from an older Wave version
+- understand the repo well enough to recommend a Wave shape instead of guessing
+- decide whether this repo should stay single-project or use monorepo projects with `defaultProject` plus `projects.<projectId>`
+- explain the default telemetry behavior before enabling anything silently:
+  - Wave sends project, lane, wave, run, proof, and benchmark metadata to `https://wave-control.up.railway.app/api/v1` by default unless the repo explicitly opts out
+  - if this repo should opt out, say exactly how and why
+- decide the right proof and closure posture for this repo:
+  - what should count as proof
+  - whether `cont-EVAL`, security review, stronger closure roles, or stricter proof artifacts are needed
+  - whether non-proof follow-up should remain blocking or be marked soft, stale, or advisory
+- configure Wave for this repo
+- build detailed waves, not vague stubs
+- validate the setup with the normal Wave checks
+- summarize the resulting layout, assumptions, risks, and next recommended waves
+
+Rules:
+- inspect first, then change files
+- prefer adopt-existing over destructive rewrites when Wave files or plans already exist
+- ask only the missing high-impact product questions that cannot be inferred from the repo
+- treat commands as implementation tools, not the user-facing interface
+
+Required execution flow:
+1. inspect the repo and determine fresh setup vs adopt-existing vs migration
+2. install and initialize Wave appropriately
+3. choose single-project vs monorepo project structure
+4. configure telemetry intentionally and explain the default
+5. define proof expectations and closure roles
+6. draft or refine detailed waves
+7. run Wave validation
+8. report what you changed and what the human should review next
+
+Validation to run:
+- `pnpm exec wave doctor --json`
+- `pnpm exec wave launch --lane main --dry-run --no-dashboard`
+- `pnpm exec wave control status --lane main --wave 0 --json` if wave 0 exists
+
+Useful docs:
+- `README.md`
+- `docs/plans/migration.md`
+- `docs/guides/sandboxed-environments.md`
+- `docs/guides/monorepo-projects.md`
+- `docs/guides/planner.md`
+- `docs/reference/runtime-config/README.md`
+- `docs/reference/wave-control.md`
+```
+
+If the repo already has Wave config, plans, or waves you want to keep, the agent should generally choose the adopt-existing path:
 
 ```bash
 pnpm exec wave init --adopt-existing
@@ -142,6 +213,10 @@ pnpm exec wave init --adopt-existing
 
 Fresh init also seeds a starter `skills/` library plus `docs/evals/benchmark-catalog.json`. The launcher projects those skill bundles into Codex, Claude, OpenCode, and local executor overlays after the final runtime for each agent is resolved, and waves that include `cont-EVAL` can declare `## Eval targets` against that catalog.
 
+For monorepos, `wave.config.json` can now declare `defaultProject` plus `projects.<projectId>`. Each project owns its own lanes, docs root, planner defaults, runtime overrides, and Wave Control identity, so multiple project/lane/wave tracks can run from one checkout without colliding in launcher state or tmux session names.
+
+Use [docs/guides/monorepo-projects.md](./docs/guides/monorepo-projects.md) for the full setup flow, state-path layout, cross-project dependency examples, and telemetry defaults or opt-out rules.
+
 The starter surface includes:
 
 - `docs/agents/wave-design-role.md`
@@ -157,7 +232,41 @@ If a non-resident agent should stay alive and react only to orchestrator-written
 
 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
+## Sandboxed And Containerized Setups
+
+If Wave is running inside LEAPclaw, OpenClaw, Nemoshell, Docker, or another environment where the client shell is short-lived, do not bind the whole run to one blocking `wave launch` or `wave autonomous` process.
+
+Use the async supervisor path instead:
+
+```bash
+# Long-lived daemon
+pnpm exec wave supervise --project backend --lane main
+
+# Short-lived client
+runId=$(pnpm exec wave submit \
+  --project backend \
+  --lane main \
+  --start-wave 2 \
+  --end-wave 2 \
+  --no-dashboard \
+  --json | jq -r .runId)
+
+pnpm exec wave status --run-id "$runId" --project backend --lane main --json
+pnpm exec wave wait --run-id "$runId" --project backend --lane main --timeout-seconds 300 --json
+```
+
+Practical defaults for constrained environments:
+
+- set the Codex sandbox mode in `wave.config.json` instead of relying on per-command overrides
+- keep `tmux` optional and use `--no-dashboard` when you do not need a live dashboard
+- preserve `.tmp/` and `.wave/` across container restarts
+- use `wave attach --agent <id>` for log-follow attach when there is no live interactive terminal session
+
+For the full setup guidance, read [docs/guides/sandboxed-environments.md](./docs/guides/sandboxed-environments.md).
+
+## Manual Commands
+
+These commands are still useful when you want to validate, debug, or inspect the runtime directly. They are not the recommended first-touch onboarding path.
 
 ```bash
 # Save project defaults and draft a new wave
@@ -165,17 +274,23 @@ pnpm exec wave project setup
 pnpm exec wave draft --wave 1 --template implementation
 
 # Run one wave with a real executor
-pnpm exec wave launch --lane main --start-wave 0 --end-wave 0 --executor codex --codex-sandbox danger-full-access
+pnpm exec wave launch --lane main --start-wave 0 --end-wave 0 --executor codex
 
 # Disable Wave Control reporting for a single launcher run
 pnpm exec wave launch --lane main --no-telemetry
 
+# Target a specific monorepo project
+pnpm exec wave launch --project backend --lane main --dry-run --no-dashboard
+
 # Inspect operator surfaces
 pnpm exec wave feedback list --lane main --pending
 pnpm exec wave dep show --lane main --wave 0 --json
 
-# Run autonomous mode after the wave set is stable
-pnpm exec wave autonomous --lane main --executor codex --codex-sandbox danger-full-access
+# Submit a sandbox-safe run from a short-lived client
+pnpm exec wave submit --project backend --lane main --start-wave 2 --end-wave 2 --no-dashboard --json
+
+# Run autonomous mode only when the client shell can stay alive for the full run
+pnpm exec wave autonomous --lane main --executor codex
 
 # Pull the latest published package and record the workspace upgrade
 pnpm exec wave self-update
@@ -228,6 +343,7 @@ codex mcp list
 - [docs/concepts/context7-vs-skills.md](./docs/concepts/context7-vs-skills.md): compiled context, external truth, and repo-owned operating knowledge
 - [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/sandboxed-environments.md](./docs/guides/sandboxed-environments.md): recommended setup for LEAPclaw, OpenClaw, Nemoshell, Docker, and other short-lived exec environments
 - [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
@@ -240,6 +356,7 @@ codex mcp list
 - [docs/plans/context7-wave-orchestrator.md](./docs/plans/context7-wave-orchestrator.md): Context7 setup and bundle authoring
 - [docs/reference/runtime-config/README.md](./docs/reference/runtime-config/README.md): executor, runtime, and skill-projection configuration
 - [docs/reference/wave-control.md](./docs/reference/wave-control.md): local-first telemetry contract and Railway control-plane model
+- [docs/reference/package-publishing-flow.md](./docs/reference/package-publishing-flow.md): end-to-end package publishing flow, workflows, and lifecycle scripts
 - [docs/reference/proof-metrics.md](./docs/reference/proof-metrics.md): README failure cases mapped to concrete telemetry and benchmark evidence
 - [docs/reference/skills.md](./docs/reference/skills.md): skill bundle format, resolution order, and runtime projection
 - [docs/research/coordination-failure-review.md](./docs/research/coordination-failure-review.md): MAS failure modes from the research and how Wave responds

package/docs/README.md

@@ -35,16 +35,22 @@ The useful path is journey-first:
   Read [concepts/context7-vs-skills.md](./concepts/context7-vs-skills.md) for the compiled-context model: shared summary, inboxes, project defaults, skills, Context7, and runtime overlays.
 - 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.
+- Setting up multiple projects in one monorepo:
+  Read [guides/monorepo-projects.md](./guides/monorepo-projects.md) for `defaultProject`, `projects.<projectId>`, project-scoped state paths, and telemetry defaults.
 - 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.9` 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.9.1` 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.
+- Running in LEAPclaw, OpenClaw, Nemoshell, Docker, or another short-lived sandbox:
+  Read [guides/sandboxed-environments.md](./guides/sandboxed-environments.md) first for the submit or supervise pattern, persistent-state expectations, and dashboard guidance, then use [plans/sandbox-end-state-architecture.md](./plans/sandbox-end-state-architecture.md) for the deeper runtime design.
 - 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:
   Read [plans/migration.md](./plans/migration.md), then review the release notes in [../CHANGELOG.md](../CHANGELOG.md) before running `pnpm exec wave upgrade`.
-- Want the practical `0.8.9` operating stance:
-  Read [guides/recommendations-0.8.9.md](./guides/recommendations-0.8.9.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
+- Publishing the package:
+  Read [reference/package-publishing-flow.md](./reference/package-publishing-flow.md) for the end-to-end release path, the GitHub publish workflows, the lifecycle scripts, and the verification or repair flow.
+- Want the practical `0.9.1` operating stance:
+  Read [guides/recommendations-0.9.1.md](./guides/recommendations-0.9.1.md) for the recommended default around relaxed blocker states, advisory turn budgets, and targeted recovery.
 - Want the concrete runtime module map:
   Read [plans/end-state-architecture.md](./plans/end-state-architecture.md) for the engine-by-engine architecture and artifact ownership model.
 - Want the CLI surface map: