session-orchestrator 5.3.0 → 5.5.0

package/CHANGELOG.md

@@ -7,6 +7,168 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.5.0] - 2026-10-03
+
+### Added
+
+- **`events-retention` session-start probe** (`scripts/lib/events-retention-banner.mjs`, #1401 part 3, variant a). Each reader of the rotated events ledger declares `REQUIRED_EVENTS_WINDOW_DAYS` next to its call (`telemetry/sync` = 1 day, a chosen ceiling; the eval engine and `telemetry-stats` = `null`, they have no finite window). The probe warns only when the archive ring is full and covers less than the largest finite window, judged on archive start times; an unmeasured or unlistable source never records as clean. When the oldest archive's rotation record names a predecessor that was pruned (a `max-backups` raised after a prune), coverage starts at that archive, and a future-dated archive is unmeasurable rather than a negative coverage. No new config key. The probe family has 20 members.
+- **`excludedScope.shell` in the tests:src envelope** (`scripts/lib/tests-src-ratio.mjs`, #1488, variant B). Shell code (`.sh`/`.bash`/`.bats`) still counts in neither bucket, so the ratio is unchanged, but its volume (split into test and src shell) is now reported. Additive; the schema stays `tests-src-ratio/2`.
+- **`orchestrator.scope.refused_grant_allowed`** (`hooks/enforce-scope.mjs`, #1485 point 1): the first Gate-5b WARN of a wave (an absolute grant the wave-scope validator would refuse) emits one event, deduplicated per session and wave.
+- **`isDeny` predicate** in `tests/_helpers/hook-decision.mjs` (#1027 Nachtrag 8), sharing one contract with `expectDeny` / `expectAllow` (the `isAllow` twin was removed again in the same cycle: zero consumers, #1497).
+- **Probe telemetry `measure`** (`scripts/lib/session-start-probes.mjs`, #1401): a probe may declare `telemetry(result)`; its output is persisted on that probe's entry in `orchestrator.probes.completed` (at most 8 snake_case keys, finite numbers or null — the event travels the webhook unredacted). `events-retention` persists `{coverage_days, archives, max_backups, required_days}` on every measured answer, so a probe that never fires stays falsifiable (HR-105).
+- **`reaper_trigger` on Stop / SubagentStop records** (`hooks/on-stop.mjs`, #1489): the orphan-scan trigger outcome is recorded as an optional key on the existing records — absent while the reaper is disabled, no new event type.
+- **`reclaimed` on `orchestrator.session.lock.acquired`** (`hooks/_lib/lock-bootstrap.mjs`): `stale-heartbeat` or `corrupt` when a SessionStart took over a FOREIGN stale lock or an unparseable one (a session re-acquiring its own stale lock is a refresh and carries no key) — the bootstrap's stderr WARN is discarded by the harness, so takeovers were uncountable.
+- **`navigator_adresse` in `scripts/fleet-checkin.mjs` output** (#1491): the validated lease address (or `null`) that session-start Phase 7.6 sends its optional hint to.
+- **`tokens_unknown_sessions`** in the autopilot loop state, return value and `autopilot.jsonl` (#1487 item 4): an iteration whose record carries no token figure is counted instead of reading as a measured 0. The token-budget kill-switch still fires on the known lower bound.
+- **`redactHomeDir(text)`** in `scripts/lib/common.mjs` (#1490): replaces the home directory with `~` in free text, path-boundary aware (`/Users/bob` never touches `/Users/bobby`).
+- **`npm run update:local` — one command updates every local install** (`scripts/self-update.mjs`). Fast-forwards the clone (`git merge --ff-only origin/main`, `npm ci` when HEAD moved), updates the Claude Code marketplace and plugin, reads `claude plugin list --json` back and runs `npm ci --omit=dev` in the reported `installPath` when runtime dependencies are missing, and re-runs `scripts/codex-install.mjs` only when the plugin is already installed in Codex. `--dry-run` prints the mutating commands, `--skip-pull` leaves the clone alone, `--json` reports per step; old cache folders are never deleted because the running session loads them until the restart. The `release.mjs --publish` checklist names it as step 3, the Claude Code update banner points to it.
+- **`vault-mirror --repo-root`** (`scripts/vault-mirror.mjs`, #1503): names the repo whose ledger is mirrored; without it the root is `<X>` of a `<X>/.orchestrator/metrics/<file>` source, else the git repo containing `--source` (realpath'd). A root whose namespace differs from the source's aborts before writing (exit 2, `aborted: source-repo-mismatch`). Notes gain a quoted `source-record` frontmatter field (learning id; `raw_session_id`, else `started_at`).
+- **`sweep-expired-learnings --drop-malformed --line N`** (#1500): the sanctioned way to remove an unparseable learnings line. Dry run by default; `--apply` needs the store `--generation` and `--repo-root`, re-reads under the store lock, refuses a changed store or a line that is not malformed, refuses a line carrying a readable record (BOM or fused after a torn prefix) unless `--accept-embedded`, snapshots the store first and emits `orchestrator.learnings.malformed_dropped`.
+- **`fallback_due_at` in `scripts/fleet-checkin.mjs` output** (#1501): check-in `zeit` + `CHECKIN_FALLBACK_MIN` while a navigator lease is active, else `zeit`; session-start Phase 7.6 reads it instead of a hard-coded 10 minutes. The check-in file schema is unchanged.
+- **`commitlint.ci.config.mjs`** (#1477 item 4): the CI lint uses the repo config with `defaultIgnores: false` and first-line-only ignores for the merge and revert subjects git or GitLab write themselves, so `fixup!`, semver-only headers and body-line merges no longer slip through. The husky hook keeps the permissive config; `config-protection` warns on both files.
+- **`history_gaps` in the `backfill-abandoned-sessions` summary** (#1498): counts pruned archives, so a backfill over a pruned history says it planned from an incomplete record.
+
+### Changed
+
+- **Subagent worktrees branch from the session HEAD** (`.claude/settings.json` `worktree.baseRef: "head"`, #1485 point 2). Per the Claude Code docs this setting also governs `--worktree` and background sessions in this repo.
+- **The worktree base check denies only a measured stale base** (`hooks/pre-task-scope-disjoint.mjs`, #1485). It reads `worktree.baseRef` in precedence order (local → project → user) at the session root, records the deciding layer as `base_ref_source`, denies an `isolation: "worktree"` dispatch only when `git merge-base --is-ancestor HEAD origin/HEAD` exits 1, skips shallow clones, unknown bases and a cached remote ref the harness would refresh first (`FETCH_HEAD` older than 24 h or absent, `skipped: 'stale-remote-ref'`), and writes no scope-ledger claim for a denied dispatch. The STATE.md `session-start-ref` prediction it replaced was wrong per the docs.
+- **The `/evolve` prune flow snapshots first** (`scripts/sweep-expired-learnings.mjs --prune --snapshot`, `skills/evolve/**`, `.cursor/rules/060-evolve.mdc`, #1486). The sidecar's first line carries the store generation and path; `--entries` needs that header.
+- **One orphan-scan trigger** (`scripts/lib/orphan-reaper/trigger.mjs`, #1489): `hooks/on-stop.mjs` and `hooks/post-tool-batch-wave-signal.mjs` import it instead of carrying byte-identical copies; the hardened no-follow append is shared too (`no-follow-append.mjs`).
+- **Every bootstrap tier ignores the store-lock artefacts** (`skills/bootstrap/_shared-template.md` § store-lock-ignore, #1489 item 17, #1487 item 11): one idempotent snippet runs from Fast Step 3 (inherited by Standard and Deep), Upgrade Flow and Refresh-Lock Flow, so repos bootstrapped before 5.4.0 get the lines on their next refresh. It adds a missing trailing newline first (an append onto `.env` without one had un-ignored it), treats `pattern\r` in a CRLF file as present, and skips without a repository root or with an unreadable `.gitignore`.
+- **The MR pipeline lints the MR title when the merge request will squash** (`.gitlab-ci.yml` `commitlint`, #1477 item 1): only when `CI_MERGE_REQUEST_SQUASH_ON_MERGE` is `"true"`, after stripping GitLab's Draft prefixes. Merge-commit MRs keep free-form titles. `docs/ci-setup.md` lists the remaining gaps.
+- **`vault-backfill` reads `vault-integration` through the canonical parser and resolves `vault-dir` host-locally** (`scripts/vault-backfill.mjs`, `scripts/lib/config/vault-integration.mjs`, #1094): the inline-object, dash-bullet and bold-bullet forms are now read (19 of 56 instruction files on the measuring host returned no vault-dir before), a block inside an HTML comment is ignored, `SO_VAULT_DIR` and `owner.yaml` win over the committed path, `~` is expanded, and `gitlab-groups: null` means unset.
+- **Scope drift counts uncommitted and untracked files** (`scripts/lib/scope-baseline.mjs`, #1027 item 2): the numerator is the committed range ∪ the working tree vs HEAD ∪ untracked files. The plugin's own writes are excluded (`.orchestrator/metrics/**`, untracked paths under `.orchestrator/`, `<state-dir>/filescopes/**` and `<state-dir>/worktrees/**`); tracked deliverables such as `.orchestrator/steering/` and `bootstrap.lock` count. Each query is bounded (10 s, 64 MiB); a failing query skips the measurement instead of reporting a partial numerator. Files already dirty at session start, or a same-checkout peer's files, can over-report (named ceiling).
+- **A session spanning the v1/v2 token-schema boundary is reported as unpriced** — the rollup returns `total_cost_usd: null` and `sessions.jsonl` omits the field (`scripts/lib/session-token-rollup.mjs`, #1487 item 1, owner decision 2026-10-02): a v1 record is an unpriced cost candidate, so a partial sum no longer reads as the whole bill (`cost_records_priced < cost_records_total` says why).
+- **Scope hooks read the session's own working copy** (`scripts/lib/platform.mjs` `resolveSessionRoot`, #1492): `enforce-scope`, `enforce-commands`, `post-bash-write-verify` and `pre-task-scope-disjoint` resolve their control files from the repo root of the payload cwd instead of `CLAUDE_PROJECT_DIR`, so a session that entered a worktree enforces that worktree's manifest. The root never climbs above the launch directory (`CLAUDE_PROJECT_DIR`; on the Cursor/Pi bridges their `*_PROJECT_DIR`, i.e. the payload cwd as before #1492), so a session launched in a monorepo package keeps its manifest; harness `agent-<hex>` worktrees lift to their parent repo, and the auto-memory carve-out still keys on the launch directory. Named ceiling: `isolation: worktree` agents of a session that entered a worktree lift to the launch checkout and stay unenforced.
+- **One dispatch-scope ledger per session** (`hooks/pre-task-scope-disjoint.mjs`, #1493): `.orchestrator/wave-dispatch-scopes.<session>.json` (+ `.lock`, path-safe id) replaces the shared file, so two sessions in one checkout no longer erase each other's claims; a legacy shared ledger is adopted read-only when its wave key names this session. Wave step 7 and session-end 3.0 delete only this session's file.
+- **The commit guard reads ownership, enforcement and role** (`hooks/wave-scope-commit-guard.mjs`, #1493): it stands down on a foreign session's manifest, skips under `enforcement: off`, notes a Discovery manifest, reports a stale one, and treats an empty writing-role union as an incomplete `--union` (warn reports, strict blocks). Out-of-scope staged paths under a non-empty manifest keep blocking at every other level.
+- **Session-end diffs use `resolveBaselineRange`** (`skills/session-end/plan-verification.md`, docs-orchestrator, #1493): `SESSION_RANGE` is `<pinned sha>..HEAD`, else `<resolved base>...HEAD`, with explicit `no-baseline-ref` / `unresolvable-ref` skips instead of a hard two-dot `origin/main..HEAD`; the pinned ref must be hex.
+- **Consumer repos ignore every plugin runtime artefact** (`skills/bootstrap/_shared-template.md` § store-lock-ignore, #1495): the snippet appends the session lock and its temps, state/rules/dispatch/transcript-tail locks, `current-session.json`, `host.json`, the staging fence, `.orchestrator/tmp/`, rewrite backups (`*.jsonl.bak-*`, legacy `*.jsonl.bak.*`) and 16 more paths a census found missing — among them `pending-dream.md` (a private MEMORY.md draft), `metrics/test-runs/` and `metrics/ux-grill/` (screenshots) and `metrics/verification-failures/`. A census test checks every `.orchestrator/` line of this repo's own `.gitignore` against the snippet; ledgers, `bootstrap.lock`, `policy/`, `steering/` and `peers/` stay versioned.
+- **The SessionStart backfill bounds its archive reads** (`scripts/lib/session-close-backfill.mjs`, `scripts/backfill-abandoned-sessions.mjs`, #1498): a session whose start rotated into `_archive/` is read from the rotated ledger, under one shared 500 ms deadline per SessionStart; a candidate left unread is deferred (`skipped-history-unread`) instead of being written with now/now times. CLI and SessionEnd stay unbounded.
+- **Telemetry answers that read "clean" while unmeasured** (#1498): `events-retention` reports a stampless ledger as unmeasurable (`ran-warn`); the autopilot run summary prints the token sum and `tokens_unknown_sessions` as a lower-bound note; `readGateProcessLedger` returns `read` / `absent` / `unreadable`, so a refused or dangling-symlink ledger is no longer silent; the orphan-scan trigger reads an unresolvable project dir as `disabled`.
+- **B5 date-bomb scanner** (`scripts/lib/validate/check-test-value-bans.mjs`, #1499): all-caps clock constants (`NOW`, `FIXED_NOW`, `NOW_MS` …) count as clock names; only `setSystemTime(<date>)` or `useFakeTimers({ now: <date> })` freeze the date (a bare `useFakeTimers()` does not); a real-clock name bound at collection time is no longer exempted by a freeze. Corpus: 0 findings in 722 files before and after.
+- **`cursor-install` prunes dead plugin links** (`scripts/cursor-install.mjs`, #1501): a `.cursor/{rules,commands,skills}` entry is removed only when it is a dangling symlink resolving inside the plugin's own `.cursor/<kind>/`; a broken link is reported as dangling instead of "symlink exists".
+- **The commitlint job survives force-pushed branches and says how to repair main** (`.gitlab-ci.yml`, #1477, #1502): a non-default-branch push whose before-sha is gone lints from the merge-base with the default branch (fail-closed); a red default-branch run prints the revert remedy; the squash-title step names why a title is not linted. `docs/ci-setup.md` documents the owner settings (`suggestion_commit_message` template, `squash_option: never`) and the cancelled-pipeline ceiling.
+- **Test fakes are no longer freshly written executables** (`tests/_helpers/executable-fixture.mjs` `installScriptCli`, `tests/fixtures/bin/node-script-launcher`, #1497): macOS's first-launch check flaked the suite under load (fresh node-shebang fake median 207 ms vs 34 ms).
+
+### Deprecated
+
+- **`findScopeFile()`** (`scripts/lib/scope-gate.mjs`, re-exported by `scripts/lib/hardening.mjs`): it returns the first `wave-scope.json` without checking whose it is, which is the #1504 item 6 defect. No production caller is left; use `findOwnScopeFile()`. Kept for one minor cycle (`.claude/rules/development.md` § Package Lifecycle).
+
+### Removed
+
+- **`/session-orchestrator:navigator` skill and command** (#1491, owner decision): the 5.4.0 package shipped fleet internals (a private host alias, internal references, calls to a CLI other users do not have). `skills/_shared/fleet-protocol.md` remains as a generic file contract; `scripts/fleet-checkin.mjs`, `scripts/lib/fleet-protocol.mjs` and the SessionStart navigator banner stay. **Not a breaking change (owner decision 2026-10-02):** a skill or slash command is not an API export under `.claude/rules/development.md` § Package Lifecycle, and this command only worked with a private CLI that other users do not have — so it ships in a minor release without a migration guide.
+- **The v1 session-lock fallback** (`scripts/lib/session-lock.mjs`, harness-audit category 4, #595; sunset target was 2026-08-25): a lock without `last_heartbeat` is still visible but never live: `acquire()` reports it as `stale-heartbeat` and the SessionStart bootstrap reclaims it. Measured 2026-10-02: 8 of 8 locks and 10 of 10 registry entries on the measuring host carry the field.
+- **The pre-#1404 staging-fence fallback** (`hooks/wave-scope-commit-guard.mjs`, #1487 item 16): its own revisit trigger named 5.4.0. The only fence writer, `hooks/pre-bash-staging-fence.mjs`, has written `paths` + `command_hash` and never `command` since 5.3.0, and no other hook or bridge writes fence files; an entry without `paths` is now skipped.
+
+### Fixed
+
+- **vault-mirror no longer overwrites another project's notes on a slug collision** (`scripts/vault-mirror.mjs`, `scripts/lib/vault-mirror/`, #1503): a run started from another repo's checkout took the namespace from the cwd and overwrote three tracked notes of a different project. The namespace now follows the `--source` ledger (see Added; a monorepo package keeps its own namespace via the `<X>/.orchestrator/metrics/` convention), and an existing note whose `source-record` is not a key of the writing ledger is `skipped-foreign-owner` — which also stops a different-id session note from being overwritten and reported as `created`. A re-learned learning goes to the `<slug>-<uuid8>` disambiguation instead of freezing, and a note that still leaks a secret is healed over the guard.
+- **Only one session wins a stale-lock takeover** (`scripts/lib/session-lock.mjs`, `hooks/_lib/lock-bootstrap.mjs`, #1494): `forceAcquire({ onlyIfNotLive })` moves the old lock to a unique tombstone and replaces it via create-or-fail, so two SessionStarts can no longer both believe they hold it; the winner keeps its enrichment through a racer's window. A `last_heartbeat` more than 5 minutes in the future is not live (mirrored in harness-audit category 4); an unreadable lock path is reported (`reason: 'unreadable'`, stderr WARN, `read_anomaly`); the `active` result carries `ageHours`.
+- **vault-backfill and archive-closed-prds honour the vault-integration off switch** (#1496): neither writes into a vault while `vault-integration` is off (env `SO_VAULT_INTEGRATION`, `owner.yaml` or committed config) — an explicit `vault-backfill --vault-dir` still wins, as the run's own request; `gitlab-groups: "null"` is the group name in block and inline form alike; scheme-less strings containing `://` are redacted in logs.
+- **A valid JSON line that is not an object no longer becomes an empty learning** (`scripts/lib/learnings/io.mjs`, #1500): `null`, numbers, arrays and strings count as malformed and are kept verbatim.
+- **Scope bookkeeping false alarms** (#1493, #1027): `scope-echo --verify` no longer reports `injection-missing` for `coordinator.json`, `agent_count` excludes it, and `post-bash-write-verify` no longer calls `<state-dir>/filescopes/` writes violations. In a session launched from a repo subdirectory the hook rebases porcelain paths onto the session root, and a `../` path is never in scope or a "peer write".
+- **A prune no longer archives learnings appended after the snapshot** (#1486). `--prune --entries --apply` compares the store generation inside the store lock and refuses on drift (exit 3, the current token is not printed); applying a sidecar to a different store, a sidecar without a header, and a `--snapshot` onto the store or archive (also via a symlinked directory or a different letter case) all exit 1. A store with unparseable lines is snapshotted with a WARN (the lines are kept verbatim on every rewrite). The Cursor `/evolve` rule had not been migrated and is now.
+- **The Agent-dispatch guard keys its state on the repository the dispatch runs in** (`hooks/pre-task-scope-disjoint.mjs`, #1489): ledger, lock, wave key and events follow the git toplevel of the payload cwd, then the nearest `.git` ancestor, then `$CLAUDE_PROJECT_DIR` — after a `cd` into a subdirectory its records had landed in `<root>/sub/.orchestrator/`. All its subprocess calls share one 1500 ms budget (one hanging call had killed the hook and lost the verdict; an exhausted budget allows and records why); a stale-base deny is recorded as `deny-stale-base`, with the value it replaces in `collision_result`.
+- **A pruned events history no longer reads as "never"** (`scripts/lib/events.mjs`, #1401, #1489): every reader of the rotated ledger declares its retention window (census over `scripts/`, `hooks/`, `skills/`), `scanEventsBackwards` reports gaps from a rotation record on any line, and maintenance-due answers *undeterminable*.
+- **The orphan reaper's gate process ledger refuses FIFOs and symlinks** (`scripts/lib/process-group.mjs`, #1489): a FIFO planted at the ledger path no longer hangs the gate, and an inode replaced mid-append is reported as unlinked, not as a hard link.
+- **Unparseable learnings-store lines survive every rewrite** (`scripts/lib/learnings/`, #1489 item 4): the expiry sweep, the prune and `export-hw-learnings` (which deleted them) write them back verbatim — `rewriteLearnings` keeps the store's own malformed lines by default — and count them as `malformed: N` (also on `orchestrator.learnings.sweep_applied`). `apply-session-learnings --apply` no longer exits 2 on such a store (it blocked the learnings write on every `/close` of that repo); it WARNs with line numbers and proceeds. A record appended after a torn last line is readable, and whitespace-only or CRLF blank lines no longer count as malformed.
+- **A corrupt `.orchestrator/session.lock` no longer blocks every new session** (`scripts/lib/session-lock.mjs`, `hooks/_lib/lock-bootstrap.mjs`): `acquire()` reports it as `corrupt` and the SessionStart bootstrap reclaims it with one stderr WARN; an absent or unreadable lock keeps the conservative `active`. The lock reaper, the autopilot stall sampler and the vault board no longer show `started_at` as a heartbeat. `buildLock` always writes the lock shape (`mode` falls back to `unknown`, a non-positive or non-numeric `ttl_hours` to 4), so a lock from a caller passing `mode: undefined` is never mistaken for a corrupt one. Two SessionStarts forcing the same stale or corrupt lock no longer stamp one session's label and owner proof onto the other's lock.
+- **The session-start probe runner never rejects on a throwing probe** (`scripts/lib/session-start-probes.mjs`): a throwing `severityOf`/`render` or an unprintable thrown value records the probe as `error` (`severity-threw` / `render-threw` / `probe-threw-unprintable`) instead of losing every banner line and the `orchestrator.probes.completed` record of that start; a throwing telemetry read drops only `measure`.
+- **pseudonym-map warnings no longer print the home directory or map content** (`scripts/lib/vault-mirror/pseudonym-map.mjs`, #1490): V8's JSON parse error quoted the map's content.
+- **Vault and home paths in logs show as `~`, and `ssh://` logins are redacted like the scp form** (`scripts/lib/vault-mirror.mjs`, `auto-commit.mjs`, `archive-closed-prds.mjs`, the `/close` metrics diagnostics, `export-hw-learnings` errors and the learnings-store WARN, #1490, #1487 items 9–10).
+- **B5 reads clock bindings and fake timers from the shared setup** (`scripts/lib/validate/check-test-value-bans.mjs`, #1489 item 16): a module-level `const now = Date.now()` passed as control is caught, a `setSystemTime` in `beforeEach` no longer raises a false finding. A setup fake timer exempts only the blocks of its own or an enclosing `describe`, and only installers (`useFakeTimers`, `setSystemTime`) count.
+- **The ci-status banner resolves its SHAs inside the probe budget** (`scripts/lib/session-start-probes.mjs`, #1396); the renderer no longer spawns git.
+- **Orphan reaper file safety** (`scripts/lib/orphan-reaper/`, `scripts/lib/tail-window.mjs`, #1487 items 5–7): the audit append refuses symlinks and hard links; the reader opens with `O_NOFOLLOW|O_NONBLOCK` (a planted FIFO no longer hangs scan children) and is capped at 1 MiB; the throttle marker is read without following symlinks, a future mtime fails toward a scan, and a symlinked marker is replaced by a regular file on the next stamp (tmp + rename) instead of switching the throttle off for good (#1489 item 9); the false-alarm window reads N decisions, not N lines.
+- **Vault logs no longer print absolute vault paths or scp login users** (`scripts/lib/vault-mirror/process.mjs`, `scripts/lib/named-vault-resolver.mjs`, #1487 items 9–10), including bracketed IPv6 remotes; the vault-relative helper matches the root by whole path segment.
+- **B5 no longer counts a real-clock value as clock control** (`scripts/lib/validate/check-test-value-bans.mjs`, #1487 item 8).
+- **The vault learnings backfill checks and appends under the store lock** (`scripts/backfill-learnings-from-vault.mjs`, #1487 item 12); bootstrap Step 3b ignores the lock artefacts in consumer repos (#1487 item 11).
+- **`codex-install.mjs` failed with `ENOBUFS` on hosts with several Codex marketplaces** — `codex plugin list --available --json` returned 2.56 MB against `spawnSync`'s 1 MiB default (measured 2026-10-02); the buffer is now 64 MiB.
+- **Claude Code skipped the plugin's dependency install** — Claude Code 2.1.287 refuses to install dependencies for a package that sets `overrides` and reports it only as `noteDetails: dependencies-refused`, leaving the 5.4.0 cache without `node_modules` (hooks still ran; skill scripts and the MCP server did not). The `overrides` block (vite, fast-uri, brace-expansion) is removed: without it npm resolves the same or newer versions and `npm audit` reports 0 vulnerabilities, full and `--omit=dev` (measured 2026-10-02); the lockfile is unchanged. `docs/install.md` § Upgrade documents the check and the manual fallback.
+- **A peer session's wave manifest no longer switches this session's scope guards off** (`scripts/lib/scope-gate.mjs`, #1504 item 6): the guards took the first `wave-scope.json` in harness order (`.pi` > `.cursor` > `.codex` > `.claude`); when that one belonged to another session, `enforce-scope`, `enforce-commands`, `post-bash-write-verify` and `wave-scope-commit-guard` stood down and never read this session's own `.claude` manifest. `findOwnScopeFile()` checks ownership per candidate and skips only a provably foreign one; unbound, corrupt or unidentifiable manifests still decide. The wave-number readers (`post-edit-validate`, `post-tool-batch-wave-signal`, `pre-bash-memory-propose-audit`, `on-stop`, `run-quality-gate`) use it too, and so does the dispatch-ledger key of `pre-task-scope-disjoint` — a peer's manifest no longer supplies this session's wave number, splits its in-flight dispatch records, or toggles `gates.post-edit-validate`.
+- **Wave readers, the staging fence and the orphan reaper resolve the session root** (`hooks/`, `scripts/lib/platform.mjs`, #1504 items 4 and 8, #1492 item 2): they used the launch dir while the scope guards use the session root, so a worktree session read its wave and reaped in the wrong tree. The fence is written at the git toplevel of the hook's cwd, where the commit guard reads it. The launch-dir clamp compares native realpaths, so a lowercase `/users/…` spelling on APFS no longer skips it. A nested repo or entered worktree that hides an active wave manifest records `orchestrator.scope.manifest_hidden_by_session_root` once per wave (#1504 item 3; the write is still allowed).
+- **`blockedCommands` carries only command patterns** (`scripts/lib/blocked-commands-policy.mjs`, `skills/wave-executor/references/wave-loop-scope-manifest.md`, #1509): the manifest recipe copied every block rule, including the typed `redirect-truncate` rules (pattern `>`) and the `path-delete` label, so `enforce-commands` denied redirects inside `bash -c`/`sh -c`/`eval` payloads. `blockedCommandPatterns()` keeps only untyped rules; the destructive guard still enforces the typed ones.
+- **Scope entries compare and grant in one spelling** (`scripts/lib/scope-gate.mjs`, `scripts/validate-wave-scope.mjs`, #1026 items 3–5): `./x`, `a//b` and `a/./b` collide with `x`/`a/b` in the disjointness check, the `allowedPaths` union is written in that canonical spelling (a `./x` entry used to be unmatchable, so the agent's own write was denied), and a schema-invalid manifest no longer hides a collision report.
+- **A future-stamped registry entry or lock is never "young"** (`scripts/lib/session-registry.mjs`, `scripts/lib/lock-reaper.mjs`, #1505 items 1–2): it counted as a fresh peer forever, was never swept, and the reaper emitted a negative `age_hours`. Beyond the shared 5-minute tolerance the age is unmeasurable (`null`, never fresh); where an age only decides deletion, the file's mtime decides.
+- **Lock leftovers of a killed reclaim are swept** (`scripts/lib/session-lock.mjs`, #1505 item 3): `acquire()` removes `.session.lock.tmp.*`, `.session.lock.create.tmp.*` and `.session.lock.reclaim.*` files older than one hour (regular files only; a reclaim tombstone only when it is not a live lock).
+- **The close backfill no longer treats an unreadable events archive as a clean scan** (`scripts/lib/session-close-backfill.mjs`, #1505 item 5): such a candidate is deferred as `skipped-history-unread`.
+- **`run-migrate-v2-cross-repo` exits 2 on read/write errors** as its help documents (#1487 item 15).
+- **vault-mirror checks the generator marker on every write path** (`scripts/lib/vault-mirror/process.mjs`, #1506 item 3): the disambiguation branch overwrote a note another generator owned.
+- **`export-hw-learnings` honours the vault-integration off switch** for its default output (#1506 item 4); `apply-session-learnings` resolves symlinks before pinning its write event to the repo.
+- **The vault staleness probes expand `~`** (`skills/discovery/probes/vault-staleness.mjs`, `vault-narrative-staleness.mjs`): the committed `~/Projects/vault` resolved to `<cwd>/~/…` and reported a false all-clear. `ssot-code-diff` counts all 27 slash commands (`commands/*.md` + user-invocable skills) instead of 2.
+- **commitlint in CI accepts merge and revert headers only from real merges and reverts** (`commitlint.ci.config.mjs`, `.gitlab-ci.yml`, #1507 item 1): an ordinary commit titled `Merge branch …` or `Revert "…"` skipped every rule. The job lints `--no-merges` and `--merges` in two passes; a revert needs git's or GitLab's `This reverts …` body line.
+- **Docs match the code**: the memory-proposal quota is per wave, shared by all agents of that wave (#1027); `docs/ci-setup.md` records the GitLab settings `squash_option: never` and the conventional `suggestion_commit_message` applied 2026-10-03 (#1507 item 5); the evolve docs name the `--drop-malformed` repair.
+
+## [5.4.0] - 2026-10-02
+
+### Added
+
+- **One lock for every in-process `learnings.jsonl` read-modify-write** (`scripts/lib/learnings/io.mjs` `withLearningsLock()`, #1447 item 8). `appendLearning`, `rewriteLearnings`, the expiry sweep and prune, `apply-session-learnings --apply`, `export-hw-learnings --promote` and `run-migrate-v2-cross-repo --apply` (a locked repo is reported and left unwritten, exit 2) run their whole read-to-write inside `<store>.lock` (over `withFileLock`, reentrant per async call chain only). Before, an append landing between a rewriter's read and its rename was lost; on a 10 s lock timeout nothing is written now and the CLIs exit non-zero naming the lock file. The lock and rewrite temp files are gitignored in this repo. Not covered: the `/evolve --prune --entries` sidecar is built by the agent before the prune runs, so a record appended in between is still archived as `pruned` (#1486).
+- **Per-model token breakdown for mixed-model subagents** (`hooks/subagent-telemetry.mjs`, `scripts/lib/subagents-schema.mjs`, #1470). A subagent record whose billable turns span two or more models carries `models_usage` (the four buckets per model); `rollupSessionTokens()` prices it part by part instead of leaving it unpriced.
+- **`cost_records_priced` / `cost_records_total` reach `sessions.jsonl`** (#1475 variant B) as optional, validated fields, so the share of a session the cost covers is visible in the ledger.
+- **`describeOriginForLog()`** (`scripts/lib/named-vault-resolver.mjs`, #1479 item 4): one formatter the three vault writers use for the origin in their refusal line — a local origin prints as `file://<local path>`, a remote one with credentials redacted.
+- **Fleet protocol v1 — files instead of messages** (#1462, Epic #1461, PRD !53 S1). New reference `skills/_shared/fleet-protocol.md` (no rule, nothing under `.claude/rules/`) and the schema library `scripts/lib/fleet-protocol.mjs` — the only place that knows the `~/.config/navigator/` layout (override `NAVIGATOR_CONFIG_DIR`, the navigator-CLI's own variable), the file modes 0600/0700, the check-in fields, `CHECKIN_FALLBACK_MIN = 10` and lease validity: `readNavigatorLease()` returns exactly `active` \| `none` (missing or expired) \| `unreadable` (broken JSON, missing fields) and is fail-closed — an unreadable or expired lease is never "aktiv". `isSafeSessionId()` guards every path built from a session id (no `/`, `..`, NUL). Review hardening before merge: a lease whose `session_id`/`adresse` carries control bytes, whose `plattform` is unknown or whose timestamps lack the `Z` is `unreadable` (a `Z`-less value would be read in local time and could extend the lease west of UTC); `repo` must be a name, `kandidaten` issue numbers only — both travel in the event, which may leave the host over the optional webhook.
+- **Fleet check-in: session-start Phase 7.6, operations-contract peer preflight, CLI and event** (#1462). `scripts/fleet-checkin.mjs` reads the check-in JSON from stdin, stamps `zeit` (`date -u +%FT%TZ` form), validates, writes `checkin/<session_id>.json` atomically with mode 0600 (directories 0700) and emits `orchestrator.fleet.checkin` (payload `session`, `repo`, `modus`, `kandidaten`, `navigator_state`; catalogued in `docs/events-schema.md`); exit 0 written, 2 invalid input (error list on stderr, no file), 1 write error. The new Phase 7.6 in `skills/session-start/SKILL.md` (+6 lines / +1 038 B against the +12 / +1 200 B ceiling) and one sentence in `references/operations-contract.md` (+4 lines / +318 B against +4 / +400 B) place the check-in before the first writing action; a hint to the navigator is optional and never awaited (CSM-004); after 10 min without `auflagen/<session_id>.json` the reference's Standard-Auflagen apply. Test isolation: `tests/setup/navigator-dir-guard.mjs` points `NAVIGATOR_CONFIG_DIR` at a tmp dir per vitest worker, so no test reads or writes the operator's real directory.
+- **Registry field `role`** (#1462). `heartbeat(sessionId, { role })` in `scripts/lib/session-registry.mjs` accepts `'navigator'` or `null`, throws `TypeError` on anything else before touching the file, and the patch-less call `heartbeat(id)` (`hooks/on-stop.mjs`) preserves the field; `_validEntry` drops an entry whose `role` is neither `null` nor a string. Display only, never ownership — the navigator lease stays authoritative (`skills/_shared/state-ownership.md`). `registerSelf()` does not set it and `classifyMode` is untouched; this change ships no production writer (the `/navigator` skill is a later cut).
+- **Navigator banner line** (#1462). `hooks/on-session-start.mjs` appends exactly one line after the peer lines, on every harness that runs the hook: `🧭 Navigator aktiv: <adresse ?? session_id>, Check-in nach ~/.config/navigator/checkin/`, `🧭 Navigator: keiner nachweisbar (keine gültige Lease)` or `🧭 Navigator: Lease unlesbar, Status nicht nachweisbar` — never more than 120 bytes UTF-8 (a long label is cut, measured with a 128-character `adresse`; a 200-character id is refused by the lease reader and renders the "unlesbar" line), never blocking. 🧭 joins the curated emoji set in `scripts/lib/validate/check-unicode-safety.mjs`.
+- **Skill `navigator` — the fleet-coordinator persona as a user-invocable skill** (#1462 B5, Epic #1461). `skills/navigator/SKILL.md` (`/session-orchestrator:navigator ticker|status|start|fenster|handover`, `disable-model-invocation: true` because a coordinator role runs only on operator command; description 344 bytes against the ≤ 400 B ceiling of PRD 4.5) describes what the navigator measures, writes and refrains from: it grants no approvals („Freigaben erteile ich keine, maßgeblich ist dein Owner-Auftrag"), writes `auflagen/<session_id>.json` only through `auflagenPath()` after `isSafeSessionId()`, treats a merge "Zeichen" as its own measurement (MR opened + mergeable, head = pipeline = gate SHA, job list, main free, file overlap), starts headless runs only behind a slot gate and a busy gate, carries the verbatim foreground wait pattern, the offload path rule (worktree path, the configured offload alias only), the Codex rules, the account watch and the AI-budget rule, and sets `role: 'navigator'` via `heartbeat()` per ticker round — the first production writer of that registry field. Lease acquisition, renewal and handover stay S4 (tracked in the navigator repository): the skill writes no lease, so the session-start banner keeps reporting "keiner nachweisbar" until S4 lands. Schemas are not repeated; `skills/_shared/fleet-protocol.md` stays the single reference (its obsolete `path-check: planned` marker for the PRD is removed and it now links the skill). Generated mirrors under `.agents/`, `.codex-plugin/`, `.cursor/` and `pi/`; README and `docs/components.md` counts move to 52 skills / 28 slash commands / 26 user-invocable skills.
+- **`skills/navigator/references/` — pure decision functions plus measurement-only shell wrappers** (#1462 B5). `fleet-decisions.mjs` exports `slotDecision` (free-memory bands 4 / 3 / 0 runs at ≥ 50 % / ≥ 35 % / below, load1 > 40 closes everything, an unreadable value yields cap 0), `busyDecision` (a Codex rollout for this checkout younger than 30 min or a `session.lock` younger than 6 h means busy; missing counts mean busy) and `chooseAccount` (usable = 5h < 97 % and 7d < 97 %, earliest 7-day reset within 3 days first, far accounts by consumption, 1 800 s tie tolerance, a row without data is never usable), all fail-closed, none reading the environment, with a stdin-JSON CLI (`slot|busy|account`, exit 0 allowed / 1 refused / 2 bad input). `slot-check.sh` and `account-check.sh` only measure (`memory_pressure`, `vm.loadavg`, `pgrep` anchored on the `timeout -k 60` wrapper because one Codex run spawns three matching processes, `find -mmin`, the operator's `NAVIGATOR_ACCOUNT_CMD`) and hand the numbers to the module; `account-check.sh` prints the decision only, never the account rows (SEC-008), and `--apply` merely shows the switch command because a switch affects every session on the host. Tests: `tests/skills/navigator/fleet-decisions.test.mjs` (24 cases, each naming its bug, every rule probed red before its fix, including that no account alias ever reaches the wrapper's output).
+- **Session Config `offload-first` — placement before pressure** (#1465, navigator decision E4). New boolean key, default `false`; `false` or absent changes nothing. With `true`, `applyOffloadDecision()` in `scripts/lib/wave-resource-gate.mjs` fires on a `proceed` verdict too, not only on `reduce` / `coordinator-direct`: an offloadable role goes to the first declared `remote-hosts` entry whose `roles-allowed` carries it and that is witnessed ready, still under the HR-004 heavy-repo cap. The offloadable table (`OFFLOADABLE_WAVE_ROLES`: `quality`/`test` → `test`, `ui`, `perf`) is not extended — build, lint and audit ride on the Quality wave's `test` role. The gate still never probes the network, so the witness (`remoteReady` or `probeFn`) is mandatory for the switch to act. A wave that stays local names why: `offload-first: no ready host for '<role>' — staying local`, or `offload-first: true but no remote-hosts declared — staying local`; `validateSessionConfig()` adds the warn-level cross-field finding `offload-first-cross-field` for the second case and never flips `ok`. Named limits: `resource-awareness: false` stays a full opt-out (no probe, no cap, no placement); the `probe failed (ignored)` path does place, since placement needs no measurement; the key is committed-only — no env or `owner.yaml` precedence, because `resolveDispatcherAutonomy` is enum-specific and `owner.yaml` freezes its sections, so reuse would need a schema change.
+
+- **`hooks/pre-edit-sessions-ledger-guard.mjs` — the sessions ledger is guarded on the Edit/Write lane too** (#1443 item 4). A PreToolUse hook on `Edit|Write|MultiEdit` (Claude Code; mirrored on Cursor and Pi, Codex recorded as a documented asymmetry in `check-hooks-symmetry.mjs`) denies a write whose `file_path` ends in `.orchestrator/metrics/sessions.jsonl` (or a rotated `sessions.jsonl.<N>`) and points at `scripts/emit-session.mjs --entry` / `scripts/check-sessions-integrity.mjs`. Every other input allows — malformed stdin, missing fields, unknown tool name, an internal error, a payload over 1 MB — so a broken hook can never block foreign edits; only the ledger path is fail-closed. Named limits in the header: the tracked fixture `tests/fixtures/harness-audit/clean-repo/.orchestrator/metrics/sessions.jsonl` is denied too (override `SO_DISABLED_HOOKS=pre-edit-sessions-ledger-guard`), the match is case-insensitive. Allow-path latency, median of 20 runs: 31.9 ms direct, 36.3 ms through `run-node.sh` (Node startup is 25.5 ms of it). **Live sessions pick the hook up only after the live checkout pulls this change.**
+- **Skill `test-audit` — gate, audit and prune tests under written evidence** (`skills/test-audit/`). `/test-audit [gate|audit|campaign] [scope] [--goal "<goal>"]` applies one value bar at three depths: a four-question write gate before any new test is written, a focused audit of one scope, and a lane-based campaign (phases P1–P9 in `references/campaign.md`). Audit and campaign open with a stated goal — default: remove at least 20 % of the least useful tests measured in test lines, total coverage within 2 percentage points of M0, no production file below its own M0 coverage — that never licenses an unproven deletion: every test declaration in scope gets one ledger mark (R/F/C/D/N/B/O), and every consolidate, delete or repair needs eight written evidence fields plus a targeted production mutation the keeper catches, restored byte for byte. Test lines count only for files the runner actually includes. `references/mutate.sh` runs a mutation manifest after a green control run, counts a mutation as caught only when the run fails AND prints a red summary, aborts on a restore mismatch (exit 3) and logs `EXTERN:<lane>` rows as cross-lane references instead of running them. Coverage thresholds, runner config, CI, snapshot updates, new dependencies and product-bug fixes stay owner decisions. Inspired by openclaw/openclaw `.agents/skills/test-audit` (MIT), rewritten for this plugin.
+
+### Changed
+
+- **The orphan reaper is six modules behind a stable entry** (`scripts/lib/orphan-reaper/`, #1437). `scripts/lib/orphan-reaper.mjs` (1588 → 316 lines) re-exports the same 21 names and keeps the CLI; the hooks import only `scan-throttle.mjs`. The audit is read through a bounded, growing tail window and pruned past 1 MiB to its newest 512 KiB; `DEFAULT_KILL_GRACE_MS` now lives in `process-group.mjs` (still re-exported from `dispatch-common.mjs`).
+- **tests:src ratio counts TypeScript and co-located tests** (`scripts/lib/tests-src-ratio.mjs`, #1451, envelope `tests-src-ratio/2`). `.ts/.tsx/.mts/.cts/.jsx` count, declaration files do not; the test side is `tests/` plus `*.test.*`/`*.spec.*` anywhere plus `__tests__/`. A TypeScript repo now gets a real number (navigator: 1.2847) instead of "not measurable". This repo moves 1.4006 → 1.4007 at the same tree.
+- **B5 proves a clock seam only from a named clock key** (`scripts/lib/validate/check-test-value-bans.mjs`, #1478): `SEAM_CLOCK_ARG` for pass 1, the wide `CONTROL_CLOCK_ARG` for pass 2; seamed pairs 192 → 172, B5 findings unchanged at 0.
+- **The offload threshold has one source** (`skills/_shared/fleet-protocol.md`, `skills/navigator/SKILL.md`, #1482): the navigator CLI's offload check and its exit contract replace the prose numbers (< 12, `last_max`).
+- **Dependency overrides:** `brace-expansion` ^5.0.12 (two high advisories in 5.0.9, #1481) and `fast-uri` ^3.1.8 (moderate GHSA-hrr3-gc8f-f4qj); `npm audit` reports 0 vulnerabilities.
+- **`vault-mirror`'s refusal path has a subprocess test for its ledger record** (#1450 follow-up 4). `tests/unit/vault-mirror.test.mjs` spawns the CLI against a vault without a git origin and pins exit 2, the stderr refusal, exactly one `orchestrator.vault.mirror_run_completed` record with `aborted: 'vault-not-canonical'` and `total: 0`, and an untouched vault directory. The exit/stderr half was already covered by `tests/scripts/vault-mirror-entry-point.test.mjs`; the ledger record and the no-write assertion were not.
+- **`board-writer.mjs` names the `vault-dirs:` cwd-match tier in its `hostPaths` JSDoc** (#1450 follow-up 2). The last precedence twin without the tier now matches `narrative-mirror.mjs`. Comment text only.
+- **Vault-dir precedence comments name the `vault-dirs:` cwd-match tier** (#1450 item 2, remaining sites). `scripts/lib/vault-status/narrative-mirror.mjs` and `tests/unit/vault-mirror.test.mjs` no longer describe the chain as `SO_VAULT_DIR > owner.yaml paths.vault-dir > committed`; the three files the issue named already carried the tier. Comment text only.
+- **The Codex entrypoints close-evidence handover is linked** (#1439 item 3). `docs/handover/2026-09-19-codex-session-entrypoints.md` now points at `2026-09-19-codex-session-entrypoints-close.md`, which no tracked file referenced before.
+- **`OPTIONAL_FIELDS` declares the four session-record fields that were written but never listed** (`scripts/lib/session-schema/constants.mjs`, #1457 item 7). `total_tokens` and `matched_records` (the #1436 rollup, shape-checked by the validator), `raw_session_id` (`scripts/emit-session.mjs`, `scripts/lib/session-close-backfill.mjs`) and `_repair_source` (`scripts/lib/session-record-repair.mjs`) join the list; no runtime consumer reads it, so nothing changes in validation.
+- **Test consolidation** (#1457 item 5, #1459 item 8). `tests/lib/autopilot/flags.test.mjs` drops the `--max-tokens` case that no mutation of `flags.mjs` could turn red (non-numeric input: default = min = 0) and the absent-flag case the empty-argv `toEqual` already pins, and asserts the bounds as literals so the behavioural cases catch a wrong constant on their own instead of only through the `FLAG_BOUNDS` pin; `tests/_helpers/markdown-fences.mjs` replaces the two private fenced-block parsers in the evolve-recipe and sweep-expired-learnings tests with one line-based, indentation-tolerant helper.
+- **`wave-executor-state-init.md` names the third reader of `session-start-ref`** (#1457 item 11): `scripts/lib/scope-baseline.mjs` diffs `<ref>..HEAD` in the coordinator's checkout, so the worktree-base edge does not apply there and the init-time edge only under-counts.
+- **`shellQuote` lives in one module** (`scripts/lib/sh-quote.mjs`, #1438). Five former copies — `scripts/cursor-install.mjs`, `scripts/lib/tmux-layout/layouts.mjs`, `scripts/lib/tmux-layout/tmux-shell.mjs`, `scripts/run-quality-gate.mjs` and an inline copy in `scripts/vault-integration-watcher.mjs` — now import it. New round-trip test `tests/lib/sh-quote.test.mjs` runs each quoted value through `sh -c 'printf %s …'` and expects it back byte-identical.
+- **Validator messages name `claude-opus-5-5` as the full-model-ID example** (#1459 item 4). `scripts/lib/agent-frontmatter.mjs`, `scripts/lib/config/persona-gate-wave.mjs`, `scripts/lib/persona-panel/catalog-loader.mjs`, `scripts/lib/validate/check-agents.mjs` and `docs/session-config-reference.md` replace the `claude-opus-4-7` example; `claude-opus-4-7` stays a valid input.
+- **`prompt-caching` is no longer vendored into `cli-tool` repos** (#1449). `rules/_index.md` drops the `cli-tool` archetype from `opt-in-domain/prompt-caching.md`: CLI repos without an Anthropic client received a 15k-character rule they can never apply; repos of the `nextjs-saas`, `express-service`, `docker-service` or `monorepo-oss` archetypes still get it; a `cli-tool` repo that does use the SDK no longer does, because a repo carries exactly one archetype (`bootstrap.lock`).
+
+### Fixed
+
+- **Each subagent counts once in the session token and cost totals** (`scripts/lib/session-token-rollup.mjs`). The telemetry hook records the RUNNING total of an agent's whole transcript at every stop, so a resumed agent (e.g. continued via SendMessage) was summed once per stop. The rollup now keeps one record per `agent_id`: the last stop that found its transcript decides pricing, the last token-bearing one the token sums (they differ only for a transcript over the hook's 50 MiB read limit, which stays an unpriced candidate). **Series break:** measured over the fleet's local ledgers, 209 of 1,533 sessions change, output tokens fall to a median 0.88× (min 0.27×), costs to a median 0.83×; sessions without a resumed agent are unchanged. Historical `sessions.jsonl` values are not rewritten.
+- **A partial session cost is no longer persisted as if complete** (`scripts/lib/session-token-rollup.mjs`, #1475 variant A). `total_cost_usd` is omitted whenever `cost_records_priced < cost_records_total` — an unknown or missing model, a found transcript without tokens, or a started agent whose transcript was never found (unless the same agent was priced from another stop). Phantom stops without a start record still never count.
+- **A killed quality-gate run is recorded as `failed` in every variant** (`scripts/run-quality-gate.mjs`, #1459). The reporting variants exit 0 by design, so a run whose command the per-command timeout killed used to emit `orchestrator.quality_gate.passed`.
+- **The autopilot stops on a backfill-stub iteration instead of counting it as 0 tokens** (`scripts/autopilot.mjs`, `scripts/lib/sessions-canonical.mjs` `isBackfillStub`, #1457 F2), and `emit-session` no longer takes a compact/resume re-emit as the session start ref (#1457 item 3).
+- **Ledger prunes rewrite atomically and refuse symlinks** (`pruneReaperAudit`, `pruneGateProcessLedger`, `touchScanMarker`): a tmp file renamed over the target behind an `lstat` regular-file check; a symlinked audit can no longer truncate the file it points to.
+- **The release regeneration moves `site/sitemap.xml` `lastmod`** (`scripts/site-numbers.mjs`, #1484): `lastmod := max(lastmod, page counted-at)`, never backwards; `--check` reports a stale `lastmod`.
+- **The vault writers' refusal lines print no local paths** (#1479 items 4–6): origin via `describeOriginForLog()`, no `vaultDir`/source path in the `vault-mirror` refusal and not-found lines (the per-note SKIP lines in `scripts/lib/vault-mirror/process.mjs` still do, #1487), one `owner.yaml` load order, `SO_CONFIG_HOME` pinned in the entry-point test.
+- **Learnings schema** (#1447 items 2, 10b, 1, 3a): strict validation type-checks `file_paths` with one shared predicate (`isRepoRelativePathEntry`) that `memory-propose --file-paths` and `validateProposalRecord` now use too, so an approved proposal can no longer fail at write time; migration strips `./` and moves array-typed path scopes into `file_paths` (scope words such as `project`/`repo` stay scopes); a missing baseline template or rule source is reported as `invalid-contract` / `invalid-rule-projection` instead of `unsafe-source`.
+- **The narrative mirror refuses a non-canonical vault** (#1450 follow-up 1). `scripts/lib/vault-status/narrative-mirror.mjs` now runs the shared `checkCanonicalVault()` after the vault dir is resolved and before any slug lookup or write — the same guard the board writer and `vault-mirror` apply. A vault whose git origin is missing or does not end in a canonical suffix yields the new action `skipped-vault-not-canonical` (catalogued in `docs/events-schema.md`), nothing is written and one stderr line names the expected suffixes; `VAULT_MIRROR_SKIP_CANONICAL_CHECK=1` still bypasses it. The host context is loaded once and shared between the Session Config parse and the guard.
+- **The board writer loads `owner.yaml` once per write** (#1450 follow-up 3). `mirrorBoardInner` resolved the host context twice — once inside `parseSessionConfig`, once for the canonical guard. `loadOwnerConfig()` has no cache and its section-drop warnings are not rate-limited, so a broken `owner.yaml` section printed every warning twice per board write. One `hostCtx` now feeds both; a regression test counts the warning lines.
+- **`VAULT_MIRROR_SKIP_CANONICAL_CHECK=1` no longer prints `vaults:` warnings** (#1450 follow-up 5). `checkCanonicalVault()` evaluates the skip switch before resolving canonical suffixes, so a skipped check neither parses `owner.yaml` `vaults:` nor emits its WARN lines; the skip result carries `expected: []`, which no caller reads on the `ok` path.
+- **`emitEvent` never writes relative to the working directory** (#1468). `scripts/lib/events.mjs` refuses an `opts.repoRoot` that is not an absolute path (empty string included) with one stderr WARN and no write, no directory, no webhook — previously `path.join` plus `mkdir -p` created `undefined/repo/.orchestrator/metrics/events.jsonl` under the cwd when an unset variable was concatenated into the root. An explicit `opts.filePath` is untouched, and `eventsFilePath()` keeps its return shape for readers. The four CLI entry points that forwarded an unresolved `--repo-root` (`release-session-lock.mjs`, `backfill-abandoned-sessions.mjs`, `wave-scope-binding.mjs`, `sweep-expired-rules.mjs`) now `path.resolve()` it at the parse site. `scripts/sweep-expired-learnings.mjs --repo-root` and an explicit root passed to `resolveRepoRoot()` in `scripts/lib/quality-gate.mjs` are resolved the same way, so a relative value there is no longer a silent telemetry drop.
+- **The vault-status board writer refuses a non-canonical vault** (`scripts/lib/vault-status/board-writer.mjs`, #1450 item 1). `mirrorBoard()`/`sweepBoard()` now run the same canonical-vault guard `scripts/vault-mirror.mjs` has had since #600: when the resolved `vault-dir`'s git origin does not end in a canonical Meta-Vault suffix (or has no origin at all), the call returns `skipped-vault-not-canonical`, writes nothing, takes no lock — dry-run included — and prints one stderr line. The check itself is now ONE shared helper, `checkCanonicalVault()` + `normalizeRemote()` in `scripts/lib/named-vault-resolver.mjs`, and `vault-mirror.mjs` calls that helper instead of its private copy, so the two writers cannot drift apart again. Tests inject the origin reader through the existing `hostPaths` seam (`readOriginUrl`); the existing `VAULT_MIRROR_SKIP_CANONICAL_CHECK=1` switch is honoured from the injected env. The third writer, `narrative-mirror.mjs`, is closed by follow-up 1 below.
+- **vault-mirror counts a collapsed duplicate session line instead of skipping it silently** (`scripts/vault-mirror.mjs`, #1291). The `--kind session` dedup pass gives a losing same-`session_id` line its own action, `skipped-duplicate-session`, through the ordinary per-entry path (stdout line, `orchestrator.vault.mirror_completed` record with `record_id` and `line`, no `path` — no target file exists for it), so `created + updated + skipped + failed === total` holds for session runs too. Both schema rows in `docs/events-schema.md` describe the new action; the #1186c ceiling test pins the invariant for both kinds.
+- **Only a harness-written carrier record can finish a running agent in the liveness index** (`hooks/pre-task-scope-disjoint.mjs`, #1459 item 2 rest, security LOW, pre-existing). `buildTranscriptIndex()` matched `task-notification` on the raw transcript line, so a complete forged block placed first in a `tool_result` (a `Read` of a fixture), in assistant text or in a typed prompt marked a still-running agent's tool-use id as finished and turned a scope-collision DENY into an ALLOW. `notificationCarrierText()` now accepts exactly the three record forms the harness writes (`user` with `origin.kind: 'task-notification'`, optionally behind the system-notification preamble; `queue-operation` enqueue/remove; `queued_command` with `commandMode: 'task-notification'`), and `finishedNotificationIds()` requires the text to begin with the opener and the head to follow the harness tag order. Measured over 11,005 local transcript files: 0 genuine carrier ids stop being finished; the 20 lines the old code additionally accepted were all quotes. A remaining false-DENY for multi-notification preamble carriers is #1467.
+- **Guards that were silently wrong** (#1455, #1451 fail-closed part, #1458 a+b, #1453, #1456, #1457 items 1–2). `hooks/pre-task-scope-disjoint.mjs`: `buildTranscriptIndex()` now treats every TERMINAL task-notification status (`completed|failed|killed|stopped`, census over local transcripts 2026-09-25) as finishing its tool-use-id, not only `completed` — a 429'd agent that notified `failed` and was resumed via `SendMessage` completed under the SendMessage's NEW id, so its dispatch never finished and the next wave was denied permanently (#1455; the resumed run itself is still unindexed — a false-ALLOW window, follow-up). `scripts/lib/tests-src-ratio.mjs`: 0 counted test files next to tracked test-like files (`*.test.ts`, `__tests__/`, anything under `tests/`) now yields `ratio: null`, `withinCorridor: null`, `reason: 'no-tests-found'`, `--check` exits 3, and the session-start probe WARNs "nicht messbar" instead of reading a TypeScript repo as green; `CODE_EXTENSIONS` is unchanged — whether TS tests COUNT is an open owner decision (#1451). `scripts/check-package-manager.mjs`: new advisory `checkHuskyHooksPath()` warns once, with `npx husky`, when `.husky/` exists but `core.hooksPath` is unset — `.npmrc` `ignore-scripts=true` skips the `prepare` script in every fresh clone, so commitlint, the owner-leakage scan and the pre-push gate were silently inactive there; never mutates, never changes the exit code, silent under CI; README names the step (#1458; the CI commitlint job is parked). `skills/evolve/references/evolve-analyze-mode.md`: the `/evolve analyze` sidecar moved from `.orchestrator/metrics/.learnings-next.jsonl` to `.orchestrator/tmp/learnings-next.jsonl`, outside the `ledger-delete-protected` denylist; a new test feeds the recipe with `$NEXT` spelled out through the real destructive guard (the literal `"$NEXT"` form was never blocked — the guard does not expand variables — so the collision only bit when an agent wrote the path out) (#1453). `persona-panel` presets, `templates/personas/*`, the `persona-gate-wave.dispatch-model` default and their docs use the alias `opus` instead of the stale pin `claude-opus-4-7`; two ID-shape examples in error messages are kept (#1456). `gate-full` publishes each command's inner kill ladder and `run-quality-gate.mjs` OR-joins it with the outer one into `orchestrator.quality_gate.*` via `joinGateKillFields()` — when the inner side was not measured and the outer did not fire the three keys are now OMITTED rather than written as `false/0/[]` (baseline/incremental/per-file publish it since the entry below, #1459 item 3); `emit-session.mjs` WARNs about a missing `session_start_ref` also without an own UUID and names what STATE.md contributed (#1457 items 1–2). Every behaviour change carries a test that is red on `0efb3e97`.
+
+- **The sessions ledger is honest again: reader, writer, repair and token rollup** (#1443, #1442, #1436, #1439 items 1–2, #1440 C1/C2/C4). `canonicalizeSessions` no longer lets a later backfill stub (0 waves, `_backfill_source`) hide a real record with the same `session_id`, merges a stub and a real record that share a `raw_session_id` onto the real one, and treats repair provenance (`repair-invalid-sessions/*`) as real (fleet check 30 ledgers / 3135 records: 7 winner changes, all stub→real). `orchestrator.session.started` carries `head_sha`; the STATE.md template gains `session-start-ref`; `emit-session.mjs` falls back to the own event's `head_sha`, drops a short ref with a WARN (53 fleet records carry 7/8-char refs, so the validator does NOT enforce the format), stamps `raw_session_id` and runs `rollupSessionTokens` mechanically (new `total_tokens` = input + output) for the own UUID only — the prose step in `session-metrics-write.md` is gone, `readTailSession()` returns `usage`, so the autopilot `token-budget-exceeded` kill-switch fires again (wiring test through the real path). `validateSession` type-checks `total_tokens` and `matched_records`. `repair-invalid-sessions`: new class `timestamp_precision` truncates sub-millisecond timestamps (deliberately NOT listed in `_backfill_incomplete_fields`, which would discard the value downstream); post-verification now means "no worsening and every repaired line valid" — an unrepairable remainder is kept byte-identical and reported, exit 4 distinguishes it from a rollback (exit 3); the Bash ledger guard's deny text for repair variants names the one allowed command and says an in-command `SO_DISABLED_HOOKS=` prefix has no effect. `orchestrator.memory.propose_invoked` writes `cwd` project-relative or as `sha256:<12 hex>` (also when the project dir is `/`, home or an ancestor of home — pseudonymisation, not anonymisation), never an absolute path. `orchestrator.quality_gate.{passed,failed}` carry `timed_out`, `survivors`, `kill_signals` on both emitters (`failed_files` documented). `run-quality-gate.mjs` sits behind an `isMainModule` guard. The `over_delivery_ratio` / `planned_files_count` prose chain (0 of 173 waves ever carried it, no code wrote or read it) is removed instead of implemented; the two tests pinning it are deleted. `release.mjs` polls the registry 12 × 15 s instead of 5 × 3 s. Review fixes before merge: the token enrichment validates the enriched record first and, on a validation error, WARNs and appends the record WITHOUT the token fields (enrichment is never the reason the ledger gains no line); `repair-invalid-sessions` keeps an existing `_backfill_source` origin and records the repair in the additive `_repair_source` field, so a repaired zero-work stub stays a stub; a missing `session_start_ref` is WARNed; the `session.started` fallback takes the FIRST own event (its `head_sha` or nothing). **Autopilot `--max-tokens` now defaults to `0` (off):** with `readTailSession()` reporting `usage`, the dormant 500 000 default would have stopped autopilot after about one deep session (measured 450 499 subagent output tokens for one session, HR-101); the unit is cumulative subagent OUTPUT tokens, coordinator tokens are not counted. The reaper PRD now says an over-budget hook latency warns, it does not skip the scan.
+
+- **`vault-dir` gains a per-directory tier, and a host can switch `vault-integration` off locally** (`scripts/lib/config/host-paths.mjs`, `scripts/lib/config.mjs`, `scripts/lib/owner-yaml.mjs`, `scripts/lib/named-baseline-resolver.mjs`, agents/vault#319, #1448). A single host-wide `owner.yaml` `paths.vault-dir` silently overrode every repo on the host, so a repo whose own vault lives elsewhere wrote its session closes into the wrong vault. `vault-dir` now resolves `SO_VAULT_DIR` > `owner.yaml` `vault-dirs:` cwd path-prefix match > `paths.vault-dir` > committed, through one helper (`resolveVaultDir`) for both the `vault-integration` and the `vault-sync` block, and the winning tier is exposed as `vault-integration.vault-dir-source` (`env|match|owner|committed`). The match tier reuses the #819 resolver, now parameterised by `section`/`envKey` (`name` stays required for `baselines:` only). The host switch `resolveVaultIntegrationHost` reads env `SO_VAULT_INTEGRATION=off|warn|strict` > `owner.yaml` `vault-integration: { enabled: false | mode: … }` > committed and may only LOWER the committed level, never enable or raise it; `vault-integration.host-override` names the tier that lowered it (`env:SO_VAULT_INTEGRATION` / `owner.yaml`, else `null`). An invalid `owner.yaml` `vault-integration:` section is dropped on its own via `droppedSections`; `vault-dirs:` is a lenient list section like `baselines:`. Session-end step 5 and the `/evolve` mirror step print `vault-mirror: bewusst aus auf diesem Host (<tier>)` instead of hitting `vault-mirror.mjs`'s exit 2 on a host without a vault, and log `vault-dir=<path> (Quelle: <source>)` when they do mirror. `claude-md-drift-check` still reads the raw committed values. A leading `~` in the two owner.yaml tiers (`vault-dirs[].path`, `paths.vault-dir`) is now expanded, and `scripts/vault-mirror.mjs` expands its `--vault-dir` at entry: before, a `~/…` value reached `existsSync(resolve(…))` as `<cwd>/~/…` and the mirror aborted with exit 2 `missing-vault-dir`. The #1244 whole-file discard (an invalid REQUIRED owner.yaml section) now keeps `vault-dirs:` raw alongside `paths:`, so an unrelated `tone:` typo no longer sends a repo under a declared prefix back into the host-wide vault. The test setup clears `SO_VAULT_INTEGRATION` (`tests/setup/scrub-session-env.mjs`), so an operator's exported switch cannot flip fixtures that assert the committed mode.
+- **A configured baseline without its exporter is reported as `producer-missing`, not `unsafe-source`** (`scripts/lib/baseline-archetypes.mjs`, #1445, GH#73). `baselineSourcePath()` maps a missing `scripts/archetype-manifest.mjs` to `producer-missing` only when `lstat` on that path itself throws `ENOENT`; symlinks (dangling or not), symlinked parent directories, paths escaping the baseline, wrong file types and every other error stay `unsafe-source`. Contract-error results gain an additive, path-free `message` field; for `producer-missing` it names the missing exporter and points to `docs/baseline.md` § How bootstrap finds it. Exit code stays 2, and `scripts/baseline-archetypes.mjs --help` names the reason. The bootstrap docs (`skills/bootstrap/public-fallback.md`, `SKILL.md`, `private-contract.md`, `references/bootstrap-retroactive-flow.md`, `docs/baseline.md`) describe the two ways forward — migrate the baseline or unset the configured path — as the user's choice, never a silent downgrade to public.
+- **Session-end learnings writes go through a validating CLI, and the migration repairs broken consumer records** (#1446, GH#69). `migrateLegacyLearning()` (`scripts/lib/learnings/schema.mjs`) coerces a path-like `scope` into `file_paths` plus `scope: private`, `scope: project|repo` to `private`, and `schema_version: "1"` / `2` to `1` — on the migration path only; the read funnel stays pass-through. `scripts/run-migrate-v2-cross-repo.mjs` reports invalid-record counts per validation error class before and after migration (`errorClassesPre` / `errorClassesPost`). The new `scripts/apply-session-learnings.mjs` (dry-run by default, `--apply` to write; strict `validateLearning()`, one invalid record writes nothing; passive decay from `learning-decay-rate`; emits `orchestrator.learnings.session_write_applied` only when an `--apply` run actually wrote the store — never on a dry run, never when nothing was written) replaces the shell `>` rewrite in `skills/session-end/learning-patterns.md` and `skills/plan/mode-retro.md`. `.cursor/rules/060-evolve.mdc` is not routed to that CLI: it now writes through the `/evolve` prune helper `scripts/sweep-expired-learnings.mjs --prune`, passing `--repo-root "$(pwd)"` like the canonical `skills/evolve/references/evolve-analyze-mode.md` so the helper records `orchestrator.evolve.completed`. All three learning templates now carry `scope` and `file_paths`. The sweep CLI's `--prune --entries` path strictly validates every sidecar record whose `id` is not yet in the store and exits 1 without writing when one is invalid. New blocking validator `scripts/lib/validate/check-learnings-shell-writes.mjs` rejects instruction prose that writes `learnings.jsonl` with `>`, `>>` or `tee`; a backticked operator counts when the store name sits within ±3 lines, a prohibition exempts a line only when its keyword precedes the operator, and Markdown blockquotes are ignored. The dead reference `GitLab #386` in the schema module now reads `EventDrop #386`; fixture `tests/fixtures/learnings-invalid-golden.jsonl` added.
+- **The `baseline`, `incremental` and `per-file` gate variants publish the per-command kill ladder** (`scripts/lib/gates/gate-{baseline,incremental,per-file}.mjs`, #1459 item 3, #1457 item 12). `typecheck` and `test` in their JSON envelope are now objects `{ status, timed_out, kill_signals, survivors }` like `gate-full`'s; a skipped command carries `{ status: 'skip' }` only. `joinGateKillFields()` can therefore join the inner ladder for these variants too, so their `orchestrator.quality_gate.*` events carry `timed_out`/`kill_signals`/`survivors` instead of omitting them. Envelope change: these keys were bare status strings before. `skills/quality-gates/SKILL.md` already documented the object form for baseline and per-file; the incremental schema is updated.
+- **A quoted `<tool-use-id>` no longer finishes a running agent** (`hooks/pre-task-scope-disjoint.mjs`, #1459 item 2, security LOW). `buildTranscriptIndex()` read every id on a notification line, so an id merely QUOTED inside another notification's `<result>`/`<summary>` counted as finished. Now only the line's FIRST `<task-notification>` block is read, and only its head before `<summary>`/`<result>`: the first `<tool-use-id>` counts, only when the first `<status>` is terminal and `</task-notification>` follows (fail-closed: the deny stays). Named ceiling: several DIFFERENT real notifications in one line report only the first — measured 0 times in this repo's transcripts.
+- **Three doc corrections** (#1451, #1457). `skills/session-start/references/phase-4-ssot-environment-check.md` describes the `checkTestsSrcRatio` "nicht messbar" warn (`reason: 'no-tests-found'`, `ratio: null`) and the `reason?` result field; the `skills/autopilot/SKILL.md` pseudocode checks `max-tokens > 0` before comparing, matching `kill-switches.mjs` (default `0` = off); `hooks/pre-bash-memory-propose-audit.mjs` and `docs/events-schema.md` no longer call `events.jsonl` tracked — it is gitignored here (`.gitignore:57`), consumer repos may track it.
+- **Vendored rules load path-scoped again: frontmatter on line 1, `paths:` beside `globs:`** (#1449). Claude Code reads a rule's `paths:` only when the frontmatter opens on line 1. The 17 library rules under `rules/` began with the provenance comment before `---`, and the 7 path-scoped ones carried only `globs:`, so every consumer loaded them always-on on every turn. The 7 rules with frontmatter (`backend`, `backend-data`, `frontend`, `swift`, `security-web`, `prompt-caching`, `bash-harness-pitfalls`) now open with `---`, carry a `paths:` list identical to `globs:` and the provenance comment directly after the closing `---`; bodies are byte-identical, the 10 rules without frontmatter are unchanged. The tooling now measures what Claude Code loads: `scripts/lib/rule-loader.mjs` reads a block only from line 1 and reports a displaced block as `defect: 'frontmatter-not-at-top'` (export `FRONTMATTER_NOT_AT_TOP`) with `globs: null`; `scripts/lib/instruction-budget-guard.mjs` counts such rules always-on and returns `defects[]` plus a banner line naming the files; `claude-md-drift-check` Check 9 drops its own header tolerance and reports the loader signal as an error. `scripts/lib/validate-vendored-rules.mjs` replaces the `paths-frontmatter` probe with `frontmatter-not-at-top` and `globs-paths-mismatch` (both errors; list comparison order-insensitive) and accepts the provenance header on line 1 (rule without frontmatter) or on the first line after the closing `---`; `scripts/lib/rules-sync.mjs` detects plugin ownership via the new `isPluginOwnedContent()` at both positions, so old-format copies stay plugin-owned and are lifted to the new format on the next sync instead of being frozen as local overrides. `docs/rule-authoring.md` documents the contract.
+- **`ci-audit-job` reports an `include:`-supplied audit as unverifiable, not missing** (`scripts/lib/project-hygiene.mjs`, #1460). When `.gitlab-ci.yml` has no local audit step but declares `include:` (component/local/project/remote/template), `checkCiConfig()` cannot see the included jobs; the finding is now `fixable: false` with "CI dependency-audit step could not be verified: N include(s) not evaluated" instead of a `fixable: true` missing-audit finding. Without `include:` nothing changes, and a local audit job still wins.
+- **Autopilot loads Session Config from a plugin path with spaces or non-ASCII characters** (`scripts/autopilot.mjs`, #1440). `loadConfig()` built the `parse-config.mjs` path from `new URL(...).pathname`, which keeps percent-encoding, so under such a path the config load failed and autopilot ran on defaults; it now uses `fileURLToPath()`. The Bash ledger guard's deny text additionally names the read-only check `scripts/check-sessions-integrity.mjs --session-id` to run after the writer succeeds.
+- **The `semgrep` CI job gets an empty entrypoint and a source directory** (`.gitlab-ci.yml`). The job now sets `image.entrypoint: [""]` and `SEMGREP_SRC_DIRECTORY: $CI_PROJECT_DIR`, as the `gitleaks` job already did for its entrypoint (infrastructure/projects-baseline#550).
+- **This repo's four project hooks read their input from stdin** (`.claude/settings.json`, contributor-facing). The destructive-command guard, the formatter, the `.env.example` reminder and the co-located-test hint read `$CLAUDE_TOOL_INPUT`, a variable Claude Code never sets, so none of them ever fired; they now parse the hook JSON from stdin (`.tool_input.command` / `.tool_input.file_path`) and answer with `hookSpecificOutput.permissionDecision`. The destructive-command guard is fail-closed: without `jq` on the PATH it denies every Bash call with an install hint instead of validating nothing (infrastructure/projects-baseline#501).
+
 ## [5.3.0] - 2026-09-22
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.5.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 
 **Give your agents a working rhythm.**
@@ -39,6 +39,8 @@ You need **Node.js 24 or later**, a git repository, and one of the four agents b
 | **Cursor IDE** | `git clone` the repo, `npm install`, then `node scripts/cursor-install.mjs /path/to/your/project` ([guide](docs/cursor-setup.md)). |
 | **Pi** | `pi install npm:session-orchestrator` ([guide](docs/pi-setup.md)). |
 
+After a clone-based install (Codex CLI, Cursor IDE, or contributing), run `npx husky` once: `.npmrc` sets `ignore-scripts=true` (SEC-020), which skips the `prepare` script that would otherwise activate the git hooks.
+
 ## Quick Start
 
 **1. Run `/bootstrap` once in your project.** It creates the minimum structure and writes `.orchestrator/bootstrap.lock`. `/session` refuses to start until that file exists.
@@ -93,7 +95,7 @@ When you type `/session feature`:
 .claude/STATE.md                    # wave progress and deviations (harness-specific directory)
 ```
 
-The plugin is **50 skills, 26 slash commands, 14 typed subagents and 27 hook files across 10 event types**. A slash command is a skill whose frontmatter says `user-invocable: true` (24 of them) or one of the two remaining `commands/*.md` files (`/session`, `/templates-ack`) — one definition per name, so nothing is listed twice in the `/` picker. Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in `scripts/lib/*.mjs` and `hooks/*.mjs`. There is no build step and no compiled artifact — when a session does something you did not expect, you can open the file that decided it. Full inventory: [`docs/components.md`](docs/components.md).
+The plugin is **51 skills, 27 slash commands, 14 typed subagents and 29 hook files across 10 event types**. A slash command is a skill whose frontmatter says `user-invocable: true` (25 of them) or one of the two remaining `commands/*.md` files (`/session`, `/templates-ack`) — one definition per name, so nothing is listed twice in the `/` picker. Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in `scripts/lib/*.mjs` and `hooks/*.mjs`. There is no build step and no compiled artifact — when a session does something you did not expect, you can open the file that decided it. Full inventory: [`docs/components.md`](docs/components.md).
 
 ## Why it is built this way
 
@@ -101,7 +103,7 @@ The plugin is **50 skills, 26 slash commands, 14 typed subagents and 27 hook fil
 - **Checks run between waves, not only at the end.** A mistake caught after wave 2 costs one wave. The same mistake found at `/close` has already been copied into every wave after it. Findings below the configured confidence threshold are not shown to you.
 - **A crash does not lose the session.** `STATE.md` records which wave finished and what deviated from the plan. The next `/session` offers to continue from the last completed wave.
 - **Two sessions in one working copy is treated as a real risk.** Two people, or two of your own sessions, in the same checkout share one git index, one filesystem and one `STATE.md`, and neither can see the other's uncommitted work. A heartbeat session lock, per-agent file-scope manifests, and the PSA rules in [`.claude/rules/parallel-sessions.md`](https://github.com/Kanevry/session-orchestrator/blob/main/.claude/rules/parallel-sessions.md) exist for exactly that case.
-- **Guards run where the harness supports them, and the table below says where it does not.** A destructive-command policy — 11 rules block, 4 warn — and file-scope enforcement run as real hooks on Claude Code, as bridges on Cursor and Pi, and as instructions only on Codex. Details: [`docs/components.md`](docs/components.md#other-surfaces).
+- **Guards run where the harness supports them, and the table below says where it does not.** A destructive-command policy — 12 rules block, 4 warn — and file-scope enforcement run as real hooks on Claude Code, as bridges on Cursor and Pi, and as instructions only on Codex. Details: [`docs/components.md`](docs/components.md#other-surfaces).
 - **What it learns is opt-in and readable.** Every session appends a record. After 5 or more sessions, `/evolve analyze` proposes patterns with a confidence score; you read them and delete the ones you disagree with. Nothing is applied without you.
 - **GitLab and GitHub, both fully.** It detects which one your remote points at and drives issues and merge/pull requests for either.
 
@@ -111,7 +113,7 @@ How this compares to other orchestrators, with measured results kept separate fr
 
 | Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
 |---|---|---|---|---|
-| All 26 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | Native `.cursor/commands` slash commands | Prompt templates |
+| All 27 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | Native `.cursor/commands` slash commands | Prompt templates |
 | Parallel agents | Agent tool | Multi-agent roles | Sequential only | Sequential (parallel planned) |
 | Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | `.pi/STATE.md` |
 | Scope enforcement | Active PreToolUse hook; blocking in `strict`, reporting in `warn` | Instructions only; no compatible `apply_patch` handler | `preToolUse` + `beforeShellExecution` bridge; scope blocking requires `strict`; `afterFileEdit` is post-hoc | `tool_call` bridge; scope blocking requires `strict` |
@@ -121,14 +123,16 @@ How this compares to other orchestrators, with measured results kept separate fr
 
 All four platforms share the same skills, commands and scripts; only the hooks differ, because each harness fires different events. Codex leaves its `PreToolUse` handlers empty because these guards do not yet match its tool names and edit payloads ([why](docs/codex-setup.md#why-our-pretooluse-guards-stay-unwired--the-reason-corrected)). Cursor and Pi have known event-coverage limits — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
 
-## Recent highlights (v5.3.0)
+## Recent highlights (v5.5.0)
 
-Highlights of the v5.3.0 line:
+Highlights of the v5.5.0 line:
 
-- **Gate commands die as a group now.** Both quality-gate paths start every command in its own process group and, on timeout, signal the whole group — SIGTERM, a grace period, then SIGKILL — instead of just the shell. The previously uncapped path B carries a 900 s ceiling and reports exit 124. Root cause was measured on 2026-09-20: four orphaned `tsgo --noEmit` processes at up to 8 GB each froze the host after a plain shell kill left them at PPID 1 (#1425, #1427, #1428).
-- **An orphan watchdog, shipped off.** `scripts/lib/orphan-reaper.mjs` decides purely (own ancestry register ∧ PPID 1 ∧ age ∧ read-only allowlist ∧ identity re-checked before every signal) and runs detached from two hooks, throttled to one scan per 30 s. `reaper.enabled` defaults to `false` and `mode` to `report`; arming `kill` waits for a measured false-alarm rate (ADR-0015, HR-107).
-- **Ledgers stop lying by omission.** `readEventsWithRotations` answers `complete: true | false | null`, a hand-placed archive is a notice rather than a gap, and the session-start probe plus the abandoned-session backfill read across rotations. `worktree_base_checked` records every worktree dispatch, including why it could not measure (#1423, #1414, #1424).
-- **Codex entrypoints aligned** (MR !40, #1391): the `session` command reaches the portable `.agents/` surface, modes are parsed independently of the free text that follows, and `go`/`close` stay explicit-only on every generated surface.
+- **Scope guards hold in worktrees, subdirectory launches and beside peer sessions.** The guards read the session's own working copy, find this session's own `wave-scope.json` even when a peer session's manifest ranks higher, and the wave readers, staging fence and orphan reaper follow the same session root. `blockedCommands` carries only command patterns, so redirects inside `bash -c` payloads are no longer denied (#1492, #1493, #1504, #1509).
+- **Session locks are taken over by exactly one session.** A stale or corrupt lock is reclaimed through a tombstone, a future-stamped lock or registry entry never counts as young, and leftovers of a killed reclaim are swept (#1494, #1505).
+- **vault-mirror never overwrites a note it does not own.** The namespace follows the mirrored ledger, a note of another project or generator is skipped, and the vault writers honour the `vault-integration` off switch (#1496, #1503, #1506).
+- **The learnings store keeps every line.** Unparseable lines survive each rewrite, `sweep-expired-learnings --drop-malformed` removes one on purpose, and a prune snapshots first and refuses on drift (#1486, #1489, #1500).
+- **Conventional commits on every path to `main`.** CI lints each commit range and the squash title, and accepts merge or revert headers only from real merges and reverts (#1477, #1502, #1507).
+- **`npm run update:local` updates every local install**, and Claude Code installs the plugin's dependencies again (the `overrides` block it refused is gone). The `/session-orchestrator:navigator` skill left the package; the fleet file contract stays (#1491).
 
 Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
 

package/docs/agent-authoring.md

@@ -49,7 +49,7 @@ Agent files live in `agents/` as Markdown with YAML frontmatter. Required fields
 ---
 name: kebab-case-name                # 3-50 chars, lowercase + hyphens only
 description: Use this agent when [conditions]. <example>Context: ... user: "..." assistant: "..." <commentary>Why this agent is appropriate</commentary></example>
-model: inherit                        # inherit | sonnet | opus | haiku | fable — OR full ID like claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-sonnet-5, claude-fable-5
+model: inherit                        # inherit | sonnet | opus | haiku | fable — OR full ID like claude-opus-5-5, claude-sonnet-4-6, claude-haiku-4-5-20251001, claude-sonnet-5, claude-fable-5
 color: blue                           # blue | cyan | green | yellow | purple | orange | pink | red | magenta
 tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (both accepted; we prefer comma-string for consistency)
 ---
@@ -76,7 +76,7 @@ tools: Read, Grep, Glob, Bash         # comma-separated string OR JSON array (bo
 - **`sonnet`** — an explicit cost cap, NOT a default. Pin it only when an agent must stay on the workhorse tier even in an Opus session, and state the reason inline. A bare `sonnet` on a working agent silently overrides the operator's session model — the failure mode that moved the implementation and review catalog to `inherit`.
 - **`inherit`** — **the default for the working catalog.** Lets the coordinator/session's active model tier flow through, so the agent runs at whatever tier the operator picked (an Opus session gives its implementers AND its reviewers Opus-quality judgment). Use it for implementation, test-writing, and review agents alike — `code-implementer`, `test-writer`, `security-reviewer`, `session-reviewer`, `db-specialist`, `ui-developer`, and the read-only analysis agents. Diverge only for a named cost/quality reason.
 - **`opus`** — reserve for agents whose task genuinely needs the strongest available reasoning (e.g. `ux-evaluator`) and where the cost is justified because the agent runs rarely (dispatched solo, not fanned out across a wave).
-- **Full model-ID pinning** (`claude-opus-4-7`, `claude-sonnet-5`, `claude-fable-5-20260101`, …) — only when the agent has a demonstrated dependency on a SPECIFIC model version, e.g. a reproducibility requirement that needs a dated snapshot, or a known behavioral regression on newer models for this agent's exact prompt. Pinning trades away automatic model-family upgrades — document the reason inline as a frontmatter comment when you do this.
+- **Full model-ID pinning** (`claude-opus-5-5`, `claude-sonnet-5`, `claude-fable-5-20260101`, …) — only when the agent has a demonstrated dependency on a SPECIFIC model version, e.g. a reproducibility requirement that needs a dated snapshot, or a known behavioral regression on newer models for this agent's exact prompt. Pinning trades away automatic model-family upgrades — document the reason inline as a frontmatter comment when you do this.
 
 **Resolution order** (highest precedence first): `CLAUDE_CODE_SUBAGENT_MODEL` environment variable → the invocation-time model parameter (if the dispatcher passes one explicitly) → the agent's own frontmatter `model:` value. An agent's `model:` is therefore a default, not a guarantee — a session or environment override can supersede it.
 

package/docs/baseline.md

@@ -39,7 +39,16 @@ resolvers. Their diagnostics are contained in a bounded local process so paths
 and private match names cannot leak through the bootstrap CLI. An absent or
 missing directory keeps the public fallback. An existing directory with a
 missing producer, unsupported schema, invalid metadata or unsafe source is an
-explicit error; bootstrap does not silently switch to a public default.
+explicit error; bootstrap does not silently switch to a public default. A
+directory without the `scripts/archetype-manifest.mjs` exporter is reported as <!-- path-check: example -->
+`producer-missing`, with a path-free `message` naming that file. A source the
+exporter declares but the baseline does not contain is an incomplete baseline, not
+a refusal: a missing archetype template directory (`templatePath`) is reported as
+`invalid-contract`, a missing rule file the `rules` projection lists as
+`invalid-rule-projection`. `unsafe-source` stays reserved for symlinks (dangling or
+not), path escapes, wrong file types and any other lookup failure. The two ways
+forward are the user's choice: migrate the baseline to the exporter contract
+below, or unset the configured path so the public fallback applies.
 
 The local producer is the baseline's `archetype-manifest.mjs export` CLI. Its reduced v1
 JSON owns IDs, ordering, declarative detection signals, runtimes, package

package/docs/ci-setup.md

@@ -419,6 +419,143 @@ The trade-off that buys is registry availability — a registry outage fails thi
 job, and therefore the pipeline, without any code being wrong. Retry the job;
 do not make it `allow_failure`, which would restore the silent hole.
 
+## `commitlint` job (#1458)
+
+Runs `commitlint` over the commits a pipeline introduces, with the CI-only rule
+set `commitlint.ci.config.mjs` (= `commitlint.config.mjs`, Conventional Commits
+with `header-max-length 120`, plus stricter ignores). CI is needed in addition to
+the husky `commit-msg` hook because the hook is inactive in a fresh clone until
+`npx husky` has run, absent for Codex / web edits, and skipped by `--no-verify`.
+
+- **Range** `<from>..$CI_COMMIT_SHA`, first match wins: `CI_MERGE_REQUEST_DIFF_BASE_SHA`
+  (MR pipelines), else `CI_COMMIT_BEFORE_SHA` (branch pipelines), else the first
+  parent of the pipeline commit (a new branch has an all-zero before-sha, so only
+  its tip is linted until its MR pipeline lints the whole range). The job logs
+  the range and the commits it lints.
+- **Force-pushed branch without an open MR (#1477 item 3, closed).** The old
+  before-sha is not in the fresh clone. On a branch other than
+  `$CI_DEFAULT_BRANCH` the job fetches `origin/$CI_DEFAULT_BRANCH` and lints from
+  the merge-base instead, and says so in the log. Only plain branch pipelines can
+  hit this: a branch with an open MR runs MR pipelines only, and `main` is
+  protected against force-push, so a missing base on `main` stays a red job.
+  The all-zero before-sha of a new branch deliberately keeps the tip-only range:
+  a branch created at `main`'s tip (GitLab UI, `git push origin main:x`) would
+  otherwise lint an empty range and go red.
+- **Fail-closed.** `commitlint --from X --to Y` exits 0 over an *empty* range
+  (measured 2026-09-29, `@commitlint/cli` 19.8.1), so the script itself fails
+  when the range is empty, its base is missing from the clone, or the fallback
+  cannot fetch `origin/$CI_DEFAULT_BRANCH` or find a merge-base. "Nothing was
+  checked" is never a pass.
+- **`GIT_DEPTH: "0"`.** The project default clone depth is 20, so the range base
+  can be absent from a shallow clone. `semgrep` uses the same setting for its
+  baseline commit.
+- **Stricter ignores in CI (#1477 item 4, closed).** commitlint's built-in default
+  ignores (`@commitlint/is-ignored` 19.8.1) skip far more than git's own merge and
+  revert messages: any message with a `Merge …` line *anywhere* (the pattern is
+  multiline, so one body line exempts the whole message), `revert <anything>`,
+  `Reapply <anything>`, `amend!`/`fixup!`/`squash!`, version headers (`v1.2.3`)
+  and `Merged …` / `Automatic merge…` / `Auto-merged … into …`. The CI config sets
+  `defaultIgnores: false` and accepts only first lines git or GitLab generate:
+  merges (`Merge branch 'x' into 'main'` from GitLab, and git's
+  `Merge branch 'main' into x`, `Merge remote-tracking branch 'origin/main' into x`,
+  `Merge branch 'main' of <remote>`), and `Revert "…"` / `Reapply "…"`. Both CI
+  call sites (range and squash title) pass `-g commitlint.ci.config.mjs`.
+  The first line alone does not prove git or GitLab wrote it (#1507 item 1): a
+  normal commit titled `Merge branch 'a' into b` or `Revert "x"` used to skip
+  every rule. So the job lints the range in two passes that together cover it
+  exactly: `--git-log-args=--no-merges` with `COMMITLINT_MERGE_COMMITS=0`, where
+  a merge-shaped subject is linted like any other, and `--git-log-args=--merges`
+  with `COMMITLINT_MERGE_COMMITS=1`, where git has counted two or more parents
+  and the merge shape is accepted. A hand-written message on a real merge is
+  still linted in the second pass. A revert or reapply shape is accepted only
+  with the body line git or GitLab writes under it: `This reverts commit <sha>`
+  (git, and GitLab's revert of a single commit) or `This reverts merge request
+  !<iid>` (GitLab's revert of a merged MR; taken from GitLab's source, not
+  measured on this instance). The squash-title call sets
+  `COMMITLINT_MERGE_COMMITS=0`: a squash commit has one parent, so a
+  merge-shaped or bare `Revert "…"` MR title fails. The
+  husky hook keeps the lenient defaults on purpose, so a local `git revert`,
+  `git commit --fixup` or `git pull` merge is not blocked mid-work; a `fixup!`
+  commit has to be autosquashed before its MR pipeline goes green.
+  History check (2026-10-02 @ `ff3e43b5`): the 200 most recent `main` commits
+  all pass the CI config (0 failures, as under the husky config). Over the full
+  history (1277 commits) it fails 10, 6 of which already failed under the old
+  config; the 4 new ones are hand-written merge subjects from 2026-04-30 to
+  2026-06-11 (e.g. `Merge branch 'x' (MR !21, …)`). The job only lints new
+  ranges, so old history cannot turn a pipeline red.
+- **MR title on a squash merge (#1477 item 1, closed).** A squash merge commits
+  the MR title (the project's squash commit template is unset, so GitLab uses
+  `%{title}`), which no linted range contains. When
+  `CI_MERGE_REQUEST_SQUASH_ON_MERGE` is `"true"` (GitLab renders
+  `squash_on_merge?`, so the project's `always`/`never` option is included),
+  the job also lints `CI_MERGE_REQUEST_TITLE`, after stripping GitLab's Draft
+  prefixes (`Draft:`, `[Draft]`, `(Draft)`, any case, repeated). An MR that will
+  not squash keeps a free-form title, because its commits are what lands. A red
+  title blocks the merge, since the project only merges with a green pipeline.
+  After fixing a title, run a new pipeline for the MR. When the title is not
+  linted the log says why (#1502): not a merge-request pipeline, the variable is
+  unset (GitLab did not provide it), or the MR does not squash.
+- **A non-conventional commit that reaches `main` (#1502).** Two cases slip past
+  every MR pipeline: the squash box ticked after the last pipeline (the variable
+  is fixed when the pipeline is created, and neither ticking squash nor editing
+  the title starts a new one), and a squash or merge commit message edited in
+  the merge dialog. `main` push pipelines run this job over `before-sha..sha`,
+  which contains the squash commit as the merge's second parent (measured
+  2026-10-02: job 152074, pipeline 16004, range `84c107a1..ff3e43b5`), so the
+  commit is caught after the fact. `main` cannot be force-pushed, so on the
+  default branch a red job prints the remedy: revert what landed via an MR
+  (`git revert -m 1 <sha>` for a merge commit, `git revert <from>..<sha>` for
+  directly pushed commits), then re-land the change from a new branch with a
+  conventional message (`git revert --no-commit <the revert commit>`, then
+  `git commit -m 'fix: …'`).
+  Closing these before the merge was an **owner decision** (project settings,
+  not changed by code):
+  - `squash_option: never` removes the squash case entirely. Cost: low,
+    measured 2026-10-02: 3 of 71 merged MRs were squashed, the newest on
+    2026-05-22. **Set by the owner on 2026-10-03** (was `default_off`;
+    verified via `glab api projects/:id` at 2026-10-03T06:47Z, #1507 item 5).
+    The title lint above stays as the guard should the setting ever change.
+  - A push rule (`commit_message_regex`) would reject an edited message at
+    merge time, but push rules are not available on this instance's tier
+    (the push-rule API answers 404).
+  A merge-commit message hand-edited in the dialog stays detectable only after
+  the fact, as above.
+- **Suggestion commits (#1477 item 2, owner setting, set).** With
+  `suggestion_commit_message` unset, GitLab commits "Apply 1 suggestion(s) to
+  1 file(s)", which fails `type-empty` / `subject-empty`. A template that passes
+  (measured exit 0 against the CI config, 2026-10-02):
+  `chore: Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)`.
+  **Set to exactly this template by the owner on 2026-10-03** (project setting
+  `suggestion_commit_message`, under the merge-request settings; verified via
+  `glab api projects/:id` at 2026-10-03T06:47Z, #1507 item 5). Keep
+  `%{file_paths}` out of it if it is ever edited: the template is the header,
+  and a few paths break `header-max-length 120`.
+- **Cancelled push pipelines (#1477 item 5, accepted ceiling).** An MR pipeline
+  re-lints the whole MR range on every push. A direct push is linted per push
+  only (`before-sha..sha`), and every job here is `interruptible` with
+  `auto_cancel_pending_pipelines` enabled, so a push pipeline auto-cancelled by
+  the next push could leave its commits unlinted if that happened before the
+  validate stage finished. Measured: of the last 100 `main` pipelines, 11 were
+  cancelled (7 with direct-push commits), and in all 11 every security and
+  validate job had already finished (2026-09-29); re-measured 0 of 11 affected
+  on 2026-10-02. No CI change: making the job non-interruptible on `main` would
+  stop auto-cancel for every merge and cost a full 30–40 minute pipeline each on
+  the constrained runner. Remedy if it recurs: lint `main` from the previous
+  successful `main` pipeline's SHA (needs a token that can read the pipeline
+  list) or from the last release tag, instead of the before-sha, which
+  re-covers a cancelled predecessor.
+  **Revisit trigger:** a non-conventional commit is found on `main` that no
+  pipeline linted because its pipeline was cancelled. Check with
+  `npx --no -- commitlint -g commitlint.ci.config.mjs --from <sha> --to origin/main`.
+
+  Two non-conforming commits reached `main` after `commitlint.config.mjs` was
+  added and before this job (`c99f57d9`, a 126-character header; `c5252e68`, a
+  `merge:` type). The same command from the commit that added this job shows
+  whether anything has slipped through since.
+- Hard-`needs`-ed by `pipeline-gate` and on the shared gate rules, so it runs on
+  every non-scheduled pipeline. Behavioural tests: `tests/ci/commitlint.test.mjs`
+  (they execute the committed script block against temp git repos).
+
 ## `pipeline-gate` — the fan-in job
 
 The last stage holds one job that depends on every blocking gate. It exists
@@ -443,10 +580,23 @@ nothing" are different failures:
    `allow_failure` job never blocks a dependent job, so `needs:` alone is blind
    to it.
 
-Coverage is required only on merge-request and default-branch pipelines (it is
-the slowest job at ~148s, and it re-runs a suite `test` has already run). On a
-plain branch pipeline `pipeline-gate` states that coverage was not measured —
-absent, but never silently absent.
+`coverage` runs only on the default branch (`main`). It is the most expensive
+job and re-runs a suite `test` has already run: across 14 MR pipelines
+(2026-09-27..29) it took 5.0 to 12.9 min, median 6.6 min, 29% of the MR job
+minutes (measured 2026-09-29 13:24 CEST). `pipeline-gate` requires
+`.ci-markers/coverage.ok` when `CI_COMMIT_BRANCH` is the default branch (push,
+web and api pipelines alike); on every MR and branch pipeline it prints
+`coverage: NOT MEASURED here` — absent, but never silently absent.
+
+Consequence: an MR no longer gets the thresholds (70/70/70/60, set in the
+vitest configuration) nor a second, instrumented full-suite run; both fire
+after the merge, so a coverage regression turns `main` red, not the MR. The
+MR page also loses its coverage percentage. The second run has caught things
+before: in the failed-job history (measured 2026-09-29, oldest 2026-05-11) 3 of
+14 failed `coverage` jobs were in MR pipelines, each with every `test` shard
+green. Revisit trigger: a `main` coverage failure whose MR pipeline was green,
+or a switch to measuring coverage inside the three `test` shards with
+`vitest --merge-reports`.
 
 ## Local pre-push gate