session-orchestrator 5.11.0 → 5.13.0

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

@@ -15,7 +15,7 @@
  * via `.passthrough()`, and it is NOT rewritten retroactively by this change.
  */
 
-import { toDate, buildTag, slugifyIdSafe } from './utils.mjs';
+import { toDate, buildTag, slugifyIdSafe, noteIdFor, yamlNoteId } from './utils.mjs';
 import { stableHostname } from '../host-identity.mjs';
 import { sourceRecordValue, sourceRecordLine } from './render-learnings.mjs';
 import { sessionNarrativeText } from './retention.mjs';
@@ -118,38 +118,17 @@ function waveCount(value) {
 }
 
 /**
- * ── RENDERABLE ⊋ SCHEMA-VALID (#964) ───────────────────────────────────────
- *
- * Each generator gates on its own required-field list. Before #964 all three
- * lists were function-local `const`s with no stated relationship to
- * `REQUIRED_FIELDS` (scripts/lib/session-schema/constants.mjs) — the write-path
- * schema — which made five independent notions of "a valid session record" in
- * one codebase, drifting silently. They are lifted here, exported, and pinned
- * against `REQUIRED_FIELDS` by a mechanical superset test in
- * tests/lib/vault-mirror/render-sessions.test.mjs.
- *
- * The relationship is deliberately asymmetric, not a duplicate:
- *
- *   `REQUIRED_FIELDS`  — "this record is well-formed". The writer
- *     (scripts/emit-session.mjs) REFUSES a record that fails it.
- *   these lists        — "this record renders into a note a human can read".
- *     vault-mirror SKIPS a record that fails them; the record stays valid.
- *
- * Collapsing the two would destroy that distinction. Hence `effectiveness`:
- * optional to the writer (a record lacking it is fine), required by the v1
- * renderer (a note reading `planned=n/a, completed=n/a, carryover=n/a,
- * rate=n/a` is worse than no note — indistinguishable from a real session whose
- * metrics happened to be absent).
- *
- * The predicate here is VALUE presence (`null`/`undefined` both fail); the
- * validator's is KEY presence. See `_validateRequiredFields` for why.
+ * ── RENDERABLE AND SCHEMA-VALID (#1575) ───────────────────────────────────
+ *
+ * The generators retain route-specific required-field lists. V1 requires the
+ * canonical REQUIRED_FIELDS; legacy V2/V3 derive aggregates from other shapes
+ * and cannot be emitted by the canonical writer. Effectiveness is optional
+ * and nullable in every route, matching the writer. Unknown metrics render
+ * n/a; a measured zero remains zero. Malformed non-object metrics still fail.
+ * Required fields use VALUE presence; the validator separately checks types.
  */
 
-/**
- * v1 — the only generator reachable from a write-path-valid record (measured:
- * 205/205 live ledger records at HEAD 730ee9d route v1). Its list is
- * `REQUIRED_FIELDS` plus `effectiveness`, i.e. a strict superset.
- */
+/** V1 uses the canonical required-field set without requiring optional metrics. */
 export const RENDERABLE_SESSION_FIELDS_V1 = Object.freeze([
   'session_id',
   'session_type',
@@ -160,7 +139,6 @@ export const RENDERABLE_SESSION_FIELDS_V1 = Object.freeze([
   'total_files_changed',
   'agent_summary',
   'waves',
-  'effectiveness',
 ]);
 
 /**
@@ -183,7 +161,6 @@ export const RENDERABLE_SESSION_FIELDS_V2 = Object.freeze([
   'completed_at',
   'waves',
   'files_changed',
-  'effectiveness',
 ]);
 
 /**
@@ -200,9 +177,18 @@ export const RENDERABLE_SESSION_FIELDS_V3 = Object.freeze([
   'started_at',
   'completed_at',
   'waves',
-  'effectiveness',
 ]);
 
+/** Optional metrics share the writer's object-or-null contract in all routes. */
+function sessionEffectiveness(entry) {
+  const value = entry.effectiveness;
+  if (value === undefined || value === null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${entry.session_id})`);
+  }
+  return value;
+}
+
 /**
  * Session-ledger status → vault-frontmatter status mapping (#909).
  *
@@ -422,12 +408,9 @@ export function generateSessionNote(entry, options = {}) {
     total_files_changed,
     agent_summary,
     waves,
-    effectiveness,
   } = entry;
 
-  if (typeof effectiveness !== 'object' || effectiveness === null) {
-    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${session_id})`);
-  }
+  const effectiveness = sessionEffectiveness(entry);
   if (typeof agent_summary !== 'object' || agent_summary === null) {
     throw new Error(`vault-mirror: session entry missing nested field 'agent_summary' (session_id=${session_id})`);
   }
@@ -463,7 +446,7 @@ export function generateSessionNote(entry, options = {}) {
   // and cap the combined tag at 64 chars so the frontmatter passes the vault
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
-  const noteId = slugifyIdSafe(session_id) ?? session_id;
+  const noteId = noteIdFor(options.repoNs, slugifyIdSafe(session_id) ?? session_id);
   // #909: the real ledger status, mapped into the vault enum — never hard-coded.
   const vaultStatus = vaultStatusForSession(entry);
   const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
@@ -554,7 +537,7 @@ export function generateSessionNote(entry, options = {}) {
   const { repoNs } = options;
 
   return `---
-id: ${noteId}
+id: ${yamlNoteId(noteId)}
 type: session
 title: ${title}
 status: ${vaultStatus}
@@ -592,11 +575,9 @@ export function generateSessionNoteV2(entry, options = {}) {
   if (!Array.isArray(entry.waves)) {
     throw new Error(`vault-mirror: session entry 'waves' must be an array (session_id=${entry.session_id})`);
   }
-  if (typeof entry.effectiveness !== 'object' || entry.effectiveness === null) {
-    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${entry.session_id})`);
-  }
+  const effectiveness = sessionEffectiveness(entry);
 
-  const { session_id, session_type, started_at, completed_at, duration_seconds, branch, planned_issues, waves, files_changed, issues_closed, issues_created, effectiveness } = entry;
+  const { session_id, session_type, started_at, completed_at, duration_seconds, branch, planned_issues, waves, files_changed, issues_closed, issues_created } = entry;
 
   const created = toDate(started_at);
   const updated = toDate(completed_at);
@@ -620,7 +601,7 @@ export function generateSessionNoteV2(entry, options = {}) {
   // and cap the combined tag at 64 chars so the frontmatter passes the vault
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
-  const noteId = slugifyIdSafe(session_id) ?? session_id;
+  const noteId = noteIdFor(options.repoNs, slugifyIdSafe(session_id) ?? session_id);
   // #909: the real ledger status, mapped into the vault enum — never hard-coded.
   const vaultStatus = vaultStatusForSession(entry);
   const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
@@ -641,7 +622,7 @@ export function generateSessionNoteV2(entry, options = {}) {
   const { repoNs } = options;
 
   return `---
-id: ${noteId}
+id: ${yamlNoteId(noteId)}
 type: session
 title: ${title}
 status: ${vaultStatus}
@@ -690,14 +671,12 @@ export function generateSessionNoteV3(entry, options = {}) {
   if (typeof entry.waves !== 'number') {
     throw new Error(`vault-mirror: session entry 'waves' must be a number (session_id=${entry.session_id})`);
   }
-  if (typeof entry.effectiveness !== 'object' || entry.effectiveness === null) {
-    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${entry.session_id})`);
-  }
+  const effectiveness = sessionEffectiveness(entry);
 
   const {
     session_id, session_type, platform, branch, started_at, completed_at,
     duration_minutes, duration_seconds, waves, agents_dispatched, agent_summary,
-    planned_issues, effectiveness, commits, issues_closed, issues_created,
+    planned_issues, commits, issues_closed, issues_created,
     follow_ups_filed, tests_total_pre, tests_total_post, tests_added,
   } = entry;
 
@@ -727,8 +706,12 @@ export function generateSessionNoteV3(entry, options = {}) {
   const failed = as.failed ?? MISSING_VALUE;
   const spiral = as.spiral ?? MISSING_VALUE;
 
+  // A qualified cross-repo reference (`group/repo#n`, #1603) already carries
+  // its own `#`; only a bare number gets the prefix.
   const fmtIssues = (list) =>
-    Array.isArray(list) && list.length ? list.map((i) => `#${i}`).join(', ') : '—';
+    Array.isArray(list) && list.length
+      ? list.map((i) => (typeof i === 'number' ? `#${i}` : String(i))).join(', ')
+      : '—';
   const closedList = fmtIssues(issues_closed);
   const createdList = fmtIssues(issues_created);
   const followList = fmtIssues(follow_ups_filed);
@@ -752,7 +735,7 @@ export function generateSessionNoteV3(entry, options = {}) {
   // and cap the combined tag at 64 chars so the frontmatter passes the vault
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
-  const noteId = slugifyIdSafe(session_id) ?? session_id;
+  const noteId = noteIdFor(options.repoNs, slugifyIdSafe(session_id) ?? session_id);
   // #909: the real ledger status, mapped into the vault enum — never hard-coded.
   const vaultStatus = vaultStatusForSession(entry);
   const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
@@ -768,7 +751,7 @@ export function generateSessionNoteV3(entry, options = {}) {
   const { repoNs } = options;
 
   return `---
-id: ${noteId}
+id: ${yamlNoteId(noteId)}
 type: session
 title: ${title}
 status: ${vaultStatus}

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

@@ -34,7 +34,7 @@
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { subjectToSlug } from './utils.mjs';
+import { subjectToSlug, noteIdFor, yamlNoteId } from './utils.mjs';
 
 /** The generator marker every mirror-written note carries. */
 export const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
@@ -367,7 +367,7 @@ export function renderRollup(existing, rows, { ns, month }) {
     .map((r) => `| ${r.date} | \`${r.id}\` | ${r.type} | ${r.waves} | ${r.agents} | ${r.files} |`)
     .join('\n');
   return `---
-id: ${idSlug}
+id: ${yamlNoteId(noteIdFor(null, idSlug))}
 type: session
 title: "Sessions ${month} (${label}, metrics only)"
 status: verified

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

@@ -10,32 +10,43 @@
 import { parseSessionId } from '../session-id.mjs';
 import { digestSha256Short } from '../crypto-digest-utils.mjs';
 
+/** Normalize letters for new note slugs. */
+function normalizeSlugLetters(value) {
+  const german = { ä: 'ae', ö: 'oe', ü: 'ue', ß: 'ss' };
+  return value.normalize('NFC').toLowerCase()
+    .replace(/[äöüß]/g, (letter) => german[letter])
+    .normalize('NFKD').replace(/\p{M}/gu, '');
+}
+
+/** Historical ASCII deletion, frozen for record identity and old note lookup. */
+export function legacySubjectToSlug(subject) {
+  return slugSubject(subject, (value) => value.toLowerCase());
+}
+
 /**
  * Convert a subject string to a kebab slug.
  * - If subject contains slashes, collapse to last path segment.
+ * - Transliterate German letters and decompose accents.
  * - Replace dots and underscores with hyphens.
  * - Strip all non-[a-z0-9-] chars.
  * - Collapse consecutive hyphens.
  * - Trim leading/trailing hyphens.
  */
 export function subjectToSlug(subject) {
-  let s = subject;
+  return slugSubject(subject, normalizeSlugLetters);
+}
 
-  // Collapse slash paths to last segment
+function slugSubject(subject, normalize) {
+  let s = subject;
   if (s.includes('/')) {
     const parts = s.split('/').filter(Boolean);
     s = parts[parts.length - 1];
   }
-
-  // Normalise: lowercase, dots/underscores → hyphens, strip invalid chars
-  s = s
-    .toLowerCase()
+  return normalize(s)
     .replace(/[._]/g, '-')
     .replace(/[^a-z0-9-]/g, '')
     .replace(/-+/g, '-')
     .replace(/^-+|-+$/g, '');
-
-  return s;
 }
 
 const slugRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -80,8 +91,8 @@ export const TAG_MAX_LENGTH = 64;
  * @returns {string}
  */
 export function slugifyTagSegment(input) {
-  const slug = String(input ?? '')
-    .toLowerCase()
+  // Tags are persistent identifiers, so retain historical ASCII deletion.
+  const slug = String(input ?? '').toLowerCase()
     .replace(/[\s._]+/g, '-')
     .replace(/[^a-z0-9-]/g, '')
     .replace(/-+/g, '-')
@@ -123,14 +134,95 @@ export function buildTag(segments) {
  */
 export function slugifyIdSafe(input) {
   // Normalise whitespace to hyphens first (so "My ID" → "my-id" rather than
-  // "myid"), then delegate to subjectToSlug for the rest of the kebab contract.
+  // "myid"), then preserve the historical ASCII kebab contract.
   const normalised = String(input ?? '').replace(/\s+/g, '-');
-  const slug = subjectToSlug(normalised);
+  // Session identity retains historical deletion; transliteration is for new
+  // learning names, never an incidental Session-ID migration.
+  const slug = legacySubjectToSlug(normalised);
   if (!slug) return null;
   // Schema requires min length 2; pad a single-char slug deterministically.
   return slug.length >= 2 ? slug : `${slug}-x`;
 }
 
+/** The vault-sync schema's `id` cap (`skills/vault-sync/validator.mjs`, `.max(128)`). */
+export const NOTE_ID_MAX_LENGTH = 128;
+
+/**
+ * The frontmatter `id` of a generated note (#1601, #1602). The FILENAME slug
+ * stays the note's identity on disk (paths never change); the `id` adds the
+ * repo namespace so it is unique across the vault's per-repo folders — a
+ * session id or learning subject recurs across repos — and is capped at
+ * {@link NOTE_ID_MAX_LENGTH}. An over-long id keeps a 119-char prefix plus an
+ * 8-hex SHA-256 suffix of the FULL id, so two long subjects sharing a prefix
+ * stay distinct. Deterministic: the same `(repoNs, slug)` always yields the
+ * same id. Without a namespace (vault-less callers, unit tests) the slug is
+ * only capped.
+ *
+ * BV-004 ceiling: the separator is a single `-` (the schema slug forbids
+ * `--`), so namespace `a` + slug `b-c` and namespace `a-b` + slug `c` render
+ * the same id. Revisit-Trigger: the vault validator reports a duplicate id
+ * whose two notes sit in different namespace folders.
+ *
+ * @param {string|null|undefined} repoNs - the resolved repo namespace folder.
+ * @param {string} slug - the note's filename slug (or rendered session slug).
+ * @returns {string}
+ */
+export function noteIdFor(repoNs, slug) {
+  const base = String(slug ?? '');
+  const ns = typeof repoNs === 'string' && repoNs.length > 0 ? (isValidSlug(repoNs) ? repoNs : legacySubjectToSlug(repoNs)) : '';
+  const full = ns ? `${ns}-${base}` : base;
+  if (full.length <= NOTE_ID_MAX_LENGTH) return full;
+  const suffix = digestSha256Short(full);
+  return `${full.slice(0, NOTE_ID_MAX_LENGTH - suffix.length - 1).replace(/-+$/, '')}-${suffix}`;
+}
+
+/**
+ * Does a note's frontmatter `id` name the note `slug`? Accepts both the
+ * pre-#1601 id (the bare slug — a numeric one parses as the same string here,
+ * `parseFrontmatter` keeps scalars verbatim) and the current {@link noteIdFor}
+ * form, so notes written before the id change keep their ownership evidence.
+ *
+ * @param {unknown} fmId
+ * @param {string} slug
+ * @param {string|null|undefined} repoNs
+ * @returns {boolean}
+ */
+export function noteIdMatches(fmId, slug, repoNs) {
+  return typeof fmId === 'string' && (fmId === slug || fmId === noteIdFor(repoNs, slug));
+}
+
+/**
+ * The `id:` frontmatter value, always a double-quoted YAML string (#1601): an
+ * unquoted all-digit id (`id: 433`) parses as a NUMBER under a real YAML parser
+ * and fails the schema's `z.string()`.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function yamlNoteId(id) {
+  return JSON.stringify(String(id));
+}
+
+/**
+ * Replace the frontmatter `id:` line of a note — used when a displaced note
+ * moves to its disambiguated name (#1506.2), whose `id` must match the file,
+ * and by the id migration (#1601, `migrate-ids.mjs`). Only the `id:` line
+ * INSIDE the leading frontmatter block changes; every other byte — body,
+ * other fields, `[REDACTED]` spans (#1025) — is kept verbatim. A note without
+ * a frontmatter `id:` line is returned unchanged.
+ * @param {string} content
+ * @param {string} id
+ * @returns {string}
+ */
+export function withNoteId(content, id) {
+  if (!content.startsWith('---')) return content;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return content;
+  const head = content.slice(0, end);
+  const nextHead = head.replace(/^id:.*$/m, `id: ${yamlNoteId(id)}`);
+  return nextHead === head ? content : nextHead + content.slice(end);
+}
+
 /** Derive the first 8 chars of a UUID (strip hyphens, take first 8 hex chars). */
 export function uuidPrefix8(id) {
   return id.replace(/-/g, '').slice(0, 8);
@@ -198,7 +290,8 @@ export function resolveSourceSessionLink(source_session, opts = {}) {
   if (!raw || raw === 'unknown') return { isLink: false, target: raw || 'unknown' };
   // Provenance tags like "agent-proposed@wave-1" are never session notes.
   if (/@/.test(raw)) return { isLink: false, target: raw };
-  const slug = subjectToSlug(raw) || raw;
+  // Session targets retain the same historical identity as their note filenames.
+  const slug = legacySubjectToSlug(raw) || raw;
   if (typeof opts.noteExists === 'function') {
     // EXISTENCE-based (authoritative when a predicate is supplied).
     return opts.noteExists(slug) ? { isLink: true, target: slug } : { isLink: false, target: raw };

package/scripts/lib/vault-staleness-banner.mjs

@@ -23,7 +23,7 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
+import { resolveLedgerPath } from './ledger-path.mjs';
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
@@ -95,12 +95,9 @@ export function checkVaultStaleness({ repoRoot, now = Date.now() } = {}) {
   try {
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
-    const jsonlPath = path.join(
-      repoRoot,
-      '.orchestrator',
-      'metrics',
-      'vault-staleness.jsonl',
-    );
+    // #1722: the ledger the probe writes (skills/discovery/probes/vault-staleness.mjs)
+    // — the main checkout's when repoRoot is a linked worktree that ignores it.
+    const jsonlPath = resolveLedgerPath('.orchestrator/metrics/vault-staleness.jsonl', repoRoot);
 
     if (!existsSync(jsonlPath)) return null;
 

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

@@ -48,7 +48,7 @@
  * canonical-vault refusal (#1450). Plain Node ESM. No external deps.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -56,6 +56,7 @@ import { emitEvent, sessionAttribution } from '../events.mjs';
 import { isLockLive, readLock, DEFAULT_TTL_HOURS } from '../session-lock.mjs';
 import { stableHostname } from '../host-identity.mjs';
 import { readRegistry, repoPathHash, isRegistryEntryFresh } from '../session-registry.mjs';
+import { digestSha256 } from '../crypto-digest-utils.mjs';
 import { parseFrontmatter } from '../vault-mirror/utils.mjs';
 import { readConfigFile, parseSessionConfig } from '../config.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
@@ -134,10 +135,29 @@ const CASE_INSENSITIVE_FS = process.platform === 'darwin' || process.platform ==
  * @returns {string|null} `KEY_LENGTH`-char hex prefix, or null for an unusable path.
  */
 export function boardKey(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
+  try {
+    let resolved = path.resolve(repoRoot);
+    try { resolved = realpathSync.native(resolved); } catch { /* Keep unavailable paths' legacy identity. */ }
+    // Fold AFTER realpath, then hash directly: repoPathHash would restore
+    // on-disk casing and change existing case-folded board keys on macOS.
+    return digestSha256(CASE_INSENSITIVE_FS ? resolved.toLowerCase() : resolved).slice(0, KEY_LENGTH);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pre-#1557 lexical board key, used to migrate rows when alias paths now
+ * resolve to a canonical key. BV-004 revisit/deletion trigger: remove once a
+ * host-wide board audit confirms no rows written before the #1557 canonical-key
+ * rollout remain for 30 consecutive days; age alone does not prove migration.
+ */
+function legacyBoardKey(repoRoot) {
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) return null;
   try {
     const resolved = path.resolve(repoRoot);
-    return repoPathHash(CASE_INSENSITIVE_FS ? resolved.toLowerCase() : resolved).slice(0, KEY_LENGTH);
+    return digestSha256(CASE_INSENSITIVE_FS ? resolved.toLowerCase() : resolved).slice(0, KEY_LENGTH);
   } catch {
     return null;
   }
@@ -435,6 +455,7 @@ export async function collectRows({ repos, now = new Date(), registry, priorStat
     rows.push({
       repo: repoName,
       key,
+      legacyKey: legacyBoardKey(repo.repoRoot), // Internal migration identity; never rendered.
       status,
       session: status === STATUS_FREI ? null : session,
       branch: status === STATUS_FREI ? null : branch,
@@ -1098,8 +1119,8 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
     // skips `frei` candidates and the TTL pass only rewrites `status`, never
     // removes a row), and the board would grow a permanent duplicate per repo.
     // So a fresh row first claims its hash slot; if that slot is new, it ADOPTS
-    // the legacy name slot for the same folded name — one board write converts
-    // the row, and the migration is complete for that repo.
+    // the legacy name slot for the same folded name and the pre-#1557 lexical
+    // key slot — one board write converts the row for that repo.
     const merged = new Map(staleRederivedRows);
     for (const row of rows) {
       const slot = row.key ? hashSlot(row.key) : nameSlot(row.repo);
@@ -1107,6 +1128,13 @@ async function mirrorBoardInner({ repoRoot, repos, explicitStatus, now = new Dat
         // First keyed write for this repo — take over its legacy row rather than
         // rendering a second one beside it.
         merged.delete(nameSlot(row.repo));
+        if (row.legacyKey && row.legacyKey !== row.key) {
+          // An 8-char key can collide: adopt the legacy-key row only when it
+          // names this repo, never another repo's row that shares the prefix.
+          const legacySlot = hashSlot(row.legacyKey);
+          const legacyRow = merged.get(legacySlot);
+          if (legacyRow && foldKey(legacyRow.repo) === foldKey(row.repo)) merged.delete(legacySlot);
+        }
       }
       merged.set(slot, row);
     }
@@ -1311,7 +1339,8 @@ export function buildSweepRepos(candidates, { thisRepoRoot } = {}) {
  * @param {object} [opts]
  * @param {string} opts.repoRoot — the calling repo (always included in the sweep).
  * @param {string} [opts.startDir] — enumeration root; omitted in production so
- *   {@link enumerateCandidates} defaults to `getConfinementRoot()` (~/Projects).
+ *   {@link enumerateCandidates} defaults to `getConfinementRoot()` (~/Projects
+ *   unless the host sets `projects-root`, #1562).
  *   Test seam only — do NOT compute `path.dirname(repoRoot)` here.
  * @param {Date|number} [opts.now] — clock seam. A `Date` is used as-is; a finite
  *   number is treated as epoch-ms (matching {@link collectRows}'s own

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

@@ -31,12 +31,15 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
-import { parseStateMd, parseMissionStatus, resolveStateMdPath } from '../state-md.mjs';
+import { parseStateMd, parseMissionStatus } from '../state-md.mjs';
+import { resolveStateMdWriteTarget, warnForeignStateMd } from '../state-md/frontmatter-mutators.mjs';
 import {
   parseFrontmatter,
   toDate,
   yamlQuoteIfNeeded,
   subjectToSlug,
+  noteIdFor,
+  yamlNoteId,
 } from '../vault-mirror/utils.mjs';
 import { matchesModuloRedaction } from '../vault-mirror/process.mjs';
 import { readConfigFile, parseSessionConfig } from '../config.mjs';
@@ -317,7 +320,7 @@ export function renderNarrative(opts) {
 
   // Frontmatter — `_generator` LAST (markdown-writer / render-sessions convention).
   lines.push('---');
-  lines.push(`id: ${noteId}`);
+  lines.push(`id: ${yamlNoteId(noteIdFor(null, noteId))}`);
   lines.push('type: session');
   lines.push(`title: ${title}`);
   lines.push(`created: ${createdValue}`);
@@ -380,6 +383,31 @@ export function resolveNarrativePath(vaultDir, repoSlug) {
   return path.join(vaultDir, '01-projects', repoSlug, '_session-narrative.md');
 }
 
+/**
+ * The `created` date of the narrative already at `outputPath` when THIS generator
+ * wrote it (#1602; same rule as board-writer.mjs). A hand-authored or foreign
+ * file, a missing one, or a malformed date yields `undefined` — the render then
+ * stamps today, exactly as on a first write. A read failure is not fatal here:
+ * `writeNarrative` reads the file again and owns that error contract.
+ *
+ * @param {string} outputPath
+ * @param {{ readFileSync?: Function, existsSync?: Function }} [injectedFs]
+ * @returns {string|undefined} `YYYY-MM-DD`
+ */
+function existingNarrativeCreated(outputPath, injectedFs) {
+  const fsExists = injectedFs?.existsSync ?? existsSync;
+  const fsReadFile = injectedFs?.readFileSync ?? readFileSync;
+  try {
+    if (!fsExists(outputPath)) return undefined;
+    const fm = parseFrontmatter(fsReadFile(outputPath, 'utf8'));
+    if (fm?.['_generator'] !== GENERATOR_MARKER) return undefined;
+    const created = fm['created'];
+    return typeof created === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(created) ? created : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // ── Idempotent write ─────────────────────────────────────────────────────────────
 
 /**
@@ -393,6 +421,26 @@ function normalizeUpdated(content) {
   return content.replace(/^(updated:\s*)(.+)$/m, `$1${UPDATED_PLACEHOLDER}`);
 }
 
+/**
+ * The comparison form of a narrative for the noop check: {@link normalizeUpdated}
+ * plus the `id:` line dropped to a bare `id:` (#1601, release-review HOCH 2).
+ * The id differs between generations of the renderer in more than one way: the
+ * render now quotes it (`id: "x"`) where older files carry `id: x`, and
+ * `noteIdFor` caps it, so a pre-cap file can carry a longer value. Any such
+ * difference made the whole document "changed", which skipped the `[REDACTED]`
+ * comparison below and rewrote the file — with the raw secret whenever it was
+ * missing from the current env (#1025). The id is derived from the note's
+ * path, not from its content, so no id difference may ever trigger a rewrite;
+ * a schema-breaking id on disk is the job of `vault-mirror/migrate-ids.mjs`,
+ * which changes that one line and nothing else.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function normalizeForNoopCompare(content) {
+  return normalizeUpdated(content).replace(/^id:.*$/m, 'id:');
+}
+
 /**
  * Write the narrative file with idempotency guards (mirrors gitlab-portfolio
  * markdown-writer.mjs contract).
@@ -501,8 +549,9 @@ export function writeNarrative(opts) {
       // #1025 — identical once every `[REDACTED]` span already on disk is read
       // as a wildcard. See the guard-order note above for why the second arm is
       // load-bearing rather than a nicety.
-      const existingNormalized = normalizeUpdated(existingContent);
-      const candidateNormalized = normalizeUpdated(content);
+      // #1601: the id line is left out of the compare — see normalizeForNoopCompare.
+      const existingNormalized = normalizeForNoopCompare(existingContent);
+      const candidateNormalized = normalizeForNoopCompare(content);
       if (
         existingNormalized === candidateNormalized ||
         matchesModuloRedaction(existingNormalized, candidateNormalized)
@@ -963,8 +1012,15 @@ async function runNarrativeMirror(opts) {
     return { result: { action: 'skipped-invalid-path', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
-  // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
-  const stateMdPath = resolveStateMdPath(repoRoot);
+  // Read STATE.md (best-effort; absent STATE.md → nothing to mirror). #1622:
+  // another platform's STATE.md not proven to be this process's counts as absent.
+  // #1640: `rejected` is also set when the target ITSELF is foreign
+  // (`blocked`) — never read and mirror that file either.
+  const { path: stateMdPath, rejected } = resolveStateMdWriteTarget(repoRoot);
+  if (rejected) {
+    warnForeignStateMd('mirrorNarrative', rejected, stateMdPath);
+    return { result: { action: 'skipped-no-statemd', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
+  }
   let stateContents;
   try {
     stateContents = await readFile(stateMdPath, 'utf8');
@@ -976,7 +1032,10 @@ async function runNarrativeMirror(opts) {
   // parse (so `[REDACTED]` can never break it) and before the render, the
   // idempotency comparison and the write. See maskNarrative above.
   const { narrative, hits } = maskNarrative(extractNarrative(stateContents), masker);
-  const content = renderNarrative({ repo: repoName, narrative, now });
+  // #1602: `created` is the day the narrative was FIRST written — carried over
+  // from the file on disk, so only `updated` moves between runs.
+  const createdIso = existingNarrativeCreated(outputPath, injectedFs);
+  const content = renderNarrative({ repo: repoName, narrative, now, createdIso });
 
   // `chars` measures the document THIS call rendered — so it is present on
   // `skipped-noop` and `dry-run` too, where the render happened but nothing