@vigolium/piolium 0.0.1

package/extensions/piolium/modes/balanced.ts

@@ -0,0 +1,750 @@
+/**
+ * Balanced mode orchestrator (`/piolium-balanced`).
+ *
+ * Pipeline (command-defs/balanced.md, archon-audit @ 2026-05-16):
+ *
+ *   B1 Intel Sweep            (cve-scout)
+ *   → B2 Threat Model         (threat-modeler)
+ *   → [B3 Code Scan ‖ B4 Targeted Probe]   (code-scanner ‖ probe-lead)
+ *   → B5 Review Panel + FP    (review-adjudicator)
+ *   → B6 Intent Reconciliation (context-reviewer; skip-and-continue)
+ *   → B7 PoC Authoring        (poc-author, per finding)
+ *   → B8 Finding Finalize     (finding-writer, per finding, both buckets)
+ *   → B9 Report Compose       (report-composer + inline cleanup/file-state)
+ *
+ * Differences from upstream (deliberate, MVP-grade):
+ *   - Chamber B5 is a single review-adjudicator run doing inline Ideator +
+ *     Devil's-Advocate work plus the FP-check / triage tail; we don't drive
+ *     a real multi-round debate.
+ *   - The probe team (B4) is a single probe-lead run that folds the
+ *     reasoner roles into its own prompt.
+ *   - Consolidation/partition is done in TS (findings.ts) rather than via
+ *     the upstream python helpers, but routes triage-skip drafts and
+ *     non-executed PoCs into `findings-theoretical/` the same way.
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, 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 {
+	consolidateDrafts,
+	findingsDraftDir,
+	listAllFindingDirs,
+	listFindingDirs,
+	partitionFindings,
+} from "../findings.ts";
+import { runReconAsync } from "../recon.ts";
+import { Scheduler } from "../scheduler.ts";
+import { type PhaseUiHooks, runAgentPhase } from "./phase-runner.ts";
+
+export type BalancedUiHooks = PhaseUiHooks;
+
+export interface RunBalancedOptions {
+	cwd: string;
+	signal?: AbortSignal;
+	ui?: BalancedUiHooks;
+	forceFresh?: boolean;
+	agentRuntime?: AgentRuntimeModel;
+}
+
+export interface RunBalancedResult {
+	auditId: string;
+	status: "complete" | "failed";
+	phases: Record<string, "complete" | "failed" | "skipped">;
+}
+
+export const BALANCED_ATTACK_SURFACE_DIR = "piolium/attack-surface";
+export const BALANCED_KB_REPORT = `${BALANCED_ATTACK_SURFACE_DIR}/knowledge-base-report.md`;
+export const BALANCED_ADVISORY_SUMMARY = `${BALANCED_ATTACK_SURFACE_DIR}/advisory-summary.md`;
+export const BALANCED_SAST_REPORT = `${BALANCED_ATTACK_SURFACE_DIR}/source-sink-flows-all-severities.md`;
+export const BALANCED_ATTACK_SURFACE_INVENTORY = `${BALANCED_ATTACK_SURFACE_DIR}/manual-attack-surface-inventory.md`;
+export const BALANCED_PROBE_SUMMARY = `${BALANCED_ATTACK_SURFACE_DIR}/balanced-probe-summary.md`;
+export const BALANCED_CHAMBER_SUMMARY = `${BALANCED_ATTACK_SURFACE_DIR}/balanced-chamber-summary.md`;
+export const BALANCED_INTENT_RECONCILIATION = `${BALANCED_ATTACK_SURFACE_DIR}/intent-reconciliation.md`;
+export const BALANCED_VERIFICATION_SUMMARY = `${BALANCED_ATTACK_SURFACE_DIR}/balanced-verification-summary.md`;
+export const BALANCED_CLEANUP_SUMMARY = `${BALANCED_ATTACK_SURFACE_DIR}/balanced-cleanup-summary.json`;
+export const BALANCED_CONSOLIDATION_MANIFEST = `${BALANCED_ATTACK_SURFACE_DIR}/balanced-consolidation-manifest.json`;
+const BALANCED_TRANSIENT_PATHS = [
+	"piolium/tmp",
+	"piolium/probe-workspace",
+	"piolium/chamber-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 FINAL_REPORT = "piolium/final-audit-report.md";
+
+function exists(cwd: string, rel: string): boolean {
+	return existsSync(join(cwd, rel));
+}
+
+function gateB1(cwd: string) {
+	return () => exists(cwd, BALANCED_ADVISORY_SUMMARY);
+}
+function gateB2(cwd: string) {
+	return () => exists(cwd, BALANCED_KB_REPORT);
+}
+function gateB3(cwd: string) {
+	return () =>
+		exists(cwd, BALANCED_SAST_REPORT) || hasDraftPrefix(cwd, "b3-") || hasDraftPrefix(cwd, "p4-");
+}
+function gateB4(cwd: string) {
+	return () => exists(cwd, BALANCED_ATTACK_SURFACE_INVENTORY) && exists(cwd, BALANCED_PROBE_SUMMARY);
+}
+function gateB5(cwd: string) {
+	return () =>
+		exists(cwd, BALANCED_CHAMBER_SUMMARY) || hasDraftPrefix(cwd, "b5-") || hasDraftPrefix(cwd, "p8-");
+}
+function gateB6(cwd: string) {
+	// Intent Reconciliation is best-effort: the artifact is nice-to-have but
+	// the phase never blocks the pipeline.
+	return () => exists(cwd, BALANCED_INTENT_RECONCILIATION);
+}
+function gateB9(cwd: string) {
+	return () => exists(cwd, FINAL_REPORT);
+}
+
+function hasDraftPrefix(cwd: string, prefix: string): boolean {
+	const dir = findingsDraftDir(cwd);
+	if (!existsSync(dir)) return false;
+	return readdirSync(dir).some((f) => f.startsWith(prefix) && f.endsWith(".md"));
+}
+
+function pickResume(cwd: string, force: 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 !== "balanced") return undefined;
+	if (audit.status === "complete") return undefined;
+	return audit;
+}
+
+function buildB1Task(): string {
+	return [
+		"You are running Phase B1 (Intel Sweep) of /piolium-balanced.",
+		"",
+		"Goal: gather published security advisories (CVE/GHSA/OSV) and high-level dependency intelligence relevant to this repository.",
+		"",
+		`Required artifact: write \`${BALANCED_ADVISORY_SUMMARY}\` with sections:`,
+		"  ## Repository Identity",
+		"  ## Recent Advisories (last 24 months)",
+		"  ## Dependency Intelligence",
+		"  ## Architecture Hints",
+		"  ## Coverage Gaps",
+		"",
+		"Scope: cve-scout only. Do NOT run commit archaeology or patch-bypass (those are deep-only).",
+		"Stop after writing the file. Do not promote drafts or move to B2.",
+	].join("\n");
+}
+
+function buildB2Task(): string {
+	return [
+		"You are running Phase B2 (Threat Model) of /piolium-balanced.",
+		"",
+		`Required artifact: \`${BALANCED_KB_REPORT}\`. Sections:`,
+		"  ## Project Type & Components",
+		"  ## Trust Boundaries",
+		"  ## Data-Flow Slices (DFD)",
+		"  ## Control-Flow Slices (CFD)",
+		"  ## Framework Contracts and Hidden Control Channels",
+		"  ## Domain Attack Modes (apply security-threat-model and other relevant skills)",
+		"  ## Coverage Gaps",
+		"",
+		"BALANCED MODE: skip Domain Attack Research Modes B and C; skip Spec Gap Candidates and CodeQL Extraction Targets sections.",
+		"Framework-contract coverage must inventory middleware/proxy/runtime/header assumptions affecting auth, routing, tenant selection, debug/admin/preview behavior, method/path override, or cache keys.",
+		"",
+		`Read \`${BALANCED_ADVISORY_SUMMARY}\` if present. If \`piolium/INFO.md\` exists, treat it as authoritative for the sections it covers.`,
+		"Stop after writing the report. Do not start B3.",
+	].join("\n");
+}
+
+function buildB3Task(): string {
+	return [
+		"You are running Phase B3 (Code Scan) of /piolium-balanced.",
+		"",
+		"Goal: run the cheapest available static analysis pass. Required artifacts:",
+		`  - \`${BALANCED_SAST_REPORT}\` summary`,
+		"  - draft findings under `piolium/findings-draft/b3-NNN-<slug>.md`",
+		"",
+		"Read `piolium/attack-surface/candidates-summary.md` and `piolium/attack-surface/candidates.jsonl` first. Prioritize precise/high-score candidate files, then validate normally.",
+		"BALANCED MODE: run built-in CodeQL security suites + Semgrep Pro only. No custom queries/rules, no structural extraction, no SpotBugs/agentic-actions.",
+		"Then perform an inline enrichment pass: classify each SAST finding as likely-security / likely-correctness / likely-environment-only and drop the latter two.",
+		"If neither CodeQL nor Semgrep is available, fall back to grep+read for command injection, path traversal, SSRF, broken authn/z, hardcoded secrets, weak crypto.",
+		"Cap drafts at 20. Each draft frontmatter MUST include: id (b3-NNN), phase (B3), slug, severity (critical|high|medium|low|info).",
+	].join("\n");
+}
+
+function buildB4Task(): string {
+	return [
+		"You are running Phase B4 (Targeted Probe) of /piolium-balanced.",
+		"",
+		"This is a SINGLE-TEAM, SINGLE-PASS probe — not the deep multi-team probe. You act as Probe Strategist, Backward Reasoner and Evidence Harvester inline.",
+		"",
+		"Steps you must complete in order, all in one session:",
+		`  1. Read \`${BALANCED_KB_REPORT}\`. If absent, fail with a clear note.`,
+		"  2. Read `piolium/attack-surface/candidates-summary.md` and pick one or two highest-impact attack-surface slices.",
+		`  3. Write \`${BALANCED_ATTACK_SURFACE_INVENTORY}\` with entry points, public routes/URLs, attacker sources, sinks, hidden control channels, middleware/proxy assumptions, and key files.`,
+		"  4. Generate hypotheses (Pre-Mortem + Abductive reasoning).",
+		"  5. Verify hypotheses with `read`/`grep`/`bash` — file:line evidence required; apply causal challenge before any INVALIDATED verdict.",
+		"  6. Write verified hypotheses as drafts to `piolium/findings-draft/b4-NNN-<slug>.md`.",
+		`  7. Write \`${BALANCED_PROBE_SUMMARY}\` summarising probe execution and coverage.`,
+		"Transient scratch, if needed: `piolium/tmp/piolium/balanced-probe/`.",
+		"",
+		"Cap drafts at 10. Each draft frontmatter MUST include id (b4-NNN), phase (B4), slug, severity.",
+	].join("\n");
+}
+
+function buildB5Task(): string {
+	return [
+		"You are running Phase B5 (Review Panel + FP Check) of /piolium-balanced.",
+		"",
+		"There is no separate Ideator / Tracer / Advocate run in balanced mode — you do all of those roles inline, then run the FP/triage tail.",
+		"",
+		"Inputs:",
+		`  - \`${BALANCED_KB_REPORT}\``,
+		`  - \`${BALANCED_ATTACK_SURFACE_INVENTORY}\``,
+		`  - \`${BALANCED_SAST_REPORT}\``,
+		"  - `piolium/attack-surface/candidates-summary.md`",
+		"  - `piolium/findings-draft/b3-*.md` (SAST drafts)",
+		"  - `piolium/findings-draft/b4-*.md` (Probe drafts)",
+		"",
+		"Steps:",
+		"  1. Read all draft findings.",
+		"  2. For each draft: act as Ideator (challenge it), Devil's-Advocate (try to reject it), and Synthesizer (final verdict). Chain/extend pre-seeded probe hypotheses rather than regenerating.",
+		"  3. Do not delete weak drafts. Mark rejected drafts with frontmatter `status: rejected-fp` and `rejection_reason: <short reason>`.",
+		"  4. fp-check tail: for surviving CRITICAL drafts, do a cold re-verification pass; HIGH/MEDIUM rely on the Advocate challenge.",
+		"  5. Triage sweep: write `Triage-Priority` (P0/P1/P2/skip), `Triage-Exploitability`, `Triage-Impact`, `Triage-Reasoning` into each surviving draft's frontmatter. `skip` is reversible (routed to the theoretical bucket later).",
+		"  6. For surviving drafts, copy them to `piolium/findings-draft/b5-NNN-<slug>.md` with frontmatter `status: valid`, severity normalised to critical|high|medium|low|info, and the Triage-* fields preserved.",
+		`  7. Write the durable chamber summary to \`${BALANCED_CHAMBER_SUMMARY}\`.`,
+		"Transient scratch, if needed: `piolium/tmp/piolium/balanced-chamber/`.",
+		"",
+		"Cap surviving drafts at 12.",
+	].join("\n");
+}
+
+function buildB6Task(): string {
+	return [
+		"You are running Phase B6 (Intent Reconciliation) of /piolium-balanced — AUDIT CONTRACT.",
+		"",
+		"Runs after the B5 FP/triage tail (every VALID draft already carries a `Triage-Priority`) and BEFORE any PoC effort. Reconcile each surviving finding against what the project documents as intentional design, an exposed feature, or an explicitly in-scope risk.",
+		"",
+		"Inputs:",
+		"  - Findings drafts: `piolium/findings-draft/b5-*.md` (evaluate every draft with `status: valid`).",
+		`  - KB: \`${BALANCED_KB_REPORT}\` (read Architecture Model, Domain Attack Research, Known False-Positive Sources).`,
+		"  - `piolium/INFO.md` `## Known False-Positive Sources` if present.",
+		"",
+		"For each VALID draft: do a bounded read of ONLY the `file:line` it cites, reconcile against documented intent, and write `Intent-Verdict` / `Intent-Source` / `Intent-Quote` into the draft frontmatter. For `intentional-design` or `documented-feature` whose decisive basis is `confidence: strong` (or operator INFO.md), 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 human-readable report to \`${BALANCED_INTENT_RECONCILIATION}\`.`,
+		"",
+		"This phase is best-effort: if you cannot complete, still write a minimal intent-reconciliation.md noting the gap. It must never suppress a finding outright.",
+	].join("\n");
+}
+
+function buildB7Task(findingDir: string, slug: string): string {
+	return [
+		"You are running Phase B7 (PoC Authoring) for a single finding in /piolium-balanced.",
+		"",
+		`Finding directory: ${findingDir}`,
+		`Slug: ${slug}`,
+		"",
+		"Steps:",
+		"  1. Read `draft.md` in the finding directory.",
+		"  2. Build a minimal proof-of-concept demonstrating exploitability.",
+		"  3. Write the PoC to `<finding-dir>/poc.{py|sh|js|rb|go}` (pick the most natural language).",
+		"  4. Write evidence (commands run, observed output) to `<finding-dir>/evidence/`.",
+		"  5. Write `PoC-Status: executed` (or `not-executed` with a reason) back into `draft.md` frontmatter.",
+		"  6. If exploitation requires an unavailable runtime, write a 'theoretical PoC' note explaining the chain and set `PoC-Status: not-executed`.",
+		"",
+		"You are NOT responsible for report.md — that is Phase B8. Stop after the PoC + evidence + PoC-Status are written.",
+	].join("\n");
+}
+
+function buildB8Task(findingDir: string): string {
+	return [
+		"You are running Phase B8 (Finding Finalize / vuln-report) for a single finding.",
+		"",
+		`Finding directory: ${findingDir}`,
+		"",
+		"Steps:",
+		"  1. Read `draft.md`, `poc.*` (if any), and `evidence/` contents.",
+		"  2. Use the `vuln-report` skill if available; otherwise produce a GitHub-advisory-style report.",
+		"  3. Write the final report to `<finding-dir>/report.md` — must be > 500 bytes, with Summary, Details, Root Cause, Proof of concept & Evidence, Impact, Remediation sections.",
+		"  4. If this finding is in the theoretical bucket (no executed PoC), the 'Proof of concept & Evidence' section must state the no-PoC reason.",
+		"",
+		"Do not modify draft.md.",
+	].join("\n");
+}
+
+function buildB9Task(): string {
+	return [
+		"You are running Phase B9 (Report Compose) of /piolium-balanced.",
+		"",
+		"Steps:",
+		"  1. List every directory under `piolium/findings/` AND `piolium/findings-theoretical/`. Each MUST have a `report.md` of >500 bytes — if any are missing, fail with a clear error and DO NOT write the final report.",
+		"  2. Compose `piolium/final-audit-report.md` with:",
+		"     - Executive Summary (note: balanced mode — skipped vs deep: commit archaeology, patch-bypass, dedicated authz/cross-service phases, multi-round probing, variant analysis. Cold verification + intent reconciliation still run.)",
+		"     - Findings by Severity — confirmed (PoC-executed) findings only, with links to per-finding report.md",
+		"     - Theoretical / Unconfirmed Findings — `piolium/findings-theoretical/` entries, kept OUT of the Summary-of-Findings table",
+		`     - Intent Reconciliation summary (surface \`${BALANCED_INTENT_RECONCILIATION}\` if present)`,
+		`     - Attack Surface Summary linking \`${BALANCED_ATTACK_SURFACE_DIR}/\` artifacts`,
+		"     - Coverage Gaps, Methodology Notes",
+		"  3. Reference findings by their <id>-<slug> directory name.",
+		"",
+		"Stop after writing the final report.",
+	].join("\n");
+}
+
+async function runB3PlusB4Parallel(
+	cwd: string,
+	audit: AuditRunState,
+	codeScanner: AgentDefinition | undefined,
+	probeLead: AgentDefinition | undefined,
+	signal: AbortSignal | undefined,
+	ui: BalancedUiHooks | undefined,
+	agentRuntime?: AgentRuntimeModel,
+): Promise<{ failed: boolean }> {
+	const scheduler = new Scheduler({ maxConcurrent: 3, ...(signal ? { signal } : {}) });
+	const settled = await Promise.allSettled([
+		scheduler.enqueue({
+			id: "B3",
+			run: (sig) =>
+				runAgentPhase({
+					cwd,
+					audit,
+					phaseName: "B3",
+					statusKey: "piolium-balanced",
+					statusLabel: "● B3 code scan",
+					agent: codeScanner,
+					missingAgentMessage: "code-scanner agent missing",
+					task: buildB3Task(),
+					gate: gateB3(cwd),
+					mode: "balanced",
+					ui,
+					agentRuntime,
+					...(sig ? { signal: sig } : {}),
+				}),
+		}),
+		scheduler.enqueue({
+			id: "B4",
+			run: (sig) =>
+				runAgentPhase({
+					cwd,
+					audit,
+					phaseName: "B4",
+					statusKey: "piolium-balanced",
+					statusLabel: "● B4 targeted probe",
+					agent: probeLead,
+					missingAgentMessage: "probe-lead agent missing",
+					task: buildB4Task(),
+					gate: gateB4(cwd),
+					mode: "balanced",
+					ui,
+					agentRuntime,
+					...(sig ? { signal: sig } : {}),
+				}),
+		}),
+	]);
+	scheduler.dispose();
+	return { failed: settled.some((s) => s.status === "rejected") };
+}
+
+async function runPerFindingPhase(
+	cwd: string,
+	audit: AuditRunState,
+	phaseName: "B7" | "B8",
+	agent: AgentDefinition | undefined,
+	taskBuilder: (dir: string, slug: string) => string,
+	dirs: { id: string; slug: string; path: string }[],
+	ui: BalancedUiHooks | undefined,
+	signal: AbortSignal | undefined,
+	agentRuntime?: AgentRuntimeModel,
+): Promise<{ failed: boolean }> {
+	if (!agent) {
+		await applyPhaseStatus(cwd, audit, phaseName, {
+			status: "failed",
+			error: `agent missing for ${phaseName}`,
+		});
+		throw new Error(`agent missing for ${phaseName}`);
+	}
+	await applyPhaseStatus(cwd, audit, phaseName, { status: "in_progress" });
+	if (dirs.length === 0) {
+		await applyPhaseStatus(cwd, audit, phaseName, { status: "skipped" });
+		return { failed: false };
+	}
+	const scheduler = new Scheduler({ maxConcurrent: 3, ...(signal ? { signal } : {}) });
+	const results = await Promise.allSettled(
+		dirs.map((d) =>
+			scheduler.enqueue({
+				id: `${phaseName}:${d.id}`,
+				run: (sig) =>
+					runAgentPhase({
+						cwd,
+						audit,
+						phaseName: `${phaseName}:${d.id}`,
+						statusKey: "piolium-balanced",
+						statusLabel: `● ${phaseName} ${d.id}`,
+						agent,
+						missingAgentMessage: `agent missing for ${phaseName}`,
+						task: taskBuilder(d.path, d.slug),
+						gate: () =>
+							phaseName === "B7"
+								? readdirSync(d.path).some((f) => f.startsWith("poc.")) ||
+									existsSync(join(d.path, "poc.theoretical.md"))
+								: existsSync(join(d.path, "report.md")),
+						mode: "balanced",
+						ui,
+						agentRuntime,
+						...(sig ? { signal: sig } : {}),
+					}),
+			}),
+		),
+	);
+	scheduler.dispose();
+	const failed = results.some((r) => r.status === "rejected");
+	await applyPhaseStatus(cwd, audit, phaseName, {
+		status: failed ? "failed" : "complete",
+		...(failed ? { error: `Some per-finding ${phaseName} runs failed.` } : {}),
+	});
+	return { failed };
+}
+
+export interface BalancedCleanupResult {
+	summaryPath: string;
+	removed: string[];
+	missing: string[];
+	retained: string[];
+}
+
+export function cleanupBalancedTransientArtifacts(cwd: string): BalancedCleanupResult {
+	mkdirSync(join(cwd, BALANCED_ATTACK_SURFACE_DIR), { recursive: true });
+	const removed: string[] = [];
+	const missing: string[] = [];
+	for (const rel of BALANCED_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: BalancedCleanupResult = {
+		summaryPath: BALANCED_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, BALANCED_CLEANUP_SUMMARY), `${JSON.stringify(result, null, "\t")}\n`);
+	return result;
+}
+
+/**
+ * Post-B9 finalize: file-state stamp note + transient cleanup, folded inline
+ * (upstream balanced has no separate verify/cleanup tail phase).
+ */
+function finalizeBalanced(cwd: string): void {
+	mkdirSync(join(cwd, BALANCED_ATTACK_SURFACE_DIR), { recursive: true });
+	const confirmed = listFindingDirs(cwd);
+	const theoretical = listAllFindingDirs(cwd).filter(
+		(d) => !confirmed.some((c) => c.path === d.path),
+	);
+	const missingReports = listAllFindingDirs(cwd)
+		.filter((d) => !d.hasReport)
+		.map((d) => `${d.id}-${d.slug}`);
+	const cleanup = cleanupBalancedTransientArtifacts(cwd);
+	writeFileSync(
+		join(cwd, BALANCED_VERIFICATION_SUMMARY),
+		[
+			"# Balanced Verification & Cleanup",
+			"",
+			`Generated: ${new Date().toISOString()}`,
+			"",
+			"## Verification",
+			"",
+			"- Scope: package verification; live target confirmation remains `/piolium-confirm`.",
+			`- Confirmed findings: ${confirmed.length}`,
+			`- Theoretical findings: ${theoretical.length}`,
+			`- Missing report.md: ${missingReports.length > 0 ? missingReports.join(", ") : "none"}`,
+			"",
+			"## File-State Stamp",
+			"",
+			"- Per-file hashes for incremental scope are persisted to `piolium/file-state.json` by the scan layer; this run records the audit id that touched each file.",
+			"",
+			"## Cleanup",
+			"",
+			`- Removed: ${cleanup.removed.length > 0 ? cleanup.removed.map((p) => `\`${p}\``).join(", ") : "(none)"}`,
+			`- Cleanup summary: \`${cleanup.summaryPath}\``,
+			"",
+		].join("\n"),
+	);
+}
+
+export async function runBalancedAudit(opts: RunBalancedOptions): Promise<RunBalancedResult> {
+	const { cwd, signal, ui } = opts;
+	ui?.setStatus?.("piolium-balanced", "● preparing recon");
+	const recon = await runReconAsync(cwd, { signal });
+	mkdirSync(join(cwd, BALANCED_ATTACK_SURFACE_DIR), { recursive: true });
+	ui?.setStatus?.("piolium-balanced", "● 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);
+	if (!audit) {
+		audit = await initAudit(cwd, {
+			mode: "balanced",
+			...(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 cveScout = agents.get("cve-scout");
+	const threatModeler = agents.get("threat-modeler");
+	const codeScanner = agents.get("code-scanner");
+	const probeLead = agents.get("probe-lead");
+	const reviewAdjudicator = agents.get("review-adjudicator");
+	const contextReviewer = agents.get("context-reviewer");
+	const pocAuthor = agents.get("poc-author");
+	const findingWriter = agents.get("finding-writer");
+	const reportComposer = agents.get("report-composer");
+
+	let failed = false;
+
+	try {
+		// B1 Intel Sweep
+		await runAgentPhase({
+			cwd,
+			audit,
+			phaseName: "B1",
+			statusKey: "piolium-balanced",
+			statusLabel: "● B1 intel sweep",
+			agent: cveScout,
+			missingAgentMessage: "cve-scout agent missing",
+			task: buildB1Task(),
+			gate: gateB1(cwd),
+			mode: "balanced",
+			ui,
+			agentRuntime: opts.agentRuntime,
+			...(signal ? { signal } : {}),
+		});
+
+		// B2 Threat Model
+		await runAgentPhase({
+			cwd,
+			audit,
+			phaseName: "B2",
+			statusKey: "piolium-balanced",
+			statusLabel: "● B2 threat model",
+			agent: threatModeler,
+			missingAgentMessage: "threat-modeler agent missing",
+			task: buildB2Task(),
+			gate: gateB2(cwd),
+			mode: "balanced",
+			ui,
+			agentRuntime: opts.agentRuntime,
+			...(signal ? { signal } : {}),
+		});
+
+		// B3 + B4 in parallel
+		const par = await runB3PlusB4Parallel(
+			cwd,
+			audit,
+			codeScanner,
+			probeLead,
+			signal,
+			ui,
+			opts.agentRuntime,
+		);
+		if (par.failed) failed = true;
+
+		// B5 Review Panel + FP Check
+		if (!failed) {
+			await runAgentPhase({
+				cwd,
+				audit,
+				phaseName: "B5",
+				statusKey: "piolium-balanced",
+				statusLabel: "● B5 review panel",
+				agent: reviewAdjudicator,
+				missingAgentMessage: "review-adjudicator agent missing",
+				task: buildB5Task(),
+				gate: gateB5(cwd),
+				mode: "balanced",
+				ui,
+				agentRuntime: opts.agentRuntime,
+				...(signal ? { signal } : {}),
+			});
+		}
+
+		// B6 Intent Reconciliation (best-effort; skip-and-continue).
+		if (!failed) {
+			try {
+				await runAgentPhase({
+					cwd,
+					audit,
+					phaseName: "B6",
+					statusKey: "piolium-balanced",
+					statusLabel: "● B6 intent reconciliation",
+					agent: contextReviewer,
+					missingAgentMessage: "context-reviewer agent missing",
+					task: buildB6Task(),
+					gate: gateB6(cwd),
+					mode: "balanced",
+					ui,
+					agentRuntime: opts.agentRuntime,
+					...(signal ? { signal } : {}),
+				});
+			} catch {
+				// Intent Reconciliation never blocks the pipeline.
+				await applyPhaseStatus(cwd, audit, "B6", {
+					status: "failed",
+					error: "policy: skip-and-continue",
+				});
+				ui?.notify?.("B6 Intent Reconciliation skipped (skip-and-continue).", "warning");
+			}
+
+			// Consolidate chamber-survived drafts (b5-*) into severity-prefixed
+			// findings/<C|H|M><N>-<slug>/. The triager / B6 may have set
+			// Triage-Priority: skip on some drafts.
+			const consolidation = consolidateDrafts(cwd, ["b5-"]);
+			const manifest = {
+				generated_at: new Date().toISOString(),
+				source_prefixes: ["b5-"],
+				promoted: consolidation.promoted.map((entry) => ({
+					id: entry.id,
+					slug: entry.slug,
+					severity: entry.severity,
+					original_id: entry.originalId,
+					...(entry.phase ? { phase: entry.phase } : {}),
+					source_path: entry.sourcePath,
+					finding_dir: entry.findingDir,
+				})),
+				dropped: consolidation.dropped.map((entry) => ({
+					original_id: entry.originalId,
+					severity: entry.severity,
+					source_path: entry.sourcePath,
+					reason: entry.reason,
+				})),
+			};
+			writeFileSync(
+				join(cwd, BALANCED_CONSOLIDATION_MANIFEST),
+				`${JSON.stringify(manifest, null, "\t")}\n`,
+			);
+			// Route triage-skip / intent-skip drafts straight to the
+			// theoretical bucket before any PoC effort.
+			const part = partitionFindings(cwd);
+			ui?.notify?.(
+				`B5/B6 promoted ${consolidation.promoted.length} finding(s); ${part.theoretical.length} routed to theoretical; dropped ${consolidation.dropped.length}.`,
+				"info",
+			);
+		}
+
+		// B7 — per-finding PoC (confirmed bucket only).
+		if (!failed) {
+			const r = await runPerFindingPhase(
+				cwd,
+				audit,
+				"B7",
+				pocAuthor,
+				buildB7Task,
+				listFindingDirs(cwd),
+				ui,
+				signal,
+				opts.agentRuntime,
+			);
+			if (r.failed) failed = true;
+			// Demote any finding whose PoC did not execute into theoretical.
+			if (!failed) partitionFindings(cwd);
+		}
+
+		// B8 — per-finding finalisation over BOTH buckets.
+		if (!failed) {
+			const r = await runPerFindingPhase(
+				cwd,
+				audit,
+				"B8",
+				findingWriter,
+				(dir) => buildB8Task(dir),
+				listAllFindingDirs(cwd),
+				ui,
+				signal,
+				opts.agentRuntime,
+			);
+			if (r.failed) failed = true;
+		}
+
+		// B9 — final report assembly + inline cleanup/file-state stamp.
+		if (!failed) {
+			await runAgentPhase({
+				cwd,
+				audit,
+				phaseName: "B9",
+				statusKey: "piolium-balanced",
+				statusLabel: "● B9 report compose",
+				agent: reportComposer,
+				missingAgentMessage: "report-composer agent missing",
+				task: buildB9Task(),
+				gate: gateB9(cwd),
+				mode: "balanced",
+				ui,
+				agentRuntime: opts.agentRuntime,
+				...(signal ? { signal } : {}),
+			});
+			if (!failed) finalizeBalanced(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 ? "Balanced audit failed." : "Balanced audit complete.",
+		failed ? "error" : "info",
+	);
+	return { auditId: audit.audit_id, status: failed ? "failed" : "complete", phases };
+}