@xaccefy/pi-casefile 0.8.3 → 0.9.1

package/src/poc-runner.ts

@@ -1,7 +1,10 @@
 import { spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
 import {
   copyFileSync,
   existsSync,
+  lstatSync,
+  mkdirSync,
   mkdtempSync,
   readFileSync,
   realpathSync,
@@ -11,6 +14,8 @@ import {
 import { tmpdir } from "node:os";
 import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
 
+import { evidenceNonceMatches, type PoCEvidence, parsePoCEvidence } from "./evidence.ts";
+import { ensureSafeStateDirectory, writeSafeFileExclusive } from "./safe-state.ts";
 import { findWorkspaceRoot } from "./scratchpad.ts";
 
 export type PocRun = {
@@ -40,12 +45,22 @@ export type PocRun = {
   mode?: string;
   /** Harness target used for this run. */
   target?: string;
-  /**
-   * True when the run never started because of harness infrastructure
+  /** True when the run never started because of harness infrastructure
    * failure (e.g. sandbox image pull failed) — set only by the runner,
-   * never derived from PoC-controlled output text.
-   */
+   * never derived from PoC-controlled output text. */
   infraError?: boolean;
+  /** Validated evidence.json written by the PoC to $PI_POC_EVIDENCE_DIR. */
+  evidence?: PoCEvidence;
+  /** SHA-256 of the evidence.json file (reproduction artifact). */
+  evidenceSha256?: string;
+  /** Absolute path of the PRESERVED copy of evidence.json (moved into the
+   * durable .pi/poc-evidence/ dir before the temp workspace is cleaned up) —
+   * lets the ledger's reproduction item stay artifact-backed and re-verifiable. */
+  evidencePath?: string;
+  /** Evidence contract failure (missing/invalid/nonce mismatch) — blocks the gate. */
+  evidenceError?: string;
+  /** The per-run nonce the evidence must be bound to (harness-generated). */
+  nonce?: string;
 };
 
 /**
@@ -71,6 +86,7 @@ export type PocRunOptions = {
 
 /** Operator-only opt-in for host execution (never agent-supplied). */
 const LOCAL_EXEC_ENV = "PI_POC_ALLOW_LOCAL";
+const EVIDENCE_MAX_BYTES = 256 * 1024;
 
 export type PocLanguage = {
   /** Docker image used when running inside the sandbox. */
@@ -115,7 +131,11 @@ const OUTPUT_MAX_CHARS = 4000;
 const TIMEOUT_MS = 30_000;
 /** Completion sentinel echoed after the PoC command inside the sandbox shell. */
 function makeSentinel(): string {
-  return `__PI_POC_DONE_${Math.random().toString(36).slice(2, 12)}__`;
+  return `__PI_POC_DONE_${randomBytes(16).toString("hex")}__`;
+}
+/** Per-run random nonce the PoC must echo in evidence.json (binds evidence to its run). */
+function makeNonce(): string {
+  return `poc_${randomBytes(24).toString("hex")}`;
 }
 /** First-use image downloads are slow — pull outside the run timeout. */
 const PULL_TIMEOUT_MS = 300_000;
@@ -286,10 +306,115 @@ function splitOutput(raw: string): { rawOutput: string; output: string; truncate
   return { rawOutput: raw, output: raw.slice(0, OUTPUT_MAX_CHARS), truncated };
 }
 
+/**
+ * Read + validate the PoC's evidence.json from the harness-owned evidence
+ * dir. Missing, malformed, or nonce-mismatched evidence is a contract
+ * failure, not a verdict — surfaced as evidenceError on the run.
+ */
+function readEvidence(
+  evidenceDir: string,
+  nonce: string,
+): {
+  evidence?: PoCEvidence;
+  evidenceSha256?: string;
+  evidenceBytes?: Buffer;
+  evidenceError?: string;
+} {
+  const p = join(evidenceDir, "evidence.json");
+  if (!existsSync(p)) {
+    return {
+      evidenceError: `evidence.json missing in ${evidenceDir} — the PoC must write it to $PI_POC_EVIDENCE_DIR ({"nonce", "claim", "verify", "observations"})`,
+    };
+  }
+  const file = lstatSync(p);
+  if (file.isSymbolicLink() || !file.isFile()) {
+    return { evidenceError: "evidence.json must be a regular, non-symlink file" };
+  }
+  if (file.size > EVIDENCE_MAX_BYTES) {
+    return {
+      evidenceError: `evidence.json too large (${file.size} bytes; max ${EVIDENCE_MAX_BYTES})`,
+    };
+  }
+  let bytes: Buffer;
+  let raw: unknown;
+  try {
+    bytes = readFileSync(p);
+    if (bytes.byteLength > EVIDENCE_MAX_BYTES) {
+      return {
+        evidenceError: `evidence.json too large (${bytes.byteLength} bytes; max ${EVIDENCE_MAX_BYTES})`,
+      };
+    }
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch (e) {
+    return { evidenceError: `evidence.json unparseable: ${(e as Error).message}` };
+  }
+  const parsed = parsePoCEvidence(raw);
+  if (!parsed.ok) return { evidenceError: parsed.error };
+  if (!evidenceNonceMatches(parsed.evidence, nonce)) {
+    return {
+      evidenceError:
+        "evidence.json nonce mismatch — the file was not written by this run (copy-pasted evidence fails here)",
+    };
+  }
+  return {
+    evidence: parsed.evidence,
+    evidenceSha256: createHash("sha256").update(bytes).digest("hex"),
+    evidenceBytes: bytes,
+  };
+}
+
 function runProvenance(env?: Record<string, string>): Pick<PocRun, "mode" | "target"> {
   return { mode: env?.PI_POC_MODE, target: env?.PI_POC_TARGET };
 }
 
+/**
+ * Copy the run's evidence.json into a durable harness-owned dir BEFORE the
+ * temp workspace is deleted. The ledger's reproduction item stores the SHA-256
+ * of this exact file, so the file must survive the run — otherwise the
+ * "artifact-backed" evidence item hashes a file that no longer exists.
+ * Returns the preserved path, or undefined when the file is missing.
+ */
+function preserveEvidence(bytes: Buffer, nonce: string): string | undefined {
+  try {
+    const projectRoot = getProjectRoot();
+    const durableDir = ensureSafeStateDirectory(projectRoot, [".pi", "poc-evidence"]);
+    const dest = join(durableDir, `${nonce}.evidence.json`);
+    writeSafeFileExclusive(dest, bytes);
+    return dest;
+  } catch {
+    // Preservation is part of the gate: readAndPreserveEvidence surfaces this
+    // as evidenceError, so confirmation cannot depend on an ephemeral file.
+    return undefined;
+  }
+}
+
+function readAndPreserveEvidence(
+  evidenceDir: string,
+  nonce: string,
+): {
+  evidence?: PoCEvidence;
+  evidenceSha256?: string;
+  evidencePath?: string;
+  evidenceError?: string;
+} {
+  const read = readEvidence(evidenceDir, nonce);
+  if (!read.evidence || !read.evidenceSha256 || !read.evidenceBytes) {
+    return { evidenceError: read.evidenceError ?? "evidence.json validation failed" };
+  }
+  const evidencePath = preserveEvidence(read.evidenceBytes, nonce);
+  if (!evidencePath) {
+    return {
+      evidenceError:
+        "evidence.json was valid but could not be preserved in the durable evidence store",
+    };
+  }
+  return {
+    evidence: read.evidence,
+    evidenceSha256: read.evidenceSha256,
+    evidencePath,
+  };
+}
+
 function outputWasComplete(result: { error?: Error; signal: string | null }): boolean {
   return !result.error && result.signal === null;
 }
@@ -422,7 +547,18 @@ function runSandboxed(
   const workspaceDir = mkdtempSync(resolve(tmpdir(), "poc-runner-"));
   // Named container so a timed-out / killed client can still be cleaned up —
   // `--rm` alone leaks the container when the CLI dies before the child exits.
-  const containerName = `poc-runner-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  const containerName = `poc-runner-${process.pid}-${randomBytes(8).toString("hex")}`;
+  // Evidence contract: harness-owned dir + per-run nonce. The PoC writes
+  // evidence.json into $PI_POC_EVIDENCE_DIR (/workspace/evidence inside the
+  // container); the nonce binds the file to this run.
+  const nonce = makeNonce();
+  const evidenceDir = join(workspaceDir, "evidence");
+  mkdirSync(evidenceDir, { recursive: true });
+  const runEnv = {
+    ...env,
+    PI_POC_EVIDENCE_DIR: "/workspace/evidence",
+    PI_POC_NONCE: nonce,
+  };
 
   try {
     // Fail closed as a non-zero run (not a throw) when docker/images are
@@ -447,15 +583,17 @@ function runSandboxed(
     const command = renderCommand(language.run, pocPath, true);
 
     // Completion sentinel: wrap the command so the shell echoes a unique token
-    // AFTER the PoC exits, preserving its exit code. If the container is
-    // killed, times out, or the run never starts, the sentinel is absent —
-    // callers can then tell "script ran and failed" from "script crashed".
+    // ONLY when the PoC exited normally (rc < 128). A child killed by a signal
+    // (segfault, OOM under the sandbox limits) yields rc = 128+N — the sentinel
+    // is suppressed, so `completed` means "the script actually ran to
+    // completion", not merely "the container exited". Callers treat a missing
+    // sentinel as "not a verdict".
     const sentinel = makeSentinel();
-    const wrapped = `${command}; rc=$?; echo '${sentinel}'; exit $rc`;
+    const wrapped = `${command}; rc=$?; if [ "$rc" -lt 128 ]; then echo '${sentinel}'; fi; exit $rc`;
 
     const result = spawnSync(
       "docker",
-      buildDockerArgs(language.image, wrapped, workspaceDir, containerName, network, env),
+      buildDockerArgs(language.image, wrapped, workspaceDir, containerName, network, runEnv),
       {
         encoding: "utf8",
         timeout: TIMEOUT_MS,
@@ -467,6 +605,7 @@ function runSandboxed(
     const raw = (result.stdout ?? "") + (result.stderr ?? "") + spawnErr;
     const completed = raw.includes(sentinel);
     const { rawOutput, output, truncated } = splitOutput(sanitizeOutput(raw.replace(sentinel, "")));
+    const evidence = readAndPreserveEvidence(evidenceDir, nonce);
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
@@ -477,6 +616,8 @@ function runSandboxed(
       sandbox: true,
       completed,
       outputComplete: outputWasComplete(result),
+      nonce,
+      ...evidence,
       ...runProvenance(env),
     };
   } finally {
@@ -496,49 +637,68 @@ function runSandboxed(
 
 function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, string>): PocRun {
   const ranAt = new Date().toISOString();
-
-  // The run template is `<interpreter> [flags...] {{file}}`. Split the static
-  // template on whitespace FIRST (builtins only, not user input), then render
-  // placeholders within each token. Passing the tokens to spawnSync with NO
-  // shell keeps a space-containing PoC path as one arg and keeps extra flags
-  // (e.g. `node --experimental-vm-modules {{file}}`) as separate args.
-  // Splitting after rendering would re-split a space-containing path.
-  const tokens = language.run.trim().split(/\s+/).filter(Boolean);
-  const interpreter = tokens.shift() ?? language.run.trim();
-  const args = tokens.map((tok) => renderCommand(tok, pocPath, false));
-
-  const result = spawnSync(interpreter, args, {
-    encoding: "utf8",
-    timeout: TIMEOUT_MS,
-    maxBuffer: MAX_BUFFER,
-    // Host runs get the harness env contract merged over the operator env;
-    // the spawn env is explicitly provided so PI_POC_MODE / PI_POC_TARGET
-    // reach the script without leaking through a shell. Same control-char
-    // rejection as the sandboxed path.
-    env: env ? { ...process.env, ...sanitizePocEnv(env) } : undefined,
-  });
-
-  // Local runs stay shell-free (space-containing paths stay single args), so
-  // there is no sentinel echo: "completed" is derived from the spawn result.
-  // A spawn error (interpreter missing) or a signal kill (timeout, SIGKILL)
-  // means the script never ran to completion — fail closed on those.
-  const spawnErr = result.error ? `\n[spawn error] ${result.error.message}` : "";
-  const completed = !result.error && result.signal === null;
-  const { rawOutput, output, truncated } = splitOutput(
-    sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr),
-  );
-  return {
-    path: pocPath,
-    exitCode: spawnExitCode(result),
-    output,
-    rawOutput,
-    truncated,
-    ranAt,
-    sandbox: false,
-    completed,
-    outputComplete: outputWasComplete(result),
-    ...runProvenance(env),
+  // Evidence contract: harness-owned temp dir + per-run nonce, same as sandboxed.
+  const nonce = makeNonce();
+  const evidenceDir = mkdtempSync(join(tmpdir(), "poc-evidence-"));
+  const runEnv = {
+    ...env,
+    PI_POC_EVIDENCE_DIR: evidenceDir,
+    PI_POC_NONCE: nonce,
   };
+
+  try {
+    // The run template is `<interpreter> [flags...] {{file}}`. Split the static
+    // template on whitespace FIRST (builtins only, not user input), then render
+    // placeholders within each token. Passing the tokens to spawnSync with NO
+    // shell keeps a space-containing PoC path as one arg and keeps extra flags
+    // (e.g. `node --experimental-vm-modules {{file}}`) as separate args.
+    // Splitting after rendering would re-split a space-containing path.
+    const tokens = language.run.trim().split(/\s+/).filter(Boolean);
+    const interpreter = tokens.shift() ?? language.run.trim();
+    const args = tokens.map((tok) => renderCommand(tok, pocPath, false));
+
+    const result = spawnSync(interpreter, args, {
+      encoding: "utf8",
+      timeout: TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER,
+      // Host runs get the harness env contract merged over the operator env;
+      // the spawn env is explicitly provided so PI_POC_MODE / PI_POC_TARGET
+      // reach the script without leaking through a shell. Same control-char
+      // rejection as the sandboxed path.
+      env: { ...process.env, ...sanitizePocEnv(runEnv) },
+    });
+
+    // Local runs stay shell-free (space-containing paths stay single args), so
+    // there is no sentinel echo: "completed" is derived from the spawn result.
+    // A spawn error (interpreter missing) or a signal kill (timeout, SIGKILL)
+    // means the script never ran to completion — fail closed on those.
+    const spawnErr = result.error ? `\n[spawn error] ${result.error.message}` : "";
+    const completed = !result.error && result.signal === null;
+    const { rawOutput, output, truncated } = splitOutput(
+      sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr),
+    );
+    const evidence = readAndPreserveEvidence(evidenceDir, nonce);
+    return {
+      path: pocPath,
+      exitCode: spawnExitCode(result),
+      output,
+      rawOutput,
+      truncated,
+      ranAt,
+      sandbox: false,
+      completed,
+      outputComplete: outputWasComplete(result),
+      nonce,
+      ...evidence,
+      ...runProvenance(env),
+    };
+  } finally {
+    try {
+      rmSync(evidenceDir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
 }
 
 /**
@@ -547,8 +707,7 @@ function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, s
  * Language detection (in order):
  * 1. Shebang line in the PoC file.
  * 2. File extension (a .py PoC in a Node repo still runs under python).
- * 3. Project type markers in the workspace root (e.g., package.json, requirements.txt).
- * 4. PI_POC_DEFAULT_LANGUAGE environment variable (a built-in language key).
+ * 3. PI_POC_DEFAULT_LANGUAGE environment variable (a built-in language key).
  *
  * Security:
  * - PoC paths must be absolute and under the project workspace by default.
@@ -561,20 +720,12 @@ function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, s
  *   `PI_POC_ALLOW_LOCAL=1` and is used only when Docker is unavailable
  *   (or when `PI_POC_FORCE_LOCAL=1` is also set). Without ALLOW the run
  *   fails closed if Docker cannot start.
- *
- * Back-compat: `runPoc(path, true)` == sandboxed, `runPoc(path, false)` ==
- * `{ local: true }` (host-network sandbox; host if operator-gated).
  */
-export function runPoc(pocPath: string, options?: PocRunOptions | boolean): PocRun {
+export function runPoc(pocPath: string, options?: PocRunOptions): PocRun {
   const normalized = validatePocPath(pocPath);
   const { language } = resolveLanguage(normalized);
 
-  const opts: PocRunOptions =
-    typeof options === "boolean"
-      ? options
-        ? { network: "none" }
-        : { local: true }
-      : (options ?? {});
+  const opts: PocRunOptions = options ?? {};
 
   // Host execution is gated by the OPERATOR, never by an agent-supplied flag.
   // `local: true` means "network access needed":

package/src/safe-state.ts

@@ -0,0 +1,108 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+function isWithin(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+
+function validateComponent(component: string): void {
+  if (!component || component === "." || component === ".." || basename(component) !== component) {
+    throw new Error(`Unsafe state path component: ${component}`);
+  }
+}
+
+function verifyDirectory(path: string, canonicalRoot: string): void {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`State directory must be a real directory, not a symlink: ${path}`);
+  }
+  const canonical = realpathSync(path);
+  if (!isWithin(canonicalRoot, canonical)) {
+    throw new Error(`State directory resolves outside its workspace: ${path}`);
+  }
+}
+
+/**
+ * Create and verify a state-directory chain beneath a trusted workspace root.
+ * Every child component is checked with lstat so a pre-planted symlink cannot
+ * redirect ledger, evidence, or scratchpad writes outside the workspace.
+ */
+export function ensureSafeStateDirectory(root: string, components: string[]): string {
+  const canonicalRoot = realpathSync(root);
+  let current = resolve(root);
+  for (const component of components) {
+    validateComponent(component);
+    current = join(current, component);
+    if (!existsSync(current)) {
+      try {
+        mkdirSync(current, { mode: 0o700 });
+      } catch (error) {
+        // A concurrent creator is acceptable only if the postcondition below
+        // proves it created a real in-workspace directory.
+        if (!existsSync(current)) throw error;
+      }
+    }
+    verifyDirectory(current, canonicalRoot);
+  }
+  return current;
+}
+
+/** Verify an existing state-directory chain without creating anything. */
+export function assertSafeStateDirectory(root: string, components: string[]): string {
+  const canonicalRoot = realpathSync(root);
+  let current = resolve(root);
+  for (const component of components) {
+    validateComponent(component);
+    current = join(current, component);
+    if (!existsSync(current)) throw new Error(`State directory does not exist: ${current}`);
+    verifyDirectory(current, canonicalRoot);
+  }
+  return current;
+}
+
+/** Return false for a missing file; reject symlinks and special files. */
+export function assertSafeRegularFile(path: string, label = "State file"): boolean {
+  if (!existsSync(path)) return false;
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`${label} must be a regular, non-symlink file: ${path}`);
+  }
+  return true;
+}
+
+export function readSafeFile(path: string, label = "State file"): Buffer {
+  if (!assertSafeRegularFile(path, label)) throw new Error(`${label} does not exist: ${path}`);
+  return readFileSync(path);
+}
+
+/**
+ * Write through an exclusive temporary file and atomically rename it into
+ * place. An existing symlink is rejected, and rename replaces the directory
+ * entry rather than following a destination changed after the check.
+ */
+export function writeSafeFileAtomic(path: string, data: string | Buffer): void {
+  assertSafeRegularFile(path);
+  const tmp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(tmp, data, { flag: "wx", mode: 0o600 });
+    renameSync(tmp, path);
+  } finally {
+    if (existsSync(tmp)) rmSync(tmp, { force: true });
+  }
+}
+
+/** Create a new immutable state file; collisions and symlinks fail closed. */
+export function writeSafeFileExclusive(path: string, data: string | Buffer): void {
+  writeFileSync(path, data, { flag: "wx", mode: 0o600 });
+}

package/src/scratchpad.ts

@@ -25,16 +25,15 @@
  */
 
 import { createHash } from "node:crypto";
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import {
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, join, resolve } from "node:path";
+  assertSafeRegularFile,
+  assertSafeStateDirectory,
+  ensureSafeStateDirectory,
+  readSafeFile,
+  writeSafeFileAtomic,
+} from "./safe-state.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -127,7 +126,7 @@ export function findWorkspaceRoot(envNames: string[], markers: string[]): string
 }
 
 /** Detect the scratchpad workspace root (override, env, then walk up). */
-function detectWorkspaceRoot(): string {
+export function detectWorkspaceRoot(): string {
   if (scratchpadRootOverride) return scratchpadRootOverride;
   return findWorkspaceRoot(
     ["XPI_SCRATCHPAD_ROOT", "PI_WORKSPACE_ROOT", "GITHUB_WORKSPACE"],
@@ -168,6 +167,23 @@ function runDirName(runId: string): string {
   return `${safe.slice(0, 80)}-${suffix}`;
 }
 
+/**
+ * Artifact names get the same disambiguation as run dirs: sanitization is
+ * lossy ("a/b" and "a_b" both become "a_b"), so a changed name gets a content
+ * hash suffix — distinct inputs can no longer silently overwrite each other's
+ * file. Reads use the same mapping, so round-trips stay consistent.
+ */
+function artifactFileName(name: string): string {
+  const safe = sanitizeName(name, "artifact name");
+  if (safe === name) return safe;
+  const suffix = createHash("sha256").update(name).digest("hex").slice(0, 12);
+  return `${safe.slice(0, 80)}-${suffix}`;
+}
+
+/** Cap on a single scratchpad artifact (2 MiB) — a hallucinating or hostile
+ * subagent must not be able to fill the disk with unbounded writes. */
+const MAX_ARTIFACT_BYTES = 2 * 1024 * 1024;
+
 /** Pre-hash-suffix naming used by older scratchpad versions (sanitize only). */
 function legacyRunDirName(runId: string): string {
   return sanitizeName(runId, "run_id");
@@ -198,17 +214,23 @@ function emptyCheckpoint(runId: string, projectRoot: string): ScratchpadCheckpoi
 }
 
 function ensureRunDirs(runDir: string): void {
-  if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
+  const scratchpadRoot = dirname(runDir);
+  const projectRoot = dirname(scratchpadRoot);
+  const runName = basename(runDir);
+  ensureSafeStateDirectory(projectRoot, [SCRATCHPAD_DIR, runName]);
   for (const phase of PHASE_ORDER) {
-    const dir = join(runDir, PHASE_DIRS[phase]);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    ensureSafeStateDirectory(projectRoot, [SCRATCHPAD_DIR, runName, PHASE_DIRS[phase]]);
   }
 }
 
 function readCheckpointRaw(runId: string, projectRoot?: string): ScratchpadCheckpoint | null {
+  const root = projectRoot ?? detectWorkspaceRoot();
   const statePath = getStatePath(runId, projectRoot);
-  if (!existsSync(statePath)) return null;
-  const raw = readFileSync(statePath, "utf8");
+  if (existsSync(statePath)) {
+    assertSafeStateDirectory(root, [SCRATCHPAD_DIR, runDirName(runId)]);
+  }
+  if (!assertSafeRegularFile(statePath, "Scratchpad checkpoint")) return null;
+  const raw = readSafeFile(statePath, "Scratchpad checkpoint").toString("utf8");
   const cp = JSON.parse(raw) as ScratchpadCheckpoint;
   if (typeof cp !== "object" || cp === null || Array.isArray(cp)) {
     throw new Error(`Corrupt scratchpad state for ${runId}: root must be an object`);
@@ -241,9 +263,7 @@ function writeCheckpointRaw(cp: ScratchpadCheckpoint, projectRoot?: string): voi
   cp.last_updated = new Date().toISOString();
   const statePath = getStatePath(cp.run_id, projectRoot);
   ensureRunDirs(getRunDir(cp.run_id, projectRoot));
-  const tmp = `${statePath}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tmp, JSON.stringify(cp, null, 2), "utf8");
-  renameSync(tmp, statePath);
+  writeSafeFileAtomic(statePath, JSON.stringify(cp, null, 2));
 }
 
 // ── Public API ───────────────────────────────────────────────────────
@@ -281,11 +301,18 @@ export function scratchpad_write(
   const runDir = getRunDir(runId, root);
   ensureRunDirs(runDir);
 
-  // Sanitize artifact name: no path traversal, no dot-only escape.
-  const safeName = sanitizeName(artifactName, "artifact name");
+  if (Buffer.byteLength(content, "utf8") > MAX_ARTIFACT_BYTES) {
+    throw new Error(
+      `Artifact too large (${Buffer.byteLength(content, "utf8")} bytes; max ${MAX_ARTIFACT_BYTES}): ${artifactName}`,
+    );
+  }
+
+  // Sanitize + disambiguate artifact name: no path traversal, no dot-only
+  // escape, and lossy sanitization cannot collide two distinct names.
+  const safeName = artifactFileName(artifactName);
   const dir = join(runDir, PHASE_DIRS[phase]);
   const filePath = join(dir, safeName);
-  writeFileSync(filePath, content, "utf8");
+  writeSafeFileAtomic(filePath, content);
   return filePath;
 }
 
@@ -299,10 +326,13 @@ export function scratchpad_read(
   projectRoot?: string,
 ): string | null {
   const root = projectRoot ?? detectWorkspaceRoot();
-  const safeName = sanitizeName(artifactName, "artifact name");
+  const safeName = artifactFileName(artifactName);
   const filePath = join(getRunDir(runId, root), PHASE_DIRS[phase], safeName);
-  if (!existsSync(filePath)) return null;
-  return readFileSync(filePath, "utf8");
+  if (existsSync(filePath)) {
+    assertSafeStateDirectory(root, [SCRATCHPAD_DIR, runDirName(runId), PHASE_DIRS[phase]]);
+  }
+  if (!assertSafeRegularFile(filePath, "Scratchpad artifact")) return null;
+  return readSafeFile(filePath, "Scratchpad artifact").toString("utf8");
 }
 
 /**
@@ -311,13 +341,16 @@ export function scratchpad_read(
 export function scratchpad_runs(projectRoot?: string): string[] {
   const root = getScratchpadRoot(projectRoot);
   if (!existsSync(root)) return [];
+  assertSafeStateDirectory(dirname(root), [SCRATCHPAD_DIR]);
   const out: string[] = [];
   for (const entry of readdirSync(root, { withFileTypes: true })) {
     if (!entry.isDirectory()) continue;
     const state = join(root, entry.name, "state.json");
-    if (!existsSync(state)) continue;
+    if (!assertSafeRegularFile(state, "Scratchpad checkpoint")) continue;
     try {
-      const cp = JSON.parse(readFileSync(state, "utf8")) as { run_id?: unknown };
+      const cp = JSON.parse(readSafeFile(state, "Scratchpad checkpoint").toString("utf8")) as {
+        run_id?: unknown;
+      };
       if (typeof cp.run_id !== "string") continue;
       if (getRunDir(cp.run_id, projectRoot) === join(root, entry.name)) {
         out.push(cp.run_id);
@@ -342,7 +375,10 @@ export function scratchpad_list(
   const root = projectRoot ?? detectWorkspaceRoot();
   const dir = join(getRunDir(runId, root), PHASE_DIRS[phase]);
   if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter((f) => f !== "state.json");
+  assertSafeStateDirectory(root, [SCRATCHPAD_DIR, runDirName(runId), PHASE_DIRS[phase]]);
+  return readdirSync(dir).filter(
+    (f) => f !== "state.json" && assertSafeRegularFile(join(dir, f), "Scratchpad artifact"),
+  );
 }
 
 /**
@@ -413,5 +449,8 @@ export function scratchpad_phase_done(
 export function scratchpad_clear(runId: string, projectRoot?: string): void {
   const root = projectRoot ?? detectWorkspaceRoot();
   const runDir = getRunDir(runId, root);
-  if (existsSync(runDir)) rmSync(runDir, { recursive: true, force: true });
+  if (existsSync(runDir)) {
+    assertSafeStateDirectory(root, [SCRATCHPAD_DIR, runDirName(runId)]);
+    rmSync(runDir, { recursive: true, force: true });
+  }
 }