@xaccefy/pi-casefile 0.9.0 → 0.9.1

package/src/pipeline-submit.ts

@@ -18,8 +18,15 @@
  */
 
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { KILL_REASON_VALUES } from "./ledger.ts";
+import {
+  assertSafeRegularFile,
+  assertSafeStateDirectory,
+  readSafeFile,
+  writeSafeFileAtomic,
+} from "./safe-state.ts";
 import { getRunDir, getScratchpadRoot, scratchpad_write } from "./scratchpad.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -45,6 +52,8 @@ export type SubmitResult = {
 };
 
 type StageSpec = {
+  /** Exact top-level field allowlist; mirrors additionalProperties:false. */
+  allowed: readonly string[];
   /** Fields that must be present and non-empty. */
   required: {
     name: string;
@@ -86,6 +95,18 @@ const VULN_CLASSES = [
 export const SPECS: Record<SubmitStage, StageSpec> = {
   // schemas/stage-finding.json
   hunt: {
+    allowed: [
+      "vuln_class",
+      "file",
+      "line",
+      "endpoint",
+      "sink",
+      "entry_point",
+      "confidence",
+      "evidence",
+      "attacker_model",
+      "subsystem",
+    ],
     required: [
       { name: "vuln_class", type: "string", enum: VULN_CLASSES },
       { name: "sink", type: "string" },
@@ -98,6 +119,15 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-trace.json
   trace: {
+    allowed: [
+      "trace_result",
+      "entry_point",
+      "call_chain",
+      "defenses_checked",
+      "attacker_model",
+      "impact_if_reachable",
+      "unreachable_reason",
+    ],
     required: [
       { name: "trace_result", type: "string", enum: ["REACHABLE", "UNREACHABLE"] },
       { name: "entry_point", type: "string" },
@@ -112,6 +142,14 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-skeptic.json
   skeptic: {
+    allowed: [
+      "finding_id",
+      "verdict",
+      "reasoning",
+      "evidence_reviewed",
+      "disconfirmation_attempt",
+      "disproval_reason",
+    ],
     required: [
       { name: "finding_id", type: "string" },
       { name: "verdict", type: "string", enum: ["CONFIRMED", "DISPROVEN"] },
@@ -131,15 +169,30 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-validation.json
   validate: {
+    allowed: [
+      "finding_id",
+      "status",
+      "technique_used",
+      "detection_method",
+      "poc_path",
+      "run_log",
+      "evidence_extracted",
+      "kill_reason",
+      "refinement_attempts",
+    ],
     required: [
       { name: "finding_id", type: "string" },
-      { name: "status", type: "string", enum: ["confirmed", "killed", "reported"] },
+      {
+        name: "status",
+        type: "string",
+        enum: ["pending_confirmation", "killed", "reported"],
+      },
       { name: "technique_used", type: "string" },
       { name: "detection_method", type: "string" },
     ],
     conditional: [
       {
-        when: { field: "status", equals: "confirmed" },
+        when: { field: "status", equals: "pending_confirmation" },
         require: ["poc_path", "run_log", "evidence_extracted"],
       },
       { when: { field: "status", equals: "killed" }, require: ["kill_reason"] },
@@ -147,6 +200,7 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-chain.json
   chain: {
+    allowed: ["chains", "summary", "tokens_input", "tokens_output"],
     required: [
       { name: "chains", type: "array" },
       { name: "summary", type: "string" },
@@ -154,6 +208,16 @@ export const SPECS: Record<SubmitStage, StageSpec> = {
   },
   // schemas/stage-report.json
   report: {
+    allowed: [
+      "target",
+      "pipeline_status",
+      "total_tokens",
+      "findings",
+      "chains",
+      "coverage",
+      "summary",
+      "patches_applied",
+    ],
     required: [
       { name: "target", type: "string" },
       { name: "pipeline_status", type: "string", enum: ["complete", "partial", "aborted"] },
@@ -212,7 +276,11 @@ function statePath(runId: string): string {
 function readState(runId: string): SubmitState {
   const p = statePath(runId);
   if (!existsSync(p)) return { repairs: {}, accepted_findings: [] };
-  const raw = JSON.parse(readFileSync(p, "utf8")) as Partial<SubmitState>;
+  assertSafeStateDirectory(projectRoot(), [".scratchpad", basename(dirname(p))]);
+  assertSafeRegularFile(p, "Pipeline state");
+  const raw = JSON.parse(
+    readSafeFile(p, "Pipeline state").toString("utf8"),
+  ) as Partial<SubmitState>;
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error(`Corrupt pipeline-submit state for ${runId}: root must be an object`);
   }
@@ -246,9 +314,8 @@ function readState(runId: string): SubmitState {
 
 function writeState(runId: string, state: SubmitState): void {
   const p = statePath(runId);
-  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tmp, JSON.stringify(state, null, 2), "utf8");
-  renameSync(tmp, p);
+  assertSafeStateDirectory(projectRoot(), [".scratchpad", basename(dirname(p))]);
+  writeSafeFileAtomic(p, JSON.stringify(state, null, 2));
 }
 
 /** Project root containing the scratchpad (file-existence checks resolve here). */
@@ -411,6 +478,11 @@ function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string
   const spec = SPECS[stage];
   const errors: string[] = [];
 
+  const allowedFields = new Set(spec.allowed);
+  for (const name of Object.keys(obj)) {
+    if (!allowedFields.has(name)) errors.push(`${name}: unknown top-level field`);
+  }
+
   for (const field of spec.required) {
     const v = obj[field.name];
     if (field.type === "string") {
@@ -495,37 +567,20 @@ function validateStage(stage: SubmitStage, obj: Record<string, unknown>): string
   if (stage === "skeptic") {
     requireStringArray(errors, "evidence_reviewed", obj.evidence_reviewed, 1);
     if (obj.verdict === "DISPROVEN" && isNonEmptyString(obj.disproval_reason)) {
-      const allowed = [
-        "unreachable",
-        "framework_protection",
-        "input_validation_blocks",
-        "requires_privilege_attacker_lacks",
-        "intended_behavior",
-        "overstated_impact",
-        "duplicate",
-        "test_artifact",
-        "out_of_scope",
-      ];
-      if (!allowed.includes(obj.disproval_reason)) errors.push("disproval_reason: invalid value");
+      if (!(KILL_REASON_VALUES as readonly string[]).includes(obj.disproval_reason)) {
+        errors.push("disproval_reason: invalid value");
+      }
     }
   }
 
   if (stage === "validate") {
     if (obj.status === "killed" && isNonEmptyString(obj.kill_reason)) {
-      const allowed = [
-        "unreachable",
-        "framework_protection",
-        "input_validation_blocks",
-        "requires_privilege_attacker_lacks",
-        "poc_failed_3x",
-        "no_real_impact",
-        "intended_behavior",
-        "duplicate",
-      ];
-      if (!allowed.includes(obj.kill_reason)) errors.push("kill_reason: invalid value");
+      if (!(KILL_REASON_VALUES as readonly string[]).includes(obj.kill_reason)) {
+        errors.push("kill_reason: invalid value");
+      }
     }
-    if (obj.status === "confirmed" && isNonEmptyString(obj.poc_path)) {
-      // A validate submission asserting "confirmed" must point at a PoC file
+    if (obj.status === "pending_confirmation" && isNonEmptyString(obj.poc_path)) {
+      // A phase-1 validation submission must point at a PoC file
       // that actually exists in the project — same file-existence filter hunt
       // findings get. Otherwise fabricated run logs pass the stage gate.
       const raw = obj.poc_path as string;

package/src/poc-runner.ts

@@ -1,8 +1,9 @@
 import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import {
   copyFileSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -14,6 +15,7 @@ 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 = {
@@ -84,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. */
@@ -128,11 +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_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+  return `poc_${randomBytes(24).toString("hex")}`;
 }
 /** First-use image downloads are slow — pull outside the run timeout. */
 const PULL_TIMEOUT_MS = 300_000;
@@ -311,16 +314,37 @@ function splitOutput(raw: string): { rawOutput: string; output: string; truncate
 function readEvidence(
   evidenceDir: string,
   nonce: string,
-): { evidence?: PoCEvidence; evidenceSha256?: string; evidenceError?: 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 {
-    raw = JSON.parse(readFileSync(p, "utf8"));
+    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}` };
   }
@@ -334,7 +358,8 @@ function readEvidence(
   }
   return {
     evidence: parsed.evidence,
-    evidenceSha256: createHash("sha256").update(readFileSync(p)).digest("hex"),
+    evidenceSha256: createHash("sha256").update(bytes).digest("hex"),
+    evidenceBytes: bytes,
   };
 }
 
@@ -349,21 +374,47 @@ function runProvenance(env?: Record<string, string>): Pick<PocRun, "mode" | "tar
  * "artifact-backed" evidence item hashes a file that no longer exists.
  * Returns the preserved path, or undefined when the file is missing.
  */
-function preserveEvidence(evidenceDir: string, nonce: string): string | undefined {
-  const source = join(evidenceDir, "evidence.json");
-  if (!existsSync(source)) return undefined;
+function preserveEvidence(bytes: Buffer, nonce: string): string | undefined {
   try {
-    const durableDir = join(getProjectRoot(), ".pi", "poc-evidence");
-    mkdirSync(durableDir, { recursive: true });
+    const projectRoot = getProjectRoot();
+    const durableDir = ensureSafeStateDirectory(projectRoot, [".pi", "poc-evidence"]);
     const dest = join(durableDir, `${nonce}.evidence.json`);
-    copyFileSync(source, dest);
+    writeSafeFileExclusive(dest, bytes);
     return dest;
   } catch {
-    // Best-effort: a preserved copy is an audit-trail improvement, not a gate.
+    // 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;
 }
@@ -496,7 +547,7 @@ 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.
@@ -554,8 +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 preserved = preserveEvidence(evidenceDir, nonce);
-    const evidence = readEvidence(evidenceDir, nonce);
+    const evidence = readAndPreserveEvidence(evidenceDir, nonce);
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
@@ -568,7 +618,6 @@ function runSandboxed(
       outputComplete: outputWasComplete(result),
       nonce,
       ...evidence,
-      evidencePath: evidence.evidence ? preserved : undefined,
       ...runProvenance(env),
     };
   } finally {
@@ -628,8 +677,7 @@ function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, s
     const { rawOutput, output, truncated } = splitOutput(
       sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr),
     );
-    const preserved = preserveEvidence(evidenceDir, nonce);
-    const evidence = readEvidence(evidenceDir, nonce);
+    const evidence = readAndPreserveEvidence(evidenceDir, nonce);
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
@@ -642,7 +690,6 @@ function runLocal(pocPath: string, language: PocLanguage, env?: Record<string, s
       outputComplete: outputWasComplete(result),
       nonce,
       ...evidence,
-      evidencePath: evidence.evidence ? preserved : undefined,
       ...runProvenance(env),
     };
   } finally {

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 ────────────────────────────────────────────────────────────
 
@@ -215,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`);
@@ -258,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 ───────────────────────────────────────────────────────
@@ -309,7 +312,7 @@ export function scratchpad_write(
   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;
 }
 
@@ -325,8 +328,11 @@ export function scratchpad_read(
   const root = projectRoot ?? detectWorkspaceRoot();
   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");
 }
 
 /**
@@ -335,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);
@@ -366,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"),
+  );
 }
 
 /**
@@ -437,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 });
+  }
 }