@xaccefy/pi-casefile 0.8.2 → 0.9.0

package/src/poc-runner.ts

@@ -1,7 +1,9 @@
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
   copyFileSync,
   existsSync,
+  mkdirSync,
   mkdtempSync,
   readFileSync,
   realpathSync,
@@ -11,6 +13,7 @@ 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 { findWorkspaceRoot } from "./scratchpad.ts";
 
 export type PocRun = {
@@ -34,12 +37,28 @@ export type PocRun = {
   rawOutput?: string;
   /** True when `output` was truncated for display (rawOutput has more). */
   truncated?: boolean;
-  /**
-   * True when the run never started because of harness infrastructure
+  /** True iff child output capture was complete. False on maxBuffer/timeouts/spawn failures. */
+  outputComplete?: boolean;
+  /** Harness mode used for this run. */
+  mode?: string;
+  /** Harness target used for this run. */
+  target?: string;
+  /** 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;
 };
 
 /**
@@ -106,13 +125,15 @@ const EXTENSION_MAP: Record<string, string> = {
 };
 
 const OUTPUT_MAX_CHARS = 4000;
-/** Sanitized output is kept whole (for marker checks) up to this size. */
-const RAW_OUTPUT_MAX_CHARS = 4 * 1024 * 1024;
 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)}__`;
 }
+/** 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)}`;
+}
 /** First-use image downloads are slow — pull outside the run timeout. */
 const PULL_TIMEOUT_MS = 300_000;
 const MAX_BUFFER = 8 * 1024 * 1024;
@@ -278,9 +299,73 @@ function sanitizeOutput(output: string): string {
 
 /** Split sanitized output into the raw (whole) and display (sliced) halves. */
 function splitOutput(raw: string): { rawOutput: string; output: string; truncated: boolean } {
-  const rawOutput = raw.slice(0, RAW_OUTPUT_MAX_CHARS);
   const truncated = raw.length > OUTPUT_MAX_CHARS;
-  return { rawOutput, output: raw.slice(0, OUTPUT_MAX_CHARS), truncated };
+  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; 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"})`,
+    };
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(p, "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(readFileSync(p)).digest("hex"),
+  };
+}
+
+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(evidenceDir: string, nonce: string): string | undefined {
+  const source = join(evidenceDir, "evidence.json");
+  if (!existsSync(source)) return undefined;
+  try {
+    const durableDir = join(getProjectRoot(), ".pi", "poc-evidence");
+    mkdirSync(durableDir, { recursive: true });
+    const dest = join(durableDir, `${nonce}.evidence.json`);
+    copyFileSync(source, dest);
+    return dest;
+  } catch {
+    // Best-effort: a preserved copy is an audit-trail improvement, not a gate.
+    return undefined;
+  }
+}
+
+function outputWasComplete(result: { error?: Error; signal: string | null }): boolean {
+  return !result.error && result.signal === null;
 }
 
 /** Reject control characters in harness-supplied PoC env values. */
@@ -412,6 +497,17 @@ function runSandboxed(
   // 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)}`;
+  // 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
@@ -427,6 +523,8 @@ function runSandboxed(
         sandbox: true,
         completed: false,
         infraError: true,
+        outputComplete: false,
+        ...runProvenance(env),
       };
     }
     copyFileSync(pocPath, `${workspaceDir}/${sourceName}`);
@@ -434,15 +532,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,
@@ -454,6 +554,8 @@ 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);
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
@@ -463,6 +565,11 @@ function runSandboxed(
       ranAt,
       sandbox: true,
       completed,
+      outputComplete: outputWasComplete(result),
+      nonce,
+      ...evidence,
+      evidencePath: evidence.evidence ? preserved : undefined,
+      ...runProvenance(env),
     };
   } finally {
     // Best-effort: remove any container still running after a timeout/kill.
@@ -481,47 +588,70 @@ 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,
+  // 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 preserved = preserveEvidence(evidenceDir, nonce);
+    const evidence = readEvidence(evidenceDir, nonce);
+    return {
+      path: pocPath,
+      exitCode: spawnExitCode(result),
+      output,
+      rawOutput,
+      truncated,
+      ranAt,
+      sandbox: false,
+      completed,
+      outputComplete: outputWasComplete(result),
+      nonce,
+      ...evidence,
+      evidencePath: evidence.evidence ? preserved : undefined,
+      ...runProvenance(env),
+    };
+  } finally {
+    try {
+      rmSync(evidenceDir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup.
+    }
+  }
 }
 
 /**
@@ -530,8 +660,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.
@@ -544,20 +673,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/scratchpad.ts

@@ -24,7 +24,16 @@
  * `--fresh` clears it via scratchpad_clear().
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join, resolve } from "node:path";
 
 // ── Types ────────────────────────────────────────────────────────────
@@ -118,7 +127,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"],
@@ -152,9 +161,38 @@ function sanitizeName(name: string, label: string): string {
   return safe;
 }
 
+function runDirName(runId: string): string {
+  const safe = sanitizeName(runId, "run_id");
+  if (safe === runId) return safe;
+  const suffix = createHash("sha256").update(runId).digest("hex").slice(0, 12);
+  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");
+}
+
 /** The directory for a specific run. */
 export function getRunDir(runId: string, projectRoot?: string): string {
-  return join(getScratchpadRoot(projectRoot), sanitizeName(runId, "run_id"));
+  return join(getScratchpadRoot(projectRoot), runDirName(runId));
 }
 
 /** The state.json path for a run. */
@@ -187,23 +225,42 @@ function ensureRunDirs(runDir: string): void {
 function readCheckpointRaw(runId: string, projectRoot?: string): ScratchpadCheckpoint | null {
   const statePath = getStatePath(runId, projectRoot);
   if (!existsSync(statePath)) return null;
-  try {
-    const raw = readFileSync(statePath, "utf8");
-    const cp = JSON.parse(raw) as ScratchpadCheckpoint;
-    // Backfill maps for phases not yet checkpointed (defensive).
-    if (!cp.phase_ids) cp.phase_ids = {} as Record<ScratchpadPhase, string[]>;
-    if (!cp.phase_summaries) cp.phase_summaries = {} as Record<ScratchpadPhase, string>;
-    return cp;
-  } catch {
-    return null;
+  const raw = readFileSync(statePath, "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`);
+  }
+  if (cp.run_id !== runId) {
+    throw new Error(`Corrupt scratchpad state for ${runId}: state belongs to ${cp.run_id}`);
+  }
+  if (!Array.isArray(cp.completed_phases)) {
+    throw new Error(`Corrupt scratchpad state for ${runId}: completed_phases must be an array`);
   }
+  for (const phase of cp.completed_phases) {
+    if (!PHASE_ORDER.includes(phase)) {
+      throw new Error(`Corrupt scratchpad state for ${runId}: invalid phase ${phase}`);
+    }
+  }
+  if (!cp.phase_ids || typeof cp.phase_ids !== "object" || Array.isArray(cp.phase_ids)) {
+    cp.phase_ids = {} as Record<ScratchpadPhase, string[]>;
+  }
+  if (
+    !cp.phase_summaries ||
+    typeof cp.phase_summaries !== "object" ||
+    Array.isArray(cp.phase_summaries)
+  ) {
+    cp.phase_summaries = {} as Record<ScratchpadPhase, string>;
+  }
+  return cp;
 }
 
 function writeCheckpointRaw(cp: ScratchpadCheckpoint, projectRoot?: string): void {
   cp.last_updated = new Date().toISOString();
   const statePath = getStatePath(cp.run_id, projectRoot);
   ensureRunDirs(getRunDir(cp.run_id, projectRoot));
-  writeFileSync(statePath, JSON.stringify(cp, null, 2), "utf8");
+  const tmp = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(cp, null, 2), "utf8");
+  renameSync(tmp, statePath);
 }
 
 // ── Public API ───────────────────────────────────────────────────────
@@ -241,8 +298,15 @@ 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");
@@ -259,7 +323,7 @@ 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");
@@ -268,6 +332,32 @@ export function scratchpad_read(
 /**
  * List all artifacts written for a phase.
  */
+export function scratchpad_runs(projectRoot?: string): string[] {
+  const root = getScratchpadRoot(projectRoot);
+  if (!existsSync(root)) return [];
+  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;
+    try {
+      const cp = JSON.parse(readFileSync(state, "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);
+      } else if (join(root, legacyRunDirName(cp.run_id)) === join(root, entry.name)) {
+        // Runs created before the hash-suffix naming used sanitizeName(runId)
+        // as the directory; keep surfacing them in bundle discovery. Safe ids
+        // were never suffixed, so only legacy unsafe ids can land here.
+        out.push(cp.run_id);
+      }
+    } catch {
+      // Corrupt runs are ignored during report bundle discovery; direct resume still fails closed.
+    }
+  }
+  return out;
+}
+
 export function scratchpad_list(
   runId: string,
   phase: ScratchpadPhase,