session-orchestrator 5.4.0 → 5.6.0

package/skills/discovery/probes/vault-narrative-staleness.mjs

@@ -24,6 +24,7 @@
 
 import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { expandTilde } from '../../../scripts/lib/common.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -73,9 +74,12 @@ function parseFrontmatter(text) {
 // Helpers
 // ---------------------------------------------------------------------------
 
+// #1506 pt 6: the committed value is `~/Projects/vault`; unexpanded it resolved
+// against the cwd (`<cwd>/~/Projects/vault`), where a stray `~` directory
+// produced a false all-clear (0 stale narratives instead of 33).
 function resolveVaultDir(projectRoot, config) {
-  if (config?.['vault-integration']?.['vault-dir']) return config['vault-integration']['vault-dir'];
-  if (process.env.VAULT_DIR) return process.env.VAULT_DIR;
+  if (config?.['vault-integration']?.['vault-dir']) return expandTilde(config['vault-integration']['vault-dir']);
+  if (process.env.VAULT_DIR) return expandTilde(process.env.VAULT_DIR);
   return null;
 }
 

package/skills/discovery/probes/vault-staleness.mjs

@@ -38,6 +38,7 @@
 
 import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { expandTilde } from '../../../scripts/lib/common.mjs';
 
 // ---------------------------------------------------------------------------
 // Minimal YAML frontmatter parser — top-level scalar fields only (<30 lines).
@@ -112,13 +113,18 @@ export async function runProbe(projectRoot, config) {
   try {
     // --- Config validation (early exit paths) ---
 
-    const vaultDir = config?.['vault-integration']?.['vault-dir'];
-    if (!vaultDir) {
+    const configuredVaultDir = config?.['vault-integration']?.['vault-dir'];
+    if (!configuredVaultDir) {
       return makeSkip('vault-dir not configured');
     }
+    // #1506 pt 6: the committed value is `~/Projects/vault`; unexpanded it
+    // resolved against the cwd (`<cwd>/~/Projects/vault`), where a stray `~`
+    // directory produced a false all-clear (0 projects scanned instead of 45).
+    const vaultDir = expandTilde(configuredVaultDir);
 
     if (!existsSync(vaultDir)) {
-      return makeSkip(`vault-dir does not exist: ${vaultDir}`);
+      // The configured spelling, not the expanded one: no home dir in the output.
+      return makeSkip(`vault-dir does not exist: ${configuredVaultDir}`);
     }
 
     const projectsDir = join(vaultDir, '01-projects');

package/skills/docs-orchestrator/SKILL.md

@@ -177,9 +177,15 @@ No Docs task generated for this audience.
 documents what the docs-writer MUST do when executing a dispatched Docs task.
 
 Before writing any documentation, the docs-writer MUST read and ingest the actual
-source material provided in the task prompt. The canonical four source types are:
-
-1. **diff** — `git diff $SESSION_START_REF..HEAD` — the verbatim diff of all changes
+source material provided in the task prompt. The canonical four source types are
+below. `$SESSION_RANGE` is ONE complete diff range: inside a wave run it is
+`"$SESSION_START_REF..HEAD"` (the SHA wave-executor pins at Pre-Wave 1a); at
+session end it is what the accessor in `skills/session-end/plan-verification.md`
+§ SESSION_START_REF accessor exports — the pinned SHA, else the resolved
+`<base>...HEAD`, never a hard-coded `origin/main`. Diffs take the range; the log
+keeps the two-dot `$SESSION_START_REF..HEAD`, which is the correct form for `git log`.
+
+1. **diff** — `git diff "$SESSION_RANGE"` — the verbatim diff of all changes
    made during this session. This is the primary authoritative source for what changed.
 2. **git-log** — `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` — commit
    messages and associated bodies. Secondary context for all audiences; use to
@@ -284,9 +290,10 @@ The docs-writer MUST emit a brief structured output summary:
 1. Collect every task classified as `Docs` in the plan.
 2. For each task, resolve the expected `file-pattern` target and check for a diff:
    ```bash
-   git diff --name-only $SESSION_START_REF..HEAD
+   git diff --name-only "$SESSION_RANGE"
    ```
-   Match the output against the task's file-pattern using glob matching.
+   (`$SESSION_RANGE` from the session-end accessor above; an empty range is a skip
+   with a named reason, never "no docs changed".) Match the output against the task's file-pattern using glob matching.
 3. Classify gaps by severity:
    - **missing diff** — no matching file was changed; the task did not run or produced
      no output.

package/skills/docs-orchestrator/audience-mapping.md

@@ -23,14 +23,16 @@ traceable source gets `<!-- REVIEW: source needed -->` — the agent NEVER inven
 
 | Source | Command / Path | Primary audience(s) | Notes |
 |--------|---------------|---------------------|-------|
-| **diff** | `git diff $SESSION_START_REF..HEAD` | Dev, Vault | Authoritative for what changed and when. Preferred primary source for Dev. |
+| **diff** | `git diff "$SESSION_RANGE"` | Dev, Vault | Authoritative for what changed and when. Preferred primary source for Dev. |
 | **git-log** | `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` | All | Secondary context; use to reconstruct the "why" when diffs alone are ambiguous. |
 | **session-memory** | `~/.claude/projects/<project>/memory/session-*.md`, `.orchestrator/` outputs | Vault, User | Primary for Vault narratives (status updates, decisions made in conversation). Also primary for User tasks designed interactively. |
 | **affected-files** | Files in wave-scope `allowedPaths` / coordinator `affected-files` context block | User, Dev | Primary for understanding updated interfaces, config schemas, or module structures. |
 
+`$SESSION_RANGE` is one complete diff range — `"$SESSION_START_REF..HEAD"` inside a wave run, the session-end accessor's export at close (`../session-end/plan-verification.md` § SESSION_START_REF accessor; never a hard-coded `origin/main`). The log keeps the two-dot `$SESSION_START_REF..HEAD`, the correct form for `git log`.
+
 **Detailed source descriptions:**
 
-1. **diff** — Direct code changes from `git diff $SESSION_START_REF..HEAD`. Authoritative
+1. **diff** — Direct code changes from `git diff "$SESSION_RANGE"`. Authoritative
    for Dev narratives (what changed and why) and Vault decisions (what was decided, when).
    Preferred primary source for Dev audience tasks.
 2. **git-log** — Commit messages and associated PR/MR bodies from
@@ -90,7 +92,7 @@ Trigger: New `coordinator-snapshot.mjs` module added; CWD-drift guard introduced
 ## Allowed Sources
 Only these four sources are permitted. Do not use general knowledge.
 
-- diff: `git diff $SESSION_START_REF..HEAD` (provided below)
+- diff: `git diff "$SESSION_RANGE"` (provided below)
 - git-log: `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` (provided below)
 - session-memory: wave summaries and agent outputs from
   ~/.claude/projects/<project>/memory/session-*.md and .orchestrator/ (provided below)

package/skills/evolve/SKILL.md

@@ -171,7 +171,10 @@ If user selects "Confidence ändern", "Ablauf verlängern", or "Delete specific
 
 Use the same archive-safe pipeline as Phase 3, Step 3.5 — **never** a hand-rolled `>` rewrite (#1017):
 
-1. Read all lines from `learnings.jsonl`
+1. Snapshot the store into the sidecar exactly as Phase 3, Step 3.5(1) does (`--prune --snapshot`,
+   with the same `--file` / `--archive` the apply will use) and work on the sidecar, never on a
+   separate read of `learnings.jsonl` (#1486). A snapshot exit `1` (a malformed store line, or a
+   PATH that would replace a ledger) wrote nothing: surface it and stop
 2. Apply the selected operation to selected learnings:
    - **Boost:** +0.15 confidence (cap 1.0), reset expires_at to `deriveExpiresAt(now, type)` (per-type TTL, `scripts/lib/learnings/schema.mjs`)
    - **Reduce:** -0.2 confidence
@@ -182,7 +185,13 @@ Use the same archive-safe pipeline as Phase 3, Step 3.5 — **never** a hand-rol
    - **Extend:** reset expires_at to `deriveExpiresAt(now, type)` — `learning-expiry-days` is parsed but read by no script (`skills/_shared/config-reading.md` § Learning Expiry Semantics)
 3. Steps 3–5 of the old prose (prune / consolidate / rewrite) are `pruneLearnings()` — run the
    **exact** Step 3.5(5) invocation, writing the post-operation entry set to the `--entries`
-   sidecar. It prunes
+   sidecar below its line-1 `_store_generation` header. Exit `1` or `2`: surface the error and
+   stop (`1` includes a sidecar snapshotted from another store than `--file`). Exit `3` means the
+   store changed after the snapshot and nothing was written: snapshot into a FRESH path,
+   re-apply the selected operations to the records in that file, and apply it once more — a
+   second consecutive `3`: stop and report. Never move the fresh header onto the old sidecar's
+   records, whose missing peer change the prune would archive `pruned` (Step 3.5(5) carries the
+   full exit-code rule). It prunes
    (`expires_at` < now → `expired`; `confidence <= 0.0` → `pruned`), consolidates duplicates
    (same `type` + non-empty `subject`, highest confidence wins, loser archived `superseded` with
    `_superseded_by`; null-subject entries preserved individually per #284), and rewrites through

package/skills/evolve/references/evolve-analyze-mode.md

@@ -208,7 +208,7 @@ If user selects "Skip all" or selects nothing, abort gracefully: "No learnings s
 
 For confirmed learnings, use atomic rewrite strategy:
 
-1. Read ALL existing lines from `.orchestrator/metrics/learnings.jsonl` (if exists) into memory. If not found, check `<state-dir>/metrics/learnings.jsonl` as a legacy fallback. If legacy data is found, it will be migrated to the v2 path on write (step 5).
+1. Snapshot the store into the sidecar: `node scripts/sweep-expired-learnings.mjs --prune --snapshot .orchestrator/tmp/learnings-next.jsonl`. It writes every record of `.orchestrator/metrics/learnings.jsonl` to that file behind a line-1 `{"_store_generation": "sha256:…", "_store_path": "…"}` header naming the exact store state and the store they came from. Read the SIDECAR, not the store, as your starting set — step 5 explains why. On a non-default store, pass the SAME `--file` / `--archive` here as to the step-5 apply: the apply refuses (exit `1`) a sidecar snapshotted from another store. A store holding a malformed (unparseable) line does NOT stop the snapshot: it prints a stderr WARN naming the line numbers and adds a `malformed` count to its summary. The sidecar carries records only, and the step-5 apply keeps the store's malformed lines verbatim at the end of the rewrite, never archived — report the count to the operator; never hand-edit the store to remove them. The one sanctioned repair is `node scripts/sweep-expired-learnings.mjs --drop-malformed --line N [--line M …]`: a dry run by default, printing each line's preview, any readable record it still carries (`bom` / `embedded_record`) and the store generation; only after the operator confirmed those previews, `--drop-malformed --line N --apply --generation <TOKEN> --repo-root "$(pwd)"` removes the lines (backup `<stem>.pre-drop-malformed.jsonl.bak-<ISO>` beside the store). A line still holding a readable record needs `--accept-embedded`; a store that changed since the dry run exits `3`. If the snapshot holds zero records, check `<state-dir>/metrics/learnings.jsonl` as a legacy fallback and add its records below line 1; they are migrated to the v2 path on write (step 5).
 2. Apply confidence updates for confirmed existing learnings:
    - Increment confidence by +0.15
    - Cap at 1.0
@@ -235,14 +235,22 @@ For confirmed learnings, use atomic rewrite strategy:
    deleted 11 of 13 `learning-id` provenance targets referenced by rendered `.claude/rules/*.md`.
    Do not hand-roll a `jq | ... > learnings.jsonl` pass; it bypasses every #721 safety net.
 
-   Write the full next-generation entry set (existing entries **with** the step-2/3 confidence
-   updates, **plus** the step-4 new learnings) as JSONL to a temp sidecar **via the Write tool**
-   (not a shell `>` redirect — the destructive-command guard blocks it) at
-   `.orchestrator/tmp/learnings-next.jsonl` (the Write tool creates the missing
-   `.orchestrator/tmp/` itself; from a shell, `mkdir -p .orchestrator/tmp` first). The sidecar
-   lives under `.orchestrator/tmp/`, never `.orchestrator/metrics/`, because `tmp/` is outside
+   Turn the step-1 sidecar `.orchestrator/tmp/learnings-next.jsonl` into the full
+   next-generation entry set (existing entries **with** the step-2/3 confidence updates,
+   **plus** the step-4 new learnings) **via the Write or Edit tool** (not a shell `>` redirect —
+   the destructive-command guard blocks it), **keeping line 1, the `_store_generation` header,
+   unchanged and first**. The sidecar lives under `.orchestrator/tmp/`, never
+   `.orchestrator/metrics/`, because `tmp/` is outside
    the ledger guard's `ledger-delete-protected` denylist — a metrics-dir sidecar made the
-   cleanup `rm` below a blocked command (#1453). Then invoke the
+   cleanup `rm` below a blocked command (#1453).
+
+   **Snapshot → token → apply refuses on drift (#1486).** Minutes pass between step 1 and the
+   call below, and a peer session may append to the store meanwhile. Such a record is on disk
+   but absent from your sidecar, so the prune would archive it `pruned` — a delete nobody
+   decided, which the store lock cannot prevent because your read happened before it, in
+   another process. So the prune re-reads the store under its lock and compares that
+   generation with the header: any difference writes nothing and exits `3`. A sidecar without
+   the header exits `1` — the header is mandatory, never optional. Then invoke the
    `--prune` subcommand of the sweep CLI. **This call is also `/evolve`'s ONLY
    `orchestrator.evolve.completed` success emit (#1206)** — export `N` (Step 3.5(4)'s
    new-learnings count), `M` (Step 3.5(2)'s reinforced-existing count) and `DURATION_MS`
@@ -258,7 +266,8 @@ For confirmed learnings, use atomic rewrite strategy:
    ```
 
    `--file` / `--archive` default to the canonical store + archive paths — pass them only when
-   operating on a non-default pair. The command prints ONE JSON line; capture it as `$PRUNE` and
+   operating on a non-default pair, and then pass the same pair to the step-1 `--snapshot` too.
+   The command prints ONE JSON line; capture it as `$PRUNE` and
    report its `{scanned, kept, archived, byReason}` in the final summary — `$PRUNE.archived` is
    also the `pruned` counter the emit above just wrote, so there is nothing left to compute for
    the telemetry after this line. Preview first with `--prune --dry-run --json` (same counts,
@@ -273,12 +282,22 @@ For confirmed learnings, use atomic rewrite strategy:
    > independently of the write it reported on. Do not re-inline either, and do not hand-roll a
    > `jq | ... > learnings.jsonl` pass — that bypasses every #721 safety net.
 
-   **Exit codes are the no-op rule.** `0` = applied (or a clean no-op). `1` = input error: the
-   sidecar is absent, carries a malformed line, or holds no records — the store and the archive
-   were **not touched**;
-   re-write the sidecar and re-run. `2` = the prune itself failed inside the lib. On any non-zero
-   exit, surface the error and stop — never retry with a shell rewrite, and never delete `$NEXT`
-   (the `&&` above already withholds the `rm`, so the assembled generation survives for a retry).
+   **Exit codes are the no-op rule.** `0` = applied (or a clean no-op). On `1` and `2`, surface
+   the error and stop. `1` = input error: the sidecar is absent, carries a malformed line, holds
+   no records, lacks its line-1 `_store_generation` header, or was snapshotted from another store
+   than this call's `--file` — the store and the archive were **not touched**. `2` = the prune
+   itself failed inside the lib. `3` =
+   `store-generation-mismatch`: the store changed after step 1 and nothing was written. This one
+   is a retry, not a stop: snapshot into a FRESH path
+   (`--prune --snapshot .orchestrator/tmp/learnings-next-retry.jsonl`, with the same `--file` /
+   `--archive` as the apply), re-apply this run's
+   decisions to the records in THAT file — they now include the peer's change — and run the block
+   above with its `NEXT` set to the fresh path. Retry once: a second consecutive `3` means the
+   store keeps moving under you — stop and report it. Never move the fresh header onto the old
+   sidecar's records: they lack exactly the peer change the header exists to protect, so the
+   prune would archive it `pruned` (the error prints no token for that reason). On every exit,
+   never retry with a shell rewrite and never delete `$NEXT` — the `&&` above withholds the `rm`,
+   so the assembled generation survives as the record of this run's decisions.
 
    `pruneLearnings()` — the function the subcommand calls — performs steps 6 + 7 + 8 mechanically
    and archives **every** record that
@@ -313,13 +332,14 @@ For confirmed learnings, use atomic rewrite strategy:
 
    b. Resolve the vault directory: use `$CONFIG."vault-integration"."vault-dir"` if non-null, otherwise fall back to the `$VAULT_DIR` environment variable. If neither is set, emit a warning and skip. Report `vault-dir=<path> (Quelle: <source>)`, where `<source>` is `$CONFIG."vault-integration"."vault-dir-source"` (`env`, `match`, `owner`, `committed`), or `env VAULT_DIR` when the fallback was used.
 
-   c. Invoke the mirror script. Derive a synthetic `EVOLVE_SESSION_ID` so the vault-mirror auto-commit phase (#31) produces a traceable commit subject (`chore(vault): mirror evolve-<date> — N learnings + 0 sessions`). Pass `--vault-name` when `vault-integration.vault-name` is set in Session Config:
+   c. Invoke the mirror script from the repo root, by its plugin path — `--repo-root "$PWD"` plus an absolute `--source` make the vault namespace this repo's identity, and a ledger from a different repo is refused (exit 2, `source-repo-mismatch`, #1503) instead of overwriting another project's notes. Derive a synthetic `EVOLVE_SESSION_ID` so the vault-mirror auto-commit phase (#31) produces a traceable commit subject (`chore(vault): mirror evolve-<date> — N learnings + 0 sessions`). Pass `--vault-name` when `vault-integration.vault-name` is set in Session Config:
       ```bash
       EVOLVE_SESSION_ID="evolve-$(date -u +%Y-%m-%d-%H%M)"
       EVOLVE_VAULT_NAME=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-name" // empty')
       node "$PLUGIN_ROOT/scripts/vault-mirror.mjs" \
         --vault-dir "<vault-dir>" \
-        --source .orchestrator/metrics/learnings.jsonl \
+        --repo-root "$PWD" \
+        --source "$PWD/.orchestrator/metrics/learnings.jsonl" \
         --kind learning \
         --session-id "$EVOLVE_SESSION_ID" \
         ${EVOLVE_VAULT_NAME:+--vault-name "$EVOLVE_VAULT_NAME"}

package/skills/session-end/learning-patterns.md

@@ -10,7 +10,7 @@
 Analyze the completed session to extract reusable learnings for future sessions.
 
 **What to extract:**
-- **Fragile files**: use `git log --name-only --format="" $SESSION_START_REF..HEAD | sort | uniq -c | sort -rn | head -10` to find files changed most frequently across commits this session. Files appearing in 3+ commits are candidates for fragile-file learnings. Cross-reference with `<state-dir>/STATE.md` Wave History to correlate with specific waves.
+- **Fragile files**: use `git log --name-only --format="" $SESSION_START_REF..HEAD | sort | uniq -c | sort -rn | head -10` to find files changed most frequently across commits this session. Files appearing in 3+ commits are candidates for fragile-file learnings. Cross-reference with `<state-dir>/STATE.md` Wave History to correlate with specific waves. Skip this when `$SESSION_START_REF` is empty (the accessor's skip in `plan-verification.md`): `git log ..HEAD` reads as `HEAD..HEAD` and prints nothing with exit 0, which would pass for "no fragile files".
 - **Effective sizing**: actual agent count vs. planned — what worked for this complexity level
 - **Recurring issues**: same issue type appearing across waves (e.g., type errors, missing imports)
 - **Scope guidance**: was the scope too large/small? How many issues fit comfortably in one session?
@@ -82,7 +82,7 @@ Before writing new learnings, read `.orchestrator/metrics/learnings.jsonl` and c
       | 9 | 0.05 | active |
       | 10 | 0.00 | pruned next write |
 
-   e. Exit codes: `0` applied (or a clean no-op); `1` input or validation error — the message names the record id and the failing field, and **nothing was written**: fix the sidecar and re-run; `2` store/IO error — report it, do not retry by hand.
-   f. **Hand-writing the store is FORBIDDEN** — no shell rewrite, no shell append, no `jq … | tee`. Those bypass validation, the `.bak` snapshot and the archive (see `skills/evolve/SKILL.md` § Critical Rules). The blocking validator `scripts/lib/validate/check-learnings-shell-writes.mjs` fails `validate-plugin` on prose that instructs one.
+   e. Exit codes: `0` applied (or a clean no-op); `1` input or validation error — the message names the record id and the failing field, and **nothing was written**: fix the sidecar and re-run; `2` store/IO error — report it, do not retry by hand. Unparseable lines already in the store are NOT an error and never block the write: the CLI keeps them verbatim at the end of the store (never archived), reports `malformed: N` in its summary and prints a stderr WARN with their line numbers — carry that count into the Phase 6 report.
+   f. **Hand-writing the store is FORBIDDEN** — no shell rewrite, no shell append, no `jq … | tee`, and that includes "repairing" a malformed line the WARN reports: it stays until the operator decides. Those bypass validation, the `.bak` snapshot and the archive (see `skills/evolve/SKILL.md` § Critical Rules). The blocking validator `scripts/lib/validate/check-learnings-shell-writes.mjs` fails `validate-plugin` on prose that instructs one. Once the operator decides to remove a line, the ONE sanctioned path is the CLI (#1500): `node scripts/sweep-expired-learnings.mjs --drop-malformed --line N` previews it (dry run: the line's text and the store `generation`), then `node scripts/sweep-expired-learnings.mjs --drop-malformed --line N --generation <that token> --apply --repo-root .` removes it. The apply copies the whole store to `learnings.pre-drop-malformed.jsonl.bak-<ISO>` beside it first and appends one `orchestrator.learnings.malformed_dropped` record. Line numbers move with every rewrite (malformed lines go to the end), so a store changed since the dry run exits `3` — re-run the dry run; a line that is not malformed exits `1`. Both write nothing. A malformed line that still holds a readable record — behind a UTF-8 BOM, or fused after a torn prefix (the dry run reports `bom` / `embedded_record`) — is refused at `--apply` with exit `1` as well, because dropping it loses that record; `--accept-embedded` is the operator's explicit decision to drop it anyway (the pre-drop snapshot keeps the line).
    g. Proof it ran: `--apply` appends one `orchestrator.learnings.session_write_applied` record to `.orchestrator/metrics/events.jsonl` (`appended`, `confirmed`, `contradicted`, `decayed`, `pruned`). No record = no write.
    h. If no existing file and no new learnings: skip

package/skills/session-end/metrics-collection.md

@@ -19,7 +19,7 @@ Finalize session metrics by reading the wave data accumulated during execution:
    - `total_agents`: sum of agents across all waves
    - `total_files_changed`: unique files changed across entire session (from `git diff --stat`)
    - `agent_summary`: `{complete: N, partial: N, failed: N, spiral: N}`
-   - **Coordinator-direct fallback (#1321):** when Wave History is empty AND the session ran coordinator-direct (housekeeping — `scripts/lib/session-shape.mjs:364-376` resolves it to ONE coordinator-direct wave that `/go` never hands to wave-executor, so no wave metrics are captured — or the express path), do NOT write `waves: []` / `total_waves: 0`. Write exactly one wave entry `{wave: 1, role: "Housekeeping", agent_count: 0, coordinator_direct: true, files_changed: <N>, quality: "<pass|fail|skip — the close quality-gate result>"}` with `total_waves: 1`, `total_agents: 0`. On this path both that wave's `files_changed` and `total_files_changed` are `git diff --name-only "$SESSION_START_REF..HEAD" | wc -l` (accessor: `plan-verification.md` § SESSION_START_REF accessor). The single definition of this shape is `isCoordinatorDirectHousekeeping(record)` in `scripts/lib/session-schema/filters.mjs` (every wave `role: "Housekeeping"` AND `coordinator_direct: true`). Consumers key on it (eval gate-health, evolve effective-sizing), so write `role` and `coordinator_direct` exactly as shown. `session_type` alone never marks it.
+   - **Coordinator-direct fallback (#1321):** when Wave History is empty AND the session ran coordinator-direct (housekeeping — `scripts/lib/session-shape.mjs:364-376` resolves it to ONE coordinator-direct wave that `/go` never hands to wave-executor, so no wave metrics are captured — or the express path), do NOT write `waves: []` / `total_waves: 0`. Write exactly one wave entry `{wave: 1, role: "Housekeeping", agent_count: 0, coordinator_direct: true, files_changed: <N>, quality: "<pass|fail|skip — the close quality-gate result>"}` with `total_waves: 1`, `total_agents: 0`. On this path both that wave's `files_changed` and `total_files_changed` are `git diff --name-only "$SESSION_RANGE" | wc -l` (accessor: `plan-verification.md` § SESSION_START_REF accessor; an empty `$SESSION_RANGE` is a skip, not zero changes — the validator still requires a number there, so name the accessor's reason in the record's `notes` beside it). The single definition of this shape is `isCoordinatorDirectHousekeeping(record)` in `scripts/lib/session-schema/filters.mjs` (every wave `role: "Housekeeping"` AND `coordinator_direct: true`). Consumers key on it (eval gate-health, evolve effective-sizing), so write `role` and `coordinator_direct` exactly as shown. `session_type` alone never marks it.
 3. Read `.orchestrator/metrics/events.jsonl` **once** and build both event aggregates in a single pass. If the file does not exist, treat both aggregates as zero events (omit both fields per the rules below) — do NOT fail the session close.
 
    Filter all lines where `session == <session_id>`, then partition by `event` value:

package/skills/session-end/phase-3-2-docs-verification.md

@@ -31,11 +31,12 @@ process.stdout.write(JSON.stringify(tasks));
 ⚠ Phase 3.2: docs-tasks parse error — <reason>. Manual docs verification required.
 ```
 
-## Step 2 — Read SESSION_START_REF
+## Step 2 — Resolve SESSION_RANGE
 
-Read `session-start-ref` from STATE.md frontmatter. Full accessor and fallback chain are documented in `plan-verification.md § SESSION_START_REF accessor`. Summary:
-- Primary: `session-start-ref` field in STATE.md frontmatter.
-- Fallback: `git diff --name-only origin/main...HEAD` (no specific base SHA).
+Run the accessor in `plan-verification.md § SESSION_START_REF accessor`; it exports `$SESSION_RANGE`, one complete diff range. Summary:
+- Primary: the pinned `session-start-ref` from STATE.md frontmatter → `<sha>..HEAD`.
+- Field absent: the baseline `resolveBaselineRange()` resolves → `<base>...HEAD` (never a hard-coded `origin/main`).
+- Nothing resolves: `$SESSION_RANGE` is empty and the accessor names `no-baseline-ref` or `unresolvable-ref` — log `⚠ Phase 3.2: no session range (<reason>). Docs verification skipped.` and skip Phase 3.2. Never treat the empty range as "no docs changed".
 
 If `git diff` itself fails (network issue, corrupt repo), log:
 ```
@@ -46,7 +47,7 @@ and skip Phase 3.2. This is an explicit error, not a silent skip.
 ## Step 3 — Compute changed files
 
 ```bash
-CHANGED_FILES=$(git diff --name-only "$SESSION_START_REF..HEAD")
+CHANGED_FILES=$(git diff --name-only "$SESSION_RANGE")
 ```
 
 Cache this list for the per-task loop below. If the command exits non-zero, surface the error per the guard above and skip Phase 3.2.
@@ -75,7 +76,7 @@ For each `task` in `docs-tasks`:
 
 3. **Matched → inspect diff:**
    ```bash
-   git diff "$SESSION_START_REF..HEAD" -- <matched-file>
+   git diff "$SESSION_RANGE" -- <matched-file>
    ```
    - **Substantive content change** (non-whitespace, non-comment-only lines added/removed): outcome `ok`.
    - **Whitespace-only or structural-only diff** (no prose or code content changed): outcome `gap`.

package/skills/session-end/plan-verification.md

@@ -9,19 +9,34 @@
 
 > Referenced by Phase 3.2 (Docs Verification) and Phase 1.1a (File-Level Grounding). Canonical definition lives here.
 
-Read `session-start-ref` from STATE.md frontmatter. If the field is missing (older session or persistence disabled), fall back to `git diff --name-only origin/main...HEAD` (compares current HEAD against origin/main rather than a pinned SHA). The fallback is less precise but functional. Always prefer the pinned SHA when available.
+Read `session-start-ref` from STATE.md frontmatter; it is the pinned session-start SHA and always wins. If the field is missing (older session or persistence disabled), RESOLVE the base with `resolveBaselineRange()` (`scripts/lib/vcs-repo-spec.mjs`, #1039 — preferred remote → `<R>/HEAD` → `<R>/{main,master}` → local `main`/`master`), the same chain `computeDrift()` uses. Never assume `origin/main`: in a repo whose remote is not named `origin` or whose default branch is not `main` that literal fails every diff below.
+
+The accessor exports two variables. Consumers that DIFF use `"$SESSION_RANGE"` as one complete range — never `"$SESSION_START_REF..HEAD"`, which turned the old fallback into a TWO-dot `origin/main..HEAD` (a diff that also counts everything `main` gained since the branch point). `$SESSION_START_REF` stays the log base (`git log "$SESSION_START_REF..HEAD"`).
 
 ```bash
-SESSION_START_REF=$(node --input-type=module -e "
+SESSION_SPEC=$(node --input-type=module -e "
 import {readFileSync} from 'node:fs';
 import {parseStateMd} from '${PLUGIN_ROOT}/scripts/lib/state-md.mjs';
-const fm = parseStateMd(readFileSync('<state-dir>/STATE.md', 'utf8')).frontmatter;
-process.stdout.write(fm['session-start-ref'] ?? '');
-" 2>/dev/null)
-# Fallback when field absent
-[ -z "$SESSION_START_REF" ] && SESSION_START_REF="origin/main"
+import {resolveBaselineRange, isQueryFailure} from '${PLUGIN_ROOT}/scripts/lib/vcs-repo-spec.mjs';
+let ref = '';
+try { ref = String(parseStateMd(readFileSync('<state-dir>/STATE.md', 'utf8')).frontmatter['session-start-ref'] ?? '').trim(); } catch {}
+if (/^[0-9a-f]{7,64}$/.test(ref)) process.stdout.write(ref + ' ' + ref + '..HEAD');
+else {
+  const r = resolveBaselineRange({ repoRoot: process.cwd() });
+  if (r.ok) process.stdout.write(r.base + ' ' + r.range);
+  else process.stderr.write('SESSION_RANGE skipped: ' + (isQueryFailure(r.reason) ? 'unresolvable-ref' : 'no-baseline-ref') + ' (' + r.reason + ')\n');
+}
+")
+SESSION_START_REF=${SESSION_SPEC%% *}   # log base: the pinned SHA, else the resolved base ref
+SESSION_RANGE=${SESSION_SPEC#* }        # diff range: <sha>..HEAD (pinned), else <base>...HEAD
 ```
 
+**Empty `$SESSION_RANGE` is an explicit skip, never "no changes".** The accessor names the reason on stderr, split by `isQueryFailure()`:
+- `no-baseline-ref` — the repo genuinely has no base to measure against (no remote, no `main`/`master`). A real, benign state: report "no session range" and skip each diff-based step below.
+- `unresolvable-ref` — git could not be asked (not a repo, git missing or failing). A degraded measurement: report it as such and skip; never read the empty file list as a clean session.
+
+On either skip `$SESSION_START_REF` is empty too, so skip every LOG-based step as well: `git log --oneline "$SESSION_START_REF..HEAD"` then becomes `git log ..HEAD`, which git reads as `HEAD..HEAD` — it prints nothing and exits 0, an empty log indistinguishable from "no commits this session". The pinned value is accepted only as a hex object name (`/^[0-9a-f]{7,64}$/`), so a STATE.md value such as `--output=x` is never handed to git as an option; anything else falls through to the resolved base.
+
 Read back the session plan that was agreed at the start. For EACH planned item:
 
 ### 1.1 Done Items
@@ -36,7 +51,7 @@ Read back the session plan that was agreed at the start. For EACH planned item:
 Compare the files the plan said would be touched against the files actually changed in the session. Catches both **scope creep** (files changed that were not in any agent's prompt scope) and **incomplete coverage** (files in the plan that were never edited).
 
 1. **Planned files** = union of all file paths from agent prompt scopes across all waves. Source: STATE.md Wave History, falling back to the original session plan's per-agent "Files:" specs. Glob patterns are expanded against the working tree at session-start time.
-2. **Actual files** = `git diff --name-only $SESSION_START_REF..HEAD`, where `$SESSION_START_REF` comes from the `session-start-ref` field in STATE.md frontmatter. If the field is missing (older session), fall back to `git diff --name-only origin/main...HEAD`.
+2. **Actual files** = `git diff --name-only "$SESSION_RANGE"` (accessor above: the pinned `session-start-ref`, else the resolved baseline range). Empty `$SESSION_RANGE` → skip 1.1a with the accessor's reason.
 3. **Compute discrepancies:**
    - **Touched** = files in both Planned and Actual
    - **Unplanned (scope creep)** = files in Actual but not in Planned
@@ -46,7 +61,7 @@ Compare the files the plan said would be touched against the files actually chan
    - Generated/lock files (`pnpm-lock.yaml`, `*.lock`, `dist/**`, `node_modules/**`) are excluded from both planned and actual sets
    - The `.claude/`, `.codex/`, and `.cursor/` state directories are excluded — they are session artifacts, not code
 
-   > **Scope-drift cross-reference:** the S2 warn-only drift tripwire (below) uses its own separately-maintained filter list — `DRIFT_EXCLUDE_PATTERNS` in `scripts/lib/scope-baseline.mjs` — and is NOT derived from the filters above. That list is the shared filter source for both sides of its ratio IN CODE: `writeBaseline()`'s denominator (`countPlannedFiles()`) and `computeDrift()`'s numerator both call the same internal `filterExcluded()` helper (#894 review finding F1 — previously only the numerator was code-filtered; the denominator relied on a coordinator prose instruction to pre-filter before calling `writeBaseline()`, which is why three earlier PRD revisions shipped a tripwire that read a wrong ratio).
+   > **Scope-drift cross-reference:** the S2 warn-only drift tripwire (below) uses its own separately-maintained filter list — `DRIFT_EXCLUDE_PATTERNS` in `scripts/lib/scope-baseline.mjs` — and is NOT derived from the filters above. That list is the shared filter source for both sides of its ratio IN CODE: `writeBaseline()`'s denominator (`countPlannedFiles()`) and `computeDrift()`'s numerator both call the same internal `filterExcluded()` helper — the numerator additionally drops UNTRACKED paths under `.orchestrator/` (`isUntrackedRuntimeWrite()`), a rule keyed on tracked status that only the live numerator has (#894 review finding F1 — previously only the numerator was code-filtered; the denominator relied on a coordinator prose instruction to pre-filter before calling `writeBaseline()`, which is why three earlier PRD revisions shipped a tripwire that read a wrong ratio).
 5. **Report** in the verification output. Also call `computeDrift({ repoRoot, threshold: 2.0 })` (`scripts/lib/scope-baseline.mjs`) and append its result — warn-only, informational, never blocks close:
    ```
    File-level grounding:
@@ -56,6 +71,7 @@ Compare the files the plan said would be touched against the files actually chan
    - Untouched (planned but not edited): N files [list first 5]
    - Scope drift: filesRatio X.X (Y actual / Z planned, threshold 2.0) — [breached | ok | skipped: <reason>]
    ```
+   Read `skipped: unresolvable-ref` as "a git query the numerator needs failed", not only "the ref is dead": besides a `session-start-ref` lost to a rebase or force-push it also covers a checkout git cannot read, the working-tree or untracked query failing, output over 64 MiB (ENOBUFS) and the 10 s per-query timeout. Run `git rev-parse --verify <session-start-ref>` before concluding the ref is gone. `skipped: no-baseline-ref` means the repo has no base to measure against (no remotes, no `main`/`master`). A `breached` result can also be an over-report: files already dirty at session start, or a same-checkout peer's files, count as drift (see `computeDrift()`'s JSDoc).
 6. **Append to session metrics** (`grounding` field in the Phase 1.7 JSONL entry):
    ```json
    "grounding": {

package/skills/session-end/references/phase-3-documentation-updates.md

@@ -26,6 +26,16 @@ rm -f <state-dir>/wave-scope.json
 
 This should have been cleaned up by wave-executor after the final wave, but crashed sessions or interrupted executions may leave it behind. A stale scope manifest from a previous session could incorrectly restrict the next session's enforcement hooks.
 
+Delete THIS session's dispatch ledger the same way (`hooks/pre-task-scope-disjoint.mjs`, one file per session since #1493 — `skills/wave-executor/references/wave-loop-scope-manifest.md` step 7). Never a file named after another session id: that is a peer's live state.
+
+```bash
+SID="${CLAUDE_CODE_SESSION_ID:-}"
+case "$SID" in
+  ''|*[!A-Za-z0-9._-]*) ;;  # no id on this harness, or not path-safe: leave the file (inert)
+  *) rm -f ".orchestrator/wave-dispatch-scopes.$SID.json" ".orchestrator/wave-dispatch-scopes.$SID.lock" ;;
+esac
+```
+
 ### 3.1 SSOT Files
 - Update `STATUS.md` / `STATE.md` if they exist (metrics, dates, status)
 - Update `CLAUDE.md` (or `AGENTS.md` on Codex CLI) if patterns or conventions changed during this session
@@ -35,7 +45,7 @@ This should have been cleaned up by wave-executor after the final wave, but cras
 
 > Skip this subsection if `docs-orchestrator.enabled` config is not `true` (default: `false`). Also skip entirely if `docs-orchestrator.mode` is `off`.
 
-Reads `docs-tasks` from STATE.md frontmatter (written by wave-executor Pre-Wave 1b), computes `CHANGED_FILES` via `git diff --name-only "$SESSION_START_REF..HEAD"`, and runs a per-task verification loop (outcome: `ok`/`partial`/`gap`). In `warn` mode logs results non-blocking; in `strict` mode blocks on any gap and presents an AskUserQuestion override prompt. Emits a `### Documentation Coverage (docs-orchestrator)` block for inclusion in the Phase 6 Final Report.
+Reads `docs-tasks` from STATE.md frontmatter (written by wave-executor Pre-Wave 1b), computes `CHANGED_FILES` via `git diff --name-only "$SESSION_RANGE"` (the `plan-verification.md` accessor; an empty range skips with its named reason), and runs a per-task verification loop (outcome: `ok`/`partial`/`gap`). In `warn` mode logs results non-blocking; in `strict` mode blocks on any gap and presents an AskUserQuestion override prompt. Emits a `### Documentation Coverage (docs-orchestrator)` block for inclusion in the Phase 6 Final Report.
 
 **See `phase-3-2-docs-verification.md` for full details.**
 

package/skills/session-end/session-metrics-write.md

@@ -31,7 +31,7 @@
 
 1a. **Token Rollup (#644, #1244 — mechanical since #1436)** — no coordinator action. `scripts/emit-session.mjs` (step 2) runs `rollupSessionTokens()` itself whenever the incoming record carries no `total_tokens`: it resolves the session's raw UUID from `.orchestrator/current-session.json` (adopted only when its `semantic_session_id` equals the record's `session_id` and no process-local session id contradicts it), joins the sibling `subagents.jsonl` on `parent_session_id`, and fills `total_tokens`, `total_token_input`, `total_token_output`, the three cache buckets, `total_cost_usd`, `subagents_with_tokens`, `matched_records`, `cost_records_priced`, `cost_records_total` and `_token_schema` for every key the record does not already carry — plus `raw_session_id`. No matching records, an unreadable ledger or a foreign marker omits the fields with a WARN on stderr, never a fabricated `0`. An explicit key on `$METRICS_ENTRY` still wins. The same UUID also backs `session_start_ref` when STATE.md has none (the `head_sha` of the session's own `orchestrator.session.started` event).
 
-   **Semantics:** `null` totals mean "no token data was captured for this session" — this is NOT the same as zero cost. Do NOT coerce null to 0 when displaying or summing across sessions. The same holds for `total_cost_usd`: it is omitted whenever `cost_records_priced < cost_records_total` (#1475) — at least one cost-relevant subagent record could not be priced (a model the price table does not know, a token-bearing turn naming no model, a transcript that yielded no tokens, e.g. one over the hook's size cap, or an agent with a start record whose stop found no transcript of its own, mostly `workflow-subagent`) — and also when `cost_records_total` is 0, because there was nothing to price. It is never "$0" for an unknown cost and never a partial sum over the v2 agents the ledger can see. Phantom stops (#939, no start record) are no agents and never count. The two counters are persisted beside it, so a missing cost says whether part of the session was unpriceable or nothing was priceable. Blind spots remain: an agent whose start record fell outside the hook's tail window looks like a phantom, an agent with neither start nor stop record is invisible, and a session spanning the 2026-09-09 schema boundary is priced over its v2 records only (its v1 records are neither priced nor counted as candidates — 4 distinct fleet sessions carry such a cost, 2026-10-01). A subagent whose turns span several models carries a per-model `models_usage` breakdown in `subagents.jsonl` (#1470) and is priced part by part. The emit-session warning names the reason via `match_status` (ledger absent, ledger with no readable records, or records present but none for the own raw UUID); none of these means zero cost.
+   **Semantics:** `null` totals mean "no token data was captured for this session" — this is NOT the same as zero cost. Do NOT coerce null to 0 when displaying or summing across sessions. The same holds for `total_cost_usd`: it is omitted whenever `cost_records_priced < cost_records_total` (#1475) — at least one cost-relevant subagent record could not be priced (a model the price table does not know, a token-bearing turn naming no model, a transcript that yielded no tokens, e.g. one over the hook's size cap, or an agent with a start record whose stop found no transcript of its own, mostly `workflow-subagent`, or an agent known only from `schema_version` 1 records — #1487 Pkt 1) — and also when `cost_records_total` is 0, because there was nothing to price. It is never "$0" for an unknown cost and never a partial sum over the v2 agents the ledger can see. Phantom stops (#939, no start record) are no agents and never count. The two counters are persisted beside it, so a missing cost says whether part of the session was unpriceable or nothing was priceable. Blind spots remain: an agent whose start record fell outside the hook's tail window looks like a phantom, an agent with neither start nor stop record is invisible. A session spanning the 2026-09-09 schema boundary therefore reports no cost (its v1 agents are unpriced candidates since 2026-10-02; before, it was priced over its v2 records only — 4 distinct fleet sessions carried such a partial sum). A subagent whose turns span several models carries a per-model `models_usage` breakdown in `subagents.jsonl` (#1470) and is priced part by part. The emit-session warning names the reason via `match_status` (ledger absent, ledger with no readable records, or records present but none for the own raw UUID); none of these means zero cost.
 
    **Provenance (#949):** the rollup sums ONLY records carrying `subagent_transcript_found: true` — the flag the producer sets when it read the subagent's own transcript. Pre-#949 records carry the PARENT transcript's running totals and are excluded, so a session made up entirely of them now reports `null` rather than a fabricated sum (73 historical sessions, 96,148,781 phantom tokens, measured 2026-08-11). Two consequences for readers: totals already written into `sessions.jsonl` before 2026-08-11 were produced by the unfiltered recipe and are a series break, not a trend; and `matched_records` counts start records and phantom stops alike, so it is NOT the denominator for a coverage ratio — use `subagents_with_tokens` against the session's real agent count.
 
@@ -98,7 +98,20 @@
        VM_DIR="$VAULT_DIR"
        VM_DIR_SOURCE="env VAULT_DIR"
      fi
-     echo "vault-dir=$VM_DIR (Quelle: $VM_DIR_SOURCE)"
+     # SO#1490: display form for echo lines only — the home dir becomes `~`
+     # through the ONE redactor (`redactHomeDir`, scripts/lib/common.mjs,
+     # path-boundary aware: `/Users/bob` never rewrites `/Users/bobby`). The
+     # commands below still get the real value. VM_DIR has no producer to emit
+     # a display path, so one helper serves every echo; if node cannot load the
+     # module it falls back to `…/<basename>` (vault-mirror's #1479 form),
+     # never to the raw path. The `--` is load-bearing: without it a value that
+     # starts with `-` (vault-dir comes from the committed CLAUDE.md / AGENTS.md) is parsed as
+     # a node option, and `--import=data:…` would execute code at /close.
+     so_tilde() {
+       node --input-type=module -e "import { redactHomeDir } from '$PLUGIN_ROOT/scripts/lib/common.mjs'; process.stdout.write(redactHomeDir(process.argv[1]))" -- "$1" 2>/dev/null \
+         || printf '…/%s' "${1##*/}"
+     }
+     echo "vault-dir=$(so_tilde "$VM_DIR") (Quelle: $VM_DIR_SOURCE)"
 
      # Quality-gate thresholds (PRD F1.2). Defaults match
      # scripts/vault-mirror.mjs (400 chars / 0.5 confidence). The nested key
@@ -108,9 +121,14 @@
      VM_QUALITY_CONFIDENCE=$(echo "$CONFIG" | jq -r '."vault-mirror".quality."min-confidence" // 0.5')
      VM_VAULT_NAME=$(echo "$CONFIG" | jq -r '."vault-integration"."vault-name" // empty')
 
+     # #1503: name the repo being mirrored and pass the ledger ABSOLUTE. The
+     # namespace is that repo's identity, never the cwd's; a --source that lies in
+     # a different repo than --repo-root is refused (exit 2, source-repo-mismatch)
+     # instead of being written over another project's notes.
      VM_OUTPUT=$(node "$PLUGIN_ROOT/scripts/vault-mirror.mjs" \
        --vault-dir "$VM_DIR" \
-       --source .orchestrator/metrics/sessions.jsonl \
+       --repo-root "$PWD" \
+       --source "$PWD/.orchestrator/metrics/sessions.jsonl" \
        --kind session \
        --session-id "$SESSION_ID" \
        ${VM_VAULT_NAME:+--vault-name "$VM_VAULT_NAME"} \
@@ -118,9 +136,11 @@
        --quality-min-confidence "$VM_QUALITY_CONFIDENCE" 2>&1)
      VM_EXIT=$?
 
-     # Surface script output so user can see skipped-handwritten results
+     # Surface script output so user can see skipped-handwritten results.
+     # `printf '%s\n'`, not `echo`: zsh's echo expands the `\n` escapes inside
+     # JSON strings and would split an action line in two.
      if [[ -n "$VM_OUTPUT" ]]; then
-       echo "$VM_OUTPUT"
+       printf '%s\n' "$VM_OUTPUT"
      fi
 
      if [[ $VM_EXIT -ne 0 ]]; then
@@ -133,18 +153,31 @@
          echo "WARNING: vault-mirror exited $VM_EXIT — session metrics were NOT mirrored to the vault. Set vault-integration.mode: strict to block on this error."
        fi
      else
-       # Parse the destination path from the script's JSON output (one JSON line per action)
-       VM_DEST=$(echo "$VM_OUTPUT" | jq -r 'select(.action == "created" or .action == "updated") | .path' 2>/dev/null | head -1)
+       # Parse the action lines. stdout carries one JSON object per entry, but
+       # this capture also holds stderr (`2>&1`): `SKIP …` / `WARN …` lines,
+       # routine since #1503. A plain `jq` stops at the first non-JSON line
+       # (exit 5) and silently loses every action after it, so read raw lines
+       # and keep only the ones that parse as JSON objects.
+       vm_actions() { printf '%s\n' "$VM_OUTPUT" | jq -R -r "fromjson? | objects | $1" 2>/dev/null; }
+
+       VM_DEST=$(vm_actions 'select(.action == "created" or .action == "updated") | .path' | head -1)
        if [[ -n "$VM_DEST" ]]; then
          echo "Mirrored session summary to $VM_DEST"
        fi
 
        # Quality gate summary (PRD F1.2): count entries skipped because they
        # failed the quality filter, so the operator can tune thresholds.
-       VM_QUALITY_SKIP=$(echo "$VM_OUTPUT" | jq -rc 'select(.action == "skipped-quality-low")' 2>/dev/null | wc -l | tr -d ' ')
+       VM_QUALITY_SKIP=$(vm_actions 'select(.action == "skipped-quality-low") | .action' | wc -l | tr -d ' ')
        if [[ "${VM_QUALITY_SKIP:-0}" -gt 0 ]]; then
          echo "vault-mirror: ${VM_QUALITY_SKIP} entry/entries skipped by quality gate (set vault-mirror.quality.min-narrative-chars / min-confidence to tune)"
        fi
+
+       # #1503: session notes left untouched because they were rendered from a
+       # record that is not in this ledger (another repo's, or an id collision).
+       VM_FOREIGN_SKIP=$(vm_actions 'select(.action == "skipped-foreign-owner") | .action' | wc -l | tr -d ' ')
+       if [[ "${VM_FOREIGN_SKIP:-0}" -gt 0 ]]; then
+         echo "vault-mirror: ${VM_FOREIGN_SKIP} note(s) left untouched — owned by a session record outside this ledger (skipped-foreign-owner; see the SKIP lines above)"
+       fi
      fi
 
      # ── Durable Narrative Mirror (#675) ────────────────────────────────────
@@ -175,7 +208,7 @@
 
      if [[ $NM_EXIT -ne 0 ]]; then
        if [[ "$VM_MODE" == "strict" ]]; then
-         echo "ERROR: narrative-mirror failed (exit $NM_EXIT) — session close blocked (vault-integration.mode=strict): $NM_OUTPUT"
+         echo "ERROR: narrative-mirror failed (exit $NM_EXIT) — session close blocked (vault-integration.mode=strict): $(so_tilde "$NM_OUTPUT")"
          echo "Fix the narrative mirror issue or set vault-integration.mode: warn to downgrade to a warning."
          exit 1
        else
@@ -185,7 +218,9 @@
      else
        # Surface the JSON result so the operator can see skipped-* / written outcomes.
        NM_ACTION=$(echo "$NM_OUTPUT" | jq -r '.action // empty' 2>/dev/null)
+       # `.path` is absolute (under the vault, i.e. the home dir) — display form only.
        NM_PATH=$(echo "$NM_OUTPUT" | jq -r '.path // empty' 2>/dev/null)
+       [[ -n "$NM_PATH" ]] && NM_PATH=$(so_tilde "$NM_PATH")
        if [[ "$NM_ACTION" == "written" && -n "$NM_PATH" ]]; then
          echo "Mirrored durable session narrative to $NM_PATH"
        elif [[ -n "$NM_ACTION" ]]; then
@@ -209,4 +244,4 @@
 
    > **Host-local overrides.** `enabled`/`mode` above are the values AFTER the host switch: env `SO_VAULT_INTEGRATION=off|warn|strict` > owner.yaml `vault-integration: { enabled: false | mode: … }` > committed. The host may only lower the committed level, never raise it; `."vault-integration"."host-override"` names the tier that lowered it (`env:SO_VAULT_INTEGRATION`, `owner.yaml`) and is `null` otherwise. `."vault-integration"."vault-dir-source"` (`env`, `match`, `owner`, `committed`) says where the vault path came from. See `docs/session-config-reference.md` § Vault Integration.
 
-   > **Hand-written note protection:** `vault-mirror.mjs` checks for a `_generator: session-orchestrator-vault-mirror@1` marker before overwriting any existing file. When it skips an existing hand-written note it emits a JSON line `{"action":"skipped-handwritten","path":"<path>","kind":"<kind>","id":"<id>"}` — the step above surfaces this output so the user can see the result. Action names: `created`, `updated`, `skipped-noop`, `skipped-handwritten`, `skipped-collision-resolved`, `skipped-invalid` (entry failed required-field validation, or the mapper crashed rendering an otherwise-parseable record — the latter case carries `reason: "mapper-crash"`, #718), `skipped-quality-low` (entry failed quality gate — PRD F1.2; line carries a `reason` field).
+   > **Hand-written note protection:** `vault-mirror.mjs` checks for a `_generator: session-orchestrator-vault-mirror@1` marker before overwriting any existing file. When it skips an existing hand-written note it emits a JSON line `{"action":"skipped-handwritten","path":"<path>","kind":"<kind>","id":"<id>"}` — the step above surfaces this output so the user can see the result. Action names: `created`, `updated`, `skipped-noop`, `skipped-handwritten`, `skipped-collision-resolved`, `skipped-foreign-owner` (sessions: the note at the target path was rendered from a record outside this ledger — `source-record` mismatch — or names a different session id; file left untouched, line carries a `reason`, counted by the step above, #1503), `skipped-invalid` (entry failed required-field validation, or the mapper crashed rendering an otherwise-parseable record — the latter case carries `reason: "mapper-crash"`, #718), `skipped-quality-low` (entry failed quality gate — PRD F1.2; line carries a `reason` field).

package/skills/session-start/SKILL.md

@@ -222,7 +222,7 @@ Group issues by:
 
 ## Phase 4: SSOT & Environment Check
 
-> Always runs; every finding is a NON-BLOCKING banner in the Session Overview (never a gate — the Full Gate is the Quality wave's job). Covers SSOT freshness, the Baseline quality commands (resolved `.orchestrator/policy/quality-gates.json` → Session Config → defaults, each availability-checked with `command -v`), Pencil design status, plugin freshness, and the banner-probe family registered in `scripts/lib/session-start-probes.mjs` (bootstrap-lock-freshness, vault-staleness, telemetry-flush-health, ci-status, qg-command-drift, peer-cards, loop-readiness, instruction-budget, maintenance-due, sessions-staleness, sessions-integrity, owner-config, moc-staleness, context-coverage, claude-md-budget-lint, tests:src-ratio, project-hygiene, mirror-issues, git-config-drift — 19 total). Per-probe module path, return contract and exact banner wording: [`references/phase-4-ssot-environment-check.md`](references/phase-4-ssot-environment-check.md).
+> Always runs; every finding is a NON-BLOCKING banner in the Session Overview (never a gate — the Full Gate is the Quality wave's job). Covers SSOT freshness, the Baseline quality commands (resolved `.orchestrator/policy/quality-gates.json` → Session Config → defaults, each availability-checked with `command -v`), Pencil design status, plugin freshness, and the banner-probe family registered in `scripts/lib/session-start-probes.mjs` (bootstrap-lock-freshness, vault-staleness, telemetry-flush-health, ci-status, qg-command-drift, peer-cards, loop-readiness, instruction-budget, maintenance-due, sessions-staleness, sessions-integrity, owner-config, moc-staleness, context-coverage, claude-md-budget-lint, tests:src-ratio, project-hygiene, mirror-issues, git-config-drift, events-retention — 20 total). Per-probe module path, return contract and exact banner wording: [`references/phase-4-ssot-environment-check.md`](references/phase-4-ssot-environment-check.md).
 
 ## Phase 4.5: Resource Health (v3.1.0)
 
@@ -354,7 +354,7 @@ Invokes `buildLiveSignals` (single SSOT for the signals shape) then `selectMode(
 
 > Skip silently when `persistence: false` (no ledger for the event). Runs BEFORE the first writing action; everything not stated here is in `skills/_shared/fleet-protocol.md`.
 
-Build the check-in JSON (fields per the reference; `session` from `.orchestrator/current-session.json`, `modus` = session type, `kandidaten` = the issue numbers you intend to claim) and pipe it into `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-checkin.mjs"` — it validates, stores `checkin/<session_id>.json` (0600) under `~/.config/navigator/` and emits `orchestrator.fleet.checkin`. Its stdout carries `navigator_state`: on `active`, and only when a peer named `navigator-*` is reachable via `ListAgents`, send ONE hint naming the file path — never expect or wait for a reply (CSM-004). Then read `auflagen/<session_id>.json`; if it is still absent 10 min after `checkin.zeit`, the reference's Standard-Auflagen apply. Reading work and edits in the own worktree continue meanwhile.
+Build the check-in JSON (fields per the reference; `session` from `.orchestrator/current-session.json`, `modus` = session type, `kandidaten` = the issue numbers you intend to claim) and pipe it into `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-checkin.mjs"` — it validates, stores `checkin/<session_id>.json` (0600) under `~/.config/navigator/` and emits `orchestrator.fleet.checkin`. Its stdout carries `navigator_state` and `navigator_adresse` (the lease's validated `adresse`, else `null`): on `active`, and only when `navigator_adresse` is non-null and reachable via `ListAgents`, send ONE hint to exactly that name, naming the file path — never expect or wait for a reply (CSM-004). Then read `auflagen/<session_id>.json`; if it is still absent at the stdout's `fallback_due_at`, the reference's Standard-Auflagen apply (the CLI computes that deadline: `zeit` plus `CHECKIN_FALLBACK_MIN` while a navigator is active, `zeit` itself — immediately — otherwise). Reading work and edits in the own worktree continue meanwhile.
 
 ## Phase 8: Structured Presentation & Q&A
 
@@ -418,7 +418,7 @@ After user alignment:
 | `phase-2-5-docs-planning.md` | Phase 2.5 full procedural body — docs-orchestrator config, audience detection, AUQ confirmation, result block emission, non-overlap rules |
 | (inline) Phase 2.6 | Steering docs gate + load — reads `.orchestrator/steering/{product,tech,structure}.md`; silent no-op when directory absent |
 | `references/phase-2-7-portfolio-snapshot.md` | Phase 2.7 full procedural body — GitLab Portfolio Snapshot: dry-run aggregation banner; gated on `gitlab-portfolio.enabled: true` + `vault-integration.enabled: true`; dispatches `scripts/lib/gitlab-portfolio/cli.mjs --dry-run`; 8s timeout; never blocks session-start |
-| `references/phase-4-ssot-environment-check.md` | Phase 4 full procedural body — SSOT freshness, Baseline quality-command resolution + `command -v` availability check, Pencil status, plugin/`bootstrap.lock` freshness, and the 19-probe banner family (module path, return contract and exact wording per probe) |
+| `references/phase-4-ssot-environment-check.md` | Phase 4 full procedural body — SSOT freshness, Baseline quality-command resolution + `command -v` availability check, Pencil status, plugin/`bootstrap.lock` freshness, and the 20-probe banner family (module path, return contract and exact wording per probe) |
 | `phase-4-5-resource-health.md` | Phase 4.5 full procedural body — resource probe, adaptive thresholds table, AUQ presentation, session-plan cap handoff |
 | `references/phase-6-5-forced-reads.md` | Phases 6.5.1 + 6.5.2 full procedural bodies — the two forced-read STATE.md continuity slots: `## What Not To Retry` (`readWhatNotToRetry`, #623) and `## Open Questions` (`readOpenQuestions`, #772), both rendered unconditionally and wrapped via `wrapHistorical` from `scripts/lib/historical-guard.mjs` |
 | `references/phase-6-6-project-intelligence.md` | Phase 6.6 full procedural body — active-learnings surface from `.orchestrator/metrics/learnings.jsonl`, cap+rank via `learnings-surface-top-n`, grouping by type, and the Surface health block |