session-orchestrator 5.6.0 → 5.8.0

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

@@ -5,17 +5,29 @@
  * Both functions write to the vault dir and emit JSON action lines to stdout.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, join, resolve, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { createSecretValueMasker } from '../secret-masker.mjs';
-import { subjectToSlug, isValidSlug, uuidPrefix8, toDate, parseFrontmatter } from './utils.mjs';
+import { subjectToSlug, isValidSlug, uuidPrefix8, recordKeySuffix8, toDate, parseFrontmatter } from './utils.mjs';
 import { isRealSession } from '../session-schema/filters.mjs';
 import { resolveRepoNamespace } from './namespace.mjs';
 import { detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2, learningSourceRecord } from './render-learnings.mjs';
 import { detectSessionSchema, normalizeSessionEntry, generateSessionNote, generateSessionNoteV2, generateSessionNoteV3, sessionSourceRecord } from './render-sessions.mjs';
 import { emitMirrorEvent } from './telemetry.mjs';
+import {
+  ARCHIVE_ROOT,
+  canonicalNamespace,
+  legacyConcatSlug,
+  noteNarrativeChars,
+  markArchived,
+  noteInsightKey,
+  renderRollup,
+  rollupRelPath,
+  rollupRowFromNote,
+  sessionNarrativeChars,
+} from './retention.mjs';
 
 const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
 
@@ -64,10 +76,92 @@ function getSessionNoteSet(vaultDir) {
   }
 
   walk(sessionsDir);
+  // #1513: session notes the pruner moved to the archive keep their basename,
+  // and Obsidian resolves a wiki-link by basename — so a learning whose source
+  // session was archived still links. Without this walk every such learning
+  // would re-render its `source_session` as plain text and churn on each run.
+  walk(join(resolvedVault, ARCHIVE_ROOT, '50-sessions'));
   _sessionNoteSets.set(resolvedVault, knownSessions);
   return knownSessions;
 }
 
+// ── Insight index for write-time dedupe (#1513) ───────────────────────────────
+
+/**
+ * Cache: `<dir>\0<dir>` → { stamp, index }. The stamp is the two directories'
+ * mtimes, which change whenever a file is added or removed — including by this
+ * process's own creates — so the index is rebuilt exactly when its population
+ * changed and reused otherwise (one read of the namespace per run, not per
+ * record).
+ *
+ * @type {Map<string, {stamp: string, index: Map<string, string>}>}
+ */
+const _insightIndexes = new Map();
+
+function dirStamp(dir) {
+  try {
+    return String(statSync(dir).mtimeMs);
+  } catch {
+    return 'absent';
+  }
+}
+
+/**
+ * normalised insight → absolute path, over the mirror-owned, NOT archived
+ * learning notes directly in `dirs` (non-recursive), plus those in `flatDir`
+ * whose `source-repo` is `ns`. Read-only.
+ *
+ * @param {string[]} dirs
+ * @param {string|null} [flatDir]
+ * @param {string|null} [ns]
+ * @returns {Map<string, string>}
+ */
+function getInsightIndex(dirs, flatDir = null, ns = null) {
+  const key = [...dirs, flatDir ?? '', ns ?? ''].join('\0');
+  const stamp = [...dirs, ...(flatDir ? [flatDir] : [])].map(dirStamp).join('\0');
+  const cached = _insightIndexes.get(key);
+  if (cached && cached.stamp === stamp) return cached.index;
+  const index = new Map();
+  // #1513 review M3: a flat legacy note counts only when its `source-repo` is
+  // this namespace — a flat note of another repo, or one without attribution,
+  // must not refuse a genuine new learning of this repo.
+  const sources = [...dirs.map((d) => ({ dir: d, onlyRepo: null })), ...(flatDir ? [{ dir: flatDir, onlyRepo: ns }] : [])];
+  for (const { dir, onlyRepo } of sources) {
+    let names;
+    try {
+      names = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of names) {
+      if (!ent.isFile() || !ent.name.endsWith('.md')) continue;
+      const abs = join(dir, ent.name);
+      let content;
+      try {
+        content = readFileSync(abs, 'utf8');
+      } catch {
+        continue;
+      }
+      const fm = parseFrontmatter(content);
+      if (!fm || fm['_generator'] !== GENERATOR_MARKER || fm['type'] !== 'learning') continue;
+      if (fm['status'] === 'archived') continue;
+      if (onlyRepo !== null && fm['source-repo'] !== onlyRepo) continue;
+      const insightKey = noteInsightKey(content);
+      if (insightKey && !index.has(insightKey)) index.set(insightKey, abs);
+    }
+  }
+  _insightIndexes.set(key, { stamp, index });
+  return index;
+}
+
+/** Today as `YYYY-MM-DD` from the injectable `ctx.now` (ms, ISO or Date). */
+function todayOf(ctx) {
+  const now = ctx?.now;
+  const ms =
+    now instanceof Date ? now.getTime() : typeof now === 'number' ? now : typeof now === 'string' ? Date.parse(now) : NaN;
+  return new Date(Number.isFinite(ms) ? ms : Date.now()).toISOString().slice(0, 10);
+}
+
 // ── Content diff helper ───────────────────────────────────────────────────────
 
 /**
@@ -329,6 +423,44 @@ function notOurGenerator(fm) {
   return null;
 }
 
+/**
+ * The disambiguation slug a record uses under `slug` in `dir` (#1506.1). An
+ * EXISTING `<slug>-<uuid8>` note that is ours and owned by this record keeps
+ * its name — the owner decision was "no mass rename"; every other case gets the
+ * full-record-key hash suffix ({@link recordKeySuffix8}), so non-UUID ids that
+ * share their first 8 chars no longer land on one file.
+ *
+ * @param {string} dir - the namespace folder.
+ * @param {string} slug - the canonical note slug.
+ * @param {{ legacyId: string, recordKey: string }} keys - `legacyId` is what the
+ *   pre-#1506 suffix was derived from (the raw id); `recordKey` the full key.
+ * @returns {{ slug: string, exists: boolean|null }} `exists: true` when the
+ *   legacy name was chosen (it was just probed); `null` when not yet probed.
+ */
+function disambigSlugFor(dir, slug, { legacyId, recordKey }) {
+  const legacy = `${slug}-${uuidPrefix8(legacyId)}`;
+  const hashed = `${slug}-${recordKeySuffix8(recordKey)}`;
+  const legacyPath = join(dir, `${legacy}.md`);
+  if (legacy !== hashed && existsSync(legacyPath)) {
+    const fm = parseFrontmatter(readFileSync(legacyPath, 'utf8'));
+    if (notOurGenerator(fm) === null && foreignOwnerReason(fm, { recordKey }) === null) {
+      return { slug: legacy, exists: true };
+    }
+  }
+  return { slug: hashed, exists: null };
+}
+
+/**
+ * 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.
+ * @param {string} content
+ * @param {string} id
+ * @returns {string}
+ */
+function withNoteId(content, id) {
+  return content.replace(/^id: .*$/m, `id: ${id}`);
+}
+
 /**
  * Emit `skipped-foreign-owner` for a note the writer must not touch: one stderr
  * `SKIP` line (vault-relative path, like every other SKIP line) and the stdout
@@ -763,6 +895,47 @@ function maskEntrySecrets(entry) {
 
 // ── Core processing ───────────────────────────────────────────────────────────
 
+/**
+ * The canonical note slug of a learning (extracted from processLearning for
+ * #1513 so the archive pass derives the SAME path). See the #725 D1 / #635
+ * notes inside.
+ *
+ * @param {object} entry normalised learning entry
+ * @param {'v1'|'v2'} schema
+ * @returns {string}
+ */
+function learningSlug(entry, schema) {
+  const entryId = entry.id;
+  let slugSource;
+  if (schema === 'v2') {
+    slugSource = entry.id;
+  } else if (typeof entry.subject === 'string') {
+    slugSource = entry.subject.trim().replace(/\s+/g, '-');
+  } else {
+    slugSource = entry.subject;
+  }
+  let slug;
+  if (typeof slugSource === 'string' && slugSource.length > 0) {
+    slug = subjectToSlug(slugSource);
+  } else {
+    slug = '';
+  }
+  if (!isValidSlug(slug)) {
+    slug = `learning-${uuidPrefix8(entryId)}`;
+  }
+  // #635: cap the slug so `<slug>.md` (plus a possible `-<uuid8>` disambig
+  // suffix) stays under the 255-byte filename limit. Normalized prose subjects
+  // can be arbitrarily long and previously aborted the whole mirror run with
+  // ENAMETOOLONG. 240 + 9 (disambig) + 3 (.md) = 252 — and every pre-existing
+  // vault note (max observed slug: 208 chars) keeps its identity untouched.
+  if (slug.length > 240) {
+    slug = slug.slice(0, 240).replace(/-+$/, '');
+  }
+
+  return slug;
+}
+
+
 export async function processLearning(rawEntry, _lineNum, ctx) {
   const {
     vaultDir,
@@ -806,34 +979,20 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // subject contract pinned by 15 tests in tests/unit/vault-mirror.test.mjs. The
   // pre-map is the mechanism the brief itself names and yields the IDENTICAL slug
   // for real data (kebab id derived from the same subject); see report.
-  let slugSource;
-  if (schema === 'v2') {
-    slugSource = entry.id;
-  } else if (typeof entry.subject === 'string') {
-    slugSource = entry.subject.trim().replace(/\s+/g, '-');
-  } else {
-    slugSource = entry.subject;
-  }
-  let slug;
-  if (typeof slugSource === 'string' && slugSource.length > 0) {
-    slug = subjectToSlug(slugSource);
-  } else {
-    slug = '';
-  }
-  if (!isValidSlug(slug)) {
-    slug = `learning-${uuidPrefix8(entryId)}`;
-  }
-  // #635: cap the slug so `<slug>.md` (plus a possible `-<uuid8>` disambig
-  // suffix) stays under the 255-byte filename limit. Normalized prose subjects
-  // can be arbitrarily long and previously aborted the whole mirror run with
-  // ENAMETOOLONG. 240 + 9 (disambig) + 3 (.md) = 252 — and every pre-existing
-  // vault note (max observed slug: 208 chars) keeps its identity untouched.
-  if (slug.length > 240) {
-    slug = slug.slice(0, 240).replace(/-+$/, '');
-  }
+  let slug = learningSlug(entry, schema);
 
   // Generator + date source differ by schema
-  const generator = schema === 'v2' ? generateLearningNoteV2 : generateLearningNote;
+  const baseGenerator = schema === 'v2' ? generateLearningNoteV2 : generateLearningNote;
+  // #1513: an expired learning (v1 `expires_at` before today) is never CREATED,
+  // and an existing note of it is re-rendered as `status: archived` +
+  // `archived-reason: expired` (the canonical-field diff sees the status change
+  // and writes it once; afterwards the note is a noop). v2 records carry no
+  // expiry. The pruner moves such notes out of the active zone.
+  const expiresDay = schema === 'v1' && typeof entry.expires_at === 'string' ? toDate(entry.expires_at) : '';
+  const expired = /^\d{4}-\d{2}-\d{2}$/.test(expiresDay) && expiresDay < todayOf(ctx);
+  const generator = expired
+    ? (e, s, o) => markArchived(baseGenerator(e, s, o), 'expired')
+    : baseGenerator;
   const dateSource = schema === 'v2' ? entry.first_seen : entry.created_at;
 
   // #704: Build a noteExists predicate from the vault's 50-sessions index so that
@@ -861,10 +1020,13 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
 
   // #660: namespace new writes under a per-repo subdirectory. #1389: `ctx.repoRoot`
   // is optional — absent, resolveRepoNamespace falls back to process.cwd().
-  const repoNs = resolveRepoNamespace({
-    vaultName: ctx?.vaultName ?? null,
-    repoRoot: ctx?.repoRoot ?? null,
-  });
+  // #1513 review M2: a hyphen alias (`gotzendorferv2`) resolves to the
+  // canonical folder already in the vault (`gotzendorfer-v2`), so the mirror
+  // and the pruner agree on where a repo's notes live.
+  const repoNs = canonicalNamespace(
+    vaultDir,
+    resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
+  );
   // #725 D2: thread the resolved repo namespace into the learning frontmatter as
   // `source-repo` for cross-repo attribution. repoNs is already sanitised +
   // leak-guarded by resolveRepoNamespace, so it is safe to interpolate as-is. The
@@ -877,11 +1039,78 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // so two records sharing a subject keep two stable notes instead of
   // overwriting each other on every run.
   const writer = { recordKey: learningSourceRecord(entry) };
+
+  /**
+   * #1513: the two reasons a NEW learning note is not created. Consulted only
+   * where a file would come into existence — updates of existing notes are
+   * never refused here. Returns the emitted action, or null to proceed.
+   *
+   *   - `skipped-expired`: the learning is past `expires_at`; a note for it
+   *     would be dead on arrival.
+   *   - `skipped-duplicate-insight`: a mirror-owned, non-archived note in this
+   *     namespace (or the flat legacy layout) already carries the same
+   *     normalised insight — the same learning under another slug or id.
+   */
+  const refuseNewNote = (content) => {
+    if (expired) {
+      return emitEntryAction(_lineNum, ctx, {
+        action: 'skipped-expired',
+        path: null,
+        id: entryId,
+        meta: { reason: `expires:${expiresDay} < today:${todayOf(ctx)}` },
+      });
+    }
+    const insightKey = noteInsightKey(content);
+    if (insightKey) {
+      const twin = getInsightIndex([targetDir], join(resolve(vaultDir), '40-learnings'), repoNs).get(insightKey);
+      if (twin !== undefined) {
+        return emitEntryAction(_lineNum, ctx, {
+          action: 'skipped-duplicate-insight',
+          path: twin,
+          id: entryId,
+          meta: { reason: 'same normalised insight as an existing note' },
+        });
+      }
+    }
+    return null;
+  };
   const targetDir = join(resolve(vaultDir), '40-learnings', repoNs);
   if (!dryRun) mkdirSync(targetDir, { recursive: true });
 
   let targetPath = join(targetDir, `${slug}.md`);
 
+  // #1513 LEGACY SLUG: until #725 D1 a v1 subject was slugged WITHOUT the
+  // whitespace → hyphen pre-map ("3parallelimplagents…"); the canonical form
+  // hyphenates ("3-parallel-impl-agents…"). When only the legacy variant of
+  // THIS record's note exists, it IS the note: it is updated in place under
+  // its own name instead of a second file being created beside it (the vault
+  // carried 364 such twins). New notes always get the canonical name.
+  if (schema === 'v1') {
+    const legacySlug = legacyConcatSlug(entry.subject);
+    const flatDir = join(resolve(vaultDir), '40-learnings');
+    if (
+      isValidSlug(legacySlug) &&
+      legacySlug !== slug &&
+      !existsSync(targetPath) &&
+      !existsSync(join(flatDir, `${slug}.md`))
+    ) {
+      for (const dir of [targetDir, flatDir]) {
+        const legacyPath = join(dir, `${legacySlug}.md`);
+        if (!existsSync(legacyPath)) continue;
+        const legacyFm = parseFrontmatter(readFileSync(legacyPath, 'utf8'));
+        if (
+          notOurGenerator(legacyFm) === null &&
+          legacyFm['id'] === legacySlug &&
+          foreignOwnerReason(legacyFm, writer) === null
+        ) {
+          slug = legacySlug;
+          targetPath = join(targetDir, `${legacySlug}.md`);
+          break;
+        }
+      }
+    }
+  }
+
   // #660 IDEMPOTENCY DUAL-PROBE: before treating the namespaced path as absent,
   // also check the legacy flat path. If a note with the same slug already exists
   // in the flat layout (pre-namespace migration), treat it as existing to avoid
@@ -963,26 +1192,58 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     // that note is masked in place first — never by rewriting it from THIS
     // record, which would be the #1503 overwrite triggered by a secret.
     //
-    // BV-004 ceiling: (1) the main `<slug>.md` keeps the FIRST record that
-    // claimed it — after a re-learn it goes stale while the current record lives
-    // at `<slug>-<uuid8>.md`; (2) disambiguation is ONE level deep — a
-    // `-<uuid8>` file owned by yet another record is skipped-foreign-owner.
-    // Fine while re-learns are rare (fleet census at review time: 39 slugs in 12
-    // repos). Revisit-Trigger: a stale main note is read as current, or a
-    // skipped-foreign-owner is reported on a `-<uuid8>` path.
+    // #1506.2: the NEWEST record owns the main `<slug>.md` — a re-learned
+    // record (strictly later `created` day) takes it over, and the displaced
+    // note moves, bytes kept but `id` renamed, to its own record's
+    // disambiguation path; never lost, never overwritten. #1506.1: a NEW
+    // disambiguation file is suffixed with a hash of the full record key, so
+    // non-UUID ids sharing a prefix no longer collide; existing `-<uuid8>`
+    // files keep their names.
+    //
+    // BV-004 ceiling: "newest" is compared at DAY granularity (`created` is a
+    // date) — a same-day re-learn keeps the current owner (stable, no churn).
+    // Revisit-Trigger: a same-day re-learn is reported as a stale main note.
+    //
+    // BV-004 ceiling: the takeover ignores repo provenance — a NEWER record of
+    // another repo mirrored into this namespace (the #1503 shape) also takes the
+    // main note, and `source-repo` cannot tell it apart (both carry the writer's
+    // namespace). Nothing is lost (the displaced note moves, never overwritten);
+    // the CLI's `source-repo-mismatch` refusal is what keeps foreign records out.
+    // Revisit-Trigger: a takeover whose displaced note belongs to this repo's
+    // live store, or any mirror run accepting a foreign `--source` again.
     const recordMismatch = foreignOwnerReason(fm, writer);
     const routedByRecord = recordMismatch !== null;
     if (routedByRecord && maskerWouldChange(existingContent)) {
       healedForeignLeak = maskForeignNoteInPlace(targetPath, existingContent, ctx);
     }
 
+    const entryDay = toDate(dateSource);
+    if (
+      routedByRecord &&
+      fm['id'] === slug &&
+      !expired &&
+      /^\d{4}-\d{2}-\d{2}$/.test(entryDay) &&
+      typeof fm['created'] === 'string' &&
+      entryDay > fm['created']
+    ) {
+      const takenOver = takeOverMainNote({
+        fm, slug, targetDir, targetPath, entry, entryId, writer, generator, generatorOpts,
+        healedForeignLeak, lineNum: _lineNum, ctx,
+      });
+      if (takenOver !== null) return takenOver;
+    }
+
     if (fm['id'] !== slug || routedByRecord) {
       // Different id (or different record) → collision: disambiguate
-      const disambigSlug = `${slug}-${uuidPrefix8(entryId)}`;
+      const picked = disambigSlugFor(targetDir, slug, {
+        legacyId: String(entryId),
+        recordKey: writer.recordKey ?? String(entryId),
+      });
+      const disambigSlug = picked.slug;
       targetPath = join(targetDir, `${disambigSlug}.md`);
       slug = disambigSlug;
 
-      if (existsSync(targetPath)) {
+      if (picked.exists ?? existsSync(targetPath)) {
         // Still exists with disambig — check if it's ours
         const disambigContent = readFileSync(targetPath, 'utf8');
         const disambigFm = parseFrontmatter(disambigContent);
@@ -1035,6 +1296,10 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
       }
 
       const content = generator(entry, slug, generatorOpts);
+      if (!existsSync(targetPath)) {
+        const refused = refuseNewNote(content);
+        if (refused !== null) return refused;
+      }
       if (!dryRun) writeFileSync(targetPath, content, 'utf8');
       return emitEntryAction(_lineNum, ctx, {
         action: 'skipped-collision-resolved',
@@ -1046,32 +1311,61 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
       });
     }
 
+    // #1506.2: the main note is this record's — a live disambiguation copy of
+    // the same record (left by an interrupted takeover) is superseded.
+    const stale = fm['source-record'] === writer.recordKey
+      ? staleOwnDisambig(targetDir, slug, entryId, writer)
+      : null;
+
     // Same id: check if updated would advance (unless --force overrides).
     // Even when the date has not advanced, content may have changed (confidence,
     // insight, expires_at, etc.) — compare canonical fields before skipping.
     const entryUpdated = toDate(dateSource);
+    let mainUnchanged = false;
     if (!force && fm['updated'] && fm['updated'] >= entryUpdated) {
       const candidateContent = generator(entry, slug, generatorOpts);
       if (learningContentMatches(existingContent, candidateContent)) {
         // #1028 residue 1: probe the on-disk content against the CURRENT masker
         // before trusting the five-field match — see maskerWouldChange above.
-        const stillLeaks = maskerWouldChange(existingContent);
-        if (!stillLeaks) {
-          return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
-        }
+        mainUnchanged = !maskerWouldChange(existingContent);
       }
       // Content differs, or the on-disk note still leaks under the current env —
       // fall through to overwrite (same path as date-advance branch).
     }
 
+    // #1519.4: archive the stale copy AND refresh the main note in the SAME run
+    // (previously the stale branch returned first, so a simultaneous record
+    // change reached the main note one run later). Stale copy first: a crash
+    // between the two writes leaves an archived copy beside a not-yet-refreshed
+    // main note, which the next run's content diff completes.
+    if (stale !== null && !dryRun) writeFileSync(stale.path, stale.next, 'utf8');
+    if (mainUnchanged) {
+      if (stale !== null) {
+        return emitEntryAction(_lineNum, ctx, {
+          action: 'updated',
+          path: stale.path,
+          id: basename(stale.path, '.md'),
+          meta: { archived_reason: 'superseded' },
+        });
+      }
+      return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
+    }
+
     // Overwrite with advanced updated date (or forced re-render)
     const content = generator(entry, slug, generatorOpts);
     if (!dryRun) writeFileSync(targetPath, content, 'utf8');
-    return emitEntryAction(_lineNum, ctx, { action: 'updated', path: targetPath, id: slug });
+    return emitEntryAction(_lineNum, ctx, {
+      action: 'updated',
+      path: targetPath,
+      id: slug,
+      ...(stale !== null ? { meta: { superseded_id: basename(stale.path, '.md') } } : {}),
+    });
   }
 
   // File does not exist — create
   const content = generator(entry, slug, generatorOpts);
+  const refused = refuseNewNote(content);
+  if (refused !== null) return refused;
   if (!dryRun) writeFileSync(targetPath, content, 'utf8');
   return emitEntryAction(_lineNum, ctx, {
     action: 'created',
@@ -1084,6 +1378,224 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   });
 }
 
+/**
+ * The writer's own disambiguation note when it is stale (#1506.2): the writer's
+ * record owns the main note, so a mirror-owned, not-yet-archived note of the
+ * SAME record (explicit `source-record` match) at its disambiguation name is a
+ * second live copy — it is marked `archived` / `superseded`. Consulted by the
+ * takeover and on every run where the main note is already ours, so a crash
+ * between a takeover's writes heals on the next run.
+ *
+ * @returns {{ path: string, next: string }|null} the rewrite, or null.
+ */
+function staleOwnDisambig(targetDir, slug, entryId, writer) {
+  if (typeof writer.recordKey !== 'string') return null;
+  const own = disambigSlugFor(targetDir, slug, { legacyId: String(entryId), recordKey: writer.recordKey });
+  const path = join(targetDir, `${own.slug}.md`);
+  if (!(own.exists ?? existsSync(path))) return null;
+  const content = readFileSync(path, 'utf8');
+  const fm = parseFrontmatter(content);
+  if (notOurGenerator(fm) !== null || fm['source-record'] !== writer.recordKey || fm['id'] !== own.slug) return null;
+  const next = markArchived(content, 'superseded');
+  return next === content ? null : { path, next };
+}
+
+/**
+ * #1506.2 takeover: the writer's record is newer than the record that owns the
+ * main note, so the writer claims `<slug>.md`. The displaced note moves to its
+ * own record's disambiguation path (`id` renamed, bytes otherwise kept); a
+ * stale disambiguation note of the writer's own record (written while the older
+ * record held the main note) is marked `archived` / `superseded`.
+ *
+ * Returns `null` — leaving the caller on the plain disambiguation route — when
+ * the displaced record's target path is occupied by a note that is not ours or
+ * belongs to yet another record: a takeover must never overwrite anything.
+ *
+ * @returns {string|null} the emitted action, or null.
+ */
+function takeOverMainNote({
+  fm, slug, targetDir, targetPath, entry, entryId, writer, generator, generatorOpts, healedForeignLeak, lineNum, ctx,
+}) {
+  const { dryRun } = ctx;
+  const displacedKey = fm['source-record'];
+  const displaced = disambigSlugFor(targetDir, slug, { legacyId: displacedKey, recordKey: displacedKey });
+  const displacedPath = join(targetDir, `${displaced.slug}.md`);
+  if (displaced.exists !== true && existsSync(displacedPath)) {
+    const dfm = parseFrontmatter(readFileSync(displacedPath, 'utf8'));
+    if (notOurGenerator(dfm) !== null || dfm['source-record'] !== displacedKey) return null;
+  }
+
+  const ownStale = staleOwnDisambig(targetDir, slug, entryId, writer);
+
+  if (!dryRun) {
+    // Re-read: an in-place leak heal above may have rewritten the note.
+    const current = readFileSync(targetPath, 'utf8');
+    // Rewritten even when it exists (and is ours, checked above): a stale copy
+    // there may carry `status: archived` from an earlier archive pass.
+    writeFileSync(displacedPath, withNoteId(current, displaced.slug), 'utf8');
+    // Before the main note: a crash between the two writes must leave the
+    // takeover re-runnable (the main note still foreign), never a main note of
+    // ours beside a stale live disambiguation note of the same record.
+    if (ownStale !== null && ownStale.path !== displacedPath) writeFileSync(ownStale.path, ownStale.next, 'utf8');
+    writeFileSync(targetPath, generator(entry, slug, generatorOpts), 'utf8');
+  }
+  return emitEntryAction(lineNum, ctx, {
+    action: 'updated',
+    path: targetPath,
+    id: slug,
+    meta: {
+      reason: 'newer record owns the main note',
+      displaced_id: displaced.slug,
+      ...(healedForeignLeak ? { healed_leak: true } : {}),
+    },
+  });
+}
+
+/**
+ * The note slugs a learning record can live under: the canonical slug, for v1
+ * the pre-#725 legacy variant, and its two disambiguation names — the
+ * pre-#1506 `-<uuid8>` and the full-key `-<hash8>` (#1506.1). Used by the CLI
+ * to keep the archive pass off notes a LIVE record still owns (#1513). The
+ * disambiguation names are record-specific, so a record displaced from the
+ * main note by a re-learn (#1506.2) is still archived once it leaves the store.
+ *
+ * @param {object} rawEntry
+ * @returns {string[]}
+ */
+export function learningNoteSlugs(rawEntry) {
+  const entry = normalizeLearningEntry(rawEntry);
+  if (!entry || entry.id === null || entry.id === undefined) return [];
+  const schema = detectLearningSchema(entry);
+  const slugs = [learningSlug(entry, schema)];
+  if (schema === 'v1') {
+    const legacy = legacyConcatSlug(entry.subject);
+    if (isValidSlug(legacy) && !slugs.includes(legacy)) slugs.push(legacy);
+  }
+  const id = String(entry.id);
+  for (const name of [`${slugs[0]}-${uuidPrefix8(id)}`, `${slugs[0]}-${recordKeySuffix8(learningSourceRecord(entry) ?? id)}`]) {
+    if (!slugs.includes(name)) slugs.push(name);
+  }
+  return slugs;
+}
+
+/**
+ * Mark the existing note of a record that left `learnings.jsonl` (#1513).
+ *
+ * Input is one `learnings-archive.jsonl` record. Its note — canonical slug,
+ * legacy slug, or a `-<uuid8>`/`-<hash8>` disambiguation, in the namespace or the flat
+ * legacy layout — gets `status: archived` + `archived-reason` (`expired` for an
+ * `_archive_reason: expired` record, `superseded` for every other reason). The
+ * note's bytes are otherwise kept; nothing is ever created. Ownership rules are
+ * the same as for writes: mirror-owned, and a `source-record` naming another
+ * record is left alone. Names in `ctx.liveLearningSlugs` (records still in the
+ * live store) are skipped, so a re-learned subject never flip-flops.
+ *
+ * @returns {Promise<string>} the emitted action
+ */
+export async function processArchivedLearning(rawEntry, _lineNum, ctx) {
+  const { vaultDir, dryRun } = ctx;
+  const entry = maskEntrySecrets(normalizeLearningEntry(rawEntry));
+  if (!entry || entry.id === null || entry.id === undefined) {
+    throw new Error(`vault-mirror: archived learning entry missing required field 'id' (id=<no id>)`);
+  }
+  const reason = entry._archive_reason === 'expired' ? 'expired' : 'superseded';
+  const live = ctx?.liveLearningSlugs instanceof Set ? ctx.liveLearningSlugs : new Set();
+  // Per name, not per record (#1506.2): a live re-learn owns the canonical
+  // slug, but the displaced note at THIS record's disambiguation name is still
+  // this record's to archive.
+  const allNames = learningNoteSlugs(entry);
+  const names = allNames.filter((s) => !live.has(s));
+  const liveOwned = () =>
+    emitEntryAction(_lineNum, ctx, {
+      // `skipped-noop`, not a class of its own: this is the steady state of
+      // every run, and noops stay out of the per-entry ledger (#1151).
+      action: 'skipped-noop',
+      path: null,
+      id: entry.id,
+      meta: { reason: 'archived record: a live record owns this note' },
+    });
+  if (names.length === 0) return liveOwned();
+  const repoNs = canonicalNamespace(
+    vaultDir,
+    resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
+  );
+  const nsDir = join(resolve(vaultDir), '40-learnings', repoNs);
+  const flatDir = join(resolve(vaultDir), '40-learnings');
+  const writer = { recordKey: learningSourceRecord(entry) };
+  for (const dir of [nsDir, flatDir]) {
+    for (const name of names) {
+      const path = join(dir, `${name}.md`);
+      if (!existsSync(path)) continue;
+      const content = readFileSync(path, 'utf8');
+      const fm = parseFrontmatter(content);
+      if (notOurGenerator(fm) !== null || fm['id'] !== name) continue;
+      if (foreignOwnerReason(fm, writer) !== null) continue;
+      const next = markArchived(content, reason);
+      if (next === content) {
+        return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path, id: name });
+      }
+      if (!dryRun) writeFileSync(path, next, 'utf8');
+      return emitEntryAction(_lineNum, ctx, {
+        action: 'updated',
+        path,
+        id: name,
+        meta: { archived_reason: reason },
+      });
+    }
+  }
+  if (names.length < allNames.length) return liveOwned();
+  return emitEntryAction(_lineNum, ctx, {
+    action: 'skipped-noop',
+    path: null,
+    id: entry.id,
+    meta: { reason: 'archived record: no note in the vault' },
+  });
+}
+
+/**
+ * Route a metrics-only session record (#1513): a note that already exists for
+ * it is left exactly as it is (the pruner decides about the bestand), and
+ * otherwise the record becomes one row in its month rollup. Idempotent: an
+ * unchanged rollup is a `skipped-noop`.
+ */
+async function rollUpSession({ renderedBody, session_id, repoNs, narrativeChars, lineNum, ctx }) {
+  const { vaultDir, dryRun, qualityMinNarrativeChars = 400 } = ctx;
+  const reason = `narrative:${narrativeChars} < min:${qualityMinNarrativeChars}`;
+  const root = resolve(vaultDir);
+  const existingNote = [join(root, '50-sessions', repoNs, `${session_id}.md`), join(root, '50-sessions', `${session_id}.md`)].find(
+    (p) => existsSync(p),
+  );
+  const row = rollupRowFromNote(renderedBody, { id: session_id });
+  if (existingNote !== undefined || row === null) {
+    return emitEntryAction(lineNum, ctx, { action: 'skipped-quality-low', path: null, id: session_id, meta: { reason } });
+  }
+  const month = row.date.slice(0, 7);
+  const rollupPath = join(root, rollupRelPath(repoNs, month));
+  let existing = null;
+  if (existsSync(rollupPath)) {
+    existing = readFileSync(rollupPath, 'utf8');
+    const notOurs = notOurGenerator(parseFrontmatter(existing));
+    if (notOurs !== null) {
+      process.stderr.write(`SKIP ${notOurs}: ${toVaultRelative(rollupPath, vaultDir)}\n`);
+      return emitEntryAction(lineNum, ctx, { action: 'skipped-handwritten', path: rollupPath, id: session_id });
+    }
+  }
+  const next = renderRollup(existing, [row], { ns: repoNs, month });
+  if (next === existing) {
+    return emitEntryAction(lineNum, ctx, { action: 'skipped-noop', path: rollupPath, id: session_id, meta: { reason } });
+  }
+  if (!dryRun) {
+    mkdirSync(join(root, '50-sessions', repoNs), { recursive: true });
+    writeFileSync(rollupPath, next, 'utf8');
+  }
+  return emitEntryAction(lineNum, ctx, {
+    action: 'skipped-metrics-only',
+    path: rollupPath,
+    id: session_id,
+    meta: { reason },
+  });
+}
+
 export async function processSession(rawEntry, _lineNum, ctx) {
   const {
     vaultDir,
@@ -1159,32 +1671,28 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // owner-leaky repo's real name reached the vault through the session-note
   // frontmatter even though the directory AND the learning `source-repo` field
   // were already pseudonym-mapped/redacted (#732 leak-guard bypass).
-  const repoNs = resolveRepoNamespace({
-    vaultName: ctx?.vaultName ?? null,
-    repoRoot: ctx?.repoRoot ?? null,
-  });
+  const repoNs = canonicalNamespace(
+    vaultDir,
+    resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
+  );
 
-  // Quality gate (PRD F1.2): skip sessions whose rendered narrative is too short.
-  // Measure on the rendered markdown body so the check is schema-agnostic across
-  // v1 and v2 producers. The render is cheap and idempotent; we reuse the result
-  // below instead of calling generator() a second time.
-  // Runs BEFORE the --force branch so --force does NOT bypass the quality filter.
-  // If the generator throws a `vault-mirror: …` validation error (missing
-  // required field), it propagates up to vault-mirror.mjs which classifies it
-  // as `skipped-invalid` rather than `skipped-quality-low` — semantically more
-  // accurate for the metrics summary in session-end Phase 3.7.
+  // Narrative gate (#1513, replaces the PRD F1.2 rendered-length gate). A
+  // session gets its own note only when its FREE-TEXT fields (`notes`,
+  // `narrative`, `summary` — see retention.mjs) carry at least
+  // `qualityMinNarrativeChars` characters. The old gate measured the rendered
+  // body INCLUDING the wave/agent tables, so nearly every record passed: 2.728
+  // of 3.003 vault session notes were tables with no information beyond git
+  // (Jev audit 2026-10-03). A record below the gate becomes one row in the
+  // month rollup `50-sessions/<ns>/_rollup-YYYY-MM.md` instead. `0` disables
+  // the gate. Runs BEFORE --force; --force does NOT bypass it.
+  //
+  // The render still happens first: a generator `vault-mirror: …` validation
+  // error must keep surfacing as `skipped-invalid`, and the rollup row is read
+  // off the rendered note so the mirror and the pruner share one parser.
   const renderedBody = generator(entry, { repoNs });
-  // Strip YAML frontmatter (lines between the first two `---` markers) so we
-  // measure only narrative content, not boilerplate.
-  const narrativeBody = renderedBody.replace(/^---[\s\S]*?---/m, '').trim();
-  const narrativeChars = narrativeBody.length;
+  const narrativeChars = sessionNarrativeChars(entry);
   if (narrativeChars < qualityMinNarrativeChars) {
-    return emitEntryAction(_lineNum, ctx, {
-      action: 'skipped-quality-low',
-      path: null,
-      id: session_id,
-      meta: { reason: `narrative:${narrativeChars} < min:${qualityMinNarrativeChars}` },
-    });
+    return rollUpSession({ renderedBody, session_id, repoNs, narrativeChars, lineNum: _lineNum, ctx });
   }
 
   // #660: namespace new writes under a per-repo subdirectory. repoNs was
@@ -1239,7 +1747,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
     }
     if (legacyMarked && !legacyForeign) {
       const entryUpdated = toDate(entry.completed_at);
-      if (!force && !legacyStillLeaks && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
+      const legacyNarrativeStale = noteNarrativeChars(legacyContent) !== noteNarrativeChars(renderedBody);
+      if (!force && !legacyStillLeaks && !legacyNarrativeStale && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
         return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: legacyFlatPath, id: session_id });
       }
       // Updated date would advance, or the on-disk note still leaks — fall
@@ -1285,7 +1794,11 @@ export async function processSession(rawEntry, _lineNum, ctx) {
     }
 
     const entryUpdated = toDate(entry.completed_at);
-    if (!force && !existingLeaks && fm['updated'] && fm['updated'] >= entryUpdated) {
+    // #1513 review H2: a note rendered before narrative/summary were printed
+    // carries less free text than the record — heal it once, or the pruner
+    // archives it as metrics-only and the mirror re-creates it every run.
+    const narrativeStale = noteNarrativeChars(existingContent) !== noteNarrativeChars(renderedBody);
+    if (!force && !existingLeaks && !narrativeStale && fm['updated'] && fm['updated'] >= entryUpdated) {
       return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: session_id });
     }
     if (!dryRun) writeFileSync(targetPath, renderedBody, 'utf8');