@vigolium/piolium 0.0.1

package/extensions/piolium/modes/merge.ts

@@ -0,0 +1,204 @@
+/**
+ * Merge mode (`/piolium-merge`).
+ *
+ * Combines multiple `piolium/` result trees into one. Two stages:
+ *
+ *   M1-M3 (deterministic): copy + collision-rename + per-finding validation.
+ *   M4-M7 (agent-driven):  semantic dedup + quarantine + renumber + final report.
+ *
+ * MVP scope:
+ *   - The deterministic stage is fully implemented in TypeScript here.
+ *   - The agent-driven stage runs as a single report-composer pass with
+ *     a long task prompt covering all of M2-M7.
+ *
+ * Each input directory is identified by an alias (`a`, `b`, ...) that gets
+ * prepended to colliding finding ids so the dedup agent has clean inputs.
+ */
+
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	renameSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import type { AgentRuntimeModel } from "../agent-runner.ts";
+import { loadAgents } from "../agents.ts";
+import { applyPhaseStatus, initAudit, markAuditStatus } from "../audit-state.ts";
+import { runReconAsync } from "../recon.ts";
+import { type PhaseUiHooks, runAgentPhase } from "./phase-runner.ts";
+
+export interface RunMergeOptions {
+	cwd: string;
+	/** Source `piolium/` trees to merge. Must be ≥2. */
+	sources: string[];
+	signal?: AbortSignal;
+	ui?: PhaseUiHooks;
+	agentRuntime?: AgentRuntimeModel;
+}
+
+export interface RunMergeResult {
+	auditId: string;
+	status: "complete" | "failed";
+	mergedFindings: string[];
+}
+
+const ATTACK_SURFACE_DIR = "piolium/attack-surface";
+export const MERGE_ATTACK_SURFACE_SUMMARY = `${ATTACK_SURFACE_DIR}/merge-summary.md`;
+
+function aliasFor(index: number): string {
+	return String.fromCharCode("a".charCodeAt(0) + index);
+}
+
+function copyTree(src: string, dest: string): void {
+	cpSync(src, dest, { recursive: true });
+}
+
+function copyFindings(src: string, dest: string, alias: string): string[] {
+	const srcFindings = join(src, "findings");
+	if (!existsSync(srcFindings)) return [];
+	const destFindings = join(dest, "findings");
+	mkdirSync(destFindings, { recursive: true });
+	const written: string[] = [];
+	for (const entry of readdirSync(srcFindings)) {
+		const srcDir = join(srcFindings, entry);
+		if (!statSync(srcDir).isDirectory()) continue;
+		const renamed = `${alias}-${entry}`;
+		const destDir = join(destFindings, renamed);
+		if (existsSync(destDir)) continue; // shouldn't happen with alias prefix
+		mkdirSync(destDir, { recursive: true });
+		copyTree(srcDir, destDir);
+		written.push(destDir);
+	}
+	return written;
+}
+
+function copyAttackSurface(src: string, dest: string, alias: string): string | undefined {
+	const srcAttackSurface = join(src, "attack-surface");
+	if (!existsSync(srcAttackSurface)) return undefined;
+	const destRoot = join(dest, "attack-surface");
+	mkdirSync(destRoot, { recursive: true });
+	const destAttackSurface = join(destRoot, alias);
+	if (existsSync(destAttackSurface)) return destAttackSurface;
+	copyTree(srcAttackSurface, destAttackSurface);
+	return destAttackSurface;
+}
+
+export async function runMergeAudit(opts: RunMergeOptions): Promise<RunMergeResult> {
+	const { cwd, signal, ui } = opts;
+	if (opts.sources.length < 2) {
+		throw new Error("Merge requires at least two source piolium/ trees.");
+	}
+
+	ui?.setStatus?.("piolium-merge", "● preparing recon");
+	const recon = await runReconAsync(cwd, { signal });
+	const audit = await initAudit(cwd, {
+		mode: "merge",
+		...(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 workspace = join(cwd, "piolium", "merge-workspace");
+	mkdirSync(workspace, { recursive: true });
+	mkdirSync(join(cwd, ATTACK_SURFACE_DIR), { recursive: true });
+
+	// M1: copy each source's findings/ and attack-surface/ into the workspace under aliases.
+	const merged: string[] = [];
+	const attackSurfaceSnapshots: Record<string, string> = {};
+	const aliasMap: Record<string, string> = {};
+	for (let i = 0; i < opts.sources.length; i++) {
+		const src = opts.sources[i];
+		if (!src) continue;
+		const alias = aliasFor(i);
+		aliasMap[alias] = src;
+		const written = copyFindings(src, workspace, alias);
+		merged.push(...written);
+		const attackSurface = copyAttackSurface(src, workspace, alias);
+		if (attackSurface) attackSurfaceSnapshots[alias] = attackSurface;
+	}
+	writeFileSync(
+		join(workspace, "findings-index.json"),
+		`${JSON.stringify({ aliasMap, merged: merged.map((p) => basename(p)) }, null, "\t")}\n`,
+	);
+	writeFileSync(
+		join(workspace, "attack-surface-index.json"),
+		`${JSON.stringify(
+			{
+				aliasMap,
+				attackSurfaceSnapshots: Object.fromEntries(
+					Object.entries(attackSurfaceSnapshots).map(([alias, path]) => [alias, basename(path)]),
+				),
+			},
+			null,
+			"\t",
+		)}\n`,
+	);
+
+	// M2-M7: agent-driven semantic dedup + renumber + final report.
+	// Upstream assigns finding-writer to M3 (auto-fix) and report-composer to
+	// M6 (regenerate summaries); the rest are deterministic. piolium runs the
+	// whole M2-M7 tail as one report-composer pass.
+	const { agents } = loadAgents({ cwd });
+	const synth = agents.get("report-composer");
+
+	const task = [
+		"You are running /piolium-merge: combining multiple archon-audit result trees into one canonical piolium/ output.",
+		"",
+		`Workspace: ${workspace}`,
+		"Each finding directory there is named `<alias>-<original-id>-<slug>` (alias = a/b/c... per source).",
+		"Each source attack-surface corpus, when present, is copied under `merge-workspace/attack-surface/<alias>/`.",
+		`Source map (alias → path):\n${Object.entries(aliasMap)
+			.map(([k, v]) => `  ${k}: ${v}`)
+			.join("\n")}`,
+		"",
+		"Steps:",
+		"  M2 — semantic dedup: identify findings that describe the same root cause across aliases. Decide canonical winner. Record decisions in `merge-workspace/dedup-decisions.json`.",
+		"  M3 — auto-fix: repair frontmatter, malformed PoC JSON, naming violations.",
+		"  M4 — quarantine: move unfixable findings to `piolium/quarantine/<orig-id>-<slug>/QUARANTINE.md` with reason.",
+		"  M5 — renumber: assign deterministic IDs by severity (M-001 critical … M-NNN info). Write `merge-workspace/rename-map.json`.",
+		"  M6 — apply rename: rename surviving finding directories under `piolium/findings/` and rewrite per-report internal links.",
+		`  M7 — merge durable source context into \`${MERGE_ATTACK_SURFACE_SUMMARY}\`, then regenerate \`piolium/final-audit-report.md\` from the merged findings with an Attack Surface Summary linking \`${ATTACK_SURFACE_DIR}/\`.`,
+		"",
+		"Cap surviving findings at 60. Quality > quantity.",
+	].join("\n");
+
+	let failed = false;
+	try {
+		await runAgentPhase({
+			cwd,
+			audit,
+			phaseName: "M1",
+			statusKey: "piolium-merge",
+			statusLabel: "● merge dedup",
+			agent: synth,
+			missingAgentMessage: "report-composer missing",
+			task,
+			gate: () =>
+				existsSync(join(cwd, "piolium/final-audit-report.md")) &&
+				existsSync(join(cwd, MERGE_ATTACK_SURFACE_SUMMARY)),
+			mode: "merge",
+			ui,
+			agentRuntime: opts.agentRuntime,
+			...(signal ? { signal } : {}),
+		});
+	} catch {
+		failed = true;
+	}
+
+	// The single agent pass covers M1-M7; reflect that across the tracked
+	// phase set so the status strip isn't stuck showing M2-M7 pending.
+	for (const p of ["M1", "M2", "M3", "M4", "M5", "M6", "M7"]) {
+		await applyPhaseStatus(cwd, audit, p, { status: failed ? "failed" : "complete" });
+	}
+
+	await markAuditStatus(cwd, audit.audit_id, failed ? "failed" : "complete");
+	void renameSync; // placeholder for future deterministic rename pass
+	ui?.notify?.(failed ? "Merge failed." : "Merge complete.", failed ? "error" : "info");
+	return { auditId: audit.audit_id, status: failed ? "failed" : "complete", mergedFindings: merged };
+}

package/extensions/piolium/modes/phase-runner.ts

@@ -0,0 +1,267 @@
+/**
+ * Shared helper for orchestrators (lite/balanced/deep/etc.) — wraps a single
+ * phase invocation with audit-state transitions, gate verification, and
+ * structured logging via UI hooks.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { type AgentRunError, type AgentRuntimeModel, runAgent } from "../agent-runner.ts";
+import type { RuntimeContext } from "../agent-runner.ts";
+import type { AgentDefinition } from "../agents.ts";
+import { type AuditRunState, applyPhaseStatus } from "../audit-state.ts";
+import {
+	DEFAULT_HEARTBEAT_INTERVAL_MS,
+	type PhaseHeartbeat,
+	createPhaseHeartbeatTracker,
+	heartbeatStateFields,
+} from "../heartbeat.ts";
+import {
+	errorMessage,
+	readNonNegativeIntEnv,
+	readPositiveIntEnv,
+	retryBackoffMs,
+	sleep,
+} from "../retry.ts";
+
+export interface PhaseUiHooks {
+	notify?: (text: string, level: "info" | "warning" | "error") => void;
+	setStatus?: (key: string, text?: string) => void;
+	/**
+	 * Forwarded copy of every child agent event. Wire this from the command
+	 * handler to surface tool calls + assistant text in the parent chat;
+	 * otherwise the subagent runs silently and the user only sees a footer
+	 * status indicator.
+	 */
+	onAgentEvent?: (phase: string, event: AgentSessionEvent) => void;
+	/**
+	 * Periodic parent-side health signal while a child agent is running.
+	 * This fires even when the child model is quiet, so the UI can prove the
+	 * phase has not been forgotten.
+	 */
+	onPhaseHeartbeat?: (phase: string, heartbeat?: PhaseHeartbeat) => void;
+}
+
+export interface RunAgentPhaseOptions {
+	cwd: string;
+	audit: AuditRunState;
+	phaseName: string;
+	statusKey: string;
+	statusLabel: string;
+	agent: AgentDefinition | undefined;
+	missingAgentMessage: string;
+	task: string;
+	runtimeExtras?: Partial<Omit<RuntimeContext, "cwd" | "mode">>;
+	gate: () => boolean;
+	signal?: AbortSignal;
+	ui?: PhaseUiHooks;
+	mode: AuditRunState["mode"];
+	agentRuntime?: AgentRuntimeModel;
+	timeoutMs?: number;
+	/** Number of retries after the first attempt. Defaults to PIOLIUM_PHASE_MAX_RETRIES or 5. */
+	maxRetries?: number;
+	retryBackoffBaseMs?: number;
+	retryBackoffMaxMs?: number;
+}
+
+const HEARTBEAT_INTERVAL_MS = readPositiveIntEnv(
+	"PIOLIUM_HEARTBEAT_INTERVAL_MS",
+	DEFAULT_HEARTBEAT_INTERVAL_MS,
+);
+
+function defaultPhaseMaxRetries(): number {
+	return readNonNegativeIntEnv("PIOLIUM_PHASE_MAX_RETRIES", 5);
+}
+
+function defaultPhaseBackoffBaseMs(): number {
+	return readPositiveIntEnv("PIOLIUM_PHASE_BACKOFF_BASE_MS", 5000);
+}
+
+function defaultPhaseBackoffMaxMs(): number {
+	return readPositiveIntEnv("PIOLIUM_PHASE_BACKOFF_MAX_MS", 120_000);
+}
+
+function makePhaseSignal(
+	parent: AbortSignal | undefined,
+	timeoutMs: number | undefined,
+	phaseName: string,
+): { signal?: AbortSignal; cleanup: () => void } {
+	if (!timeoutMs || timeoutMs <= 0) {
+		return { ...(parent ? { signal: parent } : {}), cleanup: () => {} };
+	}
+
+	const ctrl = new AbortController();
+	let timeout: ReturnType<typeof setTimeout> | undefined = setTimeout(() => {
+		ctrl.abort(new Error(`Phase ${phaseName} timed out after ${timeoutMs}ms`));
+	}, timeoutMs);
+	const onParentAbort = () => {
+		ctrl.abort(parent?.reason ?? new Error(`Phase ${phaseName} aborted`));
+	};
+	if (parent) {
+		if (parent.aborted) onParentAbort();
+		else parent.addEventListener("abort", onParentAbort, { once: true });
+	}
+	return {
+		signal: ctrl.signal,
+		cleanup: () => {
+			if (timeout) clearTimeout(timeout);
+			timeout = undefined;
+			if (parent) parent.removeEventListener("abort", onParentAbort);
+		},
+	};
+}
+
+export async function runAgentPhase(opts: RunAgentPhaseOptions): Promise<void> {
+	const { cwd, audit, phaseName, statusKey, statusLabel, agent, ui, gate, mode } = opts;
+	if (audit.phases[phaseName]?.status === "complete" && gate()) return;
+
+	const maxRetries = Math.max(0, opts.maxRetries ?? defaultPhaseMaxRetries());
+	const maxAttempts = maxRetries + 1;
+	const backoffBaseMs = opts.retryBackoffBaseMs ?? defaultPhaseBackoffBaseMs();
+	const backoffMaxMs = opts.retryBackoffMaxMs ?? defaultPhaseBackoffMaxMs();
+	const onAgentEvent = ui?.onAgentEvent;
+	const onPhaseHeartbeat = ui?.onPhaseHeartbeat;
+
+	try {
+		if (!agent) {
+			await applyPhaseStatus(cwd, audit, phaseName, {
+				status: "failed",
+				error: opts.missingAgentMessage,
+			});
+			throw new Error(opts.missingAgentMessage);
+		}
+
+		for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+			const attemptLabel =
+				maxAttempts > 1 ? `${statusLabel} (${attempt}/${maxAttempts})` : statusLabel;
+			ui?.setStatus?.(statusKey, attemptLabel);
+			await applyPhaseStatus(cwd, audit, phaseName, {
+				status: "in_progress",
+				attempt,
+				max_attempts: maxAttempts,
+				retry_backoff_ms: null,
+				next_retry_at: null,
+				...(attempt > 1 ? { error: `Retry attempt ${attempt}/${maxAttempts} running.` } : {}),
+			});
+
+			const runId = `${phaseName.toLowerCase()}-${audit.audit_id.replace(/[:.]/g, "-")}-a${attempt}-${randomUUID().slice(0, 8)}`;
+			const phaseSignal = makePhaseSignal(opts.signal, opts.timeoutMs, phaseName);
+			const heartbeat = createPhaseHeartbeatTracker({
+				phase: phaseName,
+				label: attemptLabel,
+				runId,
+			});
+			let heartbeatTimer: ReturnType<typeof setInterval> | undefined;
+			const emitHeartbeat = () => {
+				const snapshot = heartbeat.snapshot();
+				onPhaseHeartbeat?.(phaseName, snapshot);
+				void applyPhaseStatus(cwd, audit, phaseName, {
+					status: "in_progress",
+					...heartbeatStateFields(snapshot),
+				}).catch(() => {});
+			};
+			try {
+				emitHeartbeat();
+				heartbeatTimer = setInterval(emitHeartbeat, HEARTBEAT_INTERVAL_MS);
+				await runAgent({
+					agent,
+					task: opts.task,
+					runId,
+					runtime: { cwd, mode, phase: phaseName, ...opts.runtimeExtras },
+					...(opts.agentRuntime ? opts.agentRuntime : {}),
+					...(phaseSignal.signal ? { signal: phaseSignal.signal } : {}),
+					onEvent: (event) => {
+						heartbeat.recordEvent(event);
+						if (event.type === "tool_execution_start" || event.type === "tool_execution_end") {
+							onPhaseHeartbeat?.(phaseName, heartbeat.snapshot());
+						}
+						onAgentEvent?.(phaseName, event);
+					},
+				});
+
+				if (!gate()) {
+					throw new Error(`Phase ${phaseName} gate failed — expected artifact missing.`);
+				}
+
+				await applyPhaseStatus(cwd, audit, phaseName, {
+					status: "complete",
+					attempt,
+					max_attempts: maxAttempts,
+					retry_backoff_ms: null,
+					next_retry_at: null,
+					last_error: null,
+				});
+				return;
+			} catch (err) {
+				const message = errorMessage(err);
+				const failure = err as Partial<AgentRunError>;
+				const artifacts = failure.result?.transcriptPath ? [failure.result.transcriptPath] : undefined;
+
+				if (gate()) {
+					await applyPhaseStatus(cwd, audit, phaseName, {
+						status: "complete",
+						attempt,
+						max_attempts: maxAttempts,
+						retry_backoff_ms: null,
+						next_retry_at: null,
+						last_error: null,
+						...(artifacts ? { artifacts } : {}),
+					});
+					ui?.notify?.(
+						`Phase ${phaseName} errored but its required artifact exists; treating it as complete.`,
+						"warning",
+					);
+					return;
+				}
+
+				if (opts.signal?.aborted || attempt >= maxAttempts) {
+					await applyPhaseStatus(cwd, audit, phaseName, {
+						status: "failed",
+						error:
+							attempt >= maxAttempts && maxRetries > 0
+								? `Failed after ${maxRetries} retries: ${message}`
+								: message,
+						attempt,
+						max_attempts: maxAttempts,
+						retry_backoff_ms: null,
+						next_retry_at: null,
+						last_error: message,
+						...(artifacts ? { artifacts } : {}),
+					});
+					throw err;
+				}
+
+				const backoffMs = retryBackoffMs(attempt, backoffBaseMs, backoffMaxMs);
+				const nextRetryAt = new Date(Date.now() + backoffMs).toISOString();
+				await applyPhaseStatus(cwd, audit, phaseName, {
+					status: "in_progress",
+					error: `Attempt ${attempt}/${maxAttempts} failed: ${message}. Retrying at ${nextRetryAt}.`,
+					attempt,
+					max_attempts: maxAttempts,
+					retry_backoff_ms: backoffMs,
+					next_retry_at: nextRetryAt,
+					last_error: message,
+					...(artifacts ? { artifacts } : {}),
+				});
+				ui?.notify?.(
+					`Phase ${phaseName} attempt ${attempt}/${maxAttempts} failed; retrying in ${Math.ceil(backoffMs / 1000)}s.`,
+					"warning",
+				);
+				ui?.setStatus?.(statusKey, `${statusLabel} retrying in ${Math.ceil(backoffMs / 1000)}s`);
+				await sleep(backoffMs, opts.signal);
+			} finally {
+				if (heartbeatTimer) clearInterval(heartbeatTimer);
+				onPhaseHeartbeat?.(phaseName, undefined);
+				phaseSignal.cleanup();
+			}
+		}
+	} finally {
+		ui?.setStatus?.(statusKey, undefined);
+	}
+
+	await applyPhaseStatus(cwd, audit, phaseName, {
+		status: "failed",
+		error: `Phase ${phaseName} failed unexpectedly without throwing.`,
+	});
+	throw new Error(`Phase ${phaseName} failed`);
+}