@remnic/core 1.1.30 → 9.3.515

package/src/secure-store/cli-handlers.ts

@@ -193,13 +193,21 @@ export function runSecureStoreLock(options: SecureStoreLockOptions): SecureStore
 
 // ─── migrate ─────────────────────────────────────────────────────────
 
-export interface SecureStoreMigrateOptions extends SecureStoreHandlerCommon {}
+export interface SecureStoreMigrateOptions extends SecureStoreHandlerCommon {
+  /**
+   * Optional passphrase reader for standalone CLI migration. A prior
+   * `secure-store unlock` command only unlocks that process-local keyring, so
+   * standalone migrate can prompt and install the key in this process instead
+   * of pretending another process still has it.
+   */
+  readPassphrase?: PassphraseReader;
+}
 
 export type SecureStoreMigrateReport =
   | ({ ok: true } & MigrateResult)
   | ({
       ok: false;
-      reason: "not-initialized" | "locked" | "file-errors";
+      reason: "not-initialized" | "locked" | "wrong-passphrase" | "file-errors";
     } & MigrateResult);
 
 export async function runSecureStoreMigrate(
@@ -218,7 +226,13 @@ export async function runSecureStoreMigrate(
   }
 
   const id = options.keyringId ?? secureStoreDir(memoryDir);
-  const key = keyring.getKey(id);
+  const key = keyring.getKey(id) ?? await unlockForThisProcess({
+    memoryDir,
+    header,
+    keyringId: id,
+    readPassphrase: options.readPassphrase,
+    now: options.now,
+  });
   if (key === null) {
     return {
       ok: false,
@@ -228,6 +242,15 @@ export async function runSecureStoreMigrate(
       errors: [],
     };
   }
+  if (key === "wrong-passphrase") {
+    return {
+      ok: false,
+      reason: "wrong-passphrase",
+      encrypted: 0,
+      skipped: 0,
+      errors: [],
+    };
+  }
 
   const result = await migrateMemoryDirToEncrypted(memoryDir, key);
   if (result.errors.length > 0) {
@@ -238,13 +261,20 @@ export async function runSecureStoreMigrate(
 
 // ─── disable/decrypt ─────────────────────────────────────────────────
 
-export interface SecureStoreDisableOptions extends SecureStoreHandlerCommon {}
+export interface SecureStoreDisableOptions extends SecureStoreHandlerCommon {
+  /**
+   * Optional passphrase reader for standalone CLI decrypt/disable. See
+   * SecureStoreMigrateOptions.readPassphrase for the process-local keyring
+   * contract.
+   */
+  readPassphrase?: PassphraseReader;
+}
 
 export type SecureStoreDisableReport =
   | ({ ok: true } & DecryptResult)
   | ({
       ok: false;
-      reason: "not-initialized" | "locked" | "file-errors";
+      reason: "not-initialized" | "locked" | "wrong-passphrase" | "file-errors";
     } & DecryptResult);
 
 export async function runSecureStoreDisable(
@@ -263,7 +293,13 @@ export async function runSecureStoreDisable(
   }
 
   const id = options.keyringId ?? secureStoreDir(memoryDir);
-  const key = keyring.getKey(id);
+  const key = keyring.getKey(id) ?? await unlockForThisProcess({
+    memoryDir,
+    header,
+    keyringId: id,
+    readPassphrase: options.readPassphrase,
+    now: options.now,
+  });
   if (key === null) {
     return {
       ok: false,
@@ -273,6 +309,15 @@ export async function runSecureStoreDisable(
       errors: [],
     };
   }
+  if (key === "wrong-passphrase") {
+    return {
+      ok: false,
+      reason: "wrong-passphrase",
+      decrypted: 0,
+      skipped: 0,
+      errors: [],
+    };
+  }
 
   const result = await decryptMemoryDirToPlaintext(memoryDir, key);
   if (result.errors.length > 0) {
@@ -353,3 +398,22 @@ function resolveParams(
   if (algorithm === "scrypt") return { ...DEFAULT_SCRYPT_PARAMS };
   return { ...DEFAULT_ARGON2ID_PARAMS };
 }
+
+async function unlockForThisProcess(options: {
+  memoryDir: string;
+  header: SecureStoreHeader;
+  keyringId: string;
+  readPassphrase?: PassphraseReader;
+  now?: () => Date;
+}): Promise<Buffer | null | "wrong-passphrase"> {
+  if (!options.readPassphrase) return null;
+  const passphrase = await options.readPassphrase("Enter passphrase: ");
+  validatePassphrase(passphrase);
+  const candidateKey = deriveKeyFromHeader(options.header, passphrase);
+  if (!verifyKey(options.header, candidateKey)) {
+    candidateKey.fill(0);
+    return "wrong-passphrase";
+  }
+  keyring.unlock(options.keyringId, candidateKey, options.now ?? (() => new Date()));
+  return candidateKey;
+}

package/src/secure-store/cli-renderer.ts

@@ -27,13 +27,13 @@ export function renderInitReport(report: SecureStoreInitReport): string {
   lines.push("");
   lines.push("Note: init does NOT auto-unlock the store. Run");
   lines.push("  remnic engram secure-store unlock");
-  lines.push("to register the master key with the running daemon.");
+  lines.push("to register the master key in the current Remnic process.");
   return lines.join("\n");
 }
 
 export function renderUnlockReport(report: SecureStoreUnlockReport): string {
   if (report.ok) {
-    return `OK — secure-store unlocked at ${report.unlockedAt} (algorithm=${report.algorithm}).`;
+    return `OK — secure-store unlocked in this process at ${report.unlockedAt} (algorithm=${report.algorithm}).`;
   }
   if (report.reason === "not-initialized") {
     return "ERR — secure-store is not initialized. Run 'remnic engram secure-store init' first.";
@@ -43,9 +43,9 @@ export function renderUnlockReport(report: SecureStoreUnlockReport): string {
 
 export function renderLockReport(report: SecureStoreLockReport): string {
   if (report.cleared) {
-    return "OK — secure-store key cleared from in-memory keyring.";
+    return "OK — secure-store key cleared from this process's in-memory keyring.";
   }
-  return "OK — secure-store was already locked (no in-memory key to clear).";
+  return "OK — secure-store was already locked in this process (no in-memory key to clear).";
 }
 
 export function renderMigrateReport(report: SecureStoreMigrateReport): string {
@@ -53,7 +53,10 @@ export function renderMigrateReport(report: SecureStoreMigrateReport): string {
     return "ERR — secure-store is not initialized. Run 'remnic engram secure-store init' first.";
   }
   if (!report.ok && report.reason === "locked") {
-    return "ERR — secure-store is locked. Run 'remnic engram secure-store unlock' before migrate.";
+    return "ERR — secure-store is locked in this process. Run migrate from an interactive CLI so it can prompt for the passphrase, or unlock inside the daemon process that will perform the migration.";
+  }
+  if (!report.ok && report.reason === "wrong-passphrase") {
+    return "ERR — wrong passphrase.";
   }
 
   const lines: string[] = [];
@@ -75,7 +78,10 @@ export function renderDisableReport(report: SecureStoreDisableReport): string {
     return "ERR — secure-store is not initialized. Run 'remnic engram secure-store init' first.";
   }
   if (!report.ok && report.reason === "locked") {
-    return "ERR — secure-store is locked. Run 'remnic engram secure-store unlock' before disable.";
+    return "ERR — secure-store is locked in this process. Run disable from an interactive CLI so it can prompt for the passphrase, or unlock inside the daemon process that will decrypt files.";
+  }
+  if (!report.ok && report.reason === "wrong-passphrase") {
+    return "ERR — wrong passphrase.";
   }
 
   const lines: string[] = [];
@@ -105,7 +111,7 @@ export function renderStatusReport(report: SecureStoreStatusReport): string {
     return lines.join("\n");
   }
   lines.push(`createdAt: ${report.createdAt ?? "n/a"}`);
-  lines.push(`locked: ${report.locked ? "yes" : "no"}`);
+  lines.push(`lockedInThisProcess: ${report.locked ? "yes" : "no"}`);
   if (!report.locked) {
     lines.push(`lastUnlockAt: ${report.unlockedAt ?? "n/a"}`);
   }

package/src/secure-store/secure-fs.ts

@@ -43,7 +43,7 @@
  * Naming: `secure-fs.ts` (not `vault-fs.ts`) — see `kdf.ts` naming note.
  */
 
-import { createCipheriv, randomBytes } from "node:crypto";
+import { createCipheriv, randomBytes, randomUUID } from "node:crypto";
 import { lstat, mkdir, open as openFile, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 
@@ -56,6 +56,7 @@ import {
   IV_LENGTH,
   generateSalt,
   open as openEnvelope,
+  parseEnvelope,
   seal,
 } from "./cipher.js";
 
@@ -167,6 +168,7 @@ export function decryptFileBody(buf: Buffer, key: Buffer, aad?: Buffer): Buffer
     throw new Error(`decryptFileBody: unknown flags byte 0x${flags.toString(16).padStart(2, "0")}`);
   }
   const envelope = buf.subarray(MAGIC_HEADER_SIZE);
+  parseEnvelope(envelope);
   try {
     return openEnvelope(key, envelope, aad ? { aad } : {});
   } catch (err) {
@@ -270,7 +272,7 @@ export interface WriteMaybeEncryptedFileOptions {
  * - If `key` is provided and non-null, encrypt the content first.
  * - If `key` is null, write the content as plain UTF-8 (unencrypted store).
  *
- * Writes atomically: content is written to a `.tmp-<pid>-<ts>` file
+ * Writes atomically: content is written to a unique temp file
  * first, then renamed into place (CLAUDE.md gotcha #54 — never delete
  * before write).
  */
@@ -293,7 +295,7 @@ export async function writeMaybeEncryptedFile(
   }
 
   if (atomic) {
-    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    const tempPath = uniqueAtomicTempPath(filePath, "tmp");
     try {
       await writeFile(tempPath, data, { mode });
       await rename(tempPath, filePath);
@@ -445,7 +447,7 @@ export async function migrateMemoryDirToEncrypted(
       const encrypted = encryptFileBody(content, key, aad);
 
       // Atomic write: temp → rename (gotcha #54).
-      const tempPath = `${filePath}.enc-tmp-${process.pid}-${Date.now()}`;
+      const tempPath = uniqueAtomicTempPath(filePath, "enc-tmp");
       try {
         await writeFile(tempPath, encrypted, { mode: 0o600 });
         await rename(tempPath, filePath);
@@ -498,7 +500,7 @@ export async function decryptMemoryDirToPlaintext(
 
       const aad = filePathAad(filePath, storageAadRootForFile(filePath, dir));
       const plaintext = decryptFileBody(buf, key, aad);
-      const tempPath = `${filePath}.dec-tmp-${process.pid}-${Date.now()}`;
+      const tempPath = uniqueAtomicTempPath(filePath, "dec-tmp");
       try {
         await writeFile(tempPath, plaintext, { mode: 0o600 });
         await rename(tempPath, filePath);
@@ -526,6 +528,10 @@ export async function decryptMemoryDirToPlaintext(
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+function uniqueAtomicTempPath(filePath: string, label: string): string {
+  return `${filePath}.${label}-${process.pid}-${Date.now()}-${randomUUID()}`;
+}
+
 /**
  * Recursively collect files under `dir` that are read through the
  * storage-layer secure-store helpers, excluding symlinked entries and

package/src/secure-store/secure-store.test.ts

@@ -36,6 +36,13 @@ import {
   parseHeader,
   validateHeader,
 } from "./header.js";
+import {
+  FILE_FORMAT_FLAGS,
+  FILE_FORMAT_VERSION,
+  MAGIC_BYTES,
+  SecureStoreDecryptError,
+  decryptFileBody,
+} from "./secure-fs.js";
 import {
   DEFAULT_ARGON2ID_PARAMS,
   DEFAULT_SCRYPT_PARAMS,
@@ -60,6 +67,12 @@ import {
   validateMetadata,
 } from "./metadata.js";
 import { createPassphraseReader } from "./passphrase-reader.js";
+import {
+  renderInitReport,
+  renderLockReport,
+  renderStatusReport,
+  renderUnlockReport,
+} from "./cli-renderer.js";
 
 /** Cheap scrypt params for tests — still hex-correct but ~milliseconds. */
 const FAST_SCRYPT: ScryptParams = {
@@ -112,6 +125,46 @@ test("deriveKeyScrypt with default OWASP-acceptable params produces a 32-byte ke
   assert.equal(DEFAULT_SCRYPT_PARAMS.N, 1 << 17);
 });
 
+test("secure-store CLI renderers describe process-local unlock scope, not daemon state", () => {
+  const init = renderInitReport({
+    ok: true,
+    headerPath: "/tmp/memory/.secure-store/header.json",
+    createdAt: "2026-05-21T00:00:00.000Z",
+    kdf: {
+      algorithm: "scrypt",
+      params: FAST_SCRYPT,
+      salt: Buffer.alloc(KDF_SALT_LENGTH, 0x11).toString("hex"),
+    },
+  });
+  assert.match(init, /current Remnic process/);
+  assert.doesNotMatch(init, /running daemon/);
+
+  assert.match(
+    renderUnlockReport({
+      ok: true,
+      unlockedAt: "2026-05-21T00:00:01.000Z",
+      algorithm: "scrypt",
+    }),
+    /unlocked in this process/,
+  );
+  assert.match(renderLockReport({ ok: true, cleared: true }), /this process's in-memory keyring/);
+  assert.match(
+    renderStatusReport({
+      initialized: true,
+      headerPath: "/tmp/memory/.secure-store/header.json",
+      locked: false,
+      unlockedAt: "2026-05-21T00:00:01.000Z",
+      createdAt: "2026-05-21T00:00:00.000Z",
+      kdf: {
+        algorithm: "scrypt",
+        params: FAST_SCRYPT,
+        salt: Buffer.alloc(KDF_SALT_LENGTH, 0x22).toString("hex"),
+      },
+    }),
+    /lockedInThisProcess: no/,
+  );
+});
+
 test("deriveKeyScrypt rejects empty passphrase", () => {
   const salt = Buffer.alloc(KDF_SALT_LENGTH, 0);
   assert.throws(() => deriveKeyScrypt("", salt, FAST_SCRYPT), /passphrase/);
@@ -238,6 +291,23 @@ test("seal/open round-trip on an empty payload", () => {
   assert.equal(opened.length, 0);
 });
 
+test("decryptFileBody reports truncated envelopes as structural errors", () => {
+  const truncated = Buffer.concat([
+    MAGIC_BYTES,
+    Buffer.from([FILE_FORMAT_VERSION, FILE_FORMAT_FLAGS]),
+    Buffer.alloc(ENVELOPE_HEADER_SIZE - 1),
+  ]);
+  assert.throws(
+    () => decryptFileBody(truncated, Buffer.alloc(KDF_KEY_LENGTH, 0x11)),
+    (error) => {
+      assert.ok(error instanceof Error);
+      assert.equal(error instanceof SecureStoreDecryptError, false);
+      assert.match(error.message, /envelope too short/);
+      return true;
+    },
+  );
+});
+
 test("seal produces a different ciphertext for the same plaintext (random IV)", () => {
   const salt = generateSalt();
   const key = deriveKeyScrypt("pw", salt, FAST_SCRYPT);

package/src/semantic-consolidation.test.ts

@@ -8,12 +8,14 @@ import assert from "node:assert/strict";
 
 import {
   CONSOLIDATION_OPERATORS,
+  findSimilarClusters,
   isConsolidationOperator,
   isSemanticConsolidationLlmOperator,
   isValidDerivedFromEntry,
   type ConsolidationOperator,
   type SemanticConsolidationLlmOperator,
 } from "./semantic-consolidation.js";
+import type { MemoryCategory, MemoryFile } from "./types.js";
 // The standalone module is the source of truth; semantic-consolidation.ts
 // re-exports it.  This test import proves both surfaces work.
 import {
@@ -180,3 +182,46 @@ test("SemanticConsolidationLlmOperator type literally excludes pattern-reinforce
   const update: SemanticConsolidationLlmOperator = "update";
   assert.equal([split, merge, update].length, 3);
 });
+
+test("findSimilarClusters never exceeds maxPerRun after prior clusters consume budget", () => {
+  const memories = [
+    consolidationMemory("a-1", "fact", "atlas cache latency shared alpha"),
+    consolidationMemory("a-2", "fact", "atlas cache latency shared beta"),
+    consolidationMemory("a-3", "fact", "atlas cache latency shared gamma"),
+    consolidationMemory("a-4", "fact", "atlas cache latency shared delta"),
+    consolidationMemory("b-1", "preference", "aurora rollout dependency shared alpha"),
+    consolidationMemory("b-2", "preference", "aurora rollout dependency shared beta"),
+  ];
+
+  const clusters = findSimilarClusters(memories, {
+    threshold: 0.1,
+    minClusterSize: 2,
+    excludeCategories: [],
+    maxPerRun: 5,
+  });
+
+  const totalMemories = clusters.reduce((sum, cluster) => sum + cluster.memories.length, 0);
+  assert.equal(totalMemories, 4);
+  assert.deepEqual(
+    clusters.map((cluster) => cluster.memories.map((memory) => memory.frontmatter.id)),
+    [["a-1", "a-2", "a-3", "a-4"]],
+  );
+});
+
+function consolidationMemory(id: string, category: MemoryCategory, content: string): MemoryFile {
+  return {
+    path: `${category}/${id}.md`,
+    content,
+    frontmatter: {
+      id,
+      category,
+      created: "2026-05-21T00:00:00.000Z",
+      updated: "2026-05-21T00:00:00.000Z",
+      source: "test",
+      confidence: 1,
+      confidenceTier: "explicit",
+      tags: [],
+      status: "active",
+    },
+  };
+}

package/src/semantic-consolidation.ts

@@ -95,13 +95,15 @@ export function findSimilarClusters(
     const clustered = new Set<string>();
 
     for (let i = 0; i < tokenized.length && totalCandidates < config.maxPerRun; i++) {
+      const remainingBudget = config.maxPerRun - totalCandidates;
+      if (remainingBudget < config.minClusterSize) break;
       if (clustered.has(tokenized[i].memory.frontmatter.id)) continue;
 
       const cluster: MemoryFile[] = [tokenized[i].memory];
       let totalOverlap = 0;
       let comparisons = 0;
 
-      for (let j = i + 1; j < tokenized.length; j++) {
+      for (let j = i + 1; j < tokenized.length && cluster.length < remainingBudget; j++) {
         if (clustered.has(tokenized[j].memory.frontmatter.id)) continue;
 
         const aTokens = tokenized[i].tokens;
@@ -117,8 +119,6 @@ export function findSimilarClusters(
           cluster.push(tokenized[j].memory);
           totalOverlap += score;
           comparisons++;
-          // Enforce maxPerRun within a single cluster
-          if (totalCandidates + cluster.length >= config.maxPerRun) break;
         }
       }
 

package/src/session-integrity.test.ts

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { applySessionRepair, planSessionRepair } from "./session-integrity.js";
+import type { SessionIntegrityReport, SessionRepairPlan } from "./session-integrity.js";
+
+test("session repair rejects forged transcript paths outside memoryDir", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-session-repair-"));
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-session-outside-"));
+  try {
+    await mkdir(path.join(memoryDir, "transcripts"), { recursive: true });
+    const outsideFile = path.join(outside, "forged.jsonl");
+    await writeFile(outsideFile, "not json\n", "utf8");
+    const plan: SessionRepairPlan = {
+      generatedAt: new Date().toISOString(),
+      dryRun: false,
+      memoryDir,
+      allowSessionFileRepair: false,
+      actions: [
+        {
+          kind: "rewrite_transcript",
+          description: "forged",
+          targetPath: outsideFile,
+        },
+      ],
+    };
+
+    const result = await applySessionRepair({ plan });
+    assert.equal(result.actionsApplied, 0);
+    assert.match(result.errors.join("\n"), /escapes configured memoryDir/);
+    assert.equal(await readFile(outsideFile, "utf8"), "not json\n");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("session repair rejects symlinked transcript targets", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-session-repair-"));
+  const outside = await mkdtemp(path.join(os.tmpdir(), "remnic-session-outside-"));
+  try {
+    const transcripts = path.join(memoryDir, "transcripts");
+    await mkdir(transcripts, { recursive: true });
+    const outsideFile = path.join(outside, "real.jsonl");
+    const linkFile = path.join(transcripts, "link.jsonl");
+    await writeFile(outsideFile, "not json\n", "utf8");
+    await symlink(outsideFile, linkFile);
+    const plan: SessionRepairPlan = {
+      generatedAt: new Date().toISOString(),
+      dryRun: false,
+      memoryDir,
+      allowSessionFileRepair: false,
+      actions: [
+        {
+          kind: "rewrite_transcript",
+          description: "symlink",
+          targetPath: linkFile,
+        },
+      ],
+    };
+
+    const result = await applySessionRepair({ plan });
+    assert.equal(result.actionsApplied, 0);
+    assert.match(result.errors.join("\n"), /repair target crosses symlink/);
+    assert.equal(await readFile(outsideFile, "utf8"), "not json\n");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+    await rm(outside, { recursive: true, force: true });
+  }
+});
+
+test("planned session repair carries the report memoryDir into apply-time validation", () => {
+  const report: SessionIntegrityReport = {
+    generatedAt: "2026-05-22T00:00:00.000Z",
+    memoryDir: "/tmp/remnic-memory",
+    healthy: false,
+    sessions: [],
+    checkpoint: {
+      present: true,
+      healthy: false,
+      path: "/tmp/remnic-memory/state/checkpoint.json",
+    },
+    issues: [
+      {
+        code: "checkpoint_invalid_json",
+        severity: "error",
+        message: "bad checkpoint",
+        filePath: "/tmp/remnic-memory/state/checkpoint.json",
+      },
+    ],
+  };
+
+  const plan = planSessionRepair({ report, dryRun: false });
+  assert.equal(plan.memoryDir, "/tmp/remnic-memory");
+});

package/src/session-integrity.ts

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import { lstat, readFile, readdir, realpath, unlink, writeFile } from "node:fs/promises";
 import type { Checkpoint, TranscriptEntry } from "./types.js";
 
 export type SessionIntegrityIssueCode =
@@ -70,6 +70,7 @@ export interface SessionRepairAction {
 export interface SessionRepairPlan {
   generatedAt: string;
   dryRun: boolean;
+  memoryDir: string;
   allowSessionFileRepair: boolean;
   actions: SessionRepairAction[];
 }
@@ -487,6 +488,7 @@ export function planSessionRepair(options: PlanSessionRepairOptions): SessionRep
   return {
     generatedAt: new Date().toISOString(),
     dryRun: options.dryRun,
+    memoryDir: options.report.memoryDir,
     allowSessionFileRepair: options.allowSessionFileRepair === true,
     actions,
   };
@@ -535,11 +537,13 @@ export async function applySessionRepair(
   for (const action of plan.actions) {
     try {
       if (action.kind === "rewrite_transcript") {
+        await assertRepairTargetAllowed(plan.memoryDir, action);
         await rewriteTranscriptFile(action.targetPath);
         actionsApplied += 1;
         continue;
       }
       if (action.kind === "remove_checkpoint") {
+        await assertRepairTargetAllowed(plan.memoryDir, action);
         try {
           await unlink(action.targetPath);
         } catch (err) {
@@ -567,3 +571,49 @@ export async function applySessionRepair(
     errors,
   };
 }
+
+async function assertRepairTargetAllowed(memoryDir: string, action: SessionRepairAction): Promise<void> {
+  const root = path.resolve(memoryDir);
+  const target = path.resolve(action.targetPath);
+  if (action.kind === "rewrite_transcript") {
+    const transcriptsRoot = path.join(root, "transcripts");
+    if (!target.endsWith(".jsonl")) {
+      throw new Error("transcript repair target must end in .jsonl");
+    }
+    await assertNoSymlinkPath(transcriptsRoot, target);
+    return;
+  }
+  if (action.kind === "remove_checkpoint") {
+    const checkpointPath = path.join(root, "state", "checkpoint.json");
+    if (target !== checkpointPath) {
+      throw new Error("checkpoint repair target must be the configured checkpoint.json");
+    }
+    await assertNoSymlinkPath(root, target);
+  }
+}
+
+async function assertNoSymlinkPath(root: string, target: string): Promise<void> {
+  const rootReal = await realpath(root);
+  const targetDir = path.dirname(target);
+  const targetDirReal = await realpath(targetDir);
+  const relative = path.relative(rootReal, targetDirReal);
+  if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+    const normalizedTarget = path.join(targetDirReal, path.basename(target));
+    let current = rootReal;
+    for (const segment of path.relative(rootReal, normalizedTarget).split(path.sep)) {
+      if (!segment) continue;
+      current = path.join(current, segment);
+      try {
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink()) {
+          throw new Error(`repair target crosses symlink: ${current}`);
+        }
+      } catch (err) {
+        const code = typeof err === "object" && err && "code" in err ? String((err as { code?: unknown }).code ?? "") : "";
+        if (code !== "ENOENT") throw err;
+      }
+    }
+    return;
+  }
+  throw new Error("repair target escapes configured memoryDir");
+}