@aeondave/pi-persona 1.17.0 → 1.17.3

package/src/ui/persona-settings.ts

@@ -0,0 +1,328 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	Text,
+	truncateToWidth,
+	visibleWidth,
+	type Component,
+	type KeybindingsManager,
+	type TUI,
+} from "@earendil-works/pi-tui";
+
+import { compactInlineText, sanitizeTerminalText } from "./presentation.ts";
+import type { SettingId, SettingKind } from "../core/settings.ts";
+
+export interface SettingsPanelRow {
+	id: SettingId;
+	group: string;
+	label: string;
+	description: string;
+	kind: SettingKind;
+	choices?: readonly string[];
+	activeValue: unknown;
+	savedValue: unknown;
+	hasSavedValue: boolean;
+	source: "environment" | "saved" | "default";
+	locked: boolean;
+	pendingReload?: boolean;
+	applyWhen: string;
+	min?: number;
+	max?: number;
+}
+
+export interface SettingsPanelData {
+	file: string;
+	lastPersona: string | null;
+	rows: readonly SettingsPanelRow[];
+	notice?: string;
+	initialQuery?: string;
+	initialSelectedId?: SettingId;
+}
+
+export type SettingsPanelAction =
+	| { type: "edit"; id: SettingId }
+	| { type: "reset"; id: SettingId }
+	| { type: "models" }
+	| { type: "diagnostics" }
+	| { type: "close" };
+
+/** Case-insensitive search across the registry's user-facing metadata; source order is retained. */
+export function filterSettingsRows(rows: readonly SettingsPanelRow[], query: string): SettingsPanelRow[] {
+	const needle = sanitizeTerminalText(query).trim().toLocaleLowerCase();
+	if (!needle) return [...rows];
+	return rows.filter((row) => {
+		const haystack = [row.id, row.group, row.label, row.description, row.applyWhen]
+			.concat(row.choices ?? [])
+			.join(" ")
+			.toLocaleLowerCase();
+		return haystack.includes(needle);
+	});
+}
+
+/** Scroll offset that keeps the selected setting inside a bounded list viewport. */
+export function visibleSettingsWindow(selected: number, size: number, total: number, previous: number): number {
+	const count = Math.max(0, Math.floor(total));
+	const page = Math.max(1, Math.floor(size));
+	if (count <= page) return 0;
+	const index = Math.max(0, Math.min(Math.floor(selected), count - 1));
+	let scroll = Math.max(0, Math.floor(previous));
+	if (index < scroll) scroll = index;
+	else if (index >= scroll + page) scroll = index - page + 1;
+	return Math.max(0, Math.min(scroll, count - page));
+}
+
+/** Human-readable, one-line values for settings rows and details. */
+export function formatSettingValue(value: unknown): string {
+	if (value === undefined) return "(unset)";
+	if (value === null) return "(unset)";
+	if (typeof value === "boolean") return value ? "On" : "Off";
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : "(invalid number)";
+	if (Array.isArray(value)) {
+		if (value.length === 0) return "(empty list)";
+		return value.map((item) => compactInlineText(String(item), { maxChars: 160 })).join(", ");
+	}
+	if (typeof value === "string") return compactInlineText(value, { maxChars: 160 }) || "(empty)";
+	return compactInlineText(String(value), { maxChars: 160 }) || "(empty)";
+}
+
+/** One fully composed list entry, clipped by terminal columns rather than JS string length. */
+export function composeSettingsRow(row: SettingsPanelRow, selected: boolean, maxColumns: number, theme: Theme): string {
+	const width = Math.max(1, Math.floor(maxColumns));
+	const marker = selected ? theme.fg("accent", "▸ ") : "  ";
+	const group = theme.fg("dim", `[${compactInlineText(row.group, { maxChars: 32 })}] `);
+	const label = compactInlineText(row.label, { maxChars: Math.max(16, Math.floor(width * 0.55)) });
+	const value = compactInlineText(formatSettingValue(row.activeValue), { maxChars: Math.max(16, Math.floor(width * 0.44)) });
+	const source = row.locked ? theme.fg("warning", "  env locked") : row.hasSavedValue ? theme.fg("dim", "  saved") : "";
+	const valueText = theme.fg("dim", `  ${value}`);
+	return fitLine(`${marker}${group}${label}${valueText}${source}`, width);
+}
+
+function fitLine(line: string, width: number): string {
+	// Callers sanitize all registry, path, and stored-value text before applying theme roles. Keep
+	// those trusted theme escapes intact so the host palette survives truncation and layout.
+	// Do not normalize ordinary spaces: columnLines uses them to keep the detail column aligned.
+	const safe = line.replace(/[\r\n]+/g, " ");
+	if (visibleWidth(safe) <= width) return safe;
+	return truncateToWidth(safe, width, "…");
+}
+
+function wrappedLines(text: string, width: number): string[] {
+	const safe = sanitizeTerminalText(text).replace(/\r\n?/g, "\n");
+	const rendered = new Text(safe, 0, 0).render(Math.max(1, width));
+	return rendered.map((line) => fitLine(line, Math.max(1, width)));
+}
+
+function detailLines(row: SettingsPanelRow, width: number, limit: number, theme: Theme): string[] {
+	const safeWidth = Math.max(1, width);
+	const lines: string[] = [theme.fg("accent", theme.bold(compactInlineText(row.label, { maxChars: 160 })))];
+	lines.push(theme.fg("dim", `Group: ${compactInlineText(row.group, { maxChars: 100 })}`));
+	const fixedLines = row.pendingReload ? 7 : 6;
+	const description = wrappedLines(row.description, safeWidth).slice(0, Math.max(1, Math.min(3, limit - fixedLines)));
+	lines.push(...description);
+	lines.push(`Active now: ${formatSettingValue(row.activeValue)}`);
+	lines.push(`Saved override: ${row.hasSavedValue ? formatSettingValue(row.savedValue) : "none"}`);
+	lines.push(`Source: ${row.locked ? "environment · locked" : row.source}`);
+	if (row.pendingReload) lines.push("Status: saved value is pending /reload");
+	lines.push(`Applies: ${compactInlineText(row.applyWhen, { maxChars: 120 })}`);
+	if (row.locked && row.choices?.length) lines.push("Environment value must be unset to edit.");
+	return lines.slice(0, Math.max(1, limit)).map((line) => fitLine(line, safeWidth));
+}
+
+function listLines(
+	rows: readonly SettingsPanelRow[],
+	selectedIndex: number,
+	height: number,
+	width: number,
+	previousScroll: number,
+	theme: Theme,
+): { lines: string[]; scroll: number } {
+	const limit = Math.max(1, height);
+	if (rows.length === 0) return { lines: [theme.fg("dim", "No settings match this filter.")], scroll: 0 };
+	const needsMarkers = rows.length > limit;
+	const itemCount = Math.max(1, limit - (needsMarkers ? 2 : 0));
+	const scroll = visibleSettingsWindow(selectedIndex, itemCount, rows.length, previousScroll);
+	const end = Math.min(rows.length, scroll + itemCount);
+	const lines: string[] = [];
+	if (scroll > 0) lines.push(theme.fg("dim", `↑ ${scroll} settings above`));
+	for (let index = scroll; index < end; index++) {
+		const row = rows[index];
+		if (row) lines.push(composeSettingsRow(row, index === selectedIndex, width, theme));
+	}
+	if (end < rows.length) lines.push(theme.fg("dim", `↓ ${rows.length - end} settings below`));
+	return { lines: lines.slice(0, limit).map((line) => fitLine(line, width)), scroll };
+}
+
+function columnLines(left: readonly string[], right: readonly string[], leftWidth: number, rightWidth: number, width: number): string[] {
+	const count = Math.max(left.length, right.length);
+	const gap = "  ";
+	const lines: string[] = [];
+	for (let index = 0; index < count; index++) {
+		const leftLine = fitLine(left[index] ?? "", leftWidth);
+		const pad = Math.max(0, leftWidth - visibleWidth(leftLine));
+		const rightLine = fitLine(right[index] ?? "", rightWidth);
+		lines.push(fitLine(`${leftLine}${" ".repeat(pad)}${gap}${rightLine}`, width));
+	}
+	return lines;
+}
+
+function isPrintable(key: string): boolean {
+	if (key.length !== 1) return false;
+	const code = key.charCodeAt(0);
+	return code >= 0x20 && code !== 0x7f;
+}
+
+/** Full-page settings workbench. Dialogs are returned as actions so command handlers can use Pi's native prompts. */
+export class PersonaSettingsPanel implements Component {
+	private query: string;
+	private searchMode = false;
+	private selectedIndex = 0;
+	private scroll = 0;
+	private lastWidth = 80;
+	private readonly tui: TUI;
+	private readonly theme: Theme;
+	private readonly keybindings: KeybindingsManager;
+	private readonly data: SettingsPanelData;
+	private readonly onAction: (action: SettingsPanelAction) => void;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		keybindings: KeybindingsManager,
+		data: SettingsPanelData,
+		onAction: (action: SettingsPanelAction) => void,
+	) {
+		this.tui = tui;
+		this.theme = theme;
+		this.keybindings = keybindings;
+		this.data = data;
+		this.onAction = onAction;
+		this.query = data.initialQuery ?? "";
+		const initialRows = filterSettingsRows(data.rows, this.query);
+		const initialIndex = data.initialSelectedId
+			? initialRows.findIndex((row) => row.id === data.initialSelectedId)
+			: -1;
+		this.selectedIndex = initialIndex >= 0 ? initialIndex : 0;
+	}
+
+	get searchQuery(): string {
+		return this.query;
+	}
+
+	get selectedId(): SettingId | undefined {
+		return filterSettingsRows(this.data.rows, this.query)[this.selectedIndex]?.id;
+	}
+
+	invalidate(): void {
+		// Rendering is derived entirely from the small immutable snapshot passed by the command.
+	}
+
+	render(width: number): string[] {
+		const pageWidth = Math.max(1, Math.floor(width));
+		this.lastWidth = pageWidth;
+		const rows = filterSettingsRows(this.data.rows, this.query);
+		if (this.selectedIndex >= rows.length) this.selectedIndex = Math.max(0, rows.length - 1);
+		const selected = rows[this.selectedIndex];
+		const terminalRows = Math.max(8, Math.floor(this.tui.terminal.rows || 24));
+		const title = this.theme.fg("accent", this.theme.bold("Persona settings"));
+		const file = fitLine(this.theme.fg("dim", `Configuration file: ${compactInlineText(this.data.file, { maxChars: 240 })}`), pageWidth);
+		const remembered = fitLine(this.theme.fg("dim", `Remembered persona: ${this.data.lastPersona ? compactInlineText(this.data.lastPersona, { maxChars: 120 }) : "none"}`), pageWidth);
+		// Show the configured primary binding; listing every alias would hide close/edit on narrow screens.
+		const keys = (action: "tui.select.up" | "tui.select.down" | "tui.select.confirm" | "tui.select.cancel"): string =>
+			this.keybindings.getKeys(action).slice(0, 1).map((key) => key === "escape" ? "esc" : key).join("/") || "unbound";
+		const move = `${keys("tui.select.up")}/${keys("tui.select.down")}`;
+		const confirm = keys("tui.select.confirm");
+		const cancel = keys("tui.select.cancel");
+		const filter = this.searchMode
+			? this.theme.fg("accent", `Filter (type, backspace, ${confirm}): ${compactInlineText(this.query, { maxChars: 120 })}▌`)
+			: this.query
+				? this.theme.fg("dim", `Filter: ${compactInlineText(this.query, { maxChars: 120 })}`)
+				: this.theme.fg("dim", "Filter: press / to search");
+		const header = [fitLine(title, pageWidth), file, remembered, fitLine(filter, pageWidth), ""];
+		const footer = [
+			...(this.data.notice ? [fitLine(this.theme.fg("warning", compactInlineText(this.data.notice, { maxChars: 200 })), pageWidth)] : []),
+			...(pageWidth < 76
+				? [`${move} move  ${confirm} edit  r reset`, `/ filter  m models  d info  ${cancel} close`]
+				: [`${move} move  ${confirm} edit  r reset  / filter  m models  d diagnostics  ${cancel} close`])
+				.map((hint) => fitLine(this.theme.fg("dim", hint), pageWidth)),
+		];
+		const bodyHeight = Math.max(1, terminalRows - header.length - footer.length);
+		let body: string[];
+		if (!selected) {
+			body = [this.theme.fg("dim", "No settings match this filter.")];
+		} else if (pageWidth >= 80) {
+			const leftWidth = Math.max(24, Math.floor((pageWidth - 2) * 0.42));
+			const rightWidth = Math.max(1, pageWidth - leftWidth - 2);
+			const listing = listLines(rows, this.selectedIndex, bodyHeight, leftWidth, this.scroll, this.theme);
+			this.scroll = listing.scroll;
+			const details = detailLines(selected, rightWidth, bodyHeight, this.theme);
+			body = columnLines(listing.lines, details, leftWidth, rightWidth, pageWidth);
+		} else {
+			const detailsBudget = Math.min(Math.max(3, Math.floor(bodyHeight * 0.55)), Math.max(1, bodyHeight - 1));
+			const listBudget = Math.max(1, bodyHeight - detailsBudget - 1);
+			const listing = listLines(rows, this.selectedIndex, listBudget, pageWidth, this.scroll, this.theme);
+			this.scroll = listing.scroll;
+			const details = detailLines(selected, pageWidth, Math.max(1, bodyHeight - listing.lines.length - 1), this.theme);
+			body = [...listing.lines, "", ...details].slice(0, bodyHeight);
+		}
+		const output = [...header, ...body, ...footer].slice(0, terminalRows);
+		return output.map((line) => fitLine(line, pageWidth));
+	}
+
+	handleInput(key: string): void {
+		const matches = (binding: "tui.select.up" | "tui.select.down" | "tui.select.confirm" | "tui.select.cancel"): boolean =>
+			this.keybindings.matches(key, binding);
+		const rows = filterSettingsRows(this.data.rows, this.query);
+		if (this.searchMode) {
+			if (matches("tui.select.cancel")) {
+				this.query = "";
+				this.searchMode = false;
+				this.selectedIndex = 0;
+				this.scroll = 0;
+			} else if (matches("tui.select.confirm")) {
+				this.searchMode = false;
+			} else if (key === "\x7f" || key === "\b") {
+				this.query = this.query.slice(0, -1);
+				this.selectedIndex = 0;
+				this.scroll = 0;
+			} else if (isPrintable(key) && key !== "/") {
+				this.query += key;
+				this.selectedIndex = 0;
+				this.scroll = 0;
+			}
+			this.tui.requestRender();
+			return;
+		}
+		if (matches("tui.select.cancel")) {
+			if (this.query) {
+				this.query = "";
+				this.selectedIndex = 0;
+				this.scroll = 0;
+			} else this.onAction({ type: "close" });
+		} else if (key === "/") {
+			this.searchMode = true;
+		} else if (matches("tui.select.up")) {
+			this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+		} else if (matches("tui.select.down")) {
+			this.selectedIndex = Math.min(Math.max(0, rows.length - 1), this.selectedIndex + 1);
+		} else if (matches("tui.select.confirm")) {
+			const row = rows[this.selectedIndex];
+			if (row) this.onAction({ type: "edit", id: row.id });
+		} else if (key.toLocaleLowerCase() === "r") {
+			const row = rows[this.selectedIndex];
+			if (row) this.onAction({ type: "reset", id: row.id });
+		} else if (key.toLocaleLowerCase() === "m") {
+			this.onAction({ type: "models" });
+		} else if (key.toLocaleLowerCase() === "d") {
+			this.onAction({ type: "diagnostics" });
+		}
+		this.tui.requestRender();
+	}
+
+	/** Exposed to command handlers so reopening after a native dialog preserves navigation. */
+	get viewState(): { query: string; selectedId: SettingId | undefined } {
+		return { query: this.query, selectedId: this.selectedId };
+	}
+
+	get pageWidth(): number {
+		return this.lastWidth;
+	}
+}

package/src/ui/presentation.ts

@@ -168,3 +168,27 @@ export function compactVisibleText(
 		originalChars: input.length,
 	};
 }
+
+/**
+ * The prompt an operator reads before releasing a flow checkpoint: which gate, what runs next,
+ * and enough of the gated phase's output to decide. The prompt is modal, so it cannot point at an
+ * "expand" key; it states how much it left out instead.
+ */
+export function gateReviewText(gate: {
+	flow: string;
+	phase: string;
+	/** The phases the approval releases. */
+	next: ReadonlyArray<{ id: string; strategy: string }>;
+	output: string;
+}): string {
+	const name = (value: string): string => compactInlineText(value, { maxChars: 64 });
+	const body = compactVisibleText(gate.output, { maxLines: 12, maxLineChars: 100 });
+	return [
+		`Checkpoint "${name(gate.phase)}" of flow "${name(gate.flow)}" — approve and continue?`,
+		...(gate.next.length > 0 ? [`then: ${gate.next.map((p) => `${name(p.id)} (${name(p.strategy)})`).join(", ")}`] : []),
+		// Everything below is the child's text: a fixed rule keeps it from passing as more prompt.
+		"--- gated output (untrusted) ---",
+		body.text,
+		...(body.truncated ? [`(+${Math.max(0, gate.output.length - body.text.length)} characters not shown)`] : []),
+	].join("\n");
+}

package/src/ui/report-body.ts

@@ -0,0 +1,63 @@
+/** UI-only prose projection. Never rewrites stored/model-facing text or unwraps trust fences. */
+import { getMarkdownTheme, type Theme, type ThemeBg } from "@earendil-works/pi-coding-agent";
+import { Markdown, Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { sanitizeTerminalText } from "./presentation.ts";
+
+interface ReportBodyOptions {
+	/** Trusted chrome stays literal Text, outside the Markdown body. Evaluated at paint time. */
+	header?: (width: number) => string;
+	/** Custom session cards only. Normal tools already have the host's shell. */
+	background?: ThemeBg;
+	padding?: number;
+}
+
+class ReportBody implements Component {
+	private readonly markdownTheme = getMarkdownTheme();
+	private readonly markdown: Markdown;
+	readonly source: string;
+	private theme: Theme;
+	private options: ReportBodyOptions;
+	constructor(source: string, theme: Theme, options: ReportBodyOptions) {
+		this.source = source;
+		this.theme = theme;
+		this.options = options;
+		// No defaultTextStyle: Pi caches its default style prefix independently of invalidate().
+		// Apply the fallback foreground/background outside Markdown so theme changes stay fresh.
+		this.markdown = new Markdown(source, 0, 0, this.markdownTheme);
+	}
+	update(theme: Theme, options: ReportBodyOptions): void {
+		this.theme = theme;
+		this.options = options;
+		this.invalidate();
+	}
+	invalidate(): void {
+		Object.assign(this.markdownTheme, getMarkdownTheme());
+		// Native Markdown retains its source-token cache while clearing themed/layout output.
+		this.markdown.invalidate();
+	}
+	render(width: number): string[] {
+		if (width <= 0) return [];
+		const padding = Math.min(Math.max(0, Math.floor(this.options.padding ?? 0)), Math.max(0, Math.floor((width - 1) / 2)));
+		const innerWidth = Math.max(1, width - 2 * padding);
+		const header = this.options.header?.(innerWidth);
+		const lines = [
+			...(header ? new Text(header, 0, 0).render(innerWidth) : []),
+			...this.markdown.render(innerWidth).map((line) => this.theme.fg("toolOutput", line)),
+		];
+		const background = this.options.background;
+		return new Text(lines.join("\n"), padding, 0, background ? (text) => this.theme.bg(background, text) : undefined)
+			.render(width).map((line) => truncateToWidth(line, width));
+	}
+}
+
+/** Keep one native Markdown instance per report. Width changes reflow natively; invalidate() refreshes
+ * theme/layout, not source tokens. Tool callbacks can also reuse Pi's lastComponent across redraws.
+ * No global transcript/content cache: old reports are reclaimed with their host components. */
+export function createReportBody(text: string, theme: Theme, options: ReportBodyOptions = {}, previous?: Component): Component {
+	const source = sanitizeTerminalText(text);
+	if (previous instanceof ReportBody && previous.source === source) {
+		previous.update(theme, options);
+		return previous;
+	}
+	return new ReportBody(source, theme, options);
+}

package/src/ui/session-cards.ts

@@ -0,0 +1,189 @@
+/** Operator-only presentation of existing session payloads. No delivery, storage or tool shells. */
+import type { ExtensionAPI, Theme, ThemeBg, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { formatDuration } from "../core/time.ts";
+import { neutralizeMonitorUnicode } from "../core/monitor-output.ts";
+import { createReportBody } from "./report-body.ts";
+import { MONITOR_LOG_ENTRY, parseMonitorLogRecord, type MonitorLogRecord } from "../monitor/archive.ts";
+import { summarizeFailure } from "./failure-summary.ts";
+import { compactInlineText, compactVisibleText, sanitizeTerminalText, type CompactVisibleTextResult } from "./presentation.ts";
+
+type State = "neutral" | "success" | "attention" | "error";
+const COLORS: Record<State, { bg: ThemeBg; fg: ThemeColor }> = {
+	neutral: { bg: "customMessageBg", fg: "accent" },
+	success: { bg: "toolSuccessBg", fg: "success" },
+	attention: { bg: "toolPendingBg", fg: "warning" },
+	error: { bg: "toolErrorBg", fg: "error" },
+};
+interface Card {
+	title: string;
+	state: State;
+	full: string;
+	preview: (width: number) => Pick<CompactVisibleTextResult, "text" | "truncated">;
+	metadata?: string;
+	/** Selected only by trusted surface/envelope metadata, never prose keywords. */
+	markdown?: boolean;
+}
+
+/** All seven surfaces share semantic chrome. Literal paths style at paint time; report bodies
+ * use native Markdown's invalidatable layout cache. Pi rebuilds callbacks on transcript invalidation. */
+function createSessionCard(card: Card, expanded: boolean, theme: Theme, detailHint: () => string, outputPad = 0): Component {
+	if (expanded && card.markdown) {
+		return createReportBody(card.full || "(no output)", theme, {
+			padding: outputPad,
+			background: COLORS[card.state].bg,
+			header: (width) => [
+				theme.fg(COLORS[card.state].fg, theme.bold(truncateToWidth(sanitizeTerminalText(card.title), width))),
+				...(card.metadata ? [theme.fg("dim", truncateToWidth(card.metadata, width))] : []),
+			].join("\n"),
+		});
+	}
+	return {
+		invalidate() { /* Literal Text path has no themed/layout cache. */ },
+		render(width) {
+			if (width <= 0) return [];
+			const padding = Math.min(Math.max(0, Math.floor(outputPad)), Math.max(0, Math.floor((width - 1) / 2)));
+			const innerWidth = Math.max(1, width - padding * 2);
+			const colors = COLORS[card.state];
+			const preview = expanded ? undefined : card.preview(innerWidth);
+			const body = expanded ? card.full : preview?.text ?? "(no output)";
+			const lines = [
+				theme.fg(colors.fg, theme.bold(truncateToWidth(sanitizeTerminalText(card.title), innerWidth))),
+				...(card.metadata ? [theme.fg("dim", truncateToWidth(card.metadata, innerWidth))] : []),
+				...sanitizeTerminalText(body || "(no output)").split("\n").map((line) => theme.fg("toolOutput", line)),
+				...(preview?.truncated ? [theme.fg("dim", truncateToWidth(detailHint(), innerWidth))] : []),
+			];
+			// Text owns wrapping and full-row padding/background, including embedded foreground resets.
+			// A terminal narrower than a single wide glyph cannot display that glyph; clip only there.
+			return new Text(lines.join("\n"), padding, 0, (text) => theme.bg(colors.bg, text))
+				.render(width).map((line) => truncateToWidth(line, width));
+		},
+	};
+}
+
+function preview(full: string, maxLines: number, maxColumns: number): Card["preview"] {
+	return (width) => compactVisibleText(full, { maxLines, maxLineChars: Math.min(width, maxColumns) });
+}
+
+/** Only this exact runtime-owned aggregate is evidence of settlement. No keyword scan of output,
+ * asks, timers, monitor event bodies, or peers. Legacy/unknown follow-ups remain informational. */
+function followUpState(full: string): { state: State; status: string } {
+	const first = full.split("\n", 1)[0] ?? "";
+	const summary = /^(?:\[pi-persona\] )?(\d+) async runs? settled — (\d+) done, (\d+) failed(?:, (\d+) stopped)?$/.exec(first);
+	if (summary) {
+		const total = Number(summary[1]);
+		const done = Number(summary[2]);
+		const failed = Number(summary[3]);
+		const stopped = Number(summary[4] ?? 0);
+		if ([total, done, failed, stopped].every(Number.isSafeInteger) && total > 0 && total === done + failed + stopped) {
+			if (failed > 0) return { state: "error", status: "failed" };
+			if (stopped > 0) return { state: "attention", status: "stopped" };
+			return { state: "success", status: "complete" };
+		}
+	}
+	return { state: "neutral", status: "info" };
+}
+
+function monitorState(record: MonitorLogRecord): { state: State; status: string } {
+	if (record.outcome === "error") return { state: "error", status: "failed" };
+	if (record.outcome === "timeout" || record.outcome === "cancelled") return { state: "attention", status: "stopped" };
+	if (record.outcome === "exit") {
+		// MonitorManager prepends this line before any untrusted stdout/stderr diagnostics.
+		const first = record.text.split("\n", 1)[0] ?? "";
+		const exit = /^process exited with exit code (-?\d+)$/.exec(first);
+		if (exit) return exit[1] === "0" ? { state: "success", status: "complete" } : { state: "error", status: "failed" };
+		if (/^process exited (?:by .+|with exit code -?\d+ \(signal .+\))$/.test(first)) return { state: "attention", status: "stopped" };
+	}
+	return { state: "neutral", status: "info" };
+}
+
+interface ResultEntry { label?: string; content?: string; ok?: boolean; stoppedAtGate?: string; failureKind?: string; error?: string }
+interface ContentEntry { content?: string; kind?: "routine" | "stall" }
+interface RunFailureEntry { id: string; label: string; agent: string; model?: string; durationMs?: number; error: string }
+
+export interface SessionCardOptions {
+	detailHint: () => string;
+	/** Existing bounded/fenced runtime formatter, injected to keep UI independent of tool wiring. */
+	monitorLog: (record: MonitorLogRecord) => string;
+}
+
+export function registerSessionCards(pi: Pick<ExtensionAPI, "registerMessageRenderer" | "registerEntryRenderer">, options: SessionCardOptions): void {
+	const sessionCard = (card: Card, expanded: boolean, theme: Theme, outputPad = 0): Component =>
+		createSessionCard(card, expanded, theme, options.detailHint, outputPad);
+	for (const customType of ["pi-persona", "exocom_received"] as const) {
+		pi.registerMessageRenderer(customType, (message, { expanded, outputPad }, theme) => {
+			const raw = typeof message.content === "string" ? message.content
+				: message.content.map((part) => part.type === "text" ? part.text : "[image]").join("\n");
+			const full = sanitizeTerminalText(raw);
+			const { state, status } = customType === "pi-persona" ? followUpState(full) : { state: "neutral" as const, status: "inbound" };
+			// Only the validated settlement envelope is a pi-persona report. Unknown is NOT
+			// Markdown: monitor stdout/stderr, timers and operational notices share this type.
+			const markdown = customType === "exocom_received" || status !== "info";
+			return sessionCard({ title: customType === "pi-persona" ? `pi-persona · update · ${status}` : "exocom · inbound", state, full, markdown, preview: preview(full, 4, 100) }, expanded, theme, outputPad);
+		});
+	}
+	pi.registerEntryRenderer(MONITOR_LOG_ENTRY, (entry, { expanded }, theme) => {
+		const record = parseMonitorLogRecord(entry.data);
+		if (!record) return undefined;
+		const { state, status } = monitorState(record);
+		return sessionCard({
+			title: `Monitor log ${compactInlineText(record.entry.label)} · ${record.outcome} · ${status}`,
+			state, full: sanitizeTerminalText(options.monitorLog(record)),
+			preview: (width) => ({ text: `${compactInlineText(neutralizeMonitorUnicode(record.text), { maxChars: Math.min(width, 160) })}\n${compactInlineText(record.entry.id)} · monitor result`, truncated: true }),
+		}, expanded, theme);
+	});
+	pi.registerEntryRenderer<RunFailureEntry>("pi-persona-run-failure", (entry, { expanded }, theme) => {
+		const data = entry.data;
+		if (!data) return undefined;
+		const metadata = [compactInlineText(data.agent, { maxChars: 48 }), ...(data.model ? [compactInlineText(data.model, { maxChars: 96 })] : []), ...(data.durationMs !== undefined ? [formatDuration(data.durationMs)] : [])].join(" · ");
+		return sessionCard({
+			title: `${compactInlineText(data.label || data.agent, { maxChars: 80 })} · failed`, state: "error", metadata,
+			full: `Run ${compactInlineText(data.id)}\n${sanitizeTerminalText(data.error)}`,
+			preview: (width) => ({ text: compactVisibleText(summarizeFailure(data.error), { maxLines: 2, maxLineChars: Math.min(width, 100) }).text, truncated: true }),
+		}, expanded, theme);
+	});
+	pi.registerEntryRenderer<ResultEntry>("pi-persona-result", (entry, { expanded }, theme) => {
+		const data = entry.data;
+		if (!data) return undefined;
+		const full = sanitizeTerminalText(data.content || "(no output)");
+		const stopped = data.ok !== true && typeof data.stoppedAtGate === "string";
+		const state: State = stopped ? "attention" : data.ok === true ? "success" : data.ok === false ? "error" : "neutral";
+		const status = stopped ? `stopped · checkpoint ${compactInlineText(data.stoppedAtGate ?? "", { maxChars: 32 })}` : data.ok === true ? "complete" : data.ok === false ? "failed" : "unknown";
+		const cause = compactVisibleText([data.failureKind, data.error].filter(Boolean).join(" · "), { maxLines: 1, maxLineChars: 80 }).text;
+		return sessionCard({
+			title: `${compactInlineText(data.label ?? "", { maxChars: 96 }) || "result"} · ${status}${state === "error" && cause !== "(no output)" ? ` · ${cause}` : ""}`,
+			state, full, markdown: true, preview: preview(full, 3, 100),
+		}, expanded, theme);
+	});
+	pi.registerEntryRenderer<ContentEntry>("pi-persona-nudge", (entry, { expanded }, theme) => {
+		if (!entry.data) return undefined;
+		const full = sanitizeTerminalText(entry.data.content || "⟢ pi-persona · checkpoint");
+		const lines = full.split("\n").map((line) => line.trim()).filter(Boolean);
+		const header = compactInlineText(lines[0]?.replace(/^⟢\s*/, "") ?? "", { maxChars: 96 }) || "pi-persona · checkpoint";
+		const details = lines.slice(1);
+		const trigger = details.find((line) => line.startsWith("Trigger:"));
+		const action = details.find((line) => /^(?:Action|Verify|Otherwise):/.test(line));
+		const selected = [trigger, action].filter((line): line is string => line !== undefined);
+		const chosen = selected.length > 0 ? selected : details.slice(0, 2);
+		return sessionCard({
+			title: header, state: "attention", full,
+			preview: (width) => {
+				const result = preview(chosen.join("\n"), 2, 100)(width);
+				return { text: result.text, truncated: result.truncated || details.some((line) => !chosen.includes(line)) };
+			},
+		}, expanded, theme);
+	});
+	pi.registerEntryRenderer<ContentEntry>("pi-persona-status", (entry, { expanded }, theme) => {
+		if (!entry.data) return undefined;
+		const full = sanitizeTerminalText(entry.data.content || "Async activity · routine check-in");
+		const stall = entry.data.kind === "stall";
+		const digest = full.split("\n").slice(1).filter((line) => line.trim().length > 0);
+		return sessionCard({
+			title: stall ? "pi-persona · possible stall" : "pi-persona · async status", state: stall ? "attention" : "neutral", full,
+			preview: (width) => {
+				const result = preview(digest.slice(0, 2).join("\n") || full, 2, 140)(width);
+				return { text: result.text, truncated: result.truncated || digest.length > 2 };
+			},
+		}, expanded, theme);
+	});
+}