session-orchestrator 4.1.0 → 4.2.0

package/skills/session-start/references/phase-4-ssot-environment-check.md

@@ -69,11 +69,27 @@
 
    Additionally, invoke the instruction-budget probe (`scripts/lib/instruction-budget-guard.mjs`) via `checkInstructionBudget({ repoRoot })`. The helper returns `null` (silent no-op) when the always-on directive count is at or under the configured ceiling, or on any read failure. When a non-null result is returned (`{ severity: 'warn', message }`), render `result.message` alongside the other banners. Non-blocking. Cross-reference: "Instruction Budget Audit" (#687; archived in the private Meta-Vault).
 
-   Additionally, invoke the reconcile-nudge probe (`scripts/lib/reconcile-nudge-banner.mjs`) via `await checkReconcileNudge({ repoRoot, config: $CONFIG })`. The helper returns `null` (silent no-op) when `.orchestrator/metrics/learnings.jsonl` is missing/empty/all-malformed, when there are zero active learnings, or when none of its three nudge thresholds are met (≥20 active learnings with no reconcile run on record; >15 new learnings since the last determinable run; ≥3 rule-eligible learnings). Introduces NO new Session Config key — it reads the EXISTING `reconcile.enabled` key only to append an informational note, never to gate itself. When a non-null result is returned (`{ severity: 'warn', message }`), render `result.message` alongside the other banners:
-   - **Nudge fires**: `"⚠ reconcile-nudge: <N> active learnings, <E> rule-eligible, last reconcile run: <never|YYYY-MM-DD> — run /reconcile to convert learnings into rules."` plus, when `reconcile.enabled: false`, an additional line: `"(reconcile.enabled: false — banner is advisory only; /reconcile still runs on-demand.)"`
-   - **No nudge**: silent (no banner).
+   Additionally, invoke the maintenance-due probe (`scripts/lib/maintenance-due-banner.mjs`) via `await checkMaintenanceDue({ repoRoot, config: $CONFIG })`. This probe REPLACED the former `reconcile-nudge` entry in `scripts/lib/session-start-probes.mjs` (it reuses `computeReconcileNudge` wholesale as one of its six signals) AND the two retired session-end nudges — Phase 3.6.5 auto-dream and Phase 3.6.7 auto-dialectic — which asked the operator at close for work only a housekeeping session can do. Return contract: `null` (silent no-op) or `{ severity: 'warn', message }`; never throws. `computeMaintenanceDue` exposes the same computation without the banner suppression.
 
-   Non-blocking. Cross-reference: `scripts/lib/reconcile/engine.mjs` (`runReconcile`), `scripts/lib/reconcile/idempotency.mjs` (`.orchestrator/runtime/reconcile-candidates.jsonl` — the last-run provenance source), `skills/reconcile/SKILL.md`, and issue #723.
+   The six signals (`MAINTENANCE_TOTAL_SIGNALS = 6`), each side-effect-free:
+
+   | id | due when | source |
+   |---|---|---|
+   | `evolve` | no `orchestrator.evolve.completed` on record AND ≥ `MAINTENANCE_MIN_LEARNINGS` (20) active learnings | `events.jsonl` + `computeReconcileNudge` |
+   | `sweep` | the dry-run expiry sweep would archive ≥ 1 entry | `scripts/lib/learnings/expiry-sweep.mjs` |
+   | `reconcile` | `computeReconcileNudge().nudge === true` | `scripts/lib/reconcile-nudge-banner.mjs` (reused whole) |
+   | `dialectic` | `shouldDispatchAutoDialectic().trigger === true` | `scripts/lib/auto-dialectic.mjs` — the side-effect-free decision function; a variant that advanced the last-run stamp would consume the signal it reports (the former recording wrapper was removed in #1288) |
+   | `memory-cleanup` | `shouldDispatchAutoDream().trigger === true` | `scripts/lib/auto-dream.mjs` |
+   | `pending-sidecar` | an unapplied pending dream/dialectic proposal younger than `SIDECAR_MAX_AGE_DAYS` (14) | `.orchestrator/*-pending*.md` |
+
+   Introduces NO new Session Config key — every threshold is an existing key or an existing module constant.
+
+   - **Nothing due and everything readable**: silent (no banner).
+   - **A housekeeping session completed within `HOUSEKEEPING_COOLDOWN_DAYS` (7) days**: silent, even when signals are due — the operator already did the thing the banner would ask for. This cooldown is what keeps the instrument rare (HR-101, `.claude/rules/host-resources.md`); the housekeeping session's own record IS the last-maintenance stamp.
+   - **Otherwise**: render `result.message`, shaped as `⚠ maintenance due: <N> of 6 (<id>: <detail> · <id>: <detail>) — run /session housekeeping.` Every due signal carries the number or date that made it due (HR-106) — no aggregate stands alone.
+   - **Unreadable inputs** append an ` · undeterminable: <id>, <id>` suffix before the `— run /session housekeeping.` tail. A signal whose inputs cannot be read is three-state: never folded into "clean" (the `never` vs `undeterminable` discipline inherited from `reconcile-nudge-banner.mjs`).
+
+   Non-blocking. Cross-reference: `scripts/lib/reconcile-nudge-banner.mjs` (`computeReconcileNudge`), `scripts/lib/reconcile/engine.mjs` (`runReconcile`), `skills/reconcile/SKILL.md`, `skills/session-start/SKILL.md` Phase 7 (the housekeeping maintenance loop the banner routes to), and issues #723 / #1200.
 
    Additionally, invoke the sessions-staleness probe (`scripts/lib/sessions-staleness-banner.mjs`) via `checkSessionsStaleness({ repoRoot })` (synchronous — no await). This detects the "close-through" gap: sessions that end without ever writing a `.orchestrator/metrics/sessions.jsonl` ledger record. It returns `null` (silent no-op) when `.orchestrator/metrics/sessions.jsonl` or `.orchestrator/metrics/events.jsonl` are absent or all-malformed, when no foreign (pre-session) event exists, or when the gap between the last ledger entry and the newest foreign event is at or under the warn threshold. When a non-null result is returned (`{ severity, message }`), render `result.message` alongside the other banners:
    - **warn** (gap > 8h): `"⚠ sessions-staleness: last sessions.jsonl entry <ISO> is <N>h behind pre-session events.jsonl activity <ISO> — possible close-through gap (sessions ended without a ledger record; run node scripts/backfill-abandoned-sessions.mjs --dry-run)."`
@@ -156,5 +172,5 @@
 
    Non-blocking. Cross-reference: `scripts/lib/vcs-repo-spec.mjs` (`isQueryFailure` — the same absence-vs-query-failure split this probe's `degraded` state implements).
 
-   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `reconcile-nudge-banner.mjs` is absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `sessions-integrity-banner.mjs` is absent (pre-#958 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install) or `claude-md-budget-lint.mjs` is absent (pre-#878 plugin install) or `mirror-issues-banner.mjs` is absent (pre-#1022 plugin install), skip silently.
+   All banners are non-blocking — display in the Session Overview, do not halt the session. If `bootstrap-lock-freshness.mjs` is absent (pre-#186 plugin install) or `peer-cards/staleness-banner.mjs` is absent (pre-#503 plugin install) or `loop-readiness-banner.mjs` is absent (pre-#633 plugin install) or `instruction-budget-guard.mjs` is absent (pre-#687 plugin install) or `maintenance-due-banner.mjs` / `reconcile-nudge-banner.mjs` are absent (pre-#723 plugin install) or `sessions-staleness-banner.mjs` is absent (pre-#724 plugin install) or `sessions-integrity-banner.mjs` is absent (pre-#958 plugin install) or `owner-config-banner.mjs` is absent (pre-#820 plugin install) or `moc-staleness-banner.mjs` / `context-coverage-banner.mjs` are absent (pre-#831 plugin install) or `claude-md-budget-lint.mjs` is absent (pre-#878 plugin install) or `mirror-issues-banner.mjs` is absent (pre-#1022 plugin install), skip silently.
 

package/skills/session-start/references/phase-6-7-memory-banner-telemetry-consent.md

@@ -99,5 +99,7 @@ Setting `telemetry:\n  enabled: true` in the host-local `~/.config/session-orche
 
 The decision persists host-locally in `~/.config/session-orchestrator/telemetry.json`; once `consent` is non-`null` (granted or denied), `resolveConsent().prompt` stays `false` and this phase never fires again on that host — no repeat prompting across repos or sessions.
 
-Cross-reference: GitLab #845 (Epic #841); `docs/prd/2026-07-20-anonymous-usage-telemetry.md` §3 FA1/FA5; `docs/telemetry.md`; consent API in `scripts/lib/telemetry/consent.mjs` (`resolveConsent`, `grantConsent`, `denyConsent`, `isHeadless`, `readTelemetryState`).
+Cross-reference: GitLab #845 (Epic #841); `docs/telemetry.md`; consent API in `scripts/lib/telemetry/consent.mjs` (`resolveConsent`, `grantConsent`, `denyConsent`, `isHeadless`, `readTelemetryState`).
+
+Historical design: archived PRD `docs/prd/2026-07-20-anonymous-usage-telemetry.md` §3 FA1/FA5. <!-- path-check: historical -->
 

package/skills/test-runner/rubric-v1.md

@@ -316,14 +316,14 @@ indicates a translucent/blurred background that uses:
 - `.glassEffect()` — correct Liquid Glass API
 - `.glassEffect(.regular)` / `.glassEffect(.prominent)` — parametrised Liquid Glass
 - Solid color backgrounds (no blur) — these are not Liquid Glass candidates
-- Explicitly documented exceptions in `docs/apple-hig-exceptions.md`
+- Explicitly documented exceptions in `docs/apple-hig-exceptions.md` <!-- path-check: example -->
 
 **Severity mapping:**
 
 | Condition | Severity |
 |---|---|
 | Non-compliant surface, no documented exception | MEDIUM |
-| Non-compliant surface, documented exception in `docs/apple-hig-exceptions.md` | LOW |
+| Non-compliant surface, documented exception in `docs/apple-hig-exceptions.md` | LOW <!-- path-check: example --> |
 
 **Evidence required:**
 - Peekaboo screenshot of the non-compliant surface (referenced in `evidence_path`).

package/skills/wave-executor/SKILL.md

@@ -87,6 +87,8 @@ Before starting the first wave (Discovery role):
    - `persistence` (default: true), `enforcement` (default: warn), `isolation` (default: auto)
    - `agents-per-wave` (default: 6), `max-turns` (default: auto), `pencil` (default: null)
    
+   **Neither `agents-per-wave` nor `max-turns` carries its own default here.** The per-wave `agentCap` and `maxTurns` come from the RESOLVED SHAPE (`node scripts/session-shape.mjs --repo-root "$PWD" --session-type <session-type> [--profile <session-profile>] [--known-scope true|false]`, module `scripts/lib/session-shape.mjs`) — that is the one place a session mode becomes an execution shape. Session Config's `agents-per-wave` (with its per-type override, e.g. `6 (deep: 18)`) CLAMPS the shape's `agentCap`; `max-turns: auto` is expanded per type inside the shape, not in this file.
+   
    **Execution Config shortcut:** If the session-plan output contains an `### Execution Config` section, its execution-level fields (waves, agents-per-wave, isolation, enforcement, max-turns) take precedence over `$CONFIG`. Session-level fields (persistence, pencil) always come from `$CONFIG`. If the Execution Config section is missing, use `$CONFIG` alone.
 6. **Initialize session metrics** (if `persistence` enabled): Prepare a metrics tracking object for this session:
    - `session_id`: `<branch>-<YYYY-MM-DD>-<HHmm>` (HHmm from `started_at` — ensures uniqueness across multiple sessions per day)
@@ -152,6 +154,19 @@ Wave 0 — Initializing
 
 Create the `<state-dir>` directory if needed (`mkdir -p <state-dir>`) before writing. This file is the persistent state record — other skills and resumed sessions read it.
 
+**Then VALIDATE `total-waves` against the resolved shape — do not skip this.** A plan whose wave count the shape does not produce must never be dispatched silently:
+
+```bash
+node scripts/session-shape.mjs --repo-root "$PWD" \
+  --session-type <session-type> [--profile <session-profile>] [--known-scope true|false] \
+  --no-event | jq .totalWaves
+```
+
+`--no-event` is used HERE because the plan-time run already recorded `orchestrator.session.shape_resolved` — this is a re-read, not a second resolution. Compare the printed number with the plan's wave count (the value just written to `total-waves`):
+
+- **Equal** → continue to Wave 1.
+- **Mismatch** → STOP. Surface it via `AskUserQuestion` per `.claude/rules/ask-via-tool.md`, with the shape's number and the plan's number both in the option descriptions: **re-plan to the shape (Recommended)** — rebuild the wave plan at the shape's wave count, the only outcome that keeps STATE.md, the ledger and the dispatch loop describing the same session — versus **proceed with a logged Deviation**, which requires appending the divergence to STATE.md `## Deviations` (`appendDeviationOnDisk()` from `scripts/lib/state-md.mjs`) before the first dispatch.
+
 #### Pre-Wave 1b Extension: Docs Tasks Persistence (A3 / #230)
 
 After writing the base STATE.md frontmatter above, conditionally persist the docs tasks block emitted by session-plan:
@@ -227,7 +242,7 @@ Claude Code's `Agent` tool with `isolation: "worktree"` changes `process.cwd()`
 
 **Rules for the coordinator (this is YOU during wave execution):**
 
-1. **After every Agent() dispatch** (before reading its output), call `restoreCoordinatorCwd()` from `scripts/lib/worktree.mjs`. `wave-loop.md § 2` makes this explicit.
+1. **After every Agent() dispatch** (before reading its output), call `restoreCoordinatorCwd()` from `scripts/lib/workspace.mjs`. `wave-loop.md § 2` makes this explicit.
 2. **Prefer absolute file paths** for Read/Edit/Write tool calls. A drifted CWD turns relative paths into silent cross-tree writes.
 3. **Before any Bash git command**, either `cd` inside a subshell (`cd /path && cmd`) or rely on `git -C /path <cmd>`. Do not assume CWD.
 4. **Verify at checkpoints** — when in doubt, run `git rev-parse --show-toplevel` to confirm which tree is currently active.
@@ -302,29 +317,44 @@ Cross-reference: PRD F2.1 / issue #501 / `docs/memory-proposal-flow.md` (coordin
 
 ## Session Type Behavior
 
-### Housekeeping Sessions
+### Housekeeping Sessions — the Maintenance Loop
+
+A housekeeping session is **ONE coordinator-direct wave**, not a shrunken multi-wave run: `node scripts/session-shape.mjs --repo-root "$PWD" --session-type housekeeping --no-event` resolves to `totalWaves: 1` with that wave's `coordinatorDirect: true` and `writes: true`. "Coordinator-direct" means **no wave-executor dispatch loop** — it does not mean zero subagents (`/evolve dialectic` dispatches the read-only `dialectic-deriver`).
+
+**Ordered default scope — the maintenance loop.** Run it in this order, before the session's selected issues:
+
+| # | Run | Gate | Artefact that proves it ran |
+|---|---|---|---|
+| 1 | `claude-md-drift-check` | unconditional | checker JSON (`errors`/`warnings` counts) |
+| 2 | expired-learnings sweep | unconditional | `orchestrator.learnings.sweep_applied` |
+| 3 | `/evolve analyze` | AUQ-gated (the operator approves the proposed learnings) | `orchestrator.evolve.completed` |
+| 4 | `/reconcile` | AUQ-gated (rule proposals are never applied unasked) | `orchestrator.reconcile.completed` with `dry_run: false` |
+| 5 | `/evolve dialectic` | AUQ-gated (the derived thesis is presented, not committed) | `orchestrator.dialectic.completed` |
+| 6 | `/memory-cleanup` | AUQ-gated (deletions are operator-approved) | `orchestrator.memory.cleanup_completed` |
+
+The session-start probe `maintenance-due` (`scripts/lib/maintenance-due-banner.mjs`) says which of these are DUE for this repo; a run that is not due may be skipped, and the skip is reported. An AUQ-gated run the operator declines is reported as declined — never as done. **Absence of the artefact event is the only evidence that counts**: a run claimed in prose without its event is not a run (`.claude/rules/verification-before-completion.md`).
 
-Housekeeping sessions use a simplified single-wave execution model instead of the multi-wave role-based dispatch:
+Then the mechanics:
 
 1. Initialize STATE.md as normal (`session-type: housekeeping`, `total-waves: 1`)
-2. Do NOT create `wave-scope.json` — scope enforcement is not needed for low-risk housekeeping tasks
-3. Dispatch tasks serially with 1-2 agents per task
+2. Do NOT create `wave-scope.json` — there is no agent fan-out to constrain; the coordinator's own edits stay governed by its `coordinator.json` record
+3. Execute the maintenance loop above, then the session's selected issues, serially as coordinator actions
 4. Run Baseline quality checks after all tasks complete (not between tasks)
 5. Skip session-reviewer dispatch — housekeeping changes are low-risk
 6. Do NOT update STATE.md to `status: completed` — that write is reserved for session-end per state-ownership contract (`skills/_shared/state-ownership.md`). Leave `status: active`.
 7. Proceed directly to session-end (`/close`)
 
-Focus: git cleanup, SSOT refresh, CI fixes, branch merges, documentation.
+Beyond the loop: git cleanup, SSOT refresh, CI fixes, branch merges, documentation.
 End with a single commit summarizing all housekeeping work.
 
 ### Feature Sessions
-- Full wave execution (5 roles mapped to configured wave count)
-- 4-6 agents per wave (read from Session Config)
+- **3 waves** (Impl-Core → Impl-Polish+Quality → Finalization) with **no Discovery wave** — read them from the shape, not from this file: `node scripts/session-shape.mjs --repo-root "$PWD" --session-type feature --no-event`
+- Per-wave agent caps come from the shape's `agentCap` (the shape caps a feature wave at 4), clamped by Session Config `agents-per-wave`
 - Balance between implementation speed and quality
 
 ### Deep Sessions
-- Full wave execution (5 roles mapped to configured wave count)
-- Up to 10-18 agents per wave (read from Session Config)
+- **5 waves** from the shape (`--session-type deep`); the **Discovery wave is conditional** — pass `--known-scope true` when the scope is already established and the shape drops Discovery, leaving 4 waves
+- Per-wave agent caps come from the shape's `agentCap`, clamped by Session Config `agents-per-wave` with its per-type override (this repo: `agents-per-wave: 6 (deep: 18)`)
 - Extra emphasis on Discovery role and Quality role
 - May include security audits, performance profiling, architecture refactoring
 
@@ -332,9 +362,9 @@ End with a single commit summarizing all housekeeping work.
 
 Not a fourth session type — a PROFILE over `session-type: deep`, resolved from the `/session ultradeep` argument alias (`commands/session.md`). Everything below applies only when STATE.md frontmatter carries `session-profile: ultradeep`; every other behaviour in this skill is unchanged, because downstream still reads `deep`. Full spec — wave table, mandatory artefacts, cost model: `docs/prd/2026-09-06-ultradeep-session-profile.md`.
 
-- **7 waves**, per `skills/session-plan/SKILL.md` § Role-to-Wave Mapping: Research+Code-Discovery → Synthesis-Gate → Impl-Core → Impl-Polish → Review-Panel → Quality → Release/Finalization.
+- **The wave count and the wave roles come from the shape**, not from this file: `node scripts/session-shape.mjs --repo-root "$PWD" --session-type deep --profile ultradeep --no-event` returns `totalWaves: 7` (Research+Code-Discovery → Synthesis-Gate → Impl-Core → Impl-Polish → Review-Panel → Quality → Release/Finalization) and reports `wavesConfigHonored: false` with the ignored Session Config `waves` value — the profile OWNS its wave count. Role narrative: `skills/session-plan/SKILL.md` § Role-to-Wave Mapping.
 - **Wave 2 is coordinator-direct and dispatches ZERO agents.** Make NO `Agent()` call in this wave. The coordinator consolidates wave 1 into `docs/audits/<YYYY-MM-DD>-<slug>.md`, updates STATE.md, and asks ONE **blocking** `AskUserQuestion` (confirm scope / narrow / abort) per `.claude/rules/ask-via-tool.md`. Wave 3 does not start until that question is answered — this is the one gate the profile exists for, so a silent "no tasks, skip it" is a defect, not an optimisation (`skills/session-plan/SKILL.md` § Empty roles, coordinator-direct exception).
-- **`max-turns` per ROLE, not per session:** 40 for Research/Code-Discovery (wave 1), 25 for the implementing waves (3, 4, and the writing part of 6/7), 15 for Release/Finalization. Set it on the dispatch; the Session Config `max-turns` value is the fallback when a role has no entry here.
+- **`max-turns` is per ROLE, and the numbers live in the shape:** take each wave's value from `waves[].maxTurns` in the shape output above (the Research, implementing and Release/Finalization figures are produced there, not restated here). Set it on the dispatch; a wave whose `maxTurns` is `null` is coordinator-direct and dispatches nothing.
 - **Web tools are role-bound.** Research agents in wave 1 receive `WebSearch` and `WebFetch`. **No write-capable agent may receive them** — not in wave 1's Code-Discovery half, and not in any later wave. The grant follows the READ-ONLY property, so the pairing "has Write/Edit" + "has WebSearch/WebFetch" must never occur in a single dispatch. Research findings carry URL + retrieval date, the web analogue of the PSA-006 evidence rule (`.claude/rules/parallel-sessions.md`).
 - **Budgets are not implemented.** The PRD's `ultradeep.max-*` block (§ 7) is deferred until three runs have been measured (HR-105: no threshold without a firing rate). Nothing reads such a key today — do not invent one, and do not gate a wave on it.
 

package/skills/wave-executor/circuit-breaker.md

@@ -4,7 +4,7 @@ Sub-reference for the wave-executor skill. Defines safety mechanisms for agent e
 
 ## Circuit Breaker
 
-1. **MaxTurns enforcement**: Read `max-turns` from Session Config (default: auto — housekeeping=8, feature=15, deep=25). Include this instruction in EVERY agent prompt:
+1. **MaxTurns enforcement**: Read the wave's `maxTurns` from the resolved shape (`scripts/session-shape.mjs` / `scripts/lib/session-shape.mjs`; a Session Config `max-turns: auto` is expanded per session type THERE, not here). Include this instruction in EVERY agent prompt:
    ```
    TURN LIMIT: You have a maximum of [N] turns. If you cannot complete within [N] turns, report PARTIAL with what you accomplished and what remains.
    ```
@@ -93,6 +93,8 @@ The function never throws — it always returns a result object. Treat `skipped:
    | 3–4 | feature / deep | `worktree` |
    | ≥ 5 | any | `worktree` |
 
+   `sessionType` for `resolveIsolation` comes from the resolved shape (the same `session-type` the shape was resolved for), not from a value re-derived at dispatch time.
+
    Rationale: the verified learning `coordinator-over-worktree-on-shared-files` (confidence 0.75) shows that small waves on partitioned scopes merge cleaner when run in-place. Two consecutive deep-session regressions (2026-04-20 07:30, 09:00) were worktree base-ref staleness on ≤2-agent waves editing the same SKILL.md. Graduated default makes worktree the tool for parallelism, not the default tax on every wave.
 
 2. **Enforcement auto-promote (#194)**: Call `resolveEnforcement({ isolation, configEnforcement })` from the same module. When isolation resolves to `none` and the user has not explicitly set `configEnforcement: 'off'`, enforcement auto-promotes from `warn` → `strict`. Worktrees provide filesystem-level isolation; in-place dispatch relies on the scope hook as the only barrier — it must be hard, not informational. Write the resolved value into `wave-scope.json` `enforcement`.

package/skills/wave-executor/references/wave-loop-dispatch.md

@@ -113,7 +113,7 @@ When `worker-pool.enabled: true` in Session Config, dispatch via `runWavePool()`
 
 Use the **Agent tool** to dispatch this wave's agents. **`run_in_background: true` is the PLATFORM DEFAULT for wave dispatch, not a deviation of ours** — since Claude Code **2.1.232**, non-teammate agent spawns default to background in interactive sessions. Our own measurement 2026-08-22 (v2.1.239) is why that default is the right one for a wave: under blocking dispatch the coordinator was 143 s incapable of acting between an agent's mid-run escalation and its own next turn — escalation latency equals the batch's remaining runtime. Background dispatch returns turns to the coordinator between agent completions; a running agent received a queued message mid-run and answered ~9 min before its final report.
 
-Dispatch in **SMALL BATCHES of 3–4 Agent() calls per message** (cumulative up to the wave's `agents-per-wave` cap). Large single-message fan-outs (>4 Agent() calls in one message) remain **FORBIDDEN** — fleet evidence (conf 1.0, 5 sessions) shows they drop Agent() calls SILENTLY (the coordinator receives fewer results than it dispatched, with no error), whereas serial / small-batch dispatch held 13/13 and 8/8. That evidence PREDATES backgrounding and is untouched by it; what backgrounding changes is the *cost* of batching, which is now near zero — a background batch returns its launch acks immediately, so batches no longer serialize the wave. Dispatch a batch, let its acks return, then dispatch the next, until every planned agent is started; then run **Started-Set Verification** below. See `docs/specs/2026-07-02-fleet-mining-followup-grill.md` (C4) for the batching-policy rationale. The `worker-pool.enabled: true` path (above) is the mechanised opt-in alternative to manual batching.
+Dispatch in **SMALL BATCHES of 3–4 Agent() calls per message** (cumulative up to the wave's `agents-per-wave` cap). Large single-message fan-outs (>4 Agent() calls in one message) remain **FORBIDDEN** — fleet evidence (conf 1.0, 5 sessions) shows they drop Agent() calls SILENTLY (the coordinator receives fewer results than it dispatched, with no error), whereas serial / small-batch dispatch held 13/13 and 8/8. That evidence PREDATES backgrounding and is untouched by it; what backgrounding changes is the *cost* of batching, which is now near zero — a background batch returns its launch acks immediately, so batches no longer serialize the wave. Dispatch a batch, let its acks return, then dispatch the next, until every planned agent is started; then run **Started-Set Verification** below. The archived, private spec `docs/specs/2026-07-02-fleet-mining-followup-grill.md` (C4) records the batching-policy rationale. The `worker-pool.enabled: true` path (above) is the mechanised opt-in alternative to manual batching. <!-- path-check: historical -->
 
 **What is NOT the reason for 3–4 (platform caps, as of Claude Code 2.1.232).** The batch size defends against the SILENT DROP measured above. It is not, and never was, a workaround for a platform concurrency limit — and the upstream numbers no longer permit reading it as one: **2.1.217** set the concurrent-subagent cap to **20** (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`), **2.1.219** set subagent nesting depth to **3**, **2.1.224** REMOVED the former 200-spawn-per-session cap, and **2.1.232** made background the spawn default (above). So neither 3–4, nor `agents-per-wave: 6`, nor `deep: 18` sits anywhere near a platform ceiling; the only ceiling a wave can actually reach is the concurrency cap of 20, and only through the worker-pool `maxParallel` path. The rule stays at 3–4 because the drop evidence is about how many `Agent()` calls survive ONE assistant message — a question no version bump has addressed. **Revisit-Trigger:** a measurement showing a >4-call single message delivering 100% of its calls. A raised cap is not that measurement. Version provenance: `docs/audits/2026-09-06-360-audit/w1/d9-claude-code-fable.md` (FA-6, 2026-09-06).
 
@@ -123,6 +123,8 @@ After resolving `isolation`, compute the wave's enforcement via `resolveEnforcem
 
 Before dispatching, verify the wave's agent count does not exceed `$CONFIG.agents-per-wave` — if it does, warn the user and request plan revision.
 
+`sessionType` for `resolveIsolation` is the session type the shape was resolved for, and the wave's `coordinatorDirect` and `writes` flags are READ FROM the shape's wave entry (`scripts/session-shape.mjs` → `waves[]`) rather than inferred from the role name. The dispatch-side marker is unchanged: the coordinator still keys the table below on `coordinator-direct: true` in the wave-plan item — the shape says which waves are expected to carry it, the plan item is what the coordinator acts on.
+
 **Coordinator-direct waves (`coordinator-direct: true`) dispatch NOTHING — and that is not a silent drop.** Keyed on the marker, never on a profile name (`skills/session-plan/SKILL.md` keys its matching empty-role exception the same way), so any future coordinator-direct wave inherits this:
 
 | Step | Behaviour when the wave-plan item carries `coordinator-direct: true` |
@@ -480,7 +482,7 @@ After `wave-scope.json` is written for this wave and before assembling the `Agen
 
 **Gate:** runs when `.claude/rules/` exists. When it does not, the CLI prints nothing and exits 0 — zero behaviour change. This step never blocks dispatch: any non-zero exit or empty output means "inject nothing, continue" (same best-effort framing as Pre-Dispatch Grounding Injection above).
 
-**Per-wave scoping (not per-agent):** the rule set is computed ONCE per wave from the wave's `allowedPaths` union (the same `wave-scope.json` source used elsewhere), not per agent. The CLI resolves `scopePaths` from `allowedPaths`, `mode` from the `session-type:` frontmatter in `.claude/STATE.md`, and `hostClass` from `.orchestrator/host.json` — all overridable, all degrading to "no gating" when unreadable.
+**Per-wave scoping (not per-agent):** the rule set is computed ONCE per wave from the wave's `allowedPaths` union (the same `wave-scope.json` source used elsewhere), not per agent. The CLI resolves `scopePaths` from `allowedPaths`, `mode` from the `session-type:` frontmatter in the active harness's `STATE.md`, and `hostClass` from `.orchestrator/host.json` — all overridable, all degrading to "no gating" when unreadable. Default state and scope paths resolve independently: state-directory override first, then active-harness and legacy fallback.
 
 **Invocation:** once per wave, run from the repo root and capture stdout as `$RULES_BLOCK`:
 

package/skills/wave-executor/references/wave-loop-review.md

@@ -9,7 +9,7 @@
 **Step 2.0 — Restore coordinator CWD (#219):** BEFORE reading any agent output or running any quality check, restore the coordinator's working directory. Claude Code's `Agent` tool with `isolation: "worktree"` `chdir()`s into each worktree internally and does NOT restore it on agent return. Subsequent Edit/Write/Bash calls would silently route to whichever worktree's tree CWD last drifted into.
 
 ```js
-import { restoreCoordinatorCwd } from '$PLUGIN_ROOT/scripts/lib/worktree.mjs';
+import { restoreCoordinatorCwd } from '$PLUGIN_ROOT/scripts/lib/workspace.mjs';
 
 const cwd = await restoreCoordinatorCwd();
 if (cwd.restored) {

package/skills/wave-executor/references/wave-loop-scope-manifest.md

@@ -61,13 +61,13 @@ Before each wave dispatch:
 2. Validate by piping through `node "$PLUGIN_ROOT/scripts/validate-wave-scope.mjs"` (`$PLUGIN_ROOT` — see "Shell variables used in this section" above). If validation fails (exit 1), fix the JSON based on stderr errors and retry.
 3. **`allowedPaths` is COMPUTED from one canonical declaration array — never hand-transcribed (#1020/#1083).** Transcribing either declaration shape or the union by hand produced scope divergences. Globs stay verbatim (`scripts/*.sh`) — the enforcement hook resolves them at check time.
 
-   **3.1 — materialize both declaration shapes once.** Build one JSON array from the session plan, one `{id, files}` record for every agent plus exactly one `coordinator` record for the coordinator's planned direct edits. `files` arrays, their entries and their order are the plan's verbatim declarations. Materialize it ONCE and capture the aggregate-sidecar path:
+   **3.1 — materialize both declaration shapes once.** Build one JSON array from the session plan, one `{id, files}` record for every agent plus exactly one `coordinator` record for the coordinator's planned direct edits. `files` arrays, their entries and their order are the plan's verbatim declarations. Run from the **project root**, materialize it ONCE and capture the aggregate-sidecar path:
 
    ```bash
    WAVE_SCOPE_RECORDS='[{"id":"W3-I1","files":["scripts/example.mjs"]},{"id":"coordinator","files":["skills/wave-executor/wave-loop.md"]}]'
    WAVE_SCOPES_SIDECAR="$(
      printf '%s' "$WAVE_SCOPE_RECORDS" | node "$PLUGIN_ROOT/scripts/materialize-wave-scope.mjs" \
-       --state-dir "$STATE_DIR" --wave "$WAVE"
+       --state-dir "$STATE_DIR" --wave "$WAVE" --warn-missing
    )"
    [ -n "$WAVE_SCOPES_SIDECAR" ] || { echo "materialize-wave-scope produced no sidecar path" >&2; exit 1; }
    ```
@@ -81,6 +81,10 @@ Before each wave dispatch:
 
    `materialize-wave-scope.mjs` validates the COMPLETE input before writing; it writes `<state-dir>/filescopes/wave-<N>/<agent-id>.json` as each bare `files` array first, then writes `<state-dir>/filescopes/wave-<N>.scopes.json` as the unchanged aggregate record array last. Its human stdout is only that final sidecar path, so the command substitution above is the canonical `$WAVE_SCOPES_SIDECAR`. On error, do not continue with a partial declaration set; correct the plan and run the one command again.
 
+   **Check missing-path warnings before dispatch (#1235).** The recipe opts into `--warn-missing`: each absent concrete path is named with its agent on stderr. Relative paths resolve from the current project working directory, never from `$STATE_DIR`. A warning does not fail materialization or alter stdout, declaration bytes, ordering, or session binding. Grants containing `*` or ending in `/` retain their existing glob/prefix meaning and are skipped; `?` and braces remain literal path characters.
+
+   For each file the plan intentionally creates, append **`--new-file PATH`**, repeating the option for multiple files. Each exception must exactly match a path already declared in a `files` array and pass the same path validation. Invalid or undeclared exceptions fail before any scope file is written, even without `--warn-missing`. This explicit declaration suppresses only that path's warning; the materializer never guesses a filename or rewrites a grant. Without `--warn-missing`, existing callers keep their quiet missing-path behavior.
+
    The per-agent path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and File-Scope Injection (#1020) consume. Never write a `$TMPDIR` copy: it degrades to a signal-free allow when an injector cannot find the addressable wave-keyed file. The coordinator's record is materialized as `coordinator.json` and included in the aggregate, so its direct edits are covered by the two checks below.
 
    > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs before the union exists, so writing these files reports `bash-write-verify: N file(s) changed by a Bash call OUTSIDE the wave's allowedPaths` naming `filescopes/wave-<N>/*.json`. Expected once per wave rollover at this step; it is information, not a scope violation. Never widen `allowedPaths` to silence it — that would grant agents write access to the deconfliction record itself.

package/templates/nextjs-minimal/package.json

@@ -22,6 +22,6 @@
     "eslint": "^9.0.0",
     "eslint-config-next": "^15.3.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.1.0"
+    "vitest": "^4.1.11"
   }
 }

package/templates/node-minimal/package.json

@@ -16,6 +16,6 @@
     "eslint": "^9.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.1.0"
+    "vitest": "^4.1.11"
   }
 }

package/scripts/lib/multi-provider-build/providers.mjs

@@ -1,64 +0,0 @@
-/**
- * scripts/lib/multi-provider-build/providers.mjs
- *
- * Provider configuration for the single-source → many-provider build PoC.
- *
- * Scope: the THREE harnesses session-orchestrator actually targets
- * (Claude Code primary, Codex CLI, Cursor IDE). Inspired by pbakaus/impeccable's
- * 12-provider build (Apache-2.0) — we deliberately keep the templating mechanic
- * and drop the 12-provider breadth (maintenance ≫ value for providers with ~0
- * users; see the linked backlog issue's overengineering verdict).
- *
- * Each provider entry:
- *   {
- *     key,            // canonical id used in build output paths
- *     tags,           // <tag> block markers this provider keeps (rest are stripped)
- *     configDir,      // on-disk harness dir
- *     placeholders: { model, configFile, commandPrefix, askInstruction }
- *   }
- */
-
-/** @typedef {{key:string, tags:string[], configDir:string, placeholders:{model:string, configFile:string, commandPrefix:string, askInstruction:string}}} ProviderConfig */
-
-/** @type {Record<string, ProviderConfig>} */
-export const PROVIDERS = {
-  'claude-code': {
-    key: 'claude-code',
-    tags: ['claude-code', 'claude'],
-    configDir: '.claude',
-    placeholders: {
-      model: 'Claude',
-      configFile: 'CLAUDE.md',
-      commandPrefix: '/',
-      askInstruction: 'STOP and call the AskUserQuestion tool to clarify.',
-    },
-  },
-  codex: {
-    key: 'codex',
-    tags: ['codex'],
-    configDir: '.codex',
-    placeholders: {
-      model: 'GPT',
-      configFile: 'AGENTS.md',
-      commandPrefix: '$',
-      askInstruction: "STOP and use Codex's structured user-input tool to clarify.",
-    },
-  },
-  cursor: {
-    key: 'cursor',
-    tags: ['cursor'],
-    configDir: '.cursor',
-    placeholders: {
-      model: 'the model',
-      configFile: '.cursorrules',
-      commandPrefix: '/',
-      askInstruction: 'ask the user directly to clarify before proceeding.',
-    },
-  },
-};
-
-/** The full set of recognized provider block tags across ALL providers. */
-export const ALL_BLOCK_TAGS = new Set(Object.values(PROVIDERS).flatMap((p) => p.tags));
-
-/** Provider keys in a stable order. */
-export const PROVIDER_KEYS = Object.keys(PROVIDERS);

package/scripts/lib/multi-provider-build/templating.mjs

@@ -1,130 +0,0 @@
-/**
- * scripts/lib/multi-provider-build/templating.mjs
- *
- * Single-source → many-provider templating (PoC). One source document with
- * provider-conditional blocks + placeholders renders to a provider-specific
- * artifact. This replaces the "maintain N near-identical copies by hand" model
- * our codex-install.mjs / cursor-install.mjs currently imply.
- *
- * Two primitives (clean-room reimplementation of impeccable's mechanic):
- *   1. compileProviderBlocks(content, activeTags)
- *        <codex> … </codex> blocks: keep body iff the tag is active, else drop.
- *        Unknown tags are left untouched (so real HTML/JSX isn't mangled).
- *   2. replacePlaceholders(content, providerKey, opts)
- *        {{model}} {{config_file}} {{command_prefix}} {{ask_instruction}}
- *        {{available_commands}} substitution + optional /cmd → $cmd rewrite.
- *
- * renderForProvider() composes both in the correct order (blocks first, then
- * placeholders — matching impeccable's pipeline).
- */
-
-import { PROVIDERS, ALL_BLOCK_TAGS } from './providers.mjs';
-
-/**
- * Keep `<tag>…</tag>` blocks whose tag is in `activeTags`; strip the rest.
- * Only tags in `knownTags` are treated as conditional blocks — any other
- * `<foo>…</foo>` (e.g. real markup) is left exactly as-is.
- *
- * Tags must sit on their own line, e.g.:
- *   <codex>
- *   Codex-only text.
- *   </codex>
- *
- * @param {string} content
- * @param {Iterable<string>} activeTags
- * @param {Iterable<string>} [knownTags] — defaults to ALL_BLOCK_TAGS
- * @returns {string}
- */
-export function compileProviderBlocks(content, activeTags, knownTags = ALL_BLOCK_TAGS) {
-  const active = new Set(activeTags);
-  const known = new Set(knownTags);
-  let compiledAny = false;
-
-  // Match a block: leading newline (or start), <tag> on its own line, body,
-  // </tag> on its own line. Non-greedy body; the backreference enforces matching.
-  const blockRe = /(^|\r?\n)[ \t]*<([a-z][a-z0-9-]*)>[ \t]*\r?\n([\s\S]*?)\r?\n[ \t]*<\/\2>[ \t]*(?=\r?\n|$)/g;
-
-  const out = content.replace(blockRe, (match, prefix, tag, body) => {
-    if (!known.has(tag)) return match; // not a provider block — leave untouched
-    compiledAny = true;
-    return active.has(tag) ? `${prefix}${body}` : prefix;
-  });
-
-  // Collapse the 3+ blank-line runs that stripping can leave behind.
-  return compiledAny ? out.replace(/(\r?\n){3,}/g, '\n\n') : out;
-}
-
-/**
- * Substitute {{placeholders}} for a provider and (optionally) rewrite command
- * invocations from `/name` to the provider's prefix.
- *
- * @param {string} content
- * @param {string} providerKey
- * @param {{ commandNames?: string[] }} [opts]
- * @returns {string}
- */
-export function replacePlaceholders(content, providerKey, opts = {}) {
-  const provider = PROVIDERS[providerKey];
-  if (!provider) throw new Error(`Unknown provider: ${providerKey}`);
-  const { model, configFile, commandPrefix, askInstruction } = provider.placeholders;
-  const commandNames = opts.commandNames ?? [];
-
-  const availableCommands = commandNames.map((n) => `${commandPrefix}${n}`).join(', ');
-
-  let result = content
-    .replace(/\{\{model\}\}/g, model)
-    .replace(/\{\{config_file\}\}/g, configFile)
-    .replace(/\{\{ask_instruction\}\}/g, askInstruction)
-    .replace(/\{\{available_commands\}\}/g, availableCommands)
-    .replace(/\{\{command_prefix\}\}/g, commandPrefix);
-
-  // Rewrite `/cmd` invocations to the provider prefix (e.g. Codex uses `$`).
-  // Longest names first so `/session-end` is rewritten before `/session`.
-  if (commandPrefix !== '/' && commandNames.length > 0) {
-    const sorted = [...commandNames].sort((a, b) => b.length - a.length);
-    for (const name of sorted) {
-      // `/name` where name is followed by a non-identifier char or end.
-      const re = new RegExp(`\\/(${escapeRegex(name)})(?=[^a-zA-Z0-9_-]|$)`, 'g');
-      // Use a replacement FUNCTION, not a string — a `$` commandPrefix would
-      // otherwise collide with String.replace's `$$`/`$1` escape syntax.
-      result = result.replace(re, (_match, g1) => `${commandPrefix}${g1}`);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Render a source document for a single provider: compile blocks, then
- * substitute placeholders.
- *
- * @param {string} source
- * @param {string} providerKey
- * @param {{ commandNames?: string[] }} [opts]
- * @returns {string}
- */
-export function renderForProvider(source, providerKey, opts = {}) {
-  const provider = PROVIDERS[providerKey];
-  if (!provider) throw new Error(`Unknown provider: ${providerKey}`);
-  const compiled = compileProviderBlocks(source, provider.tags);
-  return replacePlaceholders(compiled, providerKey, opts);
-}
-
-/**
- * Render a source for every configured provider.
- * @param {string} source
- * @param {{ commandNames?: string[] }} [opts]
- * @returns {Record<string,string>} keyed by provider key
- */
-export function renderAll(source, opts = {}) {
-  const out = {};
-  for (const key of Object.keys(PROVIDERS)) {
-    out[key] = renderForProvider(source, key, opts);
-  }
-  return out;
-}
-
-/** @param {string} s */
-function escapeRegex(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/scripts/lib/owner-config/coerce.mjs

@@ -1,29 +0,0 @@
-/**
- * owner-config/coerce.mjs — Strict-mode wrapper around validate().
- *
- * Imports: validate + OwnerConfigError. Throws on validation failure, returns
- * the normalized value on success. Convenient for CLI entrypoints and tests
- * that want to assert on success without inspecting `ok`.
- */
-
-import { validate } from './validate.mjs';
-import { OwnerConfigError } from './error.mjs';
-
-/**
- * Strict-mode wrapper around validate(). Returns the normalized value when
- * the input passes the gate, otherwise throws OwnerConfigError with the
- * full error list attached as `.errors`.
- *
- * @param {unknown} raw
- * @returns {object}
- */
-export function coerce(raw) {
-  const result = validate(raw);
-  if (!result.ok) {
-    throw new OwnerConfigError(
-      `owner config validation failed (${result.errors.length} error${result.errors.length === 1 ? '' : 's'})`,
-      result.errors
-    );
-  }
-  return result.value;
-}

package/scripts/lib/owner-config/constants.mjs

@@ -1,21 +0,0 @@
-/**
- * owner-config/constants.mjs — Schema constants for the owner persona config.
- *
- * Leaf module. No imports. All exported arrays are frozen so consumers cannot
- * accidentally mutate the canonical enum sets.
- */
-
-/** Current owner-config schema version. New writes are stamped with this. */
-export const CURRENT_OWNER_SCHEMA_VERSION = 1;
-
-/** Valid values for tone.style. */
-export const VALID_TONE_STYLES = Object.freeze(['direct', 'neutral', 'friendly']);
-
-/** Valid values for efficiency.output-level. */
-export const VALID_OUTPUT_LEVELS = Object.freeze(['lite', 'full', 'ultra']);
-
-/** Valid values for efficiency.preamble. */
-export const VALID_PREAMBLE_LEVELS = Object.freeze(['minimal', 'verbose']);
-
-/** Valid values for efficiency.comments-in-code. */
-export const VALID_COMMENTS_LEVELS = Object.freeze(['minimal', 'full']);

package/scripts/lib/owner-config/defaults.mjs

@@ -1,50 +0,0 @@
-/**
- * owner-config/defaults.mjs — Canonical default-filled owner config factory.
- *
- * Imports constants only. Leaf in the dependency sense (no circular deps).
- * Returns the fully-default-filled config with `owner.name` and
- * `owner.language` intentionally left blank — those are required from the user;
- * the bootstrap interview (D2) fills them in.
- */
-
-import { CURRENT_OWNER_SCHEMA_VERSION } from './constants.mjs';
-
-/**
- * Returns the canonical default-filled owner config. `owner.name` and
- * `owner.language` are intentionally empty — those are user-required fields
- * the bootstrap interview (D2) fills in. The `defaults()` shape is what
- * `merge()` uses as its base when callers pass partial overrides.
- *
- * @returns {object}
- */
-export function defaults() {
-  return {
-    'schema-version': CURRENT_OWNER_SCHEMA_VERSION,
-    owner: {
-      name: '',
-      'email-hash': null,
-      language: '',
-    },
-    tone: {
-      style: 'neutral',
-      tonality: null,
-    },
-    efficiency: {
-      'output-level': 'full',
-      preamble: 'minimal',
-      'comments-in-code': 'minimal',
-    },
-    'hardware-sharing': {
-      enabled: false,
-      'hash-salt': null,
-    },
-    defaults: {
-      'preferred-test-command': null,
-      'preferred-editor': null,
-    },
-    metadata: {
-      created_at: null,
-      updated_at: null,
-    },
-  };
-}

package/scripts/lib/owner-config/error.mjs

@@ -1,19 +0,0 @@
-/**
- * owner-config/error.mjs — OwnerConfigError class.
- *
- * Leaf module. No imports. Thrown by coerce() when validation fails. The
- * `.errors` array carries the full list of human-readable failure messages
- * collected by validate().
- */
-
-export class OwnerConfigError extends Error {
-  /**
-   * @param {string} message
-   * @param {string[]} [errors]
-   */
-  constructor(message, errors = []) {
-    super(message);
-    this.name = 'OwnerConfigError';
-    this.errors = errors;
-  }
-}