@vigolium/piolium 0.0.1

package/extensions/piolium/modes/deep.ts

@@ -0,0 +1,917 @@
+/**
+ * Deep mode orchestrator (`/piolium-deep`).
+ *
+ * Pipeline (command-defs/deep.md, archon-audit @ 2026-05-16):
+ *
+ *   [D1 Intel Sweep CVE ‖ D2 Intel Sweep History]   (D2 skipped no-git)
+ *   → D3 Patch Audit                                  (skipped no-git)
+ *   → D4 Threat Model
+ *   → [D5 Code Scan ‖ D7 Access Audit]   (wave A, cap 2)
+ *   → D6 Deep Probe                       (wave B)
+ *   → D8 Taint Trace
+ *   → D9 Review Panel + inline FP/triage tail
+ *   → D10 Intent Reconciliation           (skip-and-continue)
+ *   → D11 Variant Sweep
+ *   → D12 PoC Authoring                    (per finding)
+ *   → D13 Finding Finalize                 (per finding, BOTH buckets)
+ *   → D14 Report Compose                   (+ inline cleanup/file-state)
+ *
+ * MVP simplifications (deliberate, relative to upstream):
+ *   - D6 deep probe runs as a single probe-lead session that folds the
+ *     reasoner roles inline instead of N orchestrated teams.
+ *   - D9 chamber is one review-adjudicator session per run with the FP /
+ *     cold-verify / triage tail folded into its prompt.
+ *   - D12/D13 iterate findings under the global concurrency cap.
+ *
+ * No-git mode: D2 and D3 transition to `skipped`; the audit records
+ * `history_available: false`.
+ *
+ * Single-phase mode: pass `only: ["D6"]` to rerun a specific phase. Its
+ * prerequisites must already be `complete`/`skipped`.
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentRuntimeModel } from "../agent-runner.ts";
+import { type AgentDefinition, loadAgents } from "../agents.ts";
+import {
+	type AuditRunState,
+	applyPhaseStatus,
+	initAudit,
+	latestAudit,
+	markAuditStatus,
+	readAuditState,
+} from "../audit-state.ts";
+import { runCandidateScanAsync } from "../candidate-scan.ts";
+import {
+	type FindingDir,
+	consolidateDrafts,
+	listAllFindingDirs,
+	listFindingDirs,
+	partitionFindings,
+} from "../findings.ts";
+import { runReconAsync } from "../recon.ts";
+import { readPositiveIntEnv } from "../retry.ts";
+import { Scheduler } from "../scheduler.ts";
+import { type PhaseUiHooks, runAgentPhase } from "./phase-runner.ts";
+
+export type DeepUiHooks = PhaseUiHooks;
+
+export interface RunDeepOptions {
+	cwd: string;
+	signal?: AbortSignal;
+	ui?: DeepUiHooks;
+	forceFresh?: boolean;
+	agentRuntime?: AgentRuntimeModel;
+	/** Restrict execution to a subset of phase ids (e.g. ["D6"]). */
+	only?: string[];
+}
+
+export interface RunDeepResult {
+	auditId: string;
+	status: "complete" | "failed";
+	phases: Record<string, "complete" | "failed" | "skipped">;
+}
+
+const ATTACK_SURFACE_DIR = "piolium/attack-surface";
+const KB_REPORT = `${ATTACK_SURFACE_DIR}/knowledge-base-report.md`;
+const ADVISORY_SUMMARY = `${ATTACK_SURFACE_DIR}/advisory-summary.md`;
+const COMMIT_RECON = `${ATTACK_SURFACE_DIR}/commit-recon-report.md`;
+const PATCH_BYPASS_SUMMARY = `${ATTACK_SURFACE_DIR}/patch-bypass-summary.md`;
+const ATTACK_SURFACE_ARCHITECTURE = `${ATTACK_SURFACE_DIR}/architecture-entrypoints.md`;
+const SAST_REPORT = `${ATTACK_SURFACE_DIR}/source-sink-flows-all-severities.md`;
+const AUTHZ_MATRIX = `${ATTACK_SURFACE_DIR}/public-routes-authz-matrix.md`;
+const MANUAL_ATTACK_SURFACE = `${ATTACK_SURFACE_DIR}/manual-attack-surface-inventory.md`;
+const PROBE_SUMMARY = `${ATTACK_SURFACE_DIR}/deep-probe-summary.md`;
+const CROSS_SERVICE = `${ATTACK_SURFACE_DIR}/cross-service-edges.json`;
+const CROSS_SERVICE_REPORT = `${ATTACK_SURFACE_DIR}/cross-service-edges.md`;
+const CHAMBER_INDEX = "piolium/chamber-workspace/index.md";
+const INTENT_RECONCILIATION = `${ATTACK_SURFACE_DIR}/intent-reconciliation.md`;
+const VARIANT_SUMMARY = `${ATTACK_SURFACE_DIR}/variant-summary.md`;
+const CONSOLIDATION_MANIFEST = `${ATTACK_SURFACE_DIR}/deep-consolidation-manifest.json`;
+const FINAL_REPORT = "piolium/final-audit-report.md";
+const DEEP_CLEANUP_SUMMARY = `${ATTACK_SURFACE_DIR}/deep-cleanup-summary.json`;
+const DEEP_TRANSIENT_PATHS = [
+	"piolium/tmp",
+	"piolium/chamber-workspace",
+	"piolium/probe-workspace",
+	"piolium/adversarial-reviews",
+	"piolium/bypass-analysis",
+	"piolium/codeql-artifacts",
+	"piolium/codeql-queries",
+	"piolium/semgrep-rules",
+	"piolium/agentic-actions-res",
+	"piolium/confirm-workspace",
+	"piolium/codeql-res",
+	"piolium/semgrep-res",
+	"piolium/real-env-evidence",
+	"piolium/raw",
+	"piolium/file-records",
+	"piolium/findings-draft",
+	"piolium/attack-surface/raw",
+	"piolium/attack-pattern-registry.json",
+	"piolium/authz-coverage-gaps.md",
+	"piolium/merged-results.sarif",
+];
+const PER_FINDING_MAX_RETRIES = readPositiveIntEnv("PIOLIUM_PER_FINDING_MAX_RETRIES", 10);
+const PER_FINDING_ATTEMPT_TIMEOUT_MS = readPositiveIntEnv(
+	"PIOLIUM_PER_FINDING_ATTEMPT_TIMEOUT_MS",
+	30 * 60 * 1000,
+);
+const PER_FINDING_BACKOFF_BASE_MS = readPositiveIntEnv("PIOLIUM_PER_FINDING_BACKOFF_BASE_MS", 5000);
+const PER_FINDING_BACKOFF_MAX_MS = readPositiveIntEnv(
+	"PIOLIUM_PER_FINDING_BACKOFF_MAX_MS",
+	120_000,
+);
+
+function exists(cwd: string, rel: string): boolean {
+	return existsSync(join(cwd, rel));
+}
+
+function ensureAttackSurfaceDir(cwd: string): void {
+	mkdirSync(join(cwd, ATTACK_SURFACE_DIR), { recursive: true });
+}
+
+function findingHasPoc(path: string): boolean {
+	try {
+		return (
+			readdirSync(path).some((f) => f.startsWith("poc.")) ||
+			existsSync(join(path, "poc.theoretical.md"))
+		);
+	} catch {
+		return false;
+	}
+}
+
+function findingHasReport(path: string): boolean {
+	try {
+		const report = join(path, "report.md");
+		return existsSync(report) && statSync(report).size > 500;
+	} catch {
+		return false;
+	}
+}
+
+function perFindingGate(phase: "D12" | "D13", path: string): boolean {
+	return phase === "D12" ? findingHasPoc(path) : findingHasReport(path);
+}
+
+function retryBackoffMs(attempt: number): number {
+	const exponent = Math.max(0, attempt - 1);
+	const raw = PER_FINDING_BACKOFF_BASE_MS * 2 ** exponent;
+	return Math.min(PER_FINDING_BACKOFF_MAX_MS, raw);
+}
+
+async function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+	if (ms <= 0) return;
+	if (signal?.aborted) throw signal.reason ?? new Error("Aborted");
+	await new Promise<void>((resolve, reject) => {
+		const cleanup = () => {
+			clearTimeout(timeout);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		const timeout = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			cleanup();
+			reject(signal?.reason ?? new Error("Aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+function errorMessage(err: unknown): string {
+	return err instanceof Error ? err.message : typeof err === "string" ? err : "Unknown error";
+}
+
+const PREREQS: Record<string, string[]> = {
+	D1: [],
+	D2: [],
+	D3: ["D1", "D2"],
+	D4: ["D3"],
+	D5: ["D4"],
+	D6: ["D4"],
+	D7: ["D4"],
+	D8: ["D5", "D6"],
+	D9: ["D6", "D7", "D8"],
+	D10: ["D9"],
+	D11: ["D10"],
+	D12: ["D11"],
+	D13: ["D12"],
+	D14: ["D13"],
+};
+
+function pickResume(
+	cwd: string,
+	force: boolean,
+	allowComplete: boolean,
+): AuditRunState | undefined {
+	if (force) return undefined;
+	const state = readAuditState(cwd).state;
+	const audit = state ? latestAudit(state) : undefined;
+	if (!audit) return undefined;
+	if (audit.mode !== "deep") return undefined;
+	if (audit.status === "complete" && !allowComplete) return undefined;
+	return audit;
+}
+
+function shouldRun(name: string, only: string[] | undefined): boolean {
+	if (!only) return true;
+	return only.includes(name);
+}
+
+function ensurePrereqs(audit: AuditRunState, name: string): void {
+	const prereqs = PREREQS[name] ?? [];
+	for (const prereq of prereqs) {
+		const status = audit.phases[prereq]?.status;
+		if (status !== "complete" && status !== "skipped") {
+			throw new Error(
+				`Cannot run ${name}: prerequisite ${prereq} is "${status ?? "missing"}". Resume or rerun upstream phases first.`,
+			);
+		}
+	}
+}
+
+function buildTask(phase: string, cwd: string, hasGit: boolean): string {
+	switch (phase) {
+		case "D1":
+			return [
+				"You are running Phase D1 (Intel Sweep — CVE) of /piolium-deep.",
+				`Build \`${ADVISORY_SUMMARY}\` covering CVE/GHSA/OSV advisories, dependency intel, and architecture hints. Use bash + WebFetch (run \`curl\` against advisory APIs; WebSearch may be unavailable — use bash+curl instead).`,
+				`Scope: cve-scout only. Target repository: ${cwd}.`,
+			].join("\n\n");
+		case "D2":
+			return [
+				"You are running Phase D2 (Intel Sweep — History) of /piolium-deep.",
+				hasGit
+					? `Sweep git history for security-relevant commits. Set \`MAX_COMMITS="\${PIOLIUM_COMMIT_SCAN_LIMIT:-500}"\` and \`MAX_AGE="\${PIOLIUM_COMMIT_SCAN_SINCE:-60 days ago}"\`; every \`git log\` must include \`-n "$MAX_COMMITS" --since="$MAX_AGE"\`. Categorise HIGH-risk commits (silent fixes, dangerous patterns, reverted fixes). Write \`${COMMIT_RECON}\` with categorised commits feeding D3.`
+					: `(no-git target — return immediately with a short note in \`${COMMIT_RECON}\` saying D2 is skipped: history_available=false.)`,
+			].join("\n\n");
+		case "D3":
+			return [
+				"You are running Phase D3 (Patch Audit) of /piolium-deep.",
+				hasGit
+					? `Read \`${ADVISORY_SUMMARY}\` and \`${COMMIT_RECON}\`. For each known CVE/GHSA patch and each HIGH-risk undisclosed commit, check whether the fix is bypassable today (alternate entry points, config gates, parser differentials). Write \`${PATCH_BYPASS_SUMMARY}\` with: patches reviewed, bypass attempts, conclusions, and drafts \`piolium/findings-draft/d3-NNN-<slug>.md\`.`
+					: `(no-git target — write a short \`${PATCH_BYPASS_SUMMARY}\` note saying D3 is skipped because there is no local patch history.)`,
+			].join("\n\n");
+		case "D4":
+			return [
+				"You are running Phase D4 (Threat Model) of /piolium-deep.",
+				`Build the deep KB at \`${KB_REPORT}\`. Use the security-threat-model skill if available. If \`piolium/INFO.md\` exists, treat it as authoritative for the sections it covers.`,
+				"Sections: Project Type, Trust Boundaries, DFD slices, CFD slices, Framework Contracts and Hidden Control Channels, Domain Attack Modes (apply sharp-edges, wooyun-legacy, insecure-defaults, last30days as applicable), Phase D5 CodeQL Extraction Targets, Coverage Gaps.",
+				`Also write \`${ATTACK_SURFACE_ARCHITECTURE}\` with a reusable inventory of entry points, public routes/URLs, attacker-controlled sources, high-value sinks, and key source files.`,
+				"This KB drives every later phase — be thorough.",
+			].join("\n\n");
+		case "D5":
+			return [
+				"You are running Phase D5 (Code Scan) of /piolium-deep.",
+				"Use codeql + semgrep skills if available (custom queries/rules + structural extraction allowed in deep); otherwise fall back to grep + read.",
+				"Read `piolium/attack-surface/candidates-summary.md` and `piolium/attack-surface/candidates.jsonl` first; prioritize precise/high-score candidate files before expanding coverage.",
+				"Pay special attention to `hidden-control-channel` candidates: headers or framework/proxy context affecting auth, routing, tenant selection, middleware, runtime mode, debug/admin/preview behavior, or cache keys.",
+				"Required artifacts:",
+				`  - \`${SAST_REPORT}\``,
+				"  - draft findings `piolium/findings-draft/d5-NNN-<slug>.md`",
+				"Then run an inline SAST enrichment pass: classify each candidate for security relevance (trust-boundary crossing / attacker-controlled input) and write a `## SAST Enrichment` section into the KB. Drop likely-correctness / environment-only findings.",
+				"Each draft frontmatter MUST include id (d5-NNN), phase (D5), slug, severity. Cap drafts at 30.",
+			].join("\n\n");
+		case "D6":
+			return [
+				"You are running Phase D6 (Deep Probe) of /piolium-deep.",
+				"Single-team probe in MVP — strategist + backward/contradiction reasoners + evidence harvester, all inline.",
+				"Steps:",
+				`  1. Read \`${KB_REPORT}\`, \`${ATTACK_SURFACE_DIR}/candidates-summary.md\`, plus D4/D5 artifacts. Pick the highest-impact slices.`,
+				`  2. Write \`${MANUAL_ATTACK_SURFACE}\` with public routes/URLs, attacker sources, sinks, source files, hidden control channels, exploit-relevant paths, and an inline Code Anatomy.`,
+				"  3. Generate hypotheses (Pre-Mortem + Abductive + TRIZ/Game-Theory reasoning).",
+				"  4. Verify with read/grep/bash — file:line evidence required; apply causal challenge (intervention/counterfactual/confounder) before any INVALIDATED verdict.",
+				"  5. Write drafts `piolium/findings-draft/d6-NNN-<slug>.md`.",
+				`  6. Write \`${PROBE_SUMMARY}\`.`,
+			].join("\n\n");
+		case "D7":
+			return [
+				"You are running Phase D7 (Access Audit) of /piolium-deep.",
+				`Read \`${KB_REPORT}\` and \`${ATTACK_SURFACE_ARCHITECTURE}\` if present. Enumerate every route/handler/consumer; build \`${AUTHZ_MATRIX}\` with rows: public route/URL/operation × roles, expected vs actual checks, including middleware/proxy-derived identity and hidden control channels. File anomalies as drafts \`piolium/findings-draft/d7-NNN-<slug>.md\`. Coordinate with D6 — check the probe summary before filing to avoid duplicates.`,
+			].join("\n\n");
+		case "D8":
+			return [
+				"You are running Phase D8 (Taint Trace) of /piolium-deep.",
+				`Read \`${KB_REPORT}\` Architecture/DFD sections, the D6 probe summary, and \`${AUTHZ_MATRIX}\` if present.`,
+				`If the target is a single-service repo, write \`${CROSS_SERVICE}\` containing \`{"single_service": true}\` and stop with a clean no-op note.`,
+				`Otherwise: stitch inter-component flows (HTTP/RPC/queues/DB writes), catch sanitization gaps and write-driven injection, and produce \`${CROSS_SERVICE}\` (machine-readable) plus \`${CROSS_SERVICE_REPORT}\` (human-readable). Drafts go to \`piolium/findings-draft/d8-NNN-<slug>.md\`.`,
+			].join("\n\n");
+		case "D9":
+			return [
+				"You are running Phase D9 (Review Panel + FP/Triage tail) of /piolium-deep.",
+				`Read \`${ATTACK_SURFACE_DIR}/\` artifacts as the shared attack-surface index.`,
+				"Group draft findings (d3-, d5-, d6-, d7-, d8-) into clusters by attack class. For each cluster, run an inline chamber: Synthesizer (you, final verdict) + Ideator (challenge with attack scenarios; also cover state/concurrency and spec-compliance classes since they have no dedicated phase) + Devil's Advocate (try to reject). Chain/extend pre-seeded drafts rather than regenerating.",
+				"Do not delete weak drafts. Mark rejected drafts with frontmatter `status: rejected-fp` and `rejection_reason: <short reason>`.",
+				"FP tail (inline): (1) fp-check every surviving VALID draft; (2) cold re-verification for CRITICAL survivors only; (3) triage sweep — write `Triage-Priority` (P0/P1/P2/skip), `Triage-Exploitability`, `Triage-Impact`, `Triage-Reasoning` into every surviving draft's frontmatter. `skip` is reversible (routed to the theoretical bucket later).",
+				"Survivors get copied to `piolium/findings-draft/d9-NNN-<slug>.md` with `status: valid`, normalised severity, and Triage-* preserved.",
+				"Write per-cluster transcripts under `piolium/chamber-workspace/<cluster-id>/debate.md` and an index at `piolium/chamber-workspace/index.md`.",
+			].join("\n\n");
+		case "D10":
+			return [
+				"You are running Phase D10 (Intent Reconciliation) of /piolium-deep — AUDIT CONTRACT.",
+				"Runs after the D9 FP/triage tail and BEFORE variant/PoC effort. Reconcile each surviving finding against documented intentional design / exposed feature / explicitly in-scope risk.",
+				`Inputs: \`piolium/findings-draft/d9-*.md\` (every \`status: valid\` draft), \`${KB_REPORT}\` (Architecture Model / Domain Attack Research / Known False-Positive Sources), and \`piolium/INFO.md\` if present.`,
+				"For each VALID draft: bounded read of ONLY the cited file:line, reconcile against documented intent, write `Intent-Verdict` / `Intent-Source` / `Intent-Quote` into the draft frontmatter. For strongly-intentional or documented-feature findings, overwrite `Triage-Priority: skip` with a `Triage-Reasoning: context-reviewer: …` note. Do NOT touch `status` or `severity`.",
+				`Write the corpus to \`piolium/attack-surface/intent-corpus.json\`, per-finding verdicts to \`piolium/attack-surface/intent-verdicts.json\`, and the report to \`${INTENT_RECONCILIATION}\`. Best-effort: never suppress a finding outright; always write at least a minimal intent-reconciliation.md.`,
+			].join("\n\n");
+		case "D11":
+			return [
+				"You are running Phase D11 (Variant Sweep) of /piolium-deep.",
+				`For each surviving finding whose draft is NOT \`Triage-Priority: skip\`, search the codebase and \`${ATTACK_SURFACE_DIR}/\` for similar routes, sources, sinks, and flow patterns. Use the variant-analysis skill if available. Write new drafts \`piolium/findings-draft/d11-NNN-<slug>.md\`. Write \`${VARIANT_SUMMARY}\`.`,
+			].join("\n\n");
+		case "D12":
+			return [
+				"You are running Phase D12 (PoC Authoring) of /piolium-deep — this prompt is for a SINGLE finding.",
+				"Read draft.md, build a minimal PoC, write `<finding-dir>/poc.{py|sh|js|rb|go}`, evidence to `<finding-dir>/evidence/`, and `PoC-Status: executed` (or `not-executed` with reason) into draft.md frontmatter. If runtime exploitation isn't possible, write `<finding-dir>/poc.theoretical.md` explaining the chain and set `PoC-Status: not-executed`.",
+			].join("\n\n");
+		case "D13":
+			return [
+				"You are running Phase D13 (Finding Finalize) of /piolium-deep — this prompt is for a SINGLE finding (may be in the confirmed OR theoretical bucket).",
+				"Use the vuln-report skill if available. Produce `<finding-dir>/report.md` (>500 bytes) with Summary, Details, Root Cause, Proof of concept & Evidence, Impact, Remediation. Theoretical-bucket findings get the same report; their PoC section states the no-PoC reason.",
+			].join("\n\n");
+		case "D14":
+			return [
+				"You are running Phase D14 (Report Compose) of /piolium-deep.",
+				"Verify every directory under `piolium/findings/` AND `piolium/findings-theoretical/` has `report.md` >500 bytes. If any are missing, fail with a clear error.",
+				`Compose \`piolium/final-audit-report.md\`: Executive Summary, Findings by Severity — confirmed only (with links), Theoretical / Unconfirmed Findings (kept out of the Summary-of-Findings table), Intent Reconciliation summary (surface \`${INTENT_RECONCILIATION}\` if present), Attack Surface Summary (linking \`${ATTACK_SURFACE_DIR}/\` artifacts), Coverage Gaps, Methodology Notes. If history_available is false, add an Executive Summary note that D2/D3 git-history phases were skipped.`,
+			].join("\n\n");
+		default:
+			return `Phase ${phase} task description not implemented.`;
+	}
+}
+
+function gateFor(phase: string, cwd: string): () => boolean {
+	switch (phase) {
+		case "D1":
+			return () => exists(cwd, ADVISORY_SUMMARY);
+		case "D2":
+			return () => exists(cwd, COMMIT_RECON);
+		case "D3":
+			return () => exists(cwd, PATCH_BYPASS_SUMMARY);
+		case "D4":
+			return () => exists(cwd, KB_REPORT) && exists(cwd, ATTACK_SURFACE_ARCHITECTURE);
+		case "D5":
+			return () => exists(cwd, SAST_REPORT);
+		case "D6":
+			return () => exists(cwd, MANUAL_ATTACK_SURFACE) && exists(cwd, PROBE_SUMMARY);
+		case "D7":
+			return () => exists(cwd, AUTHZ_MATRIX);
+		case "D8":
+			return () => exists(cwd, CROSS_SERVICE);
+		case "D9":
+			return () => exists(cwd, CHAMBER_INDEX);
+		case "D10":
+			return () => exists(cwd, INTENT_RECONCILIATION);
+		case "D11":
+			return () => exists(cwd, VARIANT_SUMMARY);
+		case "D12":
+			return () => {
+				const dirs = listFindingDirs(cwd);
+				return dirs.length === 0 || dirs.every((d) => findingHasPoc(d.path));
+			};
+		case "D13":
+			return () => {
+				const dirs = listAllFindingDirs(cwd);
+				return dirs.length === 0 || dirs.every((d) => findingHasReport(d.path));
+			};
+		case "D14":
+			return () => exists(cwd, FINAL_REPORT);
+		default:
+			return () => true;
+	}
+}
+
+interface PhaseSpec {
+	name: string;
+	agent: AgentDefinition | undefined;
+	missingMessage: string;
+	statusLabel: string;
+}
+
+async function runOne(
+	cwd: string,
+	audit: AuditRunState,
+	spec: PhaseSpec,
+	hasGit: boolean,
+	signal: AbortSignal | undefined,
+	ui: DeepUiHooks | undefined,
+	agentRuntime?: AgentRuntimeModel,
+): Promise<void> {
+	await runAgentPhase({
+		cwd,
+		audit,
+		phaseName: spec.name,
+		statusKey: "piolium-deep",
+		statusLabel: spec.statusLabel,
+		agent: spec.agent,
+		missingAgentMessage: spec.missingMessage,
+		task: buildTask(spec.name, cwd, hasGit),
+		gate: gateFor(spec.name, cwd),
+		mode: "deep",
+		ui,
+		agentRuntime,
+		...(signal ? { signal } : {}),
+	});
+}
+
+async function runFanout3(
+	cwd: string,
+	audit: AuditRunState,
+	specs: PhaseSpec[],
+	hasGit: boolean,
+	signal: AbortSignal | undefined,
+	ui: DeepUiHooks | undefined,
+	agentRuntime?: AgentRuntimeModel,
+): Promise<{ failed: boolean }> {
+	const scheduler = new Scheduler({ maxConcurrent: 3, ...(signal ? { signal } : {}) });
+	const settled = await Promise.allSettled(
+		specs.map((s) =>
+			scheduler.enqueue({
+				id: s.name,
+				run: (sig) => runOne(cwd, audit, s, hasGit, sig, ui, agentRuntime),
+			}),
+		),
+	);
+	scheduler.dispose();
+	return { failed: settled.some((r) => r.status === "rejected") };
+}
+
+async function runPerFinding(
+	cwd: string,
+	audit: AuditRunState,
+	phase: "D12" | "D13",
+	agent: AgentDefinition | undefined,
+	dirs: FindingDir[],
+	signal: AbortSignal | undefined,
+	ui: DeepUiHooks | undefined,
+	agentRuntime?: AgentRuntimeModel,
+): Promise<{ failed: boolean }> {
+	if (!agent) {
+		await applyPhaseStatus(cwd, audit, phase, {
+			status: "failed",
+			error: `agent missing for ${phase}`,
+		});
+		return { failed: true };
+	}
+	await applyPhaseStatus(cwd, audit, phase, { status: "in_progress" });
+	if (dirs.length === 0) {
+		await applyPhaseStatus(cwd, audit, phase, { status: "skipped" });
+		return { failed: false };
+	}
+	const maxAttempts = PER_FINDING_MAX_RETRIES + 1;
+	const scheduler = new Scheduler({ maxConcurrent: 3, ...(signal ? { signal } : {}) });
+	const settled = await Promise.allSettled(
+		dirs.map((d) =>
+			scheduler.enqueue({
+				id: `${phase}:${d.id}`,
+				run: async (sig) => {
+					const phaseName = `${phase}:${d.id}`;
+					const gate = () => perFindingGate(phase, d.path);
+					if (gate()) {
+						await applyPhaseStatus(cwd, audit, phaseName, {
+							status: "complete",
+							attempt: audit.phases[phaseName]?.attempt ?? 0,
+							max_attempts: maxAttempts,
+							retry_backoff_ms: null,
+							next_retry_at: null,
+							last_error: null,
+						});
+						return;
+					}
+
+					let lastError = "Unknown error";
+					for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+						try {
+							await applyPhaseStatus(cwd, audit, phaseName, {
+								status: "in_progress",
+								attempt,
+								max_attempts: maxAttempts,
+								retry_backoff_ms: null,
+								next_retry_at: null,
+								error: `Attempt ${attempt}/${maxAttempts} running.`,
+							});
+							await runAgentPhase({
+								cwd,
+								audit,
+								phaseName,
+								statusKey: "piolium-deep",
+								statusLabel: `● ${phase} ${d.id} (${attempt}/${maxAttempts})`,
+								agent,
+								missingAgentMessage: `agent missing for ${phase}`,
+								task: `${buildTask(phase, cwd, true)}\n\nFinding directory: ${d.path}\nSlug: ${d.slug}`,
+								gate,
+								mode: "deep",
+								ui,
+								agentRuntime,
+								timeoutMs: PER_FINDING_ATTEMPT_TIMEOUT_MS,
+								maxRetries: 0,
+								...(sig ? { signal: sig } : {}),
+							});
+							return;
+						} catch (err) {
+							lastError = errorMessage(err);
+							if (gate()) {
+								await applyPhaseStatus(cwd, audit, phaseName, {
+									status: "complete",
+									attempt,
+									max_attempts: maxAttempts,
+									retry_backoff_ms: null,
+									next_retry_at: null,
+									last_error: null,
+								});
+								return;
+							}
+
+							if (attempt >= maxAttempts) {
+								await applyPhaseStatus(cwd, audit, phaseName, {
+									status: "failed",
+									error: `Failed after ${PER_FINDING_MAX_RETRIES} retries: ${lastError}`,
+									attempt,
+									max_attempts: maxAttempts,
+									retry_backoff_ms: null,
+									next_retry_at: null,
+									last_error: lastError,
+								});
+								throw err;
+							}
+
+							const backoffMs = retryBackoffMs(attempt);
+							const nextRetryAt = new Date(Date.now() + backoffMs).toISOString();
+							await applyPhaseStatus(cwd, audit, phaseName, {
+								status: "in_progress",
+								error: `Attempt ${attempt}/${maxAttempts} failed: ${lastError}. Retrying at ${nextRetryAt}.`,
+								attempt,
+								max_attempts: maxAttempts,
+								retry_backoff_ms: backoffMs,
+								next_retry_at: nextRetryAt,
+								last_error: lastError,
+							});
+							await sleep(backoffMs, sig);
+						}
+					}
+				},
+			}),
+		),
+	);
+	scheduler.dispose();
+	const failed = settled.some((r) => r.status === "rejected");
+	await applyPhaseStatus(cwd, audit, phase, {
+		status: failed ? "failed" : "complete",
+		...(failed ? { error: `Some per-finding ${phase} runs failed.` } : {}),
+	});
+	return { failed };
+}
+
+export interface DeepTransientCleanupResult {
+	summaryPath: string;
+	removed: string[];
+	missing: string[];
+	retained: string[];
+}
+
+export function cleanupDeepTransientArtifacts(cwd: string): DeepTransientCleanupResult {
+	ensureAttackSurfaceDir(cwd);
+	const removed: string[] = [];
+	const missing: string[] = [];
+	for (const rel of DEEP_TRANSIENT_PATHS) {
+		const abs = join(cwd, rel);
+		if (!existsSync(abs)) {
+			missing.push(rel);
+			continue;
+		}
+		rmSync(abs, { recursive: true, force: true });
+		removed.push(rel);
+	}
+	const result: DeepTransientCleanupResult = {
+		summaryPath: DEEP_CLEANUP_SUMMARY,
+		removed,
+		missing,
+		retained: [
+			"piolium/attack-surface/",
+			"piolium/findings/",
+			"piolium/findings-theoretical/",
+			"piolium/final-audit-report.md",
+			"piolium/audit-state.json",
+		],
+	};
+	writeFileSync(join(cwd, DEEP_CLEANUP_SUMMARY), `${JSON.stringify(result, null, "\t")}\n`);
+	return result;
+}
+
+/** Post-D14 finalize: file-state stamp note + transient cleanup, folded inline. */
+function finalizeDeep(cwd: string): void {
+	cleanupDeepTransientArtifacts(cwd);
+}
+
+export async function runDeepAudit(opts: RunDeepOptions): Promise<RunDeepResult> {
+	const { cwd, signal, ui } = opts;
+	ui?.setStatus?.("piolium-deep", "● preparing recon");
+	const recon = await runReconAsync(cwd, { signal });
+	ensureAttackSurfaceDir(cwd);
+	ui?.setStatus?.("piolium-deep", "● scanning candidate files");
+	const candidateScan = await runCandidateScanAsync(cwd, { signal });
+	ui?.notify?.(
+		`Candidate scan: ${candidateScan.candidateCount} match(es) across ${candidateScan.candidateFiles} file(s).`,
+		"info",
+	);
+	let audit = pickResume(cwd, opts.forceFresh ?? false, Boolean(opts.only?.length));
+	if (!audit) {
+		audit = await initAudit(cwd, {
+			mode: "deep",
+			...(recon.commit ? { commit: recon.commit } : { commit: null }),
+			...(recon.branch ? { branch: recon.branch } : { branch: "nogit" }),
+			...(recon.repository ? { repository: recon.repository } : {}),
+			history_available: recon.historyAvailable,
+			agent_sdk: "pi",
+		});
+	}
+
+	const { agents } = loadAgents({ cwd });
+	const specs: Record<string, PhaseSpec> = {
+		D1: {
+			name: "D1",
+			agent: agents.get("cve-scout"),
+			missingMessage: "cve-scout missing",
+			statusLabel: "● D1 intel-cve",
+		},
+		D2: {
+			name: "D2",
+			agent: agents.get("history-miner"),
+			missingMessage: "history-miner missing",
+			statusLabel: "● D2 intel-history",
+		},
+		D3: {
+			name: "D3",
+			agent: agents.get("patch-auditor"),
+			missingMessage: "patch-auditor missing",
+			statusLabel: "● D3 patch-audit",
+		},
+		D4: {
+			name: "D4",
+			agent: agents.get("threat-modeler"),
+			missingMessage: "threat-modeler missing",
+			statusLabel: "● D4 threat-model",
+		},
+		D5: {
+			name: "D5",
+			agent: agents.get("code-scanner"),
+			missingMessage: "code-scanner missing",
+			statusLabel: "● D5 code-scan",
+		},
+		D6: {
+			name: "D6",
+			agent: agents.get("probe-lead"),
+			missingMessage: "probe-lead missing",
+			statusLabel: "● D6 deep-probe",
+		},
+		D7: {
+			name: "D7",
+			agent: agents.get("access-auditor"),
+			missingMessage: "access-auditor missing",
+			statusLabel: "● D7 access-audit",
+		},
+		D8: {
+			name: "D8",
+			agent: agents.get("taint-tracer"),
+			missingMessage: "taint-tracer missing",
+			statusLabel: "● D8 taint-trace",
+		},
+		D9: {
+			name: "D9",
+			agent: agents.get("review-adjudicator"),
+			missingMessage: "review-adjudicator missing",
+			statusLabel: "● D9 review-panel",
+		},
+		D10: {
+			name: "D10",
+			agent: agents.get("context-reviewer"),
+			missingMessage: "context-reviewer missing",
+			statusLabel: "● D10 intent-reconcile",
+		},
+		D11: {
+			name: "D11",
+			agent: agents.get("variant-scanner"),
+			missingMessage: "variant-scanner missing",
+			statusLabel: "● D11 variant-sweep",
+		},
+		D12: {
+			name: "D12",
+			agent: agents.get("poc-author"),
+			missingMessage: "poc-author missing",
+			statusLabel: "● D12 poc-author",
+		},
+		D13: {
+			name: "D13",
+			agent: agents.get("finding-writer"),
+			missingMessage: "finding-writer missing",
+			statusLabel: "● D13 finding-finalize",
+		},
+		D14: {
+			name: "D14",
+			agent: agents.get("report-composer"),
+			missingMessage: "report-composer missing",
+			statusLabel: "● D14 report-compose",
+		},
+	};
+
+	const spec = (name: keyof typeof specs): PhaseSpec => {
+		const s = specs[name];
+		if (!s) throw new Error(`Internal: phase spec ${name} missing`);
+		return s;
+	};
+
+	let failed = false;
+	const want = (name: string) => shouldRun(name, opts.only);
+
+	const runSequential = async (name: string, fn: () => Promise<void>) => {
+		if (!want(name)) return;
+		ensurePrereqs(audit, name);
+		try {
+			await fn();
+		} catch {
+			failed = true;
+			throw new Error(`Phase ${name} failed`);
+		}
+	};
+
+	const skipNoGit = async (name: "D2" | "D3") => {
+		if (!want(name)) return;
+		ensurePrereqs(audit, name);
+		if (!recon.historyAvailable) {
+			await applyPhaseStatus(cwd, audit, name, {
+				status: "skipped",
+				error: "no git history available",
+			});
+			return;
+		}
+		try {
+			await runOne(cwd, audit, spec(name), true, signal, ui, opts.agentRuntime);
+		} catch {
+			failed = true;
+		}
+	};
+
+	try {
+		// [D1 ‖ D2] — D2 skipped when no git.
+		if (want("D1") || want("D2")) {
+			const wave: PhaseSpec[] = [];
+			if (want("D1")) {
+				ensurePrereqs(audit, "D1");
+				wave.push(spec("D1"));
+			}
+			if (want("D2") && recon.historyAvailable) {
+				ensurePrereqs(audit, "D2");
+				wave.push(spec("D2"));
+			} else {
+				await skipNoGit("D2");
+			}
+			if (wave.length > 0) {
+				const r = await runFanout3(
+					cwd,
+					audit,
+					wave,
+					recon.historyAvailable,
+					signal,
+					ui,
+					opts.agentRuntime,
+				);
+				if (r.failed) failed = true;
+			}
+		}
+
+		if (!failed) await skipNoGit("D3");
+
+		if (!failed) {
+			await runSequential("D4", () =>
+				runOne(cwd, audit, spec("D4"), recon.historyAvailable, signal, ui, opts.agentRuntime),
+			);
+
+			// Wave A: [D5 ‖ D7] (cap 2, within burst cap).
+			if (!failed && (want("D5") || want("D7"))) {
+				const waveA = [spec("D5"), spec("D7")].filter((s) => want(s.name));
+				for (const s of waveA) ensurePrereqs(audit, s.name);
+				const r = await runFanout3(
+					cwd,
+					audit,
+					waveA,
+					recon.historyAvailable,
+					signal,
+					ui,
+					opts.agentRuntime,
+				);
+				if (r.failed) failed = true;
+			}
+
+			// Wave B: D6 (own wave — a probe team uses the full burst cap).
+			if (!failed) {
+				await runSequential("D6", () =>
+					runOne(cwd, audit, spec("D6"), recon.historyAvailable, signal, ui, opts.agentRuntime),
+				);
+			}
+
+			if (!failed) {
+				await runSequential("D8", () =>
+					runOne(cwd, audit, spec("D8"), recon.historyAvailable, signal, ui, opts.agentRuntime),
+				);
+				await runSequential("D9", () =>
+					runOne(cwd, audit, spec("D9"), recon.historyAvailable, signal, ui, opts.agentRuntime),
+				);
+
+				// D10 Intent Reconciliation — skip-and-continue.
+				if (want("D10")) {
+					ensurePrereqs(audit, "D10");
+					try {
+						await runOne(cwd, audit, spec("D10"), recon.historyAvailable, signal, ui, opts.agentRuntime);
+					} catch {
+						await applyPhaseStatus(cwd, audit, "D10", {
+							status: "failed",
+							error: "policy: skip-and-continue",
+						});
+						ui?.notify?.("D10 Intent Reconciliation skipped (skip-and-continue).", "warning");
+					}
+				}
+
+				// Consolidate chamber-survived (d9-) + variant (d11-) drafts into
+				// severity-prefixed finding dirs, then route triage-skip ones to
+				// the theoretical bucket.
+				const consolidate = () => {
+					const consolidation = consolidateDrafts(cwd, ["d9-", "d11-"]);
+					writeFileSync(
+						join(cwd, CONSOLIDATION_MANIFEST),
+						`${JSON.stringify(
+							{
+								generated_at: new Date().toISOString(),
+								source_prefixes: ["d9-", "d11-"],
+								promoted: consolidation.promoted,
+								dropped: consolidation.dropped,
+							},
+							null,
+							"\t",
+						)}\n`,
+					);
+					partitionFindings(cwd);
+				};
+				consolidate();
+
+				await runSequential("D11", () =>
+					runOne(cwd, audit, spec("D11"), recon.historyAvailable, signal, ui, opts.agentRuntime),
+				);
+				consolidate();
+
+				if (want("D12")) {
+					ensurePrereqs(audit, "D12");
+					const r = await runPerFinding(
+						cwd,
+						audit,
+						"D12",
+						spec("D12").agent,
+						listFindingDirs(cwd),
+						signal,
+						ui,
+						opts.agentRuntime,
+					);
+					if (r.failed) failed = true;
+					if (!failed) partitionFindings(cwd);
+				}
+				if (!failed && want("D13")) {
+					ensurePrereqs(audit, "D13");
+					const r = await runPerFinding(
+						cwd,
+						audit,
+						"D13",
+						spec("D13").agent,
+						listAllFindingDirs(cwd),
+						signal,
+						ui,
+						opts.agentRuntime,
+					);
+					if (r.failed) failed = true;
+				}
+				if (!failed && want("D14")) {
+					await runSequential("D14", () =>
+						runOne(cwd, audit, spec("D14"), recon.historyAvailable, signal, ui, opts.agentRuntime),
+					);
+					if (!failed) finalizeDeep(cwd);
+				}
+			}
+		}
+	} catch {
+		failed = true;
+	}
+
+	await markAuditStatus(cwd, audit.audit_id, failed ? "failed" : "complete");
+	const fresh =
+		readAuditState(cwd).state?.audits.find((a) => a.audit_id === audit.audit_id) ?? audit;
+	const phases: Record<string, "complete" | "failed" | "skipped"> = {};
+	for (const [name, p] of Object.entries(fresh.phases)) {
+		if (p.status === "complete" || p.status === "failed" || p.status === "skipped") {
+			phases[name] = p.status;
+		}
+	}
+	ui?.notify?.(failed ? "Deep audit failed." : "Deep audit complete.", failed ? "error" : "info");
+	return { auditId: audit.audit_id, status: failed ? "failed" : "complete", phases };
+}