chainlesschain 0.162.95 → 0.162.96

package/src/lib/cowork-template-marketplace.js

@@ -22,6 +22,7 @@ import {
   writeFileSync,
   readdirSync,
   unlinkSync,
+  renameSync,
 } from "node:fs";
 import { join } from "node:path";
 
@@ -32,10 +33,38 @@ export const _deps = {
   writeFileSync,
   readdirSync,
   unlinkSync,
+  renameSync,
   // Injected at runtime by CLI to avoid eager evomap-client load
   evomapClient: null,
 };
 
+/**
+ * Atomically write a JSON file via _deps. A user template (<id>.json) is
+ * persistent state; a crash mid-write truncates it and listUserTemplates /
+ * loadUserTemplate's JSON.parse then drops or throws on it. Temp sibling +
+ * rename (atomic within a filesystem). Graceful-degrade to a direct write when
+ * the injected fs lacks renameSync — the real fs always has it, so production
+ * is always atomic.
+ */
+function _atomicWriteJson(file, data) {
+  if (typeof _deps.renameSync !== "function") {
+    _deps.writeFileSync(file, data, "utf-8");
+    return;
+  }
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    _deps.writeFileSync(tmp, data, "utf-8");
+    _deps.renameSync(tmp, file);
+  } catch (err) {
+    try {
+      if (_deps.existsSync(tmp) && _deps.unlinkSync) _deps.unlinkSync(tmp);
+    } catch {
+      /* best-effort temp cleanup */
+    }
+    throw err;
+  }
+}
+
 const EVOMAP_CATEGORY = "cowork-template";
 
 // ─── Paths ───────────────────────────────────────────────────────────────────
@@ -48,6 +77,26 @@ function _userTemplateFile(cwd, id) {
   return join(_userTemplatesDir(cwd), `${id}.json`);
 }
 
+/**
+ * A template id is interpolated into a filesystem path (user-templates/<id>.json)
+ * and arrives from installed templates whose payload comes from an external hub /
+ * MCP download. A malicious id like "../../.ssh/authorized_keys" or
+ * "C:\\Windows\\..." would escape the user-templates dir and overwrite/delete
+ * arbitrary files. Restrict it to a single safe path segment.
+ */
+function _isSafeTemplateId(id) {
+  return (
+    typeof id === "string" &&
+    id.length > 0 &&
+    id !== "." &&
+    id !== ".." &&
+    !id.includes("/") &&
+    !id.includes("\\") &&
+    !id.includes(":") &&
+    !id.includes("\0")
+  );
+}
+
 // ─── Serialization ───────────────────────────────────────────────────────────
 
 const SHARED_FIELDS = [
@@ -148,18 +197,21 @@ export function listUserTemplates(cwd) {
 /** Save a template to the local user-templates directory. */
 export function saveUserTemplate(cwd, template) {
   if (!template?.id) throw new Error("template.id is required");
+  if (!_isSafeTemplateId(template.id)) {
+    throw new Error(`Unsafe template id (path traversal): ${template.id}`);
+  }
   const dir = _userTemplatesDir(cwd);
   _deps.mkdirSync(dir, { recursive: true });
-  _deps.writeFileSync(
+  _atomicWriteJson(
     _userTemplateFile(cwd, template.id),
     JSON.stringify(template, null, 2),
-    "utf-8",
   );
   return template;
 }
 
 /** Remove an installed user template. Returns true if removed. */
 export function removeUserTemplate(cwd, id) {
+  if (!_isSafeTemplateId(id)) return false;
   const file = _userTemplateFile(cwd, id);
   if (!_deps.existsSync(file)) return false;
   _deps.unlinkSync(file);

package/src/lib/cowork-workflow.js

@@ -29,6 +29,7 @@ import {
   readdirSync,
   unlinkSync,
   appendFileSync,
+  renameSync,
 } from "node:fs";
 import { join } from "node:path";
 import { evaluate as evalExpr, resolveReference } from "./workflow-expr.js";
@@ -47,6 +48,7 @@ export const _deps = {
   readdirSync,
   unlinkSync,
   appendFileSync,
+  renameSync,
   now: () => Date.now(),
   runTask: null, // injected by CLI
   // Timer seams (injectable for deterministic retry/timeout tests).
@@ -55,6 +57,32 @@ export const _deps = {
   clearTimeout: (t) => clearTimeout(t),
 };
 
+/**
+ * Atomically write a JSON file via _deps. A saved workflow definition is
+ * persistent user state; a crash mid-write truncates <id>.json and getWorkflow
+ * then fails to parse it. Temp sibling + rename (atomic within a filesystem).
+ * Graceful-degrade to a direct write when the injected fs lacks renameSync — the
+ * real fs always has it, so production is always atomic.
+ */
+function _atomicWriteJson(file, data) {
+  if (typeof _deps.renameSync !== "function") {
+    _deps.writeFileSync(file, data, "utf-8");
+    return;
+  }
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    _deps.writeFileSync(tmp, data, "utf-8");
+    _deps.renameSync(tmp, file);
+  } catch (err) {
+    try {
+      if (_deps.existsSync(tmp) && _deps.unlinkSync) _deps.unlinkSync(tmp);
+    } catch {
+      /* best-effort temp cleanup */
+    }
+    throw err;
+  }
+}
+
 // ─── Paths ───────────────────────────────────────────────────────────────────
 
 function workflowsDir(cwd) {
@@ -302,7 +330,10 @@ export function resolveForEachItems(forEach, resultsById) {
 export function substituteItem(template, item) {
   if (typeof template !== "string") return template;
   const repl = typeof item === "string" ? item : JSON.stringify(item);
-  return template.replace(/\$\{item\}/g, repl);
+  // Insert via a function so $-sequences in the item ($&, $`, $', $$ — common in
+  // JSON values / shell snippets) are placed literally rather than interpreted
+  // as String.replace patterns, which would corrupt the substituted value.
+  return template.replace(/\$\{item\}/g, () => repl);
 }
 
 /** Evaluate a step's `when` expression. Missing expression → always true. */
@@ -376,11 +407,7 @@ export function saveWorkflow(cwd, wf) {
   if (!valid) throw new Error(`Invalid workflow: ${errors.join("; ")}`);
   const dir = workflowsDir(cwd);
   _deps.mkdirSync(dir, { recursive: true });
-  _deps.writeFileSync(
-    workflowFile(cwd, wf.id),
-    JSON.stringify(wf, null, 2),
-    "utf-8",
-  );
+  _atomicWriteJson(workflowFile(cwd, wf.id), JSON.stringify(wf, null, 2));
   return wf;
 }
 

package/src/lib/cross-chain-mtc.js

@@ -19,6 +19,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import mtcLib from "@chainlesschain/core-mtc";
+import { withFileLock } from "./with-file-lock.js";
 
 const {
   assembleBatch,
@@ -95,6 +96,28 @@ function ensureDirs(dir) {
   }
 }
 
+/**
+ * Atomically write a UTF-8 file. The cross-chain MTC store holds config, trust
+ * anchors (federation security material), staged bridge ops, the batch-seq
+ * counter, and closed batches — a crash mid-write corrupts ledger/security
+ * state. Temp sibling + rename (atomic within a filesystem); temp names end in
+ * `.tmp` (never `.json`), so a hard-crash leftover is ignored by listStagedOps.
+ */
+function atomicWriteFileSync(filePath, data) {
+  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    fs.writeFileSync(tmp, data, "utf-8");
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      /* best-effort temp cleanup */
+    }
+    throw err;
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────
 // Namespace
 // ─────────────────────────────────────────────────────────────────────
@@ -173,7 +196,7 @@ export function saveCrossChainMtcConfig(dir, patch) {
       "config.mode must be independent, federated, or light-client",
     );
   }
-  fs.writeFileSync(configPath(dir), JSON.stringify(merged, null, 2), "utf-8");
+  atomicWriteFileSync(configPath(dir), JSON.stringify(merged, null, 2));
   return merged;
 }
 
@@ -201,11 +224,7 @@ export function loadTrustAnchors(dir) {
 }
 
 function saveTrustAnchorStore(dir, store) {
-  fs.writeFileSync(
-    trustAnchorsPath(dir),
-    JSON.stringify(store, null, 2),
-    "utf-8",
-  );
+  atomicWriteFileSync(trustAnchorsPath(dir), JSON.stringify(store, null, 2));
 }
 
 /**
@@ -456,7 +475,7 @@ export function stageBridgeOp(dir, op, opts = {}) {
   if (fs.existsSync(file)) {
     return { staged: false, path: file, reason: "ALREADY_STAGED" };
   }
-  fs.writeFileSync(file, JSON.stringify(op, null, 2), "utf-8");
+  atomicWriteFileSync(file, JSON.stringify(op, null, 2));
   return { staged: true, path: file };
 }
 
@@ -498,7 +517,7 @@ function nextBatchSeq(dir, pair) {
   }
   const next = (map[pair] || 0) + 1;
   map[pair] = next;
-  fs.writeFileSync(p, JSON.stringify(map, null, 2), "utf-8");
+  atomicWriteFileSync(p, JSON.stringify(map, null, 2));
   return next;
 }
 
@@ -514,6 +533,18 @@ function nextBatchSeq(dir, pair) {
  *             skipped: { reason: string } | null }}
  */
 export function closeBatch(dir, opts = {}) {
+  // Serialize the whole staging-scan → batch-write → staging-cleanup section
+  // across processes. Without it, two concurrent closes both read the same
+  // staged ops, allocate the same per-pair sequence (namespace collision), and
+  // batch the same ops twice before clearing staging. Best-effort lock (never
+  // hangs); generous timeout since the section includes batch assembly+signing.
+  ensureDirs(dir);
+  return withFileLock(batchesDir(dir), () => _closeBatchImpl(dir, opts), {
+    timeoutMs: 15000,
+  });
+}
+
+function _closeBatchImpl(dir, opts = {}) {
   ensureDirs(dir);
   const cfg = loadCrossChainMtcConfig(dir);
   const grouped = listStagedOps(dir);
@@ -546,16 +577,14 @@ export function closeBatch(dir, opts = {}) {
       `${pair}-${String(seq).padStart(6, "0")}`,
     );
     fs.mkdirSync(outDir, { recursive: true });
-    fs.writeFileSync(
+    atomicWriteFileSync(
       path.join(outDir, "landmark.json"),
       JSON.stringify(result.landmark, null, 2),
-      "utf-8",
     );
     result.envelopes.forEach((env, i) => {
-      fs.writeFileSync(
+      atomicWriteFileSync(
         path.join(outDir, `envelope-${String(i).padStart(4, "0")}.json`),
         JSON.stringify(env, null, 2),
-        "utf-8",
       );
     });
 

package/src/lib/crypto-manager.js

@@ -136,14 +136,24 @@ export function decryptFile(inputPath, password, outputPath) {
  * Check if a file is encrypted with our format.
  */
 export function isEncryptedFile(filePath) {
+  let fd;
   try {
-    const fd = fs.openSync(filePath, "r");
+    fd = fs.openSync(filePath, "r");
     const buf = Buffer.alloc(MAGIC_HEADER.length);
     fs.readSync(fd, buf, 0, MAGIC_HEADER.length, 0);
-    fs.closeSync(fd);
     return buf.equals(MAGIC_HEADER);
   } catch (_err) {
     return false;
+  } finally {
+    // Close in finally so a readSync throw (permission change mid-op, OS error)
+    // can't leak the descriptor — repeated failures would otherwise exhaust FDs.
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* already closed / invalid fd — nothing to release */
+      }
+    }
   }
 }
 

package/src/lib/dbevo.js

@@ -41,6 +41,17 @@ export const SUGGESTION_TYPE = Object.freeze({
 
 let _migrations = []; // registered migration definitions
 let _migrationHistory = []; // executed migration records from DB
+
+/**
+ * Compare two version strings with NUMERIC collation so "10" sorts AFTER "2".
+ * A migration framework must order numeric versions correctly; plain
+ * localeCompare()/Array.sort() is lexicographic ("10" < "2"), which would run
+ * migration v10 before v2 and corrupt the schema. Numeric collation also leaves
+ * zero-padded / date / semver-ish versions ordered as expected.
+ */
+function cmpVersion(a, b) {
+  return String(a).localeCompare(String(b), undefined, { numeric: true });
+}
 let _queryLogs = [];
 let _suggestions = new Map();
 let _slowQueryThresholdMs = 100;
@@ -147,7 +158,7 @@ export function registerMigration(
   });
 
   // Keep sorted by version
-  _migrations.sort((a, b) => a.version.localeCompare(b.version));
+  _migrations.sort((a, b) => cmpVersion(a.version, b.version));
 
   return { registered: true, version, checksum };
 }
@@ -178,13 +189,13 @@ export function getCurrentVersion(db) {
   );
 
   if (active.length === 0) return null;
-  return active.sort((a, b) => b.localeCompare(a))[0];
+  return active.sort((a, b) => cmpVersion(b, a))[0];
 }
 
 export function getPendingMigrations(db) {
   const current = getCurrentVersion(db);
   return _migrations.filter(
-    (m) => !current || m.version.localeCompare(current) > 0,
+    (m) => !current || cmpVersion(m.version, current) > 0,
   );
 }
 
@@ -193,7 +204,7 @@ export function migrateUp(db, targetVersion) {
   if (pending.length === 0) return { migrated: false, reason: "no_pending" };
 
   const toRun = targetVersion
-    ? pending.filter((m) => m.version.localeCompare(targetVersion) <= 0)
+    ? pending.filter((m) => cmpVersion(m.version, targetVersion) <= 0)
     : pending;
 
   if (toRun.length === 0) return { migrated: false, reason: "no_pending" };
@@ -248,13 +259,13 @@ export function migrateDown(db, targetVersion) {
     .filter((m) => {
       if (targetVersion) {
         return (
-          m.version.localeCompare(current) <= 0 &&
-          m.version.localeCompare(targetVersion) > 0
+          cmpVersion(m.version, current) <= 0 &&
+          cmpVersion(m.version, targetVersion) > 0
         );
       }
       return m.version === current;
     })
-    .sort((a, b) => b.version.localeCompare(a.version));
+    .sort((a, b) => cmpVersion(b.version, a.version));
 
   if (toRollBack.length === 0)
     return { rolledBack: false, reason: "nothing_to_rollback" };
@@ -331,7 +342,7 @@ export function validateMigrations() {
   if (_migrations.length === 0) return { valid: true, issues: [] };
 
   const issues = [];
-  const versions = _migrations.map((m) => m.version).sort();
+  const versions = _migrations.map((m) => m.version).sort(cmpVersion);
 
   // Check for gaps in version sequence
   for (let i = 1; i < versions.length; i++) {

package/src/lib/downloader.js

@@ -7,7 +7,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { pipeline } from "node:stream/promises";
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import ora from "ora";
 import { GITHUB_RELEASES_URL } from "../constants.js";
 import { getBinDir, ensureDir } from "./paths.js";
@@ -208,16 +208,31 @@ async function fetchRelease(url) {
   return response.json();
 }
 
-function extractZip(zipPath, destDir) {
-  const p = getPlatform();
-  if (p === "win32") {
-    // Use PowerShell on Windows
-    execSync(
-      `powershell -Command "Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force"`,
-      { stdio: "ignore" },
+export function extractZip(
+  zipPath,
+  destDir,
+  { execFileImpl = execFileSync, platform = getPlatform() } = {},
+) {
+  // Never interpolate the paths into a shell string — `zipPath`/`destDir` derive
+  // from the (remote) release asset name, so a `"`/`$()`/`'` in a path would be a
+  // command-injection vector. execFileSync runs the tool directly (no shell), and
+  // on Windows the paths go through the environment so the -Command script stays
+  // a constant the shell can't be tricked by.
+  if (platform === "win32") {
+    execFileImpl(
+      "powershell",
+      [
+        "-NoProfile",
+        "-Command",
+        "Expand-Archive -Path $env:CC_ZIP_SRC -DestinationPath $env:CC_ZIP_DEST -Force",
+      ],
+      {
+        stdio: "ignore",
+        env: { ...process.env, CC_ZIP_SRC: zipPath, CC_ZIP_DEST: destDir },
+      },
     );
   } else {
-    execSync(`unzip -o "${zipPath}" -d "${destDir}"`, { stdio: "ignore" });
+    execFileImpl("unzip", ["-o", zipPath, "-d", destDir], { stdio: "ignore" });
   }
 }
 

package/src/lib/evomap-governance.js

@@ -305,8 +305,8 @@ export function createGovernanceProposalV2(db, options = {}) {
     throw new Error(`Unknown proposal type: ${proposalType}`);
   }
 
-  const quorumValue = typeof quorum === "number" ? quorum : 3;
-  const thresholdValue = typeof threshold === "number" ? threshold : 0.5;
+  const quorumValue = Number.isFinite(quorum) ? quorum : 3;
+  const thresholdValue = Number.isFinite(threshold) ? threshold : 0.5;
   if (quorumValue < 1) throw new Error("Quorum must be >= 1");
   if (thresholdValue <= 0 || thresholdValue > 1) {
     throw new Error("Threshold must be in (0, 1]");
@@ -370,7 +370,7 @@ export function castVoteV2(db, options = {}) {
   if (!Object.values(VOTE_DIRECTION).includes(direction)) {
     throw new Error(`Unknown vote direction: ${direction}`);
   }
-  const weightValue = typeof weight === "number" ? weight : 1;
+  const weightValue = Number.isFinite(weight) ? weight : 1;
   if (weightValue <= 0) throw new Error("Vote weight must be positive");
 
   if (direction === VOTE_DIRECTION.FOR) {
@@ -456,7 +456,7 @@ export function cancelProposal(db, proposalId) {
 }
 
 export function expireProposalsV2(db, now) {
-  const cutoff = typeof now === "number" ? now : Date.now();
+  const cutoff = Number.isFinite(now) ? now : Date.now();
   const expired = [];
   for (const p of _proposals.values()) {
     if (p.status === PROPOSAL_STATUS_V2.ACTIVE) {

package/src/lib/evomap-manager.js

@@ -14,6 +14,53 @@ export const _deps = {
   path,
 };
 
+/**
+ * Atomically write a UTF-8 file via _deps.fs. A gene's gene.json / content.md
+ * are persistent store state; a crash mid-write truncates them and getGene's
+ * JSON.parse then throws. Temp sibling + rename (atomic within a filesystem).
+ * Graceful-degrade to a direct write when the injected fs has no renameSync
+ * (partial test mocks); the real fs always has it, so production is atomic.
+ */
+function _atomicWriteFile(filePath, data) {
+  const fsx = _deps.fs;
+  if (typeof fsx.renameSync !== "function") {
+    fsx.writeFileSync(filePath, data, "utf-8");
+    return;
+  }
+  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    fsx.writeFileSync(tmp, data, "utf-8");
+    fsx.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      if (fsx.existsSync(tmp) && fsx.unlinkSync) fsx.unlinkSync(tmp);
+    } catch {
+      /* best-effort temp cleanup */
+    }
+    throw err;
+  }
+}
+
+/**
+ * A gene id is interpolated into a filesystem path (genesDir/<id>/...). Gene ids
+ * arrive from downloaded/installed genes (an external hub / MCP response), so a
+ * malicious `id` like "../../.ssh/authorized_keys" or "C:\\Windows\\..." would
+ * escape genesDir and read/overwrite/delete arbitrary files. Restrict it to a
+ * single safe path segment (no separators, no traversal, no drive/NUL).
+ */
+function _isSafeGeneId(id) {
+  return (
+    typeof id === "string" &&
+    id.length > 0 &&
+    id !== "." &&
+    id !== ".." &&
+    !id.includes("/") &&
+    !id.includes("\\") &&
+    !id.includes(":") &&
+    !id.includes("\0")
+  );
+}
+
 export class EvoMapManager {
   /**
    * @param {object} options
@@ -71,6 +118,9 @@ export class EvoMapManager {
   saveGene(gene, content) {
     this.initialize();
     if (!gene || !gene.id) throw new Error("Gene ID required");
+    if (!_isSafeGeneId(gene.id)) {
+      throw new Error(`Unsafe gene id (path traversal): ${gene.id}`);
+    }
 
     const geneDir = _deps.path.join(this.genesDir, gene.id);
     if (!_deps.fs.existsSync(geneDir)) {
@@ -78,19 +128,14 @@ export class EvoMapManager {
     }
 
     // Save metadata
-    _deps.fs.writeFileSync(
+    _atomicWriteFile(
       _deps.path.join(geneDir, "gene.json"),
       JSON.stringify(gene, null, 2),
-      "utf-8",
     );
 
     // Save content
     if (content) {
-      _deps.fs.writeFileSync(
-        _deps.path.join(geneDir, "content.md"),
-        content,
-        "utf-8",
-      );
+      _atomicWriteFile(_deps.path.join(geneDir, "content.md"), content);
     }
 
     // Register in DB
@@ -170,6 +215,7 @@ export class EvoMapManager {
    */
   getGene(geneId) {
     this.initialize();
+    if (!_isSafeGeneId(geneId)) return null;
     const geneDir = _deps.path.join(this.genesDir, geneId);
 
     if (!_deps.fs.existsSync(geneDir)) return null;
@@ -192,6 +238,7 @@ export class EvoMapManager {
    */
   removeGene(geneId) {
     this.initialize();
+    if (!_isSafeGeneId(geneId)) return { removed: false };
     const geneDir = _deps.path.join(this.genesDir, geneId);
 
     if (_deps.fs.existsSync(geneDir)) {

package/src/lib/fatal-handler.js

@@ -0,0 +1,48 @@
+/**
+ * Centralized friendly-error boundary for the CLI entrypoint.
+ *
+ * An uncaught error thrown from a command action (malformed --json, a failed DB
+ * op) — or, crucially, one that escapes into an async event handler / detached
+ * task / third-party lib AFTER the top-level parse — otherwise surfaces as a raw
+ * stack trace via Node's default unhandledRejection/uncaughtException, which on
+ * modern Node terminates the process. Route all of those through one place that
+ * prints a clean `error: <message>` (full stack under --verbose or
+ * CC_DEBUG/DEBUG) and exits non-zero.
+ *
+ * Pure-ish: process bindings are injectable so this is unit-testable.
+ */
+
+export function reportFatal(
+  err,
+  {
+    stderr = process.stderr,
+    exit = process.exit,
+    argv = process.argv,
+    env = process.env,
+  } = {},
+) {
+  const verbose =
+    argv.includes("--verbose") || Boolean(env.CC_DEBUG) || Boolean(env.DEBUG);
+  if (verbose && err && err.stack) {
+    stderr.write(`${err.stack}\n`);
+  } else {
+    const msg = err && err.message ? err.message : String(err);
+    stderr.write(`error: ${msg}\n`);
+  }
+  exit(1);
+}
+
+/**
+ * Install process-level safety nets that funnel unhandled rejections and
+ * uncaught exceptions through `report`. Node terminates on these by default, so
+ * this only swaps the ugly default stack for the friendly boundary — it is not
+ * a behavior change (still exits non-zero).
+ */
+export function installGlobalErrorHandlers(proc = process, report = reportFatal) {
+  proc.on("unhandledRejection", (reason) =>
+    report(reason instanceof Error ? reason : new Error(String(reason))),
+  );
+  proc.on("uncaughtException", (err) =>
+    report(err instanceof Error ? err : new Error(String(err))),
+  );
+}

package/src/lib/file-checkpoint.js

@@ -80,6 +80,27 @@ function newId() {
   return `cp-${Date.now()}-${rand}`;
 }
 
+/**
+ * A checkpoint id is interpolated into filesystem paths (root/<id>.json and the
+ * blob dir root/<id>). The id comes from CLI args (`cc checkpoint show|delete
+ * <id>`), so an id like "../../etc/passwd" would read outside the checkpoint
+ * store, and "../../important" passed to delete would rmSync outside it. The git
+ * engine guards this via sanitizeSession(); mirror it for the copy fallback by
+ * restricting the id to a single safe path segment.
+ */
+function isSafeCheckpointId(id) {
+  return (
+    typeof id === "string" &&
+    id.length > 0 &&
+    id !== "." &&
+    id !== ".." &&
+    !id.includes("/") &&
+    !id.includes("\\") &&
+    !id.includes(":") &&
+    !id.includes("\0")
+  );
+}
+
 /**
  * Recursively collect regular files under an absolute path, honoring SKIP_DIRS
  * and a running maxFiles budget. Symlinks are not followed.
@@ -146,6 +167,9 @@ export function createCheckpoint(paths, opts = {}) {
   const uniqueAbs = [...new Set(absFiles)];
 
   const id = opts.id || newId();
+  if (!isSafeCheckpointId(id)) {
+    throw new Error(`Unsafe checkpoint id (path traversal): ${id}`);
+  }
   const blobDir = path.join(root, id);
   ensureDir(blobDir);
 
@@ -181,6 +205,7 @@ export function createCheckpoint(paths, opts = {}) {
 
 /** Load a checkpoint manifest by id, or null. */
 export function getCheckpoint(id, opts = {}) {
+  if (!isSafeCheckpointId(id)) return null;
   const root = opts.root || defaultRoot();
   const file = path.join(root, `${id}.json`);
   if (!fs.existsSync(file)) return null;
@@ -310,6 +335,7 @@ export function restoreCheckpoint(id, opts = {}) {
 
 /** Delete a checkpoint (manifest + blobs). Returns true if it existed. */
 export function deleteCheckpoint(id, opts = {}) {
+  if (!isSafeCheckpointId(id)) return false;
   const root = opts.root || defaultRoot();
   const file = path.join(root, `${id}.json`);
   const blobDir = path.join(root, id);