@xaccefy/pi-casefile 0.9.0 → 0.9.2

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * Casefile — offensive security case tracker for Pi.
  *
- * Tools: CaseAdd, CaseUpdate, PromoteFinding, EvidenceAdd, CoverageAdd, CoverageReport, ChainSuggest, CaseGet, CaseList, CaseSearch, CaseLink, CaseUnlink, CaseContext, PipelineSubmit, ScratchpadInit, ScratchpadResume, ScratchpadCheckpoint, ScratchpadWrite, ScratchpadRead, ScratchpadPhaseDone, ScratchpadClear
+ * Tools: CaseAdd, CaseUpdate, PromoteFinding, ConfirmFinding, EvidenceAdd, CoverageAdd, CoverageReport, ChainSuggest, CaseGet, CaseList, CaseSearch, CaseLink, CaseUnlink, CaseContext, PipelineSubmit, ScratchpadInit, ScratchpadResume, ScratchpadCheckpoint, ScratchpadWrite, ScratchpadRead, ScratchpadPhaseDone, ScratchpadClear
  * Command: /casefile — interactive dashboard
  * Event: before_agent_start — injects cyber workflow once per session, refreshes the active case list per prompt
  */
@@ -9,15 +9,17 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { type TSchema, Type } from "typebox";
 import {
+  CANARY_ASSESSMENT_VALUES,
   CONFIRM_DIFFERENTIAL_VALUES,
   CONFIRM_VERDICT_VALUES,
-  type ConfirmerVerdict,
   SEVERITY_MATCH_VALUES,
+  validateMainAgentVerdict,
 } from "./evidence.ts";
+import { controlTargetAuthorizationError, replayDifferential } from "./harness-verify.ts";
 import {
   addCaseResult,
   addEvidenceItemResult,
@@ -47,6 +49,7 @@ import {
   getCasefilePath,
   LINK_KIND_VALUES,
   linkCasesResult,
+  type MainAgentVerification,
   type PendingConfirmation,
   type PocEvidenceRun,
   PRIORITY_VALUES,
@@ -58,16 +61,15 @@ import {
   STATUS_VALUES,
   searchCases,
   storePendingConfirmation,
-  suggestChains,
   unlinkCasesResult,
   updateCaseResult,
-  writeCaseContext,
 } from "./ledger.ts";
+import { suggestChainsAsync, writeCaseContextAsync } from "./ledger-worker.ts";
 import { pipeline_submit, SUBMIT_STAGES, type SubmitStage } from "./pipeline-submit.ts";
 import { type PocRun, type PocRunOptions, runPoc } from "./poc-runner.ts";
 import {
   detectWorkspaceRoot,
-  PHASE_ORDER,
+  SCRATCHPAD_PHASES,
   type ScratchpadPhase,
   type ScratchpadResume,
   scratchpad_checkpoint,
@@ -167,8 +169,7 @@ const EvidenceAddSchema = Type.Object(
     artifact_path: Type.Optional(
       Type.String({
         description:
-          "Path to the artifact file on disk. Stored as basename + SHA-256 hash " +
-          "(full path is never persisted).",
+          "Path to a regular, non-symlink artifact inside the workspace. The bytes are copied durably and stored as basename + SHA-256 (full source path is never persisted).",
       }),
     ),
   },
@@ -177,12 +178,13 @@ const EvidenceAddSchema = Type.Object(
 
 // ── Tool: PromoteFinding (phase 1) / ConfirmFinding (phase 2) ──────────
 //
-// Confirmation is TWO-PHASE because tools cannot dispatch subagents: the
-// coordinator runs PromoteFinding (harness runs the PoC 2x + control,
-// validates nonce-bound evidence.json, records the bundle), dispatches the
-// confirmer subagent (fresh context, re-executes the verify request), then
-// commits the verdict via ConfirmFinding. Exit codes and markers are
-// diagnostics — the gate is evidence + verdict.
+// Confirmation is TWO-PHASE and main-agent-owned: PromoteFinding runs the PoC
+// 2x + control, validates nonce-bound evidence.json, and records the pending
+// bundle; ConfirmFinding then performs the main coordinator's review/replay and
+// commits or refuses the verdict. Subagents may gather or challenge evidence,
+// but they cannot run validation or confirmation gates. Zero exit is necessary
+// run integrity and markers are diagnostic only; the machine records
+// predicate/canary differentials and the main agent owns the semantic judgment.
 
 const PromoteSchema = Type.Object(
   {
@@ -190,19 +192,27 @@ const PromoteSchema = Type.Object(
     poc_path: Type.String({
       description: "Absolute path to the PoC script on disk",
     }),
-    control_path: Type.String({
-      description:
-        "REQUIRED: absolute path to the SAME script as poc_path (sha256-equality is ENFORCED). The harness runs it with PI_POC_MODE=control and PI_POC_TARGET=control_target.",
-    }),
+    control_path: Type.Optional(
+      Type.String({
+        description:
+          "Optional absolute path to the SAME script as poc_path (sha256-equality is ENFORCED). Defaults to poc_path. The harness runs it with PI_POC_MODE=control and PI_POC_TARGET=control_target.",
+      }),
+    ),
     control_target: Type.String({
       minLength: 1,
       description:
-        "REQUIRED: a distinct baseline target that lacks the vulnerability (patched replica, second account, baseline endpoint).",
+        "REQUIRED: a distinct baseline target that lacks the vulnerability and is operator-approved through PI_POC_CONTROL_TARGETS (patched replica, second account, baseline service).",
     }),
     local: Type.Optional(
       Type.Boolean({
         description:
-          "Run with network access (Docker sandbox with --network host — still read-only FS, dropped capabilities, unprivileged user) instead of the isolated --network none sandbox. True host execution is NOT agent-selectable: it requires the operator to set PI_POC_ALLOW_LOCAL=1, and is used only as a fallback when Docker is unavailable.",
+          "Run with network access instead of --network none. Requires operator authorization via PI_POC_ALLOW_NETWORK=1. True host fallback additionally requires PI_POC_ALLOW_LOCAL=1.",
+      }),
+    ),
+    oob: Type.Optional(
+      Type.Boolean({
+        description:
+          "Reserved for source-separated out-of-band verification. Currently fails closed because a loopback listener reachable by the PoC cannot prove target causation.",
       }),
     ),
   },
@@ -219,14 +229,13 @@ const ConfirmSchema = Type.Object(
           description: "Why the evidence does or does not demonstrate the claim",
         }),
         evidence_reviewed: Type.Array(Type.String(), {
-          description: "Files/evidence the confirmer actually reviewed",
-        }),
-        re_executed: Type.Boolean({
-          description:
-            "True iff the confirmer re-sent the verify request itself. Mandatory for CONFIRMED.",
+          description: "Files/evidence the main agent actually reviewed",
         }),
         re_execution_note: Type.Optional(
-          Type.String({ description: "What the confirmer observed when re-executing" }),
+          Type.String({
+            description:
+              "What the main agent observed during review and the fresh harness-owned target/control replay. Mandatory for CONFIRMED.",
+          }),
         ),
         differential: Type.String({
           enum: [...CONFIRM_DIFFERENTIAL_VALUES],
@@ -241,7 +250,20 @@ const ConfirmSchema = Type.Object(
         disconfirmation_attempt: Type.Optional(
           Type.String({
             description:
-              "The confirmer's own failed attempt to disprove — becomes the case's disconfirmation",
+              "The main agent's own failed attempt to disprove — becomes the case's disconfirmation",
+          }),
+        ),
+        canary_assessment: Type.Optional(
+          Type.String({
+            enum: [...CANARY_ASSESSMENT_VALUES],
+            description:
+              "verified when the replay carried a harness-generated reflection canary; otherwise not_applicable with a concrete reason",
+          }),
+        ),
+        canary_reason: Type.Optional(
+          Type.String({
+            description:
+              "Why a causal reflection canary is not meaningful for this exploit class. Required when canary_assessment=not_applicable.",
           }),
         ),
         model: Type.Optional(
@@ -335,9 +357,9 @@ const UnlinkSchema = Type.Object(
 // artifacts; it does not re-run completed phases (idempotent).
 
 const ScratchpadPhaseSchema = Type.String({
-  enum: [...PHASE_ORDER],
+  enum: [...SCRATCHPAD_PHASES],
   description:
-    "Pipeline phase: recon | hunt | gapfil | trace | skeptic | validate | chain | patch | report",
+    "Pipeline phase: recon | hunt | trace | skeptic | validate | chain | patch | report (legacy gapfil is accepted for older runs)",
 });
 
 /** run_id-only schema, shared by Scratchpad Init / Resume / Clear. */
@@ -676,13 +698,13 @@ export function detectHost(): "omp" | "pi" {
  * case list DOES change as cases are added, so it is refreshed every prompt.
  *
  * mode selects the workflow text: "lite" injects the single-agent workflow
- * (no subagent dispatch), anything else gets the full subagent pipeline,
+ * (no subagent dispatch), "swarm" gets the full subagent pipeline,
  * rendered for the host's dispatch convention (pi-subagents vs OMP task).
  */
 function buildAgentInjection(
   active: CaseRecord[],
   includeWorkflow: boolean,
-  mode: XpMode = "on",
+  mode: XpMode = "swarm",
 ): string {
   const caseList = buildCaseListContext(active);
   if (!includeWorkflow) return caseList;
@@ -699,13 +721,15 @@ function buildAgentInjection(
 // ── XP (offensive / exploit) mode toggle ─────────────────────────────
 // Casefile historically injected the cyber workflow into every prompt.
 // For normal dev work that is just noise, so XP mode defaults OFF. Enable
-// it for offensive/audit sessions to get the full attacker discipline back,
-// or lite for the single-agent variant (no subagent dispatch). Toggle with
-// /xp (or /xp on|off|lite); override per-session with PI_XP_MODE.
+// swarm for the bounded multi-agent variant, or lite for the single-agent
+// attacker discipline. Toggle with /xp (off <-> swarm), or set explicitly with
+// /xp on|lite|swarm|off. "on" means the default enabled SWARM mode; use "lite"
+// for no subagent dispatch.
+// Override per-session with PI_XP_MODE.
 // Pure helpers exported for unit tests.
 
 export const XP_MODE_ENV = "PI_XP_MODE";
-export type XpMode = "on" | "off" | "lite";
+export type XpMode = "swarm" | "off" | "lite";
 
 export function getXpModeStatePath(): string {
   return join(dirname(getCasefilePath()), "xp-mode");
@@ -716,13 +740,14 @@ export function readXpMode(
   statePath: string = getXpModeStatePath(),
 ): XpMode {
   const env = (envValue ?? "").trim().toLowerCase();
-  if (env === "on" || env === "1" || env === "true") return "on";
+  if (env === "swarm") return "swarm";
+  if (env === "on" || env === "1" || env === "true") return "swarm";
   if (env === "lite") return "lite";
   if (env === "off" || env === "0" || env === "false") return "off";
   try {
     if (existsSync(statePath)) {
       const v = readFileSync(statePath, "utf8").trim().toLowerCase();
-      if (v === "on") return "on";
+      if (v === "swarm" || v === "on") return "swarm";
       if (v === "lite") return "lite";
       if (v === "off") return "off";
     }
@@ -742,16 +767,22 @@ export function writeXpMode(state: XpMode, statePath: string = getXpModeStatePat
 
 export function parseXpModeArg(args: string, current: XpMode): XpMode {
   const arg = (args ?? "").trim().toLowerCase();
-  if (arg === "on") return "on";
+  if (arg === "swarm") return "swarm";
+  if (arg === "on") return "swarm";
   if (arg === "off") return "off";
   if (arg === "lite") return "lite";
-  // Bare /xp toggles between on and off (lite is only set explicitly).
-  return current === "on" ? "off" : "on";
+  // Bare /xp is the low-ceremony path: toggle the default XP workflow on/off.
+  return current === "off" ? "swarm" : "off";
 }
 
 // ── Main extension ────────────────────────────────────────────────────
 
 export default function casefileExtension(pi: ExtensionAPI) {
+  // Process role is immutable for this extension instance. A worker may spawn
+  // shells, but unsetting PI_SUBAGENT_CHILD in a child shell cannot upgrade the
+  // already-loaded extension or reveal a tool that was omitted at startup.
+  const startedAsSubagent = process.env.PI_SUBAGENT_CHILD === "1";
+  const isSubagentProcess = () => startedAsSubagent || process.env.PI_SUBAGENT_CHILD === "1";
   // Pin the workspace root ONCE at extension load. Every scratchpad / pipeline
   // / PoC-path lookup otherwise re-walks the ambient cwd on each call — a
   // mid-session `cd` would split state across two .scratchpad roots and
@@ -761,34 +792,37 @@ export default function casefileExtension(pi: ExtensionAPI) {
   setScratchpadRoot(workspaceRoot);
   process.env.PI_POC_ROOT ??= workspaceRoot;
 
-  // ── Diagnostic Error Handler Middleware ──
-  const originalRegisterTool = pi.registerTool.bind(pi);
-  pi.registerTool = (spec: any) => {
+  // ── Diagnostic Error Handler ──
+  const registerCaseTool = <TParams extends TSchema, TDetails = unknown, TState = unknown>(
+    spec: ToolDefinition<TParams, TDetails, TState>,
+  ) => {
     const origExecute = spec.execute;
-    spec.execute = async (...args: any[]) => {
-      try {
-        return await origExecute(...args);
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        let hint = "";
-        if (
-          message.includes("SQLITE") ||
-          message.includes("database") ||
-          message.includes("permission") ||
-          message.includes("readonly") ||
-          message.includes("lock")
-        ) {
-          hint = `\n\nHint: A database access error occurred on the casefile SQLite ledger.\nTo troubleshoot:\n  1. Check filesystem read/write permissions for the database path: ${getCasefilePath()}.\n  2. If using a locked folder, you can override the ledger location by setting:\n     export PI_CASEFILE_PATH=/your/writable/directory/casefile.db`;
+    pi.registerTool({
+      ...spec,
+      execute: async (...args: Parameters<typeof origExecute>) => {
+        try {
+          return await origExecute(...args);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          let hint = "";
+          if (
+            message.includes("SQLITE") ||
+            message.includes("database") ||
+            message.includes("permission") ||
+            message.includes("readonly") ||
+            message.includes("lock")
+          ) {
+            hint = `\n\nHint: A database access error occurred on the casefile SQLite ledger.\nTo troubleshoot:\n  1. Check filesystem read/write permissions for the database path: ${getCasefilePath()}.\n  2. If using a locked folder, you can override the ledger location by setting:\n     export PI_CASEFILE_PATH=/your/writable/directory/casefile.db`;
+          }
+          throw new Error(`${spec.name} failed: ${message}${hint}`, { cause: err });
         }
-        throw new Error(`${spec.name} failed: ${message}${hint}`, { cause: err });
-      }
-    };
-    originalRegisterTool(spec);
+      },
+    });
   };
 
   // ── Tool: CaseAdd ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseAdd",
     label: "Add Case",
     description:
@@ -842,7 +876,7 @@ export default function casefileExtension(pi: ExtensionAPI) {
 
   // ── Tool: CaseUpdate ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseUpdate",
     label: "Update Case",
     description:
@@ -897,11 +931,11 @@ export default function casefileExtension(pi: ExtensionAPI) {
 
   // ── Tool: EvidenceAdd ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "EvidenceAdd",
     label: "Add Evidence Item",
     description:
-      "Record a role-typed, artifact-backed evidence item on a case (observation, reproduction, impact, refutation, cleanup). Artifact files are stored as basename + SHA-256 — the full path is never persisted. refutation items justify a kill; cleanup items track engagement cleanup before REPORT.",
+      "Record a role-typed, artifact-backed evidence item on a case. Artifact reads are restricted to regular, non-symlink files inside the workspace; bytes are copied durably and stored as basename + SHA-256. refutation items justify a kill; cleanup items track engagement cleanup before REPORT.",
     promptSnippet: "Record a role-typed evidence item",
     promptGuidelines: [
       "Use EvidenceAdd for artifact-backed evidence: raw responses, logs, screenshots, disproof attempts — anything a claim should trace back to.",
@@ -917,7 +951,8 @@ export default function casefileExtension(pi: ExtensionAPI) {
         summary: params.summary as string,
         artifactPath: params.artifact_path as string | undefined,
       });
-      const record = getCaseById(params.case_id as string)!;
+      const record = getCaseById(params.case_id as string);
+      if (!record) throw new Error(`Case not found after evidence insert: ${params.case_id}`);
       return {
         content: [
           {
@@ -990,7 +1025,7 @@ export default function casefileExtension(pi: ExtensionAPI) {
     { additionalProperties: false },
   );
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CoverageAdd",
     label: "Record Coverage",
     description:
@@ -1012,7 +1047,8 @@ export default function casefileExtension(pi: ExtensionAPI) {
         note: params.note as string,
         evidenceItemId: params.evidence_item_id as string | undefined,
       });
-      const record = getCaseById(params.case_id as string)!;
+      const record = getCaseById(params.case_id as string);
+      if (!record) throw new Error(`Case not found after coverage insert: ${params.case_id}`);
       return {
         content: [
           {
@@ -1056,11 +1092,11 @@ export default function casefileExtension(pi: ExtensionAPI) {
     { additionalProperties: false },
   );
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CoverageReport",
     label: "Coverage Matrix",
     description:
-      "Render the machine-checkable coverage matrix for a case: which (asset × attack-class) cells are tested, with wide-verdict propagation. Run before deciding the hunt/gapfill is done — the plateau stop (zero new classes testable) must be visible in the matrix, not asserted in prose.",
+      "Render the machine-checkable coverage matrix for a case: which (asset × attack-class) cells are tested, with wide-verdict propagation. Run before deciding HUNT coverage is done — the plateau stop (zero new classes testable) must be visible in the matrix, not asserted in prose.",
     promptSnippet: "Show which attack classes were tested where",
     promptGuidelines: [
       "Run CoverageReport before claiming 'every class is COVERED/SKIPPED/NOT_FOUND' — the claim must match the matrix.",
@@ -1103,259 +1139,347 @@ export default function casefileExtension(pi: ExtensionAPI) {
     },
   });
 
-  // ── Tool: PromoteFinding ──
   // ── Tool: PromoteFinding (phase 1) ──
 
-  pi.registerTool({
-    name: "PromoteFinding",
-    label: "Run PoC Evidence",
-    description:
-      "Phase 1 of confirmation: run the PoC twice against the case target plus once against control_target (same script, sha256-enforced), then validate the nonce-bound evidence.json each run writes to $PI_POC_EVIDENCE_DIR. Records a pending confirmation bundle (expires in 1h) and returns the confirmer dispatch instruction. Exit codes and markers are DIAGNOSTICS — the gate is evidence + confirmer verdict. After PromoteFinding: dispatch the confirmer subagent, then commit its verdict with ConfirmFinding. Host execution is never agent-selectable — local:true uses a host-network Docker sandbox; true host runs need PI_POC_ALLOW_LOCAL=1.",
-    promptSnippet: "Phase 1: run PoC evidence (target x2 + control) and record the pending bundle",
-    promptGuidelines: [
-      "Use PromoteFinding when an investigating case has a concrete PoC script on disk and you are ready to prove it.",
-      "Prerequisites: status='investigating' and non-empty poc, evidence, impact, severity, target, plus an artifact-backed EvidenceAdd 'observation' item on the case (the initial signal, with artifact_path). The disconfirmation comes from the confirmer at confirm time.",
-      "The PoC MUST write evidence.json to $PI_POC_EVIDENCE_DIR: { nonce (echo $PI_POC_NONCE), claim, verify: { method, url, expect: { status/body_contains/body_regex } }, observations }. The harness validates it and binds it to the run — missing/invalid/misnonced evidence blocks promotion.",
-      "control_path (REQUIRED): the SAME script as poc_path (sha256-equality is ENFORCED). The harness runs it with PI_POC_MODE=control and PI_POC_TARGET=control_target. The control's evidence must DIFFER from the target's (not target-dependent → blocked).",
-      "Default sandbox: docker run --rm --network none. Use local:true for network-dependent bugs (host-network sandbox; host execution needs operator PI_POC_ALLOW_LOCAL=1).",
-      "After the bundle is recorded, dispatch the confirmer subagent (agents/confirmer.md, fresh context, different model) and commit its verdict with ConfirmFinding. Never CaseUpdate status='confirmed' directly.",
-    ],
-    parameters: PromoteSchema,
-
-    async execute(_id, params, _signal, _onUpdate, _ctx) {
-      // Validate promotability BEFORE running the PoC — each sandboxed run can
-      // take 30s (plus first-time image pull), so fail cheap when the case
-      // can't advance anyway (missing, wrong status, missing required fields,
-      // missing artifact-backed observation evidence).
-      const caseId = params.id as string;
-      const current = assertPromotable(caseId);
-
-      const fail = (text: string, _extra?: Record<string, unknown>): never => {
-        throw new Error(text);
-      };
-
-      const controlPath = (params.control_path as string | undefined)?.trim() ?? "";
-      const controlTarget = (params.control_target as string | undefined)?.trim() ?? "";
-      if (!controlPath) {
-        return fail(
-          "control_path is REQUIRED: the SAME script as poc_path (sha256-equality is ENFORCED), run by the harness with PI_POC_MODE=control and PI_POC_TARGET=control_target.",
-          { missingControl: true },
-        );
-      }
-      if (!controlTarget) {
-        return fail(
-          "control_target is REQUIRED: a distinct baseline target that lacks the vulnerability.",
-          { missingControlTarget: true },
-        );
-      }
-      if (controlTarget === current.target) {
-        return fail(
-          "control_target must differ from the case target; a control run against the vulnerable target proves nothing.",
-          { controlTargetEqualsCaseTarget: true },
-        );
-      }
-
-      // Same-file contract (anti-cheat): control must be the SAME bytes as the
-      // PoC, differing only via the harness-set env. Check BEFORE any run.
-      const pocPath = (params.poc_path as string | undefined)?.trim() ?? "";
-      let pocHash: string | undefined;
-      let controlHash: string | undefined;
-      try {
-        pocHash = createHash("sha256").update(readFileSync(pocPath)).digest("hex");
-        controlHash = createHash("sha256").update(readFileSync(controlPath)).digest("hex");
-      } catch (e) {
-        return fail(
-          `Cannot read PoC/control scripts for the same-file check: ${(e as Error).message}`,
-          { sameFileCheckFailed: true },
-        );
-      }
-      if (pocHash !== controlHash) {
-        return fail(
-          "CONTROL CHECK FAILED: control_path must be the SAME script as poc_path (sha256 mismatch). Case remains investigating.",
-          { controlHashMismatch: true },
-        );
-      }
-
-      const runOptions = (pocMode: string, target: string): PocRunOptions => ({
-        network: params.local === true ? "host" : "none",
-        local: params.local === true,
-        env: { PI_POC_MODE: pocMode, PI_POC_TARGET: target },
-      });
+  if (!startedAsSubagent)
+    registerCaseTool({
+      name: "PromoteFinding",
+      label: "Run PoC Evidence",
+      description:
+        "Main-agent phase 1 of confirmation: run the same PoC twice against the case target and once against an operator-approved control_target, validate nonce-bound evidence.json with a response-body assertion, then have the harness execute one immutable HTTP request template against both target and control. control_path defaults to poc_path; if supplied, sha256 equality is enforced. The machine records a predicate differential, or a stronger canary differential when a reflection placeholder is requested and observed only on target; neither is automatically a vulnerability verdict. Exit 0 is necessary run integrity, never proof. Networked execution, controls, and private replay are operator-gated. Blind/OOB confirmation fails closed until source separation exists. Records a pending bundle for main-agent semantic review via ConfirmFinding. Worker/subagent processes are rejected.",
+      promptSnippet:
+        "Phase 1: run PoC evidence (target x2 + control) and record the pending bundle",
+      promptGuidelines: [
+        "Use PromoteFinding only from the main/coordinator agent when an investigating case has a concrete PoC script on disk and you are ready to subject its claim to the machine gate.",
+        "Prerequisites: status='investigating' and non-empty poc, evidence, impact, severity, target, plus an artifact-backed EvidenceAdd 'observation' item on the case (the initial signal, with artifact_path). The final disconfirmation comes from the main agent at confirm time.",
+        "The PoC MUST write evidence.json to $PI_POC_EVIDENCE_DIR: { nonce (echo $PI_POC_NONCE), claim, verify: { method, url, expect: { status?, body_contains/body_regex } }, observations }. A non-empty body predicate is mandatory; status-only evidence is rejected. verify.url must belong to the case target.",
+        "For reflection-capable requests, place {{PI_POC_CANARY}} exactly once in verify.url/body/header values and declare verify.canary={mode:'reflection',placeholder:'{{PI_POC_CANARY}}'}. The harness substitutes an unpredictable value only after the PoC exits and requires target-only reflection; the raw token is not persisted.",
+        "control_path is optional and defaults to poc_path; if supplied, it must be the SAME script as poc_path. control_target must be pre-approved by the operator in PI_POC_CONTROL_TARGETS. The harness derives the control request from the target request, changes only its origin, and applies the same predicates to two conclusive responses.",
+        "local:true requires PI_POC_ALLOW_NETWORK=1. Private/internal harness replay additionally requires PI_POC_ALLOW_PRIVATE_REPLAY=1. Neither silently falls back to a model verdict.",
+        "Blind/OOB classes are not promotable through the built-in loopback listener because the PoC can self-call it; obtain a direct-response or state oracle, otherwise keep the case investigating.",
+        "After the bundle is recorded, stay in the main agent: inspect the script/evidence, attempt disconfirmation, and call ConfirmFinding itself; that call performs a fresh harness-owned target/control replay. Never delegate validation/confirmation and never CaseUpdate status='confirmed' directly.",
+      ],
+      parameters: PromoteSchema,
+
+      async execute(_id, params, _signal, _onUpdate, _ctx) {
+        if (isSubagentProcess()) {
+          throw new Error(
+            "PromoteFinding is reserved for the main/coordinator agent. A worker or subagent may gather evidence but cannot run validation or create a promotion bundle.",
+          );
+        }
+        // Validate promotability BEFORE running the PoC — each sandboxed run can
+        // take 30s (plus first-time image pull), so fail cheap when the case
+        // can't advance anyway (missing, wrong status, missing required fields,
+        // missing artifact-backed observation evidence).
+        const caseId = params.id as string;
+        const current = assertPromotable(caseId);
+
+        const fail = (text: string, _extra?: Record<string, unknown>): never => {
+          throw new Error(text);
+        };
 
-      const caseTarget = current.target ?? "";
-      // Determinism: TWO target runs + one control run. Exit codes are
-      // diagnostics; completion, evidence validity, determinism, and the
-      // differential are the gate.
-      const run1 = runPoc(pocPath, runOptions("poc", caseTarget));
-      const run2 = runPoc(pocPath, runOptions("poc", caseTarget));
-      const controlRun = runPoc(controlPath, runOptions("control", controlTarget));
+        const pocPath = (params.poc_path as string | undefined)?.trim() ?? "";
+        const controlPath = (params.control_path as string | undefined)?.trim() || pocPath;
+        const controlTarget = (params.control_target as string | undefined)?.trim() ?? "";
+        if (!pocPath) {
+          return fail("poc_path is REQUIRED: absolute path to the PoC script run by the harness.", {
+            missingPocPath: true,
+          });
+        }
+        if (!controlTarget) {
+          return fail(
+            "control_target is REQUIRED: a distinct baseline target that lacks the vulnerability.",
+            { missingControlTarget: true },
+          );
+        }
+        if (controlTarget === current.target) {
+          return fail(
+            "control_target must differ from the case target; a control run against the vulnerable target proves nothing.",
+            { controlTargetEqualsCaseTarget: true },
+          );
+        }
+        if (params.local === true && process.env.PI_POC_ALLOW_NETWORK !== "1") {
+          return fail(
+            "Networked PoC execution is operator-gated. Set PI_POC_ALLOW_NETWORK=1 to authorize the host-network sandbox for this session.",
+            { networkNotAuthorized: true },
+          );
+        }
+        const controlAuthorization = controlTargetAuthorizationError(controlTarget);
+        if (controlAuthorization) {
+          return fail(
+            `CONTROL AUTHORIZATION FAILED: ${controlAuthorization}. ` +
+              "The operator must set PI_POC_CONTROL_TARGETS to the exact approved control host/origin before this control can anchor confirmation.",
+            { controlNotAuthorized: true },
+          );
+        }
 
-      const evidenceRun = (r: PocRun, mode: "poc" | "control", target: string): PocEvidenceRun => {
-        if (!r.completed || !r.outputComplete) {
+        // Same-file contract (anti-cheat): control must be the SAME bytes as the
+        // PoC, differing only via the harness-set env. Check BEFORE any run.
+        let pocHash: string | undefined;
+        let controlHash: string | undefined;
+        try {
+          pocHash = createHash("sha256").update(readFileSync(pocPath)).digest("hex");
+          controlHash = createHash("sha256").update(readFileSync(controlPath)).digest("hex");
+        } catch (e) {
           return fail(
-            `${mode} run did not complete or output capture was incomplete` +
-              (r.infraError ? ` (infra: ${r.output.trim()})` : "") +
-              ". A crash is not evidence. Case remains investigating.",
-            { run: r, pocCrashed: true },
+            `Cannot read PoC/control scripts for the same-file check: ${(e as Error).message}`,
+            { sameFileCheckFailed: true },
           );
         }
-        if (r.evidenceError) {
+        if (pocHash !== controlHash) {
           return fail(
-            `EVIDENCE CONTRACT FAILED (${mode} run): ${r.evidenceError}. ` +
-              "The PoC must write evidence.json to $PI_POC_EVIDENCE_DIR — { nonce (echo $PI_POC_NONCE), claim, verify: { method, url, expect: { status / body_contains / body_regex } }, observations } — " +
-              "the file is bound to this run and validated by the harness. Case remains investigating.",
-            { run: r, evidenceError: r.evidenceError },
+            "CONTROL CHECK FAILED: control_path must be the SAME script as poc_path (sha256 mismatch). Case remains investigating.",
+            { controlHashMismatch: true },
           );
         }
-        if (!r.evidence || !r.evidenceSha256 || !r.nonce) {
-          return fail(`${mode} run produced no evidence. Case remains investigating.`, { run: r });
+
+        // ── OOB callback (Tier 1, opt-in for blind classes) ──
+        const oobRequested = params.oob === true;
+        if (oobRequested) {
+          return fail(
+            "OOB confirmation is fail-closed: the built-in loopback listener is reachable by the PoC and cannot prove the target caused a callback. A source-separated, operator-owned callback service is required before blind findings can be promoted.",
+            { oobSourceSeparationRequired: true },
+          );
         }
-        return {
-          mode,
-          target,
-          nonce: r.nonce,
-          ranAt: r.ranAt,
-          exitCode: r.exitCode,
-          sandbox: r.sandbox,
-          completed: r.completed,
-          outputComplete: r.outputComplete,
-          output: r.output ?? "",
-          evidence: r.evidence,
-          evidenceSha256: r.evidenceSha256,
-          evidencePath: r.evidencePath,
+        const runOptions = (pocMode: string, target: string): PocRunOptions => ({
+          network: params.local === true ? "host" : "none",
+          local: params.local === true,
+          env: {
+            PI_POC_MODE: pocMode,
+            PI_POC_TARGET: target,
+          },
+        });
+
+        const caseTarget = current.target ?? "";
+        // Determinism: TWO target runs + one control run. Exit 0 is run
+        // integrity only; nonce-bound body evidence and the harness-owned
+        // target/control replay form the machine gate.
+        const run1 = runPoc(pocPath, runOptions("poc", caseTarget));
+        const run2 = runPoc(pocPath, runOptions("poc", caseTarget));
+        const controlRun = runPoc(controlPath, runOptions("control", controlTarget));
+
+        const evidenceRun = (
+          r: PocRun,
+          mode: "poc" | "control",
+          target: string,
+        ): PocEvidenceRun => {
+          if (!r.completed || !r.outputComplete) {
+            return fail(
+              `${mode} run did not complete or output capture was incomplete` +
+                (r.infraError ? ` (infra: ${r.output.trim()})` : "") +
+                ". A crash is not evidence. Case remains investigating.",
+              { run: r, pocCrashed: true },
+            );
+          }
+          if (r.evidenceError) {
+            return fail(
+              `EVIDENCE CONTRACT FAILED (${mode} run): ${r.evidenceError}. ` +
+                "The PoC must write evidence.json to $PI_POC_EVIDENCE_DIR — { nonce (echo $PI_POC_NONCE), claim, verify: { method, url, expect: { status?, body_contains / body_regex } }, observations }; a response-body assertion is mandatory — " +
+                "the file is bound to this run and validated by the harness. Case remains investigating.",
+              { run: r, evidenceError: r.evidenceError },
+            );
+          }
+          if (!r.evidence || !r.evidenceSha256 || !r.nonce) {
+            return fail(`${mode} run produced no evidence. Case remains investigating.`, {
+              run: r,
+            });
+          }
+          return {
+            mode,
+            target,
+            nonce: r.nonce,
+            ranAt: r.ranAt,
+            exitCode: r.exitCode,
+            sandbox: r.sandbox,
+            completed: r.completed,
+            outputComplete: r.outputComplete,
+            output: r.output ?? "",
+            evidence: r.evidence,
+            evidenceSha256: r.evidenceSha256,
+            evidencePath: r.evidencePath,
+          };
         };
-      };
 
-      const targetRuns: [PocEvidenceRun, PocEvidenceRun] = [
-        evidenceRun(run1, "poc", caseTarget),
-        evidenceRun(run2, "poc", caseTarget),
-      ];
-      const control = evidenceRun(controlRun, "control", controlTarget);
-
-      const bundle: PendingConfirmation = {
-        caseId,
-        ranAt: new Date().toISOString(),
-        pocPath,
-        pocSha256: pocHash,
-        controlPath,
-        controlTarget,
-        targetRuns,
-        controlRun: control,
-      };
+        const targetRuns: [PocEvidenceRun, PocEvidenceRun] = [
+          evidenceRun(run1, "poc", caseTarget),
+          evidenceRun(run2, "poc", caseTarget),
+        ];
+        const control = evidenceRun(controlRun, "control", controlTarget);
+
+        // Tier 2 (docs/poc-trust-model.md): the harness executes the SAME
+        // request template against target and operator-approved control, applying
+        // the target's predicates to both. DNS is pinned at connect time.
+        const harnessVerified = await replayDifferential(
+          targetRuns[0].evidence,
+          caseTarget,
+          controlTarget,
+          { allowPrivate: process.env.PI_POC_ALLOW_PRIVATE_REPLAY === "1" },
+        );
 
-      let record: CaseRecord;
-      try {
-        record = storePendingConfirmation(caseId, bundle);
-      } catch (e) {
-        return fail(`Pending confirmation rejected: ${(e as Error).message}`, {
-          storeRejected: true,
-        });
-      }
+        const bundle: PendingConfirmation = {
+          caseId,
+          ranAt: new Date().toISOString(),
+          pocPath,
+          pocSha256: pocHash,
+          controlPath,
+          controlTarget,
+          targetRuns,
+          controlRun: control,
+          harnessVerified,
+        };
 
-      return {
-        content: [
-          {
-            type: "text",
-            text:
-              `Phase 1 complete — evidence bundle recorded on ${caseId} (expires in 1h).\n` +
-              `Target runs: 2, Control run: 1 — all with validated nonce-bound evidence.json.\n` +
-              `Evidence sha256: ${targetRuns[0].evidenceSha256}\n` +
-              `PoC script sha256 (at run time): ${pocHash}\n\n` +
-              (detectHost() === "omp"
-                ? `DISPATCH THE CONFIRMER now: task({ context: 'fresh', tasks: [{ name: 'confirm-${caseId}-1', agent: 'confirmer', task: 'Verify the PoC evidence for case ${caseId} (poc_path=${pocPath}, control_target=${controlTarget}, evidence_sha256=${targetRuns[0].evidenceSha256}, poc_sha256=${pocHash}). Assume fabricated, prove real. Re-send the verify request yourself. Return the verdict.' }] })\n`
-                : `DISPATCH THE CONFIRMER now: subagent({ workflowScript: "return runs.run('confirm-${caseId}-1', { agent: 'confirmer', task: 'Verify the PoC evidence for case ${caseId} (poc_path=${pocPath}, control_target=${controlTarget}, evidence_sha256=${targetRuns[0].evidenceSha256}, poc_sha256=${pocHash}). Assume fabricated, prove real. Re-send the verify request yourself. Return the verdict.' })", context: 'fresh', async: true })\n`) +
-              "Then commit the verdict with ConfirmFinding(case_id, verdict) — CONFIRMED promotes, NOT_CONFIRMED keeps investigating.",
-          },
-        ],
-        details: {
-          record,
-          bundle: {
-            caseId,
-            ranAt: bundle.ranAt,
-            pocPath,
-            controlPath,
-            controlTarget,
-            pocSha256: pocHash,
-            evidenceSha256: targetRuns[0].evidenceSha256,
+        let record: CaseRecord;
+        try {
+          record = storePendingConfirmation(caseId, bundle);
+        } catch (e) {
+          return fail(`Pending confirmation rejected: ${(e as Error).message}`, {
+            storeRejected: true,
+          });
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `Phase 1 complete — evidence bundle recorded on ${caseId} (expires in 1h).\n` +
+                `Target runs: 2, Control run: 1 — all with validated nonce-bound evidence.json.\n` +
+                `Evidence sha256: ${targetRuns[0].evidenceSha256}\n` +
+                `PoC script sha256 (at run time): ${pocHash}\n` +
+                `Harness verify replay: ${harnessVerified.attempted ? (harnessVerified.pass ? `PASS (status ${harnessVerified.status})` : `FAILED — ${harnessVerified.note}`) : harnessVerified.note}\n` +
+                `\nMAIN-AGENT REVIEW REQUIRED (do not delegate): inspect case ${caseId}, PoC ${pocPath}, control ${controlTarget}, evidence ${targetRuns[0].evidenceSha256}, and PoC hash ${pocHash}. Hunt for a trivial predicate or fabricated differential and perform a concrete disconfirmation attempt, then call ConfirmFinding yourself. A CONFIRMED call performs and stores a fresh harness-owned target/control replay; NOT_CONFIRMED keeps the case investigating.`,
+            },
+          ],
+          details: {
+            record,
+            bundle: {
+              caseId,
+              ranAt: bundle.ranAt,
+              pocPath,
+              controlPath,
+              controlTarget,
+              pocSha256: pocHash,
+              evidenceSha256: targetRuns[0].evidenceSha256,
+              harnessVerified,
+            },
           },
-        },
-      };
-    },
+        };
+      },
 
-    renderCall(args, theme) {
-      return callLine(theme, "PromoteFinding", (args.id as string) ?? "");
-    },
+      renderCall(args, theme) {
+        return callLine(theme, "PromoteFinding", (args.id as string) ?? "");
+      },
 
-    renderResult(result, _opts, theme) {
-      const details = result.details as { bundle?: { evidenceSha256?: string } } | undefined;
-      if (!details?.bundle) {
-        return new Text(theme.fg("error", "✗ PromoteFinding failed"), 0, 0);
-      }
-      return new Text(
-        theme.fg("success", "✓ ") +
-          theme.fg("dim", "evidence bundle ") +
-          theme.fg("muted", details.bundle.evidenceSha256?.slice(0, 12) ?? ""),
-        0,
-        0,
-      );
-    },
-  });
+      renderResult(result, _opts, theme) {
+        const details = result.details as { bundle?: { evidenceSha256?: string } } | undefined;
+        if (!details?.bundle) {
+          return new Text(theme.fg("error", "✗ PromoteFinding failed"), 0, 0);
+        }
+        return new Text(
+          theme.fg("success", "✓ ") +
+            theme.fg("dim", "evidence bundle ") +
+            theme.fg("muted", details.bundle.evidenceSha256?.slice(0, 12) ?? ""),
+          0,
+          0,
+        );
+      },
+    });
 
   // ── Tool: ConfirmFinding (phase 2) ──
 
-  pi.registerTool({
-    name: "ConfirmFinding",
-    label: "Commit Confirmer Verdict",
-    description:
-      "Phase 2 of confirmation: commit (or refuse) a promotion on the confirmer subagent's verdict. CONFIRMED requires a target-only differential, re_executed: true (the confirmer re-sent the verify request itself), a disconfirmation_attempt (becomes the case's disconfirmation), and the pending bundle from PromoteFinding still valid (nonce-bound evidence, determinism, control differential, PoC script unchanged — checked again at the ledger). NOT_CONFIRMED records the verdict and keeps the case investigating — no tie-breaker.",
-    promptSnippet: "Commit the confirmer verdict — promote or keep investigating",
-    promptGuidelines: [
-      "Run after PromoteFinding + the confirmer dispatch. The verdict comes from the confirmer subagent output, not from the writer.",
-      "CONFIRMED requires differential: 'target_only', re_executed: true, and disconfirmation_attempt (the confirmer's own failed disproof). A verdict missing any of these is rejected.",
-      "NOT_CONFIRMED is final for that attempt — the case stays investigating with the reasoning recorded in assumptions. Re-dispatch a new confirmer if you want a second opinion; every attempt is recorded.",
-      "Never CaseUpdate status='confirmed' directly — it is rejected. Always use PromoteFinding + ConfirmFinding.",
-    ],
-    parameters: ConfirmSchema,
-
-    async execute(_id, params, _signal, _onUpdate, _ctx) {
-      const caseId = params.id as string;
-      const result = applyConfirmationResult(caseId, params.verdict as ConfirmerVerdict);
-      const record = result.record;
-      const promoted = record.status === "confirmed";
-      return {
-        content: [
-          {
-            type: "text",
-            text: promoted
-              ? `Confirmer CONFIRMED. Case promoted:
+  // Do not expose the commit capability in a worker process at all. The
+  // execute-time check remains as defense in depth if process state changes
+  // after registration or another integration forwards a stale tool handle.
+  if (!startedAsSubagent)
+    registerCaseTool({
+      name: "ConfirmFinding",
+      label: "Main-Agent Confirmation",
+      description:
+        "Phase 2 of confirmation, reserved for the main/coordinator agent: commit or refuse promotion after personally reviewing the machine bundle. On CONFIRMED, this tool performs a fresh harness-owned target/control replay; the verdict requires a target-only differential, a concrete re_execution_note and disconfirmation_attempt, a canary assessment, and the still-valid PromoteFinding bundle. The machine transcript is evidence, not the semantic vulnerability verdict. Worker/subagent processes are rejected. NOT_CONFIRMED records the review and keeps the case investigating.",
+      promptSnippet: "Main agent: independently review and commit or refuse PoC confirmation",
+      promptGuidelines: [
+        "Run only in the main/coordinator agent after PromoteFinding returns. Do not dispatch a worker to decide or author this verdict.",
+        "Personally inspect the PoC and preserved evidence and try a concrete disconfirmation before deciding. ConfirmFinding itself re-sends the immutable verify request against target and operator-approved control so phase 2 has a harness-owned transcript.",
+        "CONFIRMED requires differential: 'target_only', re_execution_note, and disconfirmation_attempt (the main agent's failed disproof). A verdict missing any of these is rejected.",
+        "Set canary_assessment='verified' when the immutable request declared a canary; otherwise set not_applicable and explain why a reflection canary is not meaningful for this exploit class.",
+        "NOT_CONFIRMED is final for that attempt — the case stays investigating with the main agent's reasoning recorded. A fresh PromoteFinding run is required for another attempt.",
+        "Never CaseUpdate status='confirmed' directly — it is rejected. Always use PromoteFinding + ConfirmFinding.",
+      ],
+      parameters: ConfirmSchema,
+
+      async execute(_id, params, _signal, _onUpdate, _ctx) {
+        if (isSubagentProcess()) {
+          throw new Error(
+            "ConfirmFinding is reserved for the main/coordinator agent. A worker or subagent may gather or challenge evidence but cannot run validation or confirm a PoC.",
+          );
+        }
+        const caseId = params.id as string;
+        const parsedVerdict = validateMainAgentVerdict(params.verdict);
+        if (!parsedVerdict.ok) {
+          throw new Error(`Invalid main-agent confirmation verdict: ${parsedVerdict.error}`);
+        }
+        let phase2Verification: MainAgentVerification | undefined;
+        if (parsedVerdict.verdict.verdict === "CONFIRMED") {
+          const current = getCaseById(caseId);
+          if (!current) throw new Error(`Case not found: ${caseId}`);
+          const bundle = current.pendingConfirmation;
+          if (!bundle) {
+            throw new Error("No pending confirmation on this case — run PromoteFinding first");
+          }
+          const controlAuthorizationError = controlTargetAuthorizationError(bundle.controlTarget);
+          if (controlAuthorizationError) {
+            throw new Error(`CONTROL AUTHORIZATION FAILED: ${controlAuthorizationError}`);
+          }
+          const replay = await replayDifferential(
+            bundle.targetRuns[0].evidence,
+            current.target ?? bundle.targetRuns[0].target,
+            bundle.controlTarget,
+            { allowPrivate: process.env.PI_POC_ALLOW_PRIVATE_REPLAY === "1" },
+          );
+          phase2Verification = {
+            at: new Date().toISOString(),
+            result: replay,
+          };
+        }
+        const result = applyConfirmationResult(caseId, parsedVerdict.verdict, phase2Verification, {
+          startedAsSubagent: isSubagentProcess(),
+        });
+        const record = result.record;
+        const promoted = record.status === "confirmed";
+        return {
+          content: [
+            {
+              type: "text",
+              text: promoted
+                ? `Main agent CONFIRMED. Case promoted:
 ${formatCaseDetail(record)}`
-              : `Confirmer NOT_CONFIRMED — case stays investigating (attempt recorded):
+                : `Main agent NOT_CONFIRMED — case stays investigating (attempt recorded):
 ${formatCaseDetail(record)}`,
-          },
-        ],
-        details: { record, promoted, changed: result.changed },
-      };
-    },
+            },
+          ],
+          details: { record, promoted, changed: result.changed },
+        };
+      },
 
-    renderCall(args, theme) {
-      return callLine(theme, "ConfirmFinding", (args.id as string) ?? "");
-    },
+      renderCall(args, theme) {
+        return callLine(theme, "ConfirmFinding", (args.id as string) ?? "");
+      },
 
-    renderResult(result, _opts, theme) {
-      const details = result.details as { promoted?: boolean } | undefined;
-      return new Text(
-        details?.promoted
-          ? theme.fg("success", "✓ Promoted")
-          : theme.fg("warning", "↷ Not confirmed"),
-        0,
-        0,
-      );
-    },
-  });
+      renderResult(result, _opts, theme) {
+        const details = result.details as { promoted?: boolean } | undefined;
+        return new Text(
+          details?.promoted
+            ? theme.fg("success", "✓ Promoted")
+            : theme.fg("warning", "↷ Not confirmed"),
+          0,
+          0,
+        );
+      },
+    });
 
   // ── Tool: CaseGet ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseGet",
     label: "Get Case",
     description: "Get full details of a single case by ID.",
@@ -1384,7 +1508,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: CaseList ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseList",
     label: "List Cases",
     description:
@@ -1414,7 +1538,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: CaseSearch ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseSearch",
     label: "Search Cases",
     description:
@@ -1442,7 +1566,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: CaseLink ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseLink",
     label: "Link Cases",
     description:
@@ -1514,7 +1638,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: CaseUnlink ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseUnlink",
     label: "Unlink Cases",
     description: "Remove a bidirectional link between two cases.",
@@ -1581,7 +1705,7 @@ ${formatCaseDetail(record)}`,
     { additionalProperties: false },
   );
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ChainSuggest",
     label: "Suggest Exploit Chains",
     description:
@@ -1595,7 +1719,9 @@ ${formatCaseDetail(record)}`,
     parameters: ChainSuggestSchema,
 
     async execute(_id, params, _signal, _onUpdate, _ctx) {
-      const suggestions = suggestChains((params.case_id as string | undefined) ?? undefined);
+      const suggestions = await suggestChainsAsync(
+        (params.case_id as string | undefined) ?? undefined,
+      );
       const lines: string[] = [
         suggestions.length
           ? `${suggestions.length} chain candidate(s):`
@@ -1628,25 +1754,25 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: CaseContext ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "CaseContext",
     label: "Generate Case Context",
     description:
-      "Generate the case context bundle for a confirmed or reported case under the casefile report directory (next to the casefile DB): full evidence, PoC verification log, disconfirmation attempt, links, and timeline, plus the target report path. The report writer (reporter subagent) turns this context into the final polished H1-style report. Hypothesis/investigating/blocked/killed cases are rejected — promote to confirmed first.",
-    promptSnippet: "Generate case context for the report writer",
+      "Generate the case context bundle for a confirmed or reported case under the casefile report directory (next to the casefile DB): full evidence, PoC verification log, disconfirmation attempt, links, and timeline, plus the target report path. The main agent turns this context into the final polished H1-style report. Hypothesis/investigating/blocked/killed cases are rejected — promote to confirmed first.",
+    promptSnippet: "Generate case context for the final report",
     promptGuidelines: [
       "Use CaseContext only for confirmed or already reported cases. Keep hypotheses and investigating cases in the ledger until proof is captured.",
-      "After CaseContext, dispatch the reporter subagent (agents/reporter) to write the final report to the returned report path, then CaseUpdate(status: 'reported').",
+      "After CaseContext, write the final report to the returned report path yourself, then CaseUpdate(status: 'reported').",
     ],
     parameters: IdSchema,
 
     async execute(_id, params, _signal, _onUpdate, _ctx) {
-      const { path, contextPath, record } = writeCaseContext(params.id as string);
+      const { path, contextPath, record } = await writeCaseContextAsync(params.id as string);
       return {
         content: [
           {
             type: "text",
-            text: `Case context written: ${contextPath}\nReport path (for the reporter agent): ${path}\n${formatCase(record)}`,
+            text: `Case context written: ${contextPath}\nReport path: ${path}\n${formatCase(record)}`,
           },
         ],
         details: { path, contextPath, record },
@@ -1671,7 +1797,7 @@ ${formatCaseDetail(record)}`,
 
   pi.registerCommand("xp", {
     description:
-      "Toggle casefile XP (offensive) mode. ON injects the full cyber workflow (subagent pipeline); LITE injects the single-agent workflow (no subagent dispatch); OFF (default) keeps context quiet for normal dev work. Usage: /xp [on|off|lite]",
+      "Toggle casefile XP (offensive) mode. Bare /xp and /xp on select SWARM, the bounded multi-agent workflow. LITE keeps XP single-agent. OFF (default) keeps context quiet for normal dev work. Usage: /xp [on|lite|swarm|off]",
     handler: async (args, ctx) => {
       const next = parseXpModeArg(args ?? "", readXpMode());
       writeXpMode(next);
@@ -1682,23 +1808,25 @@ ${formatCaseDetail(record)}`,
       if (next !== "off") workflowInjected = false;
       ctx.ui.notify(
         `Casefile XP mode: ${next.toUpperCase()} (takes effect on the next prompt)`,
-        next === "on" ? "info" : "warning",
+        next === "off" ? "warning" : "info",
       );
     },
   });
 
   // ── Tool: PipelineSubmit ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "PipelineSubmit",
     label: "Submit Stage Output",
     description:
       "Submit a pipeline stage's output (hunt, trace, skeptic, validate, chain, report) through the validation gate. Validates required fields against the stage spec (mirrors schemas/*.json), applies the deterministic pre-filter (test-path and file-existence filters on hunt findings, trivial dedup by file+class+line), and counts repair attempts (max 2, then rejected). A stage cannot advance on an invalid output — submit fixed output until accepted.",
     promptSnippet: "Validate and submit a pipeline stage's output",
     promptGuidelines: [
-      "Every stage output a subagent returns must go through PipelineSubmit before the next stage is dispatched — do not eyeball schemas.",
+      "Every delegated stage output and every main-agent VALIDATE/REPORT output must go through PipelineSubmit before the next stage starts — do not eyeball schemas.",
       "verdict repair → fix the listed fields and re-submit the same output; budget is 2 attempts per finding, then rejected.",
-      "Skeptic: unparseable/schema-invalid = UNDETERMINED (never DISPROVEN). Tracer error = UNREACHABLE. Both return repair.",
+      "Skeptic: unparseable/schema-invalid = no verdict (repair/re-dispatch); only schema-valid DISPROVEN kills, and schema-valid UNDETERMINED blocks validation.",
+      "Tracer crash/invalid output = no trace verdict; repair or re-dispatch.",
+      'Only schema-valid trace_result: "UNREACHABLE" blocks advancement as a proven unreachable path; schema-valid UNDETERMINED blocks validation until resolved.',
       "Test-path findings and hallucinated files are rejected by the pre-filter, not repairable — the finding itself is noise.",
     ],
     parameters: Type.Object(
@@ -1758,7 +1886,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: ScratchpadInit ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ScratchpadInit",
     label: "Init Scratchpad",
     description:
@@ -1796,7 +1924,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: ScratchpadResume ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ScratchpadResume",
     label: "Resume Scratchpad",
     description:
@@ -1855,7 +1983,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: ScratchpadCheckpoint ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ScratchpadCheckpoint",
     label: "Checkpoint Phase",
     description:
@@ -1905,7 +2033,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: ScratchpadWrite ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ScratchpadWrite",
     label: "Write Artifact",
     description:
@@ -1951,7 +2079,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: ScratchpadRead ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ScratchpadRead",
     label: "Read Artifact",
     description:
@@ -2008,7 +2136,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: ScratchpadPhaseDone ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ScratchpadPhaseDone",
     label: "Phase Done?",
     description:
@@ -2051,7 +2179,7 @@ ${formatCaseDetail(record)}`,
 
   // ── Tool: ScratchpadClear ──
 
-  pi.registerTool({
+  registerCaseTool({
     name: "ScratchpadClear",
     label: "Clear Run",
     description:
@@ -2135,7 +2263,7 @@ ${formatCaseDetail(record)}`,
     // the workflow + entire active-case ledger into every child dispatch is a
     // token multiplier (N subagents × workflow + growing case list per turn) —
     // workers get what they need via their task and tool guidelines.
-    if (process.env.PI_SUBAGENT_CHILD === "1") return;
+    if (isSubagentProcess()) return;
 
     const includeWorkflow = !workflowInjected;