@xaccefy/pi-casefile 0.8.1 → 0.8.3

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 ────────────────────────────────────────────────────────────
@@ -152,9 +161,21 @@ 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}`;
+}
+
+/** 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 +208,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 ───────────────────────────────────────────────────────
@@ -268,6 +308,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,

package/src/workflow.ts

@@ -38,15 +38,15 @@ Think like a real external attacker, not a code reviewer. Technical bugs are che
 
 **Web lookup (research):** web_search, web_fetch, exploit_search, context7, deepwiki, http_request
 
-**Subagent dispatch:** \`subagent({agent: "auditor"|"tracer"|"skeptic"|"exploit"|"chain"|"reporter", task: "..."})\` — dispatch specialists; do NOT do the specialist work yourself.
+**Subagent dispatch:** every launch uses \`subagent({ workflowScript: "return runs.run('stable-key', { agent: 'tracer', task: '...' })", context: 'fresh', async: true })\`. Parallel HUNT uses one workflowScript with \`return runs.all([{ key: 'run-class-attempt', agent: 'auditor', task: '...' }, ...])\`. Stable keys include run, stage, class/case, and attempt. Dispatch specialists; do NOT do their work yourself.
 
 ## Stage Machine (run in order — you are the coordinator)
 
 RECON (you, inline) → **HUNT** (auditor subagents, one per attack class, parallel) → TRACE (tracer) → SKEPTIC (high-confidence only) → VALIDATE (exploit) → CHAIN (chain) → REPORT (reporter)
 
-**HARD GATE — after RECON:** record the entry-point inventory, then STOP all inline reading/probing. Your very next tool call MUST be \`subagent({ tasks: [...] })\` dispatching HUNT auditors. If you catch yourself mapping a sink, reading a handler, or probing an endpoint beyond the recon inventory — that is HUNT work; stop, note it as a hunt task, and dispatch. Recon that bleeds into hunting is a pipeline violation, not progress.
+**HARD GATE — after RECON:** record the entry-point inventory, then STOP all inline reading/probing. Your next tool call MUST launch one async workflowScript whose \`runs.all([...])\` dispatches HUNT auditors. When its completion is delivered, submit each output through PipelineSubmit. If you catch yourself mapping a sink, reading a handler, or probing an endpoint beyond the recon inventory, stop and add it to a HUNT task.
 
-**Subagent crash handling:** a subagent that dies (SIGABRT, OOM, timeout) is a RETRY, not a verdict — re-dispatch the same task once with a stronger model (\`subagent({agent, model, task})\`); repetition-loop runs are a known failure mode on cheap models. Crash again → record \`blocked: <agent> crashed\` in the pipeline-run case and continue; never silently drop the stage.
+**Subagent crash handling:** a crash (SIGABRT, OOM, timeout) is a RETRY, not a verdict. Launch one new workflowScript with the same specialist task, a new stable attempt key, and a stronger model. Crash again → record \`blocked: <agent> crashed\` in the pipeline-run case and continue; never silently drop the stage.
 
 ## Case Lifecycle (State Machine)
 ${LIFECYCLE_DIAGRAM}
@@ -66,7 +66,7 @@ ${LIFECYCLE_DIAGRAM}
 | Advance To | Required Case Fields | On Disk |
 |-----------|---------------------|---------|
 | HYPOTHESIS → INVESTIGATING | evidence (observations), confidence | Notes on what was observed |
-| INVESTIGATING → **CONFIRMED** | evidence, poc, **impact** (content below), severity, **target**, **disconfirmation** (your documented disprove attempt) | PoC script, exit 0, **verification_marker in output** (proves the exploit ran, not just the script). Optional disconfirmation script exit non-0. |
+| INVESTIGATING → **CONFIRMED** | evidence, poc, **impact** (content below), severity, **target**, **disconfirmation** (your documented disprove attempt) | PoC script exit 0 with verification_marker; same-script control at a distinct control_target completes with liveness but no vuln marker; disconfirmation script completed and exited non-0. |
 | Any → KILLED | assumptions (why it died) | — |
 | CONFIRMED → REPORTED | CaseContext(id) succeeded (records report path) AND the reporter agent wrote the report file | Context bundle + report file |
 
@@ -120,7 +120,7 @@ If you cannot name a concrete attacker who gains something they should not have
 
 The finding must survive an attempt to disprove it. Two tiers, gated on \`confidence\` (severity comes later, from the PoC):
 
-**\`confidence: high\` → skeptic subagent (MANDATORY):** dispatch \`subagent({agent: "skeptic", task: "..."})\` BEFORE the exploit agent. It independently re-reads the source (or re-probes live), verifies scope, and tries to disprove. Its \`disconfirmation_attempt\` becomes the case's \`disconfirmation\` — stronger than self-disconfirmation. DISPROVEN → killed directly, no tie-breaker. Do NOT skip; do NOT self-disconfirm high-confidence findings.
+**\`confidence: high\` → skeptic subagent (MANDATORY):** dispatch it BEFORE the exploit agent with \`subagent({ workflowScript: "return runs.run('skeptic-<case>-1', { agent: 'skeptic', task: '...' })", context: 'fresh', async: true })\`. It independently re-reads the source (or re-probes live), verifies scope, and tries to disprove. Its \`disconfirmation_attempt\` becomes the case's \`disconfirmation\` — stronger than self-disconfirmation. DISPROVEN → killed directly, no tie-breaker. Do NOT skip; do NOT self-disconfirm high-confidence findings.
 
 **Below high → self-disconfirmation:** actively try to disprove your own finding; document it. Not a formality.
 
@@ -129,13 +129,13 @@ An attempt: reproduce under different conditions (auth/config/network position);
 Strong example: "Read /api/users/123 as user B after confirming user A owns 123 → 403. Repeated with X-Override-User header (seen in admin traffic) → user A's data returned. Protection bypassed via the admin header."
 Weak: "Tried to disprove. Could not." — insufficient.
 
-If the disconfirmation script (\`disconfirmation_path\`) exits 0, promotion is blocked. If you cannot write a meaningful disconfirmation script, you don't understand the finding well enough to promote it. A disconfirmation (or control) script that CRASHES — killed, timed out, interpreter missing — is blocked too: the harness detects the missing completion marker, and a crash is neither a survived disproof nor a clean control verdict.
+If the disconfirmation script (\`disconfirmation_path\`) exits 0, promotion is blocked. The disconfirmation script is REQUIRED for **every** promotion — the prose \`disconfirmation\` field alone cannot carry the disprove-attempt at any severity (a case filed low/medium must not skip the run and be re-raised afterwards). If you cannot write a meaningful disconfirmation script, you don't understand the finding well enough to promote it. A disconfirmation (or control) script that CRASHES — killed, timed out, interpreter missing — is blocked too: the harness detects the missing completion marker, and a crash is neither a survived disproof nor a clean control verdict.
 
-**Evidence chain closure (before PromoteFinding):** promotion is rejected unless the case carries an \`observation\` evidence item (EvidenceAdd role=observation — the initial signal) in addition to the auto-recorded reproduction item. Record observations as you go, not at promote time.
+**Evidence chain closure (before PromoteFinding):** promotion is rejected unless the case carries an **artifact-backed** \`observation\` evidence item (EvidenceAdd role=observation with \`artifact_path\` — the initial signal, stored with its SHA-256) in addition to the auto-recorded reproduction item. Record observations as you go, not at promote time.
 
-**Control-target check (anti-cheat, REQUIRED for live findings):** for any finding tested against a live target (\`local:true\`), write \`control_path\` — a script that runs the SAME PoC against a control lacking the vulnerability (patched replica, second account, baseline endpoint, WAF-blocked path). The harness runs it and blocks promotion if the verification_marker appears in the control output. That is what proves the marker is target-dependent, not an unconditional print. If the PoC cannot be pointed at a control (no replica exists), say so in \`disconfirmation\` and downgrade confidence accordingly — do not skip the check for live findings.
+**Differential control check (REQUIRED for EVERY promotion):** pass \`control_path\` (the SAME bytes as the PoC), a distinct \`control_target\`, and \`control_liveness_marker\`. The harness runs the same script with \`PI_POC_MODE=poc\` and the case target, then \`PI_POC_MODE=control\` and \`control_target\`. Control must complete, print liveness after reaching the baseline, and omit the vulnerability marker. Checks use complete captured output; crashed or truncated output blocks promotion. **Local/live findings:** \`local:true\` uses the host-network Docker sandbox. Bare host execution still needs operator \`PI_POC_ALLOW_LOCAL=1\`.
 
-**PoC audit (anti-cheat, before PromoteFinding):** have an independent eye on the PoC script itself. For \`confidence: high\` findings the skeptic agent re-reads the PoC file (not just the source) hunting for: unconditional marker prints, trivially-true checks (accepting any 200, grepping for always-present strings), hardcoded expected values, and local mocks of the target. Record the audit result as an EvidenceAdd \`observation\` item (or \`refutation\` if it found a cheat → kill). The model that writes the check must not be the only one that reads it.
+**PoC audit (anti-cheat, before PromoteFinding):** have an independent eye on the PoC script itself. For \`confidence: high\` findings the skeptic agent re-reads the PoC file (not just the source) hunting for: unconditional marker prints, trivially-true checks (accepting any 200, grepping for always-present strings), hardcoded expected values, and local mocks of the target. Record the audit result as an EvidenceAdd \`observation\` item (or \`refutation\` if it found a cheat → kill). The model that writes the check must not be the only one that reads it. The deterministic backstops are code, not prompts: the control run (mandatory, marker-absence + liveness-presence checks) and, for high/critical, the executed disconfirmation run.
 
 ### 2. Design & Runtime Check — non-intentionality gate (mandatory)
 
@@ -161,7 +161,7 @@ Name the **specific target host/repo** in the target field. Dev-only with non-de
 
 ### 4. KILL at Validate stage
 
-Documented intended behavior · self-XSS/self-DoS only · requires admin/root role that already has the power · local-only/offline/impossible deployment · needs physical access or social engineering with no trust-boundary break · no C/I/A/financial effect for anyone but the attacker · PoC proves a code path but no victim asset · protections block the path and are not bypassed.
+Documented intended behavior · self-XSS/self-DoS only · requires admin/root role that already has the power · local-only/offline/impossible deployment · needs physical access or social engineering with no trust-boundary break · no C/I/A/financial effect for anyone but the attacker · PoC proves a code path but no victim asset · protections block the path and are not bypassed. **Kill gate:** killing a case that reached \`investigating\`/\`confirmed\` requires a refutation evidence item (EvidenceAdd role=refutation — the disprove attempt that ended the lead); a keyword in free text is not enough once the case advanced past hypothesis.
 
 ### 5. Evidence-First Doctrine
 
@@ -210,7 +210,7 @@ Reproduce at least twice or via two methods.
 ## At REPORT
 
 1. **Run CaseContext(case_id)** — writes the context bundle (complete record, PoC + disconfirmation logs, links, pipeline artifacts) and records the report path.
-2. **Dispatch the reporter subagent**: \`subagent({agent: "reporter", task: "Write the final report for case <id>. case_id=<id>, context_path=<path from CaseContext>, report_path=<path from CaseContext>, program_name=<program if known>. Apply the fixed report format rules in your prompt (title convention, body template, tone rules). Output: the report file written to report_path + CaseUpdate(status: 'reported')."})\`. It writes the polished report and flips the case to REPORTED.
+2. **Dispatch the reporter subagent** with \`subagent({ workflowScript: "return runs.run('report-<case>-1', { agent: 'reporter', task: 'Write the final report. case_id=<id>, context_path=<context path>, report_path=<report path>, program_name=<if known>.' })", context: 'fresh', async: true })\`. It writes the polished report and flips the case to REPORTED.
 3. **Report-readiness gate** (YOU check this on the reporter's output before accepting; on failure, re-dispatch with the gap list):
 - Deterministic reproduction by another researcher
 - Steps realistic in production
@@ -219,6 +219,8 @@ Reproduce at least twice or via two methods.
 - Attacker model + victim impact + target explicit
 - No internal identifiers: no case IDs, ledger paths, PoC filenames, or local paths in the report file
 
+The ledger enforces a machine floor on the report file before accepting \`reported\`: non-trivial size, required section headings (Summary / Impact / Remediation), and a forbidden-identifier scan (case id, ledger/report paths, PoC/control/disconfirmation basenames). A report that fails the scan keeps the case CONFIRMED — fix the file, then retry the transition.
+
 ---
 
 ## KILLED cataloging
@@ -275,7 +277,7 @@ Write the final report as a self-contained markdown file at the report path Case
 - **No finding is confirmed until its target is verified in scope** per the program's scope instruction. Out-of-scope findings are killed, not confirmed.
 - **No finding is validated without a reachability trace** showing REACHABLE.
 - **High-confidence findings: do your own adversarial disconfirmation.** No skeptic subagent in lite mode — actively try to disprove your own finding and document the attempt in \`disconfirmation\`. Failing to disprove is the expected outcome.
-- **Confirmed requires** evidence + poc + impact + severity + target + disconfirmation, and a PoC that exited 0 **with the verification_marker in the output**. **Live findings (local:true) also require control_path**: the same PoC run against a control lacking the vuln must NOT print the marker (harness-side check) — this is what stops unconditional-marker and mock-target cheats. No mocks for the exploitation step.
+- **Confirmed requires** evidence + poc + impact + severity + target + disconfirmation. Every promotion also requires \`disconfirmation_path\`, same-script \`control_path\`, a distinct \`control_target\`, and \`control_liveness_marker\`. The PoC must print the verification marker; the completed control must print liveness and omit it. \`local:true\` uses a host-network sandbox; bare host execution needs operator \`PI_POC_ALLOW_LOCAL=1\`. No mocks.
 - **Severity is derived from proven PoC impact, not theory.** Under-claiming is safe; over-claiming gets the finding rejected at triage.
 - **Evidence-first:** every claim must be traceable to observed/reproduced behavior, source code, or documented platform behavior.
 - **Design & runtime check (mandatory before CONFIRMED):** actively search the target's docs, git history, changelog, and runtime/framework docs for evidence the behavior is BY DESIGN or already FIXED IN THE RUNTIME. Found it → KILL (\`intended_behavior\` / \`framework_protection\`), unless the documented intent is itself the flaw with real attacker impact. Not found → document the search in \`disconfirmation\` as non-intentionality proof.