@chllming/wave-orchestration 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.6.3 - 2026-03-22
+
+- Added a best-effort npmjs update notice on `wave launch`, `wave autonomous`, and `wave adhoc run`, with cached lookup state under `.wave/package-update-check.json` and opt-out via `WAVE_SKIP_UPDATE_CHECK=1`.
+- Added `wave self-update`, which detects the workspace package manager, updates `@chllming/wave-orchestration`, prints the changelog delta since the recorded install, and then runs `wave upgrade`.
+- Suppressed duplicate notices for nested launcher calls so autonomous and ad-hoc runs announce at most once, while keeping JSON-oriented stdout surfaces clean by emitting notices on stderr.
+- Documented the new update flow and added regression coverage for notice caching, package-manager-aware self-update, and nested-launch suppression.
+
+## 0.6.2 - 2026-03-22
+
+- Added first-class `claude.effort` support across config profiles, lane overrides, and per-agent `### Executor` blocks, and now emit `--effort` in Claude launch previews and live runs.
+- Clarified operator runtime visibility with additive `launch-preview.json` `limits` metadata, including explicit known turn ceilings for Claude/OpenCode and explicit Codex opacity when Wave does not emit a turn-limit flag.
+- Clarified dashboard and terminal UX: global wave counts now distinguish done, active, pending, and failed agents; the current-wave dashboard keeps a stable terminal name; and TTY dashboards use simple color cues for faster scanning.
+- Pruned stale dry-run executor preview directories when wave agent sets shrink, so manual inspection of `.tmp/.../dry-run/executors/` matches the current manifest.
+- Preserved already-landed implementation slices for shared promoted components by retrying only the sibling owners that still owe closure proof instead of blindly replaying the landed owner.
+- Added release-surface alignment regression coverage and updated the shipped docs so README, runtime-config references, changelog, and release metadata match the `0.6.2` package surface.
+
 ## 0.6.1 - 2026-03-22
 
 - Published the post-merge `main` source as `0.6.1` so the default branch, tagged source, and package docs all agree on the current release.

package/README.md

@@ -1,48 +1,90 @@
 # Wave Orchestration
 
-Wave Orchestration is a repository harness for running multi-agent work in bounded waves. You define shared plan docs plus per-wave markdown, the launcher validates the wave, compiles prompts and inboxes, runs implementation agents first, then performs staged closure. Every run writes durable state under `.tmp/<lane>-wave-launcher/` so humans can inspect progress, replay outcomes, and intervene only when needed.
+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.
+
+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.
+2. It runs work as a blackboard-style multi-agent system. Agents do not just exchange chat messages; they work against shared state, generated inboxes, explicit ownership, and staged closure, and a wave keeps going until the declared goals, proof, production-live criteria, or eval targets are actually satisfied.
+3. It compiles context dynamically for the task at hand. Shared memory, generated runtime files, project defaults, skills, Context7, and cached external docs are assembled at runtime so you do not have to hand-maintain separate Claude, Codex, or other context files.
+
+## Core Ideas
+
+- `One orchestrator, many runtimes.`
+  Planning, skills, evals, proof, and traces stay constant while the executor adapter changes.
+- `A blackboard-style multi-agent system.`
+  The coordination log is canonical shared state; the rolling board, shared summary, inboxes, ledger, and integration views are generated projections over that state.
+- `Completion is goal-driven and proof-bounded.`
+  Waves close only when deliverables, proof artifacts, eval targets, dependencies, and closure stewards agree.
+- `Context is compiled, not hand-maintained.`
+  Wave builds runtime context from repo state, project memory, skills, Context7, and generated overlays.
+- `The system is inspectable and replayable.`
+  Dry-run previews, logs, dashboards, ledgers, traces, and replay make the system debuggable instead of mysterious.
+
+## How The Architecture Works
+
+1. Define shared docs plus `docs/plans/waves/wave-<n>.md` files, or generate them with `wave draft`.
+2. Run `wave launch --dry-run` to validate the wave and materialize prompts, shared summaries, inboxes, dashboards, and executor previews before any live execution.
+3. During live execution, implementation agents write claims, evidence, requests, and decisions into the canonical coordination log instead of relying on ad hoc terminal narration.
+4. The launcher compiles blackboard projections from that state: rolling board, shared summary, per-agent inboxes, ledger, docs queue, dependency views, and integration summaries.
+5. Closure runs only when the integrated state is ready: optional `cont-EVAL` (`E0`), optional security review, integration (`A8`), documentation (`A9`), and `cont-QA` (`A0`).
+
+## Architecture Surfaces
+
+- `Wave contract`
+  Shared plan docs, wave markdown, deliverables, proof artifacts, and eval targets define the goal.
+- `Shared state`
+  The coordination log is the source of truth; the board is for humans, not the scheduler.
+- `Runtime abstraction`
+  Executor adapters preserve Codex, Claude, and OpenCode-specific launch features without changing the higher-level wave contract.
+- `Compiled context`
+  Project profile memory, shared summary, inboxes, skills, Context7, and runtime overlays are generated for the chosen executor.
+- `Proof and closure`
+  Exit contracts, proof artifacts, eval markers, and closure stewards stop waves from closing on narrative-only PASS.
+- `Replay and audit`
+  Traces capture the attempt so failures can be inspected and replayed instead of guessed from screenshots.
 
-## How It Works
+## Example Output
 
-1. Write shared docs and one or more `docs/plans/waves/wave-<n>.md` files.
-2. Run `wave launch --dry-run` to validate the wave and materialize prompts, inboxes, dashboards, and executor previews.
-3. A real launch runs implementation agents first. Agents post claims, evidence, requests, and decisions into the coordination log and rolling message board.
-4. When implementation gates pass, closure runs in order: optional `cont-EVAL` (`E0`), integration (`A8`), documentation (`A9`), and `cont-QA` (`A0`).
-5. Operators use the generated ledgers, inboxes, feedback queue, dependency views, and traces instead of guessing from raw terminal output.
+Representative rolling message board output from a real wave run:
 
-## Features
+<img src="./docs/image.png" alt="Example rolling message board output showing claims, evidence, requests, and cont-QA closure for a wave run" width="100%" />
 
-- Planner foundation with saved project profile memory, draft specs, and rendered wave markdown
-- Implementation-first execution with staged closure and retry support
-- Durable coordination log, rolling message board, compiled inboxes, and per-wave ledger
-- Dry-run prompt and executor preview mode before any real agent launch
-- Context7 bundle selection, caching, and prompt injection
-- Multi-executor support for Codex, Claude Code, OpenCode, and a local smoke executor
-- Cross-runtime skill packs loaded from `skills/` and resolved by lane, role, runtime, deploy kind, and per-agent attachment
-- Human feedback routing, clarification triage, helper assignment, and cross-lane dependencies
-- Replayable trace bundles for regression and release verification
+## Common MAS Failure Cases
 
-## Example Output
+Recent multi-agent research keeps returning to the same failure modes:
 
-Representative rolling message board output from a real wave run:
+- `Cosmetic board, no canonical state`
+  Agents appear coordinated, but there is no machine-trustable source of truth underneath the conversation.
+- `Hidden evidence never gets pooled`
+  One agent has the critical fact, but it never reaches shared state before closure.
+- `Communication without global-state reconstruction`
+  Agents exchange information, but nobody reconstructs the correct cross-agent picture.
+- `Simultaneous coordination collapse`
+  A team that looks fine in serial work falls apart when multiple owners, blockers, or resources must move together.
+- `Expert signal gets averaged away`
+  The strongest specialist view is diluted into a weaker compromise.
+- `Contradictions get smoothed over`
+  Conflicts are narrated away instead of being turned into explicit repair work.
+- `Premature closure`
+  Agents say they are done before proof, evals, or integrated state actually support PASS.
 
-<img src="./docs/image.png" alt="Example rolling message board output showing claims, evidence, requests, and cont-QA closure for a wave run" width="100%" />
+Wave is built to mitigate those failures with canonical shared state, generated blackboard projections, explicit ownership, goal-driven, proof-bounded closure, and replayable traces. For the research framing and the current gaps, see [docs/research/coordination-failure-review.md](./docs/research/coordination-failure-review.md).
 
 ## Quick Start
 
 Current release:
 
-- `@chllming/wave-orchestration@0.6.1`
-- Release tag: [`v0.6.1`](https://github.com/chllming/wave-orchestration/releases/tag/v0.6.1)
+- `@chllming/wave-orchestration@0.6.3`
+- Release tag: [`v0.6.3`](https://github.com/chllming/wave-orchestration/releases/tag/v0.6.3)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.6.1`:
+Highlights in `0.6.3`:
 
-- `cont-EVAL` (`E0`) is now a first-class optional eval stage before integration, separate from final `cont-QA` closure.
-- Optional security review now has a dedicated role, report path, and `[wave-security]` closure marker.
-- `wave adhoc plan|run|show|promote` now supports transient operator requests on the same launcher substrate.
-- Starter docs and skills now cover the current `0.6.1` closure, benchmark, security, and provider surfaces.
+- Runtime launch entrypoints now check npmjs for a newer published package in the background, cache the result under `.wave/package-update-check.json`, and warn on stderr when the workspace is behind.
+- `wave self-update` now gives downstream repos a one-command update path that detects the workspace package manager, updates the dependency, shows the changelog delta, and records the workspace upgrade report.
+- Autonomous and ad-hoc flows suppress nested notices so operators see at most one update banner per top-level run, and structured stdout remains clean for JSON consumers.
 
 Requirements:
 
@@ -59,7 +101,7 @@ 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
+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:
@@ -70,6 +112,8 @@ 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.
 
+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
 
 ```bash
@@ -86,6 +130,9 @@ 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
+
+# Pull the latest published package and record the workspace upgrade
+pnpm exec wave self-update
 ```
 
 ## Develop This Package
@@ -99,14 +146,16 @@ node scripts/wave.mjs launch --lane main --dry-run --no-dashboard
 ## Learn More
 
 - [docs/README.md](./docs/README.md): docs map and suggested structure
-- [docs/concepts/what-is-a-wave.md](./docs/concepts/what-is-a-wave.md): wave anatomy, lifecycle, and closure model
+- [docs/concepts/what-is-a-wave.md](./docs/concepts/what-is-a-wave.md): wave anatomy, blackboard execution model, and proof-bounded closure
+- [docs/concepts/runtime-agnostic-orchestration.md](./docs/concepts/runtime-agnostic-orchestration.md): how one orchestration substrate spans Claude, Codex, OpenCode, and local execution
+- [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/concepts/context7-vs-skills.md](./docs/concepts/context7-vs-skills.md): when to use external docs vs repo-owned skills
 - [docs/guides/terminal-surfaces.md](./docs/guides/terminal-surfaces.md): tmux, VS Code terminal registry, and dry-run surfaces
 - [docs/plans/wave-orchestrator.md](./docs/plans/wave-orchestrator.md): operator runbook
 - [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/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
 - [CHANGELOG.md](./CHANGELOG.md): release history
 
 ## Research Sources

package/docs/README.md

@@ -1,6 +1,12 @@
 # Wave Documentation
 
-This repository now uses a layered docs structure, but the useful path is journey-first:
+These docs are organized around three core ideas:
+
+- one orchestrator, many runtimes across Claude, Codex, OpenCode, and local execution
+- a blackboard-style multi-agent system with goal-driven, proof-bounded closure
+- compiled context from shared state, skills, runtime files, and Context7 instead of hand-maintained per-runtime context files
+
+The useful path is journey-first:
 
 - start with one core concept doc
 - then use one end-to-end workflow guide
@@ -22,7 +28,11 @@ This repository now uses a layered docs structure, but the useful path is journe
 ## Start Here
 
 - New to Wave:
-  Read [concepts/what-is-a-wave.md](./concepts/what-is-a-wave.md). It now covers the core execution model, runtime posture, closure, and state model in one place.
+  Read [concepts/what-is-a-wave.md](./concepts/what-is-a-wave.md). It covers the blackboard execution model, proof-bounded closure, runtime posture, and durable state model in one place.
+- Want the runtime abstraction story:
+  Read [concepts/runtime-agnostic-orchestration.md](./concepts/runtime-agnostic-orchestration.md) to see how planning, skills, evals, proof, and traces stay stable across Claude, Codex, OpenCode, and local execution.
+- Want the context story:
+  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.
 - Adding a security review pass:
@@ -37,8 +47,10 @@ This repository now uses a layered docs structure, but the useful path is journe
   Start with [guides/author-and-run-waves.md](./guides/author-and-run-waves.md), then use [plans/wave-orchestrator.md](./plans/wave-orchestrator.md) for the live operator flow.
 - Tuning runtime behavior:
   Read [reference/runtime-config/README.md](./reference/runtime-config/README.md) and [reference/skills.md](./reference/skills.md).
+- Want the research framing behind the design:
+  Read [research/coordination-failure-review.md](./research/coordination-failure-review.md) for the common MAS failure modes and how Wave tries to mitigate them, then use [research/agent-context-sources.md](./research/agent-context-sources.md) as the bibliography.
 - Looking for supporting concept pages:
-  Use [concepts/runtime-agnostic-orchestration.md](./concepts/runtime-agnostic-orchestration.md), [concepts/operating-modes.md](./concepts/operating-modes.md), and [concepts/context7-vs-skills.md](./concepts/context7-vs-skills.md) after the main concept and workflow docs.
+  Use [concepts/operating-modes.md](./concepts/operating-modes.md) after the main concept, runtime, and context docs.
 
 ## Package vs Repo-Owned Material
 

package/docs/concepts/context7-vs-skills.md

@@ -4,6 +4,30 @@ Context7 and skills solve different problems.
 
 Use Context7 for external library truth. Use skills for repo-owned, reusable operating knowledge.
 
+That comparison matters because Wave treats context as something to compile at runtime, not something humans should maintain separately for Claude, Codex, OpenCode, and every other executor.
+
+## Compiled Context, Not Hand-Maintained Context Files
+
+The active context for an agent is assembled from multiple layers:
+
+- repository source and the wave's owned files
+- wave markdown and shared plan docs
+- generated shared summary and per-agent inbox
+- saved project defaults such as `.wave/project-profile.json`
+- resolved repo-owned skills
+- selected Context7 snippets for external library truth
+- generated runtime overlays and launch artifacts
+
+Because of that, the question is not "which hand-written context file does this runtime use?" The question is "which context sources does this wave compile for the selected runtime right now?"
+
+Runtime-specific context is still real, but it is mostly generated:
+
+- Claude gets merged system-prompt and settings overlays
+- Codex gets executor flags plus runtime-projected skills
+- OpenCode gets generated config, attachments, and runtime instructions
+
+That keeps the context model unified even when the transport layer differs.
+
 ## Short Version
 
 - Context7

package/docs/concepts/runtime-agnostic-orchestration.md

@@ -1,15 +1,22 @@
 # Runtime-Agnostic Orchestration
 
+In short: one orchestrator, many runtimes.
+
 Wave is runtime agnostic at the orchestration layer.
 
-That means planning, coordination, closure, and traces do not depend on whether the selected executor is Codex, Claude Code, OpenCode, or the local smoke executor.
+That means planning, skills, evaluation, proof, coordination, closure, and traces do not depend on whether the selected executor is Codex, Claude Code, OpenCode, or the local smoke executor.
+
+Wave abstracts the runtime away without flattening everything to the lowest common denominator. The wave contract stays stable while the executor adapter preserves the useful runtime-native features.
 
 ## What Stays The Same Across Runtimes
 
 These layers are runtime-neutral:
 
 - wave parsing and validation
+- planner-produced wave specs and authored wave markdown
+- eval targets, deliverables, and proof artifacts
 - component and closure gates
+- skill resolution and attachment policy
 - compiled shared summaries and per-agent inboxes
 - coordination log and rendered message board
 - helper assignments and dependency handling
@@ -34,11 +41,19 @@ Runtime-specific behavior is isolated to the executor adapter layer:
 
 The orchestration substrate above those adapters does not need to know how the runtime transports prompts.
 
+This is the important distinction:
+
+- the orchestration layer owns goals, ownership, proof, and shared state
+- the executor adapter owns prompt transport, runtime-native flags, files, and settings
+
+That split is what lets Wave stay portable without giving up runtime-specific leverage.
+
 ## Why This Matters
 
 Runtime agnosticism gives you:
 
-- the same plan and closure model across vendors
+- the same plan, skill, and closure model across vendors
+- the same eval and proof model across vendors
 - replay and audit surfaces that do not care which runtime produced the work
 - per-role runtime choice without rewriting authoring conventions
 - retry-time fallback without inventing a second planning model

package/docs/concepts/what-is-a-wave.md

@@ -2,6 +2,8 @@
 
 A wave is the main planning and execution unit in Wave Orchestration.
 
+It turns free-form agent runs into a bounded blackboard-style work package with shared state, explicit ownership, dynamic context, goal-driven execution, and proof-bounded closure.
+
 It is not just a prompt file. A wave is a bounded slice of repository work with:
 
 - explicit scope
@@ -34,6 +36,16 @@ Waves force a higher planning bar than ad hoc prompts. A good wave answers:
 - What evidence closes the wave?
 - Which dependencies, helper requests, or escalations can still block completion?
 
+## Why This Is A Blackboard-Style Model
+
+Wave is blackboard-style because agents work against shared state instead of treating chat output as the system of record.
+
+- the canonical coordination log is the machine-readable source of truth
+- the rolling board is a human projection over that state, not the scheduler's authority
+- shared summaries and per-agent inboxes are compiled views over the same state
+- helper assignments, clarification flow, dependencies, and integration all operate on that shared state
+- closure depends on the integrated state, not on whether an agent says "done"
+
 ## Wave Anatomy
 
 Wave markdown is the authored execution surface today. A typical wave can include:
@@ -136,6 +148,22 @@ Current live waves are strict about closure artifacts:
 - `cont-QA` must emit both a final `Verdict:` line and a final `[wave-gate]` marker.
 - Replay keeps read-only compatibility with older traces and older evaluator-era artifacts, but live waves do not pass on verdict-only or underspecified closure markers.
 
+## Context Is Compiled At Runtime
+
+Wave also treats context as something to compile for the current task, not something humans should hand-maintain separately for each runtime.
+
+The active context for an agent is assembled from:
+
+- repository source and owned files
+- wave markdown and shared plan docs
+- saved project defaults such as `.wave/project-profile.json`
+- the generated shared summary and the agent's inbox
+- resolved skills and runtime-specific skill projections
+- selected Context7 snippets for external library truth
+- generated executor overlays and launch artifacts
+
+That is why switching an agent between Codex, Claude, or OpenCode does not require maintaining separate parallel context files. The orchestrator recomputes the context package for the selected runtime and the current wave state.
+
 ## What Makes A Wave "Done"
 
 A wave is not done because an agent said so. It is done only when the runtime surfaces agree:

package/docs/evals/README.md

@@ -16,6 +16,8 @@ The catalog is reference metadata, not a run-history database. It tells the wave
 
 For a full authored wave example that uses these patterns, see [docs/reference/sample-waves.md](../reference/sample-waves.md).
 
+These benchmark families are also Wave's operator-facing vocabulary for common MAS failure modes. For the research-side framing and the current architectural gaps, see [docs/research/coordination-failure-review.md](../research/coordination-failure-review.md).
+
 ## Migrating From Legacy Evaluator Waves
 
 If your `0.5.4`-era repo still talks about a single `evaluator` role, split that surface before adopting `0.6.1`:

package/docs/guides/terminal-surfaces.md

@@ -45,6 +45,8 @@ Use `tmux` when:
 
 By default the launcher can start per-wave dashboard sessions in tmux.
 
+When `--terminal-surface vscode` is active, Wave also maintains a stable current-wave dashboard terminal entry instead of creating a new wave-numbered dashboard attach target for every wave transition.
+
 Important flags:
 
 - `--no-dashboard`

package/docs/plans/current-state.md

@@ -1,8 +1,9 @@
 # Current State
 
-- The starter workspace in this source repo reflects the `0.6.1` package release surface.
+- The starter workspace in this source repo reflects the `0.6.3` package release surface.
 - 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/`.
+- Runtime launch entrypoints now perform a best-effort npmjs version check, cache the result under `.wave/package-update-check.json`, and point operators at `pnpm exec wave self-update` when a newer published package exists.
 - This source repo is itself kept as an adopted Wave workspace, so `node scripts/wave.mjs doctor --json` should pass from the repo root.
 - The default lane is `main`.
 - Planner foundation is now shipped:

package/docs/plans/wave-orchestrator.md

@@ -4,6 +4,14 @@ The Wave Orchestrator coordinates repository work as bounded execution waves.
 
 For the broader docs map, concept pages, and workflow guides, start at [docs/README.md](../README.md).
 
+This runbook is the operational view of the architecture:
+
+- one wave contract defines goals, ownership, proof, and closure
+- one canonical coordination log acts as the shared blackboard state
+- generated board, shared summary, inboxes, ledger, and integration outputs are projections over that state
+- executor adapters preserve Claude, Codex, and OpenCode-specific runtime features at the edge
+- closure makes completion depend on integrated proof and shared state, not on free-form agent narration
+
 ## What It Does
 
 - parses wave plans from `docs/plans/waves/`
@@ -46,6 +54,7 @@ For the broader docs map, concept pages, and workflow guides, start at [docs/REA
 - `pnpm exec wave dep show --lane main --wave 0 --json`
 - `pnpm exec wave dep post --owner-lane main --requester-lane release --owner-wave 0 --requester-wave 2 --agent launcher --summary "Need shared-plan reconciliation" --target capability:docs-shared-plan --required`
 - `pnpm exec wave upgrade`
+- `pnpm exec wave self-update`
 
 ## Configuration
 
@@ -143,6 +152,16 @@ Required inbound dependencies block autonomous next-wave start and lane finaliza
 
 ## Upgrade Flow
 
+Fast path:
+
+```bash
+pnpm exec wave self-update
+```
+
+That command updates the dependency through the workspace package manager, prints the changelog delta since the recorded install, and then runs `wave upgrade` to record the new install-state and upgrade report.
+
+Manual path:
+
 1. Upgrade the package version:
 
 ```bash
@@ -260,7 +279,7 @@ The launcher entrypoint in `scripts/wave-orchestrator/launcher.mjs` now delegate
 - Skills resolve only after that executor choice is known. Runtime-specific skill overlays are regenerated whenever retry-time fallback changes the selected executor.
 - Runtime mix targets are enforced before launch and again before any retry-time fallback reassignment.
 - Fallbacks are declared in profiles or lane policy, can be applied automatically on retry when the next executor is available and still satisfies mix targets, and are recorded in the ledger, integration summary, and traces when used.
-- Generic `budget.minutes` caps per-agent attempt timeouts. Generic `budget.turns` seeds `claude.maxTurns` and `opencode.steps` when executor-specific values are not set.
+- Generic `budget.minutes` caps per-agent attempt timeouts. Generic `budget.turns` seeds `claude.maxTurns` and `opencode.steps` when executor-specific values are not set; Codex turn ceilings remain external to Wave and show up in preview metadata as opaque when Wave cannot inspect them.
 - The launcher writes runtime overlay files under `.tmp/<lane>-wave-launcher/executors/`; these should stay ignored and local.
 
 Runtime authoring examples:
@@ -294,7 +313,7 @@ Runtime authoring examples:
 - opencode.config_json: {"instructions":["Keep shared-plan edits concise."]}
 ````
 
-Dry-run is the intended validation path for these runtime surfaces. `wave launch --dry-run --no-dashboard` now writes compiled prompts, merged runtime overlays, and `launch-preview.json` files under `.tmp/<lane>-wave-launcher/dry-run/` so the harness can verify invocation shape without requiring the executor binaries to run.
+Dry-run is the intended validation path for these runtime surfaces. `wave launch --dry-run --no-dashboard` now writes compiled prompts, merged runtime overlays, and `launch-preview.json` files under `.tmp/<lane>-wave-launcher/dry-run/` so the harness can verify invocation shape, attempt budgets, and known or opaque turn-limit metadata without requiring the executor binaries to run.
 
 ## Human Feedback Queue
 
@@ -308,7 +327,7 @@ pnpm exec wave feedback respond --id <request-id> --response "..."
 
 ## Closure Sweep
 
-If implementation agents ran, the launcher does not stop at `exit 0`. It checks implementation exit contracts, promoted component proof, helper assignments, required dependencies, and the integration recommendation first. When present, `cont-EVAL` must satisfy its declared eval targets before integration can close. Optional security review then runs before integration so the reviewer can publish findings and approval-sensitive actions while the wave is still active. In the default planner shape `E0` is report-only; if a wave explicitly assigns `E0` non-report files, the launcher also applies the normal implementation proof gates to that role. Security reviewers stay report-only by default. Documentation and cont-QA closure only run after integration is explicitly ready for doc closure; if `cont-EVAL`, security review, or integration reports more work, or if helper assignments or required dependency tickets remain open, the wave stops there and retries only the implicated owners plus the relevant closure steward.
+If implementation agents ran, the launcher does not stop at `exit 0`. It checks implementation exit contracts, promoted component proof, helper assignments, required dependencies, and the integration recommendation first. When present, `cont-EVAL` must satisfy its declared eval targets before integration can close. Optional security review then runs before integration so the reviewer can publish findings and approval-sensitive actions while the wave is still active. In the default planner shape `E0` is report-only; if a wave explicitly assigns `E0` non-report files, the launcher also applies the normal implementation proof gates to that role. Security reviewers stay report-only by default. Documentation and cont-QA closure only run after integration is explicitly ready for doc closure; if `cont-EVAL`, security review, or integration reports more work, or if helper assignments or required dependency tickets remain open, the wave stops there and retries only the implicated owners plus the relevant closure steward. When multiple implementation agents share a promoted component, owners that already landed valid proof stay reusable while the launcher retries only the sibling owners that still owe closure evidence.
 
 Live closure is fail-closed:
 

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

@@ -1,6 +1,6 @@
 # Runtime Configuration Reference
 
-This directory is the canonical reference for executor configuration in Wave `0.6.1`.
+This directory is the canonical reference for executor configuration in the packaged Wave release.
 
 Use it when you need the full supported surface for:
 
@@ -65,7 +65,7 @@ These fields are shared across runtimes:
 | Model | `model` in profile, `executors.claude.model`, `executors.opencode.model` | `model` | Codex uses shared `model` from profile or agent only |
 | Fallbacks | `fallbacks` in profile | `fallbacks` | Runtime ids used for retry-time reassignment |
 | Tags | `tags` in profile | `tags` | Stored in resolved executor state for policy and traces |
-| Budget turns | `budget.turns` in profile | `budget.turns` | Seeds Claude `maxTurns` and OpenCode `steps` when runtime-specific values are absent |
+| Budget turns | `budget.turns` in profile | `budget.turns` | Seeds Claude `maxTurns` and OpenCode `steps` when runtime-specific values are absent; it does not set a Codex turn limit |
 | Budget minutes | `budget.minutes` in profile | `budget.minutes` | Caps attempt timeout |
 
 ## Runtime Pages
@@ -83,7 +83,7 @@ Wave writes runtime artifacts here:
 
 Common files:
 
-- `launch-preview.json`: resolved invocation lines, env vars, and retry mode
+- `launch-preview.json`: resolved invocation lines, env vars, retry mode, and structured attempt/turn-limit metadata
 - `skills.resolved.md`: compact metadata-first skill catalog for the selected agent and runtime
 - `skills.expanded.md`: full canonical/debug skill payload with `SKILL.md` bodies and adapters
 - `skills.metadata.json`: resolved skill ids, activation metadata, permissions, hashes, and generated artifact paths
@@ -100,7 +100,7 @@ Runtime-specific delivery:
 - OpenCode injects the compact catalog into `opencode.json` and attaches `skill.json`, `SKILL.md`, the selected adapter, and recursive `references/**` files through `--file`.
 - Local keeps skills prompt-only.
 
-`launch-preview.json` also records the resolved skill metadata so dry-run can verify the exact runtime plus skill combination before any live launch.
+`launch-preview.json` also records the resolved skill metadata plus a `limits` section. For Claude and OpenCode, that section reports the known turn ceiling and whether it came from the runtime-specific setting or generic `budget.turns`. For Codex, it explicitly records that Wave emitted no turn-limit flag and that any effective ceiling may come from the selected Codex profile or upstream runtime.
 
 ## Recommended Validation Path
 

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

@@ -12,6 +12,7 @@ Wave launches Claude headlessly with `claude -p --no-session-persistence`.
 | Prompt mode | `executors.claude.appendSystemPromptMode` | n/a | Uses `--append-system-prompt-file` or `--system-prompt-file` |
 | Permission mode | `executors.claude.permissionMode`, `executors.profiles.<name>.claude.permissionMode` | `claude.permission_mode` | Adds `--permission-mode <mode>` |
 | Permission prompt tool | `executors.claude.permissionPromptTool`, `executors.profiles.<name>.claude.permissionPromptTool` | `claude.permission_prompt_tool` | Adds `--permission-prompt-tool <tool>` |
+| Effort | `executors.claude.effort`, `executors.profiles.<name>.claude.effort` | `claude.effort` | Adds `--effort low|medium|high|max` |
 | Max turns | `executors.claude.maxTurns`, `executors.profiles.<name>.claude.maxTurns` | `claude.max_turns` | Adds `--max-turns <n>` |
 | MCP config | `executors.claude.mcpConfig`, `executors.profiles.<name>.claude.mcpConfig` | `claude.mcp_config` | Adds repeated `--mcp-config <path>` |
 | Strict MCP mode | `executors.claude.strictMcpConfig`, `executors.profiles.<name>.claude.strictMcpConfig` | n/a | Adds `--strict-mcp-config` |
@@ -27,6 +28,8 @@ Wave launches Claude headlessly with `claude -p --no-session-persistence`.
 
 Wave always writes `claude-system-prompt.txt` for the harness runtime instructions.
 
+Wave validates the effort enum only. Model-specific compatibility for values such as `max` remains enforced by Claude Code itself.
+
 Wave writes `claude-settings.json` only when at least one inline overlay input is present:
 
 - `settingsJson`
@@ -57,6 +60,7 @@ If no inline overlay data is present, Wave passes the base `claude.settings` fil
         },
         "claude": {
           "agent": "reviewer",
+          "effort": "high",
           "permissionMode": "plan",
           "allowedTools": ["Read"],
           "disallowedTools": ["Edit"]
@@ -84,6 +88,7 @@ If no inline overlay data is present, Wave passes the base `claude.settings` fil
 
 - id: claude
 - model: claude-sonnet-4-6
+- claude.effort: high
 - claude.permission_mode: plan
 - claude.max_turns: 4
 - claude.settings_json: {"permissions":{"allow":["Read"]}}
@@ -102,4 +107,4 @@ For a dry run, inspect:
 - `claude-settings.json`, when generated
 - `launch-preview.json`
 
-`launch-preview.json` shows the final `claude -p` invocation and whether `--settings`, `--allowedTools`, `--disallowedTools`, `--mcp-config`, or `--system-prompt-file` were included.
+`launch-preview.json` shows the final `claude -p` invocation, whether `--effort`, `--settings`, `--allowedTools`, `--disallowedTools`, `--mcp-config`, or `--system-prompt-file` were included, and the resolved `limits` block for attempt timeout plus known turn ceiling.

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

@@ -20,6 +20,7 @@ Wave launches Codex with `codex exec` and pipes the generated task prompt throug
 ## Notes
 
 - There is no `executors.codex.model` key today. Use profile `model` or per-agent `model`.
+- Generic `budget.turns` does not set a Codex turn limit. If Codex stops on a turn ceiling, that limit came from the selected Codex profile or upstream Codex runtime, not from a Wave-emitted CLI flag.
 - `codex.images`, `codex.add_dirs`, and `codex.config` accept either a string array in `wave.config.json` or a comma-separated list in a wave file.
 - Relative paths are passed to Codex relative to the repository root because Wave launches the executor from the repo workspace.
 
@@ -35,7 +36,6 @@ Wave launches Codex with `codex exec` and pipes the generated task prompt throug
         "model": "gpt-5-codex",
         "fallbacks": ["claude", "opencode"],
         "budget": {
-          "turns": 12,
           "minutes": 45
         },
         "codex": {
@@ -78,4 +78,4 @@ For a dry run, inspect:
 - `launch-preview.json` for the final `codex exec` command
 - any referenced prompt file under `.tmp/<lane>-wave-launcher/dry-run/prompts/`
 
-The preview records the exact `--profile`, repeated `-c`, `--image`, and `--add-dir` flags that Wave would use in a live launch.
+The preview records the exact `--profile`, repeated `-c`, `--image`, and `--add-dir` flags that Wave would use in a live launch. It also includes a `limits` block that makes Wave's Codex visibility explicit: `turnLimitSource: "not-set-by-wave"` means Wave emitted no Codex turn-limit flag, so any effective ceiling is external to the Wave CLI invocation.

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

@@ -90,4 +90,4 @@ For a dry run, inspect:
 - `opencode.json`
 - `launch-preview.json`
 
-`launch-preview.json` shows the final `opencode run` command and the exported `OPENCODE_CONFIG` path.
+`launch-preview.json` shows the final `opencode run` command, the exported `OPENCODE_CONFIG` path, and the resolved `limits` block for attempt timeout plus known step ceiling.

package/docs/research/agent-context-sources.md

@@ -7,6 +7,8 @@ summary: "Primary external sources used as inspiration for planning, harness des
 
 This repository does not commit converted paper/article caches. Keep any hydrated local copies under `docs/research/agent-context-cache/` or another ignored cache directory.
 
+For a narrative synthesis of the most relevant MAS failure modes and how Wave responds to them, start with [coordination-failure-review.md](./coordination-failure-review.md) and then use this page as the bibliography.
+
 ## Practice Articles
 
 - [Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)