session-orchestrator 5.11.0 → 5.13.0

package/docs/session-config-reference.md

@@ -32,6 +32,8 @@ Validation runs automatically via `scripts/parse-config.mjs` → `scripts/valida
 
 Bypass via `SO_SKIP_CONFIG_VALIDATION=1`. Missing fields can be patched into an existing config file via `/bootstrap --retroactive`.
 
+**Unknown keys (#1562).** `parse-config.mjs` compares every top-level key of the local `## Session Config` block with the keys of the plugin's own `docs/session-config-template.md` (the starter block plus the opt-in baseline, read by `knownTemplateKeys()` in `scripts/lib/config/template-keys.mjs`) and with every top-level key `parseSessionConfig()` emits, so `skill-evolution` and `dispatcher-autonomy` (parsed from the whole file) count as known inside the block too. It reads the block the way the runtime parser does (`collectTopLevelKeyLines()` in `scripts/lib/config/section-extractor.mjs`): keys inside an HTML comment are ignored, nested-block headers count as top-level keys, indented children do not. Each unknown key produces one stderr line, `⚠ <file>:<line>: unknown Session Config key '<key>' — …`, under `enforcement: warn` and `strict`; it never refuses the run, because a key from a newer plugin version is not a defect of the repo. `enforcement: off` silences it. If the template cannot be read, one line says the check did not run, so "not measured" never reads as "no unknown keys". stdout JSON is unchanged.
+
 ## Parser Gotcha: No-Inline-Comment Block Headers
 
 **General contract, applies to every nested (block-shaped) Session Config key, not just the handful annotated below.** A top-level block key like `eval:`, `custom-phases:`, `moc-staleness:`, `context-coverage:`, or `worktree-orphans:` is opened by the shared bold-tolerant matcher `matchBlockHeader(line, key)` (`scripts/lib/config/block-header.mjs`) rather than by a per-key regex. As of the #830 generalisation, **38 files** under `scripts/lib/config/` import it — 37 block-shaped parsers (`auto-dream`, `broken-window`, `cold-start`, `config-protection`, `context-coverage`, `cross-repo`, `custom-phases`, `dialectic`, `discovery-validator`, `dispatcher-autonomy`, `dispatcher-autonomy-capture`, `docs-orchestrator`, `docs-staleness`, `drift-check`, `eval`, `events-rotation`, `evolve`, `frontend-slop-hook`, `gitlab-portfolio`, `handover-gate`, `loop-guard`, `memory`, `moc-staleness`, `persona-gate-wave`, `reconcile`, `skill-evolution`, `slopcheck`, `state-md-lock`, `templates-first`, `test`, `vault-integration`, `vault-mirror-quality`, `vault-staleness`, `vault-sync`, `verification-auto-fix`, `wave-reviewers`, `worktree-orphans`) plus `block-header.mjs` itself — confirmed via `grep -rln "matchBlockHeader" scripts/lib/config/ | wc -l` → `38`.
@@ -114,7 +116,7 @@ Raw caps are the `agents-per-wave` value BEFORE the session-type override resolv
 | Read/write API | `readSessionProfile` / `setSessionProfile` / `SESSION_PROFILE_FIELD` in `scripts/lib/state-md.mjs` |
 | Absent means | No profile. Never an empty string, never `none` — `readSessionProfile` returns `null` |
 | Session record | Optional `session_profile` field (`scripts/lib/session-schema/constants.mjs` `OPTIONAL_FIELDS`); records without it validate unchanged |
-| Defined values | `ultradeep` (7 waves, coordinator-direct Synthesis-Gate at wave 2) — spec: `docs/prd/2026-09-06-ultradeep-session-profile.md` |
+| Defined values | `ultradeep` (7 waves, coordinator-direct Synthesis-Gate at wave 2) — spec: the internal ultradeep session-profile PRD (2026-09-06, not in the public mirror) |
 
 `session-type` NEVER becomes `ultradeep`: that value is a closed set in `scripts/lib/session-schema/constants.mjs`, `scripts/lib/wave-sizing.mjs` and `scripts/lib/session-close-backfill.mjs`, and an unknown member degrades SILENTLY there (telemetry maps it to `"other"`, the close-backfill labels it `housekeeping`). The profile field exists so no closed set has to change.
 
@@ -163,8 +165,10 @@ agent-mapping: { impl: cursor:composer-2.5, test: cursor:cursor-grok-4.6-high, s
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `vcs` | string | auto-detect | Version control platform: `github` or `gitlab`. Auto-detected from git remote URL if not set. |
+| `project-name` | string | none | Informational. `/bootstrap` writes it (`skills/bootstrap/fast-template.md`, `templates/_minimal/CLAUDE.md.tmpl`) to name the repo for human and agent readers; no runtime code reads it. Documented so the unknown-key report (#1562) does not flag it. |
+| `vault` | object | none | Product-vault registration (`path`, `product-domain`, `persona-db`) that `/bootstrap` appends for repos with product data (`skills/bootstrap/_shared-template.md`). Its presence is the marker `hasVaultConfig()` (`scripts/lib/product-repo-detect.mjs`) reads so bootstrap does not ask again; `parseSessionConfig()` does not emit it. Distinct from `vault-integration`. |
 | `gitlab-host` | string | from remote | Custom GitLab hostname. Only needed if the host cannot be inferred from the git remote URL. |
-| `mirror` | string | absent (`null`) | GitHub mirror push at session-end Phase 4.4 (`skills/session-end/SKILL.md` § 4.4, read via `parse-config.mjs`). `github` or **absent** → push `HEAD` to the `github` remote when one exists (absent keeps the pre-#1034 remote-based behaviour, so keyless repos keep mirroring). `none` → never push, even with a `github` remote; unlike other string keys an explicit `none` parses to the string `'none'`, not `null`. Any other value → WARN, nothing pushed, exit 1. Only `none` switches the push off: `mirror: null` parses as an absent key and therefore pushes when a `github` remote exists. Without a `github` remote the key is not read at all — the block skips with exit 0 before it. Not a per-commit hook: the push happens once per `/close`. |
+| `mirror` | string | absent (`null`) | GitHub mirror push at session-end Phase 4.4 (`skills/session-end/SKILL.md` § 4.4, read via `parse-config.mjs`). `github` or **absent** → push `HEAD` to the `github` remote when one exists (absent keeps the pre-#1034 remote-based behaviour, so keyless repos keep mirroring). `none` → never push, even with a `github` remote; unlike other string keys an explicit `none` parses to the string `'none'`, not `null`. `curated` (#1631, #1594) → never push `HEAD`. Only when `HEAD` is on branch `main` AND equals `git ls-remote origin refs/heads/main` (any other state skips with exit 0, nothing pushed — GitHub main deploys production), `node scripts/github-export.mjs --source <that sha>` builds ONE squash commit on `refs/heads/github-export`: source tree minus the paths in `.orchestrator/policy/public-export.json`, parent ALWAYS the public GitHub main (`refs/remotes/github/main`, required to equal `git ls-remote github refs/heads/main`), trailer `Source-Commit: <sha>`, strict leakage scan plus excluded-path citation guard on the snapshot. Export exit 3 = nothing to publish (no push); exit 1 (refused) → WARN, nothing pushed, exit 1. The push is bound to the scanned sha (read from the export's stdout only): the push URL of `github` must equal its fetch URL, then `github-export.mjs --verify <sha> --source <origin main>` re-checks it right before the push (one commit on the `ls-remote`-verified github main, trailer == origin's main, no excluded path in its tree), and a plain fast-forward `git push github <sha>:refs/heads/main` sends exactly that sha. Details: `docs/github-mirror-protection.md` § Curated public mirror. The private history is never reachable from the public ref. Any other value → WARN, nothing pushed, exit 1 (plugin copies that predate `curated` treat it the same way). Only `none` switches the push off: `mirror: null` parses as an absent key and therefore pushes when a `github` remote exists. Without a `github` remote the key is not read at all — the block skips with exit 0 before it. Not a per-commit hook: the push happens once per `/close`. |
 | `cross-repos` | list | none | Related repositories under `~/Projects/`. The orchestrator checks their git state and critical issues during session start. |
 | `cross-repo.projects` | list | `[]` | Repos to process when running cross-repo maintenance scripts (`run-migrate-v2-cross-repo.mjs`, `vault-integration-watcher.mjs`, `promote-vault-strict.mjs`). Each entry is a path (absolute, `~`-prefixed, or bare name resolved under `~/Projects/`). When this list is empty or absent, those scripts emit a one-line notice and exit 0 — they never error on an empty list. Example: `[~/Projects/my-app, ~/Projects/another-app]`. |
 | `pencil` | string | none | Path to a `.pen` design file (relative to project root). Enables design-code alignment reviews after Impl-Core and Impl-Polish waves. |
@@ -207,7 +211,7 @@ cross-repo:
   projects: [~/Projects/my-app, ~/Projects/another-app]   # INLINE list only
 ```
 
-Parsed by `_parseCrossRepo()` (`scripts/lib/config/cross-repo.mjs:50-84`). Only the inline form on the `projects:` line is read — a block list of `- ` items under `projects:` yields `[]` without a warning (measured 2026-09-18). An entry containing anything outside `[A-Za-z0-9._~/-]` (a shell metacharacter, a space) is dropped with one stderr line `cross-repo: rejected project entry with shell metacharacter: …`. Absent, empty, `none` or `null` → `[]`. Readers additionally drop entries resolving outside `~/Projects/` (confinement root, `getConfinementRoot()`). Read by `scripts/run-migrate-v2-cross-repo.mjs`, `scripts/vault-integration-watcher.mjs`, `scripts/promote-vault-strict.mjs`, and — as a secondary repo source after the filesystem scan — `scripts/lib/dispatcher/enumerate.mjs:303`.
+Parsed by `_parseCrossRepo()` (`scripts/lib/config/cross-repo.mjs:98-132`). Only the inline form on the `projects:` line is read — a block list of `- ` items under `projects:` yields `[]` without a warning (measured 2026-09-18). An entry containing anything outside `[A-Za-z0-9._~/-]` (a shell metacharacter, a space) is dropped with one stderr line `cross-repo: rejected project entry with shell metacharacter: …`. Absent, empty, `none` or `null` → `[]`. Readers additionally drop entries resolving outside the confinement root (`getConfinementRoot()`), which is also the root the host-wide sweeps scan. It resolves host-locally (#1562), highest first: env `CROSS_REPO_CONFINEMENT_ROOT` (test-only) > env `SO_PROJECTS_ROOT` > `owner.yaml` `paths.projects-root` > `~/Projects`. A leading `~` is expanded on the two host-local tiers; a value that is still not absolute is ignored with one stderr WARN naming its source, and the next tier is tried. It is deliberately not a Session Config key: a personal absolute path does not belong in a committed CLAUDE.md (#653). Read by `scripts/run-migrate-v2-cross-repo.mjs`, `scripts/vault-integration-watcher.mjs`, `scripts/promote-vault-strict.mjs`, and — as a secondary repo source after the filesystem scan — `scripts/lib/dispatcher/enumerate.mjs:303`.
 
 ## Auto-Skill Dispatch (#337)
 
@@ -304,11 +308,11 @@ issue-budget:
 | `issue-budget.mode` | string | `strict` | `strict` blocks over-cap creations (exit 2 from the hook) and parks them as overflow; `warn` allows them with a stderr notice; `off` disables the gate entirely (no counter is written). |
 | `issue-budget.overflow` | string | `collect-issue` | Where session-end drains parked creations. `collect-issue` files exactly ONE `[Backlog-Sammel] <session-id>, N zurückgestellte Punkte` issue (`type::backlog`, `priority::low`) whose body is a checklist of the parked items; `vault-note` writes a single Markdown file under `vault/00-inbox/` instead. |
 
-**Override resolution (#1163-adjacent, load-bearing split).** `_parseIssueBudget()` (`scripts/lib/config/issue-budget.mjs`) returns TWO keys: `"max-per-session"` (always a plain number — the resolved `.default`, so the three existing consumers that treat it as a number never see `[object Object]`) and `"max-per-session-raw"` (the full parsed value, number or override object). `loadIssueBudgetConfig()` (`scripts/lib/issue-budget.mjs`) resolves the effective cap for the CURRENT session by reading `session-type:` off the active STATE.md frontmatter (`readSessionTypeFromStateMd()`, never throws — a missing/unparseable STATE.md yields `null`, read as "use the default") and calling `resolveMaxPerSession(cfg, sessionType)`, whose precedence is `raw[sessionType] ?? raw.default ?? cfg['max-per-session']`. The resolved session type is also returned as `"session-type-resolved"` (`null` when STATE.md carries none) so a caller can tell the resolution actually happened rather than fallen through.
+**Override resolution (#1163-adjacent, load-bearing split).** `_parseIssueBudget()` (`scripts/lib/config/issue-budget.mjs`) returns TWO keys: `"max-per-session"` (always a plain number — the resolved `.default`, so the three existing consumers that treat it as a number never see `[object Object]`) and `"max-per-session-raw"` (the full parsed value, number or override object). `loadIssueBudgetConfig()` (`scripts/lib/issue-budget.mjs`) resolves the effective cap for the CURRENT session by reading `session-type:` off the active STATE.md frontmatter (`readSessionTypeFromStateMd()`, never throws — a missing/unparseable STATE.md yields `null`, read as "use the default"; since #1636 a STATE.md that `resolveStateMdWriteTarget()` rejects as foreign counts as missing, so a peer's `session-type` never sets this session's cap) and calling `resolveMaxPerSession(cfg, sessionType)`, whose precedence is `raw[sessionType] ?? raw.default ?? cfg['max-per-session']`. The resolved session type is also returned as `"session-type-resolved"` (`null` when STATE.md carries none) so a caller can tell the resolution actually happened rather than fallen through.
 
 **Exemptions (load-bearing).** `priority::critical`, the carryover class (`[Carryover]`, `[SPIRAL]`/`[FAILED]`, `type::carryover`, a bare `carryover` label) and `broken-window` closure issues bypass the cap unconditionally. Without those exemptions the cap would break the standing session-end promises in `skills/session-end/SKILL.md` (Phase 1.8 "non-deselectable" SPIRAL/FAILED carryover, and the Critical Rule "ALWAYS create issues for unfinished PLANNED work"). Exempt creations are counted in the state file's `exempt` field for observability but never blocked.
 
-**Counter file:** `.orchestrator/runtime/issue-budget/<sha256(sessionId)[0..16]>.json` — `{ sessionId, count, exempt, overflow: [...] }`, ONE file per session (#1141: the former single `issue-budget.json` slot was reset by whichever session wrote last, so two sessions in one working copy silently disabled each other's cap). Identity-less callers still use the legacy flat path; `budgetStatePath(repoRoot, sessionId)` in `scripts/lib/issue-budget.mjs` is the resolver.
+**Counter file:** `.orchestrator/runtime/issue-budget/<sha256(sessionId)[0..16]>.json` — `{ sessionId, count, exempt, overflow: [...] }`, ONE file per session (#1141: the former single `issue-budget.json` slot was reset by whichever session wrote last, so two sessions in one working copy silently disabled each other's cap). Identity-less callers still use the legacy flat path; `budgetStatePath(repoRoot, sessionId)` in `scripts/lib/issue-budget.mjs` is the resolver. It roots both paths at `resolveEventsLedgerRoot(repoRoot)` (#1729): a linked worktree maps to its main checkout, every other root stays as it is. The hook (launch directory, usually the main checkout) and session-end (the worktree) therefore open the same file, and `reapStaleBudgetFiles` sweeps where the files are.
 
 **Close-time reconcile (#1163).** The cap is enforced by a PreToolUse hook, which only sees the shell routes it pattern-matches — every unmatched creation route (a GUI-created issue, an unmatched CLI form) is a silent zero: no ledger line, no error, indistinguishable from "created nothing". `scripts/lib/issue-budget-reconcile.mjs` closes that gap at session-end by comparing two independently-produced numbers: `recorded` (`record.issues_created.length` from the session record) against `charged + exempt` (summed over BOTH the semantic-id and raw-id ledger keys — which key a given session's counter file used depends on a condition, `resolveIssueBudgetSessionId`, that can change mid-session). It emits `orchestrator.issue_budget.reconciled` with a `verdict`: `match` (recorded ≤ charged + exempt), `escaped` (`recorded > charged + exempt` — some creations bypassed the hook), `no-ledger` (`recorded > 0` and no counter file existed under either key — the hook never ran once), or `stale-record` (a ledger exists but the record shows 0 recorded with a positive charge). Fail-open by contract: nothing in this module throws, and a close-time cross-check that could abort the close would be strictly worse than one that reports `no-ledger`.
 
@@ -357,9 +361,9 @@ slopcheck:
 | `auto-commit-per-wave` | boolean | `false` | **Planned, currently a no-op (#1219).** Intended to commit each wave's work after the Quality-Lite gate passes, as checkpoints against data loss from `git stash` collisions in parallel sessions; when `false`, all work is committed at session-end via `/close`. Today no code reads the flag for a commit: the procedural sequence (`scripts/lib/auto-commit.mjs`) does not exist, and the only consumer is the contract prose in `skills/wave-executor/references/wave-loop-review.md`. Setting it to `true` changes nothing — no commit per wave, and no session-start warning is emitted by any script or hook (measured 2026-10-05: `rg "not yet active" skills scripts hooks` hits only that prose file). The key is declared in `docs/session-config-template.md` and allowlisted in `check-unwired-features.mjs`; `parse-config` drops it. <!-- path-check: planned #1219 --> |
 
 **Guard coverage (moved from CLAUDE.md Critical Gotchas, 2026-09-25).** **Destructive-Command Guard is active in main + subagent waves on harnesses with a compatible command hook.** On Claude Code, and through the supported Cursor and Pi bridges, `hooks/pre-bash-destructive-guard.mjs` applies `.orchestrator/policy/blocked-commands.json`:
-**12 of its 16 rules are `severity: block`, the other 4 only warn** (measured 2026-09-19: `jq '[.rules[].severity]|group_by(.)|map({(.[0]):length})|add' .orchestrator/policy/blocked-commands.json`).
-The 16th is `ledger-delete-protected` (#1401): `rm`/`mv`/`unlink` on `.orchestrator/metrics/**` — added after a wave agent deleted a rotated 53.896-line ledger archive that no rule covered, because `rm` existed only as the pattern `rm -rf` and the redirect denylist's `*.jsonl` did not match `events.jsonl.1`.
-On Codex, the destructive-command rules are instructions only because no compatible `PreToolUse` command handler is wired. Rule source of truth: [`.claude/rules/parallel-sessions.md`](../.claude/rules/parallel-sessions.md) (PSA-003). Per-session bypass via Session Config: `allow-destructive-ops: true` (intentional maintenance only).
+**13 of its 17 rules are `severity: block`, the other 4 only warn** (measured 2026-10-22: `jq '[.rules[].severity]|group_by(.)|map({(.[0]):length})|add' .orchestrator/policy/blocked-commands.json`).
+The 17th is `git-hooks-missing-in-worktree` (#1732): `git commit`/`git push` in a linked worktree whose relative `core.hooksPath` (husky: `.husky/_`) is missing there while the main checkout has it — such a worktree runs no hook at all, silently. The fix, each step as its own command: install the dependencies from the lockfile (`npm ci` / `pnpm install --frozen-lockfile` — a bare `npx husky` without them would fetch husky from the public registry past SEC-020 and leave hooks that fail on missing tools), then `npx husky`. Not judged, and on purpose not named in the deny message: a directory the guard cannot read (variable, `cd -`, a `cd` inside a subshell or command substitution, `--git-dir`/`--work-tree`, `-c core.hooksPath=…`) and an explicit skip (`--no-verify`, `commit -n`/`-nm`, `HUSKY=0`). The 16th is `ledger-delete-protected` (#1401): `rm`/`mv`/`unlink` on `.orchestrator/metrics/**` — added after a wave agent deleted a rotated 53.896-line ledger archive that no rule covered, because `rm` existed only as the pattern `rm -rf` and the redirect denylist's `*.jsonl` did not match `events.jsonl.1`.
+On Codex the guard is wired in `hooks/hooks-codex.json` too: Codex sends shell calls as `tool_name: "Bash"` (#1669) and honours the deny — measured 2026-10-20 on codex-cli 0.160.1, a `printf x > CLAUDE.md` was blocked and the file stayed unchanged (#1691). Rule source of truth: [`.claude/rules/parallel-sessions.md`](../.claude/rules/parallel-sessions.md) (PSA-003). Per-session bypass via Session Config: `allow-destructive-ops: true` (intentional maintenance only).
 
 ### enforcement-gates: the five gate keys (#800/#915)
 
@@ -559,7 +563,7 @@ resource-thresholds:
   ram-free-min-gb: 4            # soft memory signal (see precedence below)
   ram-free-critical-gb: 2       # hard memory signal → coordinator-direct
   cpu-load-max-pct: 90          # soft CPU signal, judged on min(1m, 5m)
-  concurrent-sessions-warn: 5   # soft signal at this many live peer SESSIONS
+  concurrent-sessions-warn: 5   # REPORTED at this many live peer SESSIONS; never a soft signal (#1654)
   ssh-no-docker: true           # when session is over SSH, steer the plan away from Docker-based tests
   zombie-threshold-min: 30      # age (minutes) above which an idle Claude/Node process is a zombie candidate
 ```
@@ -584,8 +588,16 @@ hosts with 24-128 GB installed — gating on it fired `ram-free-critical-gb` on
 comes from the session registry (`detectPeers()` — self excluded,
 heartbeat-fresh). Until #1089 it was compared against `claude_processes_count`, a
 measured 6x unit error (median processes:sessions = 6.0) that fired the threshold
-on 93.6% of starts instead of 4.2%. When the registry is unreadable the probe
-falls back to the process count rescaled by that same factor.
+on 93.6% of starts instead of 4.2%. The 4.2% did not hold: re-measured on
+2026-10-17 (#1650), `peer_count >= 5` fired on 67.4% of M4 and 25.7% of M5
+starts since 2026-08-24, so the banner icon now follows a start wave instead.
+Since #1654 the key is **report-only** in `evaluate()` too: reaching it adds an
+`info:` reason but never a soft signal, so it can neither cap a wave alone nor
+pair with another signal into a cap (HR-104 — a standing condition is no second
+opinion). `/evolve`'s `concurrent-session-pressure` detector no longer reads it
+either; it keys on the start-wave field `recent_starts_count`.
+When the registry is unreadable the probe
+falls back to the process count rescaled by that same factor (equally report-only).
 
 **`zombie-threshold-min`** (default: `30`): When set, the resource probe runs a secondary `ps` pass that counts Claude and Node processes older than this many minutes **and** with CPU% ≤ 1%. These are "zombie candidates" — stale sessions or orphaned workers that still hold RAM. The probe exposes them via `zombie_processes_count` in the snapshot. Since #1089 this is a *soft* signal: it is reported when `zombie_processes_count >= 1` **and** there is a live peer/process context, but on its own it caps nothing — sweeping stale sessions is housekeeping advice, not a reason to shrink a wave. The reason string surfaces the threshold and count so the session-start banner gives actionable context. Set to `0` to disable zombie detection entirely (the field is omitted from the default snapshot when absent from config).
 
@@ -793,6 +805,8 @@ vault-integration:
 >
 > A leading `~` is expanded to the home directory: `path-prefix` when matching, and the `path` / `paths.vault-dir` value the two owner.yaml tiers return (`match`, `owner`). The `env` and `committed` tiers pass through unexpanded; `scripts/vault-mirror.mjs` expands its `--vault-dir` at entry, so a `~/…` from any tier reaches the vault rather than `<cwd>/~/…`.
 >
+> `projects-root` (#1562) — the cross-repo confinement and scan root — resolves through the same layer but has no committed tier: `SO_PROJECTS_ROOT` env > `owner.yaml` `paths.projects-root` > `~/Projects` (env `CROSS_REPO_CONFINEMENT_ROOT`, test-only, outranks all three). A leading `~` is expanded; a relative value is ignored with a WARN. Resolver: `getConfinementRoot()` in `scripts/lib/config/cross-repo.mjs`; see § `cross-repo.projects` block form.
+>
 > The parsed config reports which tier won as `vault-integration.vault-dir-source` (`env`, `match`, `owner`, `committed`). This keeps maintainer-specific absolute paths out of version control. Resolvers: `scripts/lib/config.mjs` (`resolveVaultDir`, exported; `scripts/vault-backfill.mjs` resolves its stub root through it, #1094), `scripts/lib/config/host-paths.mjs` (`resolveHostPath`, used for `plan-baseline-path`) and `scripts/lib/named-baseline-resolver.mjs` (the `baselines:` / `vault-dirs:` match tier).
 >
 > **Fake-repoRoot trap (moved from CLAUDE.md Critical Gotchas, 2026-09-25).** A throwaway invocation of a vault writer (`mirrorNarrative()`, `vault-mirror.mjs`, the board writer) with a synthetic `repoRoot` does **not** land in a sandbox — the fake repo path only fakes the SOURCE, never the DESTINATION. A reviewer in this repo walked into exactly that.
@@ -812,6 +826,26 @@ vault-integration:
 | `vault-integration.vault-name` | string or null | `null` | Optional override for the per-project vault namespace segment (#660). When set (or via CLI `--vault-name`), vault writes go to `40-learnings/<vault-name>/` and `50-sessions/<vault-name>/`, sanitised to a kebab slug. When null/absent, the namespace is derived from the git origin via `deriveRepo()`. Owner-privacy leaks (personal home path / private slug / personal name) are redacted to `redacted-repo`. NOT a filesystem path → NOT host-path-resolved. **Coverage gap:** portfolio board rows are NOT yet namespace-aware — the override only reaches `40-learnings/`, `50-sessions/`, and the per-repo narrative mirror (`narrative-mirror.mjs`, #832 item 2); tracked separately in #832. Resolver: `scripts/lib/vault-mirror/namespace.mjs` (`resolveRepoNamespace`). |
 | `vault-integration.gitlab-groups` | string[] or null | `null` | List of GitLab group paths to scan for repos missing `.vault.yaml`. Parsed by `_parseVaultIntegration` (`scripts/lib/config/vault-integration.mjs`) and consumed by `scripts/vault-backfill.mjs`. Accepts a comma string, `[a, b]`, or a YAML block list; in the inline-object form more than one group needs `[a, b]`; an empty list is `null`. YAML semantics: `null`, `~` and an empty value mean unset (as a list element too, where they are dropped), and each element loses one pair of matching quotes — `["a"]` is the group `a`, and only a quoted `"null"` element is a group named `null`. Also consumed by the `/plan retro` vault-backfill sub-mode (`skills/plan/mode-retro.md` Phase 1.6 Step 1). When null/unset and neither `--groups` nor `--yes` is passed, the backfill CLI exits 1 with `no GitLab groups specified — pass --groups <CSV> or set vault-integration.gitlab-groups in CLAUDE.md`. |
 
+### Learnings store role (host-local, #1516)
+
+The store role is a **host-wide** switch: it applies to every repo on this host, not to one repo. It exists for repos with versioned learnings that are synced between two hosts — only one host may rewrite `.orchestrator/metrics/learnings.jsonl` wholesale, because every rewrite replaces the whole file and two rewriting hosts conflict on every merge. Setting `inbox` on a host therefore makes that host an inbox for **all** its repos. The role is host-local and is not a Session Config key. Precedence: env `SO_LEARNINGS_STORE_ROLE=writer|inbox` > `owner.yaml` `learnings.store-role` > `writer`. Resolver: `scripts/lib/learnings/store-role.mjs` (`resolveStoreRole()`).
+
+**Limit:** a repo that lives only on an inbox host, with no writer host anywhere, silently freezes: nothing ever sweeps, prunes or rewrites its store, and confidence updates never land — new learnings pile up in `learnings-inbox.jsonl`. There is no per-repo role. For such a repo, run the write command with a one-shot override, e.g. `SO_LEARNINGS_STORE_ROLE=writer node scripts/sweep-expired-learnings.mjs --apply`; the override ingests the inbox records on that run.
+
+**Fail-closed:** only "nothing configured" (no env value, no owner.yaml, no `learnings` key, an empty `learnings:`, or a `learnings` section without `store-role`) means `writer`. A role that is set but unusable resolves to `invalid`: a non-empty `SO_LEARNINGS_STORE_ROLE` that is not `writer`/`inbox`, an owner.yaml that exists but cannot be read, or an owner.yaml with a top-level `learnings` key whose `store-role` does not load as a valid role (typo such as `inbx`, any key other than `store-role` such as the misspelt `store_role`, unparseable file, missing YAML parser). With an invalid role every write path for the canonical store refuses and writes nothing: `appendLearning()`, `rewriteLearnings()` (not on `dryRun`), and the applies of the expiry sweep, `pruneLearnings()` and `dropMalformedLines()` throw `LearningsStoreRoleError` before any lock, archive append or rewrite; `apply-session-learnings.mjs --apply` exits 4, `export-hw-learnings.mjs --promote` exits 1, `run-migrate-v2-cross-repo.mjs --apply` exits 4 (repos reported `status: 'refused-store-role-invalid'`), and `migrate-legacy-learnings.sh` exits 4 (`{"status":"refused_store_role_invalid"}`, also when `node` cannot resolve the role). Readers keep working. Ceiling: a top-level `learnings` mapping written in YAML flow style (`{learnings: {...}}`) is not detected, so a broken one of those still resolves to `writer`.
+
+- **`writer`** (default): unchanged behaviour. A rewrite of the live store also takes in the inbox records it carries, and an expiry sweep or prune archives inbox records directly; the writer appends one `{id, ingested_at}` receipt line per record it ingested or archived to `learnings-inbox-ingested.jsonl`. The archive itself is not synced between hosts, so the receipt is what keeps an archived record hidden on the inbox host.
+- **`inbox`**: the live store is never written on this host. New learnings are appended to `learnings-inbox.jsonl` beside it. Readers (`readLearnings()`, the session-start banner, the learnings index, the dialectic deriver and the auto-dialectic signal count) show the live records plus every inbox record that is not live, archived or receipted. `backfill-learnings-from-vault.mjs` counts an id found in the inbox as present (`found_in: inbox`): on an inbox host every inbox id, so a second `--apply` there appends nothing; on any other host only a visible one (not receipted, not archived), so a record that was ingested and then lost from the live store is still restored. Two readers deliberately read only the live store (#1685): `vault-mirror.mjs` (an inbox record gets its vault note on the first mirror run after ingest) and the rule-expiry sweep (an inbox-only learning-id resolves as absent: a consolidated pair stays kept, a single-entry rule falls back to its own `expires-at`).
+- Writes that only make sense on the writer refuse on an inbox host: the expiry sweep and `pruneLearnings()` archive nothing (result field `skipped: 'store-role-inbox'`; the prune still appends new ids to the inbox; session-end 3.6.4 returns `{ran: false, reason: 'store-role-inbox'}` without `orchestrator.learnings.sweep_applied`, and `sweep-expired-learnings.mjs` emits no `orchestrator.evolve.completed` and ends its human line with `skipped=store-role-inbox`), `dropMalformedLines()` writes nothing, `export-hw-learnings.mjs --promote` exits 1, `run-migrate-v2-cross-repo.mjs --apply` exits 3 and `migrate-legacy-learnings.sh` exits 3.
+- **Sync:** both inbox files are append-only, so the consumer's `.gitattributes` needs `merge=union` for them:
+
+  ```
+  .orchestrator/metrics/learnings-inbox.jsonl merge=union
+  .orchestrator/metrics/learnings-inbox-ingested.jsonl merge=union
+  ```
+
+- **Ceilings:** an inbox host drops confidence updates, decay and sweeps of existing learnings; only records with a new id reach the writer. The inbox file is never truncated; records already ingested or archived stay in it and are hidden by their receipts.
+
 ### Environment override: `VAULT_MIRROR_CANONICAL_SUFFIX`
 
 `vault-mirror.mjs` refuses to mirror into any directory whose `git remote get-url origin` does not end with a canonical-vault path suffix — a network-of-trust guard (#600 D2) that stops notes from silently accumulating in a wrong or typo'd vault location. A non-matching suffix fails the **whole run** (`process.exit(2)`), not a per-entry skip — mirroring even one note into the wrong place is the bug it prevents.
@@ -1059,7 +1093,7 @@ dialectic:
 
 Opt-in configuration for the Standard v1 evaluation harness and the `/eval` skill (Session-Prozess-Eval). The current workflow is documented in `skills/eval/SKILL.md`.
 
-The original config proposal is in the archived PRD `docs/prd/2026-07-16-aiat-llm-eval.md` §S6 (Epic #803). <!-- path-check: historical -->
+The original config proposal is in the archived LLM-eval PRD of 2026-07-16, §S6 (Epic #803; internal, not in the public mirror).
 
 All fields live under a top-level `eval` object in your Session Config host file (`CLAUDE.md` or `AGENTS.md`), for example:
 
@@ -1260,8 +1294,8 @@ gitlab-portfolio:
 
 | Field | Type | Default | Allowed values | Description |
 |-------|------|---------|----------------|-------------|
-| `gitlab-portfolio.enabled` | boolean | `false` | `true` / `false` | Only the literal `true` enables it. When false, `/portfolio` prints `disabled` and exits 0 (`cli.mjs:192-199`), and session-start Phase 2.7 skips its dry-run banner (`skills/session-start/SKILL.md` § Phase 2.7). |
-| `gitlab-portfolio.mode` | string | `warn` | `warn` / `strict` / `off` | `strict` makes the CLI exit 2 when any repo failed to fetch (`cli.mjs:375`). `warn` and `off` both exit 0 in the CLI; `off` additionally suppresses the session-start banner. An unknown value falls back to `warn`. |
+| `gitlab-portfolio.enabled` | boolean | `false` | `true` / `false` | Only the literal `true` enables it. When false, `/portfolio` prints `disabled` and exits 0 (`cli.mjs:195`), and session-start Phase 2.7 skips its dry-run banner (`skills/session-start/SKILL.md` § Phase 2.7). |
+| `gitlab-portfolio.mode` | string | `warn` | `warn` / `strict` / `off` | `strict` makes the CLI exit 2 when any repo failed to fetch (`cli.mjs:386`). `off` makes the CLI exit 0 with one line before it resolves the vault-dir or scans any repo, and writes nothing (`cli.mjs:203`, #1619); it also suppresses the session-start banner. `warn` exits 0 with partial data. An unknown value falls back to `warn`. |
 | `gitlab-portfolio.stale-days` | integer | `30` | integer ≥ 1 | An open issue whose `updated_at` is older than this counts as stale (`scripts/lib/gitlab-portfolio/aggregator.mjs`). An invalid value falls back to `30`. |
 | `gitlab-portfolio.critical-labels` | array of string | `[priority::critical, priority::high]` | non-empty strings | Labels that count an issue as critical; matching is scope-tolerant (`priority:critical` also matches). **Block list only:** items need their own `- ` lines indented at least 3 spaces. The inline form `critical-labels: [a, b]` is NOT read — the parser silently keeps the default (measured 2026-09-18 via `_parseGitlabPortfolio`). |
 
@@ -1357,7 +1391,7 @@ Opt-in declaration of ssh-reachable hosts a heavy wave role may be OFFLOADED to
 
 ```yaml
 remote-hosts:
-  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+  - alias: build-host                  # required, SAFE slug; reaches argv as `-H <alias>`
     roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
     repo-path: ~/Projects/Alice     # optional; SAFE path; default null
     claude-path: ~/.local/bin/claude   # optional; SAFE path; default null
@@ -1373,7 +1407,7 @@ remote-hosts:
 
 **Two enums, never conflated.** `roles-allowed` holds `agent-mapping` roles (`test`, `ui`, `perf`) — NOT wave roles (`Impl-Core`, `Quality`, …). The wave→role translation is `OFFLOADABLE_WAVE_ROLES` in `scripts/lib/wave-resource-gate.mjs`; a wave role absent from that map is local-only by default.
 
-**Placement contract.** The gate applies its offload arm only after the HR-004 heavy-repo cap, and only when the resource verdict was `reduce` or `coordinator-direct` — or, with `offload-first: true`, on `proceed` as well (see § `offload-first` below). It does NOT probe the network: the coordinator supplies a readiness witness (`remoteReady: { m5: true }`, or an async `probeFn`). With no witness, no host counts as ready and the decision stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`) is never offloaded regardless.
+**Placement contract.** The gate applies its offload arm only after the HR-004 heavy-repo cap, and only when the resource verdict was `reduce` or `coordinator-direct` — or, with `offload-first: true`, on `proceed` as well (see § `offload-first` below). It does NOT probe the network: the coordinator supplies a readiness witness (`remoteReady: { 'build-host': true }`, or an async `probeFn`). With no witness, no host counts as ready and the decision stays local — the gate fails toward local, never toward an unverified host. A role in `NEVER_FOREIGN_ROLES` (`scripts/lib/wave-executor/dispatch-common.mjs`) is never offloaded regardless.
 
 **agent-mapping interaction.** A declared alias is what an `agent-mapping` value of the form `<role>: ssh:<alias>` validates against; naming an undeclared host throws at parse time, naming the `ssh` channel with no target throws as for any other channel.
 
@@ -1396,7 +1430,7 @@ offload-first: false   # true = offloadable roles go to a witnessed-ready remote
 **Behaviour with `offload-first: true`.**
 
 - Only roles in `OFFLOADABLE_WAVE_ROLES` (`scripts/lib/wave-resource-gate.mjs`) move: wave roles `quality` / `test` → `test`, `ui` → `ui`, `perf` → `perf`. The table is NOT extended by this switch — build, lint and audit work is covered by the Quality wave's `test` role. `impl-core`, `security-review`, `migration`, `release`, `secrets`, `incident` and `refactor-crosscut` never leave the local host.
-- The target is the FIRST declared `remote-hosts` entry whose `roles-allowed` carries the mapped role AND that is witnessed ready (`remoteReady: { m5: true }` or an async `probeFn`). The gate still never probes the network itself, so the witness is mandatory for the switch to have any effect: without one, nothing offloads even with the switch on.
+- The target is the FIRST declared `remote-hosts` entry whose `roles-allowed` carries the mapped role AND that is witnessed ready (`remoteReady: { 'build-host': true }` or an async `probeFn`). The gate still never probes the network itself, so the witness is mandatory for the switch to have any effect: without one, nothing offloads even with the switch on.
 - The HR-004 heavy-repo cap still binds the offloaded agent count.
 - No ready host for the role → the verdict is unchanged (`proceed`, or the `reduce`/`coordinator-direct` the resource rules computed) and `reasons` carries `offload-first: no ready host for '<role>' — staying local`.
 - Switch on but no `remote-hosts` declared → the verdict is unchanged and `reasons` carries `offload-first: true but no remote-hosts declared — staying local`. `validateSessionConfig()` (`scripts/lib/config-schema.mjs`) additionally emits a warn-level cross-field finding `offload-first-cross-field` for that combination; it never flips `ok`.
@@ -1531,7 +1565,7 @@ Implementation: `scripts/lib/recommendations-v0.mjs` → `computeV0Recommendatio
 
 - Pre-v1.1 STATE.md files (produced by sessions before Epic #271 shipped) simply do not contain these fields. The parser returns `null` from `parseRecommendations`; the banner silently no-ops.
 - `schema-version` is NOT bumped to `1.1` in the frontmatter — the existing `schema-version: 1` remains canonical. The v1.1 label is documentation-only, describing the additive surface.
-- Idle Reset (session-start Phase 1.5) archives these fields into the `## Previous Session` body block of STATE.md as a human-readable block, then removes them from the frontmatter — so a fresh session never inherits stale recommendations in its live frontmatter.
+- Idle Reset (session-start Phase 1.5, `scripts/state-md-idle-reset.mjs`) copies these fields into the `## Previous Session` body block of STATE.md as a human-readable block and KEEPS them in the frontmatter: they are the handoff the Phase 7.5 Mode-Selector reads after the reset (#1560). Deleting them, as the reset did before #1560, left the selector at confidence 0 after every clean `/close`. The next session-end Phase 3.7a overwrites them.
 
 ### Reader behavior
 
@@ -1552,8 +1586,8 @@ The banner renders with one of the following shapes:
 
 - **Writer:** `skills/session-end/SKILL.md` § Phase 3.7a "Compute and Write Recommendations" (runs after Phase 3.7 sessions.jsonl write, before Phase 3.4 `status: completed` setting).
 - **Reader:** `skills/session-start/SKILL.md` § Phase 1.5 "Recommendations Banner" (renders on `status: completed` branch only).
-- **Archival:** `skills/session-start/SKILL.md` § Idle Reset rule 6 (removes fields from frontmatter, prepends readable block to `## Previous Session`).
-- **Future consumer:** Phase B Mode-Selector skill (planned in Epic #271) will read these fields as the primary input for autonomous mode selection.
+- **Archival:** `skills/session-start/references/phase-1-5-session-continuity.md` § Idle Reset rule 6 (keeps the fields in the frontmatter, prepends a readable block to `## Previous Session`).
+- **Mode-Selector:** `skills/session-start/phase-7-5-mode-selector.md` reads these fields through `buildLiveSignals()` (`scripts/lib/build-live-signals.mjs`) as its primary input.
 
 ## Frontend-Slop Hook (#684) — deprecated
 
@@ -1628,7 +1662,7 @@ reaper:
 | `reaper.max-hook-latency-ms` | integer (≥ 1) | `50` | Ceiling the TRIGGER may delay a hook by — the config read, the marker `stat` and the detached spawn, measured with `performance.now()` in `maybeTriggerOrphanScan()`. Overrunning it writes ONE stderr WARN line and nothing else: no event (a `PostToolBatch`-class hook emitting per fire is the always-on signal HR-101 calls a broken instrument) and no abort (the child is already detached by then). The scan itself is not covered — that is the point of spawning detached. |
 | `reaper.false-alarm-window` | integer (≥ 1) | `50` | Rolling window of audit decisions the HR-101 10 % false-alarm rate is judged over — a window in DECISIONS, not calendar time, so the rate has a population on quiet hosts too. Reaches the scan as `--false-alarm-window` on the detached child's argv and becomes `runOrphanScan`'s `falseAlarmWindow`; the CLI refuses `0`, which `falseAlarmRate()` would read as “every firing ever recorded” rather than as a window. |
 
-**Used by:** `hooks/post-tool-batch-wave-signal.mjs`, `hooks/on-stop.mjs` (both via `maybeTriggerOrphanScan()` from `scripts/lib/orphan-reaper/trigger.mjs`), `scripts/lib/orphan-reaper.mjs`, `scripts/lib/config/reaper.mjs` (`_parseReaper`). PRD `docs/prd/2026-09-20-prozessgruppen-kill-und-waisen-waechter.md`, Epic #1425, issue #1432.
+**Used by:** `hooks/post-tool-batch-wave-signal.mjs`, `hooks/on-stop.mjs` (both via `maybeTriggerOrphanScan()` from `scripts/lib/orphan-reaper/trigger.mjs`), `scripts/lib/orphan-reaper.mjs`, `scripts/lib/config/reaper.mjs` (`_parseReaper`). the internal process-group-kill and orphan-reaper PRD (2026-09-20, not in the public mirror), Epic #1425, issue #1432.
 
 ## Gate Timeout — Path B (#1425 A3)
 

package/docs/session-config-template.md

@@ -8,11 +8,29 @@
 
 1. Pick the host file: `CLAUDE.md (or AGENTS.md on Codex CLI)`. Never both.
 2. Add a single `## Session Config` H2. The header must match exactly — `skills/_shared/config-reading.md` parses the block under that heading.
-3. Start from the [Full minimal baseline](#full-minimal-baseline-copy-paste) at the bottom of this document. Add opt-in blocks one at a time as you adopt features.
+3. Start from the [Starter config](#starter-config-copy-paste) directly below. Add opt-in blocks one at a time as you adopt features; the [Full opt-in baseline](#full-opt-in-baseline-copy-paste) near the end shows every block at once.
 4. Run `/bootstrap --retroactive` to schema-validate the result.
 5. Validate at any time with `node scripts/parse-config.mjs --json`.
 
-The format is the same on every platform. Fields not listed here are silently ignored — typos do **not** raise.
+The format is the same on every platform. A top-level key this template does not list has no effect, so `node scripts/parse-config.mjs` reports it on stderr with file, line and key — a typo, or a key from a newer plugin version. The report appears under `enforcement: warn` and `strict` and never refuses the run; `enforcement: off` silences it.
+
+## Starter config (copy-paste)
+
+The smallest valid Session Config — passes `validate-config` without warnings on a typical Node/TS repo:
+
+```yaml
+## Session Config
+
+test-command: npm test
+typecheck-command: npm run typecheck
+lint-command: npm run lint
+agents-per-wave: 6
+waves: 5
+persistence: true
+enforcement: warn
+```
+
+That's enough for `/session feature` → `/go` → `/close` to work end-to-end. Every other field falls back to documented defaults.
 
 ## Where this file lives
 
@@ -68,7 +86,7 @@ Read by: `skills/session-start/SKILL.md` (Phase 4.5), `skills/session-plan/SKILL
 ```yaml
 vcs: gitlab                            # github | gitlab — auto-detected from remote when unset
 gitlab-host: gitlab.example.com        # only if remote URL doesn't expose it
-mirror: github                         # session-end pushes to the `github` remote (none | github; absent = push if remote exists)
+mirror: github                         # session-end pushes to the `github` remote (none | github | curated; absent = push if remote exists; curated = public snapshot via scripts/github-export.mjs)
 cross-repos: [related-repo-1]          # repos under ~/Projects/ to snapshot at session-start
 pencil: path/to/design.pen             # design-code alignment input
 ecosystem-health: true                 # toggle health-endpoint probes
@@ -172,7 +190,7 @@ resource-thresholds:
   ram-free-min-gb: 4                   # below: cap agents-per-wave at 2
   ram-free-critical-gb: 2              # below: recommend coordinator-direct
   cpu-load-max-pct: 80                 # sustained above: cap agents-per-wave at 2
-  concurrent-sessions-warn: 5          # warn at this many peer Claude sessions
+  concurrent-sessions-warn: 5          # report-only: names peer sessions, never caps (#1654)
   ssh-no-docker: true                  # SSH session: avoid Docker-based tests
   zombie-threshold-min: 30             # min idle time before stale-process flag (#178)
 ```
@@ -393,7 +411,7 @@ Opt-in declaration of ssh-reachable hosts that heavy wave roles may be OFFLOADED
 
 ```yaml
 remote-hosts:
-  - alias: m5                          # required, SAFE slug ([A-Za-z0-9._-]); reaches argv as `-H <alias>`
+  - alias: build-host                  # required, SAFE slug ([A-Za-z0-9._-]); reaches argv as `-H <alias>`
     roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
     repo-path: ~/Projects/Alice     # optional SAFE path (default: null)
     claude-path: ~/.local/bin/claude   # optional SAFE path (default: null)
@@ -660,24 +678,6 @@ Read by: `skills/session-plan/SKILL.md`, `skills/wave-executor/wave-loop.md`.
 
 The dispatch resolution is three-tier: project agents (`.claude/agents/`) > plugin agents (`session-orchestrator:*`) > `general-purpose`.
 
-## Full minimal baseline (copy-paste)
-
-The smallest valid Session Config — passes `validate-config` without warnings on a typical Node/TS repo:
-
-```yaml
-## Session Config
-
-test-command: npm test
-typecheck-command: npm run typecheck
-lint-command: npm run lint
-agents-per-wave: 6
-waves: 5
-persistence: true
-enforcement: warn
-```
-
-That's enough for `/session feature` → `/go` → `/close` to work end-to-end. Every other field falls back to documented defaults.
-
 ## Full opt-in baseline (copy-paste)
 
 Everything turned on for a project that wants the full feature surface (vault, docs, drift checks, env-aware sizing). Trim to taste:
@@ -697,6 +697,7 @@ enforcement: warn
 # Session structure
 recent-commits: 20
 special: "follow .claude/rules/parallel-sessions.md"
+project-name: my-project               # informational: written by /bootstrap, names the repo for readers; no runtime reader
 
 # VCS & infrastructure
 vcs: gitlab
@@ -793,6 +794,13 @@ vault-integration:
   vault-name:                          # optional (#660) — per-project vault namespace override; null/absent → deriveRepo()
   gitlab-groups: []
 
+# Product-vault registration — written by /bootstrap (skills/bootstrap/_shared-template.md);
+# its presence is the marker hasVaultConfig() reads so bootstrap does not ask again
+vault:
+  path: ~/Projects/vault
+  product-domain: my-domain
+  persona-db:
+
 # GitLab portfolio dashboard — /portfolio (GH #41); needs vault-integration.vault-dir
 gitlab-portfolio:
   enabled: false                       # opt-in; only the literal true enables it
@@ -890,7 +898,7 @@ custom-phases:
 
 # Remote hosts — ssh-reachable offload targets for heavy roles (#1160)
 remote-hosts:
-  - alias: m5                          # required, SAFE slug; reaches argv as `-H <alias>`
+  - alias: build-host                  # required, SAFE slug; reaches argv as `-H <alias>`
     roles-allowed: [test, ui, perf]    # subset of test|ui|perf (default: all three)
     repo-path: ~/Projects/Alice     # optional SAFE path (default: null)
     claude-path: ~/.local/bin/claude   # optional SAFE path (default: null)

package/docs/sessions-ledger-repair.md

@@ -0,0 +1,137 @@
+# Session ledger diagnosis and repair
+
+The session ledger is `.orchestrator/metrics/sessions.jsonl`. Diagnose schema
+failures separately from records that vault-mirror cannot render. Repairing a
+ledger is a write operation; a guard allowance does not authorize repairing a
+consumer's history. Obtain a separate task before applying repairs to a real
+consumer or vault ledger.
+
+## Missing metrics are unknown
+
+`validateSession` accepts an absent or `null` `effectiveness`. All three mirror
+renderers accept that same shape and display unknown metrics as `n/a` (or the
+existing table placeholder). A measured zero remains zero. Optional missing
+subfields likewise remain unknown; neither rendering nor repair invents issue
+counts or completion rates. A malformed non-object `effectiveness`, including
+an array, still fails rendering.
+
+Legacy V2 and V3 records can render while failing the canonical writer schema.
+V2 lacks canonical aggregate fields; V3 uses scalar `waves` instead of the
+required array. Those are separate schema defects, not evidence that missing
+`effectiveness` needs a migration. An already schema-valid historical line is
+preserved byte-for-byte by the repair helper, with one exception (#1705): a
+valid record whose `completed_at` copies a valid, monotonic `ended_at` but is
+still listed in `_backfill_incomplete_fields` is healed (status `repaired`,
+counted `healed_valid`, defect `completed_at_flag_stale`; the prior list is kept
+once in `_backfill_incomplete_fields_raw`).
+
+## Read-only diagnosis
+
+Use the installed plugin's actual absolute script path and the actual project
+root. These examples use generic paths:
+
+```sh
+node /opt/plugin/scripts/check-sessions-integrity.mjs --repo-root /work/repo --json
+node /opt/plugin/scripts/repair-invalid-sessions.mjs --dry-run --repo-root /work/repo --json
+```
+
+The integrity command and session-start banner evaluate validation and the real
+mirror render path independently. The banner reports `schemaInvalid` and
+`mirrorSkipped`; a render-only failure is not proof of a schema failure or of
+how a record was written. A schema-invalid record that still renders produces
+a warning; a mirror skip produces an alert. Abandoned session filtering applies
+to this banner population.
+
+Repair dry-run reports schema defects, projected repairs, and the lines that
+would remain unrepairable. It is a repairability preview, not an integrity
+verdict: exit 0 alone does not prove that every record currently validates and
+renders. Compare named lines and defect classes, accounting for banner filters
+and renderer-only failures rather than expecting all totals to be identical.
+Dry-run writes nothing and is the CLI default. The CLI can diagnose a metrics
+directory outside a Git repository; the new guard allowance for apply cannot.
+
+## Apply and recovery
+
+The repair CLI retains its existing contract: before replacing the file it
+creates a mandatory `<file>.bak-<stamp>` backup, writes replacement content to
+a temporary file, and atomically renames it over the target. It verifies the
+result against validation and, for the canonical ledger path, integrity. Failed
+post-verification restores the backup byte-for-byte. Repairable rows retain
+their position; valid rows (except the stale-flag heal above) and unrepairable
+rows retain their original bytes.
+Duplicate IDs are observed, never deduplicated. Repeating a successful repair
+preserves ledger bytes; `--apply` still creates a backup and atomically replaces
+the file.
+
+The CLI restricts targets to `<repo-root>/.orchestrator/metrics/`, resolving
+parent symlinks for containment. Its broader CLI flags do not broaden the
+guard's apply allowance.
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Completed; no unrepairable remainder reported (dry-run may propose repairs) |
+| 1 | Argument or target error |
+| 2 | System or I/O error |
+| 3 | Post-verification failed; backup restored, no repairs kept |
+| 4 | Repairable lines handled; unrepairable lines remain unchanged |
+
+Exit 3 takes precedence over exit 4. Inspect the summary and retained backup
+before deciding on further work; never bypass the ledger guard to force a repair.
+
+## Guarded apply commands
+
+The existing exact relative form remains supported:
+
+```sh
+node scripts/repair-invalid-sessions.mjs --apply
+```
+
+The additional allowance accepts only the installed plugin's canonical absolute
+repair script, with `--apply` followed by mandatory `--repo-root` and the
+absolute current Git top-level:
+
+```sh
+node /opt/plugin/scripts/repair-invalid-sessions.mjs --apply --repo-root /work/repo
+node '/opt/plugin with spaces/scripts/repair-invalid-sessions.mjs' --apply --repo-root '/work/repo with spaces'
+```
+
+Use literal path values, with simple single quotes for spaces. Do not place
+`$PWD`, environment expansions, command substitutions, escaping, redirections,
+pipes, chained commands, or shell wrappers in the tool command. Additional
+flags (including `--file`, `--json`, or `--dry-run`), reordered arguments,
+alternative Node spellings, and foreign script paths do not qualify.
+
+The script and all path components must exist at canonical absolute paths
+without symlinks. The measured Git top-level for the hook process and payload
+working directory must agree. The measured root must also contain both physical
+working directories; a local `core.worktree` setting that reports a root
+elsewhere grants no apply allowance. The hook's project resolver, including
+launcher-provided context, must resolve to that same root. The explicit root
+must exactly equal the measured realpath: no trailing slash, `..`, subdirectory
+or another checkout. Omitting `--repo-root` is denied: a child CLI without the
+hook's launcher variables could otherwise select a nested `CLAUDE.md` root.
+Git discovery/configuration overrides,
+a symlinked `.git` marker, context disagreement, or a failed Git measurement
+deny the additional allowance. A sandbox Git error is a denial, not evidence
+that the native target context works.
+
+For synthetic mirror or repair probes, set `SO_VAULT_DIR` to a fresh temporary
+directory before running the probe and let child processes inherit it. Apply
+tests belong only on disposable ledgers with isolated configuration. Native
+path and process behavior requires a suitable native runner; sandbox results
+do not establish macOS acceptance.
+
+The absolute repair allowance denies `--repo-root` equal to or inside the
+realpath-resolved vault directory. The existing resolver gives precedence to
+`SO_VAULT_DIR`, owner configuration (`vault-dirs`, then `paths.vault-dir`), then
+the committed `vault-dir`. A measurable configured vault takes precedence over
+the fallback. If resolution has no value, fails, or cannot be canonicalized,
+only the realpath-resolved `<canonical HOME>/Projects/vault` and its descendants
+are denied. Prefix neighbors such as `vault-x` and other `vault` segments under
+`Projects` are not fallback targets. If the fallback also cannot be measured,
+it adds no denial; the other absolute-allowance checks still apply.
+
+This check applies only to the absolute repair allowance. The exact relative
+repair exception is unchanged; the check is not a general vault-write boundary.
+Vault ledgers remain forbidden repair targets under this runbook, regardless
+of whether a command receives a guard allowance.

package/docs/vault-docs-architecture.md

@@ -11,7 +11,7 @@ to recover when something breaks.
 re-measured against the code that writes it — `scripts/lib/vault-status/narrative-mirror.mjs`
 (`resolveNarrativePath`) and `scripts/lib/vault-status/board-writer.mjs` (`resolveBoardPath`) —
 after the pre-#673/#674/#675 layout in this file was found stale by the 2026-09-06
-360°-Audit (`docs/audits/2026-09-06-360-audit/w1/d6-docs-drift.md`). The `daily` skill
+360°-Audit (its docs-drift report; audit reports are not part of the public mirror). The `daily` skill
 rows are gone with the skill itself (§ 5A of that audit).
 
 ---