session-orchestrator 5.10.0 → 5.12.0

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

@@ -10,7 +10,7 @@ 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, recordKeySuffix8, toDate, parseFrontmatter } from './utils.mjs';
+import { subjectToSlug, legacySubjectToSlug, 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';
@@ -19,7 +19,6 @@ import { emitMirrorEvent } from './telemetry.mjs';
 import {
   ARCHIVE_ROOT,
   canonicalNamespace,
-  legacyConcatSlug,
   noteNarrativeChars,
   markArchived,
   noteInsightKey,
@@ -904,7 +903,7 @@ function maskEntrySecrets(entry) {
  * @param {'v1'|'v2'} schema
  * @returns {string}
  */
-function learningSlug(entry, schema) {
+function learningSlug(entry, schema, slugger = learningNameSlugger(entry)) {
   const entryId = entry.id;
   let slugSource;
   if (schema === 'v2') {
@@ -916,7 +915,7 @@ function learningSlug(entry, schema) {
   }
   let slug;
   if (typeof slugSource === 'string' && slugSource.length > 0) {
-    slug = subjectToSlug(slugSource);
+    slug = slugger(slugSource);
   } else {
     slug = '';
   }
@@ -936,6 +935,52 @@ function learningSlug(entry, schema) {
 }
 
 
+/** A record without representable provenance (v1 or v2) keeps its historical name. */
+function learningNameSlugger(entry) {
+  return learningSourceRecord(entry) === null ? legacySubjectToSlug : subjectToSlug;
+}
+
+/** Compare BEFORE filename capping so a changed concatenated name is protected. */
+function hasLearningSlugTransition(entry, schema) {
+  if (learningNameSlugger(entry) === legacySubjectToSlug) return false;
+  const source = schema === 'v2' ? entry.id : entry.subject;
+  if (typeof source !== 'string' || source.length === 0) return false;
+  const normalized = schema === 'v1' ? source.trim().replace(/\s+/g, '-') : source;
+  return subjectToSlug(normalized) !== legacySubjectToSlug(normalized) ||
+    (schema === 'v1' && subjectToSlug(source) !== legacySubjectToSlug(source));
+}
+
+function historicalConcatSlug(subject) {
+  if (typeof subject !== 'string') return '';
+  return legacySubjectToSlug(subject);
+}
+
+/** All historical names, including both generations of disambiguation suffix. */
+function learningSlugVariants(entry, schema) {
+  const bases = new Set([learningSlug(entry, schema), learningSlug(entry, schema, legacySubjectToSlug)]);
+  if (schema === 'v1') {
+    const concat = historicalConcatSlug(entry.subject);
+    if (isValidSlug(concat)) {
+      bases.add(concat);
+      if (concat.length > 240) bases.add(concat.slice(0, 240).replace(/-+$/, ''));
+    }
+  }
+  const names = new Set(bases);
+  const id = String(entry.id);
+  for (const base of bases) {
+    names.add(`${base}-${uuidPrefix8(id)}`);
+    names.add(`${base}-${recordKeySuffix8(learningSourceRecord(entry) ?? id)}`);
+  }
+  return [...names];
+}
+
+/** Only explicit, exact provenance permits assigning an old name to a record. */
+function positiveLearningOwner(fm, name, repoNs, recordKey) {
+  return recordKey !== null && notOurGenerator(fm) === null &&
+    fm['id'] === name && fm['source-record'] === recordKey && fm['source-repo'] === repoNs;
+}
+
+
 export async function processLearning(rawEntry, _lineNum, ctx) {
   const {
     vaultDir,
@@ -1023,10 +1068,8 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // #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 }),
-  );
+  const stableNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null });
+  const repoNs = canonicalNamespace(vaultDir, stableNs);
   // #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
@@ -1075,18 +1118,56 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     return null;
   };
   const targetDir = join(resolve(vaultDir), '40-learnings', repoNs);
-  if (!dryRun) mkdirSync(targetDir, { recursive: true });
 
   let targetPath = join(targetDir, `${slug}.md`);
 
+  // #1548: inspect EVERY candidate before mutation when normalization changes
+  // a name. Missing/foreign/ambiguous provenance is not permission to create a
+  // second note, including under --force. Keep the actual flat or namespace path.
+  const slugTransition = hasLearningSlugTransition(entry, schema);
+  if (slugTransition) {
+    const matches = [];
+    for (const dir of [targetDir, join(resolve(vaultDir), '40-learnings')]) {
+      for (const name of learningSlugVariants(entry, schema)) {
+        const path = join(dir, `${name}.md`);
+        if (!existsSync(path)) continue;
+        const fm = parseFrontmatter(readFileSync(path, 'utf8'));
+        matches.push({ path, name, valid: positiveLearningOwner(fm, name, repoNs, writer.recordKey) });
+      }
+    }
+    if (matches.length > 1 || matches.some((match) => !match.valid)) {
+      return emitEntryAction(_lineNum, ctx, {
+        action: 'skipped-foreign-owner', path: null, id: entryId,
+        meta: { reason: 'slug transition: ambiguous or missing/contradictory provenance' },
+      });
+    }
+    if (matches.length === 1) {
+      slug = matches[0].name;
+      targetPath = matches[0].path;
+    }
+  }
+
+  // A provenance-less flat v2 note cannot be assigned to this namespace.
+  // Keep it untouched rather than creating a second copy on an advanced date.
+  if (schema === 'v2' && writer.recordKey === null &&
+      learningSlugVariants(entry, schema).some((name) =>
+        existsSync(join(resolve(vaultDir), '40-learnings', name + '.md')))) {
+    return emitEntryAction(_lineNum, ctx, {
+      action: 'skipped-foreign-owner', path: null, id: entryId,
+      meta: { reason: 'flat note: missing representable source provenance' },
+    });
+  }
+
+  if (!dryRun) mkdirSync(targetDir, { recursive: true });
+
   // #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);
+  if (!slugTransition && schema === 'v1') {
+    const legacySlug = historicalConcatSlug(entry.subject);
     const flatDir = join(resolve(vaultDir), '40-learnings');
     if (
       isValidSlug(legacySlug) &&
@@ -1104,7 +1185,9 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
           foreignOwnerReason(legacyFm, writer) === null
         ) {
           slug = legacySlug;
-          targetPath = join(targetDir, `${legacySlug}.md`);
+          targetPath = positiveLearningOwner(legacyFm, legacySlug, repoNs, writer.recordKey)
+            ? legacyPath
+            : join(targetDir, `${legacySlug}.md`);
           break;
         }
       }
@@ -1114,8 +1197,8 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
   // #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
-  // duplicating the note. The deferred-migration decision means we only skip;
-  // we do NOT move the flat note into the namespaced dir here.
+  // duplicating the note. Positive provenance also permits an update at the
+  // actual flat path; notes without that evidence keep their historical rules.
   const legacyFlatPath = join(resolve(vaultDir), '40-learnings', `${slug}.md`);
   // Set when a still-leaking legacy flat note was healed in place below, so the
   // action emitted for THIS entry can say so (see the write sites at the end).
@@ -1142,7 +1225,11 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     if (legacyForeign && legacyStillLeaks) {
       healedForeignLeak = maskForeignNoteInPlace(legacyFlatPath, legacyContent, ctx);
     }
-    if (legacyMarked && !legacyForeign) {
+    if (positiveLearningOwner(legacyFm, slug, repoNs, writer.recordKey)) {
+      // A proven flat note is the update target. Let the common existing-note
+      // branch below compare/render/heal it ONCE; never pre-write a healed copy.
+      targetPath = legacyFlatPath;
+    } else if (legacyMarked && !legacyForeign) {
       const entryUpdated = toDate(dateSource);
       if (!force && legacyFm['updated'] && legacyFm['updated'] >= entryUpdated) {
         // Date has not advanced — but content may have changed (confidence, insight, etc.).
@@ -1313,7 +1400,7 @@ 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
+    const stale = !slugTransition && fm['source-record'] === writer.recordKey
       ? staleOwnDisambig(targetDir, slug, entryId, writer)
       : null;
 
@@ -1351,14 +1438,19 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
       return emitEntryAction(_lineNum, ctx, { action: 'skipped-noop', path: targetPath, id: slug });
     }
 
-    // Overwrite with advanced updated date (or forced re-render)
+    // Overwrite with advanced updated date (or forced re-render). A retained
+    // flat note, including an old Unicode slug, is healed by this single write.
     const content = generator(entry, slug, generatorOpts);
+    healedLegacyFlat = !dryRun && targetPath === legacyFlatPath && maskerWouldChange(existingContent);
     if (!dryRun) writeFileSync(targetPath, content, 'utf8');
     return emitEntryAction(_lineNum, ctx, {
       action: 'updated',
       path: targetPath,
       id: slug,
-      ...(stale !== null ? { meta: { superseded_id: basename(stale.path, '.md') } } : {}),
+      ...((stale !== null || healedLegacyFlat) ? { meta: {
+        ...(stale !== null ? { superseded_id: basename(stale.path, '.md') } : {}),
+        ...(healedLegacyFlat ? { healed_legacy_flat: true } : {}),
+      } } : {}),
     });
   }
 
@@ -1465,17 +1557,7 @@ function takeOverMainNote({
 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;
+  return learningSlugVariants(entry, detectLearningSchema(entry));
 }
 
 /**
@@ -1515,13 +1597,36 @@ export async function processArchivedLearning(rawEntry, _lineNum, ctx) {
       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 stableNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null });
+  const repoNs = canonicalNamespace(vaultDir, stableNs);
   const nsDir = join(resolve(vaultDir), '40-learnings', repoNs);
   const flatDir = join(resolve(vaultDir), '40-learnings');
   const writer = { recordKey: learningSourceRecord(entry) };
+  const schema = detectLearningSchema(entry);
+  if (schema === 'v2' && writer.recordKey === null &&
+      allNames.some((name) => existsSync(join(flatDir, name + '.md')))) {
+    return emitEntryAction(_lineNum, ctx, {
+      action: 'skipped-foreign-owner', path: null, id: entry.id,
+      meta: { reason: 'flat note: missing representable source provenance' },
+    });
+  }
+  if (hasLearningSlugTransition(entry, schema)) {
+    const matches = [];
+    for (const dir of [nsDir, flatDir]) {
+      for (const name of allNames) {
+        const path = join(dir, `${name}.md`);
+        if (!existsSync(path)) continue;
+        const fm = parseFrontmatter(readFileSync(path, 'utf8'));
+        matches.push(positiveLearningOwner(fm, name, repoNs, writer.recordKey));
+      }
+    }
+    if (matches.length > 1 || matches.some((valid) => !valid)) {
+      return emitEntryAction(_lineNum, ctx, {
+        action: 'skipped-foreign-owner', path: null, id: entry.id,
+        meta: { reason: 'slug transition: ambiguous or missing/contradictory provenance' },
+      });
+    }
+  }
   for (const dir of [nsDir, flatDir]) {
     for (const name of names) {
       const path = join(dir, `${name}.md`);
@@ -1615,8 +1720,8 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   const generator =
     schema === 'v3' ? generateSessionNoteV3 : schema === 'v2' ? generateSessionNoteV2 : generateSessionNote;
 
-  // Validate session_id as a filesystem-safe slug; fall back via subjectToSlug
-  // (which collapses slashes to last segment + strips invalid chars) before
+  // Validate session_id as a filesystem-safe slug; preserve old Session identity
+  // with the historical sanitizer (collapse slash paths + strip invalid chars), before
   // resorting to a uuid-derived slug. Without subjectToSlug, raw slashes in
   // rawSessionId (e.g. "feat/opus-4-7-...") would survive uuidPrefix8 and
   // produce a path with directory separators in the basename.
@@ -1624,7 +1729,7 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   if (isValidSlug(rawSessionId)) {
     session_id = rawSessionId;
   } else if (typeof rawSessionId === 'string' && rawSessionId.length > 0) {
-    const sanitised = subjectToSlug(rawSessionId);
+    const sanitised = legacySubjectToSlug(rawSessionId);
     session_id = isValidSlug(sanitised) ? sanitised : `session-${uuidPrefix8(rawSessionId)}`;
   } else {
     session_id = `session-${uuidPrefix8(randomUUID())}`;
@@ -1671,10 +1776,8 @@ 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 = canonicalNamespace(
-    vaultDir,
-    resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null }),
-  );
+  const stableNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null, repoRoot: ctx?.repoRoot ?? null });
+  const repoNs = canonicalNamespace(vaultDir, stableNs);
 
   // Narrative gate (#1513, replaces the PRD F1.2 rendered-length gate). A
   // session gets its own note only when its FREE-TEXT fields (`notes`,

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

@@ -5,7 +5,7 @@
  *          sourceRecordValue, learningSourceRecord, sourceRecordLine (#1503)
  */
 
-import { toDate, truncateAtWord, yamlQuoteIfNeeded, subjectToSlug, isValidSlug, buildTag, resolveSourceSessionLink } from './utils.mjs';
+import { toDate, truncateAtWord, yamlQuoteIfNeeded, legacySubjectToSlug, isValidSlug, buildTag, resolveSourceSessionLink } from './utils.mjs';
 
 const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
 
@@ -118,9 +118,10 @@ export function normalizeLearningEntry(entry) {
     e.evidence = joinList(e.evidence_sessions) ?? joinList(e.files) ?? joinList(e.sessions) ?? '(none recorded)';
   }
   if (e.id === null || e.id === undefined) {
-    // subjectToSlug strips whitespace without hyphenating (designed for
+    // Keep historical ASCII deletion for record identity; only note names
+    // transliterate. The old slugger strips whitespace (designed for
     // kebab-ish inputs) — pre-map whitespace to hyphens for prose subjects.
-    const derived = firstString(e.subject) ? subjectToSlug(e.subject.trim().replace(/\s+/g, '-')) : '';
+    const derived = firstString(e.subject) ? legacySubjectToSlug(e.subject.trim().replace(/\s+/g, '-')) : '';
     if (isValidSlug(derived)) e.id = derived;
   }
   if (e.source_session === null || e.source_session === undefined) {
@@ -157,7 +158,7 @@ export function generateLearningNote(entry, slug, opts = {}) {
   // through buildTag so each is kebab-slugified and capped at 64 chars. The
   // existing source/<session> slug is preserved (buildTag is idempotent for an
   // already-kebab value and adds the length cap).
-  const sourceTag = subjectToSlug(String(source_session)) || 'unknown';
+  const sourceTag = legacySubjectToSlug(String(source_session)) || 'unknown';
   const tags = `[${buildTag(['learning', type])}, ${buildTag(['status', status])}, ${buildTag(['source', sourceTag])}]`;
 
   // Check if expires has a value; it's optional in schema
@@ -230,7 +231,7 @@ export function generateLearningNoteV2(entry, slug, opts = {}) {
   const title = yamlQuoteIfNeeded(titleRaw);
 
   // #602: type/status interpolated raw upstream — slugify + cap each segment.
-  const scopeTag = subjectToSlug(scope) || 'unscoped';
+  const scopeTag = legacySubjectToSlug(scope) || 'unscoped';
   const tags = `[${buildTag(['learning', type])}, ${buildTag(['status', status])}, ${buildTag(['scope', scopeTag])}]`;
 
   // #725 D2: emit `source-repo` for cross-repo attribution when the caller threads

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,9 +134,11 @@ 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`;
@@ -198,7 +211,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-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);
     }

package/scripts/measure-context-overhead.sh

@@ -44,6 +44,8 @@
 set -uo pipefail
 
 PROMPT='Antworte nur mit dem Wort: OK'
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+FORMATTER="$SCRIPT_DIR/lib/context-overhead-format.mjs"
 
 measure_one() {
   local dir="$1" label="$2"
@@ -51,29 +53,10 @@ measure_one() {
     printf '%s\tNO-SUCH-DIR\n' "$label"
     return
   fi
-  ( cd "$dir" && claude -p "$PROMPT" --output-format json 2>/dev/null ) | node -e "
-let s = '';
-process.stdin.on('data', (d) => (s += d)).on('end', () => {
-  const label = process.argv[1];
-  try {
-    const j = JSON.parse(s);
-    const u = j.usage || {};
-    const ctx =
-      (u.input_tokens || 0) +
-      (u.cache_creation_input_tokens || 0) +
-      (u.cache_read_input_tokens || 0);
-    process.stdout.write(
-      [label, ctx, u.cache_creation_input_tokens || 0, u.cache_read_input_tokens || 0,
-       u.output_tokens || 0, (j.total_cost_usd || 0).toFixed(4)].join('\t') + '\n',
-    );
-  } catch {
-    process.stdout.write(label + '\tPARSE-ERROR\n');
-  }
-});
-" "$label"
+  ( cd "$dir" && claude -p "$PROMPT" --output-format json 2>/dev/null ) | node "$FORMATTER" -- "$label"
 }
 
-header() { printf 'LABEL\tCONTEXT_TOK\tcache_create\tcache_read\toutput\tUSD\n'; }
+header() { node "$FORMATTER" --header; }
 
 # ── --ablate mode ───────────────────────────────────────────────────
 if [ "${1:-}" = "--ablate" ]; then