session-orchestrator 5.6.0 → 5.7.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
-    "version": "5.6.0"
+    "version": "5.7.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.6.0+codex.20261003103620",
+  "version": "5.7.0+codex.20261003172657",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "keywords": [
     "session",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer"

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.7.0] - 2026-10-03
+
+### Added
+
+- **`scripts/vault-mirror-prune.mjs`** (#1513): applies the vault-mirror retention rules to the existing `40-learnings/` and `50-sessions/` notes. Dry run by default with a JSON manifest (`--manifest`: path, reason, action, target, kept copy, rollup); `--apply` writes the month rollups, then moves archived notes to `90-archive/mirror/<zone>/<same path>` with `status: archived` + `archived-reason`, then renames alias-folder and flat notes into their namespace. Reasons: `duplicate`, `superseded`, `expired`, `metrics-only-session`, `namespace-alias`, `flat-relocate`. Only notes with the mirror's `_generator` marker are touched; nothing is deleted; a second run plans nothing.
+
+### Changed
+
+- **vault-mirror narrative gate for sessions** (#1513): `vault-mirror.quality.min-narrative-chars` now measures the record's free text (`notes`, `narrative`, `summary`) instead of the rendered body with its tables. A record below it gets no note but one row in `50-sessions/<repo>/_rollup-YYYY-MM.md` (action `skipped-metrics-only`; idempotent). `0` disables the gate.
+- **vault-mirror learnings lifecycle** (#1513): the pre-#725 slug variant of a note is updated in place instead of getting a hyphenated twin; a new note whose normalised insight already exists in the namespace is refused (`skipped-duplicate-insight`); an expired learning is never created (`skipped-expired`) and its existing note becomes `status: archived` + `archived-reason: expired`; `--kind learning` also reads the sibling `learnings-archive.jsonl` and marks the notes of archived records (`expired` / `superseded`). `backfill-learnings-from-vault.mjs` falls back to `90-archive/mirror/40-learnings/`.
+- **`session-close-backfill.log` carries events only** (#1513): `skipped-*` outcomes are no longer appended (86 % of the Meta-Vault's 723 KB log); they remain queryable as ledger events.
+- **`sweep-expired-rules` removes expired single-entry rule files** (#1513): a generated rule with one learning and no counter sentence was skipped as `no-counter-sentence` forever; it is now deleted (pair stamped first) once the later of its frontmatter `expires-at` and the learning's store date has passed.
+- **Commit guard names the manifest** (#1514): a parse error and each block header now carry the manifest path (`.claude/wave-scope.json` vs `pkg/.claude/wave-scope.json`), and the "To proceed" hint prints once when both manifests block.
+- **Read failures other than a missing file are reported** (#1216): `countProposalsForWave` and the transcript tail's `readAgentType` now warn on stderr instead of silently returning `0` / `unknown`.
+- **Lint rejects the deprecated locks shim and the deleted `OWNER_YAML_PATH`** (#1234): `no-restricted-imports` with the replacement named in the message.
+- **ADR-0002 verdict corrected to Stay** (#1053): native session↔session and agent→coordinator messaging (Claude Code 2.1.224) removed the one capability Agent Teams added; ADR-0003/0007/0010 and the rules point at the addendum. LM-002a separates Channels from cross-session messaging.
+
+### Fixed
+
+- **Drift-check Check 7 derives learning keys with the shared `learningKeyOf`** (#1021): a learning with a blank title or an untrimmed type no longer produces a key that differs from the one the rule emitter stamps.
+- Shared helpers instead of private copies: one `tombstoneGap` for the three archive-gap sites (#1505), and `deriveFenceToken`, `learningKeyOf`, `kebab` imported where they were copied (#1021). Behaviour unchanged.
+
+### Removed
+
+- **H3 Agent Teams test harness** (`hooks/agent-teams-h3-test.sh`, `scripts/spikes/h3-agent-teams/`) — the question it measured is closed (#1061).
+
 ## [5.6.0] - 2026-10-03
 
 ### 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.6.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.7.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.**
@@ -139,15 +139,14 @@ 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.6.0)
+## Recent highlights (v5.7.0)
 
-Highlights of the v5.6.0 line:
+Highlights of the v5.7.0 line:
 
-- **Clearer about what you get.** The website, this README and the npm page now open with the problem the plugin solves and list the features by benefit: what each part does for you, then how it works.
-- **Sessions in a worktree or a subdirectory report their own tree.** A wave's start commit, changed files, HEAD and the stop record's branch now describe the tree the session works in, and the commit guard also checks the manifest of a session launched in a subdirectory, never less strictly than before (#1511).
-- **One rule for how scope paths are spelled.** The overlap check before dispatch and the scope tools now compare paths the same way, and `validate-wave-scope --assert-disjoint --no-manifest` checks a plan's file lists without a dummy manifest (#1510).
-- **A changed scope sidecar can no longer hide a violation.** If the per-wave sidecar changes under a standing manifest, peer records stop counting and you get one notice (#1504).
-- **Close-backfill reads ledger gaps only inside the session's own time window**, so one pruned archive no longer holds back every later session (#1512).
+- **Tidy up the vault mirror in place.** `scripts/vault-mirror-prune.mjs` applies the retention rules to existing learning and session notes: dry run with a manifest first, then `--apply` archives duplicates, superseded and expired notes and writes month rollups. Nothing is deleted, and a second run plans nothing (#1513).
+- **Fewer, better vault notes from now on.** A session record without enough free text gets one rollup row instead of a note, an expired learning never becomes a note, and a learning whose insight already exists is refused (#1513).
+- **The commit guard says which manifest it means.** Parse errors and block messages name the manifest file, and the "To proceed" hint prints once (#1514).
+- **Silent failures made visible.** Read errors other than a missing file are now reported instead of turning into `0` or `unknown` (#1216), and lint blocks imports of the deprecated locks shim (#1234).
 
 Full changes and verification: [CHANGELOG.md](CHANGELOG.md).
 

package/docs/USER-GUIDE.md

@@ -454,7 +454,7 @@ Add a `## Session Config` section to your project's Session Config host file to
 | `plan-retro-location` | string | `docs/retro/` | Directory where retrospective documents are saved (relative to project root). |
 | `memory-cleanup-threshold` | integer | `5` | Recommend `/memory-cleanup` after N accumulated session memory files. |
 | `memory-cleanup-soft-limit` | integer | `180` | Hard ceiling on accumulated memory files before the cleanup nudge escalates from soft suggestion to strong recommendation. PRD F2.2 / issue #502. |
-| `vault-mirror.quality.min-narrative-chars` | integer | `400` | Minimum body length (characters) before a learning or session note is mirrored to the vault. Notes shorter than this threshold are skipped. PRD F1.2 / issue #504. |
+| `vault-mirror.quality.min-narrative-chars` | integer | `400` | Minimum free text (characters in the session record's `notes` / `narrative` / `summary`) before a session gets its own vault note; below it the session becomes a row in the month rollup `50-sessions/<repo>/_rollup-YYYY-MM.md`. PRD F1.2 / #504, #1513. |
 | `vault-mirror.quality.min-confidence` | float | `0.5` | Minimum learning confidence (0.0..1.0) before a learning note is mirrored. Set to `0.0` to mirror every learning regardless of confidence. PRD F1.2 / issue #504. |
 | `cold-start.enabled` | boolean | `true` | Master toggle for the cold-start detector. When `false`, no idle-time nudges fire at session-start. PRD F1.3 / issue #500. |
 | `cold-start.nudge-after-hours` | integer | `1` | Hours of wall-clock idle (since the last session-end) before the cold-start detector fires a nudge. PRD F1.3 / issue #500. |

package/docs/rule-authoring.md

@@ -466,6 +466,16 @@ under four contracts, all of them consequences of the four merge rules above:
 `--apply` emits `orchestrator.rules.expiry_sweep_applied` after the writes
 succeed (see `docs/events-schema.md`); a dry run emits nothing.
 
+**Single-entry files (#1513).** A generated rule holding exactly ONE learning
+(one provenance pair, no `###` entry, no counter sentence — the per-learning
+shape a consumer's reconciliation engine writes; all 21 generated rules of the
+Meta-Vault on 2026-10-03) is dated by its own frontmatter `expires-at`, the
+date `rule-loader.mjs` acts on. There is no body sentence to keep in agreement,
+so the `no-counter-sentence` refusal does not apply: the file is deleted
+(`reason: 'single-entry-expired'`, pair stamped terminal first) once the LATER
+of that date and the learning's store `expires_at` (when it resolves) has
+passed. A re-stamped learning therefore keeps its rule.
+
 ## Authoring Examples
 
 ### (a) Hand-authored always-on rule (no frontmatter)

package/docs/session-config-reference.md

@@ -837,7 +837,7 @@ vault-mirror:
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `vault-mirror.quality.min-narrative-chars` | integer | `400` | Minimum body length (characters) before a learning or session note is mirrored to the vault. Notes shorter than this threshold are skipped — useful to prevent low-information notes from cluttering the vault during onboarding or when a session yields only stubs. Bounds: integer ≥ 0. Out-of-range values silently fall back to the default. PRD F1.2 / issue #504. |
+| `vault-mirror.quality.min-narrative-chars` | integer | `400` | Minimum free text (characters in the session record's `notes` / `narrative` / `summary`) before a session gets its own vault note (#1513). Below it the session becomes one row in `50-sessions/<repo>/_rollup-YYYY-MM.md`; `0` disables the gate. Learnings are not gated by length. Bounds: integer ≥ 0. Out-of-range values silently fall back to the default. PRD F1.2 / issue #504, narrative semantics #1513. |
 | `vault-mirror.quality.min-confidence` | float | `0.5` | Minimum learning confidence (0.0..1.0) before a learning note is mirrored. Confidence is read from the source learning record. Notes below this threshold are skipped. Set to `0.0` to mirror every learning regardless of confidence. Bounds: `0.0 ≤ value ≤ 1.0`. Out-of-range values silently fall back to the default. PRD F1.2 / issue #504. |
 
 **Used by:** `scripts/vault-mirror.mjs`.

package/docs/session-config-template.md

@@ -235,7 +235,7 @@ Quality thresholds applied by `scripts/vault-mirror.mjs` before mirroring a lear
 ```yaml
 vault-mirror:
   quality:
-    min-narrative-chars: 400           # integer ≥ 0 — minimum body length to mirror
+    min-narrative-chars: 400           # integer ≥ 0 — minimum session free text (notes/narrative/summary) for an own note; below → month rollup (#1513)
     min-confidence: 0.5                # float 0.0..1.0 — minimum learning confidence to mirror
 ```
 

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.6.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.7.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.6.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.7.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/wave-scope-commit-guard.mjs

@@ -154,6 +154,29 @@ function findOverlaps(fenceJsonPath, ourStaged) {
   return matches;
 }
 
+/** Remediation for an allowedPaths violation, printed once per commit. */
+const ALLOWED_PATHS_HINT = [
+  '',
+  'These files were likely added by lint-staged eslint --fix / prettier --write.',
+  'To proceed:',
+  '  1) git restore --staged <path>   # for each foreign path',
+  '  2) git commit                    # retry',
+];
+
+/**
+ * A manifest path for messages: relative to the repo root, the absolute path
+ * when it does not lie beneath it (#1514.2 — two candidate manifests, so a
+ * message must say which one it means).
+ *
+ * @param {string} repoRoot
+ * @param {string} scopePath
+ * @returns {string}
+ */
+function manifestLabel(repoRoot, scopePath) {
+  const rel = relative(repoRoot, scopePath);
+  return rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) ? scopePath : rel;
+}
+
 /** mtime of a file in ms, or `null` when it cannot be stat'ed. */
 function mtimeMsOf(file) {
   try {
@@ -183,11 +206,14 @@ function mtimeMsOf(file) {
  *   without pattern matching, since a `../`-prefixed path would match a glob
  *   like `**\/*.mjs` and enforce-scope denies every write outside its root
  *   (REQ-04).
- * @param {string} p.scopeRel manifest path for messages, repo-relative
+ * @param {string} p.scopeRel manifest path for messages, repo-relative (absolute
+ *   when outside the repo root) — `manifestLabel`
  * @param {Set<string>} p.ownIds this process's session ids
  * @param {number|null} p.scopeMtimeMs
  * @param {number|null} p.sessionAge ms since the newest session clock
- * @returns {{action: 'pass'|'report'|'block', lines: string[]}}
+ * @returns {{action: 'pass'|'report'|'block', lines: string[], hint?: string[]}}
+ *   `hint` = the remediation block; `main()` prints it ONCE after every
+ *   manifest was judged, so two blocking manifests do not repeat it (#1514.3).
  */
 function scopeCommitVerdict({ scope, stagedFiles, scopePathOf = (f) => f, scopeRel, ownIds, scopeMtimeMs, sessionAge }) {
   if (stagedFiles.length === 0) return { action: 'pass', lines: [] };
@@ -218,14 +244,10 @@ function scopeCommitVerdict({ scope, stagedFiles, scopePathOf = (f) => f, scopeR
     return {
       action: 'block',
       lines: [
-        '✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths:',
+        `✗ wave-scope-commit-guard: staged paths outside wave-scope.allowedPaths (${scopeRel}):`,
         ...violations.map((v) => `  - ${v}`),
-        '',
-        'These files were likely added by lint-staged eslint --fix / prettier --write.',
-        'To proceed:',
-        '  1) git restore --staged <path>   # for each foreign path',
-        '  2) git commit                    # retry',
       ],
+      hint: ALLOWED_PATHS_HINT,
     };
   }
 
@@ -354,15 +376,22 @@ async function main() {
   const stagedFiles = stagedOutput.split('\n').filter(Boolean);
 
   let blocked = false;
+  /** @type {string[]|null} printed once after the loop (#1514.3) */
+  let hint = null;
+  const flushHint = () => {
+    if (hint !== null) for (const line of hint) process.stderr.write(`${line}\n`);
+  };
   for (const { root, scopePathOf } of judgements) {
     const located = findOwnScopeFile(root, ownIds, classifyManifestSession);
     const scopePath = located.path ?? located.foreignPath;
     if (!scopePath) continue;
+    const scopeRel = manifestLabel(repoRoot, scopePath);
     let scope;
     try {
       scope = JSON.parse(readFileSync(scopePath, 'utf8'));
     } catch (err) {
-      process.stderr.write(`wave-scope-commit-guard: failed to parse wave-scope.json: ${err.message}\n`);
+      process.stderr.write(`wave-scope-commit-guard: failed to parse ${scopeRel}: ${err.message}\n`);
+      flushHint();
       process.exit(1);
     }
 
@@ -370,14 +399,16 @@ async function main() {
       scope: scope !== null && typeof scope === 'object' ? scope : {},
       stagedFiles,
       scopePathOf,
-      scopeRel: relative(repoRoot, scopePath) || scopePath,
+      scopeRel,
       ownIds,
       scopeMtimeMs: mtimeMsOf(scopePath),
       sessionAge: sessionAgeMs(root),
     });
     for (const line of verdict.lines) process.stderr.write(`${line}\n`);
+    if (verdict.hint) hint = verdict.hint;
     if (verdict.action === 'block') blocked = true;
   }
+  flushHint();
   if (blocked) process.exit(1);
 
   // -------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",

package/scripts/backfill-abandoned-sessions.mjs

@@ -42,8 +42,8 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
-import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst } from './lib/events.mjs';
-import { ARCHIVE_DIR_NAME, ROTATION_EVENT } from './lib/events-schema.mjs';
+import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst, tombstoneGap } from './lib/events.mjs';
+import { ARCHIVE_DIR_NAME } from './lib/events-schema.mjs';
 import { getProjectDir } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { isLockLive, readLock } from './lib/session-lock.mjs';
@@ -163,7 +163,8 @@ export function planSessions({ repoRoot }) {
  * not one of the sources read (#1498). Pruned history used to shrink the plan
  * silently; non-zero `historyGaps` says the candidate count is a floor.
  *
- * The check is `readEventsWithRotations` rule 1 (`scripts/lib/events.mjs`):
+ * The check is `tombstoneGap` (`scripts/lib/events.mjs`), the one shared with
+ * `readEventsWithRotations` rule 1:
  * resolved by BASENAME against this ledger's own `_archive/` (#1411), and a
  * file that exists but is not a source (renamed out of `ARCHIVE_NAME_RE`)
  * counts as a gap too — existence is not reading (#1423).
@@ -203,10 +204,7 @@ function planWithGaps({ repoRoot }) {
   for (const source of [...sources].reverse()) {
     forEachJsonlRecord(source.path, (ev) => {
       if (!ev || typeof ev !== 'object') return;
-      if (ev.event === ROTATION_EVENT && typeof ev.archived_as === 'string' && ev.archived_as.length > 0
-        && !read.has(path.join(archiveDir, path.basename(ev.archived_as)))) {
-        historyGaps += 1;
-      }
+      if (tombstoneGap(ev, archiveDir, read) !== null) historyGaps += 1;
       if (typeof ev.session_id === 'string' && typeof ev.semantic_session_id === 'string') {
         if (ev.event === LOCK_ACQUIRED) semanticFromLock.set(ev.session_id, ev.semantic_session_id);
         else if (ev.event === SESSION_ENDED) {

package/scripts/backfill-learnings-from-vault.mjs

@@ -837,6 +837,19 @@ export async function main(argv = [], deps = {}) {
   const archiveIds = idsInStore(archiveAbs);
   const backups = backupPaths(storeAbs).map((p) => ({ path: p, ids: idsInStore(p) }));
   const { notes, unreadable } = indexVaultNotes(learningsAbs);
+  // #1513: `vault-mirror-prune --apply` moves expired/duplicate/superseded
+  // learning notes to `90-archive/mirror/<subdir>/…` with their bytes intact.
+  // They are still evidence for this restore tool — but only as a FALLBACK:
+  // the archive holds the non-canonical twins of live notes, and searching
+  // both at once would turn every such learning into an ambiguous match.
+  const archivedAbs = resolve(vaultDir, '90-archive', 'mirror', vaultSubdir);
+  const archivedNotes = [];
+  if (archivedAbs !== learningsAbs && existsSync(archivedAbs)) {
+    const archived = indexVaultNotes(archivedAbs);
+    for (const n of archived.notes) n.relPath = join('90-archive', 'mirror', vaultSubdir, n.relPath);
+    archivedNotes.push(...archived.notes);
+    unreadable.push(...archived.unreadable);
+  }
   for (const u of unreadable) process.stderr.write(`backfill-learnings-from-vault: WARN unreadable vault note ${u}\n`);
 
   const repoHint = basename(root);
@@ -879,12 +892,10 @@ export async function main(argv = [], deps = {}) {
 
     orphanIndex += 1;
     const keySubjectSlug = prov.learningKey ? prov.learningKey.split('/').slice(1).join('/') : null;
-    const { note, strategy, ambiguous } = locateNote(notes, {
-      subject: prov.subject,
-      keySlug: keySubjectSlug,
-      learningId: id,
-      repoHint,
-    });
+    const query = { subject: prov.subject, keySlug: keySubjectSlug, learningId: id, repoHint };
+    let located = locateNote(notes, query);
+    if (!located.note && !located.ambiguous && archivedNotes.length > 0) located = locateNote(archivedNotes, query);
+    const { note, strategy, ambiguous } = located;
 
     const { record, fidelity, conflicts, crossChecks, validates, validationError } = reconstructRecord({
       rule: prov,

package/scripts/lib/dispatcher/rank.mjs

@@ -202,7 +202,11 @@ async function defaultStaleDaysFor(repoRoot, nowMs) {
     const days = (nowMs - latestMs) / MS_PER_DAY;
     return days > 0 ? days : 0;
   } catch {
-    // No sessions file (or unreadable) ⇒ never worked on ⇒ maximally stale.
+    // Not the missing/unreadable-ledger path: readCanonicalSessions already
+    // returns [] for both (ENOENT silently, any other read failure with a
+    // stderr WARN — sessions-canonical.mjs § #1188), handled by the
+    // `records.length === 0` branch above. This catch only absorbs an
+    // unexpected throw (e.g. a non-string repoRoot) ⇒ maximally stale.
     return STALENESS_CAP_DAYS;
   }
 }

package/scripts/lib/events.mjs

@@ -578,6 +578,60 @@ function discoverArchives(logPath) {
   return { archives, legacy: present.map((i) => `${logPath}.${i}`), ringHoles, unindexed };
 }
 
+/**
+ * The one tombstone-to-archive match (#1505 5c) — shared by
+ * {@link readEventsWithRotations} rule 1, {@link scanEventsBackwards}, and
+ * `planWithGaps` in `scripts/backfill-abandoned-sessions.mjs`, which used to
+ * carry three hand-kept copies of it.
+ *
+ * #1411 — the tombstone resolves against THIS ledger's own `_archive/`, by
+ * BASENAME, never against the absolute value it stores. The writer keeps
+ * `archived_as` absolute (`events-rotation.mjs` joins the repo root) and that
+ * value stays in the record as PROVENANCE. It is not a lookup key: a moved
+ * checkout, a clone, or a sibling git worktree — routine here — makes every
+ * tombstone name a path that does not exist in THIS tree, so an exact
+ * comparison reported a phantom `missing-archive` for an archive sitting right
+ * beside the active file. Basename, not `realpath`: realpath cannot resolve a
+ * path that no longer exists, which IS the failure mode.
+ *
+ * ORDER (why the absolute value has no second chance): the sibling answer is
+ * consulted first, and an absolute hit would only be trustworthy while it
+ * pointed INSIDE this ledger's own archive dir — but any such path resolves to
+ * exactly the sibling path already tested, so once the sibling misses, an
+ * absolute hit can ONLY be a still-present OLD checkout. Honouring it would
+ * validate THIS ledger against a FOREIGN repo's archive: a silent false
+ * negative, worse than the phantom gap.
+ *
+ * #1423 — THREE outcomes, not two: read (`null`), present-but-unread
+ * (`unindexed-archive`), gone (`missing-archive`). The middle one used to be
+ * folded into the first by `existsSync`, so a tombstone whose archive had been
+ * RENAMED out of `ARCHIVE_NAME_RE` reported `complete: true` while its records
+ * were absent.
+ *
+ * @param {unknown} record  a parsed ledger line
+ * @param {string} ownArchiveDir  this ledger's `_archive/`, built exactly as
+ *   `discoverArchives` builds it so a read archive matches `readSet` by string
+ * @param {Set<string>} readSet  the paths this read actually took as sources
+ * @returns {{kind: 'unindexed-archive'|'missing-archive', path: string,
+ *            archived_as: string, first_ts: string|null, last_ts: string|null}|null}
+ *   `null` when `record` is not a rotation tombstone, names no archive, or its
+ *   archive was read.
+ */
+export function tombstoneGap(record, ownArchiveDir, readSet) {
+  if (record?.event !== ROTATION_EVENT) return null;
+  const target = record.archived_as;
+  if (typeof target !== 'string' || target.length === 0) return null;
+  const sibling = path.join(ownArchiveDir, path.basename(target));
+  if (readSet.has(sibling)) return null;
+  return {
+    kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
+    path: sibling,
+    archived_as: target,
+    first_ts: record.first_ts ?? null,
+    last_ts: record.last_ts ?? null,
+  };
+}
+
 /**
  * Read the events ledger ACROSS rotation boundaries — active file plus every
  * archive still on disk — in time order, reporting what is missing instead of
@@ -660,44 +714,14 @@ export function readEventsWithRotations(repoRoot, opts = {}) {
   // `onDisk` still match by string.
   const ownArchiveDir = path.join(path.dirname(activePath), ARCHIVE_DIR_NAME);
 
-  // Rule 1 — every rotation tombstone must still point at a file.
+  // Rule 1 — every rotation tombstone must still point at a file (resolution
+  // and the three outcomes: {@link tombstoneGap}).
   for (const source of sources) {
     for (const record of source.records) {
-      if (record?.event !== ROTATION_EVENT) continue;
-      const target = record.archived_as;
-      if (typeof target !== 'string' || target.length === 0) continue;
-      // #1411 — resolve the tombstone against THIS ledger's own `_archive/`,
-      // by BASENAME, and never against the absolute value it stores.
-      //
-      // The writer keeps `archived_as` absolute (`events-rotation.mjs` joins
-      // the repo root) and that value stays in the record as PROVENANCE. It is
-      // not a lookup key: a moved checkout, a clone, or a sibling git worktree
-      // — routine here — makes every tombstone name a path that does not exist
-      // in THIS tree, so the old exact comparison reported a phantom
-      // `missing-archive` for an archive sitting right beside the active file.
-      // Basename, not `realpath`: realpath cannot resolve a path that no longer
-      // exists, which IS the failure mode.
-      //
-      // ORDER (why the absolute value has no second chance): the sibling answer
-      // is consulted first, and an absolute hit would only be trustworthy while
-      // it pointed INSIDE this ledger's own archive dir — but any such path
-      // resolves to exactly the sibling path already tested, so once the
-      // sibling misses, an absolute hit can ONLY be a still-present OLD
-      // checkout. Honouring it would validate THIS ledger against a FOREIGN
-      // repo's archive: a silent false negative, worse than the phantom gap.
-      const sibling = path.join(ownArchiveDir, path.basename(target));
-      if (onDisk.has(sibling)) continue;
+      const gap = tombstoneGap(record, ownArchiveDir, onDisk);
+      if (gap === null) continue;
       gaps.push({
-        // #1423 — THREE outcomes, not two: read (above), present-but-unread
-        // (here), gone (below). The middle one used to be silently folded into
-        // the first by `existsSync`, so a tombstone whose archive had been
-        // RENAMED out of `ARCHIVE_NAME_RE` reported `complete: true` while its
-        // records were absent from `events`.
-        kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
-        path: sibling,
-        archived_as: target,
-        first_ts: record.first_ts ?? null,
-        last_ts: record.last_ts ?? null,
+        ...gap,
         lines: record.lines ?? null,
         size_before: record.size_before ?? null,
         reported_by: source.path,
@@ -866,8 +890,7 @@ export function scanEventsBackwards(opts = {}) {
    * LOW-2): `maybeRotate` renames, prunes, THEN appends the tombstone, from an
    * async SessionStart hook, so a concurrent append can land first and push it
    * to line 2. Called BEFORE the caller's `filter`, which names another event
-   * and would otherwise hide the cut. Resolved by basename against this
-   * ledger's own `_archive/`, never by the absolute provenance value (#1411).
+   * and would otherwise hide the cut. Matched by {@link tombstoneGap}.
    */
   const noteCut = (line, source) => {
     if (!line.includes(ROTATION_EVENT)) return;
@@ -877,18 +900,8 @@ export function scanEventsBackwards(opts = {}) {
     } catch {
       return; // counted by `consume` like every other malformed line
     }
-    const target = record?.event === ROTATION_EVENT ? record.archived_as : null;
-    if (typeof target !== 'string' || target.length === 0) return;
-    const sibling = path.join(ownArchiveDir, path.basename(target));
-    if (listed.has(sibling)) return;
-    gaps.push({
-      kind: existsSync(sibling) ? 'unindexed-archive' : 'missing-archive',
-      path: sibling,
-      archived_as: target,
-      first_ts: record.first_ts ?? null,
-      last_ts: record.last_ts ?? null,
-      reported_by: source.path,
-    });
+    const gap = tombstoneGap(record, ownArchiveDir, listed);
+    if (gap !== null) gaps.push({ ...gap, reported_by: source.path });
   };
 
   /** @returns {boolean} true ⇒ the caller accepted a record; stop everything. */

package/scripts/lib/io.mjs

@@ -946,16 +946,21 @@ export function writeJsonAtomicSync(filePath, data, opts = {}) {
  * neither may mask the original error.
  *
  * ── BV-004 ceiling + revisit trigger ────────────────────────────────────────
- * TWO PRODUCTION CALL-SITES: `vault-status/board-writer.mjs#writeBoard`
- * (`backup: false`) and {@link writeJsonAtomicSync}, which carries 12 further
- * call-sites across 9 files behind it. That second one is the load-bearing
+ * THREE PRODUCTION CALL-SITES (re-measured 2026-10-03 @ 0e0c4b08 with
+ * `rg -n "atomicWriteWithBackup\(" scripts hooks skills --glob '*.mjs'`):
+ * `vault-status/board-writer.mjs#writeBoard` (`backup: false`),
+ * `reconcile/rule-expiry-sweep.mjs` (no `backup`, i.e. `false`) and
+ * {@link writeJsonAtomicSync}, which carries 14 further call-sites across 11
+ * files behind it (`rg -n "writeJsonAtomicSync\("` over the same scope, minus
+ * the definition and `host-identity.mjs`'s private `_writeJsonAtomicSync`
+ * copy, which does NOT route through this helper). That last one is the load-bearing
  * evidence — the previous revision of this note recorded ONE call-site and
  * concluded the signature was unproven, while the function with an identical
  * body sat 60 lines above in this same file, unmigrated. The cheapest possible
  * migration going unmade is not a neutral fact about a helper: it is the
  * measurement that the helper is not paying for itself.
  *
- * What the second call-site does NOT prove: `writeJsonAtomicSync` passes
+ * What the `writeJsonAtomicSync` call-site does NOT prove: it passes
  * `backup: false` and no `fs`, so the backup half and the injection seam still
  * rest on tests plus one board-writer flag. REVISIT TRIGGER — when a sweep
  * migrates the remaining hand-rolled sites, re-check before widening:

package/scripts/lib/learnings/candidates.mjs

@@ -185,7 +185,7 @@
 
 import { tokenize } from './affinity.mjs';
 import { readLearnings } from './io.mjs';
-import { kebab } from './kebab.mjs';
+import { learningKeyOf } from './kebab.mjs';
 import { normalizeDialects } from './schema.mjs';
 
 // ---------------------------------------------------------------------------
@@ -441,27 +441,18 @@ export function emptyPools() {
 /**
  * Logical identity of a learning: `` `${type}/${kebab(title || subject)}` ``.
  *
- * Returns `null` when either half is unusable — mirroring
- * `validate/check-learning-provenance.mjs::learningKeyOf`, so an unkeyable
- * record simply does not participate in the exact-key pass. It still seeds and
+ * Returns `null` when either half is unusable (non-record input, blank
+ * type/title/subject, or an all-symbol title that kebabs to '') — delegates to
+ * the shared `kebab.mjs::learningKeyOf` (#1021) so the key space cannot fork
+ * from the provenance checker's. An unkeyable record simply does not
+ * participate in the exact-key pass. It still seeds and
  * joins pools: a missing title is not a reason to hide a learning from dedupe.
  *
  * @param {unknown} record
  * @returns {string|null}
  */
 export function learningKey(record) {
-  if (!_isRecord(record)) return null;
-  const type = typeof record.type === 'string' ? record.type.trim() : '';
-  const titleOrSubject =
-    (typeof record.title === 'string' && record.title.trim() !== '' ? record.title : '') ||
-    (typeof record.subject === 'string' && record.subject.trim() !== '' ? record.subject : '');
-  if (type === '' || titleOrSubject === '') return null;
-  const slug = kebab(titleOrSubject);
-  // `kebab` may legally return '' (all-symbol input) — an empty slug is not an
-  // identity, so such a record is unkeyable rather than colliding with every
-  // other empty-slug record of the same type.
-  if (slug === '') return null;
-  return `${type}/${slug}`;
+  return learningKeyOf(record);
 }
 
 /**

package/scripts/lib/memory-proposals/store.mjs

@@ -413,7 +413,10 @@ export async function appendProposal({
  * Reads proposals.jsonl without acquiring the lock — suitable for diagnostics
  * and reads where eventual consistency is acceptable.
  *
- * Returns 0 when the file does not exist.
+ * Returns 0 when the file does not exist (silently — `countWaveLines` maps
+ * ENOENT to 0). Any other read failure also returns 0, but with a stderr WARN
+ * so a 0 caused by an unreadable file is distinguishable from an empty queue
+ * (#1216).
  *
  * @param {object} opts
  * @param {string} opts.repoRoot
@@ -424,7 +427,11 @@ export async function countProposalsForWave({ repoRoot, waveId }) {
   const jsonlPath = jsonlPathFor(repoRoot);
   try {
     return countWaveLines(jsonlPath, waveId);
-  } catch {
+  } catch (err) {
+    process.stderr.write(
+      `[memory-proposals] WARN: countProposalsForWave: ` +
+        `${err?.code ?? '?'}: ${err?.message ?? String(err)} — returning 0\n`,
+    );
     return 0;
   }
 }