session-orchestrator 5.3.0 → 5.4.0

package/scripts/lib/learnings/schema.mjs

@@ -230,17 +230,19 @@ export class ValidationError extends Error {
  * Throws ValidationError on contract violations. Does NOT mutate input.
  *
  * @param {object} entry — candidate learning
- * @param {{ legacyTolerant?: boolean }} [opts] — GitLab #386. When `true`, a
+ * @param {{ legacyTolerant?: boolean }} [opts] — EventDrop #386. When `true`, a
  *   value `normalizeLearning()` already passes through UNCHECKED (or merely
  *   DEFAULTED, never validated) on read is no longer rejected here either:
  *   an out-of-enum `schema_version` (measured against the real EventDrop.at
  *   store: 3 live records carry `schema_version: 2`), the
  *   LEGACY_REQUIRED_FIELDS presence check, the `confidence` range/type check
  *   when NO `confidence` key is present, and the `scope`/`host_class`/
- *   `anonymized` shape checks (measured live: a record with `scope:
- *   "src/components/landing/mobile-sticky-cta.tsx"` — a producer bug that
- *   wrote a file path into the scope column, which `normalizeLearning` never
- *   validates and therefore never rejects). A field that IS present keeps
+ *   `anonymized`/`file_paths` shape checks (measured live: a record whose `scope` held a
+ *   file path — e.g. a repo-relative component path such as
+ *   `src/components/sample/sticky-cta.tsx` (the measured value is not
+ *   reproduced here) — a producer bug that wrote a file path into the scope
+ *   column, which `normalizeLearning` never validates and therefore never
+ *   rejects). A field that IS present keeps
  *   being validated regardless when its DATA TYPE can be silently corrupted
  *   by a JSON round-trip (a present-but-malformed `confidence` still throws
  *   — see io.mjs #662): this option relaxes "you must HAVE a valid value",
@@ -296,9 +298,11 @@ export function validateLearning(entry, { legacyTolerant = false } = {}) {
   // scope/host_class/anonymized: `normalizeLearning()` only DEFAULTS an
   // absent value (`d.scope ?? 'local'`, etc.) on read — it never validates a
   // PRESENT one, so a corrupt legacy value round-trips silently today
-  // (measured live in production: a record with `scope:
-  // "src/components/landing/mobile-sticky-cta.tsx"` — evidently a producer
-  // bug that wrote a file path into the scope column). All three checks are
+  // (measured live in production: a record whose `scope` held a file path —
+  // e.g. a repo-relative component path such as
+  // `src/components/sample/sticky-cta.tsx` (the measured value is not
+  // reproduced here) — evidently a producer bug that wrote a file path into
+  // the scope column). All three checks are
   // therefore skipped under legacyTolerant. Unlike `confidence` (a number,
   // where `NaN`/`Infinity` are non-JSON-safe and silently become `null`
   // across a JSON round-trip — the #662 concern), a string/string-or-null/
@@ -319,6 +323,24 @@ export function validateLearning(entry, { legacyTolerant = false } = {}) {
     throw new ValidationError(`anonymized must be boolean, got: ${typeof anonymized}`);
   }
 
+  // file_paths (GitLab #1447): when present, an array of repo-relative path
+  // strings — a bare string (`file_paths: "src/x.ts"`) is the producer slip
+  // this rejects; every reader iterates it as a list. `null` reads as absent,
+  // as in migrateLegacyLearning. Skipped under legacyTolerant like the shape
+  // checks above: the read funnel passes the value through unchecked.
+  const filePaths = entry.file_paths;
+  if (!legacyTolerant && filePaths !== undefined && filePaths !== null) {
+    if (!Array.isArray(filePaths)) {
+      throw new ValidationError(`file_paths must be an array of repo-relative paths, got: ${typeof filePaths}`);
+    }
+    const badIndex = filePaths.findIndex((p) => !isRepoRelativePathEntry(p));
+    if (badIndex !== -1) {
+      throw new ValidationError(
+        `file_paths[${badIndex}] must be a non-empty repo-relative path (not absolute, no '..' segment), got: ${JSON.stringify(filePaths[badIndex])}`
+      );
+    }
+  }
+
   // Privacy contract — NEVER relaxed, legacyTolerant or not: an out-of-enum
   // `scope` (garbage or otherwise) is by definition not `'public'`, so this
   // pair only ever fires for a record that genuinely claims `scope: 'public'`
@@ -476,6 +498,85 @@ export function normalizeDialects(entry, { reserializeTimestamps = true } = {})
   return out;
 }
 
+/**
+ * File extensions a path-like `scope` value must end in to be treated as a
+ * repo-relative file path (GitHub #69 / GitLab #1446). Deliberately a closed
+ * list: a looser "contains a slash and a dot" test would also swallow values
+ * such as `infrastructure/docker-compose` or `node.js`.
+ */
+const PATH_SCOPE_EXT = /\.(mjs|cjs|js|jsx|ts|tsx|mts|cts|json|jsonl|md|mdx|ya?ml|toml|css|scss|html|vue|svelte|astro|py|rb|go|rs|swift|kt|java|sh|sql|prisma)$/i;
+
+/**
+ * Strict predicate: is `s` a repo-relative file path (at least one directory
+ * segment, no `..`, no empty segment, a known source/doc extension)? Rejects
+ * canonical scopes, absolute and home-relative paths, Windows drive paths,
+ * URLs, and anything containing whitespace.
+ *
+ * @param {unknown} s — candidate `scope` value
+ * @returns {boolean}
+ */
+function looksLikeRepoRelativePath(s) {
+  if (typeof s !== 'string' || VALID_SCOPES.includes(s) || s.length > 512) return false;
+  if (/\s/.test(s) || /^[/~]/.test(s) || /^[A-Za-z]:[\\/]/.test(s) || s.includes('://')) return false;
+  const segs = s.split('/');
+  if (segs.length < 2 || segs.includes('..') || segs.includes('')) return false;
+  return PATH_SCOPE_EXT.test(segs[segs.length - 1]);
+}
+
+/**
+ * Loose predicate for ONE `file_paths` entry (GitLab #1447): a non-empty string
+ * that is not absolute (`/`, `\`, `~`, a Windows drive), not a URL, and has no
+ * `..` segment. Deliberately looser than {@link looksLikeRepoRelativePath}:
+ * root-level files (`package.json`), directories (`docs/prd`) and globs
+ * (`skills/**`) are legitimate `file_paths` values.
+ *
+ * Exported because `scripts/memory-propose.mjs` gates `--file-paths` on the same
+ * rule: a proposal this predicate rejects would be queued, approved, and then
+ * refused by {@link validateLearning} at write time.
+ *
+ * @param {unknown} s — candidate entry
+ * @returns {boolean}
+ */
+export function isRepoRelativePathEntry(s) {
+  if (typeof s !== 'string' || s.trim() === '') return false;
+  if (/^[/\\~]/.test(s) || /^[A-Za-z]:[\\/]/.test(s) || s.includes('://')) return false;
+  return !s.split(/[\\/]/).includes('..');
+}
+
+const LEADING_DOT_SLASH = /^(?:\.\/)+/;
+
+/** Non-canonical STRING scopes {@link migrateLegacyLearning} coerces to `'local'`. */
+const LOCAL_ALIAS_SCOPES = new Set(['vault-tools', 'deep-sessions', 'wave-executor', 'coordinator']);
+
+/** Non-canonical STRING scopes {@link migrateLegacyLearning} coerces to `'private'`. */
+const PRIVATE_ALIAS_SCOPES = new Set(['project', 'repo']);
+
+/**
+ * Every word the migration reads as scope vocabulary. An array-scope entry
+ * equal to one of these is a scope word, never a path — the same reading the
+ * string branch gives it, so `['project']` is not turned into
+ * `file_paths: ['project']`.
+ */
+const SCOPE_WORDS = new Set([...VALID_SCOPES, ...LOCAL_ALIAS_SCOPES, ...PRIVATE_ALIAS_SCOPES]);
+
+/**
+ * The repo-relative paths a broken `scope` value carries, or `null` when it is
+ * not a path scope. A single string must pass the strict
+ * {@link looksLikeRepoRelativePath} (a lone string may be a scope word); an
+ * ARRAY is never scope vocabulary, so the loose per-entry predicate suffices
+ * there — an empty array yields `[]`. A leading `./` run is stripped from each
+ * path; case is kept (git paths are case-sensitive).
+ *
+ * @param {unknown} scope
+ * @returns {string[] | null}
+ */
+function pathScopeEntries(scope) {
+  if (looksLikeRepoRelativePath(scope)) return [scope.replace(LEADING_DOT_SLASH, '')];
+  if (!Array.isArray(scope)) return null;
+  const entries = scope.map((e) => (typeof e === 'string' ? e.replace(LEADING_DOT_SLASH, '') : e));
+  return entries.every((e) => isRepoRelativePathEntry(e) && !SCOPE_WORDS.has(e)) ? entries : null;
+}
+
 /**
  * Migrate a legacy learning record to the canonical schema_version:1 shape.
  * Idempotent — calling it on an already-canonical record is a safe no-op.
@@ -483,9 +584,32 @@ export function normalizeDialects(entry, { reserializeTimestamps = true } = {})
  * Alias precedence for insight: insight > description > recommendation > observation > lesson
  *
  * Producer dialects (`files`→`file_paths`, duplicate `session_id`, `last_seen`,
- * `next_review: null`) are normalized by {@link normalizeDialects} as the final
- * step. Timestamp FORMAT is deliberately NOT reformatted here (byte-exact
- * contract preserved); the read funnel + backfill canonicalize timestamps.
+ * `next_review: null`) are normalized by {@link normalizeDialects}. Timestamp
+ * FORMAT is deliberately NOT reformatted here (byte-exact contract preserved);
+ * the read funnel + backfill canonicalize timestamps.
+ *
+ * Broken-consumer-record coercions (GitHub #69 / GitLab #1446 — measured in a
+ * consumer store: 124 of 307 records failed strict validateLearning, 76 on
+ * `scope`, 48 on `schema_version`). Applied AFTER normalizeDialects, because
+ * coercing a path-like scope before the `files`→`file_paths` move would lose
+ * the legacy `files` data. Only this MIGRATION path coerces — the read funnel
+ * (normalizeLearning / normalizeDialects) stays pass-through by design:
+ *   - path-like `scope` (a repo-relative file path a producer wrote into the
+ *     scope column, see {@link looksLikeRepoRelativePath}) → appended to
+ *     `file_paths` (copied, never mutated in place; created when absent/null;
+ *     no duplicate) and `scope: 'private'`. A present non-array `file_paths`
+ *     leaves the record untouched — it stays invalid and is counted. A
+ *     leading `./` run is stripped first (GitLab #1447).
+ *   - array-typed `scope` (GitLab #1447) → the same move when every entry is a
+ *     repo-relative path ({@link isRepoRelativePathEntry}: root files, dirs and
+ *     globs included); an empty array → `scope: 'private'`. An array holding an
+ *     absolute path, a non-string or a scope word — canonical or one of the
+ *     aliases below, e.g. `['project']` — stays untouched (invalid, counted);
+ *     nothing is ever dropped.
+ *   - `scope: 'project'` / `scope: 'repo'` → `'private'`.
+ *   - `schema_version: '1'` (string) or `2` (number) → `1`.
+ * Each rule's output never re-matches that rule, so the whole function stays
+ * idempotent.
  *
  * The caller MUST still run validateLearning() on the result to confirm the
  * migrated record passes the full schema gate before writing.
@@ -534,8 +658,7 @@ export function migrateLegacyLearning(entry) {
     out.evidence = '';
   }
 
-  const COERCIBLE_SCOPES = new Set(['vault-tools', 'deep-sessions', 'wave-executor', 'coordinator']);
-  if (out.scope && !VALID_SCOPES.includes(out.scope) && COERCIBLE_SCOPES.has(out.scope)) {
+  if (out.scope && !VALID_SCOPES.includes(out.scope) && LOCAL_ALIAS_SCOPES.has(out.scope)) {
     out.scope = 'local';
   }
 
@@ -560,12 +683,37 @@ export function migrateLegacyLearning(entry) {
     out.schema_version = CURRENT_SCHEMA_VERSION;
   }
 
-  // Normalize producer dialects last (files→file_paths, session_id/last_seen/
+  // Normalize producer dialects (files→file_paths, session_id/last_seen/
   // next_review reconciliation) — schema_version is preserved by normalizeDialects.
   // reserializeTimestamps:false keeps migrateLegacyLearning's byte-exact timestamp
   // contract (it does schema/alias migration, not timestamp reformatting). The
   // READ funnel (normalizeLearning) and the backfill canonicalize timestamp format.
-  return normalizeDialects(out, { reserializeTimestamps: false });
+  const migrated = normalizeDialects(out, { reserializeTimestamps: false });
+
+  // Broken-consumer-record coercions (GitHub #69 / GitLab #1446, #1447) — AFTER
+  // normalizeDialects so a legacy `files` list has already become `file_paths`.
+  const pathEntries = pathScopeEntries(migrated.scope);
+  if (pathEntries !== null) {
+    const existing = migrated.file_paths;
+    if (existing === undefined || existing === null || Array.isArray(existing)) {
+      // Copy: normalizeDialects' shallow copy still shares the caller's array.
+      const filePaths = Array.isArray(existing) ? [...existing] : [];
+      for (const p of pathEntries) {
+        if (!filePaths.includes(p)) filePaths.push(p);
+      }
+      if (filePaths.length > 0) migrated.file_paths = filePaths;
+      migrated.scope = 'private';
+    }
+    // Present but not an array → leave untouched; the record stays invalid.
+  } else if (PRIVATE_ALIAS_SCOPES.has(migrated.scope)) {
+    migrated.scope = 'private';
+  }
+
+  if (migrated.schema_version === '1' || migrated.schema_version === 2) {
+    migrated.schema_version = CURRENT_SCHEMA_VERSION;
+  }
+
+  return migrated;
 }
 
 // Module-level dedupe sets for warnings (per-process).

package/scripts/lib/learnings/sizing-subject.mjs

@@ -9,8 +9,8 @@
  * 4-5. Before this module, the `effective-sizing` analyzer
  * (`skills/evolve/references/evolve-analyze-mode.md`) keyed its subject on
  * `session_type` alone (e.g. `deep-session-sizing`), so a 7-wave ultradeep
- * session and a 5-wave deep session landed on the SAME row — the over-delivery
- * median for one profile silently absorbed the other's.
+ * session and a 5-wave deep session landed on the SAME row — the agents-per-wave
+ * average for one profile silently absorbed the other's.
  *
  * Pure, stdlib-only, no imports, no clock, no fs.
  *

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

@@ -7,7 +7,8 @@
  * during a wave, reviewed by the memory-cleanup flow, and either accepted
  * (appended to learnings.jsonl) or discarded.
  *
- * Pure leaf module — imports only node:crypto. No I/O, no quota enforcement
+ * Pure module — imports only node:crypto and the pure learnings/schema.mjs
+ * (type registry, repo-relative path predicate). No I/O, no quota enforcement
  * (see store.mjs for those responsibilities).
  *
  * Canonical schema (schema_version: 1) — ALL required fields:
@@ -30,7 +31,8 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { LEARNING_TYPE_REGISTRY } from '../learnings/schema.mjs';
+
+import { isRepoRelativePathEntry, LEARNING_TYPE_REGISTRY } from '../learnings/schema.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -251,24 +253,28 @@ export function validateProposalRecord(record) {
   }
 
   // file_paths (optional, but if present must be a non-empty array of
-  // non-empty, newline-free, glob-metacharacter-free strings) — issue #900 C,
+  // repo-relative, newline-free, glob-metacharacter-free strings) — issue #900 C,
   // Q3-MED fix pass: a glob metacharacter (* ? [ ] { }) surviving this schema
   // gate would later reach emitter.mjs::globsFromFilePaths verbatim for a
   // top-level (dirname==='.') entry, effectively producing an always-on rule
   // glob (e.g. `file_paths: ['**']`). `createProposalRecord` never sets an
   // empty array (it omits the key), so a present-but-empty `[]` is itself a
   // signal of a malformed/tampered record — reject it explicitly.
+  // Repo-relative is the SAME predicate validateLearning applies at write time
+  // (isRepoRelativePathEntry): a record read back from proposals.jsonl is not
+  // re-validated before writeApproved → appendLearning, so an absolute, home-
+  // relative or URL entry must be refused here, not silently at promotion.
   if ('file_paths' in record) {
     const fp = record.file_paths;
     const isValidArray =
       Array.isArray(fp) &&
       fp.length > 0 &&
       fp.every(
-        (p) => typeof p === 'string' && p.length > 0 && !/[\r\n]/.test(p) && !/[*?[\]{}]/.test(p),
+        (p) => isRepoRelativePathEntry(p) && !/[\r\n]/.test(p) && !/[*?[\]{}]/.test(p),
       );
     if (!isValidArray) {
       errors.push(
-        'file_paths must be a non-empty array of non-empty, newline-free, glob-metacharacter-free strings when present',
+        'file_paths must be a non-empty array of repo-relative, newline-free, glob-metacharacter-free strings when present',
       );
     }
   }

package/scripts/lib/named-baseline-resolver.mjs

@@ -29,11 +29,21 @@
  *   also YIELDS to tier 1: when SO_BASELINE_PATH is set (non-blank), resolveNamedBaseline
  *   returns the null-fallback ({source:null}) so the caller's env tier wins.
  *
+ * ── Other sections (agents/vault#319) ────────────────────────────────────────
+ *
+ *   The same directory-prefix match serves any owner.yaml list of the shape
+ *   `{ path, match: { path-prefix } }`. `section` picks the list and `envKey` the
+ *   env var this tier yields to. The live second consumer is `vault-dirs:`
+ *   (section 'vault-dirs', envKey 'SO_VAULT_DIR'), driven by
+ *   `resolveVaultDir` in scripts/lib/config/host-paths.mjs. `name` is required
+ *   only for `baselines:` (the #819 contract); elsewhere it is optional and
+ *   defaults to `path`, which is what the ambiguity WARN then names.
+ *
  * ── Exports ──────────────────────────────────────────────────────────────────
  *
- *   parseBaselines(ownerConfig)
- *   matchBaselineForPath(absPath, baselines)
- *   resolveNamedBaseline({ cwd, ownerConfig, env })
+ *   parseBaselines(ownerConfig, section?)
+ *   matchBaselineForPath(absPath, baselines, section?)
+ *   resolveNamedBaseline({ cwd, ownerConfig, env, section?, envKey? })
  */
 
 import { normalize, sep } from 'node:path';
@@ -43,6 +53,9 @@ import { expandTilde } from './common.mjs';
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/** Sections whose entries MUST carry a `name` (the #819 baselines contract). */
+const NAME_REQUIRED_SECTIONS = new Set(['baselines']);
+
 /** @param {unknown} v */
 function isPlainObject(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -70,18 +83,23 @@ function _normalizePath(p) {
 // ---------------------------------------------------------------------------
 
 /**
- * Extract and validate the `baselines:` list from a raw ownerConfig object.
+ * Extract and validate a directory-prefix list (default `baselines:`) from a raw
+ * ownerConfig object.
  *
  * Drop-and-WARN on malformed entries; never throw. Returns [] when the section
- * is absent, null, or empty — the backward-compat no-op path.
+ * is absent, null, or empty — the backward-compat no-op path. Every WARN names
+ * the section it came from.
  *
- * Each valid entry: { name: string, path: string, match: { 'path-prefix': string } }
+ * Each valid entry: { name: string, path: string, match: { 'path-prefix': string } }.
+ * `name` is required for `baselines`; for other sections an absent name falls
+ * back to `path` (a present-but-blank or non-string name is still dropped).
  *
  * @param {object|undefined} ownerConfig — raw parsed owner.yaml (NOT merged with defaults)
+ * @param {string} [section='baselines'] — owner.yaml list to read (e.g. 'vault-dirs')
  * @returns {Array<{name:string, path:string, match:{'path-prefix':string}}>}
  */
-export function parseBaselines(ownerConfig) {
-  const raw = ownerConfig?.baselines;
+export function parseBaselines(ownerConfig, section = 'baselines') {
+  const raw = ownerConfig?.[section];
 
   // Absent or explicit null/empty → no-op
   if (raw === undefined || raw === null) return [];
@@ -89,54 +107,56 @@ export function parseBaselines(ownerConfig) {
 
   if (!Array.isArray(raw)) {
     process.stderr.write(
-      'WARN named-baseline-resolver: owner.yaml baselines: must be an array; ignoring\n',
+      `WARN named-baseline-resolver: owner.yaml ${section}: must be an array; ignoring\n`,
     );
     return [];
   }
 
+  const nameRequired = NAME_REQUIRED_SECTIONS.has(section);
   const result = [];
   for (let i = 0; i < raw.length; i++) {
     const entry = raw[i];
     if (!isPlainObject(entry)) {
       process.stderr.write(
-        `WARN named-baseline-resolver: owner.yaml baselines[${i}] is not an object; dropping\n`,
+        `WARN named-baseline-resolver: owner.yaml ${section}[${i}] is not an object; dropping\n`,
       );
       continue;
     }
 
     const { name, path: entryPath, match } = entry;
 
-    if (typeof name !== 'string' || name.trim() === '') {
+    const nameAbsent = name === undefined || name === null;
+    if ((nameRequired || !nameAbsent) && (typeof name !== 'string' || name.trim() === '')) {
       process.stderr.write(
-        `WARN named-baseline-resolver: owner.yaml baselines[${i}].name must be a non-empty string; dropping entry\n`,
+        `WARN named-baseline-resolver: owner.yaml ${section}[${i}].name must be a non-empty string; dropping entry\n`,
       );
       continue;
     }
     if (typeof entryPath !== 'string' || entryPath.trim() === '') {
       process.stderr.write(
-        `WARN named-baseline-resolver: owner.yaml baselines[${i}].path must be a non-empty string; dropping entry\n`,
+        `WARN named-baseline-resolver: owner.yaml ${section}[${i}].path must be a non-empty string; dropping entry\n`,
       );
       continue;
     }
 
-    // match is REQUIRED (unlike vaults) — a baseline with no path-prefix can
+    // match is REQUIRED (unlike vaults) — an entry with no path-prefix can
     // never be selected, so it is dropped rather than kept.
     if (!isPlainObject(match)) {
       process.stderr.write(
-        `WARN named-baseline-resolver: owner.yaml baselines[${i}].match must be an object; dropping entry\n`,
+        `WARN named-baseline-resolver: owner.yaml ${section}[${i}].match must be an object; dropping entry\n`,
       );
       continue;
     }
     const pathPrefix = match['path-prefix'];
     if (typeof pathPrefix !== 'string' || pathPrefix.trim() === '') {
       process.stderr.write(
-        `WARN named-baseline-resolver: owner.yaml baselines[${i}].match.path-prefix must be a non-empty string; dropping entry\n`,
+        `WARN named-baseline-resolver: owner.yaml ${section}[${i}].match.path-prefix must be a non-empty string; dropping entry\n`,
       );
       continue;
     }
 
     result.push({
-      name: name.trim(),
+      name: nameAbsent ? entryPath.trim() : name.trim(),
       path: entryPath.trim(),
       match: { 'path-prefix': pathPrefix.trim() },
     });
@@ -162,9 +182,10 @@ export function parseBaselines(ownerConfig) {
  *
  * @param {string} absPath — the working directory to classify
  * @param {Array<{name:string, path:string, match:{'path-prefix':string}}>} baselines
+ * @param {string} [section='baselines'] — owner.yaml list name, used only in the WARN
  * @returns {{name:string, path:string, match:{'path-prefix':string}}|null}
  */
-export function matchBaselineForPath(absPath, baselines) {
+export function matchBaselineForPath(absPath, baselines, section = 'baselines') {
   if (!absPath || !Array.isArray(baselines) || baselines.length === 0) return null;
 
   const target = _normalizePath(absPath);
@@ -181,7 +202,7 @@ export function matchBaselineForPath(absPath, baselines) {
 
   if (matched.length > 1) {
     process.stderr.write(
-      `WARN named-baseline-resolver: multiple baselines match path "${absPath}": ${matched
+      `WARN named-baseline-resolver: multiple ${section} match path "${absPath}": ${matched
         .map((b) => b.name)
         .join(', ')}; using first match "${matched[0].name}"\n`,
     );
@@ -195,13 +216,13 @@ export function matchBaselineForPath(absPath, baselines) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the `baselines:` match tier for a given cwd.
+ * Resolve the directory-prefix match tier (default `baselines:`) for a given cwd.
  *
  * Returns:
- *   { path, name, source:'match' } when a baseline directory-prefix matches cwd.
+ *   { path, name, source:'match' } when an entry's directory-prefix matches cwd.
  *   { path:null, name:null, source:null } (the null-fallback) otherwise — including
- *   when SO_BASELINE_PATH env is set (this tier yields to the higher env tier the
- *   caller owns), when no `baselines:` are configured, or when nothing matches.
+ *   when `env[envKey]` is set (this tier yields to the higher env tier the caller
+ *   owns), when the section is not configured, or when nothing matches.
  *
  * Pure + synchronous — no git calls, no disk reads. Never throws.
  *
@@ -209,22 +230,26 @@ export function matchBaselineForPath(absPath, baselines) {
  *   cwd?: string,
  *   ownerConfig?: object,
  *   env?: Record<string, string|undefined>,
- * }} [opts]
+ *   section?: string,
+ *   envKey?: string,
+ * }} [opts] — `section` defaults to 'baselines', `envKey` to 'SO_BASELINE_PATH'
  * @returns {{ path: string|null, name: string|null, source: 'match'|null }}
  */
 export function resolveNamedBaseline({
   cwd = process.cwd(),
   ownerConfig,
   env = process.env,
+  section = 'baselines',
+  envKey = 'SO_BASELINE_PATH',
 } = {}) {
-  // Yield to the higher-precedence env tier the caller owns (SO_BASELINE_PATH).
-  const envVal = env?.SO_BASELINE_PATH;
+  // Yield to the higher-precedence env tier the caller owns.
+  const envVal = env?.[envKey];
   if (typeof envVal === 'string' && envVal.trim() !== '') {
     return { path: null, name: null, source: null };
   }
 
-  const baselines = parseBaselines(ownerConfig);
-  const matched = baselines.length > 0 ? matchBaselineForPath(cwd, baselines) : null;
+  const entries = parseBaselines(ownerConfig, section);
+  const matched = entries.length > 0 ? matchBaselineForPath(cwd, entries, section) : null;
   if (matched !== null) {
     return { path: matched.path, name: matched.name, source: 'match' };
   }

package/scripts/lib/named-vault-resolver.mjs

@@ -47,11 +47,14 @@
  *   resolveCanonicalSuffixes({ ownerConfig, env })
  *   findRepoRoot(cwd, { existsSync, realpathSync })
  *   resolveNamedVault({ vaultName, cwd, ownerConfig, env, gitRemote, existsSync, realpathSync })
+ *   normalizeRemote(url)
+ *   checkCanonicalVault({ vaultDir, ownerConfig, env, readOriginUrl })
  */
 
 import { join, dirname } from 'node:path';
 import { existsSync as nodeExistsSync, realpathSync as nodeRealpathSync } from 'node:fs';
-import { resolvePreferredRemote, isQueryFailure } from './vcs-repo-spec.mjs';
+import { spawnSync } from 'node:child_process';
+import { resolvePreferredRemote, isQueryFailure, redactUrlCredentials } from './vcs-repo-spec.mjs';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -255,6 +258,73 @@ export function resolveCanonicalSuffixes({ ownerConfig, env = process.env } = {}
   return canonicalSuffixesFromVaults(vaults, env?.VAULT_MIRROR_CANONICAL_SUFFIX);
 }
 
+// ---------------------------------------------------------------------------
+// checkCanonicalVault — the canonical-vault write guard (#1450)
+// ---------------------------------------------------------------------------
+
+/**
+ * Default origin reader: `git -C <vaultDir> remote get-url origin`. Returns
+ * `''` on a spawn error or a non-zero exit, so every failure reads as "no
+ * origin" and the guard stays fail-closed.
+ * @param {string} vaultDir
+ * @returns {string}
+ */
+function _defaultReadOriginUrl(vaultDir) {
+  const res = spawnSync('git', ['-C', vaultDir, 'remote', 'get-url', 'origin'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) return '';
+  return String(res.stdout ?? '').trim();
+}
+
+/**
+ * Decide whether `vaultDir` is a canonical Meta-Vault, i.e. whether its git
+ * `origin` ends in one of {@link resolveCanonicalSuffixes}. Shared by every
+ * writer into the vault so none of them can write into a foreign vault that
+ * `vault-dir` happened to resolve to.
+ *
+ * Fail-closed: a missing origin, a failing or throwing reader, and a suffix
+ * resolution that throws all return `ok: false`. The only bypass is the
+ * existing `VAULT_MIRROR_SKIP_CANONICAL_CHECK === '1'` switch, read from the
+ * `env` passed in (never from the ambient process.env when `env` is given).
+ * It is evaluated before any suffix resolution, so a skipped check neither
+ * parses `ownerConfig.vaults` nor prints its WARN lines, and returns
+ * `expected: []`.
+ *
+ * @param {{
+ *   vaultDir: string,
+ *   ownerConfig?: object,
+ *   env?: Record<string, string|undefined>,
+ *   readOriginUrl?: (vaultDir: string) => string,
+ * }} opts
+ * @returns {{ ok: boolean, reason?: 'skipped-by-env'|'no-git-origin'|'not-canonical', got?: string, expected: string[] }}
+ */
+export function checkCanonicalVault({ vaultDir, ownerConfig, env = process.env, readOriginUrl = _defaultReadOriginUrl } = {}) {
+  if (env?.VAULT_MIRROR_SKIP_CANONICAL_CHECK === '1') {
+    // Empty on purpose: suffix resolution is exactly what the switch skips, and
+    // callers read `expected` only on `ok: false`.
+    return { ok: true, reason: 'skipped-by-env', expected: [] };
+  }
+  let expected;
+  try {
+    expected = resolveCanonicalSuffixes({ ownerConfig, env });
+  } catch {
+    return { ok: false, reason: 'not-canonical', expected: [] };
+  }
+
+  let url;
+  try {
+    url = String(readOriginUrl(vaultDir) ?? '').trim();
+  } catch {
+    url = '';
+  }
+  if (!url) return { ok: false, reason: 'no-git-origin', expected };
+
+  const normalized = normalizeRemote(url);
+  if (!expected.some((s) => normalized.endsWith(s))) {
+    return { ok: false, reason: 'not-canonical', got: url, expected };
+  }
+  return { ok: true, expected };
+}
+
 // ---------------------------------------------------------------------------
 // findRepoRoot — injectable IO
 // ---------------------------------------------------------------------------
@@ -414,7 +484,7 @@ export function resolveNamedVault({
 
         // Guard: if this repo IS one of the vaults, skip (don't self-mirror)
         const canonicalSuffixes = canonicalSuffixesFromVaults(vaults, env?.VAULT_MIRROR_CANONICAL_SUFFIX);
-        const normalized = _normalizeRemoteUrl(remoteUrl);
+        const normalized = normalizeRemote(remoteUrl);
         if (canonicalSuffixes.some((s) => normalized.endsWith(s))) {
           // This is the vault itself — fall through to fallback
         } else {
@@ -460,11 +530,14 @@ function _resolveEnvSuffix(env) {
 }
 
 /**
- * Normalize a git remote URL to host/path tail (mirrors vault-mirror.mjs _normalizeRemote).
+ * Normalize a git remote URL to a host/path tail for canonical-suffix matching.
+ * Strips `.git`, the `git@host:` / scheme prefixes, and trailing slashes —
+ * byte-identical to vault-mirror.mjs `_normalizeRemote`, which predates this
+ * export and can import it from here.
  * @param {string} url
  * @returns {string}
  */
-function _normalizeRemoteUrl(url) {
+export function normalizeRemote(url) {
   return String(url ?? '')
     .trim()
     .replace(/\.git$/, '')
@@ -473,6 +546,32 @@ function _normalizeRemoteUrl(url) {
     .replace(/\/+$/, '');
 }
 
+/**
+ * Render a git origin URL for a stderr line (#1479). The vault writers print
+ * the origin {@link checkCanonicalVault} rejected, and that stderr lands in CI
+ * logs and session transcripts — so a LOCAL origin must not carry its path
+ * (the operator's home dir, `.claude/rules/security.md` § Owner-Privacy).
+ *
+ * - `file:` URL, or a bare/relative path (git's rule: no `://` and no `:`
+ *   before the first `/`, a Windows drive letter counting as a path)
+ *   → `file://<local path>`.
+ * - Every other form (`https://`, `ssh://`, scp-like `git@host:path`) keeps its
+ *   host/path and goes through {@link redactUrlCredentials}, so an
+ *   `https://user:token@host/…` origin cannot leak its credential either.
+ *
+ * Returns `''` for an empty/absent origin; callers supply their own wording.
+ * @param {string|undefined|null} url
+ * @returns {string}
+ */
+export function describeOriginForLog(url) {
+  const s = String(url ?? '').trim();
+  if (!s) return '';
+  if (/^file:/i.test(s)) return 'file://<local path>';
+  if (s.includes('://')) return redactUrlCredentials(s);
+  const scpLike = /^[^/\\]*:/.test(s) && !/^[a-z]:[\\/]/i.test(s);
+  return scpLike ? redactUrlCredentials(s) : 'file://<local path>';
+}
+
 /**
  * Derive an org/repo slug from a git remote URL.
  * e.g. 'git@github.com:my-org/my-repo.git' → 'my-org/my-repo'
@@ -480,7 +579,7 @@ function _normalizeRemoteUrl(url) {
  * @returns {string}
  */
 function _deriveSlugFromRemote(url) {
-  const normalized = _normalizeRemoteUrl(url);
+  const normalized = normalizeRemote(url);
   // normalized is now 'host/path/to/repo' — take the last two segments
   const parts = normalized.split('/').filter(Boolean);
   if (parts.length >= 2) {