session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/validate/check-unwired-features.mjs

@@ -53,6 +53,30 @@
  * a rule that only cites live instances loses its explanation the moment it works.
  * If you need a CURRENT S2 hit, run the checker; do not assume this one.
  *
+ *   S6 `parser-only-config-key`  — the key IS read, but the ONLY file that
+ *                                   reads it is its own block parser
+ *                                   `scripts/lib/config/<root>.mjs`.
+ *
+ * S6 is the mirror image of S2, and it exists because S1 counts the PARSER as a
+ * consumer: `CONSUMER_DIRS` is `scripts/` + `hooks/`, and every block parser
+ * lives under `scripts/lib/config/`. A key its parser resolves and nothing else
+ * reads is `compact-nudge` wearing a value object. Measured 2026-09-22 on this
+ * tree: `reaper.max-hook-latency-ms` and `reaper.false-alarm-window` both passed
+ * S1 on `scripts/lib/config/reaper.mjs` alone while `scripts/lib/orphan-reaper.mjs`
+ * used same-named HARDCODED defaults and never saw the parsed value.
+ *
+ * Why the signal is this narrow — one read file, and it is the key's OWN parser.
+ * The blunt rule ("the parser layer never counts") was measured first and
+ * REJECTED: it flips 102 of 263 declared keys to unwired, because the ordinary
+ * shape here is a consumer that reads the camelCase FIELD (`cfg.driftCheck.mode`)
+ * while this census matches the kebab TOKEN. 102 of 263 is the broken instrument
+ * `.claude/rules/host-resources.md` HR-101 forbids. The narrow rule reports 32 —
+ * a backlog, printed as an aggregate like S4 and enumerated under `--list`.
+ *
+ * S6 carries no camelCase fallback ON PURPOSE: adding one re-hides both reaper
+ * keys, whose camelCase names exist in `orphan-reaper.mjs` as that module's own
+ * defaults. A name is not a read.
+ *
  * S2 applies to TOP-LEVEL keys only — a nested key reaches code through its
  * parent — and its premise is structural: every Session Config key has to pass
  * through the parser layer to become a value. Measured 2026-08-08: 84 of 89
@@ -393,6 +417,29 @@ const PARSER_PATHS = Object.freeze([
   path.join('scripts', 'parse-config.mjs'),
 ]);
 
+/**
+ * The per-block parser directory: `scripts/lib/config/<block>.mjs` turns ONE
+ * Session Config block's YAML into a value object and does nothing else.
+ *
+ * Signal S6 below is about this directory specifically, which is why it is not
+ * folded into {@link PARSER_PATHS}.
+ */
+const BLOCK_PARSER_DIR = path.join('scripts', 'lib', 'config');
+
+/**
+ * The key's OWN block parser, by convention `scripts/lib/config/<root>.mjs`.
+ *
+ * Deliberately an exact name match and not "anything under the parser dir": a
+ * sibling block's parser reading the key is still a second file, and S6 only
+ * fires when there is exactly ONE reader and it is the key's own.
+ *
+ * @param {string} root top-level key of the block
+ * @returns {string} plugin-root-relative path
+ */
+function ownBlockParserPath(root) {
+  return path.join(BLOCK_PARSER_DIR, `${root}.mjs`);
+}
+
 /**
  * Declared-but-unread keys accepted on purpose. Key = full dotted path (S1/S2)
  * or module path relative to the plugin root (S4), value = REASON naming the
@@ -420,7 +467,8 @@ const ALLOWLIST = Object.freeze({
 
 /**
  * @typedef {{
- *   kind: 'unwired-config-key' | 'parser-orphan-config-key' | 'allowlist-missing-reason'
+ *   kind: 'unwired-config-key' | 'parser-orphan-config-key' | 'parser-only-config-key'
+ *       | 'allowlist-missing-reason'
  *       | 'allowlist-stale' | 'orphaned-prose-module' | 'unreachable-library-module'
  *       | 'coordinator-invoked-module' | 'hand-keyed-learning-subject'
  *       | 'tool-error',
@@ -883,7 +931,9 @@ function mentionedModuleTokens(lines) {
  *    switched off. Revisit if a real module-resolver (import-specifier resolution
  *    relative to the importing file) becomes cheap, or if a collided basename is
  *    ever confirmed to mask a true positive. The `coordinator-invoked-module`
- *    DOWNGRADE is exempt, and since #1293 so is the CLUSTER-ROOT filter: in both
+ *    DOWNGRADE is exempt, and since #1293 so is the CLUSTER-ROOT filter (since
+ *    #1298 its predicate also drives the "drags N" count, which had collapsed
+ *    two dragged `index.mjs` into one): in both
  *    a colliding basename must be named with its `dirname/base` suffix, because
  *    those matches move a module OUT of the reportable class and would otherwise
  *    hide a true unreachable sibling. Measured cost of leaving the root filter
@@ -1014,24 +1064,41 @@ export function collectUnreachableLibraryModules(pluginRoot) {
   const basenameCount = new Map();
   for (const module of modules) basenameCount.set(module.base, (basenameCount.get(module.base) ?? 0) + 1);
 
-  const roots = unreachable.filter((module) => {
-    // A bare-basename mention only suppresses when the basename is UNIQUE
-    // (see the census above). When it collides, the mentioning module must name
-    // the `dirname/base` form in its body — otherwise ONE unreachable module
-    // mentioning bare `index.mjs` masks EVERY differently-pathed `index.mjs`
-    // root at once (#1293: `locks/index.mjs` + `worktree/index.mjs` were masked
-    // by a third unreachable module until that module was deleted for an
-    // unrelated reason).
-    const ambiguous = (basenameCount.get(module.base) ?? 0) > 1;
-    const qualified = module.relative.split(path.sep).slice(-2).join('/');
-    const qualifiedRe = ambiguous ? tokenMatcher(qualified) : null;
-    return !unreachable.some(
-      (other) =>
-        other.relative !== module.relative &&
-        other.mentions.has(module.base) &&
-        (qualifiedRe === null || qualifiedRe.test(other.rawBody)),
-    );
-  });
+  // One `dirname/base` matcher per unreachable module whose basename collides,
+  // built once: `references` below runs per (mentioner, target) pair.
+  /** @type {Map<string, RegExp>} */
+  const qualifiedMatchers = new Map();
+  for (const module of unreachable) {
+    if ((basenameCount.get(module.base) ?? 0) < 2) continue;
+    qualifiedMatchers.set(module.relative, tokenMatcher(module.relative.split(path.sep).slice(-2).join('/')));
+  }
+  /**
+   * Does `mentioner` reference the unreachable module `target`? A bare-basename
+   * mention only counts when the basename is UNIQUE (see the census above).
+   * When it collides, the mentioning module must name the `dirname/base` form
+   * in its body — otherwise ONE unreachable module mentioning bare `index.mjs`
+   * references EVERY differently-pathed `index.mjs` at once (#1293:
+   * `locks/index.mjs` + `worktree/index.mjs` were masked as roots by a third
+   * unreachable module until that module was deleted for an unrelated reason).
+   *
+   * The ONE predicate for both consumers — the cluster-root filter and the drag
+   * count of the finding message — so the two cannot disagree about who
+   * references whom. They did (#1298): the drag count compared bare basenames,
+   * so a root importing `a/index.mjs` AND `b/index.mjs` read "drags 1".
+   *
+   * @param {(typeof modules)[number]} mentioner
+   * @param {(typeof modules)[number]} target an `unreachable` module
+   * @returns {boolean}
+   */
+  const references = (mentioner, target) => {
+    if (!mentioner.mentions.has(target.base)) return false;
+    const qualifiedRe = qualifiedMatchers.get(target.relative);
+    return qualifiedRe === undefined || qualifiedRe.test(mentioner.rawBody);
+  };
+
+  const roots = unreachable.filter(
+    (module) => !unreachable.some((other) => other.relative !== module.relative && references(other, module)),
+  );
 
   // A pure `export *` barrel enters the population above so it can HEAD its own
   // cluster, but reporting it needs one more condition. S3 already exempts this
@@ -1106,9 +1173,10 @@ export function collectUnreachableLibraryModules(pluginRoot) {
           'architecture. Re-check only if that instruction is ever removed',
       });
     }
-    const dragged = [...module.mentions].filter(
-      (token) => token !== module.base && [...unreachableSet].some((rel) => path.basename(rel) === token),
-    );
+    // Counted per MODULE through the root filter's own predicate, never per
+    // basename token: `mentions` is a Set of basenames, so two dragged
+    // `index.mjs` files would collapse into one (#1298).
+    const dragged = unreachable.filter((other) => other.relative !== module.relative && references(module, other));
     const tail = dragged.length > 0 ? `, and drags ${dragged.length} further unreachable module(s)` : '';
     // A pure barrel reports its re-export surface; naming "0 symbol(s)" there
     // would read as a checker bug rather than as the barrel it is.
@@ -1259,6 +1327,7 @@ export function inspectUnwiredFeatures(pluginRoot) {
       orphanedModules: 0,
       unreachableModules: 0,
       coordinatorInvokedModules: 0,
+      parserOnly: 0,
       handKeyedSubjects: 0,
       judgedSubjects: 0,
     },
@@ -1318,7 +1387,7 @@ export function inspectUnwiredFeatures(pluginRoot) {
 
   for (const key of [...declared.keys.keys()].sort()) {
     const meta = /** @type {DeclaredKey} */ (declared.keys.get(key));
-    const { code, comment } = countReadSites(meta, corpus);
+    const { code, comment, files: readFiles } = countReadSites(meta, corpus);
 
     /** @type {Finding | null} */
     let issue = null;
@@ -1331,6 +1400,21 @@ export function inspectUnwiredFeatures(pluginRoot) {
           `declared in ${meta.sources.join(' + ')} but no .mjs under ${CONSUMER_DIRS.join('/ or ')}/ ` +
           `reads it${commentNote} — wire it, delete it, or allowlist it with a reason`,
       };
+    } else if (readFiles.length === 1 && readFiles[0] === ownBlockParserPath(meta.root)) {
+      // S6 — the ONLY file that reads this key is the parser that produced it.
+      // A parser is not a consumer: it turns YAML into a field nobody then
+      // reads, which is `compact-nudge` wearing a value object. Measured
+      // 2026-09-22: `reaper.max-hook-latency-ms` and `reaper.false-alarm-window`
+      // both passed S1 on the strength of `scripts/lib/config/reaper.mjs`
+      // alone, while `orphan-reaper.mjs` used its OWN hardcoded defaults of the
+      // same name and never received the parsed value.
+      issue = {
+        kind: 'parser-only-config-key',
+        key,
+        message:
+          `read only by its own block parser (${readFiles[0]}) — a parser is not a consumer; ` +
+          'nothing outside the config layer reads the parsed value',
+      };
     } else if (key === meta.root && !tokenMatcher(key).test(parserBody)) {
       issue = {
         kind: 'parser-orphan-config-key',
@@ -1356,7 +1440,8 @@ export function inspectUnwiredFeatures(pluginRoot) {
       continue;
     }
 
-    result.summary.unwired += 1;
+    if (issue.kind === 'parser-only-config-key') result.summary.parserOnly += 1;
+    else result.summary.unwired += 1;
     findings.push(issue);
   }
 
@@ -1426,6 +1511,7 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
     consumerFiles,
     unwired,
     allowlisted,
+    parserOnly,
     orphanedModules,
     unreachableModules,
     coordinatorInvokedModules,
@@ -1445,8 +1531,16 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
   // architecture — an instruction surface tells an LLM to call the module.
   // Measured 2026-09-07: 46 of the 52 findings the single S4 class carried.
   // Printing 46 WARN lines for the design is the broken instrument HR-101 forbids.
-  const DEFERRED = Object.freeze(['unreachable-library-module', 'coordinator-invoked-module']);
+  //
+  // `parser-only-config-key` (S6) is deferred on the S4 terms too: 32 findings
+  // on the live tree is a backlog to work down, not a per-run alarm.
+  const DEFERRED = Object.freeze([
+    'unreachable-library-module',
+    'coordinator-invoked-module',
+    'parser-only-config-key',
+  ]);
   const s4 = inspection.findings.filter((item) => item.kind === 'unreachable-library-module');
+  const s6 = inspection.findings.filter((item) => item.kind === 'parser-only-config-key');
   for (const item of inspection.findings) {
     if (!list && DEFERRED.includes(item.kind)) continue;
     console.log(`  WARN: [${item.kind}] ${item.key} — ${item.message}`);
@@ -1465,10 +1559,19 @@ export function runCheckUnwiredFeatures(pluginRoot, { list = false } = {}) {
     );
   }
 
+  if (!list && s6.length > 0) {
+    console.log(
+      `  WARN: [parser-only-config-key] ${s6.length} declared key(s) whose only reader is their own ` +
+        `block parser — e.g. ${s6.slice(0, 3).map((item) => item.key).join(', ')}. ` +
+        'Re-run with --list for the full census.',
+    );
+  }
+
   console.log(
     `  PASS: censused ${declaredKeys} declared key(s) from ${inspection.sourcesScanned.join(' + ') || '(no source)'} ` +
       `against ${consumerFiles} consumer file(s) — ${unwired} unwired, ${allowlisted} allowlisted, ` +
-      `${orphanedModules} prose-orphaned module(s), ${unreachableModules} unreachable module(s), ` +
+      `${parserOnly} parser-only, ${orphanedModules} prose-orphaned module(s), ` +
+      `${unreachableModules} unreachable module(s), ` +
       `${coordinatorInvokedModules} coordinator-invoked module(s), ${handKeyedSubjects} hand-keyed ` +
       `learning subject(s) of ${judgedSubjects} judged`,
   );

package/scripts/lib/validate/check-validator-registration.mjs

@@ -51,15 +51,21 @@
  * skill body) and nowhere in the three RUN surfaces above still reports
  * UNREGISTERED — being documented is not being run. REVISIT if a fourth run
  * surface (a new CI job file, a different git hook) is ever added: extend
- * `RUN_SURFACES`, do not special-case it here. The comment stripper's own
- * quote-tracking is a single flat state — an escaped quote (`\"`) inside a
- * double-quoted string is not honoured, and a template-literal's `${...}`
- * interpolation is not walked separately. Both failure directions lean
- * toward treating MORE text as "inside a string" than a real parser would,
- * which can only make the stripper MISS a comment (false "still
- * registered"), never manufacture a false UNREGISTERED — the direction this
- * checker's own false-positive history (the paragraph above) already
- * measured as the live hazard.
+ * `RUN_SURFACES`, do not special-case it here.
+ *
+ * THE "NEVER A FALSE UNREGISTERED" CLAIM WAS FALSE (#1388, measured
+ * 2026-09-18 @ 20a4cbff). This header used to argue that the hand-rolled
+ * stripper could only ever MISS a comment, never manufacture a false
+ * UNREGISTERED. It had no regex-literal branch, so
+ * `const re = /\/*$/;` in `scripts/validate-plugin.mjs` opened a BLOCK
+ * COMMENT at the regex's `/*` and swallowed every `runCheck(...)` line below
+ * it — precisely a false UNREGISTERED, for every checker registered after
+ * that point. The `.mjs` surface is therefore lexed by the shared
+ * `maskSource` (`scripts/lib/js-mask.mjs`), which recognises regex literals;
+ * only the `#`-comment shell/YAML surfaces (`.husky/pre-commit`,
+ * `.gitlab-ci.yml`) still use the small local walker, whose flat
+ * quote-tracking ceiling (no `\"` escape handling, no `${...}` walk) is
+ * real but bounded to those two files.
  *
  * Usage: check-validator-registration.mjs <repo-root>
  * Output: `  PASS: …` / `  FAIL: …` lines (two leading spaces), then
@@ -74,6 +80,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { enumerateRepoFiles } from './enumerate-repo-files.mjs';
 import { isMainModule } from '../is-main-module.mjs';
+import { maskSource } from '../js-mask.mjs';
 
 /** Marker line inside a checker's own header — declares deliberate CLI-only status. */
 export const STANDALONE_MARKER = /^\s*\/\/\s*registration:\s*standalone\b(?:\s+(.*))?$/m;
@@ -113,11 +120,28 @@ function commentStyleForSurface(rel) {
  * truncating the line early. See the header NAMED CEILING for what this
  * quote-tracking deliberately does not attempt.
  *
+ * The JS style (`//` + `/* *\/`) is delegated to the shared lexer
+ * {@link maskSource} in `keepLiterals` mode — it is the only one of the three
+ * RUN_SURFACES that can contain a REGEX LITERAL, and a stripper without a
+ * regex branch reads `/\/*$/` as a block-comment opener and swallows every
+ * registration below it (#1388, see the header). `maskSource` blanks comment
+ * bytes to SPACES rather than deleting them, which is strictly safer for the
+ * substring match below: deletion could splice two fragments into a basename
+ * that was never written. The `#` style stays local — `maskSource` models
+ * JavaScript, not sh/YAML.
+ *
  * @param {string} text
  * @param {{lineComment: string, blockComment: boolean, quoteChars: string[]}} style
- * @returns {string}
+ * @returns {string} TWO comment models behind one signature, and they differ in
+ * shape: the JS style (`//` + `/* *\/`, delegated to {@link maskSource})
+ * returns a string of the SAME LENGTH as `text`, with comment bytes blanked to
+ * spaces; the `#` style (sh/YAML, the local walker) returns a SHORTER string,
+ * with the comment text deleted to end-of-line (the newline itself is kept).
+ * Only the substring match below is common to both — do not rely on offsets
+ * surviving the `#` style.
  */
 export function stripComments(text, { lineComment, blockComment, quoteChars }) {
+  if (lineComment === '//' && blockComment) return maskSource(text, { keepLiterals: true });
   let out = '';
   let i = 0;
   let inQuote = null;

package/scripts/lib/validate/confidential-names.mjs

@@ -177,6 +177,16 @@ export function inspectConfidentialNames({ namesPath, deps = {} } = {}) {
   // Unconfigured → no list, no noise. This is the normal case for public repos
   // and for any host that has not opted into confidential-name scanning.
   if (typeof namesPath !== 'string' || namesPath.trim() === '') {
+    // UNREACHABLE from the one production caller today (#1273 P1):
+    // `check-owner-leakage.mjs` resolves `namesPath` via `resolveHostPath()`
+    // and returns its own early `disabledReason` on an empty/non-string path
+    // BEFORE ever calling `inspectConfidentialNames` — so in production this
+    // branch never runs. It is reachable only for a direct caller (or a test)
+    // that skips that pre-filter. Kept regardless: `status` is part of the
+    // documented public contract every deep importer may switch on, and
+    // 'unconfigured' is the correct answer for exactly this input shape.
+    // REVISIT TRIGGER (BV-004): the production caller stops pre-filtering an
+    // empty/non-string `namesPath` before calling `inspectConfidentialNames`.
     return { status: 'unconfigured', names: [] };
   }
 

package/scripts/lib/validate-vendored-rules.mjs

@@ -617,8 +617,9 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
 }
 
 /**
- * Validates every `*.md` rule file under `dir`, recursively (skips dotfiles
- * and `_index.md`).
+ * Validates every `*.md` rule file under `dir`, recursively (skips dotfiles,
+ * `_index.md` and `README.md` — neither is a vendored rule: `rules-sync.mjs`
+ * vendors only the entries listed in `_index.md`, #1164).
  *
  * When `pluginRoot` is given, every scanned file is additionally passed through
  * `scanVendoringLeaks()` and the findings are collected into the additive
@@ -642,7 +643,7 @@ export function validateRulesDir({ dir, targetRoot = null, requireProvenance = f
       const absPath = join(absDir, entry.name);
       if (entry.isDirectory()) {
         files.push(...collectRuleFiles(absPath));
-      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_index.md') {
+      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_index.md' && entry.name !== 'README.md') {
         files.push(relative(dir, absPath).replace(/\\/g, '/'));
       }
     }

package/scripts/lib/vault-mirror/namespace.mjs

@@ -5,10 +5,18 @@
  * vault writes under `40-learnings/<repoNs>/` and `50-sessions/<repoNs>/`.
  *
  * Contract:
- *   resolveRepoNamespace({ vaultName?, cwd? }) → string
+ *   resolveRepoNamespace({ vaultName?, repoRoot? }) → string
  *
- *   - Pure + deterministic (given the same git remote / cwd / vaultName input,
- *     and the same host-local pseudonym map).
+ *   - Pure + deterministic (given the same vaultName, the same `.vault.yaml`
+ *     under `repoRoot`, the same git remote, and the same host-local pseudonym
+ *     map).
+ *   - `repoRoot` (#1389) selects the directory whose `.vault.yaml` is read;
+ *     it defaults to `process.cwd()`. Named limit: it scopes ONLY that lookup —
+ *     the {@link deriveRepo} fallback still resolves from the process cwd and
+ *     is cached per process, so a `repoRoot` that differs from the cwd AND has
+ *     no declared slug falls back to the cwd's git identity. Every production
+ *     caller passes its own cwd today; revisit if a caller ever mirrors a repo
+ *     other than the one it runs in.
  *   - Returns a lowercase kebab slug safe for use as a filesystem path segment.
  *   - Host-local pseudonym mapping (Epic #725 D5): consulted ONLY at the redaction
  *     site (only when a segment is owner-leaky). If such a repo (raw or sanitised)
@@ -47,6 +55,7 @@ import { isOwnerLeakySegment } from '../../lib/validate/check-owner-leakage.mjs'
 import { loadPseudonymMap } from './pseudonym-map.mjs';
 import { loadHostPaths, resolveHostPath } from '../config/host-paths.mjs';
 import { isQueryFailure, resolvePreferredRemote } from '../vcs-repo-spec.mjs';
+import { readVaultSlug } from '../vault-yaml.mjs';
 
 // ── Lazy pseudonym-map path resolution (Epic #725 D5) ────────────────────────
 // The map path comes from env SO_NAMESPACE_MAP > owner.yaml paths.namespace-map-path
@@ -237,19 +246,48 @@ function lookupPseudonym(base, seg) {
  *
  * @param {object}  [opts]
  * @param {string|null} [opts.vaultName] - Optional override for the repo identifier.
- *   When non-empty and non-whitespace, used in place of the git-derived repo name.
- *   When absent, the namespace is derived from the git origin via deriveRepo().
+ *   When non-empty and non-whitespace, used in place of the declared/git-derived
+ *   repo name. When absent, the base is the repo's declared `.vault.yaml`
+ *   `metadata.slug` (#1131), else the git origin via deriveRepo().
+ * @param {string|null} [opts.repoRoot] - Directory whose `.vault.yaml` supplies
+ *   the declared slug (#1389). `undefined`/`null` → `process.cwd()`. Does NOT
+ *   redirect the deriveRepo() fallback (see the module header's named limit).
  * @returns {string} A single kebab-slug path segment, e.g. 'session-orchestrator'.
  *   Special returns:
  *   - 'unknown-repo'  — slug derivation produced an empty string.
  *   - 'redacted-repo' — the raw or slugified value matched an owner-leakage pattern
  *     (CP1 personal home path / CP6 private slug / CP10 personal name in Projects path).
  */
-export function resolveRepoNamespace({ vaultName = null } = {}) {
-  // Choose the base identifier: explicit override first, then git-derived.
+export function resolveRepoNamespace({ vaultName = null, repoRoot = null } = {}) {
+  // Choose the base identifier. Precedence: explicit `vaultName` override >
+  // the repo's declared `.vault.yaml` `metadata.slug` (#1131) > git-derived.
+  //
+  // WHY the slug sits HERE and not in deriveRepo(): deriveRepo() is the RAW
+  // repo IDENTITY (`org/repo`) and has consumers that want exactly that and
+  // nothing else — `vault-relocation-rules.mjs`, `relocate-vault-corpus.mjs`,
+  // `named-vault-resolver.mjs` (which documents the `org/repo-name` format).
+  // #1131 concerns the vault FOLDER namespace, which is what THIS function
+  // decides, so the lookup belongs at this candidate-selection point.
+  //
+  // Note what this placement does NOT buy: the `source-repo:` frontmatter is
+  // this function's output, not deriveRepo()'s (#732; process.mjs deliberately
+  // shares ONE value between the write path and the rendered field), so a repo
+  // whose declared slug differs from its derived name gets a new `source-repo`
+  // either way. That is inherent to moving the folder, not a side effect of
+  // where the lookup lives.
+  //
+  // It sits BELOW `vaultName` (an explicit per-call/operator override must stay
+  // honourable) and ABOVE derivation (a declared registration beats a guess from
+  // the remote URL or the checkout directory: the remote answers "where does
+  // this code live?", the slug answers "which vault project IS this?", and a
+  // host-side rename legitimately diverges the two). It sits ABOVE the leak
+  // guard below deliberately — a declared slug is operator data flowing into a
+  // written path and is checked by CP1/CP6/CP10 and the pseudonym map exactly
+  // like any git-derived identifier.
+  const declaredSlug = readVaultSlug(repoRoot ?? process.cwd());
   const base = (vaultName && typeof vaultName === 'string' && vaultName.trim())
     ? vaultName.trim()
-    : deriveRepo();
+    : (declaredSlug ?? deriveRepo());
 
   // Sanitise: collapse to last path segment, lowercase, strip non-[a-z0-9-].
   const seg = subjectToSlug(base);

package/scripts/lib/vault-mirror/process.mjs

@@ -666,8 +666,12 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     });
   }
 
-  // #660: namespace new writes under a per-repo subdirectory.
-  const repoNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null });
+  // #660: namespace new writes under a per-repo subdirectory. #1389: `ctx.repoRoot`
+  // is optional — absent, resolveRepoNamespace falls back to process.cwd().
+  const repoNs = resolveRepoNamespace({
+    vaultName: ctx?.vaultName ?? null,
+    repoRoot: ctx?.repoRoot ?? null,
+  });
   // #725 D2: thread the resolved repo namespace into the learning frontmatter as
   // `source-repo` for cross-repo attribution. repoNs is already sanitised +
   // leak-guarded by resolveRepoNamespace, so it is safe to interpolate as-is. The
@@ -898,7 +902,10 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // owner-leaky repo's real name reached the vault through the session-note
   // frontmatter even though the directory AND the learning `source-repo` field
   // were already pseudonym-mapped/redacted (#732 leak-guard bypass).
-  const repoNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null });
+  const repoNs = resolveRepoNamespace({
+    vaultName: ctx?.vaultName ?? null,
+    repoRoot: ctx?.repoRoot ?? null,
+  });
 
   // Quality gate (PRD F1.2): skip sessions whose rendered narrative is too short.
   // Measure on the rendered markdown body so the check is schema-agnostic across

package/scripts/lib/vault-mirror/render-sessions.mjs

@@ -476,14 +476,24 @@ export function generateSessionNote(entry, options = {}) {
       // #1276: lifecycle-only records omit every older count alias. Started
       // measures participation; completed/planned-only counts retain their
       // labels so a plan or a completion count never claims dispatch coverage.
-      const completedAgents = waveCount(w.agent_count_completed);
-      const plannedAgents = waveCount(w.agent_count_planned);
+      // The `agents_*` triple is the same lifecycle measurement under the
+      // de-underscored producer spelling: `metrics-collection.md` documents
+      // `agent_count_{planned,started,completed}`, but the live ledger carries
+      // one session (`main-2026-09-18-session-1`, 5 waves, measured 2026-09-18
+      // over `.orchestrator/metrics/sessions.jsonl`) whose waves emit only
+      // `agents_planned` / `agents_started` / `agents_completed` — every one of
+      // its 15 counts rendered `?` beside a real number, exactly the #1074 bug
+      // class. Each alias sits at the precedence of its documented twin, so no
+      // cell that already rendered a value can change.
+      const completedAgents = waveCount(w.agent_count_completed) ?? waveCount(w.agents_completed);
+      const plannedAgents = waveCount(w.agent_count_planned) ?? waveCount(w.agents_planned);
       const agentsCell =
         waveCount(w.agent_count) ??
         waveCount(w.agents) ??
         waveCount(w.agents_dispatched) ??
         waveCount(w.dispatched) ??
         waveCount(w.agent_count_started) ??
+        waveCount(w.agents_started) ??
         (completedAgents === undefined ? undefined : `${completedAgents} completed`) ??
         (plannedAgents === undefined ? MISSING_CELL : `${plannedAgents} planned`);
       const filesCell = waveCount(w.files_changed) ?? waveCount(w.files) ?? MISSING_CELL;

package/scripts/lib/vault-status/narrative-mirror.mjs

@@ -43,6 +43,7 @@ import { readConfigFile, parseSessionConfig } from '../config.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { createSecretValueMasker } from '../secret-masker.mjs';
 import { expandTilde } from '../common.mjs';
+import { readVaultSlug } from '../vault-yaml.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned narrative files. */
 export const GENERATOR_MARKER = 'session-orchestrator-vault-status-narrative@1';
@@ -869,15 +870,29 @@ async function runNarrativeMirror(opts) {
 
   // Defense-in-depth: when the caller omits (or passes an empty) `repo`, derive
   // it from the operator-configured `vault-name` override (#660/#832) when set,
-  // else the repoRoot basename — never silently mis-file under 'unknown' (#675
-  // review). Precedence: explicit `repo` opt > `vault-name` > basename.
+  // else the `.vault.yaml` slug (#1131), else the repoRoot basename — never
+  // silently mis-file under 'unknown' (#675 review).
   const vaultNameOverride =
     typeof vaultIntegration['vault-name'] === 'string' && vaultIntegration['vault-name'].trim()
       ? vaultIntegration['vault-name'].trim()
       : null;
-  const repoName = (typeof repo === 'string' && repo.trim().length > 0)
+  const explicitName = (typeof repo === 'string' && repo.trim().length > 0)
     ? repo
-    : vaultNameOverride ?? path.basename(path.resolve(repoRoot));
+    : vaultNameOverride;
+
+  // #1131: with NO explicit override, the repo's own `.vault.yaml`
+  // `metadata.slug` — the CANONICAL vault registration — outranks the
+  // directory basename. Precedence: explicit `repo` opt > `vault-name` >
+  // `.vault.yaml` slug > basename.
+  //
+  // WHY the two overrides still win: both are things a CALLER/operator states
+  // for THIS call (`repo` is only ever passed to override the derived name —
+  // the sole production caller, `skills/session-end/session-metrics-write.md`,
+  // passes `repoRoot` alone), so honouring the file over them would make an
+  // explicit override unhonourable. The file wins over the basename, which is
+  // a guess nobody stated.
+  const vaultYamlSlug = explicitName ? null : readVaultSlug(repoRoot);
+  const repoName = explicitName ?? vaultYamlSlug ?? path.basename(path.resolve(repoRoot));
 
   const rawVaultDir = vaultIntegration['vault-dir'];
   if (!rawVaultDir || typeof rawVaultDir !== 'string') {
@@ -886,10 +901,19 @@ async function runNarrativeMirror(opts) {
 
   const vaultDir = path.resolve(expandTilde(rawVaultDir));
   const candidateSlug = subjectToSlug(repoName) || 'unknown';
-  // Loose-match against existing 01-projects/ folders before minting a new
-  // slug (issue #829 Finding 3) — see resolveLooseSlug for the ambiguity
+  // A declared `.vault.yaml` slug needs no healing — it IS the canonical folder
+  // name, so resolveLooseSlug is SKIPPED for it. Running the healer over it
+  // would re-open the bug this fixes: a vault that also carries an unhealed
+  // legacy folder (e.g. `foobarapp` beside the declared `foo-bar-app`) makes
+  // the loose match ambiguous, and ambiguity falls back to the candidate —
+  // which is how a duplicate pair, once created, keeps being written to.
+  //
+  // Otherwise: loose-match against existing 01-projects/ folders before minting
+  // a new slug (issue #829 Finding 3) — see resolveLooseSlug for the ambiguity
   // rules. Falls through to `candidateSlug` unchanged on any read failure.
-  const repoSlug = resolveLooseSlug(vaultDir, candidateSlug, { readdirSync: injectedFs?.readdirSync });
+  const repoSlug = vaultYamlSlug
+    ? candidateSlug
+    : resolveLooseSlug(vaultDir, candidateSlug, { readdirSync: injectedFs?.readdirSync });
   const outputPath = resolveNarrativePath(vaultDir, repoSlug);
 
   // Defense-in-depth: ensure the resolved file stays inside the vault root.