@vigolium/piolium 0.0.1

package/extensions/piolium/modes/lite.ts

@@ -0,0 +1,540 @@
+/**
+ * Lite mode orchestrator (`/piolium-lite`).
+ *
+ * Pipeline (command-defs/lite.md, archon-audit @ 2026-05-16):
+ *
+ *   L1 Recon Sweep   →   [L2 Secrets Scan ‖ L3 Fast Code Scan]
+ *
+ * All three phases have `agent: null` upstream — L1 and L2 run
+ * deterministically in-process, L3 spawns the `code-scanner` agent with a
+ * tightly-scoped lite-mode task. L2 and L3 race under the global cap.
+ *
+ * Upstream lite produces only draft findings and folds any consolidation /
+ * cleanup inline (no tracked PoC or cleanup phases — piolium's old Q3/Q4
+ * tail was dropped to match upstream exactly). piolium still consolidates
+ * surviving drafts into `findings/<ID>-<slug>/` and removes transient
+ * artifacts as an inline post-L3 pass so downstream modes have inputs.
+ */
+
+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 {
+	candidateSummaryPath,
+	candidatesJsonlPath,
+	runCandidateScanAsync,
+} from "../candidate-scan.ts";
+import { consolidateDrafts, listFindingDirs } from "../findings.ts";
+import { reconReportPath, runReconAsync } from "../recon.ts";
+import { errorMessage, readNonNegativeIntEnv, readPositiveIntEnv, runWithRetry } from "../retry.ts";
+import { Scheduler } from "../scheduler.ts";
+import { Q1_SECRETS_SUMMARY, findingsDraftDir, runQ1SecretsScan } from "../secrets.ts";
+import { type PhaseUiHooks, runAgentPhase } from "./phase-runner.ts";
+
+export type LiteUiHooks = PhaseUiHooks;
+
+export interface RunLiteOptions {
+	cwd: string;
+	signal?: AbortSignal;
+	ui?: LiteUiHooks;
+	/** When true, restart from scratch even if an in-progress audit exists. */
+	forceFresh?: boolean;
+	agentRuntime?: AgentRuntimeModel;
+}
+
+export interface RunLiteResult {
+	auditId: string;
+	status: "complete" | "failed";
+	phases: Record<string, "complete" | "failed" | "skipped">;
+	summaryPath: string;
+}
+
+export const LITE_ATTACK_SURFACE_DIR = "piolium/attack-surface";
+export const L2_SUMMARY = Q1_SECRETS_SUMMARY;
+export const L3_SUMMARY = `${LITE_ATTACK_SURFACE_DIR}/lite-l3-summary.md`;
+export const LITE_CONSOLIDATION_MANIFEST = `${LITE_ATTACK_SURFACE_DIR}/lite-consolidation-manifest.json`;
+export const LITE_VERIFICATION_SUMMARY = `${LITE_ATTACK_SURFACE_DIR}/lite-verification-summary.md`;
+export const LITE_CLEANUP_SUMMARY = `${LITE_ATTACK_SURFACE_DIR}/lite-cleanup-summary.json`;
+const LITE_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",
+];
+
+function litePhaseMaxRetries(): number {
+	return readNonNegativeIntEnv(
+		"PIOLIUM_LITE_PHASE_MAX_RETRIES",
+		readNonNegativeIntEnv("PIOLIUM_PHASE_MAX_RETRIES", 5),
+	);
+}
+
+function litePhaseBackoffBaseMs(): number {
+	return readPositiveIntEnv(
+		"PIOLIUM_LITE_PHASE_BACKOFF_BASE_MS",
+		readPositiveIntEnv("PIOLIUM_PHASE_BACKOFF_BASE_MS", 5000),
+	);
+}
+
+function litePhaseBackoffMaxMs(): number {
+	return readPositiveIntEnv(
+		"PIOLIUM_LITE_PHASE_BACKOFF_MAX_MS",
+		readPositiveIntEnv("PIOLIUM_PHASE_BACKOFF_MAX_MS", 120_000),
+	);
+}
+
+function gatePass(cwd: string, phase: "L1" | "L2" | "L3"): boolean {
+	switch (phase) {
+		case "L1":
+			return (
+				existsSync(reconReportPath(cwd)) &&
+				existsSync(candidateSummaryPath(cwd)) &&
+				existsSync(candidatesJsonlPath(cwd))
+			);
+		case "L2":
+			return existsSync(join(cwd, L2_SUMMARY));
+		case "L3":
+			return existsSync(join(cwd, L3_SUMMARY));
+	}
+}
+
+function pickResumeAudit(cwd: string, forceFresh: boolean): AuditRunState | undefined {
+	if (forceFresh) return undefined;
+	const state = readAuditState(cwd).state;
+	if (!state) return undefined;
+	const audit = latestAudit(state);
+	if (!audit) return undefined;
+	if (audit.mode !== "lite") return undefined;
+	if (audit.status === "complete") return undefined;
+	return audit;
+}
+
+function notify(
+	ui: LiteUiHooks | undefined,
+	level: Parameters<NonNullable<LiteUiHooks["notify"]>>[1],
+	msg: string,
+) {
+	ui?.notify?.(msg, level);
+}
+
+function setStatus(ui: LiteUiHooks | undefined, key: string, text?: string) {
+	ui?.setStatus?.(key, text);
+}
+
+interface LiteLocalPhaseResult {
+	artifacts: string[];
+	notifyText?: string;
+}
+
+async function runLiteLocalPhase(
+	cwd: string,
+	audit: AuditRunState,
+	phaseName: "L1" | "L2",
+	statusLabel: string,
+	gate: () => boolean,
+	run: () => LiteLocalPhaseResult | Promise<LiteLocalPhaseResult>,
+	signal: AbortSignal | undefined,
+	ui?: LiteUiHooks,
+): Promise<void> {
+	if (audit.phases[phaseName]?.status === "complete" && gate()) {
+		return;
+	}
+
+	const maxRetries = litePhaseMaxRetries();
+	const maxAttempts = maxRetries + 1;
+	const backoffBaseMs = litePhaseBackoffBaseMs();
+	const backoffMaxMs = litePhaseBackoffMaxMs();
+	try {
+		const result = await runWithRetry(
+			async (attempt, attempts) => {
+				const attemptLabel = attempts > 1 ? `${statusLabel} (${attempt}/${attempts})` : statusLabel;
+				setStatus(ui, "piolium-lite", attemptLabel);
+				await applyPhaseStatus(cwd, audit, phaseName, {
+					status: "in_progress",
+					attempt,
+					max_attempts: attempts,
+					retry_backoff_ms: null,
+					next_retry_at: null,
+					...(attempt > 1 ? { error: `Retry attempt ${attempt}/${attempts} running.` } : {}),
+				});
+
+				try {
+					const phaseResult = await run();
+					if (!gate()) {
+						throw new Error(`Phase ${phaseName} gate failed — expected artifact missing.`);
+					}
+					await applyPhaseStatus(cwd, audit, phaseName, {
+						status: "complete",
+						artifacts: phaseResult.artifacts,
+						attempt,
+						max_attempts: attempts,
+						retry_backoff_ms: null,
+						next_retry_at: null,
+						last_error: null,
+					});
+					return phaseResult;
+				} catch (err) {
+					if (gate()) {
+						await applyPhaseStatus(cwd, audit, phaseName, {
+							status: "complete",
+							attempt,
+							max_attempts: attempts,
+							retry_backoff_ms: null,
+							next_retry_at: null,
+							last_error: null,
+						});
+						notify(
+							ui,
+							"warning",
+							`Phase ${phaseName} errored but its required artifact exists; treating it as complete.`,
+						);
+						return { artifacts: [] };
+					}
+					throw err;
+				}
+			},
+			{
+				maxRetries,
+				backoffBaseMs,
+				backoffMaxMs,
+				...(signal ? { signal } : {}),
+				onRetry: async (info) => {
+					await applyPhaseStatus(cwd, audit, phaseName, {
+						status: "in_progress",
+						error: `Attempt ${info.attempt}/${info.maxAttempts} failed: ${info.errorMessage}. Retrying at ${info.nextRetryAt}.`,
+						attempt: info.attempt,
+						max_attempts: info.maxAttempts,
+						retry_backoff_ms: info.backoffMs,
+						next_retry_at: info.nextRetryAt,
+						last_error: info.errorMessage,
+					});
+					notify(
+						ui,
+						"warning",
+						`Phase ${phaseName} attempt ${info.attempt}/${info.maxAttempts} failed; retrying in ${Math.ceil(info.backoffMs / 1000)}s.`,
+					);
+					setStatus(
+						ui,
+						"piolium-lite",
+						`${statusLabel} retrying in ${Math.ceil(info.backoffMs / 1000)}s`,
+					);
+				},
+			},
+		);
+		if (result.notifyText) notify(ui, "info", result.notifyText);
+	} catch (err) {
+		const message = errorMessage(err);
+		await applyPhaseStatus(cwd, audit, phaseName, {
+			status: "failed",
+			error: maxRetries > 0 ? `Failed after ${maxRetries} retries: ${message}` : message,
+			attempt: maxAttempts,
+			max_attempts: maxAttempts,
+			retry_backoff_ms: null,
+			next_retry_at: null,
+			last_error: message,
+		});
+		throw err;
+	}
+}
+
+async function runL1(
+	cwd: string,
+	audit: AuditRunState,
+	signal: AbortSignal | undefined,
+	ui?: LiteUiHooks,
+): Promise<void> {
+	await runLiteLocalPhase(
+		cwd,
+		audit,
+		"L1",
+		"● L1 recon sweep",
+		() => gatePass(cwd, "L1"),
+		async () => {
+			const recon = await runReconAsync(cwd, { signal });
+			const candidates = await runCandidateScanAsync(cwd, { signal });
+			return {
+				artifacts: [recon.reportPath, candidates.summaryPath, candidates.candidatesPath],
+				notifyText: `L1 recon: ${candidates.candidateCount} candidate match(es) across ${candidates.candidateFiles} file(s).`,
+			};
+		},
+		signal,
+		ui,
+	);
+}
+
+async function runL2(
+	cwd: string,
+	audit: AuditRunState,
+	signal: AbortSignal | undefined,
+	ui?: LiteUiHooks,
+): Promise<void> {
+	await runLiteLocalPhase(
+		cwd,
+		audit,
+		"L2",
+		"● L2 secrets scan",
+		() => gatePass(cwd, "L2"),
+		() => {
+			const result = runQ1SecretsScan(cwd);
+			return {
+				artifacts: [join(cwd, L2_SUMMARY), ...result.draftPaths],
+				notifyText: `L2 ${result.backend}: ${result.findings.length} draft finding(s).`,
+			};
+		},
+		signal,
+		ui,
+	);
+}
+
+function buildL3Task(cwd: string): string {
+	return [
+		"You are running Phase L3 (Fast Code Scan) of a /piolium-lite scan.",
+		"This is a TIGHTLY SCOPED lite-mode SAST pass — not a full audit. Constraints:",
+		"  - Hard time budget: 5 minutes wall-clock.",
+		"  - Do NOT build CodeQL/Semgrep databases. If those tools aren't already installed, fall back to grep + read.",
+		"  - Focus on cheap, high-signal patterns: command injection, path traversal, SSRF, hardcoded crypto, broken authn/z.",
+		"  - Read `piolium/attack-surface/lite-recon.md`, `piolium/attack-surface/candidates-summary.md`, `piolium/attack-surface/candidates.jsonl`, and `piolium/attack-surface/lite-q1-summary.md` if present.",
+		"  - Prioritize precise/high-score candidate files first, but validate with source evidence before drafting.",
+		"  - For each candidate issue, write a draft finding to `piolium/findings-draft/l3-NNN-<slug>.md`.",
+		`  - Write a phase summary to \`${L3_SUMMARY}\` even when nothing is found.`,
+		"  - Stop after at most 8 candidate findings — quality over quantity.",
+		"",
+		`Target repository: ${cwd}`,
+		"",
+		"Each finding draft should follow this frontmatter:",
+		"  ---",
+		"  id: l3-NNN",
+		"  phase: L3",
+		"  slug: <kebab-case>",
+		"  severity: high|medium|low",
+		"  ---",
+		"",
+		"Begin now.",
+	].join("\n");
+}
+
+async function runL3(
+	cwd: string,
+	audit: AuditRunState,
+	codeScanner: AgentDefinition | undefined,
+	signal: AbortSignal | undefined,
+	ui?: LiteUiHooks,
+	agentRuntime?: AgentRuntimeModel,
+): Promise<void> {
+	await runAgentPhase({
+		cwd,
+		audit,
+		phaseName: "L3",
+		statusKey: "piolium-lite",
+		statusLabel: "● L3 fast code scan",
+		agent: codeScanner,
+		missingAgentMessage: "code-scanner agent not found in bundled agents/.",
+		task: buildL3Task(cwd),
+		runtimeExtras: {
+			outputPaths: [findingsDraftDir(cwd), join(cwd, L3_SUMMARY)],
+			notes: ["Lite mode — keep the run under 5 minutes wall-clock."],
+		},
+		gate: () => gatePass(cwd, "L3"),
+		mode: "lite",
+		ui,
+		agentRuntime,
+		...(signal ? { signal } : {}),
+	});
+	notify(ui, "info", `L3 produced ${listL3Drafts(cwd).length} draft finding(s).`);
+}
+
+function listL3Drafts(cwd: string): string[] {
+	const dir = findingsDraftDir(cwd);
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir)
+		.filter((f) => f.startsWith("l3-") && f.endsWith(".md"))
+		.map((f) => join(dir, f));
+}
+
+export interface LiteCleanupResult {
+	summaryPath: string;
+	removed: string[];
+	missing: string[];
+	retained: string[];
+}
+
+export function cleanupLiteTransientArtifacts(cwd: string): LiteCleanupResult {
+	mkdirSync(join(cwd, LITE_ATTACK_SURFACE_DIR), { recursive: true });
+	const removed: string[] = [];
+	const missing: string[] = [];
+	for (const rel of LITE_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: LiteCleanupResult = {
+		summaryPath: LITE_CLEANUP_SUMMARY,
+		removed,
+		missing,
+		retained: ["piolium/attack-surface/", "piolium/findings/", "piolium/audit-state.json"],
+	};
+	writeFileSync(join(cwd, LITE_CLEANUP_SUMMARY), `${JSON.stringify(result, null, "\t")}\n`);
+	return result;
+}
+
+/**
+ * Inline post-L3 finalize (upstream lite has no tracked consolidation /
+ * cleanup phase): promote surviving l2-/l3- drafts into severity-prefixed
+ * finding dirs and remove transient artifacts.
+ */
+function finalizeLite(cwd: string): void {
+	mkdirSync(join(cwd, LITE_ATTACK_SURFACE_DIR), { recursive: true });
+	const consolidation = consolidateDrafts(cwd, ["l2-", "l3-", "q1-", "q2-"]);
+	writeFileSync(
+		join(cwd, LITE_CONSOLIDATION_MANIFEST),
+		`${JSON.stringify(
+			{
+				generated_at: new Date().toISOString(),
+				source_prefixes: ["l2-", "l3-"],
+				promoted: consolidation.promoted,
+				dropped: consolidation.dropped,
+			},
+			null,
+			"\t",
+		)}\n`,
+	);
+	const dirs = listFindingDirs(cwd);
+	const cleanup = cleanupLiteTransientArtifacts(cwd);
+	writeFileSync(
+		join(cwd, LITE_VERIFICATION_SUMMARY),
+		[
+			"# Lite Verification & Cleanup",
+			"",
+			`Generated: ${new Date().toISOString()}`,
+			"",
+			"## Verification",
+			"",
+			"- Scope: fast triage; PoC + live confirmation remain `/piolium-balanced` / `/piolium-confirm`.",
+			`- Promoted finding directories: ${dirs.length}`,
+			"- Durable review inputs remain under `piolium/attack-surface/`.",
+			"",
+			"## Cleanup",
+			"",
+			`- Removed: ${cleanup.removed.length > 0 ? cleanup.removed.map((p) => `\`${p}\``).join(", ") : "(none)"}`,
+			`- Cleanup summary: \`${cleanup.summaryPath}\``,
+			"",
+		].join("\n"),
+	);
+}
+
+export async function runLiteAudit(opts: RunLiteOptions): Promise<RunLiteResult> {
+	const { cwd, signal, ui } = opts;
+	mkdirSync(join(cwd, LITE_ATTACK_SURFACE_DIR), { recursive: true });
+
+	ui?.setStatus?.("piolium-lite", "● preparing recon");
+	const recon0 = await runReconAsync(cwd, { signal });
+	ui?.setStatus?.("piolium-lite", "● 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 = pickResumeAudit(cwd, opts.forceFresh ?? false);
+	if (!audit) {
+		audit = await initAudit(cwd, {
+			mode: "lite",
+			...(recon0.commit ? { commit: recon0.commit } : { commit: null }),
+			...(recon0.branch ? { branch: recon0.branch } : { branch: "nogit" }),
+			...(recon0.repository ? { repository: recon0.repository } : {}),
+			history_available: recon0.historyAvailable,
+			agent_sdk: "pi",
+		});
+	}
+
+	// L1 first, deterministic. Required for the L3 task to have target context.
+	try {
+		await runL1(cwd, audit, signal, ui);
+	} catch {
+		await markAuditStatus(cwd, audit.audit_id, "failed");
+		setStatus(ui, "piolium-lite", undefined);
+		return finalResult(audit, "failed", cwd);
+	}
+
+	// L2 + L3 race under the cap. Both are independent.
+	const scheduler = new Scheduler({ maxConcurrent: 3, ...(signal ? { signal } : {}) });
+	const { agents } = loadAgents({ cwd });
+	const codeScanner = agents.get("code-scanner");
+
+	const settled = await Promise.allSettled([
+		scheduler.enqueue({ id: "L2", run: (sig) => runL2(cwd, audit, sig, ui) }),
+		scheduler.enqueue({
+			id: "L3",
+			run: (sig) => runL3(cwd, audit, codeScanner, sig, ui, opts.agentRuntime),
+		}),
+	]);
+	scheduler.dispose();
+
+	const failed = settled.some((s) => s.status === "rejected");
+	if (!failed) {
+		try {
+			finalizeLite(cwd);
+		} catch (err) {
+			notify(ui, "warning", `Lite finalize failed: ${errorMessage(err)}`);
+		}
+	}
+	const final = await markAuditStatus(cwd, audit.audit_id, failed ? "failed" : "complete");
+	setStatus(ui, "piolium-lite", undefined);
+	if (failed) {
+		notify(
+			ui,
+			"error",
+			`Lite audit failed (${settled.filter((s) => s.status === "rejected").length} phase failure(s)).`,
+		);
+	} else {
+		notify(ui, "info", "Lite audit complete.");
+	}
+	return finalResult(final ?? audit, failed ? "failed" : "complete", cwd);
+}
+
+function finalResult(
+	audit: AuditRunState,
+	status: "complete" | "failed",
+	cwd: string,
+): RunLiteResult {
+	const phases: Record<string, "complete" | "failed" | "skipped"> = {};
+	for (const [name, phase] of Object.entries(audit.phases)) {
+		if (phase.status === "complete" || phase.status === "failed" || phase.status === "skipped") {
+			phases[name] = phase.status;
+		}
+	}
+	return {
+		auditId: audit.audit_id,
+		status,
+		phases,
+		summaryPath: reconReportPath(cwd),
+	};
+}