session-orchestrator 5.12.0 → 5.13.0

package/skills/session-start/references/phase-1-2-session-lock.md

@@ -10,11 +10,13 @@
 
 Acquire a distributed session-lock to detect parallel sessions in the same repo before initializing STATE.md. This prevents two concurrent Claude/Codex sessions from stomping each other's wave state and metrics writes.
 
-**Mechanical wiring (Epic #583, 2026-05-27):** The SessionStart hook (`hooks/on-session-start.mjs` → `hooks/_lib/lock-bootstrap.mjs`) now writes `.orchestrator/session.lock` mechanically BEFORE this skill's prose runs. The prose Phase 1.2 becomes confirmatory — it verifies the lock exists with the expected shape via `readLock({ repoRoot: process.cwd() })`. Re-call `acquire()` only if `readLock()` returns `null` (mechanical hook failed) OR the existing lock's raw `session_id` does not exactly match the current session's raw id (a rare divergence — surface via AUQ before overwriting). A matching `semantic_session_id`, STATE.md `session`, or owner proof cannot repair that mismatch. The decision flow below still applies to all five outcomes (active / stale / corrupt / unreadable / fs-error) when the prose path needs to acquire. Every `ok: true` from `acquire()` / `forceAcquire()` also rewrites `.orchestrator/runtime/lock-owner-proof.json` for the new lock (#1541), so the `/close` release stays proof-gated; a failed proof write is reported as `result.ownerProof: { ok: false, reason }`, never thrown.
+**Mechanical wiring (Epic #583, 2026-05-27):** The SessionStart hook (`hooks/on-session-start.mjs` → `hooks/_lib/lock-bootstrap.mjs`) now writes `.orchestrator/session.lock` mechanically BEFORE this skill's prose runs. The prose Phase 1.2 becomes confirmatory — it verifies the lock exists with the expected shape via `readLock({ repoRoot: lockRoot })`, where `lockRoot = resolveOwnLockRootFor({ sessionId }).root` (`scripts/lib/own-lock-root.mjs`, #1730): the checkout whose lock carries the raw id, so a Phase 1.2 run after `EnterWorktree` or a `cd` finds the lock it already holds instead of taking a second one beside the cwd; with no such lock it is the cwd's checkout, as before. Re-call `acquire()` only if `readLock()` returns `null` (mechanical hook failed) OR the existing lock's raw `session_id` does not exactly match the current session's raw id (a rare divergence — surface via AUQ before overwriting). A matching `semantic_session_id`, STATE.md `session`, or owner proof cannot repair that mismatch. The decision flow below still applies to all five outcomes (active / stale / corrupt / unreadable / fs-error) when the prose path needs to acquire. Every `ok: true` from `acquire()` / `forceAcquire()` also rewrites `.orchestrator/runtime/lock-owner-proof.json` for the new lock (#1541), so the `/close` release stays proof-gated; a failed proof write is reported as `result.ownerProof: { ok: false, reason }`, never thrown.
 
 ```javascript
 import { acquire, forceAcquire } from 'scripts/lib/session-lock.mjs';
-const result = acquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd() });
+import { resolveOwnLockRootFor } from 'scripts/lib/own-lock-root.mjs';
+const lockRoot = resolveOwnLockRootFor({ sessionId }).root;
+const result = acquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: lockRoot });
 ```
 
 Where `sessionId` is the physical raw identity for this invocation: the native harness-provided raw id, or a generated UUID when no trustworthy raw id exists. It is the only value passed to `acquire()` and the only live lock/registry ownership key. `semanticSessionId` may be recorded separately as an attribution/history label and may populate STATE.md `session`; neither label is a substitute for `sessionId`. `sessionType` is the session mode (`housekeeping`, `feature`, or `deep`).
@@ -51,7 +53,7 @@ Where `sessionId` is the physical raw identity for this invocation: the native h
      Reply with the number of your choice.
      ```
    - On **Abort**: exit session-start cleanly with a brief stderr note (`session-lock: aborted — active lock held by session_id=<id>`). Do NOT initialize STATE.md.
-   - On **Force-take**: call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd() })`. After Phase 1.5 initializes STATE.md, append a deviation via `appendDeviation()`:
+   - On **Force-take**: call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: lockRoot })`. After Phase 1.5 initializes STATE.md, append a deviation via `appendDeviation()`:
      `Force-took session lock from session_id=<existingLock.session_id>, age=<ageHours>h, mode=<existingLock.mode>, pid=<existingLock.pid>`. Continue.
 
 3. **`result.ok === false`** with `reason === 'stale-heartbeat'`:
@@ -99,13 +101,13 @@ Where `sessionId` is the physical raw identity for this invocation: the native h
      2. Abort — stops here and writes nothing. The lock file `.orchestrator/session.lock` (it names the process that wrote it) tells you whether that session is still alive.
      Reply with the number of your choice.
      ```
-   - On **Reclaim**: call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd(), onlyIfNotLive: true })` — the single-winner takeover (#1494): if another session reclaimed the lock in the meantime, it returns that session's `active` result instead of overwriting it; follow the decision flow for the returned result. After Phase 1.5 initializes STATE.md, append a deviation:
+   - On **Reclaim**: call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: lockRoot, onlyIfNotLive: true })` — the single-winner takeover (#1494): if another session reclaimed the lock in the meantime, it returns that session's `active` result instead of overwriting it; follow the decision flow for the returned result. After Phase 1.5 initializes STATE.md, append a deviation:
      `Stale-lock reclaim: replaced lock from session_id=<existingLock.session_id>, age=<ageHours>h, pid=<existingLock.pid>`. Continue.
    - On **Abort**: exit cleanly.
 
 4. **`result.ok === false`** with `reason === 'corrupt'`:
    - `.orchestrator/session.lock` exists but is not a lock record (invalid JSON, or JSON without the lock shape). It can never be a live lock: every writer writes it atomically (tmp+link / tmp+rename), so no reader sees a half-written file. The SessionStart hook already reclaims this case mechanically and prints one stderr WARN; reaching it here means the hook did not run or its reclaim failed.
-   - No AUQ — the answer is derivable (AUQ-001.2). Log `⚠ session-lock: .orchestrator/session.lock was not a valid lock record — reclaiming.`, call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: process.cwd(), onlyIfNotLive: true })` (a non-ok result means another session got there first — follow the decision flow for it), and after Phase 1.5 append a deviation: `Corrupt-lock reclaim: replaced an unparseable .orchestrator/session.lock`. Continue.
+   - No AUQ — the answer is derivable (AUQ-001.2). Log `⚠ session-lock: .orchestrator/session.lock was not a valid lock record — reclaiming.`, call `forceAcquire({ sessionId, mode: sessionType, ttlHours: 4, repoRoot: lockRoot, onlyIfNotLive: true })` (a non-ok result means another session got there first — follow the decision flow for it), and after Phase 1.5 append a deviation: `Corrupt-lock reclaim: replaced an unparseable .orchestrator/session.lock`. Continue.
 
 5. **`result.ok === false`** with `reason === 'unreadable'`:
    - `.orchestrator/session.lock` exists but cannot be read (`result.error`, e.g. `EACCES`, or `EISDIR` for a directory at the path). Nothing was written, and it is never reclaimed: no lock writer produces such a path, and a directory may hold content nobody here created (PSA-003). The SessionStart hook already printed a stderr WARN and emitted `orchestrator.session.lock.read_anomaly` (`status: 'unreadable'`).

package/skills/session-start/references/phase-1-5-session-continuity.md

@@ -104,7 +104,7 @@ Run it as code, after the Recommendations Banner — never rewrite STATE.md by h
 node "${PLUGIN_ROOT}/scripts/state-md-idle-reset.mjs" --json
 ```
 
-It prints `{"changed": <bool>, "reason": <string|null>, "path": "<STATE.md>"}` and writes under the STATE.md lock (`resetStateMdToIdle` in `scripts/lib/state-md/idle-reset.mjs`). A no-op exits 0 with `changed: false` and one of `reason: "status-not-completed"` (any status other than `completed`), `"unparseable"` (no frontmatter) or `"missing"` (no or empty STATE.md). Exit 2 means `--repo-root` is not a directory, the write failed, or a STATE.md guard refused it (`reason` names the guard) — report it as a Deviation and continue. Without a new `## Wave History` (a coordinator-direct session) the earlier `## Previous Session` body is kept below the new recommendations copy. The rules below are the contract that code implements:
+It prints `{"changed": <bool>, "reason": <string|null>, "path": "<STATE.md>"}` and writes under the STATE.md lock (`resetStateMdToIdle` in `scripts/lib/state-md/idle-reset.mjs`). A no-op exits 0 with `changed: false` and one of `reason: "status-not-completed"` (any status other than `completed`), `"unparseable"` (no frontmatter) `"missing"` (no or empty STATE.md) or `"foreign-state-md"` (the only STATE.md belongs to another platform's foreign session and is left untouched, #1618 — treat like `missing`). Exit 2 means `--repo-root` is not a directory, the write failed, or a STATE.md guard refused it (`reason` names the guard) — report it as a Deviation and continue. Without a new `## Wave History` (a coordinator-direct session) the earlier `## Previous Session` body is kept below the new recommendations copy. The rules below are the contract that code implements:
 
 1. Set frontmatter `status: idle`.
 2. Clear `current-wave` (set to `0`).
@@ -247,7 +247,7 @@ Also read `<state-dir>/STATUS.md` if it exists for additional project-level cont
 
 ### Session-Profile Persistence (`ultradeep` alias)
 
-> **CONTENT ADDITION — not part of the #1157 move.** Applies to the STATE.md initialization write (Phase 1b), the same write that sets `session-type`. Rationale, wave shape and budgets: `docs/prd/2026-09-06-ultradeep-session-profile.md` — do not restate them here. Alias resolution: `commands/session.md` § Argument alias.
+> **CONTENT ADDITION — not part of the #1157 move.** Applies to the STATE.md initialization write (Phase 1b), the same write that sets `session-type`. Rationale, wave shape and budgets: the internal ultradeep session-profile PRD (2026-09-06, not in the public mirror) — do not restate them here. Alias resolution: `commands/session.md` § Argument alias.
 
 When the `/session` argument was the `ultradeep` ALIAS, persist the profile alongside the type:
 

package/skills/session-start/references/phase-1-7-vault-status-board.md

@@ -29,7 +29,7 @@ await sweepBoard({
 });
 ```
 
-`sweepBoard` enumerates candidate repos host-wide (`enumerateCandidates` — confinement root `~/Projects` plus any `cross-repo.projects` config-declared repos, issue #676), re-derives the board status for every BUSY repo it finds (`in-progress` or `force-closed`, never `frei`), unions in THIS repo so its own row is always re-derived, and writes the board in one idempotent merge. **A crashed session in ANY repo now renders `force-closed` on the board from THIS repo's session-start** — not only from that repo's own next session-start/-end.
+`sweepBoard` enumerates candidate repos host-wide (`enumerateCandidates` — confinement root from `getConfinementRoot()`, `~/Projects` unless the host sets `SO_PROJECTS_ROOT` or owner.yaml `paths.projects-root` (#1562), plus any `cross-repo.projects` config-declared repos, issue #676), re-derives the board status for every BUSY repo it finds (`in-progress` or `force-closed`, never `frei`), unions in THIS repo so its own row is always re-derived, and writes the board in one idempotent merge. **A crashed session in ANY repo now renders `force-closed` on the board from THIS repo's session-start** — not only from that repo's own next session-start/-end.
 
 > **Call-site contract:** `sweepBoard` is now the primary call. `explicitStatus` is **inert for `'in-progress'`** — `collectRows` only honors an explicit per-repo `status: 'closed'` override; THIS repo's `in-progress` row is always rendered from its own **live `session.lock` lease** (already written/heartbeated by Phase 1.2's `acquire()`), never from a passed-in status string. If constructing `repos` manually for a narrower sweep, `collectRows` requires `{ repoRoot }` object descriptors and silently skips bare path strings (`board-writer.mjs` `collectRows` guard) — `sweepBoard`/`buildSweepRepos` already produce the correct shape, so this only matters for a hand-rolled `mirrorBoard({ repos })` call.
 

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

@@ -9,7 +9,7 @@
    a. `.orchestrator/policy/quality-gates.json` — preferred source when present.
    b. Session Config `test-command` / `typecheck-command` / `lint-command` — fallback.
    c. Hardcoded defaults: `npm test`, `npm run typecheck`, `npm run lint`.
-   Before running, perform a **command-availability check**: for each resolved command, extract the binary (first token) and run `command -v <binary>`. If absent, skip that check and log `⚠ Quality baseline: <binary> not found — skipping <variant>`. Report results but do not block the session.
+   Execute each complete configured shell command and report `fail` if its binary is missing (exit 127; on Windows `cmd.exe` exits 1, also `fail`). Correct the command or explicitly set it to `skip` in Session Config; explicit `skip` remains `skip`. Report baseline failures without blocking the session.
 3. **Pencil design status**: if `pencil` is configured, verify the `.pen` file exists at the configured path. Report: "Pencil design configured at [path] — design-code alignment reviews will run after Impl-Core and Impl-Polish waves." If file not found, warn: "Pencil path configured but file not found at [path]."
 4. **Plugin freshness**: Determine the session-orchestrator plugin directory (navigate up from this skill's base directory to the plugin root). Run `git -C <plugin-dir> log -1 --format="%ci"` to get the last commit date. If older than `plugin-freshness-days` (default: 30) days, flag a warning in the Session Overview: `"⚠ Session Orchestrator plugin last updated [N] days ago — consider pulling the latest version."` Non-blocking — present in overview, don't halt.
 
@@ -42,6 +42,7 @@
 
    When `result.status === 'red'`, render a banner alongside the bootstrap-lock and vault-staleness warnings:
    - **Red** (`status === 'red'`): `"🚨 CI RED on HEAD (pipeline #<currentPipelineId>) — last green: #<lastGreen.pipelineId> (commit <SHA-7>, <redCount> pipelines ago). Failing job: <failingJobName>"`
+   - **Red on GitHub** (`details.cliUsed === 'gh'`, #1727/#856): GitHub has no pipelines, so the line carries no `(pipeline #…)` and `lastGreen` has no `pipelineId`: `"🚨 CI RED on HEAD — last green: commit <SHA-7> (<ageCommits> commit(s) ago). Failing job: <failingJobName>"`. When the history query failed (`details.reason === 'last-green-query-failed'`) the middle part reads `— last green: unknown (history query failed)`; when no green commit lies in the 16-commit window it is absent. The probe reads the red verdict without the history (`checkCiStatus({ deferHistory: true })`, #1728) and fetches the history in its follow-up, inside what is left of `PROBE_BUDGET_MS`: when that runs out (`details.reason === 'last-green-budget-exceeded'`) the red line still renders, with `— last green: unknown (history not read within the probe budget)`. The reading is for the LOCAL HEAD (`git rev-parse HEAD`), never the remote default branch; an unpushed HEAD is `unknown` with reason `head-sha-not-on-remote` (Unknown branch below).
    - **Green with soft failures** (`status === 'green'` AND `result.allowFailureJobs` is present): `"⚠ CI green on HEAD, but <N> allow_failure job(s) FAILED: <names>. A pipeline reports success regardless of these — a job red on every run stays invisible at the pipeline level."` Render this even though the pipeline passed: the whole point is that pipeline status cannot express it.
    - **Degraded** (`result.degraded` present): `"⚠ ci-status: CI status for HEAD could not be determined (<reason>) — state UNKNOWN, not \"green\"."` — the probe builds this message itself; render it verbatim.
    - **Unknown** (`status === 'unknown'` — HEAD carries no pipeline, e.g. unpushed local commits; #1337): NOT silent — `"<mark> ci-status: CI status for HEAD could not be determined (<reason>) — <hint>"`, where `<mark>` is `🚨` when the last PUSHED commit's pipeline verdict is `red` (severity `alert`) and `⚠` otherwise (severity `warn`). Silence here would read as green when the pushed commit may actually be red.
@@ -166,7 +167,7 @@
 
    The return contract has THREE states, not the usual two, and the third is the point: `null` means either "no mirror remote" or "queried successfully, zero open issues"; `{ severity, message, count, repoSpec, issues }` means N > 0; and `{ severity, message, repoSpec, degraded }` means the query did NOT succeed, where `degraded` is one of `cli-missing | timeout | parse-error | auth-error | query-failed`. Render `result.message` verbatim in either non-null case. A `degraded` result must be read as *"the mirror's state is unknown"* — never as clean. `scripts/lib/ci-status-banner.mjs` **was** the unmigrated side until #1031: it collapsed missing-CLI, timeout and unparseable output onto the same `null` an absent remote returns, which in the banner contract reads as "all clear", and that collapse is why this gap survived unseen. It now carries its own `DEGRADED_REASONS` enum (`cli-missing | timeout | parse-error | query-failed | git-error`) and the same three-state shape — see the CI-status paragraph above. The two enums are deliberately NOT merged: each names the failures its own probe can actually reach.
 
-   The git-config-drift probe (`scripts/lib/git-config-drift.mjs`, `checkGitConfigDrift`) runs in the Phase 4 banner family as `id: 'git-config-drift'` in `scripts/lib/session-start-probes.mjs` `PROBES` (`env` defaults to `process.env`). It reads `git config --local --list` with a FILTERED environment, so an ambient `GIT_DIR` cannot redirect the probe itself at a foreign repository and let it call this one clean. **Three states, not two:** `null` = read and clean; `{ severity: 'warn', message, findings }` = at least one unexpected entry (a local identity override, a local `commit.gpgsign`, a remote on a reserved fixture host, a `core.hooksPath` not pointing at `.husky/_` AND not DECLARED by the repo, or `GIT_DIR`/`GIT_WORK_TREE` set in the environment); `{ …, degraded }` = the config could NOT be read — **never render that as clean.** Render `result.message` alongside the other banners.
+   The git-config-drift probe (`scripts/lib/git-config-drift.mjs`, `checkGitConfigDrift`) runs in the Phase 4 banner family as `id: 'git-config-drift'` in `scripts/lib/session-start-probes.mjs` `PROBES` (`env` defaults to `process.env`). It reads `git config --local --list` with a FILTERED environment, so an ambient `GIT_DIR` cannot redirect the probe itself at a foreign repository and let it call this one clean. **Three states, not two:** `null` = read and clean; `{ severity: 'warn', message, findings }` = at least one unexpected entry (a local identity override, a local `commit.gpgsign`, a remote on a reserved fixture host, a `core.hooksPath` not pointing at `.husky/_` AND not DECLARED by the repo, a `.husky/_` hooksPath whose directory git resolves to in THIS working tree has no `pre-push`, has a non-executable `pre-push`, or lacks the `h` helper (each defect is a separate finding) — the gitignored runtime a fresh linked worktree never gets, so commit and push run ungated; repair with the target repo’s canonical PM per SEC-020: `pnpm exec husky` (pnpm), `npm exec --no -- husky` (npm), `yarn exec husky` (Yarn), or `bun run husky` (Bun); when unknown, identify the canonical PM first (#1688) —, a `core.hooksPath` set in NO scope while the repo tracks `.husky/<hook>` files, so git never runs them (`hooks-path-unset`, same repair; a failed query is reported as unknown; #1692), or `GIT_DIR`/`GIT_WORK_TREE` set in the environment); `{ …, degraded }` = the config could NOT be read — **never render that as clean.** Render `result.message` alongside the other banners.
 
    The `core.hooksPath` trigger is narrower than "points somewhere other than `.husky/_`" — a hooksPath the repo DECLARES is accepted without any config key. Declared means `git ls-files -- <hooksPath>` finds at least one TRACKED file DIRECTLY under it (not nested deeper) whose BASENAME is a real git hook name (`pre-commit`, `pre-push`, `commit-msg`, …) — a tracked directory of ordinary source, or an untracked file merely named like a hook, does not count. This document does not restate the hook-name list — `GIT_HOOK_NAMES` in `scripts/lib/git-config-drift.mjs` (sourced from `git help hooks`) is the single declaration site (#1158 review N1 — the first cut of this rule accepted any tracked file under the path at all, which a fixture-planted `scripts/pre-commit` left untracked, sitting beside ordinary tracked source, would have bypassed silently).
 

package/skills/tmux-layout/SKILL.md

@@ -55,9 +55,9 @@ The skill prints a one-line tmux command. Paste it into a SECOND terminal (do no
 | 2 | STATE.md tail | `tail -F <state-dir>/STATE.md` |
 | 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status -R <spec> --output json \| jq -r '.jobs[] \| ...'; sleep 15; done` |
 | 4 | events.jsonl wave/gate filter | `tail -F .orchestrator/metrics/events.jsonl \| jq --unbuffered 'select(.event \| test("wave\|gate\|spiral"))'` |
-| 5 | agent-status telemetry (#565, only with `--with-status-pane`) | `while true; do clear; node --input-type=module -e '...readCurrentStatus({repoRoot:process.cwd()})...'; sleep 2; done` |
+| 5 | agent-status telemetry (#565, only with `--with-status-pane`) | `while true; do clear; node --input-type=module -e '...readCurrentStatus({repoRoot:"<own lock root>"})...'; sleep 2; done` — the root holding this session's own lock, resolved once when the layout is rendered (`resolveOwnLockRootFor`, #1730); none found → `process.cwd()` |
 
-Pane 5 renders through `readCurrentStatus()` (`scripts/lib/agent-status.mjs`), never the cache file directly (#1342): its header line `agent-status · source=<live-map|rebuilt-log|stale-cache|absent> · at=<ISO|n/a>` says WHAT is on screen, in four states — `live-map` = every shown record came from the current-map cache and the cache was VERIFIED against the ledger, `rebuilt-log` = at least one record was taken from the append-only `agent-status.jsonl` because the cache was behind (or unreadable) for that agent, `stale-cache` = no ledger to check the cache against, `absent` = nothing on disk yet (no ledger, no cache), which stays unmarked because a fresh repo is not a degradation — plus a leading `⚠` and the words STALE / `DEGRADED: <reasons>` in TEXT whenever the view is not verified live. The render command is exported as `buildStatusPaneRenderCommand()` so it can be executed once (outside the poll loop) in tests.
+Pane 5 renders through `readCurrentStatus()` (`scripts/lib/agent-status.mjs`), never the cache file directly (#1342): its header line `agent-status · source=<live-map|rebuilt-log|stale-cache|absent> · at=<ISO|n/a>` says WHAT is on screen, in four states — `live-map` = every shown record came from the current-map cache and the cache was VERIFIED against the ledger, `rebuilt-log` = at least one record was taken from the append-only `agent-status.jsonl` because the cache was behind (or unreadable) for that agent, `stale-cache` = no ledger to check the cache against, `absent` = nothing on disk yet (no ledger, no cache), which stays unmarked because a fresh repo is not a degradation — plus a leading `⚠` and the words STALE / `DEGRADED: <reasons>` in TEXT whenever the view is not verified live. The render command is exported as `buildStatusPaneRenderCommand({ repoRoot })` so it can be executed once (outside the poll loop) in tests; without `repoRoot` it reads its own cwd.
 
 `<state-dir>` is resolved via `resolveStateDir()` from `scripts/lib/platform.mjs` (`.claude/`, `.codex/`, or `.cursor/`).
 Pane 3 command is vcs-aware (`glab` for gitlab, `gh pr checks` for github, informational `echo` fallback when no CLI).

package/skills/vault-sync/validator.mjs

@@ -62,6 +62,7 @@ import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import YAML from 'yaml';
 import { resolveInstructionFile } from '../../scripts/lib/common.mjs';
+import { resolveLedgerPath } from '../../scripts/lib/ledger-path.mjs';
 import { findSessionConfigBlock } from '../../scripts/lib/config/section-extractor.mjs';
 import {
   computeSchemaHash,
@@ -810,7 +811,7 @@ if (filesSkippedNoFrontmatter > 0) {
 // ── mode=baseline ─────────────────────────────────────────────────────────
 // Serialize current errors + warnings as a snapshot, then exit 0.
 if (mode === 'baseline') {
-  const baselinePath = join(vaultDir, '.orchestrator', 'metrics', 'vault-sync-baseline.json');
+  const baselinePath = resolveLedgerPath('.orchestrator/metrics/vault-sync-baseline.json', vaultDir);
   writeBaseline(baselinePath, {
     errors,
     warnings,
@@ -827,7 +828,7 @@ if (mode === 'baseline') {
 // ── mode=diff ─────────────────────────────────────────────────────────────
 // Read a prior baseline, compute set-differences, emit JSON diff to stdout.
 if (mode === 'diff') {
-  const baselinePath = join(vaultDir, '.orchestrator', 'metrics', 'vault-sync-baseline.json');
+  const baselinePath = resolveLedgerPath('.orchestrator/metrics/vault-sync-baseline.json', vaultDir);
   const baseline = readBaseline(baselinePath);
 
   if (!baseline) {

package/skills/wave-executor/SKILL.md

@@ -113,13 +113,13 @@ Example: If user said `/go focus on API endpoints`, each agent prompt includes:
 
 ## Pre-Wave 1a: Capture Session Start Ref
 
-Before dispatching Wave 1, capture the current commit as the session baseline:
+Before dispatching Wave 1, capture the current commit of the session's own checkout as the session baseline — the tree this session's STATE.md lives in and its consumers diff (repoRoot); in a promoted or EnterWorktree session that is the worktree (#1652). Same value as STATE.md's `session-start-ref`:
 
 ```bash
-SESSION_START_REF=$(git rev-parse HEAD)
+SESSION_START_REF=$(git -C "<session checkout (repoRoot)>" rev-parse HEAD)
 ```
 
-Store this value for use throughout the session — it is needed by the simplification pass (Quality wave) and session-reviewer dispatch to determine which files changed during this session. Include it in the coordinator's context, NOT in individual agent prompts.
+Store this value for use throughout the session — it is needed by the simplification pass (Quality wave) and session-reviewer dispatch to determine which files changed during this session. Include it in the coordinator's context, NOT in individual agent prompts. This single ref covers the session's own checkout only: commits made in additional worktrees of the session are recorded by the staging fence as `orchestrator.session.work_tree` events and listed by `node scripts/session-commit-files.mjs` (#1659; remaining limits: `references/wave-executor-state-init.md`).
 
 ## Pre-Wave 1b: Initialize STATE.md
 
@@ -293,7 +293,7 @@ End with a single commit summarizing all housekeeping work.
 
 ### Ultradeep Profile (`session-profile: ultradeep`)
 
-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`.
+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: the internal ultradeep session-profile PRD (2026-09-06, not in the public mirror).
 
 - **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).
@@ -352,6 +352,7 @@ After the Finalization wave completes successfully:
 1. Report final status to the user
 2. If `persistence: true`, suggest invoking `/close` to finalize the session. If `persistence: false`, note that the session is complete (no STATE.md to close — session-end would be a no-op).
 3. Do NOT auto-commit — `/close` handles that with proper verification
+4. With fleet integration this report is the session's finished or waiting answer: apply `skills/_shared/fleet-protocol.md` § Rücklauf an den Navigator (Pflicht) (wait case `fertig`, or `zug-<name>` when only a release train or pipeline is left) and, in this same turn, § Übergabe und Zug-Manifest — write the file, report „bereit zum Schließen“, stop monitors and background work, start nothing new, and leave `/close` to the coordinator. The report then ends with the sentence `Bereit zum Schließen.` instead of the `/close` suggestion of step 2: the coordinator reads only the last 600 characters, and no question may follow. Without fleet integration, nothing changes.
 
 ## Vault-Sync Diff Reporting (#327)
 

package/skills/wave-executor/references/wave-executor-state-init.md

@@ -21,7 +21,7 @@ issues: [<issue numbers from plan>]
 session: <semantic session label, e.g. main-2026-01-01-deep-1>
 session-id: <raw session_id from .orchestrator/session.lock — OMIT the key when no lock exists>
 started_at: <resolveSessionStartedAt({ repoRoot }) — the lock's own started_at, NEVER new Date() at write time (#1368)>
-session-start-ref: <full sha from git rev-parse HEAD at init>
+session-start-ref: <full sha from git -C <session checkout (repoRoot)> rev-parse HEAD at init (#1652)>
 status: active
 current-wave: 0
 total-waves: <from session plan>
@@ -50,9 +50,9 @@ node -e "import('./scripts/lib/state-md.mjs').then(m => console.log(JSON.stringi
 
 `resolveSessionStartedAt()` returns `.orchestrator/session.lock`'s own `started_at`, which the `orchestrator.session.lock.acquired` and `orchestrator.session.started` events agree with to the millisecond; it falls back to the current time only when no lock exists (`persistence: false`, or the acquire failed). Writing `new Date()` here instead put STATE.md 48 minutes ahead of the lock (measured 2026-09-13) and made `/close`'s #429 pre-check unable to join STATE.md to its own ledger record.
 
-`session-id` is the raw/native harness id (`resolveSessionIds().session_id`), `session` the semantic label (`.semantic_session_id`). Both are OPTIONAL (`schema-version` stays `1`): when the lock yields `null`, OMIT the key entirely — never write a placeholder. Neither field grants lock or registry ownership; see `skills/_shared/state-ownership.md`.
+`session-id` is the raw/native harness id (`resolveSessionIds().session_id`), `session` the semantic label (`.semantic_session_id`). Both are OPTIONAL (`schema-version` stays `1`): when the command yields `null`, OMIT the key entirely — never write a placeholder. **The guard is in the command, not in you (#1663):** the lock is repo-global and can name a PEER (a lost acquire race, or a pre-#1641 lock without `claude_pid` that stays until its TTL), so `resolveSessionIds()` returns `session_id` only when the lock's raw id is one of `readProcessLocalSessionIds()` (this process's own native id) and `null` otherwise; a provably foreign lock also nulls `semantic_session_id`. A foreign lock id therefore means the key is OMITTED — never copy it from the lock by hand, because `/close` compares STATE.md `session-id` against the own native id (#1661) and a peer's id would make this session's own STATE.md read `foreign`. Neither field grants lock or registry ownership; see `skills/_shared/state-ownership.md`.
 
-`session-start-ref` is the commit the session started on (`git rev-parse HEAD`, full SHA); `scripts/emit-session.mjs` derives the ledger's `session_start_ref` from it and, when the key is absent, falls back to the `head_sha` of this session's own `orchestrator.session.started` event (#1443). `hooks/pre-task-scope-disjoint.mjs` no longer reads it: since #1485 its stale-worktree check on `isolation: "worktree"` dispatches compares HEAD against the base the harness actually branches from (`origin/HEAD` unless `worktree.baseRef: "head"`, then HEAD), and DENIES a measured mismatch. The other reader is `scripts/lib/scope-baseline.mjs` (`readBaseline()` reads the key into `sessionStartRef`, `computeDrift()` consumes it): with the key present its numerator is the union of the committed `<ref>..HEAD` diff, the working tree vs HEAD (staged + unstaged) and the untracked files (#1027 Pkt 2), all in the coordinator's own checkout; absent, it resolves a base itself (the preferred remote's default branch, else a local `main`/`master`; nothing resolvable skips with `no-baseline-ref`); a present-but-dead ref skips with `unresolvable-ref`, and so does any failed, oversized or timed-out numerator query. All three git queries run with `cwd` = repoRoot, so they never read an agent worktree's contents (the worktree directory itself is excluded from the untracked list). The ref bounds only the committed source, which gives the ratio two edges in opposite directions. Under-report: this template takes HEAD at wave-executor init rather than at session start, so files changed by a commit landed between session start and wave-executor init are missing from the committed source. Over-report: the working-tree and untracked sources are not tied to the ref at all, so files already dirty when the session started and a same-checkout peer session's files count as drift and can raise a false WARN. That second edge is a named ceiling in `computeDrift()`'s JSDoc; removing it needs a start-dirty snapshot persisted at freeze time, a storage change outside this template.
+`session-start-ref` is the commit the session started on, in the session's OWN checkout (#1652): `git -C <repoRoot> rev-parse HEAD`, full SHA — the tree this STATE.md lives in, because every consumer below runs `<ref>..HEAD` there. In a promoted or EnterWorktree session that tree is the WORKTREE (its STATE.md lives there), never the main checkout it came from. A ref taken from ANOTHER tree is wrong in both directions: a foreign worktree's HEAD or a stale main checkout's HEAD turns the two-dot diff into a diff between two unrelated trees. Commits a coordinator (or its subagents) makes in additional worktrees of its own (coordinator in the main checkout, branches in `_wt/…`) are NOT covered by this single ref; they are attributed separately (#1659): `hooks/pre-bash-staging-fence.mjs` records `(tree, start_ref)` as an `orchestrator.session.work_tree` event before every `git commit`, and `node scripts/session-commit-files.mjs [--session-id <raw-id>] [--json]` lists the files per tree and their union, each tree diffed only inside itself. Remaining limits: commits nested in `bash -c "…"`, `cd` operands needing shell expansion, commits after `pushd`/`popd`/`chdir`/`builtin cd` in the same command and the first commit on an unborn HEAD are not recorded; subshell scope is not modelled, so in `(cd x && git commit); git commit` the second commit is attributed to `x` as well; a commit inside `$( … )` or backticks is recorded for the start directory only when no outer statement changed directory, otherwise not at all (#1670); `SO_DISABLED_HOOKS=pre-bash-staging-fence` disables recording; Codex sessions record nothing (the fence is not in `hooks/hooks-codex.json`); two sessions committing in the same tree after one's start ref cannot be separated by a ref diff. Never substitute `origin/main` or another upstream ref: the consumers run the two-dot tree diff `git diff <ref>..HEAD`, which against a ref that is not an ancestor of HEAD lists the upstream's foreign files too. `scripts/emit-session.mjs` derives the ledger's `session_start_ref` from it and, when the key is absent, falls back to the `head_sha` of this session's own `orchestrator.session.started` event (#1443) — omitted with a WARN when that event measured `behind > 0`, because after a pull `<head_sha>..HEAD` would include the pulled-in upstream commits (#1668); when the session committed in more than its own tree, the record also carries `session_work_trees` (`[{ tree, start_ref }]`, #1659). `hooks/pre-task-scope-disjoint.mjs` no longer reads it: since #1485 its stale-worktree check on `isolation: "worktree"` dispatches compares HEAD against the base the harness actually branches from (`origin/HEAD` unless `worktree.baseRef: "head"`, then HEAD), and DENIES a measured mismatch. The other reader is `scripts/lib/scope-baseline.mjs` (`readBaseline()` reads the key into `sessionStartRef`, `computeDrift()` consumes it): with the key present its numerator is the union of the committed `<ref>..HEAD` diff, the working tree vs HEAD (staged + unstaged) and the untracked files (#1027 Pkt 2), all in the coordinator's own checkout, plus (#1659) the files committed in the session's OTHER own work trees of the same repository, read from its `orchestrator.session.work_tree` records and each diffed `<start_ref>..HEAD` only inside its own tree (the own tree keeps the STATE.md ref; trees of another repository are left out), reported in the additive result field `otherWorkTrees: { counted, skipped, otherRepo, malformed, invalid }`, present only when at least one other own tree is recorded; absent, it resolves a base itself (the preferred remote's default branch, else a local `main`/`master`; nothing resolvable skips with `no-baseline-ref`); a present-but-dead ref skips with `unresolvable-ref`, and so does any failed, oversized or timed-out numerator query. The three own-checkout git queries run with `cwd` = repoRoot, so they never read an agent worktree's contents (the worktree directory itself is excluded from the untracked list); another tree contributes only its committed diff, never its working tree or untracked files. The ref bounds only the committed source, which gives the ratio two edges in opposite directions. Under-report: this template takes HEAD at wave-executor init rather than at session start, so files changed by a commit landed between session start and wave-executor init are missing from the committed source. Over-report: the working-tree and untracked sources are not tied to the ref at all, so files already dirty when the session started and a same-checkout peer session's files count as drift and can raise a false WARN. That second edge is a named ceiling in `computeDrift()`'s JSDoc; removing it needs a start-dirty snapshot persisted at freeze time, a storage change outside this template.
 
 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.
 

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

@@ -14,10 +14,11 @@ Run this ONCE at the start of wave execution (before the first wave — not per-
 
 ```js
 import { appendSkillInvocation } from '$PLUGIN_ROOT/scripts/lib/skill-invocations-schema.mjs';
-import path from 'node:path';
+import { resolveLedgerPath } from '$PLUGIN_ROOT/scripts/lib/ledger-path.mjs';
 try {
   await appendSkillInvocation(
-    path.join(process.cwd(), '.orchestrator/metrics/skill-invocations.jsonl'),
+    // In a linked worktree the main checkout's ledger when it is gitignored there (#1722).
+    resolveLedgerPath('.orchestrator/metrics/skill-invocations.jsonl', process.cwd()),
     { timestamp: new Date().toISOString(), event: 'selected', skill: 'session-orchestrator:wave-executor', session_id: '<session_id>', phase: 'wave-execution' },
   );
 } catch { /* telemetry is best-effort — swallow and continue to dispatch */ }
@@ -117,7 +118,7 @@ Use the **Agent tool** to dispatch this wave's agents. **`run_in_background: tru
 
 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).
+**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: the Claude Code release-notes report of the 2026-09-06 360° audit (FA-6; internal, not in the public mirror).
 
 Read each wave's dispatch metadata from the session plan header (e.g., `(4 agents, parallel, isolation: worktree)`). When the plan specifies `isolation`, use it verbatim. When the plan does not specify, resolve the effective value via `resolveIsolation({ agentCount, sessionType, collisionRisk, configIsolation })` from `scripts/lib/wave-sizing.mjs` — the graduated default (#194) replaces the previous session-type-only switch. Pass the resolved value to each Agent() tool call per `circuit-breaker.md` (omit the parameter when resolved to `none`).
 
@@ -137,7 +138,7 @@ Before dispatching, verify the wave's agent count does not exceed `$CONFIG.agent
 | Advancing to the next wave | BLOCKS on the wave's AskUserQuestion. This is the one wave whose purpose is to stop; never auto-advance past it. |
 | STATE.md Wave History (§ 3a in `wave-loop-review.md`) | Record the wave with its role and `agents: 0`, so the wave count stays honest. |
 
-Rationale and the first consumer (the ultradeep profile's wave 2, "Synthesis-Gate"): `docs/prd/2026-09-06-ultradeep-session-profile.md`. Not restated here.
+Rationale and the first consumer (the ultradeep profile's wave 2, "Synthesis-Gate"): the internal ultradeep session-profile PRD (2026-09-06, not in the public mirror). Not restated here.
 
 #### Contract-Lock Serialization (Pattern A, #730/H1)
 
@@ -311,8 +312,11 @@ For each agent in this wave:
       - Any repo-state fact carried from an earlier wave: in the ASSERTED/UNVERIFIED form, never as a bare value (see Pre-Dispatch: Fact-Staleness Annotation above)
       - VCS issue reference if applicable
       - What NOT to touch (other agents' files)
+      - Git-write ban (PSA-007): "Do NOT run git add, git commit, git stash, git mv, git rm, git push or git reset. The coordinator commits." A wave prompt never carries a WORKTREE-MODE line, so the worktree exception of code-implementer never applies inside a wave.
+      - Waiting rule (#1615): "Do not wait longer than 5 minutes for anything (pipeline, remote run, rerun). Report your intermediate state and end; the coordinator waits with Monitor and continues you with SendMessage." A subagent's prompt cache lives 5 minutes, so every longer wait rebuilds its whole context.
       >",
     subagent_type: "<from session plan>",   // resolved agent type
+    model: "sonnet",   // ONLY when subagent_type is "Explore" (#1614): on a subscription the built-in Explore otherwise runs on the opus alias. Plugin agents pin model + effort in their own frontmatter — pass nothing for them.
     run_in_background: true   // RECOMMENDED — verify the started set via meta.json sidecars, never via the launch ack (§ Started-Set Verification)
   })
       - Turn budget and status reporting: "You have a maximum of [maxTurns] turns for this task. If you cannot complete within this budget, report STATUS: partial with what was accomplished and what remains. At the end of your work, report STATUS: done (all acceptance criteria met) or STATUS: partial (some criteria unmet — list which ones)."
@@ -331,6 +335,8 @@ The colon heuristic (§ "How to detect project agents") has **three** readings,
 
 **Trust boundary.** A foreign run bypasses the ENTIRE hook chain — no `PreToolUse:Agent`, no scope enforcement, no `SubagentStop` telemetry (verified against `hooks/hooks.json`, W1/D4). Everything inside the detached worktree is **untrusted** until a Claude coordinator has read the diff and applied it. The replacement ledger record is the `orchestrator.foreign_dispatch.completed` event the adapter emits (payload in `docs/events-schema.md`), which fires on refusals too — a blocked dispatch is a record, not a silence.
 
+**No codebase index (#1683).** The argv carries `--disable-codebase-ref` (`FOREIGN_AGENT_BASE_ARGS`). Without it each run leaves a `worker-server` and a `typescript-language-server` behind with PPID 1, out of reach of the timeout kill. The foreign agent therefore has no semantic search and no LSP lints, only read and grep; the diff review above stays the quality gate. The hidden `--disable-indexing` flag is not needed (#1687): it only switches off the codebase sync inside that `worker-server`, which never starts here — measured 2026-10-20 on cursor-agent 2026.10.01-e373342, 52–71 KB outbound per run with or without it against a 1.5 MB worktree.
+
 **Composition.** A foreign run is a background Bash task, so it composes with background `Agent()` dispatch in the same wave. It is **NOT** part of § Started-Set Verification: no `meta.json` sidecar exists for it and no task-notification arrives. Its lifecycle is the adapter's return value — do not count it as planned/started/completed, and do not read its absence from the started set as a drop.
 
 **Model selection** is not decided here: the operator's model-routing SSOT (ADR-002) owns it. Working defaults: `composer-2.5` for foreign impl; `cursor-grok-4.6-high` for review / test-writing / judgment roles, at `timeoutSec ≥ 900`. Dogfood evidence (2026-08-25): `composer-2.5` on issue #1105 — 165 s, 2 files, +93 lines, mandatory review passed, merged only after independent test verification.
@@ -595,7 +601,7 @@ Rules:
 
 **Resolution chain** (if the plan does not specify `subagent_type` for an agent):
 
-1. **Discovery waves** → `"Explore"` (always, read-only)
+1. **Discovery waves** → `"Explore"` (always, read-only; dispatched with `model: "sonnet"`, see the template above)
 2. **Quality review** → `"session-orchestrator:session-reviewer"` (always)
 3. **Impl-Core / Impl-Polish / Quality (test-writing)** → check in order:
    a. Project agent matching the task domain (e.g., `"database-architect"` for DB tasks)

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

@@ -497,7 +497,10 @@ After each wave completes and before the progress update, update `<state-dir>/ST
    //   and stored in .orchestrator/session.lock (session_id field); matches the
    //   STATE.md frontmatter `session:` field written during Pre-Wave 1b initialization.
    import { updateHeartbeat } from '../../scripts/lib/session-lock.mjs';
-   updateHeartbeat({ sessionId, repoRoot: process.cwd() });
+   import { resolveOwnLockRootFor } from '../../scripts/lib/own-lock-root.mjs';
+   // The lock is not always in the cwd's checkout (#1730): a worktree session keeps it in the main checkout,
+   // or the other way round. At the wrong root updateHeartbeat writes nothing and the 4h TTL lapses.
+   updateHeartbeat({ sessionId, repoRoot: resolveOwnLockRootFor({ sessionId }).root });
    ```
 
    Skip silently if `persistence: false` in Session Config (no session.lock exists in that mode).
@@ -525,11 +528,16 @@ The helper is `scripts/lib/agent-status.mjs`. The writers (`setStatus`, `setProg
 
    ```js
    import { setStatus, setProgress } from '../../scripts/lib/agent-status.mjs';
+   import { resolveOwnLockRootFor } from '../../scripts/lib/own-lock-root.mjs';
+
+   // Once per wave: the root beside this session's own lock. The SubagentStart/Stop hooks write there too, and
+   // the HUD and the tmux pane read there (#1730); without it the writers default to process.cwd().
+   const statusOpts = { repoRoot: resolveOwnLockRootFor({ sessionId }).root };
 
    // For each agent dispatched in this wave (i = 0-based position, total = wave agent count):
-   await setStatus(agentId, `dispatched — ${subagentType}`);              // free-text variant
+   await setStatus(agentId, `dispatched — ${subagentType}`, statusOpts);              // free-text variant
    // — or —
-   await setProgress(agentId, { step: i + 1, total, label: subagentType }); // progress variant
+   await setProgress(agentId, { step: i + 1, total, label: subagentType }, statusOpts); // progress variant
    ```
 
    `agentId` is a stable per-agent key (e.g. `wave${waveN}-${i}-${subagentType}`). There is **no separate "agent-start" hook distinct from dispatch** — wave agents are in-process `Agent()` calls with no PID/TTY (see `skills/tmux-layout/SKILL.md § When NOT to Use`), so dispatch IS the start signal. Do not invent one.
@@ -538,14 +546,14 @@ The helper is `scripts/lib/agent-status.mjs`. The writers (`setStatus`, `setProg
 
    ```js
    // status ∈ {'done','partial','failed'} from the agent's STATUS: line
-   await setStatus(agentId, status);
+   await setStatus(agentId, status, statusOpts);
    ```
 
 3. **wave-end rollup** — in `### 3a. Post-Wave: Update STATE.md`, beside the `updateHeartbeat` call (step 5), push one wave-level rollup using a wave-scoped key:
 
    ```js
    // e.g. agentId = `wave${waveN}` ; counts from the wave's per-agent results
-   await setStatus(`wave${waveN}`, `wave ${waveN} complete — ${done} done, ${partial} partial, ${failed} failed`);
+   await setStatus(`wave${waveN}`, `wave ${waveN} complete — ${done} done, ${partial} partial, ${failed} failed`, statusOpts);
    ```
 
 A push failure (timeout, fs-error, invalid-input) is logged to the wave progress update at most as a one-line WARN — never block, never retry, never surface to the user. If `agent-status.mjs` is absent (older plugin checkout), wrap the import defensively and no-op, exactly as `layouts.mjs` does for its telemetry import.

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

@@ -165,7 +165,7 @@ Before each wave dispatch:
    5. Delete `<state-dir>/wave-scope.json`
    6. Write Phase 2 wave-scope.json with test file allowedPaths (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
    7. Dispatch test/review agents
-7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup). Delete `<state-dir>/filescopes/` in the same step — the per-agent scope files (§ 3.1) are wave-local working state, and a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified. Delete THIS session's dispatch ledger in the same step too — `hooks/pre-task-scope-disjoint.mjs` keeps one file per session since #1493, `.orchestrator/wave-dispatch-scopes.<session-id>.json` plus its `.lock`, under the session root (the repo root, or the worktree the session entered). Only your own: a file beside it named after another id holds a peer session's live claims. Delete only an id that is already path-safe (the hook names the file after it unchanged); anything else is left behind, inert, because no other session reads it:
+7. After the final wave completes, delete `<state-dir>/wave-scope.json` (cleanup). Make the session's own commits BEFORE this step: while the last wave's manifest is active, `wave-scope-commit-guard` admits files of earlier waves only through their `filescopes/wave-<k>.scopes.json` sidecars (#1680). Delete `<state-dir>/filescopes/` in the same step — the per-agent scope files (§ 3.1) are wave-local working state, and a stale `wave-<N>/` directory left behind is a scope claim nobody re-verified. Delete THIS session's dispatch ledger in the same step too — `hooks/pre-task-scope-disjoint.mjs` keeps one file per session since #1493, `.orchestrator/wave-dispatch-scopes.<session-id>.json` plus its `.lock`, under the session root (the repo root, or the worktree the session entered). Only your own: a file beside it named after another id holds a peer session's live claims. Delete only an id that is already path-safe (the hook names the file after it unchanged); anything else is left behind, inert, because no other session reads it:
 
    ```bash
    SID="${CLAUDE_CODE_SESSION_ID:-}"

package/assets/og-card.svg

@@ -1,47 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" role="img" aria-label="Session Orchestrator">
-  <title>Session Orchestrator</title>
-  <desc>Wave-based Claude Code sessions with quality gates</desc>
-
-  <!-- Background: GitHub-dark -->
-  <rect width="1280" height="640" fill="#0d1117"/>
-
-  <!-- Subtle gradient accent in top-right -->
-  <defs>
-    <radialGradient id="accent" cx="80%" cy="20%" r="50%">
-      <stop offset="0%" stop-color="#1f6feb" stop-opacity="0.18"/>
-      <stop offset="100%" stop-color="#0d1117" stop-opacity="0"/>
-    </radialGradient>
-    <linearGradient id="waveStroke" x1="0" y1="0" x2="1" y2="0">
-      <stop offset="0%" stop-color="#1f6feb" stop-opacity="0.55"/>
-      <stop offset="50%" stop-color="#238636" stop-opacity="0.55"/>
-      <stop offset="100%" stop-color="#d29922" stop-opacity="0.55"/>
-    </linearGradient>
-  </defs>
-  <rect width="1280" height="640" fill="url(#accent)"/>
-
-  <!-- Five wave glyphs as watermark (echo of icon.svg motif) on right side -->
-  <g transform="translate(740, 140)" opacity="0.85">
-    <path d="M 0 40 Q 100 0 200 40 T 400 40" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
-    <path d="M 0 110 Q 100 70 200 110 T 400 110" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
-    <path d="M 0 180 Q 100 140 200 180 T 400 180" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
-    <path d="M 0 250 Q 100 210 200 250 T 400 250" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
-    <path d="M 0 320 Q 100 280 200 320 T 400 320" fill="none" stroke="url(#waveStroke)" stroke-width="10" stroke-linecap="round"/>
-  </g>
-
-  <!-- Title block (left-aligned) -->
-  <g font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif">
-    <!-- Eyebrow -->
-    <text x="80" y="170" font-size="24" font-weight="500" fill="#7d8590" letter-spacing="4">CLAUDE CODE PLUGIN</text>
-
-    <!-- Title -->
-    <text x="80" y="265" font-size="80" font-weight="700" fill="#f0f6fc">Session</text>
-    <text x="80" y="355" font-size="80" font-weight="700" fill="#f0f6fc">Orchestrator</text>
-
-    <!-- Subtitle -->
-    <text x="80" y="430" font-size="32" font-weight="400" fill="#c9d1d9">Wave-based Claude Code sessions</text>
-    <text x="80" y="472" font-size="32" font-weight="400" fill="#c9d1d9">with quality gates</text>
-
-    <!-- Footer -->
-    <text x="80" y="570" font-size="24" font-weight="400" fill="#7d8590">Claude Code · Codex CLI · Cursor IDE · MIT</text>
-  </g>
-</svg>

package/assets/wave-lifecycle.svg

@@ -1,98 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1062 372" width="1062" height="372" role="img" aria-labelledby="wl-title wl-desc" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif">
-  <title id="wl-title">Session Orchestrator wave lifecycle</title>
-  <desc id="wl-desc">Flow diagram. Precondition: /bootstrap runs once per repository, then /session agrees the scope, then /go executes. /go runs five typed waves left to right: 1 Discovery (read-only audit), gate G1, 2 Impl-Core (primary code), gate G2, 3 Impl-Polish (integration and edge cases), gate G3, 4 Quality (simplification pass, then tests), gate G4 Full Gate, 5 Finalization (commit and close). Gates G1 to G3 are Quality-Lite (typecheck, lint, test); G4 is the Full Gate and additionally runs the full suite plus a debug-artifact scan. After wave 5, /close verifies every planned item, runs the Full Gate, files carryover issues, commits, and writes the session record.</desc>
-
-  <defs>
-    <marker id="wl-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
-      <path d="M 0 0 L 10 5 L 0 10 z" fill="#94A3B8"/>
-    </marker>
-  </defs>
-
-  <!-- heading -->
-  <rect x="28" y="16" width="430" height="32" rx="6" fill="#1E293B"/>
-  <text x="44" y="37" font-size="14" font-weight="600" fill="#F8FAFC">Session Orchestrator — wave lifecycle and gates</text>
-
-  <!-- row A: the three commands -->
-  <rect x="28" y="68" width="196" height="48" rx="8" fill="#475569"/>
-  <text x="126" y="90" font-size="14" font-weight="600" fill="#F8FAFC" text-anchor="middle">/bootstrap</text>
-  <text x="126" y="106" font-size="11" fill="#E2E8F0" text-anchor="middle">once per repo — writes bootstrap.lock</text>
-
-  <line x1="228" y1="92" x2="248" y2="92" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-
-  <rect x="252" y="68" width="196" height="48" rx="8" fill="#1F6FEB"/>
-  <text x="350" y="90" font-size="14" font-weight="600" fill="#FFFFFF" text-anchor="middle">/session [type]</text>
-  <text x="350" y="106" font-size="11" fill="#DBEAFE" text-anchor="middle">research + Q&#38;A — agree the scope</text>
-
-  <line x1="452" y1="92" x2="472" y2="92" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-
-  <rect x="476" y="68" width="140" height="48" rx="8" fill="#1F6FEB"/>
-  <text x="546" y="90" font-size="14" font-weight="600" fill="#FFFFFF" text-anchor="middle">/go</text>
-  <text x="546" y="106" font-size="11" fill="#DBEAFE" text-anchor="middle">executes the waves</text>
-
-  <!-- /go down into wave 1 -->
-  <polyline points="546,116 546,134 93,134 93,146" fill="none" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-
-  <!-- row B: waves and gates -->
-  <rect x="28" y="150" width="130" height="76" rx="8" fill="#0F766E"/>
-  <text x="93" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">1 · Discovery</text>
-  <text x="93" y="198" font-size="11" fill="#CCFBF1" text-anchor="middle">read-only audit</text>
-  <text x="93" y="213" font-size="11" fill="#CCFBF1" text-anchor="middle">no writes</text>
-
-  <line x1="160" y1="188" x2="170" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="172" y="166" width="56" height="44" rx="6" fill="#64748B"/>
-  <text x="200" y="185" font-size="13" font-weight="700" fill="#FFFFFF" text-anchor="middle">G1</text>
-  <text x="200" y="200" font-size="9" fill="#F1F5F9" text-anchor="middle">lite</text>
-
-  <line x1="230" y1="188" x2="240" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="242" y="150" width="130" height="76" rx="8" fill="#1F6FEB"/>
-  <text x="307" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">2 · Impl-Core</text>
-  <text x="307" y="198" font-size="11" fill="#DBEAFE" text-anchor="middle">primary code</text>
-  <text x="307" y="213" font-size="11" fill="#DBEAFE" text-anchor="middle">architecture first</text>
-
-  <line x1="374" y1="188" x2="384" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="386" y="166" width="56" height="44" rx="6" fill="#64748B"/>
-  <text x="414" y="185" font-size="13" font-weight="700" fill="#FFFFFF" text-anchor="middle">G2</text>
-  <text x="414" y="200" font-size="9" fill="#F1F5F9" text-anchor="middle">lite</text>
-
-  <line x1="444" y1="188" x2="454" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="456" y="150" width="130" height="76" rx="8" fill="#3B82F6"/>
-  <text x="521" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">3 · Impl-Polish</text>
-  <text x="521" y="198" font-size="11" fill="#EFF6FF" text-anchor="middle">integration</text>
-  <text x="521" y="213" font-size="11" fill="#EFF6FF" text-anchor="middle">edge cases</text>
-
-  <line x1="588" y1="188" x2="598" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="600" y="166" width="56" height="44" rx="6" fill="#64748B"/>
-  <text x="628" y="185" font-size="13" font-weight="700" fill="#FFFFFF" text-anchor="middle">G3</text>
-  <text x="628" y="200" font-size="9" fill="#F1F5F9" text-anchor="middle">lite</text>
-
-  <line x1="658" y1="188" x2="668" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="670" y="150" width="130" height="76" rx="8" fill="#7C3AED"/>
-  <text x="735" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">4 · Quality</text>
-  <text x="735" y="198" font-size="11" fill="#EDE9FE" text-anchor="middle">simplify first,</text>
-  <text x="735" y="213" font-size="11" fill="#EDE9FE" text-anchor="middle">then write tests</text>
-
-  <line x1="802" y1="188" x2="812" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="814" y="160" width="76" height="56" rx="6" fill="#D29922"/>
-  <text x="852" y="182" font-size="13" font-weight="700" fill="#1F2937" text-anchor="middle">G4</text>
-  <text x="852" y="199" font-size="10" font-weight="600" fill="#1F2937" text-anchor="middle">Full Gate</text>
-
-  <line x1="892" y1="188" x2="902" y2="188" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-  <rect x="904" y="150" width="130" height="76" rx="8" fill="#238636"/>
-  <text x="969" y="180" font-size="13" font-weight="600" fill="#FFFFFF" text-anchor="middle">5 · Finalization</text>
-  <text x="969" y="198" font-size="11" fill="#DCFCE7" text-anchor="middle">commit + close</text>
-
-  <!-- gate legend -->
-  <rect x="28" y="246" width="880" height="30" rx="6" fill="#1E293B"/>
-  <text x="44" y="266" font-size="11" fill="#CBD5E1">G1–G3 = Quality-Lite gate (typecheck · lint · test) + inter-wave session-reviewer · G4 = Full Gate (adds the full suite and a debug-artifact scan)</text>
-
-  <!-- wave 5 down into /close -->
-  <polyline points="969,228 969,296" fill="none" stroke="#94A3B8" stroke-width="2" marker-end="url(#wl-arrow)"/>
-
-  <!-- row C -->
-  <rect x="28" y="300" width="862" height="48" rx="8" fill="#334155"/>
-  <text x="44" y="321" font-size="12" font-weight="600" fill="#F8FAFC">After the last wave: every planned item is verified against evidence, the Full Gate runs once more,</text>
-  <text x="44" y="338" font-size="12" font-weight="600" fill="#F8FAFC">unfinished work becomes carryover issues, files are staged individually, the session record is written.</text>
-
-  <rect x="904" y="300" width="130" height="48" rx="8" fill="#238636"/>
-  <text x="969" y="330" font-size="14" font-weight="600" fill="#FFFFFF" text-anchor="middle">/close</text>
-</svg>