@xaccefy/pi-casefile 0.8.3 → 0.9.1

package/README.md

@@ -32,6 +32,9 @@ State is persisted next to the ledger as `xp-mode` (e.g. `.pi/xp-mode`).
 |----------|---------|
 | `PI_CASEFILE_PATH` | Absolute path to the SQLite ledger file |
 | `CASEFILE_WORKSPACE_ROOT` / `PI_WORKSPACE_ROOT` | Override workspace root used to place `.pi/casefile.db` |
+| `PI_POC_ALLOW_NETWORK=1` | Operator authorization for a networked PoC sandbox |
+| `PI_POC_ALLOW_PRIVATE_REPLAY=1` | Operator authorization for harness replay to private/internal targets |
+| `PI_POC_CONTROL_TARGETS` | Comma/newline-separated operator-approved control hosts/origins; agent-invented controls are rejected |
 
 Default DB path: `<workspace>/.pi/casefile.db`
 
@@ -44,16 +47,16 @@ hypothesis → investigating → confirmed → reported
 ```
 
 - **investigating** needs `evidence` + `confidence`
-- **confirmed** only by running the PoC (`PromoteFinding`, exit 0 + verification marker in output) — you can't just set status to confirmed. Promotion additionally requires an EvidenceAdd `observation` item (the initial signal) — the ledger rejects a `confirmed` with no evidence chain.
-- **Live findings (`local:true`) also require `control_path`**: the same PoC run against a control lacking the vuln must NOT print the marker. The harness checks the control output itself — an unconditional-marker or mock-target PoC is blocked. The control run is stored as `controlVerified`. A control or disconfirmation script that **crashes** (killed / timeout / spawn error — no completion marker) is blocked too: a crash is not a clean control verdict and not a survived disproof. This applies at the ledger level, not just the tool: a local (sandbox:false) promotion without `controlVerification` is rejected by `promoteFindingResult` itself.
+- **confirmed** only through the two-phase gate — `PromoteFinding` runs the PoC 2× target + 1× control, requires complete zero-exit runs and nonce-bound discriminating response-body evidence, then the harness performs a DNS-pinned identical replay and requires two conclusive responses with `target_only`. Reflection-capable requests may add a post-PoC harness-generated canary that must appear only on target. Status-only/trivial matchers and incomplete response capture are rejected. Exit zero is necessary but never proof. The main agent performs semantic review and calls `ConfirmFinding`, which captures a second fresh harness replay and binds it to the verdict; worker processes are rejected. Blind/OOB claims fail closed without a source-separated oracle.
+- **Every promotion requires `control_path`** (the same bytes as the PoC — sha256 enforced) and a distinct `control_target` pre-approved by the operator in `PI_POC_CONTROL_TARGETS`; an agent cannot invent its own easy control. The control run is stored as `controlVerified`. Crashes, transport-inconclusive controls, status-only evidence, and missing evidence all block promotion.
 - **New cases require `disproveIf`** — falsification conditions (what would disprove this hypothesis). A hypothesis that can't say what kills it isn't one yet.
-- **A kill must be justified**: either an EvidenceAdd `refutation` item, or a kill-reason token (intended_behavior, duplicate, framework_protection, out_of_scope, skeptic-disproven, no_attack_path, ...) in assumptions/nextStep. Bare `status: "killed"` is rejected.
+- **A kill must be justified**: either an EvidenceAdd `refutation` item, or a canonical kill-reason token (intended_behavior, duplicate, framework_protection, out_of_scope, insufficient_impact, no_attack_path, ...) in assumptions/nextStep. Bare `status: "killed"` is rejected.
 - **reported** needs `CaseContext` first (records the report path; the report writer produces the final file)
 - **killed** / **reported** are final (no more edits)
 
 ## Evidence items
 
-`EvidenceAdd` records role-typed, artifact-backed evidence (observation / reproduction / impact / refutation / cleanup). Artifacts are stored as basename + SHA-256 — the full path is never persisted. The PoC gate auto-records the `reproduction` item (the PoC file, hashed) at promotion, so a confirmed case always traces back to a real artifact. `cleanup` items track engagement cleanup; record and confirm them before REPORT for sanctioned engagements (advisory — not yet a hard gate).
+`EvidenceAdd` records role-typed, artifact-backed evidence (observation / reproduction / impact / refutation / cleanup). Artifact reads are restricted to regular, non-symlink files inside the workspace. Bytes are copied durably and stored as basename + SHA-256; the full source path is never persisted. The PoC gate auto-records the `reproduction` item at promotion.
 
 ## Tools
 
@@ -62,7 +65,8 @@ hypothesis → investigating → confirmed → reported
 | `CaseAdd` | Open a case (`title` + `disproveIf` required; start as `hypothesis` or `investigating`) |
 | `CaseUpdate` | Evidence, impact, severity, status (not direct confirm) |
 | `EvidenceAdd` | Role-typed, hashed evidence item on a case (refutation justifies kills; cleanup tracks cleanup) |
-| `PromoteFinding` | Run on-disk PoC (Docker sandbox by default; `local:true` = host-network sandbox, host execution operator-gated via `PI_POC_ALLOW_LOCAL=1`) → confirm on exit 0 + marker; `control_path` + `control_liveness_marker` REQUIRED for every promotion |
+| `PromoteFinding` | Phase 1: PoC 2× target + 1× operator-approved control, then DNS-pinned harness-owned replay requiring conclusive `target_only`; optional reflection canary upgrades the recorded proof strength when observed only on target. `local:true` and private replay are operator-gated; blind/OOB proof fails closed without source separation |
+| `ConfirmFinding` | Phase 2: main-agent-only semantic decision plus a fresh harness-owned target/control replay (CONFIRMED promotes; NOT_CONFIRMED keeps investigating; worker calls are rejected) |
 | `CaseGet` / `CaseList` / `CaseSearch` | Read / filter / search |
 | `CaseLink` / `CaseUnlink` | Bidirectional exploit chains |
 | `ChainSuggest` | Scan cases for exploitable chain combinations (credential+endpoint→ATO, redirect+OAuth→token theft, XSS+state-change→CSRF, IDOR+user-data, SSTI→RCE, race+payment, info-disclosure+SSRF), ranked by confidence |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xaccefy/pi-casefile",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "Offensive security case tracker for Pi Agent — bug bounties, CTFs, security audits",
   "keywords": [
     "pi-package",
@@ -15,12 +15,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/x4cc3/pi-xpi.git",
+    "url": "git+https://github.com/xaccefy/pi-xpi.git",
     "directory": "packages/pi-casefile"
   },
-  "homepage": "https://github.com/x4cc3/pi-xpi/tree/main/packages/pi-casefile#readme",
+  "homepage": "https://github.com/xaccefy/pi-xpi/tree/main/packages/pi-casefile#readme",
   "bugs": {
-    "url": "https://github.com/x4cc3/pi-xpi/issues"
+    "url": "https://github.com/xaccefy/pi-xpi/issues"
   },
   "scripts": {
     "test": "bun test test",
@@ -32,6 +32,11 @@
   },
   "files": [
     "src/index.ts",
+    "src/evidence.ts",
+    "src/harness-verify.ts",
+    "src/safe-state.ts",
+    "src/ledger-worker.ts",
+    "src/ledger-worker-entry.ts",
     "src/ledger.ts",
     "src/workflow.ts",
     "src/poc-runner.ts",
@@ -43,6 +48,10 @@
     "LICENSE"
   ],
   "main": "src/index.ts",
+  "dependencies": {
+    "@xaccefy/pi-shared": "0.9.1",
+    "undici": "^8.9.0"
+  },
   "pi": {
     "extensions": [
       "./src/index.ts"

package/skills/casefile/SKILL.md

@@ -13,7 +13,7 @@ Use Casefile to maintain durable security investigation state across agent turns
 1. Check existing cases before opening a new one with CaseList or CaseSearch.
 2. Open new leads with CaseAdd as `hypothesis` or `investigating`.
 3. Promote cases with CaseUpdate only after materially new evidence, proof, impact, blockers, remediation, or status changes.
-4. Mark `confirmed` only via PromoteFinding after a real PoC exit 0 (evidence, impact, severity, poc required).
+4. Mark `confirmed` only via the two-phase gate — `PromoteFinding` (PoC 2× target + 1× operator-approved control, nonce-bound body evidence, then a DNS-pinned conclusive `target_only` replay; use the post-PoC harness-generated canary for reflection-capable requests) → the main agent personally reviews → `ConfirmFinding`, which captures a fresh second harness replay before commit. Never delegate phase 2; worker calls are rejected. Exit zero is run integrity, never vulnerability proof. A predicate differential is evidence, not an automatic exploit verdict. Blind/OOB findings remain investigating without a source-separated oracle.
 5. Use CaseLink and CaseUnlink for exploit chains. Do not edit linked case IDs directly.
 6. Use CaseContext only for confirmed or already reported cases: it writes the full context bundle (complete record, verification logs, links, pipeline artifacts) and records the report path. Then have the report written (reporter agent in the full pipeline; yourself in lite mode) and CaseUpdate status=`reported`.
 7. Use `killed` for disproven, duplicate, or dead-end leads, and include evidence, blockers, next step, or assumptions explaining why.
@@ -27,14 +27,15 @@ hypothesis → investigating → confirmed → reported
 ```
 
 - investigating requires evidence + confidence
-- confirmed requires PromoteFinding (not CaseUpdate)
+- confirmed requires PromoteFinding + ConfirmFinding (never CaseUpdate)
 - killed/reported are terminal (no field edits or re-links)
 
 ## Tool Map
 
 - `CaseAdd`: create a new case.
 - `CaseUpdate`: update an existing case.
-- `PromoteFinding`: run an on-disk PoC script (Docker sandbox or local) and promote a case to confirmed on exit 0.
+- `PromoteFinding`: phase 1 — require a body predicate, bind the verify URL, pin DNS, and send the same request to target and an operator-approved `PI_POC_CONTROL_TARGETS` control. Both responses must be conclusive and only `target_only` passes. For reflection, place `{{PI_POC_CANARY}}` exactly once in the request and declare `verify.canary`; the harness creates the secret after the PoC exits and requires target-only reflection. Network/private access remains operator-gated; OOB fails closed without source separation.
+- `ConfirmFinding`: phase 2 — main-agent-only review and fresh harness replay before commit (CONFIRMED promotes; NOT_CONFIRMED keeps investigating; worker/subagent calls are rejected). Record `canary_assessment=verified` when requested, otherwise `not_applicable` with a concrete reason.
 - `CaseGet`: read one case by ID.
 - `CaseList`: list cases with filters and pagination.
 - `CaseSearch`: search all fields or a scoped field.

package/src/evidence.ts

@@ -0,0 +1,501 @@
+/**
+ * Evidence contract for PoC confirmation.
+ *
+ * A PoC must write `evidence.json` into $PI_POC_EVIDENCE_DIR: a nonce-bound,
+ * schema-validated record of what it claims and the request spec the harness
+ * executes against both target and control. The harness validates the file,
+ * binds it to the run via $PI_POC_NONCE, and acquires the responses itself.
+ * The main/coordinator agent remains the semantic reviewer after the machine differential.
+ *
+ * Exit zero is required run integrity, but never vulnerability proof.
+ */
+
+// ── PoC evidence (written by the PoC script) ────────────────────────
+
+export type VerifyExpect = {
+  /** Acceptable HTTP statuses for the verify request. */
+  status?: number[];
+  /** Substrings the verify response must contain. */
+  body_contains?: string[];
+  /** Regexes the verify response must match. */
+  body_regex?: string[];
+};
+
+/** Replaced only inside the harness replay, after the PoC process has exited. */
+export const POC_CANARY_PLACEHOLDER = "{{PI_POC_CANARY}}";
+
+export type VerifyCanary = {
+  /** Reflection is machine-checked: target must return the fresh token and control must not. */
+  mode: "reflection";
+  /** Fixed literal; callers cannot choose or predict the harness-generated token. */
+  placeholder: typeof POC_CANARY_PLACEHOLDER;
+};
+
+export type PoCEvidence = {
+  /** Must equal the run's PI_POC_NONCE (harness-verified). */
+  nonce: string;
+  /** What the exploit asserts, e.g. "read /etc/passwd of target". */
+  claim: string;
+  /** Request spec the harness executes in phase 1 and again from the main-agent phase-2 call. */
+  verify: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+    expect: VerifyExpect;
+    /** Optional stronger causality dimension, independent of the authored predicate. */
+    canary?: VerifyCanary;
+  };
+  /** What the script itself saw — corroboration only, never proof. */
+  observations: string[];
+  /** Optional baseline request for the main agent's differential review. */
+  baseline?: {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+    body_contains?: string[];
+  };
+};
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+const MAX_CLAIM_CHARS = 2_000;
+const MAX_URL_CHARS = 4_096;
+const MAX_REQUEST_BODY_CHARS = 128 * 1024;
+const MAX_HEADERS = 64;
+const MAX_HEADER_CHARS = 8 * 1024;
+const MAX_EXPECT_VALUES = 16;
+const MAX_EXPECT_CHARS = 1_024;
+const MAX_REGEX_VALUES = 8;
+const MAX_REGEX_CHARS = 512;
+const MAX_OBSERVATIONS = 64;
+const MAX_OBSERVATION_CHARS = 4_096;
+const FORBIDDEN_REQUEST_HEADERS = new Set([
+  "connection",
+  "content-length",
+  "host",
+  "keep-alive",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function nonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+function boundedStringArray(v: unknown, maxItems: number, maxChars: number): v is string[] {
+  return (
+    Array.isArray(v) &&
+    v.length <= maxItems &&
+    v.every((x) => nonEmptyString(x) && x.length <= maxChars)
+  );
+}
+
+/** Bounded RFC-token header map with no CR/LF (injection/resource guard). */
+function headerRecord(v: unknown): v is Record<string, string> {
+  if (!isRecord(v)) return false;
+  const entries = Object.entries(v);
+  return (
+    entries.length <= MAX_HEADERS &&
+    entries.every(
+      ([key, value]) =>
+        /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(key) &&
+        !FORBIDDEN_REQUEST_HEADERS.has(key.toLowerCase()) &&
+        key.length <= 256 &&
+        typeof value === "string" &&
+        value.length <= MAX_HEADER_CHARS &&
+        !/[\r\n]/.test(value),
+    )
+  );
+}
+
+/** http(s) URL with a non-empty host — prefix-only matches would accept garbage. */
+function httpUrl(v: unknown): v is string {
+  if (!nonEmptyString(v) || v.length > MAX_URL_CHARS) return false;
+  let parsed: URL;
+  try {
+    parsed = new URL(v);
+  } catch {
+    return false;
+  }
+  return (
+    (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.hostname.length > 0
+  );
+}
+
+/** body_regex entries must compile — evaluation is isolated and time-bounded by the harness. */
+function validRegexArray(v: unknown): v is string[] {
+  return (
+    boundedStringArray(v, MAX_REGEX_VALUES, MAX_REGEX_CHARS) &&
+    v.every((re) => {
+      try {
+        new RegExp(re);
+        return true;
+      } catch {
+        return false;
+      }
+    })
+  );
+}
+
+function hasMeaningfulExpectation(expect: Record<string, unknown>): boolean {
+  return [expect.status, expect.body_contains, expect.body_regex].some(
+    (value) => Array.isArray(value) && value.length > 0,
+  );
+}
+
+function hasBodyExpectation(expect: Record<string, unknown>): boolean {
+  return [expect.body_contains, expect.body_regex].some(
+    (value) => Array.isArray(value) && value.length > 0,
+  );
+}
+
+/** Reject predicates that are structurally incapable of carrying useful proof. */
+function hasDiscriminatingBodyExpectation(expect: Record<string, unknown>): boolean {
+  const contains = Array.isArray(expect.body_contains) ? expect.body_contains : [];
+  if (contains.some((value) => typeof value === "string" && value.trim().length >= 4)) {
+    return true;
+  }
+  const regexes = Array.isArray(expect.body_regex) ? expect.body_regex : [];
+  return regexes.some(
+    (pattern) =>
+      typeof pattern === "string" &&
+      // Require a literal alphabetic anchor, e.g. `root:\\S+` or `is_admin`.
+      // Patterns such as `.`, `.*`, or `\\d+` match broad response classes and
+      // cannot independently identify the claimed vulnerability effect.
+      /[A-Za-z]{4,}/.test(pattern.replace(/\\[dDsSwWbB]/g, "")),
+  );
+}
+
+function countOccurrences(value: string, needle: string): number {
+  return value.split(needle).length - 1;
+}
+
+/**
+ * Parse + validate a PoC's evidence.json. Returns the validated object or a
+ * field-level error. Deliberately strict: an invalid evidence file means the
+ * run failed the contract, which blocks promotion.
+ */
+export function parsePoCEvidence(
+  raw: unknown,
+): { ok: true; evidence: PoCEvidence } | { ok: false; error: string } {
+  if (!isRecord(raw)) return { ok: false, error: "evidence.json must be a JSON object" };
+  if (!nonEmptyString(raw.nonce)) return { ok: false, error: "evidence.json missing nonce" };
+  if (raw.nonce.length > 256) return { ok: false, error: "evidence.json nonce is too long" };
+  if (!nonEmptyString(raw.claim)) return { ok: false, error: "evidence.json missing claim" };
+  if (raw.claim.length > MAX_CLAIM_CHARS) {
+    return { ok: false, error: `evidence.json claim exceeds ${MAX_CLAIM_CHARS} characters` };
+  }
+  const verify = raw.verify;
+  if (!isRecord(verify)) return { ok: false, error: "evidence.json verify must be an object" };
+  if (!nonEmptyString(verify.method) || !HTTP_METHODS.includes(verify.method.toUpperCase())) {
+    return {
+      ok: false,
+      error: `evidence.json verify.method must be one of ${HTTP_METHODS.join("|")}`,
+    };
+  }
+  if (!httpUrl(verify.url)) {
+    return { ok: false, error: "evidence.json verify.url must be an http(s) URL with a host" };
+  }
+  if (verify.headers !== undefined && !headerRecord(verify.headers)) {
+    return {
+      ok: false,
+      error:
+        "evidence.json verify.headers must be bounded valid end-to-end HTTP headers; authority, framing, proxy, and hop-by-hop headers are forbidden",
+    };
+  }
+  if (
+    verify.body !== undefined &&
+    (typeof verify.body !== "string" || verify.body.length > MAX_REQUEST_BODY_CHARS)
+  ) {
+    return {
+      ok: false,
+      error: `evidence.json verify.body must be a string no longer than ${MAX_REQUEST_BODY_CHARS} characters`,
+    };
+  }
+  if (verify.canary !== undefined) {
+    if (
+      !isRecord(verify.canary) ||
+      verify.canary.mode !== "reflection" ||
+      verify.canary.placeholder !== POC_CANARY_PLACEHOLDER
+    ) {
+      return {
+        ok: false,
+        error: `evidence.json verify.canary must be {"mode":"reflection","placeholder":"${POC_CANARY_PLACEHOLDER}"}`,
+      };
+    }
+    const canaryLocations = [
+      verify.url,
+      typeof verify.body === "string" ? verify.body : "",
+      ...(isRecord(verify.headers)
+        ? Object.values(verify.headers).filter(
+            (value): value is string => typeof value === "string",
+          )
+        : []),
+    ];
+    const count = canaryLocations.reduce(
+      (total, value) => total + countOccurrences(value, POC_CANARY_PLACEHOLDER),
+      0,
+    );
+    if (count !== 1) {
+      return {
+        ok: false,
+        error: `evidence.json verify.canary requires exactly one ${POC_CANARY_PLACEHOLDER} placeholder across url, body, or header values (got ${count})`,
+      };
+    }
+  }
+  const expect = verify.expect;
+  if (!isRecord(expect))
+    return { ok: false, error: "evidence.json verify.expect must be an object" };
+  if (
+    expect.status !== undefined &&
+    (!Array.isArray(expect.status) ||
+      expect.status.length === 0 ||
+      expect.status.length > MAX_EXPECT_VALUES ||
+      !expect.status.every((s) => Number.isInteger(s) && s >= 100 && s <= 599))
+  ) {
+    return {
+      ok: false,
+      error: "evidence.json verify.expect.status must be a non-empty array of HTTP status codes",
+    };
+  }
+  if (
+    expect.body_contains !== undefined &&
+    !boundedStringArray(expect.body_contains, MAX_EXPECT_VALUES, MAX_EXPECT_CHARS)
+  ) {
+    return {
+      ok: false,
+      error: `evidence.json verify.expect.body_contains must have at most ${MAX_EXPECT_VALUES} non-empty strings of at most ${MAX_EXPECT_CHARS} characters`,
+    };
+  }
+  if (expect.body_regex !== undefined && !validRegexArray(expect.body_regex)) {
+    return {
+      ok: false,
+      error: `evidence.json verify.expect.body_regex must have at most ${MAX_REGEX_VALUES} compilable patterns of at most ${MAX_REGEX_CHARS} characters`,
+    };
+  }
+  if (!hasMeaningfulExpectation(expect)) {
+    return {
+      ok: false,
+      error:
+        "evidence.json verify.expect must contain at least one non-empty status, body_contains, or body_regex assertion",
+    };
+  }
+  if (!hasBodyExpectation(expect)) {
+    return {
+      ok: false,
+      error:
+        "evidence.json verify.expect needs a non-empty body_contains or body_regex assertion; status-only differences are not vulnerability proof",
+    };
+  }
+  if (!hasDiscriminatingBodyExpectation(expect)) {
+    return {
+      ok: false,
+      error:
+        "evidence.json verify.expect needs a discriminating body predicate: body_contains must include at least 4 characters or body_regex must include a literal alphabetic anchor; trivial matchers are not vulnerability proof",
+    };
+  }
+  if (
+    !Array.isArray(raw.observations) ||
+    raw.observations.length > MAX_OBSERVATIONS ||
+    !raw.observations.every((o) => typeof o === "string" && o.length <= MAX_OBSERVATION_CHARS)
+  ) {
+    return { ok: false, error: "evidence.json observations exceed the bounded string-array limit" };
+  }
+  if (raw.baseline !== undefined) {
+    const b = raw.baseline;
+    if (!isRecord(b)) return { ok: false, error: "evidence.json baseline must be an object" };
+    if (
+      !nonEmptyString(b.method) ||
+      !HTTP_METHODS.includes(b.method.toUpperCase()) ||
+      !httpUrl(b.url)
+    ) {
+      return {
+        ok: false,
+        error: "evidence.json baseline needs an http(s) url and a valid HTTP method",
+      };
+    }
+    if (b.headers !== undefined && !headerRecord(b.headers)) {
+      return {
+        ok: false,
+        error:
+          "evidence.json baseline.headers must be bounded valid end-to-end HTTP headers; authority, framing, proxy, and hop-by-hop headers are forbidden",
+      };
+    }
+    if (
+      b.body !== undefined &&
+      (typeof b.body !== "string" || b.body.length > MAX_REQUEST_BODY_CHARS)
+    ) {
+      return {
+        ok: false,
+        error: `evidence.json baseline.body must be no longer than ${MAX_REQUEST_BODY_CHARS} characters`,
+      };
+    }
+    if (
+      b.body_contains !== undefined &&
+      !boundedStringArray(b.body_contains, MAX_EXPECT_VALUES, MAX_EXPECT_CHARS)
+    ) {
+      return { ok: false, error: "evidence.json baseline.body_contains exceeds limits" };
+    }
+  }
+  return { ok: true, evidence: raw as unknown as PoCEvidence };
+}
+
+/** Bind evidence to its run: the nonce must equal the harness-generated one. */
+export function evidenceNonceMatches(evidence: PoCEvidence, nonce: string): boolean {
+  return evidence.nonce === nonce;
+}
+
+/**
+ * The comparator for determinism + differential checks. Strips the nonce
+ * (per-run by design) and observations (free-form, run-dependent) — the
+ * load-bearing shape is claim + verify + baseline.
+ */
+export function normalizeEvidence(e: PoCEvidence): string {
+  return JSON.stringify({ claim: e.claim, verify: e.verify, baseline: e.baseline });
+}
+
+// ── Main-agent confirmation verdict ─────────────────────────────────
+
+export const CONFIRM_VERDICT_VALUES = ["CONFIRMED", "NOT_CONFIRMED"] as const;
+export type ConfirmVerdict = (typeof CONFIRM_VERDICT_VALUES)[number];
+
+export const CONFIRM_DIFFERENTIAL_VALUES = [
+  "target_only",
+  "both",
+  "control_only",
+  "unclear",
+] as const;
+export type ConfirmDifferential = (typeof CONFIRM_DIFFERENTIAL_VALUES)[number];
+
+export const SEVERITY_MATCH_VALUES = ["under", "over", "ok"] as const;
+export const CANARY_ASSESSMENT_VALUES = ["verified", "not_applicable"] as const;
+
+export type MainAgentVerdict = {
+  verdict: ConfirmVerdict;
+  reasoning: string;
+  /** Files/evidence the main agent actually reviewed. */
+  evidence_reviewed: string[];
+  /** What the main agent observed during its review and fresh harness replay. */
+  re_execution_note?: string;
+  /** Target vs control evidence comparison. CONFIRMED requires target_only. */
+  differential: ConfirmDifferential;
+  /** Claimed severity vs what the evidence shows. */
+  severity_match?: (typeof SEVERITY_MATCH_VALUES)[number];
+  /** The main agent's own failed attempt to disprove — becomes the case's disconfirmation. */
+  disconfirmation_attempt?: string;
+  /** Whether the machine replay carried a harness-generated causal canary. */
+  canary_assessment?: (typeof CANARY_ASSESSMENT_VALUES)[number];
+  /** Why no meaningful canary oracle exists for this exploit class. */
+  canary_reason?: string;
+  /** Which model judged (recorded for the accuracy ledger). */
+  model?: string;
+};
+
+/**
+ * Validate the main-agent verdict. CONFIRMED additionally requires a target-only
+ * differential, a concrete review note, and a disconfirmation attempt. The
+ * ledger separately requires a fresh harness-owned phase-2 replay; there is no
+ * caller-supplied `re_executed` checkbox.
+ */
+export function validateMainAgentVerdict(
+  raw: unknown,
+): { ok: true; verdict: MainAgentVerdict } | { ok: false; error: string } {
+  if (!isRecord(raw)) return { ok: false, error: "verdict must be a JSON object" };
+  if (!nonEmptyString(raw.verdict) || !CONFIRM_VERDICT_VALUES.includes(raw.verdict as never)) {
+    return {
+      ok: false,
+      error: `verdict must be one of ${CONFIRM_VERDICT_VALUES.join(" | ")}`,
+    };
+  }
+  if (!nonEmptyString(raw.reasoning)) return { ok: false, error: "verdict reasoning required" };
+  if (!Array.isArray(raw.evidence_reviewed) || raw.evidence_reviewed.length === 0) {
+    return { ok: false, error: "verdict evidence_reviewed must be a non-empty array" };
+  }
+  if (!raw.evidence_reviewed.every((e) => typeof e === "string")) {
+    return { ok: false, error: "verdict evidence_reviewed entries must be strings" };
+  }
+  if (raw.re_execution_note !== undefined && !nonEmptyString(raw.re_execution_note)) {
+    return { ok: false, error: "verdict re_execution_note must be a non-empty string" };
+  }
+  if (
+    !nonEmptyString(raw.differential) ||
+    !CONFIRM_DIFFERENTIAL_VALUES.includes(raw.differential as never)
+  ) {
+    return {
+      ok: false,
+      error: `verdict differential must be one of ${CONFIRM_DIFFERENTIAL_VALUES.join(" | ")}`,
+    };
+  }
+  if (
+    raw.canary_assessment !== undefined &&
+    !CANARY_ASSESSMENT_VALUES.includes(raw.canary_assessment as never)
+  ) {
+    return {
+      ok: false,
+      error: `verdict canary_assessment must be one of ${CANARY_ASSESSMENT_VALUES.join(" | ")}`,
+    };
+  }
+  if (raw.canary_reason !== undefined && !nonEmptyString(raw.canary_reason)) {
+    return { ok: false, error: "verdict canary_reason must be a non-empty string" };
+  }
+  if (
+    raw.severity_match !== undefined &&
+    !SEVERITY_MATCH_VALUES.includes(raw.severity_match as never)
+  ) {
+    return {
+      ok: false,
+      error: `verdict severity_match must be one of ${SEVERITY_MATCH_VALUES.join(" | ")}`,
+    };
+  }
+  if (raw.verdict === "CONFIRMED") {
+    if (raw.differential !== "target_only") {
+      return {
+        ok: false,
+        error:
+          'CONFIRMED requires differential "target_only" — the control run must not demonstrate the claimed impact',
+      };
+    }
+    if (!nonEmptyString(raw.re_execution_note)) {
+      return {
+        ok: false,
+        error:
+          "CONFIRMED requires re_execution_note — record what the main agent observed during review and the fresh harness replay",
+      };
+    }
+    if (!nonEmptyString(raw.disconfirmation_attempt)) {
+      return {
+        ok: false,
+        error:
+          "CONFIRMED requires disconfirmation_attempt — the main agent's own failed attempt to disprove",
+      };
+    }
+    if (!CANARY_ASSESSMENT_VALUES.includes(raw.canary_assessment as never)) {
+      return {
+        ok: false,
+        error: `CONFIRMED requires canary_assessment (${CANARY_ASSESSMENT_VALUES.join(" | ")})`,
+      };
+    }
+    if (raw.canary_assessment === "not_applicable" && !nonEmptyString(raw.canary_reason)) {
+      return {
+        ok: false,
+        error: "CONFIRMED with canary_assessment not_applicable requires canary_reason",
+      };
+    }
+  }
+  return { ok: true, verdict: raw as unknown as MainAgentVerdict };
+}
+
+/** @deprecated Compatibility alias for integrations built before phase 2 became main-agent-only. */
+export type ConfirmerVerdict = MainAgentVerdict;
+
+/** @deprecated Use validateMainAgentVerdict. */
+export const validateConfirmerVerdict = validateMainAgentVerdict;