@chllming/wave-orchestration 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 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.
+- Updated shipped package docs and release metadata to advertise `0.6.1` as the current release surface, including the runtime-config reference that still said `0.5.x` during the `0.6.0` cut.
+- No additional runtime behavior changes beyond the `0.6.0` workspace-scoped tmux isolation fix; this patch release aligns the published package with the merged source tree.
+
 ## 0.6.0 - 2026-03-22
 
 ### Breaking Changes

package/README.md

@@ -1,48 +1,91 @@
 # 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.0`
-- Release tag: [`v0.6.0`](https://github.com/chllming/wave-orchestration/releases/tag/v0.6.0)
+- `@chllming/wave-orchestration@0.6.2`
+- Release tag: [`v0.6.2`](https://github.com/chllming/wave-orchestration/releases/tag/v0.6.2)
 - Public install path: npmjs
 - Authenticated fallback: GitHub Packages
 
-Highlights in `0.6.0`:
+Highlights in `0.6.2`:
 
-- `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.0` closure, benchmark, security, and provider surfaces.
+- Runtime previews and docs now expose first-class Claude effort plus structured limit metadata, making known Claude/OpenCode ceilings explicit and Codex opacity explicit.
+- The global dashboard and VS Code terminal surfaces are easier to read: active vs pending counts are distinct, the current-wave dashboard keeps a stable terminal name, and TTY dashboards now use simple color cues.
+- Dry-run executor preview directories now prune stale agent folders when a wave shrinks.
+- Shared promoted-component retries now preserve already-landed owner slices and relaunch only the sibling owners still needed for closure.
 
 Requirements:
 
@@ -59,7 +102,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:
@@ -99,14 +142,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,16 +16,18 @@ 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.0`:
+If your `0.5.4`-era repo still talks about a single `evaluator` role, split that surface before adopting `0.6.1`:
 
 - keep `A0` as `cont-QA` for the final closure verdict and `[wave-gate]`
 - add `E0` only when the wave needs benchmark-driven tuning or service-output evaluation
 - treat `cont-EVAL` as report-only unless the wave explicitly gives `E0` owned implementation files
 - keep `## Eval targets` at the wave level so `cont-EVAL` has an exact contract to satisfy
 
-`cont-EVAL` is not a rename of `cont-QA`. In `0.6.0`, `E0` proves the eval contract before integration, while `A0` still owns the final release verdict after documentation closure.
+`cont-EVAL` is not a rename of `cont-QA`. In `0.6.1`, `E0` proves the eval contract before integration, while `A0` still owns the final release verdict after documentation closure.
 
 ## When To Use Delegated Vs Pinned Targets
 

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,6 +1,6 @@
 # Current State
 
-- The starter workspace in this source repo reflects the `0.6.0` package release surface.
+- The starter workspace in this source repo reflects the `0.6.1` 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/`.
 - This source repo is itself kept as an adopted Wave workspace, so `node scripts/wave.mjs doctor --json` should pass from the repo root.

package/docs/plans/examples/wave-example-live-proof.md

@@ -2,7 +2,7 @@
 
 This is a showcase-first sample wave.
 
-Use it as the single reference example for the current `0.6.0` Wave surface.
+Use it as the single reference example for the current `0.6.1` Wave surface.
 
 It intentionally combines more sections than a normal production wave so one file can demonstrate:
 

package/docs/plans/migration.md

@@ -22,9 +22,9 @@ GitHub Packages remains available as an authenticated fallback path, and maintai
 - Fresh `wave init` seeds the starter `skills/` library. `wave init --adopt-existing` records existing repo-owned skill bundles when they are already present, but does not replace or rewrite them.
 - The current runtime expects the post-roadmap model: typed coordination, compiled inboxes, `A8` integration, staged closure, orchestrator-first clarification, and operational runtime policy.
 
-## Upgrading From 0.5.4 To 0.6.0
+## Upgrading From 0.5.4 To 0.6.1
 
-Read `CHANGELOG.md` first, then treat the rest of this page as the manual repo-owned migration checklist for the `0.6.0` release. `wave upgrade` will update package-owned runtime code only; it will not rewrite the docs, prompts, config, or wave files that your repo already owns.
+Read `CHANGELOG.md` first, then treat the rest of this page as the manual repo-owned migration checklist for the `0.6.1` release. `wave upgrade` will update package-owned runtime code only; it will not rewrite the docs, prompts, config, or wave files that your repo already owns.
 
 ### Required Repo Changes
 
@@ -32,7 +32,7 @@ Read `CHANGELOG.md` first, then treat the rest of this page as the manual repo-o
 2. Keep `A0` as the final closure owner that emits both the final verdict and `[wave-gate]`.
 3. Add `E0` only when the wave needs benchmark-driven tuning or service-output evaluation.
 4. Add wave-level `## Eval targets` whenever `cont-EVAL` is present.
-5. Update any starter docs or examples that still describe the pre-`0.6.0` evaluator model.
+5. Update any starter docs or examples that still describe the pre-`0.6.1` evaluator model.
 
 In practice that means checking:
 
@@ -47,7 +47,7 @@ In practice that means checking:
 
 ### Closure And Marker Changes
 
-Live `0.6.0` closure is stricter than `0.5.4`.
+Live `0.6.1` closure is stricter than `0.5.4`.
 
 - `cont-EVAL` must leave a report plus a final `[wave-eval]` marker whose `target_ids` exactly matches the wave contract and whose `benchmark_ids` stays within the benchmark catalog.
 - Security review, when present, must leave a report plus a final `[wave-security]` marker.

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/`
@@ -260,7 +268,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 +302,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 +316,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/npmjs-trusted-publishing.md

@@ -2,7 +2,7 @@
 
 This repo now includes a dedicated npmjs publish workflow at [publish-npm.yml](../../.github/workflows/publish-npm.yml).
 
-The current `0.6.0` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
+The current `0.6.1` release procedure publishes through a repository Actions secret named `NPM_TOKEN`.
 
 ## What This Repo Already Does
 
@@ -47,6 +47,6 @@ If this repo later needs private npm dependencies during CI, consider a separate
 1. Confirm [publish-npm.yml](../../.github/workflows/publish-npm.yml) is on the default branch.
 2. Confirm `NPM_TOKEN` exists in the GitHub repo secrets.
 3. Confirm the package version has been bumped and committed.
-4. Push the release commit and release tag, for example `v0.6.0`.
+4. Push the release commit and release tag, for example `v0.6.1`.
 5. Verify both `publish-npm.yml` and `publish-package.yml` start from the tag push.
 6. Verify the npmjs publish completes successfully for the tagged source.

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.5.x`.
+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/reference/sample-waves.md

@@ -1,18 +1,18 @@
 ---
 title: "Sample Waves"
-summary: "A showcase-first sample wave that demonstrates the current 0.6.0 Wave surface."
+summary: "A showcase-first sample wave that demonstrates the current 0.6.1 Wave surface."
 ---
 
 # Sample Waves
 
-This guide points to one showcase-first sample wave that demonstrates the current `0.6.0` authored Wave surface.
+This guide points to one showcase-first sample wave that demonstrates the current `0.6.1` authored Wave surface.
 
 The example is intentionally denser than a typical production wave. Its job is to teach the current authoring and runtime surface quickly, not to be the smallest possible launch-ready file.
 
 ## Canonical Example
 
 - [Full modern sample wave](../plans/examples/wave-example-live-proof.md)
-  Shows the combined `0.6.0` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
+  Shows the combined `0.6.1` authored surface in one file: closure roles, `E0`, optional security review, delegated and pinned benchmark targets, richer executor config, `### Skills`, `### Capabilities`, `### Deliverables`, `### Exit contract`, `### Proof artifacts`, sticky retry, deploy environments, and proof-first live-wave structure.
 
 ## What This Example Teaches
 
@@ -32,7 +32,7 @@ The example is intentionally denser than a typical production wave. Its job is t
 
 ## Feature Coverage Map
 
-This sample covers the main surfaces added or hardened for `0.6.0`:
+This sample covers the main surfaces added or hardened for `0.6.1`:
 
 - planner-era authored wave structure
 - cross-runtime `### Skills`