@vigolium/piolium 0.0.1

package/extensions/piolium/findings.ts

@@ -0,0 +1,448 @@
+/**
+ * Helpers for working with `piolium/findings-draft/` and
+ * `piolium/findings/<id>-<slug>/`.
+ *
+ * The on-disk layout matches archon-audit so artifact files written by
+ * either system are interchangeable. Promotion (draft → finding directory)
+ * happens after Review Chamber phases when the orchestrator decides which
+ * drafts have survived dedup / FP elimination.
+ */
+
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "./_vendor/yaml.bundle.mjs";
+import { splitFrontmatter } from "./agents.ts";
+
+export interface FindingDraft {
+	path: string;
+	id: string;
+	slug: string;
+	severity: "critical" | "high" | "medium" | "low" | "info";
+	phase?: string;
+	status?: string;
+	verdict?: string;
+	body: string;
+	frontmatter: Record<string, unknown>;
+}
+
+export interface FindingDir {
+	id: string;
+	slug: string;
+	path: string;
+	hasReport: boolean;
+	hasPoc: boolean;
+	hasEvidence: boolean;
+}
+
+export function findingsDraftDir(cwd: string): string {
+	return join(cwd, "piolium", "findings-draft");
+}
+
+export function findingsDir(cwd: string): string {
+	return join(cwd, "piolium", "findings");
+}
+
+/**
+ * The theoretical / unconfirmed bucket. Drafts the triager (or Intent
+ * Reconciliation) marked skip, and findings whose PoC never executed, land
+ * here. They still get a `report.md` but are kept out of the main
+ * Summary-of-Findings table. Matches upstream archon-audit's
+ * `findings-theoretical/`.
+ */
+export function findingsTheoreticalDir(cwd: string): string {
+	return join(cwd, "piolium", "findings-theoretical");
+}
+
+const SEVERITIES = new Set<FindingDraft["severity"]>(["critical", "high", "medium", "low", "info"]);
+
+function normalizeSeverity(value: unknown): FindingDraft["severity"] {
+	if (typeof value !== "string") return "info";
+	const lower = value.toLowerCase().trim() as FindingDraft["severity"];
+	return SEVERITIES.has(lower) ? lower : "info";
+}
+
+export function listDraftFindings(cwd: string, prefix?: string): FindingDraft[] {
+	const dir = findingsDraftDir(cwd);
+	if (!existsSync(dir)) return [];
+	const out: FindingDraft[] = [];
+	for (const entry of readdirSync(dir).sort()) {
+		if (!entry.endsWith(".md")) continue;
+		if (prefix && !entry.startsWith(prefix)) continue;
+		const path = join(dir, entry);
+		try {
+			const raw = readFileSync(path, "utf8");
+			const { frontmatter, body } = splitFrontmatter(raw);
+			const id =
+				typeof frontmatter.id === "string"
+					? frontmatter.id
+					: (basename(entry, ".md").split("-")[0] ?? basename(entry, ".md"));
+			const slug =
+				typeof frontmatter.slug === "string"
+					? frontmatter.slug
+					: basename(entry, ".md").replace(/^[a-z0-9]+-\d+-?/i, "");
+			out.push({
+				path,
+				id,
+				slug,
+				severity: normalizeSeverity(frontmatter.severity),
+				...(typeof frontmatter.phase === "string" ? { phase: frontmatter.phase } : {}),
+				...(typeof frontmatter.status === "string" ? { status: frontmatter.status } : {}),
+				...(typeof frontmatter.verdict === "string" ? { verdict: frontmatter.verdict } : {}),
+				body,
+				frontmatter,
+			});
+		} catch {
+			// skip malformed files
+		}
+	}
+	return out;
+}
+
+// Match `<id>-<slug>` directory names. Ordered alternatives (longest-first):
+//   FP-<phase>-<seq>  (e.g. FP-p8-001-…)
+//   <phase>-<seq>     (e.g. p8-001-…, q1-002-…)
+//   FP-<sev><n>       (e.g. FP-H1-…)
+//   <sev><n>          (e.g. C1-…, H1-…, M1-…)
+//   <seq>             (legacy bare-numeric ids)
+const FINDING_DIR_RE = /^((?:FP-)?[A-Za-z0-9]+-\d+|(?:FP-)?[A-Za-z]+\d+|\d+)-(.+)$/;
+
+export function parseFindingDirName(entry: string): { id: string; slug: string } {
+	const m = entry.match(FINDING_DIR_RE);
+	if (m?.[1] && m?.[2]) return { id: m[1], slug: m[2] };
+	const parts = entry.split("-");
+	return parts.length > 1
+		? { id: parts.slice(0, -1).join("-"), slug: parts[parts.length - 1] ?? entry }
+		: { id: entry, slug: entry };
+}
+
+function listFindingDirsIn(root: string): FindingDir[] {
+	if (!existsSync(root)) return [];
+	const out: FindingDir[] = [];
+	for (const entry of readdirSync(root).sort()) {
+		const path = join(root, entry);
+		if (!statSync(path).isDirectory()) continue;
+		const { id, slug } = parseFindingDirName(entry);
+		out.push({
+			id,
+			slug,
+			path,
+			hasReport: existsSync(join(path, "report.md")),
+			hasPoc: readdirSync(path).some((f) => f.startsWith("poc.")),
+			hasEvidence: existsSync(join(path, "evidence")),
+		});
+	}
+	return out;
+}
+
+export function listFindingDirs(cwd: string): FindingDir[] {
+	return listFindingDirsIn(findingsDir(cwd));
+}
+
+export function listTheoreticalFindingDirs(cwd: string): FindingDir[] {
+	return listFindingDirsIn(findingsTheoreticalDir(cwd));
+}
+
+/** Both buckets — used by finalize/report phases that cover everything. */
+export function listAllFindingDirs(cwd: string): FindingDir[] {
+	return [...listFindingDirs(cwd), ...listTheoreticalFindingDirs(cwd)];
+}
+
+const TRIAGE_SKIP_KEYS = ["Triage-Priority", "triage_priority", "triage-priority"];
+
+/**
+ * A draft routed to the theoretical bucket: the triager or Intent
+ * Reconciliation set `Triage-Priority: skip`, or the draft self-declares a
+ * theoretical/no-poc disposition.
+ */
+export function isTheoreticalDraft(frontmatter: Record<string, unknown>): boolean {
+	for (const key of TRIAGE_SKIP_KEYS) {
+		const v = frontmatter[key];
+		if (typeof v === "string" && v.trim().toLowerCase() === "skip") return true;
+	}
+	const disposition = frontmatter.disposition ?? frontmatter.bucket;
+	return typeof disposition === "string" && disposition.trim().toLowerCase() === "theoretical";
+}
+
+/**
+ * Move a finding directory between buckets, preserving its `<id>-<slug>`
+ * name. Idempotent: a no-op when already at the destination.
+ */
+function moveFindingDir(fromPath: string, toRoot: string): string {
+	const name = basename(fromPath);
+	mkdirSync(toRoot, { recursive: true });
+	const dest = join(toRoot, name);
+	if (fromPath === dest || existsSync(dest)) return dest;
+	// Cross-bucket move within the same filesystem.
+	renameSync(fromPath, dest);
+	return dest;
+}
+
+export interface PartitionResult {
+	confirmed: string[];
+	theoretical: string[];
+}
+
+/**
+ * Demote every `piolium/findings/<id>-<slug>/` whose `draft.md` did not
+ * reach an executed PoC (or is flagged theoretical) into
+ * `piolium/findings-theoretical/`. Mirrors upstream
+ * `partition_findings.py`. Idempotent; safe to call when there are no
+ * findings.
+ */
+export function partitionFindings(cwd: string): PartitionResult {
+	const confirmed: string[] = [];
+	const theoretical: string[] = [];
+	for (const dir of listFindingDirs(cwd)) {
+		const fm: Record<string, unknown> = readFindingFrontmatter(dir.path) ?? {};
+		const pocStatus = String(fm["PoC-Status"] ?? fm.poc_status ?? fm["poc-status"] ?? "")
+			.trim()
+			.toLowerCase();
+		const pocExecuted = dir.hasPoc && (pocStatus === "" || pocStatus === "executed");
+		if (isTheoreticalDraft(fm) || !pocExecuted) {
+			theoretical.push(moveFindingDir(dir.path, findingsTheoreticalDir(cwd)));
+		} else {
+			confirmed.push(dir.path);
+		}
+	}
+	return { confirmed, theoretical };
+}
+
+/**
+ * Promote a draft into a finding directory. Idempotent — calling twice with
+ * the same draft is a no-op once the finding dir exists. Returns the
+ * finding dir path.
+ */
+export function promoteDraftToFinding(cwd: string, draft: FindingDraft): string {
+	const dirName = `${draft.id}-${draft.slug}`;
+	const dir = join(findingsDir(cwd), dirName);
+	if (existsSync(dir)) return dir;
+	mkdirSync(dir, { recursive: true });
+	const out: Record<string, unknown> = { ...draft.frontmatter };
+	out.id = draft.id;
+	out.slug = draft.slug;
+	out.severity = draft.severity;
+	const draftPath = join(dir, "draft.md");
+	const yaml = stringifyYaml(out, { lineWidth: 0 }).trimEnd();
+	writeFileSync(draftPath, `---\n${yaml}\n---\n\n${draft.body.trimStart()}`);
+	return dir;
+}
+
+export interface PromotionResult {
+	promoted: string[]; // finding dir paths
+	skipped: string[]; // already-existing finding dir paths
+}
+
+/**
+ * Promote every draft in `piolium/findings-draft/` matching `prefix` to a
+ * finding directory. Returns the list of dirs written and the list of dirs
+ * that were already present.
+ */
+export function promoteDraftsByPrefix(cwd: string, prefix: string): PromotionResult {
+	const drafts = listDraftFindings(cwd, prefix);
+	const promoted: string[] = [];
+	const skipped: string[] = [];
+	for (const draft of drafts) {
+		if (isRejectedDraft(draft) || draft.severity === "low" || draft.severity === "info") continue;
+		const dirName = `${draft.id}-${draft.slug}`;
+		const dirPath = join(findingsDir(cwd), dirName);
+		const existed = existsSync(dirPath);
+		promoteDraftToFinding(cwd, draft);
+		if (existed) skipped.push(dirPath);
+		else promoted.push(dirPath);
+	}
+	return { promoted, skipped };
+}
+
+export interface ConsolidationEntry {
+	/** New severity-prefixed id assigned during consolidation, e.g. "C1", "H1", "M1". */
+	id: string;
+	slug: string;
+	severity: "critical" | "high" | "medium";
+	/** Original draft id from frontmatter, e.g. "q2-001", "p8-003". */
+	originalId: string;
+	/** Phase id from the draft frontmatter, when present. */
+	phase?: string;
+	/** Path to the source draft file in `piolium/findings-draft/`. */
+	sourcePath: string;
+	/** Path to the created finding directory under `piolium/findings/`. */
+	findingDir: string;
+}
+
+export interface ConsolidationDropped {
+	originalId: string;
+	severity: FindingDraft["severity"];
+	sourcePath: string;
+	reason: "below-threshold" | "rejected";
+	status?: string;
+}
+
+export interface ConsolidationResult {
+	promoted: ConsolidationEntry[];
+	dropped: ConsolidationDropped[];
+}
+
+const SEVERITY_RANK: Record<FindingDraft["severity"], number> = {
+	critical: 0,
+	high: 1,
+	medium: 2,
+	low: 3,
+	info: 4,
+};
+
+const SEVERITY_LETTER = { critical: "C", high: "H", medium: "M" } as const;
+
+const REJECTED_VALUES = new Set([
+	"rejected",
+	"rejected-fp",
+	"false-positive",
+	"false_positive",
+	"fp",
+	"invalid",
+	"not-valid",
+	"not_valid",
+	"noise",
+	"non-security",
+	"non_security",
+]);
+
+export function isRejectedDraft(draft: FindingDraft): boolean {
+	const values = [
+		draft.status,
+		draft.verdict,
+		draft.frontmatter.outcome,
+		draft.frontmatter.decision,
+		draft.frontmatter.fp_status,
+		draft.frontmatter.confirm_status,
+		draft.frontmatter["Confirm-Status"],
+	];
+	return values.some((value) => {
+		if (typeof value !== "string") return false;
+		const normalized = value.toLowerCase().trim();
+		return REJECTED_VALUES.has(normalized) || normalized.includes("false-positive");
+	});
+}
+
+export function isPromotableDraft(draft: FindingDraft): boolean {
+	return !isRejectedDraft(draft) && draft.severity !== "low" && draft.severity !== "info";
+}
+
+/**
+ * Promote drafts matching any of `prefixes` into severity-prefixed finding
+ * directories. Drafts with severity below "medium" are dropped (not
+ * promoted) — matching the upstream archon-audit convention. Returns a
+ * manifest of the promotions and drops, suitable for serializing as a
+ * consolidation manifest.
+ *
+ * IDs are assigned deterministically: drafts are stable-sorted by
+ * (severity, source path), then numbered C1.. / H1.. / M1.. per severity.
+ *
+ * If a finding directory with the same `<id>-<slug>` name already exists,
+ * the existing directory is reused (idempotent for re-runs / resume).
+ */
+export function consolidateDrafts(cwd: string, prefixes: string[]): ConsolidationResult {
+	const seen = new Set<string>();
+	const drafts: FindingDraft[] = [];
+	for (const prefix of prefixes) {
+		for (const draft of listDraftFindings(cwd, prefix)) {
+			if (seen.has(draft.path)) continue;
+			seen.add(draft.path);
+			drafts.push(draft);
+		}
+	}
+	drafts.sort((a, b) => {
+		const sa = SEVERITY_RANK[a.severity];
+		const sb = SEVERITY_RANK[b.severity];
+		if (sa !== sb) return sa - sb;
+		return a.path.localeCompare(b.path);
+	});
+
+	const counters: Record<"critical" | "high" | "medium", number> = {
+		critical: 0,
+		high: 0,
+		medium: 0,
+	};
+	const promoted: ConsolidationEntry[] = [];
+	const dropped: ConsolidationDropped[] = [];
+	for (const draft of drafts) {
+		if (isRejectedDraft(draft)) {
+			dropped.push({
+				originalId: draft.id,
+				severity: draft.severity,
+				sourcePath: draft.path,
+				reason: "rejected",
+				...((draft.status ?? draft.verdict) ? { status: draft.status ?? draft.verdict } : {}),
+			});
+			continue;
+		}
+		if (draft.severity === "low" || draft.severity === "info") {
+			dropped.push({
+				originalId: draft.id,
+				severity: draft.severity,
+				sourcePath: draft.path,
+				reason: "below-threshold",
+			});
+			continue;
+		}
+		counters[draft.severity] += 1;
+		const newId = `${SEVERITY_LETTER[draft.severity]}${counters[draft.severity]}`;
+		const promotedDraft: FindingDraft = {
+			...draft,
+			id: newId,
+			frontmatter: {
+				...draft.frontmatter,
+				original_id: draft.id,
+				...(draft.phase ? { phase: draft.phase } : {}),
+			},
+		};
+		const findingDir = promoteDraftToFinding(cwd, promotedDraft);
+		mkdirSync(join(findingDir, "evidence"), { recursive: true });
+		promoted.push({
+			id: newId,
+			slug: draft.slug,
+			severity: draft.severity,
+			originalId: draft.id,
+			...(draft.phase ? { phase: draft.phase } : {}),
+			sourcePath: draft.path,
+			findingDir,
+		});
+	}
+	return { promoted, dropped };
+}
+
+export interface FindingFrontmatter {
+	id: string;
+	slug: string;
+	severity: FindingDraft["severity"];
+	[k: string]: unknown;
+}
+
+export function readFindingFrontmatter(findingDir: string): FindingFrontmatter | undefined {
+	const draft = join(findingDir, "draft.md");
+	if (!existsSync(draft)) return undefined;
+	let frontmatter: Record<string, unknown>;
+	try {
+		({ frontmatter } = splitFrontmatter(readFileSync(draft, "utf8")));
+	} catch {
+		return undefined;
+	}
+	const id = typeof frontmatter.id === "string" ? frontmatter.id : "";
+	const slug = typeof frontmatter.slug === "string" ? frontmatter.slug : "";
+	if (!id || !slug) return undefined;
+	return {
+		...frontmatter,
+		id,
+		slug,
+		severity: normalizeSeverity(frontmatter.severity),
+	};
+}
+
+/** Re-export for callers that already imported via this module. */
+export { parseYaml, stringifyYaml };

package/extensions/piolium/heartbeat.ts

@@ -0,0 +1,182 @@
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+export interface PhaseHeartbeat {
+	phase: string;
+	label: string;
+	startedAtMs: number;
+	lastEventAtMs: number;
+	nowMs: number;
+	lastToolName?: string;
+	lastToolSummary?: string;
+	lastAssistantSummary?: string;
+	runId?: string;
+}
+
+export interface PhaseHeartbeatTracker {
+	recordEvent(event: AgentSessionEvent): void;
+	snapshot(nowMs?: number): PhaseHeartbeat;
+}
+
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+export const DEFAULT_HEARTBEAT_QUIET_MS = 90_000;
+export const DEFAULT_HEARTBEAT_STALLED_MS = 5 * 60_000;
+export const PHASE_HEARTBEAT_UI_COLOR = "mdLink";
+
+export function createPhaseHeartbeatTracker(options: {
+	phase: string;
+	label: string;
+	runId?: string;
+	nowMs?: number;
+}): PhaseHeartbeatTracker {
+	const startedAtMs = options.nowMs ?? Date.now();
+	let lastEventAtMs = startedAtMs;
+	let lastToolName: string | undefined;
+	let lastToolSummary: string | undefined;
+	let lastAssistantSummary: string | undefined;
+
+	return {
+		recordEvent(event) {
+			lastEventAtMs = Date.now();
+			if (event.type === "tool_execution_start") {
+				const toolName = stringFromUnknown((event as { toolName?: unknown }).toolName);
+				if (toolName) lastToolName = toolName;
+				const summary = summarizeArgs((event as { args?: unknown }).args);
+				lastToolSummary = summary || undefined;
+			}
+			if (event.type === "message_end") {
+				const message = (event as { message?: unknown }).message;
+				const text = extractAssistantText(
+					message && typeof message === "object"
+						? (message as { content?: unknown }).content
+						: undefined,
+				);
+				lastAssistantSummary = compactLine(text, 80) || undefined;
+			}
+		},
+		snapshot(nowMs = Date.now()) {
+			return {
+				phase: options.phase,
+				label: options.label,
+				startedAtMs,
+				lastEventAtMs,
+				nowMs,
+				...(lastToolName ? { lastToolName } : {}),
+				...(lastToolSummary ? { lastToolSummary } : {}),
+				...(lastAssistantSummary ? { lastAssistantSummary } : {}),
+				...(options.runId ? { runId: options.runId } : {}),
+			};
+		},
+	};
+}
+
+export function formatPhaseHeartbeat(
+	heartbeat: PhaseHeartbeat,
+	options: {
+		quietMs?: number;
+		stalledMs?: number;
+		nowMs?: number;
+		includePhase?: boolean;
+	} = {},
+): string {
+	const nowMs = options.nowMs ?? heartbeat.nowMs;
+	const quietMs = options.quietMs ?? DEFAULT_HEARTBEAT_QUIET_MS;
+	const stalledMs = options.stalledMs ?? DEFAULT_HEARTBEAT_STALLED_MS;
+	const elapsedMs = Math.max(0, nowMs - heartbeat.startedAtMs);
+	const idleMs = Math.max(0, nowMs - heartbeat.lastEventAtMs);
+	const prefix = options.includePhase === false ? "" : `${heartbeat.phase} `;
+	const status = idleMs >= stalledMs ? "may be stalled" : "running";
+	const idle =
+		idleMs >= quietMs
+			? `quiet for ${formatDuration(idleMs)}`
+			: `last output ${formatDuration(idleMs)} ago`;
+	const tool = heartbeat.lastToolName
+		? `last tool: ${compactLine(
+				`${heartbeat.lastToolName}${heartbeat.lastToolSummary ? ` ${heartbeat.lastToolSummary}` : ""}`,
+				90,
+			)}`
+		: heartbeat.lastAssistantSummary
+			? `last note: ${heartbeat.lastAssistantSummary}`
+			: "waiting for first event";
+	return `${prefix}${status} ${formatDuration(elapsedMs)} · ${idle} · ${tool}`;
+}
+
+export function formatPhaseHeartbeatStatusLine(
+	heartbeat: PhaseHeartbeat,
+	options: Parameters<typeof formatPhaseHeartbeat>[1] = {},
+): string {
+	return `↳ health: ${formatPhaseHeartbeat(heartbeat, options)}`;
+}
+
+export function phaseHeartbeatColor(
+	heartbeat: PhaseHeartbeat,
+	options: { quietMs?: number; stalledMs?: number; nowMs?: number } = {},
+): "warning" | "muted" | "dim" {
+	const nowMs = options.nowMs ?? heartbeat.nowMs;
+	const quietMs = options.quietMs ?? DEFAULT_HEARTBEAT_QUIET_MS;
+	const stalledMs = options.stalledMs ?? DEFAULT_HEARTBEAT_STALLED_MS;
+	const idleMs = Math.max(0, nowMs - heartbeat.lastEventAtMs);
+	if (idleMs >= stalledMs) return "warning";
+	if (idleMs >= quietMs) return "muted";
+	return "dim";
+}
+
+export function heartbeatStateFields(heartbeat: PhaseHeartbeat): {
+	heartbeat_at: string;
+	last_event_at: string;
+	last_tool: string | null;
+	last_tool_summary: string | null;
+	run_id: string | null;
+} {
+	return {
+		heartbeat_at: new Date(heartbeat.nowMs).toISOString(),
+		last_event_at: new Date(heartbeat.lastEventAtMs).toISOString(),
+		last_tool: heartbeat.lastToolName ?? null,
+		last_tool_summary: heartbeat.lastToolSummary ?? null,
+		run_id: heartbeat.runId ?? null,
+	};
+}
+
+function formatDuration(ms: number): string {
+	const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+	const seconds = totalSeconds % 60;
+	if (hours > 0) {
+		return `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+	}
+	return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+
+function summarizeArgs(args: unknown): string {
+	if (!args || typeof args !== "object") return "";
+	const obj = args as Record<string, unknown>;
+	const pickKey = ["file_path", "path", "command", "pattern", "query", "url"].find(
+		(k) => typeof obj[k] === "string",
+	);
+	if (pickKey) return compactLine(String(obj[pickKey]), 90);
+	try {
+		return compactLine(JSON.stringify(obj), 90);
+	} catch {
+		return "";
+	}
+}
+
+function extractAssistantText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((c) => c && typeof c === "object" && (c as { type?: string }).type === "text")
+		.map((c) => (c as { text?: unknown }).text)
+		.filter((text): text is string => typeof text === "string")
+		.join("");
+}
+
+function stringFromUnknown(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function compactLine(text: string, max: number): string {
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	if (collapsed.length <= max) return collapsed;
+	return `${collapsed.slice(0, max - 1)}…`;
+}