@remnic/core 9.3.645 → 9.3.647

package/src/session-identity.ts

@@ -0,0 +1,281 @@
+import path from "node:path";
+import {
+  encodeStoragePathSegment,
+  encodeStoragePathSegmentWithHash,
+  isSafeLegacyPathSegment,
+  storagePathHash,
+} from "./storage-paths.js";
+
+/**
+ * Shared session-identity / transcript-pathing layer (issue #1496).
+ *
+ * This module is the SINGLE source of truth for turning a `sessionKey` into a
+ * channel identity and a set of deterministic, collision-resistant storage
+ * paths. Every subsystem that previously re-parsed session keys (transcript
+ * pathing, tool-usage pathing, hourly summaries, session auditing, conversation
+ * indexing) MUST route through `parseSessionIdentity()` / `sessionStoragePaths()`
+ * so behavior stays identical across paths (rule #22, #39).
+ *
+ * Two shapes are recognized:
+ *
+ *   1. Legacy `agent:<agentId>:<channelType>:...` keys keep their existing
+ *      readable channel identity:
+ *        - agent:<id>:main                      → type="main",    id="default"
+ *        - agent:<id>:discord:channel:<chanId>  → type="discord", id="<chanId>"
+ *        - agent:<id>:slack:channel:<chanId>    → type="slack",   id="<chanId>"
+ *        - agent:<id>:cron:<jobId>              → type="cron",    id="<jobId>"
+ *        - agent:<id>:<other>[:<id>]            → type="<other>", id="<id?>"
+ *
+ *   2. Arbitrary / non-legacy keys (e.g. `pi-geek:abc123`) become first-class
+ *      from the FIRST write — they NEVER start life under `other/default`:
+ *        channelType = "session"
+ *        channelId   = storagePathHash(sessionKey)   (collision-resistant)
+ *      yielding `transcripts/session/<hash>/YYYY-MM-DD.jsonl`.
+ *
+ * The reserved `"session"` channel type is what makes arbitrary keys isolated
+ * and auditable. Legacy data under `other/default` (and any legacy channel
+ * directory) remains READABLE via `legacyDir` / `alternateDir` candidates.
+ */
+
+/** Channel type reserved for first-class arbitrary (non-legacy) session keys. */
+export const SESSION_CHANNEL_TYPE = "session";
+
+/** Legacy fallback channel identity for un-parseable keys (read-back only). */
+export const LEGACY_FALLBACK_CHANNEL_TYPE = "other";
+export const LEGACY_FALLBACK_CHANNEL_ID = "default";
+
+/** Max characters of the raw session key kept in a human-readable display label. */
+const DISPLAY_LABEL_MAX_LENGTH = 64;
+
+export interface SessionIdentity {
+  /** Channel type — legacy channel type for known shapes, else `"session"`. */
+  channelType: string;
+  /** Channel id — legacy channel id for known shapes, else the key hash. */
+  channelId: string;
+  /** Human-readable, non-authoritative label derived from the raw key. */
+  displayLabel: string;
+  /** The original session key, unchanged. */
+  canonicalSessionKey: string;
+  /** True when the key matched a known legacy `agent:<id>:...` shape. */
+  legacy: boolean;
+}
+
+export interface SessionStoragePaths {
+  /** Channel type (mirrors {@link SessionIdentity.channelType}). */
+  channelType: string;
+  /** Channel id (mirrors {@link SessionIdentity.channelId}). */
+  channelId: string;
+  /** Primary encoded storage subdirectory: `<encodedType>/<encodedId>`. */
+  dir: string;
+  /**
+   * Collision-resistant alternate subdirectory that always embeds the full
+   * session-key hash. Used both as a write-time collision escape hatch and as a
+   * read-back candidate for data written before this layer existed.
+   */
+  alternateDir: string;
+  /**
+   * Un-encoded `<type>/<id>` directory for reading data written by older
+   * builds that did not URL-encode path segments. Undefined when it would be
+   * identical to `dir` or when either segment is path-unsafe.
+   */
+  legacyDir?: string;
+  /**
+   * Ordered, de-duplicated list of READ-BACK-ONLY directories where an older
+   * build may have stranded this key's data. NEW writes never target these —
+   * they exist purely so pre-#1496 transcripts/tool-usage stay discoverable
+   * (and migratable). Populated only for non-legacy keys. Includes:
+   *   1. the shared `other/default` fallback (every arbitrary key landed here);
+   *   2. the directory the OLD `parts.length >= 3` parser would have chosen
+   *      (e.g. `foo:bar:baz` → `baz/default`, `foo:bar:baz:qux` → `baz/qux`).
+   * See {@link legacyParserReadbackDir}.
+   */
+  readbackDirs: string[];
+}
+
+/**
+ * Parse a session key into a stable channel identity.
+ *
+ * Pure and deterministic — no filesystem access. Same input always yields the
+ * same identity, which is what makes arbitrary keys collision-resistant from
+ * the first write.
+ */
+export function parseSessionIdentity(sessionKey: string): SessionIdentity {
+  const canonicalSessionKey = typeof sessionKey === "string" ? sessionKey : "";
+  const legacy = parseLegacyChannelIdentity(canonicalSessionKey);
+  if (legacy) {
+    return {
+      channelType: legacy.channelType,
+      channelId: legacy.channelId,
+      displayLabel: safeDisplayLabel(canonicalSessionKey),
+      canonicalSessionKey,
+      legacy: true,
+    };
+  }
+
+  return {
+    channelType: SESSION_CHANNEL_TYPE,
+    channelId: storagePathHash(canonicalSessionKey),
+    displayLabel: safeDisplayLabel(canonicalSessionKey),
+    canonicalSessionKey,
+    legacy: false,
+  };
+}
+
+/**
+ * Resolve the storage path pieces for a session key. Wraps
+ * {@link parseSessionIdentity} so transcript, tool-usage, and summary writers
+ * share one implementation (rule #22).
+ */
+export function sessionStoragePaths(sessionKey: string): SessionStoragePaths {
+  const identity = parseSessionIdentity(sessionKey);
+  const { channelType, channelId, canonicalSessionKey } = identity;
+
+  const dir = path.join(encodeStoragePathSegment(channelType), encodeStoragePathSegment(channelId));
+
+  const alternateDir = path.join(
+    encodeStoragePathSegmentWithHash(channelType),
+    `${encodeStoragePathSegmentWithHash(channelId)}--session-${storagePathHash(canonicalSessionKey)}`
+  );
+
+  let legacyDir: string | undefined;
+  if (isSafeLegacyPathSegment(channelType) && isSafeLegacyPathSegment(channelId)) {
+    const candidate = path.join(channelType, channelId);
+    if (candidate !== dir) {
+      legacyDir = candidate;
+    }
+  }
+
+  // Read-back-only candidates are only relevant for non-legacy keys: legacy
+  // `agent:<id>:...` keys still resolve to their original channel directory, so
+  // nothing about their on-disk location moved.
+  const readbackDirs: string[] = [];
+  if (!identity.legacy) {
+    const seen = new Set<string>([dir]);
+    if (alternateDir) seen.add(alternateDir);
+    if (legacyDir) seen.add(legacyDir);
+    for (const candidate of [OTHER_DEFAULT_READBACK_DIR, legacyParserReadbackDir(canonicalSessionKey)]) {
+      if (!candidate || seen.has(candidate)) continue;
+      seen.add(candidate);
+      readbackDirs.push(candidate);
+    }
+  }
+
+  return { channelType, channelId, dir, alternateDir, legacyDir, readbackDirs };
+}
+
+/**
+ * The shared `other/default` directory every arbitrary key was routed into by
+ * builds predating issue #1496. Exposed so transcript/tool-usage/summary read
+ * paths and the migration scanner all agree on the same fallback location.
+ */
+export const OTHER_DEFAULT_READBACK_DIR = path.join(
+  LEGACY_FALLBACK_CHANNEL_TYPE,
+  LEGACY_FALLBACK_CHANNEL_ID
+);
+
+/**
+ * Reconstruct the transcript/tool-usage directory the OLD `getTranscriptPath`
+ * parser (pre-#1496) would have produced for a key the NEW parser reclassifies
+ * as a first-class `session/<hash>` identity.
+ *
+ * The OLD parser treated ANY key with `parts.length >= 3` as legacy — it did
+ * NOT require a leading `agent` segment — so an arbitrary key like
+ * `foo:bar:baz` was stored under `baz/default` and `foo:bar:baz:qux` under
+ * `baz/qux`. Those directories must stay readable (and migratable) for existing
+ * installs even though the key now writes to `session/<hash>` (Thread B / codex
+ * review on PR #1504). Path segments are encoded exactly as the old `dir` was
+ * built (`encodeStoragePathSegment`) so the candidate matches the bytes on disk.
+ *
+ * Returns `undefined` when the key has fewer than three colon parts (the old
+ * parser would have used the `other/default` fallback, already covered), when
+ * the channel type is empty, or when the result is unsafe.
+ */
+export function legacyParserReadbackDir(sessionKey: string): string | undefined {
+  if (typeof sessionKey !== "string" || sessionKey.length === 0) return undefined;
+  const parts = sessionKey.split(":");
+  if (parts.length < 3) return undefined;
+
+  const channelType = parts[2];
+  if (!channelType || channelType.length === 0) return undefined;
+
+  // Mirror the OLD parser's channelId derivation for parts.length >= 3 keys.
+  let channelId = LEGACY_FALLBACK_CHANNEL_ID;
+  if (channelType === "main") {
+    channelId = "default";
+  } else if (channelType === "discord" && parts.length >= 5 && parts[3] === "channel") {
+    channelId = parts[4];
+  } else if (channelType === "slack" && parts.length >= 5 && parts[3] === "channel") {
+    channelId = parts[4];
+  } else if (channelType === "cron" && parts.length >= 4) {
+    channelId = parts[3];
+  } else if (parts.length >= 4) {
+    channelId = parts[3];
+  }
+  if (!channelId || channelId.length === 0) {
+    channelId = LEGACY_FALLBACK_CHANNEL_ID;
+  }
+
+  return path.join(encodeStoragePathSegment(channelType), encodeStoragePathSegment(channelId));
+}
+
+/**
+ * Parse the legacy `agent:<agentId>:<channelType>:...` shape. Returns
+ * `undefined` for anything that is not a recognized legacy key, so the caller
+ * can route it to a first-class `session/<hash>` identity instead.
+ *
+ * A legacy key must start with the literal `agent` segment and a non-empty
+ * agent id; otherwise an arbitrary key like `pi-geek:abc123` would be
+ * misread as `channelType = "abc123"`.
+ */
+function parseLegacyChannelIdentity(sessionKey: string): { channelType: string; channelId: string } | undefined {
+  if (sessionKey.length === 0) return undefined;
+  const parts = sessionKey.split(":");
+  if (parts.length < 3) return undefined;
+  if (parts[0] !== "agent") return undefined;
+  if (!parts[1] || parts[1].length === 0) return undefined;
+
+  const channelType = parts[2];
+  if (!channelType || channelType.length === 0) return undefined;
+
+  let channelId = LEGACY_FALLBACK_CHANNEL_ID;
+  if (channelType === "main") {
+    channelId = "default";
+  } else if (channelType === "discord" && parts.length >= 5 && parts[3] === "channel") {
+    channelId = parts[4];
+  } else if (channelType === "slack" && parts.length >= 5 && parts[3] === "channel") {
+    channelId = parts[4];
+  } else if (channelType === "cron" && parts.length >= 4) {
+    channelId = parts[3];
+  } else if (parts.length >= 4) {
+    channelId = parts[3];
+  }
+
+  if (!channelId || channelId.length === 0) {
+    channelId = LEGACY_FALLBACK_CHANNEL_ID;
+  }
+
+  return { channelType, channelId };
+}
+
+/**
+ * A short, human-readable label for dashboards/audits. Never used for storage
+ * routing — `channelId` (the hash) owns isolation. Control characters and path
+ * separators are stripped so the label is safe to render.
+ */
+function safeDisplayLabel(sessionKey: string): string {
+  if (sessionKey.length === 0) return "(empty)";
+  let out = "";
+  for (const char of sessionKey) {
+    const code = char.codePointAt(0) ?? 0;
+    // Drop ASCII control characters (0x00-0x1F) and DEL (0x7F).
+    if (code <= 0x1f || code === 0x7f) continue;
+    if (char === "/" || char === "\\") {
+      out += "_";
+      continue;
+    }
+    out += char;
+  }
+  const trimmed = out.trim();
+  if (trimmed.length === 0) return "(empty)";
+  return trimmed.length > DISPLAY_LABEL_MAX_LENGTH ? `${trimmed.slice(0, DISPLAY_LABEL_MAX_LENGTH - 1)}…` : trimmed;
+}

package/src/session-transcript-migration.test.ts

@@ -0,0 +1,350 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { sessionStoragePaths } from "./session-identity.js";
+import { migrateSessionTranscripts, planSessionTranscriptMigration } from "./session-transcript-migration.js";
+
+async function makeMemoryDir(): Promise<string> {
+  return mkdtemp(path.join(os.tmpdir(), "remnic-sess-mig-"));
+}
+
+function entryLine(sessionKey: string, turnId: string, role: "user" | "assistant"): string {
+  return JSON.stringify({
+    sessionKey,
+    turnId,
+    role,
+    content: `content-${turnId}`,
+    timestamp: `2026-06-29T10:0${turnId}:00.000Z`,
+  });
+}
+
+async function seedMixedOtherDefault(memoryDir: string, fileName: string, lines: string[]): Promise<string> {
+  const dir = path.join(memoryDir, "transcripts", "other", "default");
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, fileName);
+  await writeFile(filePath, `${lines.join("\n")}\n`, "utf-8");
+  return filePath;
+}
+
+test("dry-run reports expected splits for mixed other/default file and changes nothing", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    const lines = [
+      entryLine("pi-geek:abc123", "1", "user"),
+      entryLine("pi-friend:def456", "2", "user"),
+      entryLine("pi-geek:abc123", "3", "assistant"),
+    ];
+    const sourcePath = await seedMixedOtherDefault(memoryDir, fileName, lines);
+
+    const plan = await planSessionTranscriptMigration({ memoryDir });
+    assert.equal(plan.dryRun, true);
+    assert.equal(plan.files.length, 1);
+    assert.equal(plan.distinctSessions, 2);
+    assert.equal(plan.movedEntries, 3);
+
+    const groupKeys = plan.files[0].groups.map((g) => g.sessionKey).sort();
+    assert.deepEqual(groupKeys, ["pi-friend:def456", "pi-geek:abc123"]);
+
+    // Nothing moved.
+    const before = await readFile(sourcePath, "utf-8");
+    assert.equal(before.split("\n").filter(Boolean).length, 3);
+    const sessionDir = path.join(memoryDir, "transcripts", "session");
+    await assert.rejects(() => readdir(sessionDir));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("apply is lossless: every entry lands in its session dir, source is emptied", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    const lines = [
+      entryLine("pi-geek:abc123", "1", "user"),
+      entryLine("pi-friend:def456", "2", "user"),
+      entryLine("pi-geek:abc123", "3", "assistant"),
+    ];
+    await seedMixedOtherDefault(memoryDir, fileName, lines);
+
+    const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(result.applied, true);
+    assert.equal(result.errors.length, 0);
+
+    const geekDir = sessionStoragePaths("pi-geek:abc123").dir;
+    const friendDir = sessionStoragePaths("pi-friend:def456").dir;
+
+    const geekContent = await readFile(path.join(memoryDir, "transcripts", geekDir, fileName), "utf-8");
+    const friendContent = await readFile(path.join(memoryDir, "transcripts", friendDir, fileName), "utf-8");
+
+    const geekLines = geekContent.split("\n").filter(Boolean);
+    const friendLines = friendContent.split("\n").filter(Boolean);
+    assert.equal(geekLines.length, 2);
+    assert.equal(friendLines.length, 1);
+
+    // Ordering preserved within a session (turn 1 before turn 3).
+    assert.ok(geekLines[0].includes('"turnId":"1"'));
+    assert.ok(geekLines[1].includes('"turnId":"3"'));
+
+    // Source other/default file removed (no entries retained).
+    await assert.rejects(() => readFile(path.join(memoryDir, "transcripts", "other", "default", fileName), "utf-8"));
+
+    // No entries lost: 3 in, 3 out.
+    assert.equal(geekLines.length + friendLines.length, 3);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("apply is idempotent: a second run finds nothing to migrate and does not duplicate", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    const lines = [entryLine("pi-geek:abc123", "1", "user"), entryLine("pi-geek:abc123", "2", "assistant")];
+    await seedMixedOtherDefault(memoryDir, fileName, lines);
+
+    const first = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(first.errors.length, 0);
+
+    const second = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(second.errors.length, 0);
+    assert.equal(second.plan.files.length, 0);
+    assert.equal(second.plan.movedEntries, 0);
+
+    const geekDir = sessionStoragePaths("pi-geek:abc123").dir;
+    const geekContent = await readFile(path.join(memoryDir, "transcripts", geekDir, fileName), "utf-8");
+    // Still exactly 2 lines — no duplication.
+    assert.equal(geekContent.split("\n").filter(Boolean).length, 2);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("unparseable and legacy-homed lines are retained in the source file", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    // One arbitrary key (movable), one malformed line (retained).
+    const lines = [entryLine("pi-geek:abc123", "1", "user"), "{not valid json"];
+    await seedMixedOtherDefault(memoryDir, fileName, lines);
+
+    const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(result.errors.length, 0);
+
+    // Source retains the malformed line (not deleted).
+    const sourceContent = await readFile(path.join(memoryDir, "transcripts", "other", "default", fileName), "utf-8");
+    assert.ok(sourceContent.includes("{not valid json"));
+
+    // The movable entry landed in its session dir.
+    const geekDir = sessionStoragePaths("pi-geek:abc123").dir;
+    const geekContent = await readFile(path.join(memoryDir, "transcripts", geekDir, fileName), "utf-8");
+    assert.equal(geekContent.split("\n").filter(Boolean).length, 1);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+async function seedLegacyParserDir(
+  memoryDir: string,
+  channelType: string,
+  channelId: string,
+  fileName: string,
+  lines: string[]
+): Promise<string> {
+  const dir = path.join(memoryDir, "transcripts", channelType, channelId);
+  await mkdir(dir, { recursive: true });
+  const filePath = path.join(dir, fileName);
+  await writeFile(filePath, `${lines.join("\n")}\n`, "utf-8");
+  return filePath;
+}
+
+test("migration scan picks up pre-existing foo:bar:baz data under old baz/default", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    // OLD build stored foo:bar:baz under baz/default (parts.length >= 3 parser).
+    const sourcePath = await seedLegacyParserDir(memoryDir, "baz", "default", fileName, [
+      entryLine("foo:bar:baz", "1", "user"),
+      entryLine("foo:bar:baz", "2", "assistant"),
+    ]);
+
+    const plan = await planSessionTranscriptMigration({ memoryDir });
+    assert.equal(plan.files.length, 1, "baz/default must be a migration candidate");
+    assert.equal(plan.distinctSessions, 1);
+    assert.equal(plan.movedEntries, 2);
+
+    const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(result.errors.length, 0);
+
+    const destDir = sessionStoragePaths("foo:bar:baz").dir;
+    const destContent = await readFile(path.join(memoryDir, "transcripts", destDir, fileName), "utf-8");
+    assert.equal(destContent.split("\n").filter(Boolean).length, 2);
+
+    // Source emptied/removed.
+    await assert.rejects(() => readFile(sourcePath, "utf-8"));
+
+    // Idempotent: a second run finds nothing.
+    const second = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(second.plan.files.length, 0);
+    assert.equal(second.plan.movedEntries, 0);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("migration leaves legitimate legacy agent:<id>:main data in place (dest === source)", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    // agent:generalist:main legitimately lives in main/default and must NOT move.
+    await seedLegacyParserDir(memoryDir, "main", "default", fileName, [
+      entryLine("agent:generalist:main", "1", "user"),
+    ]);
+
+    const plan = await planSessionTranscriptMigration({ memoryDir });
+    assert.equal(plan.files.length, 0, "legacy agent data must not be a migration source");
+    assert.equal(plan.movedEntries, 0);
+
+    const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(result.errors.length, 0);
+    const stillThere = await readFile(path.join(memoryDir, "transcripts", "main", "default", fileName), "utf-8");
+    assert.equal(stillThere.split("\n").filter(Boolean).length, 1);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("migration never treats session/<hash> dirs as sources", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    const sessionKey = "pi-geek:abc123";
+    const destDir = sessionStoragePaths(sessionKey).dir; // session/<hash>
+    const [type, id] = destDir.split("/");
+    await seedLegacyParserDir(memoryDir, type, id, fileName, [entryLine(sessionKey, "1", "user")]);
+
+    const plan = await planSessionTranscriptMigration({ memoryDir });
+    assert.equal(plan.files.length, 0, "already-homed session/<hash> must never be scanned");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("migration splits a LEGACY session/<name> dir while leaving real session/<hash> untouched", async () => {
+  // Thread 3 (codex review on PR #1504): pre-#1496 the OLD parser stored a key
+  // whose 3rd colon segment was literally `session` (e.g. foo:bar:session:baz)
+  // under transcripts/session/baz — a NON-hash id. The new layer maps that key
+  // to session/<hash>, but the migration previously BLANKET-SKIPPED everything
+  // under session/, so the legacy session/baz dir was never scanned. Only the
+  // canonical 16-hex session/<hash> dirs must be skipped.
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    const legacyKey = "foo:bar:session:baz";
+
+    // LEGACY: OLD parser homed foo:bar:session:baz under session/baz (non-hash).
+    const legacySourcePath = await seedLegacyParserDir(memoryDir, "session", "baz", fileName, [
+      entryLine(legacyKey, "1", "user"),
+      entryLine(legacyKey, "2", "assistant"),
+    ]);
+
+    // CANONICAL: a genuinely-homed session/<hash> dir for a different key.
+    const homedKey = "pi-geek:abc123";
+    const homedDir = sessionStoragePaths(homedKey).dir; // session/<16hex>
+    const [homedType, homedId] = homedDir.split("/");
+    assert.match(homedId, /^[0-9a-f]{16}$/);
+    await seedLegacyParserDir(memoryDir, homedType, homedId, fileName, [
+      entryLine(homedKey, "1", "user"),
+    ]);
+    const homedContentBefore = await readFile(path.join(memoryDir, "transcripts", homedDir, fileName), "utf-8");
+
+    // Plan: only the legacy session/baz dir is a source; session/<hash> is left.
+    const plan = await planSessionTranscriptMigration({ memoryDir });
+    assert.equal(plan.files.length, 1, "only the legacy session/<name> dir must be a source");
+    assert.equal(plan.distinctSessions, 1);
+    assert.equal(plan.movedEntries, 2);
+    assert.equal(plan.files[0].sourceRelPath, path.join("session", "baz", fileName));
+
+    const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(result.errors.length, 0);
+
+    // Legacy data re-homed to its canonical session/<hash> dir, order preserved.
+    const legacyDestDir = sessionStoragePaths(legacyKey).dir;
+    assert.notEqual(legacyDestDir, path.join("session", "baz"));
+    const legacyDestContent = await readFile(
+      path.join(memoryDir, "transcripts", legacyDestDir, fileName),
+      "utf-8",
+    );
+    const legacyDestLines = legacyDestContent.split("\n").filter(Boolean);
+    assert.equal(legacyDestLines.length, 2);
+    assert.ok(legacyDestLines[0].includes('"turnId":"1"'));
+    assert.ok(legacyDestLines[1].includes('"turnId":"2"'));
+
+    // Legacy source emptied/removed (lossless move).
+    await assert.rejects(() => readFile(legacySourcePath, "utf-8"));
+
+    // The real session/<hash> dir is byte-for-byte untouched.
+    const homedContentAfter = await readFile(path.join(memoryDir, "transcripts", homedDir, fileName), "utf-8");
+    assert.equal(homedContentAfter, homedContentBefore);
+
+    // Idempotent: a second run finds nothing and does not duplicate.
+    const second = await migrateSessionTranscripts({ memoryDir, apply: true });
+    assert.equal(second.plan.files.length, 0);
+    assert.equal(second.plan.movedEntries, 0);
+    const reread = await readFile(path.join(memoryDir, "transcripts", legacyDestDir, fileName), "utf-8");
+    assert.equal(reread.split("\n").filter(Boolean).length, 2);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("migration error detail is sanitized (no raw filesystem/stack message leak)", async () => {
+  // Thread 2 (cursor review on PR #1504): the per-file catch must route
+  // operator-facing strings (CLI output + audit manifest) through the shared
+  // displayErrorDetail() sanitizer so a raw fs path or stack detail cannot leak.
+  const memoryDir = await makeMemoryDir();
+  try {
+    const fileName = "2026-06-29.jsonl";
+    // Arbitrary key routes to transcripts/session/<hash>. Planting a FILE at
+    // transcripts/session makes the destination `mkdir` fail with ENOTDIR — a
+    // realistic write-time failure whose raw OS message embeds an absolute path.
+    await seedMixedOtherDefault(memoryDir, fileName, [entryLine("pi-geek:abc123", "1", "user")]);
+    await writeFile(path.join(memoryDir, "transcripts", "session"), "blocker", "utf-8");
+
+    const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+
+    assert.equal(result.errors.length, 1);
+    const message = result.errors[0];
+    // Sanitized: includes the relative source path + the error name/code only.
+    assert.ok(
+      message.startsWith(`Failed to migrate ${path.join("other", "default", fileName)}`),
+      `unexpected error prefix: ${message}`,
+    );
+    assert.match(message, /\(ENOTDIR\)/);
+    // Must NOT leak the raw OS message or any absolute filesystem path.
+    assert.ok(!message.includes(memoryDir), "sanitized error must not leak an absolute fs path");
+    assert.ok(
+      !/not a directory|open '|write '/i.test(message),
+      `sanitized error must not leak the raw OS message: ${message}`,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("apply writes an audit manifest", async () => {
+  const memoryDir = await makeMemoryDir();
+  try {
+    await seedMixedOtherDefault(memoryDir, "2026-06-29.jsonl", [entryLine("pi-geek:abc123", "1", "user")]);
+    const result = await migrateSessionTranscripts({ memoryDir, apply: true });
+    const manifestPath = result.manifestPath;
+    assert.ok(manifestPath);
+    const manifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+    assert.equal(manifest.applied, true);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});