@chllming/wave-orchestration 0.8.9 → 0.9.1

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

@@ -13,7 +13,7 @@ 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`
+- saved project defaults such as `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects
 - resolved repo-owned skills
 - selected Context7 snippets for external library truth
 - generated runtime overlays and launch artifacts

package/docs/concepts/operating-modes.md

@@ -11,7 +11,7 @@ Today that posture is captured in project profile memory and planner output. The
 - `dark-factory`
   The goal is end-to-end execution without routine human intervention.
 
-These values are stored in `.wave/project-profile.json` and emitted into planner-generated specs and wave markdown.
+These values are stored in `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects, and emitted into planner-generated specs and wave markdown.
 
 ## What Ships Today
 
@@ -82,10 +82,10 @@ That usually means:
 
 ## Relationship To The Roadmap
 
-The roadmap still includes stronger explicit oversight vs dark-factory workflows. What is shipped today is the planning foundation:
+The current roadmap is a release-direction document, not a backlog of planner phases. What is shipped today is still the planning foundation:
 
 - stored project defaults
 - typed values in planner output
 - better environment modeling
 
-The stricter execution semantics are the next step, not a hidden already-finished feature.
+The stricter execution semantics are still future work, not a hidden already-finished feature in `0.9.1`.

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

@@ -160,7 +160,7 @@ 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`
+- saved project defaults such as `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects
 - the generated shared summary and the agent's inbox
 - resolved skills and runtime-specific skill projections
 - selected Context7 snippets for external library truth

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

@@ -13,6 +13,13 @@ pnpm exec wave project setup
 pnpm exec wave project show --json
 ```
 
+In a monorepo, run the same setup per project:
+
+```bash
+pnpm exec wave project setup --project backend
+pnpm exec wave project show --project backend --json
+```
+
 The saved project profile remembers:
 
 - default oversight mode
@@ -31,6 +38,12 @@ Generate a structured draft:
 pnpm exec wave draft --wave 1 --template implementation
 ```
 
+For an explicit monorepo project:
+
+```bash
+pnpm exec wave draft --project backend --lane main --wave 1 --template implementation
+```
+
 The planner writes two artifacts:
 
 - `docs/plans/waves/specs/wave-<n>.json`
@@ -61,7 +74,7 @@ Good fits:
 - multi-owner waves where downstream implementers need the same decisions and assumptions
 - ambiguous tasks where open questions should become explicit before code owners fan out
 
-The starter contract in `0.8.9` is:
+The starter contract in `0.9.1` is:
 
 - import `docs/agents/wave-design-role.md`
 - own one packet such as `docs/plans/waves/design/wave-<n>-<agentId>.md`
@@ -88,12 +101,12 @@ Human feedback is an escalation path, not the operating mode itself. The orchest
 
 ## 4. Choose The Operator Surface
 
-Live runs always execute in `tmux`. The terminal surface only decides how you attach:
+Live agent runs now execute in detached process runners. The terminal surface only decides how you follow logs and attach to dashboard projections:
 
 - `vscode`
-  VS Code gets temporary attach entries for the live tmux sessions.
+  VS Code gets temporary attach entries for process-backed agent logs and dashboard projections.
 - `tmux`
-  Terminal-native operation with no VS Code integration.
+  Terminal-native dashboard and operator projection surface with no VS Code integration.
 - `none`
   Dry-run only.
 
@@ -103,6 +116,16 @@ Recommended defaults:
 - remote shell or devbox: `tmux`
 - CI or validation-only work: `none` with `--dry-run`
 
+If the surrounding environment is the unstable part, not the repo itself, prefer the sandbox-safe path:
+
+- `wave submit`
+- `wave supervise`
+- `wave status`
+- `wave wait`
+- `wave attach`
+
+That is the right fit for LEAPclaw, OpenClaw, Nemoshell, Docker, and similar short-lived exec shells. Use direct `wave launch` when the client shell itself can stay alive for the entire wave. For the concrete setup patterns, read [sandboxed-environments.md](./sandboxed-environments.md).
+
 ## 5. Dry-Run Before Live Execution
 
 Treat dry-run as the quality gate for the authored wave:

package/docs/guides/monorepo-projects.md

@@ -0,0 +1,226 @@
+# Monorepo Projects Guide
+
+Use this guide when one repository needs multiple independent Wave tracks.
+
+Wave now supports:
+
+- `defaultProject`
+- `projects.<projectId>`
+- project-scoped lanes
+- project-scoped planner memory
+- project-scoped ad-hoc runs
+- project-scoped launcher state and telemetry
+
+## What A Project Means
+
+A Wave project is the namespace above lanes.
+
+- a project owns its own `lanes`
+- a project can relocate its docs root with `rootDir`
+- a project can override planner, runtime, skills, and Wave Control settings
+- a project gets isolated runtime state when it is explicit in `wave.config.json`
+
+That isolation is what lets one checkout run multiple project/lane/wave tracks without tmux, telemetry, ad-hoc storage, or planner-profile collisions.
+
+## Minimal Config
+
+```json
+{
+  "defaultProject": "app",
+  "projects": {
+    "app": {
+      "rootDir": ".",
+      "lanes": {
+        "main": {}
+      }
+    },
+    "service": {
+      "rootDir": "services/api",
+      "lanes": {
+        "main": {}
+      }
+    }
+  }
+}
+```
+
+Rules:
+
+- `defaultProject` is used when you omit `--project`
+- `projects.<projectId>.rootDir` changes that project's default docs root
+- `projects.<projectId>.paths.*` overrides that project's docs, launcher-state, terminal-registry, benchmark-catalog, and component-matrix paths
+- `projects.<projectId>.lanes.<lane>` is the authoritative lane map for that project
+- legacy top-level `lanes` still work as the implicit default-project compatibility layer
+- an explicit unknown `--project` now fails fast instead of silently falling back to the default project
+
+Supported `projects.<projectId>.paths.*` fields:
+
+- `docsDir`
+- `stateRoot`
+- `orchestratorStateDir`
+- `terminalsPath`
+- `context7BundleIndexPath`
+- `benchmarkCatalogPath`
+- `componentCutoverMatrixDocPath`
+- `componentCutoverMatrixJsonPath`
+
+Path precedence is:
+
+1. lane-specific override such as `projects.<projectId>.lanes.<lane>.terminalsPath`
+2. `projects.<projectId>.paths.*`
+3. repo-global `paths.*`
+4. the built-in lane default for derived docs, plans, waves, and matrix paths
+
+## Advanced Config
+
+Use a fuller project block when different projects need isolated docs roots, terminal registries, telemetry ids, or runtime-policy defaults:
+
+```json
+{
+  "defaultProject": "app",
+  "paths": {
+    "stateRoot": ".tmp",
+    "terminalsPath": ".vscode/terminals.json"
+  },
+  "projects": {
+    "app": {
+      "rootDir": ".",
+      "lanes": {
+        "main": {}
+      }
+    },
+    "service": {
+      "rootDir": "services/api",
+      "paths": {
+        "docsDir": "services/api/docs",
+        "stateRoot": ".tmp/service-wave",
+        "orchestratorStateDir": ".tmp/service-orchestrator",
+        "terminalsPath": ".vscode/service-terminals.json",
+        "context7BundleIndexPath": "services/api/docs/context7/bundles.json",
+        "benchmarkCatalogPath": "services/api/docs/evals/benchmark-catalog.json",
+        "componentCutoverMatrixDocPath": "services/api/docs/plans/component-cutover-matrix.md",
+        "componentCutoverMatrixJsonPath": "services/api/docs/plans/component-cutover-matrix.json"
+      },
+      "waveControl": {
+        "projectId": "service-api",
+        "reportMode": "metadata-plus-selected"
+      },
+      "lanes": {
+        "main": {
+          "runtimePolicy": {
+            "defaultExecutorByRole": {
+              "design": "claude",
+              "implementation": "codex",
+              "integration": "claude",
+              "documentation": "claude",
+              "cont-qa": "claude",
+              "cont-eval": "codex"
+            },
+            "runtimeMixTargets": {
+              "codex": 4,
+              "claude": 3,
+              "opencode": 1
+            },
+            "fallbackExecutorOrder": ["claude", "opencode", "codex"]
+          }
+        },
+        "release": {
+          "docsDir": "services/api/docs/release",
+          "plansDir": "services/api/docs/release/plans",
+          "wavesDir": "services/api/docs/release/plans/waves"
+        }
+      }
+    }
+  }
+}
+```
+
+## Where State Lives
+
+Implicit default project:
+
+- planner profile: `.wave/project-profile.json`
+- ad-hoc runs: `.wave/adhoc/default/runs/<run-id>/`
+- launcher state: `.tmp/<lane>-wave-launcher/`
+
+Explicit projects:
+
+- planner profile: `.wave/projects/<projectId>/project-profile.json`
+- ad-hoc runs: `.wave/adhoc/<projectId>/runs/<run-id>/`
+- launcher state: `.tmp/projects/<projectId>/<lane>-wave-launcher/`
+
+Project-scoped tmux session names, terminal prefixes, and telemetry spools derive from that same project id.
+
+If a project overrides `stateRoot` or `terminalsPath`, those derived runtime locations move with it. For example, the `service` project above writes launcher state under `.tmp/service-wave/projects/service/<lane>-wave-launcher/` and keeps its VS Code terminal registry in `.vscode/service-terminals.json`.
+
+## Common Commands
+
+Set project defaults:
+
+```bash
+pnpm exec wave project setup --project service
+pnpm exec wave project show --project service --json
+```
+
+Draft and dry-run:
+
+```bash
+pnpm exec wave draft --project service --lane main --wave 1 --template implementation
+pnpm exec wave launch --project service --lane main --dry-run --no-dashboard
+```
+
+Control and inspection:
+
+```bash
+pnpm exec wave control status --project service --lane main --wave 0 --json
+pnpm exec wave coord show --project service --lane main --wave 0 --json
+pnpm exec wave dep show --project service --lane main --wave 0 --json
+pnpm exec wave dashboard --project service --lane main --attach current
+```
+
+Ad-hoc work:
+
+```bash
+pnpm exec wave adhoc plan --project service --lane main --task "Investigate release blocker"
+pnpm exec wave adhoc run --project service --lane main --task "Patch the deploy script" --yes
+```
+
+Benchmarks:
+
+```bash
+pnpm exec wave benchmark run --project service --lane main --json
+pnpm exec wave benchmark external-run --project service --lane main --adapter swe-bench-pro --dry-run --json
+```
+
+## Cross-Project Dependencies
+
+Use owner and requester project metadata when the dependency crosses project boundaries:
+
+```bash
+pnpm exec wave dep post \
+  --owner-project service --owner-lane main \
+  --requester-project app --requester-lane release \
+  --owner-wave 0 --requester-wave 2 \
+  --agent launcher \
+  --summary "Need API contract landed before release wave 2"
+```
+
+Dependency tickets are stored under the owner project's scoped dependency directory and carry both owner and requester project metadata.
+
+## Telemetry Defaults
+
+Packaged defaults:
+
+- endpoint: `https://wave-control.up.railway.app/api/v1`
+- enabled: `true`
+- report mode: `metadata-only`
+
+By default, repos using the packaged surface send project, lane, wave, run, proof, and benchmark metadata to the author's Wave Control endpoint. This is a personal project default, not a neutral hosted default.
+
+Opt out explicitly with any of:
+
+- `waveControl.enabled: false`
+- `waveControl.reportMode: "disabled"`
+- `pnpm exec wave launch --project service --lane main --no-telemetry`
+
+Project-scoped telemetry identity defaults to the resolved `projectId` first, then lane and wave metadata from the active run.

package/docs/guides/planner.md

@@ -6,7 +6,7 @@ If you want the full author-to-launch workflow, start with [author-and-run-waves
 
 It reduces repeated setup questions, stores project defaults, and generates wave specs plus markdown that already fit the launcher.
 
-The published `0.8.9` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
+The published `0.9.1` package already includes the optional `design` worker role for pre-implementation design packets. This guide calls out where that affects drafting.
 
 ## What Ships Today
 
@@ -17,7 +17,7 @@ The published `0.8.9` package already includes the optional `design` worker role
 - planner run review via `wave draft --show-run <run-id>`
 - explicit materialization via `wave draft --apply-run <run-id>`
 - worker role kinds including optional `design`
-- persistent project memory in `.wave/project-profile.json`
+- persistent project memory in `.wave/project-profile.json` for the implicit default project, or `.wave/projects/<projectId>/project-profile.json` for explicit projects
 - transient planner packets in `.wave/planner/runs/<run-id>/`
 - planner-run Context7 injection via `planner.agentic.context7Bundle`
 - JSON specs in `docs/plans/waves/specs/wave-<n>.json`
@@ -48,7 +48,7 @@ pnpm exec wave launch --lane main --dry-run --no-dashboard
 - forward replanning of later waves
 - separate runtime enforcement for oversight vs dark-factory
 
-Those remain roadmap work. The planner foundation is about better structured authoring, not a second execution engine.
+Those remain future work outside the current `0.9.1` release line. The planner foundation is about better structured authoring, not a second execution engine.
 
 ## Project Profile
 
@@ -59,6 +59,13 @@ pnpm exec wave project setup
 pnpm exec wave project show --json
 ```
 
+For monorepos, scope that memory explicitly:
+
+```bash
+pnpm exec wave project setup --project backend
+pnpm exec wave project show --project backend --json
+```
+
 The saved profile remembers:
 
 - whether the repo is a new project

package/docs/guides/{recommendations-0.8.9.md → recommendations-0.9.1.md}

@@ -1,21 +1,22 @@
 ---
-title: "0.8.9 Recommendations"
-summary: "How to use 0.8.9's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
+title: "0.9.1 Recommendations"
+summary: "How to use 0.9.1's softer blocker states, advisory turn budgets, and targeted recovery without weakening proof and closure."
 ---
 
-# 0.8.9 Recommendations
+# 0.9.1 Recommendations
 
-Use this guide when you are adopting `0.8.9` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
+Use this guide when you are adopting `0.9.1` and want one practical operating stance for the softer blocker states, advisory turn-budget behavior, and targeted recovery flow that the current package line ships.
 
 ## Recommended Default
 
-For most repos, the safest `0.8.9` default is:
+For most repos, the safest `0.9.1` default is:
 
 - bound work with `budget.minutes`
 - leave generic `budget.turns` as advisory metadata
 - author non-proof follow-up as `soft`, `stale`, or `advisory` instead of silently treating every open record as a hard blocker
 - use `resolve-policy` when the answer already exists in repo policy or shipped docs
 - prefer targeted rerun or resume after timeout, max-turn, rate-limit, or missing-status outcomes instead of relaunching the whole wave
+- in short-lived sandboxes, prefer `wave submit`, `wave supervise`, `wave status`, and `wave wait` instead of binding the full run to one client shell
 
 That recommendation matches the runtime:
 
@@ -75,7 +76,7 @@ Only set a hard runtime ceiling when you deliberately want the runtime itself to
 
 ## 2. Softer Coordination States
 
-`0.8.9` keeps “still visible” separate from “still blocking”.
+`0.9.1` keeps “still visible” separate from “still blocking”.
 
 Use these states intentionally:
 
@@ -111,7 +112,7 @@ If the current wave cannot truthfully close without the answer, keep it blocking
 
 ## 4. Recovery Recommendation
 
-My recommendation after reviewing the current `0.8.9` code path is:
+My recommendation after reviewing the current `0.9.1` code path is:
 
 - let timeout, max-turn, rate-limit, and missing-status failures go through the built-in targeted recovery path first
 - inspect the queued rerun or resume request before manually relaunching the whole wave

package/docs/guides/sandboxed-environments.md

@@ -0,0 +1,158 @@
+# Running Wave In Sandboxed Environments
+
+Use this guide when Wave is running under a short-lived shell or exec environment rather than a normal long-lived operator shell.
+
+Typical examples:
+
+- LEAPclaw or OpenClaw-style agent harnesses that give you short `exec` windows
+- Nemoshell or similar hosted terminal sandboxes
+- Docker or devcontainer setups where the client process is disposable but the workspace and state volume persist
+
+The core rule in `0.9.1` is simple:
+
+- clients should be short-lived
+- supervision should be long-lived
+- agent execution should be process-backed, not tmux-backed
+
+Wave now launches agents through detached process runners by default, which lowers tmux session churn and memory pressure compared with the old “every live agent owns a tmux session” shape. Tmux is now optional and dashboard-only.
+
+## Recommended Model
+
+For sandboxes, prefer the async supervisor surface:
+
+```bash
+pnpm exec wave submit ...
+pnpm exec wave supervise ...
+pnpm exec wave status ...
+pnpm exec wave wait ...
+pnpm exec wave attach ...
+```
+
+Use direct `wave launch` when:
+
+- you control a normal long-lived shell
+- the launcher process can stay alive for the whole run
+- you are doing local debugging or dry-run validation
+
+Do not bind a multi-hour wave to one short-lived sandbox client process.
+
+## Baseline Configuration
+
+Set the Codex sandbox default in `wave.config.json` for the lane or executor profile instead of retyping `--codex-sandbox` on every command.
+
+Typical sandbox-safe pattern:
+
+```json
+{
+  "executors": {
+    "codex": {
+      "sandbox": "workspace-write"
+    }
+  }
+}
+```
+
+Use a stricter mode such as `read-only` when the task truly should not write. Use `danger-full-access` only when the outer environment is already providing the isolation you want.
+
+Treat `tmux` as optional:
+
+- install it only if you want live dashboard attach
+- use `--no-dashboard` in constrained environments when you do not need the extra projection process
+
+## LEAPclaw / OpenClaw / Nemoshell Pattern
+
+In these environments, the common failure mode is a short-lived client exec timeout while the wave itself needs much longer.
+
+Preferred shape:
+
+1. A disposable client submits work.
+2. A durable daemon owns the run.
+3. Clients poll or wait observationally.
+
+Example:
+
+```bash
+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
+```
+
+Keep `wave supervise` alive outside the short-lived client call:
+
+- a long-lived host shell
+- a background service
+- a job runner that can outlive the client request
+
+If the sandbox only gives you short exec windows, `wave autonomous` should not be the thing owning the run. Use submit plus observe instead.
+
+## Docker And Containerized Setups
+
+Docker works well with the `0.9.1` process-backed runner model, but only if the state directories survive container restarts.
+
+Recommended container posture:
+
+- mount the repo root as a persistent volume
+- preserve `.tmp/` and `.wave/`
+- run `wave supervise` in a long-lived container or sidecar
+- use `wave submit/status/wait` from short-lived execs
+- disable dashboards unless the image actually includes `tmux` and you want the extra process
+
+Practical rules:
+
+- dashboard attach is optional; log-follow attach is enough for most sandbox automation
+- `wave attach --agent <id>` now follows the recorded log when no live interactive session exists
+- `wave attach --dashboard` falls back to the last written dashboard file when no live dashboard session exists
+
+## Terminal Surface Recommendations
+
+For constrained sandboxes:
+
+- `--terminal-surface vscode`
+  Good when the repo is local and the editor integration is useful.
+- `--terminal-surface tmux`
+  Good only when `tmux` is installed and you actually want live dashboard attach.
+- `--terminal-surface none`
+  Dry-run only.
+
+The important distinction is that terminal surface is now an operator preference, not the agent execution backend.
+
+## Validation Checklist
+
+Run these after setup changes:
+
+```bash
+pnpm exec wave doctor --json
+pnpm exec wave launch --lane main --dry-run --no-dashboard
+```
+
+For a sandboxed lane, also verify:
+
+- `wave submit --json` returns a `runId`
+- `wave status` and `wave wait` work with exact `--project` and `--lane`
+- the supervisor run tree exists under `.tmp/.../control/supervisor/runs/<runId>/`
+- dashboards are either intentionally disabled or intentionally backed by a real `tmux` install
+
+## When To Keep Using `wave launch`
+
+Use `wave launch` directly when:
+
+- you are on a normal workstation shell
+- the launcher can stay alive for the entire run
+- you want the fastest direct local workflow
+- you are debugging wave behavior and want the simplest path
+
+Use `wave submit` plus `wave supervise` when the surrounding environment, not the wave itself, is the unstable part.
+
+## Related Docs
+
+- [author-and-run-waves.md](./author-and-run-waves.md)
+- [terminal-surfaces.md](./terminal-surfaces.md)
+- [../reference/cli-reference.md](../reference/cli-reference.md)
+- [../plans/sandbox-end-state-architecture.md](../plans/sandbox-end-state-architecture.md)

package/docs/guides/terminal-surfaces.md

@@ -6,15 +6,16 @@ Wave has separate concepts for execution substrate and operator surface.
 
 The important detail is:
 
-- live runs use `tmux` sessions
-- terminal surfaces control how operators attach to those sessions
+- live agent runs use detached process runners
+- terminal surfaces control how operators follow logs and attach to dashboard projections
+- sandbox-safe submission and supervision are documented separately in [sandboxed-environments.md](./sandboxed-environments.md)
 
 ## The Three Terminal Surfaces
 
 - `vscode`
-  The launcher writes temporary entries to `.vscode/terminals.json` so VS Code can attach to the tmux sessions.
+  The launcher writes temporary entries to `.vscode/terminals.json` so VS Code can follow process-backed agent logs and attach to stable dashboard projections.
 - `tmux`
-  The launcher uses tmux only and never touches `.vscode/terminals.json`.
+  The launcher uses tmux only for dashboard and operator projection sessions and never touches `.vscode/terminals.json`.
 - `none`
   Dry-run only. No live terminal surface is allowed in this mode.
 
@@ -22,12 +23,12 @@ The important detail is:
 
 `vscode` is not a second process host. It is a convenience attachment surface.
 
-The actual live sessions still run in tmux. The VS Code terminal registry just exposes stable attach commands for those tmux sessions.
+The actual live agent work runs in detached processes. The VS Code terminal registry exposes stable log-follow commands for agents plus stable attach commands for dashboard projections.
 
 Use `vscode` when:
 
 - your main operator flow is inside VS Code
-- you want one-click attach behavior for agent sessions and dashboards
+- you want one-click attach behavior for agent logs and dashboards
 - touching `.vscode/terminals.json` is acceptable in the repo
 
 ## What `tmux` Really Means
@@ -47,7 +48,7 @@ By default the launcher can start per-wave dashboard sessions in tmux.
 
 Wave now maintains stable tmux attach targets for both the current-wave dashboard and the global dashboard on the lane socket.
 
-Wave-agent sessions and the resident orchestrator now also use stable per-wave tmux session names. A relaunch reuses the same session identity for that wave instead of creating a new run-tagged session name each time, which reduces stale session buildup after launcher crashes or interrupted retries.
+Wave agent execution no longer depends on tmux. `wave attach --agent` uses a live interactive session only when the runtime explicitly exposes one; otherwise it follows the recorded agent log or prints the terminal log tail.
 
 Use:
 
@@ -56,18 +57,18 @@ pnpm exec wave dashboard --lane main --attach current
 pnpm exec wave dashboard --lane main --attach global
 ```
 
-Those commands work for both `tmux` and `vscode` terminal surfaces because the live sessions still run on the lane tmux socket.
+Those commands work for both `tmux` and `vscode` terminal surfaces because the live dashboard projections still run on the lane tmux socket. If no live dashboard session exists, the attach command falls back to the last written dashboard JSON instead of failing immediately.
 
 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`
-  Disable the per-wave tmux dashboard session.
+  Disable the per-wave dashboard projection session.
 - `--cleanup-sessions`
-  Kill lane tmux sessions after each wave. This is the default.
+  Kill lane tmux dashboard and projection sessions after each wave. This is the default.
 - `--keep-sessions`
-  Preserve tmux sessions after the wave for inspection.
+  Preserve tmux dashboard and projection sessions after the wave for inspection.
 - `--keep-terminals`
   Keep temporary VS Code terminal entries instead of cleaning them up.
 
@@ -76,7 +77,8 @@ Important flags:
 - Use `vscode` for local interactive operator work when the temporary terminal registry is useful.
 - Use `tmux` for remote, CI-like, or editor-independent operation.
 - Use `none` only with `--dry-run`.
-- Prefer `wave dashboard --attach current|global` over manual `tmux -L <socket> attach ...` lookups.
+- In constrained sandboxes or containers, treat dashboards as optional and prefer `--no-dashboard` unless `tmux` is installed and you actually want the extra projection process.
+- Prefer `wave dashboard --attach current|global` over manual `tmux -L <socket> attach ...` lookups; it will fall back to the last written dashboard file when no live session exists.
 - Pair `--keep-sessions` with incident review or deep debugging, not as a default steady-state mode.
 - Pair `--no-dashboard` with scripted dry-runs or when the board and summaries are sufficient.