session-orchestrator 5.3.0 → 5.4.0

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

@@ -6,17 +6,21 @@
  * Catches vendoring bugs that are invisible at the source-of-truth layer but
  * become live footguns once synced into a target repo:
  *
- *   - `paths:` frontmatter in a `rules/` LIBRARY SOURCE — a vendoring-
- *     CONVENTION gate, not a loader-compatibility one. Since #795
- *     `rule-loader.mjs` accepts `paths:` as an alias for `globs:`, so such a
- *     rule IS glob-scoped; `globs:` stays the canonical form for a rule
- *     vendored out through the library (#742). See § Scope below — this probe
- *     never judges a repo's own consolidated `.claude/rules/` files.
+ *   - `frontmatter-not-at-top` — a `---` block preceded by anything (the
+ *     provenance comment, a blank line). Claude Code reads frontmatter only
+ *     from line 1 and reads only its `paths:` key, so such a rule silently
+ *     loads ALWAYS-ON in every consumer repo (#1449).
+ *   - `globs-paths-mismatch` — a library rule's frontmatter must carry
+ *     `globs:` AND `paths:` with the identical list (order-insensitive), or
+ *     neither. `paths:` is what Claude Code reads; `globs:` stays because
+ *     `rule-loader.mjs` prefers it (#742/#795). One key alone, or two
+ *     different lists, scopes the rule differently per loader.
  *   - Missing provenance header — `rules-sync.mjs` detects "plugin-owned vs.
- *     local override" purely by checking whether the first line starts with
- *     `PLUGIN_HEADER_PREFIX`. A source file missing that header gets
- *     mis-detected as a local override on the NEXT re-sync (it looks
- *     hand-authored), so the plugin can never update it again.
+ *     local override" via `isPluginOwnedContent()`: the header line starting
+ *     with `PLUGIN_HEADER_PREFIX` on line 1 (a rule without frontmatter) or as
+ *     the first non-blank line after a line-1 frontmatter block. A source file
+ *     missing it gets mis-detected as a local override on the NEXT re-sync (it
+ *     looks hand-authored), so the plugin can never update it again.
  *   - Unfilled placeholder tokens (`{{PROJECT_NAME}}`-style, `## TODO:
  *     Customize` headings, `<!-- TODO:` comments) leaking from an
  *     un-filled-in skeleton into a synced rule.
@@ -30,9 +34,10 @@
  * Stdlib-only ESM, with the same picomatch-with-fallback resolution pattern
  * as `rule-loader.mjs` (duplicated here rather than imported because those
  * helpers are module-private there — the *approach* is reused, not
- * reinvented). Frontmatter `globs:` extraction is NOT duplicated — this
- * module imports the already-exported `parseGlobsFrontmatter` from
- * `rule-loader.mjs` directly.
+ * reinvented). The globs-derived probes use the already-exported
+ * `parseGlobsFrontmatter` from `rule-loader.mjs` directly; only
+ * `globs-paths-mismatch` reads the two keys itself (`readScopeKeys`), because
+ * the loader merges them and cannot say which key carried which list.
  *
  * ## Scope: the `rules/` fleet library, never a repo's own `.claude/rules/`
  *
@@ -43,15 +48,14 @@
  * written target is never read back through the gate. The CLI's `--dir` is
  * operator-supplied and means that same library.
  *
- * This is load-bearing for `paths-frontmatter`: a repo's own CONSOLIDATED rules
- * under `.claude/rules/` are `paths:`-canonical by design, because Claude
- * Code's native loader reads ONLY `paths:` and treats a rule without it as
- * always-on (`validate/check-rules.mjs` #1108; `docs/rule-authoring.md`
- * § Consolidated rules point 3). Measured 2026-09-16 in this repo: 10
- * path-scoped rule files there, 9 of them `paths:`-only. Pointing `--dir` at
- * such a tree would emit findings that, if obeyed, UNDO that consolidation —
- * which is also why `check-rules.mjs` deliberately does not duplicate this
- * probe for `.claude/rules/`.
+ * This matters for `globs-paths-mismatch` and the provenance probe: they encode
+ * the LIBRARY convention (both scope keys, a provenance header). A repo's own
+ * CONSOLIDATED rules under `.claude/rules/` are `paths:`-only and header-free
+ * by design, because Claude Code's native loader reads ONLY `paths:`
+ * (`validate/check-rules.mjs` #1108; `docs/rule-authoring.md` § Consolidated
+ * rules point 3). Measured 2026-09-16 in this repo: 10 path-scoped rule files
+ * there, 9 of them `paths:`-only. Pointing `--dir` at such a tree reports
+ * findings about a convention those files were never meant to follow.
  *
  * @module validate-vendored-rules
  */
@@ -61,7 +65,7 @@ import { join, resolve, relative, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { parseGlobsFrontmatter } from './rule-loader.mjs';
+import { parseGlobsFrontmatter, FRONTMATTER_NOT_AT_TOP } from './rule-loader.mjs';
 import { isMainModule } from './is-main-module.mjs';
 
 // Mirrors rules-sync.mjs's exported PLUGIN_HEADER_PREFIX (rules-sync.mjs
@@ -137,21 +141,26 @@ function matchGlob(filePath, globPattern) {
 // Frontmatter helpers
 // ---------------------------------------------------------------------------
 
+// A line that may precede a MISPLACED frontmatter opener: blank, or one
+// complete single-line HTML comment (the provenance header's shape).
 const HEADER_LINE_RE = /^[ \t]*(?:<!--.*-->)?[ \t]*$/;
 
 /**
- * Finds a YAML frontmatter block delimited by `---` lines.
+ * Locates a YAML frontmatter block delimited by `---` lines.
  *
- * Mirrors rule-loader.mjs's header-tolerant frontmatter shape for the `paths:`
- * authoring guard: a leading run of blank lines and/or single-line HTML
- * comments may precede the opening `---`.
+ * Deliberately tolerant of a leading run of blank lines and/or single-line
+ * HTML comments before the opener — NOT because such a block is valid (Claude
+ * Code reads frontmatter only when `---` is line 1, and `rule-loader.mjs`
+ * no longer tolerates the prefix either), but so `frontmatter-not-at-top` can
+ * SEE the misplaced block and report it. Callers that judge what a loader
+ * reads must check `startLine === 0` first.
  *
- * @param {string} content
- * @returns {{ body: string, startLine: number } | null} startLine is the
- *   0-based file-line index of the opening `---`.
+ * @param {string[]} lines - file content split on `\r?\n`
+ * @returns {{ bodyLines: string[], startLine: number, endLine: number } | null}
+ *   startLine / endLine are the 0-based file-line indices of the opening and
+ *   closing `---`.
  */
-function extractFrontmatter(content) {
-  const lines = content.split(/\r?\n/);
+function locateFrontmatter(lines) {
   let startLine = 0;
   while (startLine < lines.length && HEADER_LINE_RE.test(lines[startLine])) {
     startLine++;
@@ -159,22 +168,93 @@ function extractFrontmatter(content) {
   if (lines[startLine] !== '---') return null;
   for (let i = startLine + 1; i < lines.length; i++) {
     if (lines[i] === '---') {
-      return { body: lines.slice(startLine + 1, i).join('\n'), startLine };
+      return { bodyLines: lines.slice(startLine + 1, i), startLine, endLine: i };
     }
   }
   return null;
 }
 
 /**
- * Line number (1-based, absolute within the file) of a match at `bodyIndex`
- * inside the frontmatter body.
- * @param {number} startLine - 0-based file-line index of the opening `---`
- * @param {string} body - frontmatter body text
- * @param {number} bodyIndex - character offset within body
- * @returns {number}
+ * True when `content` carries the plugin provenance header in one of the two
+ * positions the vendoring convention allows (#1449):
+ *
+ *   (a) line 1 — a rule WITHOUT frontmatter, and also every vendored copy
+ *       written before #1449 (header on line 1, frontmatter after it);
+ *   (b) the first non-blank line after the closing `---` of a frontmatter
+ *       block that opens on line 1 — the current format for a rule WITH
+ *       frontmatter, because Claude Code reads `paths:` only from a line-1
+ *       block.
+ *
+ * This is the ownership predicate `rules-sync.mjs` uses to tell a
+ * plugin-owned vendored copy (rewrite it) from a local rule (preserve it), and
+ * the `provenance-header` probe's acceptance test. Accepting (a) with a
+ * frontmatter after it keeps old-format consumer copies plugin-owned, so the
+ * next sync REWRITES them into the new format instead of preserving them
+ * forever. Lives here rather than in rules-sync.mjs because rules-sync.mjs
+ * imports from this module; it re-exports this function.
+ *
+ * @param {string} content - raw rule file content
+ * @returns {boolean}
  */
-function lineWithinFrontmatter(startLine, body, bodyIndex) {
-  return startLine + 1 + body.slice(0, bodyIndex).split('\n').length;
+export function isPluginOwnedContent(content) {
+  const lines = content.split(/\r?\n/);
+  if ((lines[0] ?? '').startsWith(PLUGIN_HEADER_PREFIX)) return true;
+  const fm = locateFrontmatter(lines);
+  if (!fm || fm.startLine !== 0) return false;
+  const next = lines.slice(fm.endLine + 1).find((l) => l.trim() !== '');
+  return next !== undefined && next.startsWith(PLUGIN_HEADER_PREFIX);
+}
+
+/**
+ * Strips one pair of surrounding quotes, as rule-loader.mjs does for list items.
+ * @param {string} s
+ * @returns {string}
+ */
+function unquoteItem(s) {
+  return s.trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Reads the `globs:` and `paths:` sequences of a frontmatter body EACH ON ITS
+ * OWN. `parseGlobsFrontmatter()` cannot answer this: it merges the two keys by
+ * design (`globs:` wins, `paths:` is discarded), so it cannot say which key
+ * carried which list. Accepts the three value shapes rule-loader.mjs accepts —
+ * indented block list, flow list `[a, b]`, single inline value.
+ *
+ * @param {string[]} bodyLines - frontmatter lines between the `---` markers
+ * @returns {{ globs?: { values: string[], index: number }, paths?: { values: string[], index: number } }}
+ *   `index` is the 0-based body line of the key.
+ */
+function readScopeKeys(bodyLines) {
+  /** @type {{ globs?: { values: string[], index: number }, paths?: { values: string[], index: number } }} */
+  const found = {};
+  let active = null;
+  bodyLines.forEach((raw, index) => {
+    const line = raw.replace(/\s+$/, '');
+    if (line === '' || /^\s*#/.test(line)) return;
+    if (active) {
+      const item = /^\s+-\s+(.*)$/.exec(line);
+      if (item) {
+        found[active].values.push(unquoteItem(item[1]));
+        return;
+      }
+      active = null;
+    }
+    const key = /^(globs|paths):\s*(.*)$/.exec(line);
+    if (!key) return;
+    const [, name, value] = key;
+    let values = [];
+    if (value === '') {
+      active = name;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      const inner = value.slice(1, -1).trim();
+      values = inner === '' ? [] : inner.split(',').map(unquoteItem);
+    } else {
+      values = [unquoteItem(value)];
+    }
+    found[name] = { values, index };
+  });
+  return found;
 }
 
 /**
@@ -463,7 +543,7 @@ const FOREIGN_TOKEN_RE = /[A-Z][a-z]+[A-Z]/;
 
 /**
  * @typedef {object} RuleViolation
- * @property {string} rule - check id (paths-frontmatter | provenance-header | placeholder | zero-match-globs | foreign-glob)
+ * @property {string} rule - check id (frontmatter-not-at-top | globs-paths-mismatch | provenance-header | placeholder | zero-match-globs | foreign-glob)
  * @property {'error'|'warn'} severity
  * @property {string} message
  * @property {number} [line] - 1-based line number, when known
@@ -486,52 +566,94 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
   /** @type {RuleViolation[]} */
   const violations = [];
 
-  // ---- paths-frontmatter (error) ----
-  const fm = extractFrontmatter(content);
-  if (fm) {
-    const pathsMatch = /^paths:/m.exec(fm.body);
-    if (pathsMatch) {
+  const lines = content.split(/\r?\n/);
+  const fm = locateFrontmatter(lines);
+
+  // ---- frontmatter-not-at-top (error) ----
+  // Claude Code reads frontmatter only when `---` is line 1. Anything before
+  // it (the provenance comment, a blank line) makes it see NO frontmatter, so
+  // a path-scoped rule loads ALWAYS-ON in every consumer repo, with no error.
+  // Two detectors, one verdict (BV-003): `locateFrontmatter` sees a block
+  // behind blank lines / single-line comments (the provenance shape);
+  // `parseGlobsFrontmatter` (the loader — the same code the wave injector
+  // runs) additionally sees one behind ANY text, e.g. a heading. Either
+  // signal is the defect; the finding is reported once.
+  const loaderDefect = parseGlobsFrontmatter(content).defect === FRONTMATTER_NOT_AT_TOP;
+  if ((fm && fm.startLine !== 0) || (!(fm && fm.startLine === 0) && loaderDefect)) {
+    const openerLine = fm ? fm.startLine + 1 : lines.findIndex((l) => l === '---') + 1;
+    violations.push({
+      rule: 'frontmatter-not-at-top',
+      severity: 'error',
+      message:
+        `${relPath}: the frontmatter block opens on line ${openerLine}, not line 1. ` +
+        `Claude Code reads frontmatter only when '---' is the very first line, so it sees none ` +
+        `here and loads this rule always-on, ignoring its 'paths:' scope. Move the block to the ` +
+        `top; the provenance header goes on the first line after the closing '---'.`,
+      line: 1,
+    });
+  }
+
+  // ---- globs-paths-mismatch (error) ----
+  // Judged only on a line-1 block: a misplaced block is read by no loader,
+  // and frontmatter-not-at-top already reports it.
+  if (fm && fm.startLine === 0) {
+    const { globs, paths } = readScopeKeys(fm.bodyLines);
+    // body index i sits on 1-based file line i + 2 when the opener is line 1.
+    const keyLine = (k) => k.index + 2;
+    let detail = null;
+    let line;
+    if (globs && !paths) {
+      detail =
+        `declares 'globs:' but no 'paths:'. Claude Code reads only 'paths:', so it loads this ` +
+        `rule always-on. Add 'paths:' carrying the identical list.`;
+      line = keyLine(globs);
+    } else if (paths && !globs) {
+      detail =
+        `declares 'paths:' but no 'globs:'. rule-loader.mjs prefers 'globs:' (#742/#795); a ` +
+        `rule vendored out through the plugin's rules/ library carries both keys. Add 'globs:' ` +
+        `carrying the identical list. This does NOT apply to a repo's own consolidated ` +
+        `.claude/rules/ files — those are paths:-only by design and this gate never scans them.`;
+      line = keyLine(paths);
+    } else if (globs && paths) {
+      const g = new Set(globs.values);
+      const p = new Set(paths.values);
+      const onlyGlobs = [...g].filter((x) => !p.has(x));
+      const onlyPaths = [...p].filter((x) => !g.has(x));
+      if (onlyGlobs.length > 0 || onlyPaths.length > 0) {
+        detail =
+          `'globs:' and 'paths:' carry different lists (only in globs: ${JSON.stringify(onlyGlobs)}; ` +
+          `only in paths: ${JSON.stringify(onlyPaths)}). Claude Code scopes by 'paths:', ` +
+          `rule-loader.mjs by 'globs:', so the two would activate this rule on different files. ` +
+          `Make both lists identical.`;
+        line = keyLine(globs.index <= paths.index ? globs : paths);
+      }
+    }
+    if (detail) {
       violations.push({
-        rule: 'paths-frontmatter',
+        rule: 'globs-paths-mismatch',
         severity: 'error',
-        // NOTE (#795 / corrected 2026-07-25): the previous wording claimed rule-loader.mjs
-        // does not recognize `paths:` and that such a rule loads always-on. Both are false
-        // since #795 — `rule-loader.mjs:275` accepts `paths` alongside `globs`, and `:313`
-        // treats it as a fallback alias (`globs:` wins silently when both are present), so a
-        // `paths:`-only rule IS glob-scoped. The probe itself stays: it enforces the canonical
-        // vendoring form, which is a convention gate, not a loader-compatibility gate. That
-        // intent survives #795 and is the subject of the #742 fleet canonicalisation sweep.
-        // SCOPE (2026-09-16): this fires only over `rules/` library sources — the module doc's
-        // § Scope section names every caller. Do NOT re-point it at a repo's own
-        // `.claude/rules/`: those consolidated files are `paths:`-canonical and obeying this
-        // remedy there would undo the consolidation (docs/rule-authoring.md point 3).
-        message:
-          `${relPath}: frontmatter declares a top-level 'paths:' key. It is a recognized alias ` +
-          `for 'globs:' (issue #795), so the rule does load glob-scoped — but 'globs:' is the ` +
-          `canonical form for a rule VENDORED OUT through the plugin's rules/ library, which is ` +
-          `this probe's only population. Migrate to 'globs:' (see issue #742). This does NOT ` +
-          `apply to a repo's own consolidated .claude/rules/ files — those are paths:-canonical ` +
-          `(Claude Code's native loader reads only 'paths:') and this gate never scans them.`,
-        line: lineWithinFrontmatter(fm.startLine, fm.body, pathsMatch.index),
+        message: `${relPath}: frontmatter ${detail}`,
+        line,
       });
     }
   }
 
   // ---- provenance-header (error, opt-in) ----
-  if (requireProvenance) {
-    const firstLine = content.split('\n')[0] ?? '';
-    if (!firstLine.startsWith(PLUGIN_HEADER_PREFIX)) {
-      violations.push({
-        rule: 'provenance-header',
-        severity: 'error',
-        message:
-          `${relPath}: missing provenance header — the first line must start with ` +
-          `${JSON.stringify(PLUGIN_HEADER_PREFIX)} (see rules-sync.mjs PLUGIN_HEADER_PREFIX). ` +
-          `Without it, rules-sync.mjs mis-detects this file as a local override on the next re-sync ` +
-          `and will never update it again.`,
-        line: 1,
-      });
-    }
+  // A header on line 1 followed by a frontmatter is accepted HERE (the file
+  // has a header, and isPluginOwnedContent must keep old vendored copies
+  // plugin-owned); frontmatter-not-at-top reports that shape, once.
+  if (requireProvenance && !isPluginOwnedContent(content)) {
+    violations.push({
+      rule: 'provenance-header',
+      severity: 'error',
+      message:
+        `${relPath}: missing provenance header — a line starting with ` +
+        `${JSON.stringify(PLUGIN_HEADER_PREFIX)} (see rules-sync.mjs PLUGIN_HEADER_PREFIX) must ` +
+        `stand either on line 1 (a rule without frontmatter) or on the first non-blank line after ` +
+        `the closing '---' of a frontmatter that opens on line 1. Without it, rules-sync.mjs ` +
+        `mis-detects this file as a local override on the next re-sync and will never update it again.`,
+      line: 1,
+    });
   }
 
   // ---- placeholder (error) — skip matches inside fenced code blocks ----
@@ -569,6 +691,9 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
   }
 
   // ---- globs: derived checks (zero-match-globs, foreign-glob) ----
+  // Driven by the loader's own parse, so these judge exactly the list
+  // rule-loader.mjs will scope by (`globs:`, else its `paths:` alias). On a
+  // misplaced block that yields no globs — frontmatter-not-at-top covers it.
   let globs;
   try {
     ({ globs } = parseGlobsFrontmatter(content));

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

@@ -11,6 +11,10 @@
  *     records that between them said nothing happened (#1151). Its count is
  *     carried by the run event's `skipped` total and `action_breakdown`, so the
  *     class stays measured — only its per-line locators are gone.
+ *     `skipped-duplicate-session` (#1291) is one of these per-entry records:
+ *     a `--kind session` line whose `session_id` a later line in the same
+ *     source superseded, so it was never dispatched. It carries `record_id`
+ *     and `line` and never `path` — no target file exists for it.
  *   - `orchestrator.vault.mirror_run_completed` — ONE record per CLI run,
  *     carrying the DENOMINATOR (`total` plus the per-class counts).
  *
@@ -162,7 +166,10 @@ export async function emitMirrorEvent({
  * @param {number} opts.updated — entries whose action was `updated`.
  * @param {number} opts.skipped — entries skipped for a NON-failure reason
  *   (`skipped-noop`, `skipped-handwritten`, `skipped-quality-low`,
- *   `skipped-collision-resolved`, `skipped-abandoned`).
+ *   `skipped-collision-resolved`, `skipped-abandoned`,
+ *   `skipped-duplicate-session`). The last one (#1291) is what keeps
+ *   `created + updated + skipped + failed === total` true for a `--kind
+ *   session` run whose dedup pass collapsed a duplicate `session_id` line.
  * @param {number} opts.failed — entries that produced `skipped-invalid`
  *   (validation error or mapper crash). Split out from `skipped` because these
  *   are the runs where a session silently ends up WITHOUT its vault note.

package/scripts/lib/vault-status/board-writer.mjs

@@ -12,8 +12,9 @@
  *
  * Telemetry: every {@link mirrorBoard} call — and therefore every
  * {@link sweepBoard} call — emits exactly ONE {@link BOARD_EVENT} record,
- * including the no-op paths (`skipped-vault-disabled`, `skipped-handwritten`,
- * `skipped-noop`, `skipped-write-failed`). Those are the states that previously
+ * including the no-op paths (`skipped-vault-disabled`,
+ * `skipped-vault-not-canonical`, `skipped-handwritten`, `skipped-noop`,
+ * `skipped-write-failed`). Those are the states that previously
  * looked identical to a healthy write from outside the process. Emission is
  * best-effort and can never fail a board write.
  *
@@ -43,7 +44,8 @@
  *   2. Defense-in-depth: writeBoard hard-refuses to touch `_overview.md`
  *      (sven-owned, must NEVER be written by this generator).
  *
- * No console noise — library code. Plain Node ESM. No external deps.
+ * No console noise — library code — except the one stderr line on a
+ * canonical-vault refusal (#1450). Plain Node ESM. No external deps.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
@@ -60,6 +62,8 @@ import { enumerateCandidates } from '../dispatcher/enumerate.mjs';
 import { atomicWriteWithBackup } from '../io.mjs';
 import { withBoardLock } from './board-lock.mjs';
 import { expandTilde } from '../common.mjs';
+import { checkCanonicalVault, describeOriginForLog } from '../named-vault-resolver.mjs';
+import { loadHostPaths } from '../config/host-paths.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned board files. */
 export const GENERATOR_MARKER = 'session-orchestrator-active-sessions@1';
@@ -825,6 +829,8 @@ async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows
  * Vault path assertion (Epic #673 safety): the resolved vault dir MUST live
  * under $HOME — a vault outside the home tree is refused as `skipped-vault-disabled`
  * so a misconfigured path can never drive a write into an arbitrary location.
+ * It must also be a canonical Meta-Vault ({@link checkCanonicalVault}, #1450):
+ * otherwise `skipped-vault-not-canonical`, nothing written, no lock, dry-run included.
  *
  * @param {object} opts
  * @param {string} opts.repoRoot — the repo whose row is being updated.
@@ -840,11 +846,14 @@ async function emitBoardEvent({ repoRoot, caller, action, path: outputPath, rows
  * @param {Date} [opts.now]
  * @param {boolean} [opts.dryRun]
  * @param {object} [opts.fs] — injectable fs for tests.
- * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [opts.hostPaths]
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object,
+ *   readOriginUrl?: (vaultDir: string) => string }} [opts.hostPaths]
  *   — forwarded verbatim to {@link parseSessionConfig}'s `hostPaths` DI seam (issue #653).
+ *   The same ctx feeds {@link checkCanonicalVault}; `readOriginUrl` replaces its
+ *   `git remote get-url origin` read (tests only — tmp vaults have no origin).
  *   Tests MUST pass a hermetic ctx (e.g. `{ env: {}, ownerConfig: undefined }`) when
  *   asserting a fixture's committed `vault-dir` — omitting it reads the REAL host
- *   `owner.yaml`, whose `paths.vault-dir` override (if set) wins over the fixture value
+ *   `owner.yaml`, whose `vault-dirs:` cwd match or `paths.vault-dir` override (if set) wins over the fixture value
  *   and bleeds into the assertion (issue #783). Production callers omit this — the
  *   default (real owner.yaml resolution) is the correct host-local behavior there.
  * @returns {Promise<{ result: { action: string, path?: string }, rows?: number,
@@ -861,10 +870,19 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
   }
 
   // Read + parse Session Config. Any failure → silent no-op.
+  // The host context is resolved ONCE here and reused by the canonical-vault
+  // guard below: loadOwnerConfig() has no cache and its section-drop WARNs are
+  // not rate-limited, so a second load would print every WARN of a broken
+  // owner.yaml twice per board write (#1450 follow-up). The config file is read
+  // BEFORE owner.yaml — the order narrative-mirror.mjs shares (#1479); vault-dir
+  // precedence is applied in parseSessionConfig, so the order changes only
+  // whether a repo without a config file reads owner.yaml at all.
   let config;
+  let hostCtx;
   try {
     const text = await readConfigFile(repoRoot);
-    config = parseSessionConfig(text, { hostPaths });
+    hostCtx = hostPaths ?? loadHostPaths();
+    config = parseSessionConfig(text, { hostPaths: hostCtx });
   } catch {
     return { result: { action: 'skipped-vault-disabled' } };
   }
@@ -886,6 +904,24 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
     return { result: { action: 'skipped-vault-disabled' } };
   }
 
+  // Safety: the vault must be a canonical Meta-Vault (#1450) — the same guard
+  // vault-mirror applies, so a vault-dir that resolved to a FOREIGN vault can
+  // never receive the board. Reuses the `hostCtx` the config parse used, so a
+  // hermetic ctx never reads the real owner.yaml and owner.yaml is loaded at
+  // most once. Runs before the dry-run branch and the lock: fail-closed.
+  const canonical = checkCanonicalVault({
+    vaultDir: expandedVault,
+    ownerConfig: hostCtx.ownerConfig,
+    env: hostCtx.env ?? process.env,
+    readOriginUrl: hostCtx.readOriginUrl,
+  });
+  if (!canonical.ok) {
+    process.stderr.write(
+      `vault-status board: refusing to write — vault is not the canonical Meta-Vault (expected git origin ending in one of: ${canonical.expected.join(', ')}; got ${describeOriginForLog(canonical.got) || 'no git origin'})\n`,
+    );
+    return { result: { action: 'skipped-vault-not-canonical' } };
+  }
+
   // `vault-name` (#660) overrides the git-derived repo slug for per-project
   // vault namespacing. Without it `collectRows` falls back to
   // `path.basename(repoRoot)`, so a repo whose directory name differs from its
@@ -1112,10 +1148,10 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
  * Public {@link mirrorBoardInner} wrapper that emits exactly ONE
  * {@link BOARD_EVENT} per call — on EVERY path, no-ops included.
  *
- * The wrapper exists so the emit cannot be forgotten: the six return points
- * inside {@link mirrorBoardInner} (five `skipped-vault-disabled` guards plus
- * whatever {@link writeBoard} decides) all funnel through here, and so does the
- * seventh someone adds next. Emitting per-return instead would leave each new
+ * The wrapper exists so the emit cannot be forgotten: the seven return points
+ * inside {@link mirrorBoardInner} (five `skipped-vault-disabled` guards, the
+ * `skipped-vault-not-canonical` guard, plus whatever {@link writeBoard}
+ * decides) all funnel through here, and so does the eighth someone adds next. Emitting per-return instead would leave each new
  * early return silent by default — which is the exact defect being fixed.
  *
  * A THROW from the inner function is deliberately NOT converted into an event:
@@ -1276,7 +1312,8 @@ export function buildSweepRepos(candidates, { thisRepoRoot } = {}) {
  * @param {object} [opts.deps] — injectable deps for {@link enumerateCandidates}
  *   (test seam: `readdirSync`, `existsSync`, `readLock`, `isLockLive`,
  *   `getCrossRepoProjects`, `validatePathInsideProject`, `now`).
- * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object }} [opts.hostPaths]
+ * @param {{ env?: Record<string, string|undefined>, ownerConfig?: object,
+ *   readOriginUrl?: (vaultDir: string) => string }} [opts.hostPaths]
  *   — forwarded verbatim to every {@link mirrorBoard} call below (both the happy-path
  *   and the enumeration-failure-fallback path), which in turn forwards it to
  *   {@link parseSessionConfig}'s `hostPaths` DI seam (issue #653/#783). See

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

@@ -44,6 +44,8 @@ import { validatePathInsideProject } from '../path-utils.mjs';
 import { createSecretValueMasker } from '../secret-masker.mjs';
 import { expandTilde } from '../common.mjs';
 import { readVaultSlug } from '../vault-yaml.mjs';
+import { checkCanonicalVault, describeOriginForLog } from '../named-vault-resolver.mjs';
+import { loadHostPaths } from '../config/host-paths.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned narrative files. */
 export const GENERATOR_MARKER = 'session-orchestrator-vault-status-narrative@1';
@@ -763,9 +765,10 @@ async function emitMaskerEvent({ repoRoot, needleCount, hits, dryRun }) {
  * before any write.
  *
  * THIS FUNCTION WRITES TO THE OPERATOR'S REAL VAULT UNLESS YOU STOP IT. `vault-dir`
- * resolves HOST-LOCALLY — `SO_VAULT_DIR` > `owner.yaml` `paths.vault-dir` >
- * committed Session Config (`scripts/lib/config/host-paths.mjs`) — so the literal
- * value in a CLAUDE.md you just wrote into a tmp dir LOSES to both overrides. A
+ * resolves HOST-LOCALLY — `SO_VAULT_DIR` > `owner.yaml` `vault-dirs:` cwd match >
+ * `owner.yaml` `paths.vault-dir` > committed Session Config (`resolveVaultDir` in
+ * `scripts/lib/config.mjs`) — so the literal value in a CLAUDE.md you just wrote
+ * into a tmp dir LOSES to every override. A
  * probe that passes a synthetic `repoRoot` and nothing else has already written
  * into the live vault once (#1025 review). Any caller that must not touch the real
  * vault passes `hostPaths: { env: {}, ownerConfig: undefined }` (see below),
@@ -777,13 +780,16 @@ async function emitMaskerEvent({ repoRoot, needleCount, hits, dryRun }) {
  *   now?: Date,
  *   dryRun?: boolean,
  *   fs?: object,
- *   hostPaths?: { env?: Record<string, string|undefined>, ownerConfig?: object },
+ *   hostPaths?: { env?: Record<string, string|undefined>, ownerConfig?: object,
+ *     readOriginUrl?: (vaultDir: string) => string },
  * }} opts
  *   `hostPaths` is forwarded verbatim to {@link parseSessionConfig}'s `hostPaths` DI
- *   seam (issue #653). Tests MUST pass a hermetic ctx (e.g. `{ env: {}, ownerConfig:
+ *   seam (issue #653). The same ctx feeds {@link checkCanonicalVault} (#1450);
+ *   `readOriginUrl` replaces its `git remote get-url origin` read (tests only —
+ *   tmp vaults have no origin). Tests MUST pass a hermetic ctx (e.g. `{ env: {}, ownerConfig:
  *   undefined }`) when asserting a fixture's committed `vault-dir` — omitting it reads
- *   the REAL host `owner.yaml`, whose `paths.vault-dir` override (if set) wins over the
- *   fixture value and bleeds into the assertion (issue #783). Production callers omit
+ *   the REAL host `owner.yaml`, whose `vault-dirs:` cwd match or `paths.vault-dir`
+ *   override (if set) wins over the fixture value and bleeds into the assertion (issue #783). Production callers omit
  *   this — the default (real owner.yaml resolution) is the correct host-local behavior.
  * @returns {Promise<{ action: string, path?: string }>}
  */
@@ -829,7 +835,7 @@ export async function mirrorNarrative(opts) {
  * Split out so that the two emit sites in `mirrorNarrative` (the narrative
  * event AND, since #1028, the masker event) each cover EVERY outcome from
  * ONE call: a future early return added inside this function is telemetered
- * by construction, whereas hand-placing an emit beside each of the seven
+ * by construction, whereas hand-placing an emit beside each of the eight
  * `return`s makes "forgot the new one" the default failure. The `chars` companion travels beside the result
  * rather than inside it because the returned object is a PUBLIC shape that
  * callers (and tests) compare with `toEqual` — adding a key there would be an
@@ -855,10 +861,19 @@ async function runNarrativeMirror(opts) {
   const masker = createSecretValueMasker(process.env);
 
   // Read Session Config (CLAUDE.md / AGENTS.md) and resolve vault settings.
+  // The host context is loaded ONCE and shared by the Session Config parse and
+  // the canonical-vault guard below, so owner.yaml is read a single time per run.
+  // Order (#1479, same as board-writer.mjs): config file first, owner.yaml
+  // second. The `vault-dir` precedence (SO_VAULT_DIR > owner.yaml > committed)
+  // is applied inside parseSessionConfig, after both are in hand, so the order
+  // cannot change the resolved dir; it only spares a repo without a config file
+  // the owner.yaml read and its section-drop WARNs on a run that skips anyway.
   let config;
+  let hostCtx;
   try {
     const configText = await readConfigFile(repoRoot);
-    config = parseSessionConfig(configText, { hostPaths });
+    hostCtx = hostPaths ?? loadHostPaths();
+    config = parseSessionConfig(configText, { hostPaths: hostCtx });
   } catch {
     return { result: { action: 'skipped-vault-disabled' }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
@@ -900,6 +915,22 @@ async function runNarrativeMirror(opts) {
   }
 
   const vaultDir = path.resolve(expandTilde(rawVaultDir));
+
+  // #1450: same shared guard as board-writer.mjs and scripts/vault-mirror.mjs —
+  // refuse a vault-dir whose git origin is not a canonical Meta-Vault. The
+  // stderr line names the expected suffixes and the origin, never the vault
+  // path itself.
+  const canonical = checkCanonicalVault({
+    vaultDir,
+    ownerConfig: hostCtx.ownerConfig,
+    env: hostCtx.env ?? process.env,
+    readOriginUrl: hostCtx.readOriginUrl,
+  });
+  if (!canonical.ok) {
+    process.stderr.write(`narrative-mirror: refusing to write — vault is not the canonical Meta-Vault (expected git origin ending in one of: ${canonical.expected.join(', ')}; got ${describeOriginForLog(canonical.got) || 'no git origin'})\n`);
+    return { result: { action: 'skipped-vault-not-canonical' }, needleCount: masker.needleCount, hits: 0, dryRun };
+  }
+
   const candidateSlug = subjectToSlug(repoName) || 'unknown';
   // 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