@aeondave/pi-persona 1.15.2

package/src/ui/agent-tree.ts

@@ -0,0 +1,307 @@
+import { compactTokens } from "../core/format.ts";
+import { formatDuration } from "../core/time.ts";
+import { compactInlineText } from "./presentation.ts";
+
+/**
+ * The unified agent tree — a single live model of *every* agent in flight,
+ * regardless of how it was spawned: strategy cores (magi/fanout/critic), the
+ * `delegate` tool's sub-agents, and dynamic specialists. The UI layer renders
+ * one sticky tree above the input from this model, and (later) lets the user
+ * drill into a node. Sources only push status/detail; rendering is pure.
+ */
+
+export type AgentNodeStatus = "running" | "done" | "failed" | "stopped";
+export type AgentNodeKind = "subagent" | "delegate" | "council" | "flow" | "phase";
+
+export interface AgentNode {
+	id: string;
+	label: string;
+	parentId: string | undefined;
+	status: AgentNodeStatus;
+	/** Semantic role in the orchestration graph; omitted by legacy callers. */
+	kind?: AgentNodeKind;
+	/** Configured agent definition (operator/reviewer/…), if known. */
+	agent?: string;
+	model?: string;
+	/** A short trailing annotation (usage, current activity), shown after the label. */
+	detail: string | undefined;
+	/** The agent's output buffer, shown when the user drills into the node. */
+	output?: string;
+	/** Clock data (ms since epoch). Set by the tree on add; `lastAdvanceAt` moves on real progress.
+	 *  Excluded from change notifications — the live clock paints them. */
+	startedAt?: number;
+	lastAdvanceAt?: number;
+}
+
+export type AgentTreeChange =
+	| { type: "added"; node: AgentNode }
+	| { type: "updated"; node: AgentNode }
+	| { type: "removed"; nodes: AgentNode[] }
+	| { type: "cleared"; nodes: AgentNode[] };
+
+export interface FlatRow {
+	node: AgentNode;
+	depth: number;
+}
+
+/** Flatten the tree into display order (root, then its children…) with depth. Pure. */
+export function flattenTree(nodes: AgentNode[]): FlatRow[] {
+	const rows: FlatRow[] = [];
+	const walk = (parentId: string | undefined, depth: number): void => {
+		for (const node of nodes.filter((n) => n.parentId === parentId)) {
+			rows.push({ node, depth });
+			walk(node.id, depth + 1);
+		}
+	};
+	walk(undefined, 0);
+	return rows;
+}
+
+/** Status → glyph, shared by every agent surface (tree, overlay). */
+export const GLYPH: Record<AgentNodeStatus, string> = { running: "⏳", done: "✓", failed: "✗", stopped: "■" };
+
+export interface RenderOptions {
+	/** Current time; omitted ⇒ no elapsed/stall annotation (pure renders stay byte-identical). */
+	now?: number;
+	/** Quiet time after which a running row shows the stall badge; 0/omitted ⇒ never. */
+	stallMs?: number;
+}
+
+/** Whether `detail` is the literal "queued" marker a seeded-but-not-yet-live leg carries — shared
+ *  by `runningAnnotation` (suppresses the clock) and `telemetryStatus` (`extension.ts`, reports the
+ *  `queued` state). One predicate so the two readings of the marker cannot drift apart. */
+export function isQueuedMarker(detail: string | undefined): boolean {
+	return detail?.trim().toLowerCase() === "queued";
+}
+
+/** "1m 15s" while a running node keeps advancing; "⚠ stalled 1m 30s" once it has been quiet
+ *  for `stallMs`. Undefined for settled nodes, nodes without clock data, or a node still carrying
+ *  the "queued" marker — it was seeded ahead of the concurrency gate and has not started running
+ *  yet, so its clock (stamped at seed time) has nothing true to report. Pure. */
+export function runningAnnotation(node: Pick<AgentNode, "status" | "startedAt" | "lastAdvanceAt" | "detail">, now: number, stallMs: number): string | undefined {
+	if (node.status !== "running" || node.startedAt === undefined) return undefined;
+	if (isQueuedMarker(node.detail)) return undefined;
+	const quietSince = node.lastAdvanceAt ?? node.startedAt;
+	if (stallMs > 0 && now - quietSince >= stallMs) return `⚠ stalled ${formatDuration(now - quietSince)}`;
+	return formatDuration(now - node.startedAt);
+}
+
+/** The tree patch for one progress snapshot: every snapshot is an advance; activity wins over
+ *  a bare token count as the visible detail. One helper for every progress site. */
+export function progressPatch(snap: { output?: string; activity?: string; tokens?: number }, now: number): AgentNodePatch {
+	const patch: AgentNodePatch = { lastAdvanceAt: now };
+	if (snap.output) patch.output = snap.output;
+	if (snap.activity) patch.detail = snap.activity;
+	else if (snap.tokens) patch.detail = `${compactTokens(snap.tokens)} tok`;
+	return patch;
+}
+
+function safeInline(value: string): string {
+	return compactInlineText(value, { maxChars: 96 });
+}
+
+/** Render the tree as plain lines with ├─/└─ branches and status glyphs. Pure. */
+export function renderAgentTree(nodes: AgentNode[], opts: RenderOptions = {}): string[] {
+	const lines: string[] = [];
+	// Build the hierarchy once. Filtering the complete node array at every recursive step made
+	// wide fan-outs quadratic, exactly where progress snapshots cause the most UI activity.
+	const childrenByParent = new Map<string | undefined, AgentNode[]>();
+	for (const node of nodes) {
+		const siblings = childrenByParent.get(node.parentId);
+		if (siblings) siblings.push(node);
+		else childrenByParent.set(node.parentId, [node]);
+	}
+
+	const walk = (parentId: string | undefined, prefix: string): void => {
+		const kids = childrenByParent.get(parentId);
+		if (!kids) return;
+		kids.forEach((node, i) => {
+			const isRoot = parentId === undefined;
+			const isLast = i === kids.length - 1;
+			const branch = isRoot ? "" : isLast ? "└─ " : "├─ ";
+			const label = safeInline(node.label) || safeInline(node.id) || "agent";
+			const detailText = node.detail ? safeInline(node.detail) : "";
+			const clock = opts.now !== undefined ? runningAnnotation(node, opts.now, opts.stallMs ?? 0) : undefined;
+			const tail = [detailText, clock].filter((s): s is string => Boolean(s)).join(" · ");
+			const detail = tail ? `  ${tail}` : "";
+			lines.push(`${prefix}${branch}${GLYPH[node.status]} ${label}${detail}`);
+			const childPrefix = isRoot ? "" : `${prefix}${isLast ? "   " : "│  "}`;
+			walk(node.id, childPrefix);
+		});
+	};
+
+	walk(undefined, "");
+	return lines;
+}
+
+/**
+ * Bounded above-editor digest. Large fan-outs belong in the scrollable F9
+ * overlay; they must not push the editor and conversation off the screen.
+ */
+export function renderAgentTreeSummary(nodes: AgentNode[], maxRows = 8, opts: RenderOptions = {}): string[] {
+	const rows = renderAgentTree(nodes, opts);
+	const limit = Math.max(1, Math.floor(maxRows));
+	if (rows.length <= limit) return rows;
+	const failed = nodes.filter((node) => node.status === "failed");
+	if (failed.length > 0) {
+		const names = failed.slice(0, 2).map((node) => {
+			const label = safeInline(node.label) || "agent";
+			const detail = node.detail ? safeInline(node.detail) : "";
+			return detail ? `${label} (${detail})` : label;
+		});
+		const extra = failed.length - names.length;
+		const failureLine = `✗ ${failed.length} failed: ${names.join(", ")}${extra > 0 ? `, +${extra} more` : ""}`;
+		if (limit === 1) return [failureLine];
+		const visibleCount = Math.max(0, limit - 2);
+		return [
+			...rows.slice(0, visibleCount),
+			failureLine,
+			`… +${rows.length - visibleCount} more · F9 or /agents for the full live tree`,
+		];
+	}
+	const visibleCount = Math.max(0, limit - 1);
+	return [
+		...rows.slice(0, visibleCount),
+		`… +${rows.length - visibleCount} more · F9 or /agents for the full live tree`,
+	];
+}
+
+export interface AddNodeInput {
+	id: string;
+	label: string;
+	parentId?: string;
+	status?: AgentNodeStatus;
+	kind?: AgentNodeKind;
+	agent?: string;
+	model?: string;
+	detail?: string;
+	output?: string;
+	startedAt?: number;
+	lastAdvanceAt?: number;
+}
+
+export interface AgentNodePatch {
+	status?: AgentNodeStatus;
+	kind?: AgentNodeKind;
+	agent?: string;
+	model?: string;
+	detail?: string;
+	output?: string;
+	startedAt?: number;
+	lastAdvanceAt?: number;
+}
+
+/** Apply the fields `add`'s upsert branch and `update` both accept, in place — the one place
+ *  that lists them, so the two callers can never let a field drift out of sync between them. */
+function applyPatch(node: AgentNode, patch: AgentNodePatch): void {
+	if (patch.status) node.status = patch.status;
+	if (patch.kind !== undefined) node.kind = patch.kind;
+	if (patch.agent !== undefined) node.agent = patch.agent;
+	if (patch.model !== undefined) node.model = patch.model;
+	if (patch.detail !== undefined) node.detail = patch.detail;
+	if (patch.output !== undefined) node.output = patch.output;
+	if (patch.startedAt !== undefined) node.startedAt = patch.startedAt;
+	if (patch.lastAdvanceAt !== undefined) node.lastAdvanceAt = patch.lastAdvanceAt;
+}
+
+/** A small mutable registry with change notification. The extension owns one. */
+export class AgentTree {
+	private nodes: AgentNode[] = [];
+	private listeners = new Set<(change: AgentTreeChange) => void>();
+	private readonly now: () => number;
+
+	constructor(now: () => number = Date.now) {
+		this.now = now;
+	}
+
+	/** Insert a node, or upsert (relabel / restatus / reparent) when the id already exists. */
+	add(input: AddNodeInput): void {
+		const existing = this.nodes.find((n) => n.id === input.id);
+		if (existing) {
+			const before = { ...existing };
+			existing.label = input.label;
+			if (input.parentId !== undefined) existing.parentId = input.parentId;
+			applyPatch(existing, input);
+			if (!sameNode(before, existing)) this.emit({ type: "updated", node: { ...existing } });
+			return;
+		}
+		const t = this.now();
+		const node: AgentNode = {
+			id: input.id,
+			label: input.label,
+			parentId: input.parentId,
+			status: input.status ?? "running",
+			detail: input.detail,
+			startedAt: input.startedAt ?? t,
+			lastAdvanceAt: input.lastAdvanceAt ?? input.startedAt ?? t,
+			...(input.kind !== undefined ? { kind: input.kind } : {}),
+			...(input.agent !== undefined ? { agent: input.agent } : {}),
+			...(input.model !== undefined ? { model: input.model } : {}),
+			...(input.output !== undefined ? { output: input.output } : {}),
+		};
+		this.nodes.push(node);
+		this.emit({ type: "added", node: { ...node } });
+	}
+
+	update(id: string, patch: AgentNodePatch): void {
+		const node = this.nodes.find((n) => n.id === id);
+		if (!node) return;
+		const before = { ...node };
+		applyPatch(node, patch);
+		if (!sameNode(before, node)) this.emit({ type: "updated", node: { ...node } });
+	}
+
+	/** Remove a node and all its descendants. */
+	remove(id: string): void {
+		const doomed = new Set<string>([id]);
+		for (let grew = true; grew; ) {
+			grew = false;
+			for (const n of this.nodes) {
+				if (n.parentId !== undefined && doomed.has(n.parentId) && !doomed.has(n.id)) {
+					doomed.add(n.id);
+					grew = true;
+				}
+			}
+		}
+		const removed = this.nodes.filter((n) => doomed.has(n.id)).map((n) => ({ ...n }));
+		if (removed.length === 0) return;
+		this.nodes = this.nodes.filter((n) => !doomed.has(n.id));
+		this.emit({ type: "removed", nodes: removed });
+	}
+
+	clear(): void {
+		if (this.nodes.length === 0) return;
+		const removed = this.snapshot();
+		this.nodes = [];
+		this.emit({ type: "cleared", nodes: removed });
+	}
+
+	snapshot(): AgentNode[] {
+		return this.nodes.map((n) => ({ ...n }));
+	}
+
+	isEmpty(): boolean {
+		return this.nodes.length === 0;
+	}
+
+	hasRunning(): boolean {
+		return this.nodes.some((n) => n.status === "running");
+	}
+
+	onChange(fn: (change: AgentTreeChange) => void): () => void {
+		this.listeners.add(fn);
+		return () => {
+			this.listeners.delete(fn);
+		};
+	}
+
+	private emit(change: AgentTreeChange): void {
+		for (const fn of this.listeners) fn(change);
+	}
+}
+
+const CLOCK_KEYS = new Set<keyof AgentNode>(["startedAt", "lastAdvanceAt"]);
+function sameNode(a: AgentNode, b: AgentNode): boolean {
+	const keys = new Set([...Object.keys(a), ...Object.keys(b)] as Array<keyof AgentNode>);
+	return [...keys].every((key) => CLOCK_KEYS.has(key) || a[key] === b[key]);
+}

package/src/ui/live-clock.ts

@@ -0,0 +1,42 @@
+/**
+ * A repeating tick that exists only while something is live. Surfaces that show a running clock
+ * (the agent widget, the F9 overlay) start it when work appears; it stops itself the first time
+ * `isLive()` is false, so an idle session owns no timer. `unref`'d — never keeps the process alive.
+ */
+export interface LiveClockOptions {
+	intervalMs: number;
+	isLive: () => boolean;
+	onTick: () => void;
+}
+
+export class LiveClock {
+	private readonly opts: LiveClockOptions;
+	private timer: ReturnType<typeof setInterval> | undefined;
+
+	constructor(opts: LiveClockOptions) {
+		this.opts = opts;
+	}
+
+	/** Idempotent; a no-op while nothing is live. */
+	start(): void {
+		if (this.timer || !this.opts.isLive()) return;
+		this.timer = setInterval(() => {
+			if (!this.opts.isLive()) {
+				this.stop();
+				return;
+			}
+			this.opts.onTick();
+		}, this.opts.intervalMs);
+		this.timer.unref?.();
+	}
+
+	stop(): void {
+		if (!this.timer) return;
+		clearInterval(this.timer);
+		this.timer = undefined;
+	}
+
+	get running(): boolean {
+		return this.timer !== undefined;
+	}
+}

package/src/ui/model-picker.ts

@@ -0,0 +1,160 @@
+/**
+ * A focusable, searchable model picker opened with ctx.ui.custom (overlay: true).
+ * Type to filter, ↑↓ to move, ⏎ to choose, esc to keep the default. Unlike the
+ * built-in `ui.select`, the list is filterable (essential when a provider exposes
+ * hundreds of models) and the viewport *follows the selection* — the highlighted
+ * row is always on screen, so picking never jumps off the top.
+ *
+ * The pure parts (filter / viewport window / ordering) are exported and unit-tested;
+ * this file's component is the thin pi-tui glue (focus + keyboard + framing).
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, getKeybindings, Spacer, Text, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+const VIEWPORT = 12; // rows shown at once (the rest scrolls)
+
+/** Case-insensitive substring filter over model refs; order preserved, empty query = all. */
+export function filterModels(options: string[], query: string): string[] {
+	const q = query.trim().toLowerCase();
+	if (!q) return options;
+	return options.filter((o) => o.toLowerCase().includes(q));
+}
+
+/** Scroll offset that keeps `selected` visible in a `size`-row window over `total`
+ *  rows, moving as little as possible from `prevScroll`. Clamped to [0, total-size]. */
+export function visibleWindow(selected: number, size: number, total: number, prevScroll: number): number {
+	if (total <= size) return 0;
+	let scroll = prevScroll;
+	if (selected < scroll) scroll = selected; // selection above the window → pull up
+	else if (selected >= scroll + size) scroll = selected - size + 1; // below → push down
+	const maxScroll = Math.max(0, total - size);
+	return Math.max(0, Math.min(scroll, maxScroll));
+}
+
+/** Order refs with the session provider's models first (then alphabetical). Pure. */
+export function orderModelRefs(refs: string[], sessionProvider?: string): string[] {
+	const isSession = (r: string): boolean => sessionProvider !== undefined && r.startsWith(`${sessionProvider}/`);
+	return [...refs].sort((a, b) => Number(!isSession(a)) - Number(!isSession(b)) || a.localeCompare(b));
+}
+
+/** Is this keystroke a single printable character (a filter keystroke)? */
+function isPrintable(key: string): boolean {
+	if (key.length !== 1) return false;
+	const c = key.charCodeAt(0);
+	return c >= 0x20 && c !== 0x7f;
+}
+
+export class ModelPicker extends Container {
+	private theme: Theme;
+	private title: string;
+	private options: string[];
+	private sessionProvider: string | undefined;
+	private done: (ref: string | undefined) => void;
+	private tui: TUI;
+	private query = "";
+	private selected = 0;
+	private scroll = 0;
+	private lastWidth = 100;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		title: string,
+		options: string[],
+		sessionProvider: string | undefined,
+		done: (ref: string | undefined) => void,
+	) {
+		super();
+		this.tui = tui;
+		this.theme = theme;
+		this.title = title;
+		this.options = options;
+		this.sessionProvider = sessionProvider;
+		this.done = done;
+		this.rebuild();
+	}
+
+	private refresh(): void {
+		this.rebuild();
+		this.tui.requestRender();
+	}
+
+	private filtered(): string[] {
+		return filterModels(this.options, this.query);
+	}
+
+	override render(width: number): string[] {
+		this.lastWidth = width;
+		const inner = this.inner();
+		const b = (s: string): string => this.theme.fg("accent", s);
+		const framed = super.render(inner).map((line) => {
+			const pad = " ".repeat(Math.max(0, inner - visibleWidth(line)));
+			return `${b("│")} ${line}${pad} ${b("│")}`;
+		});
+		return [b(`┌${"─".repeat(inner + 2)}┐`), ...framed, b(`└${"─".repeat(inner + 2)}┘`)];
+	}
+
+	private inner(): number {
+		return Math.max(24, Math.min(this.lastWidth - 4, 100));
+	}
+
+	private rebuild(): void {
+		this.clear();
+		const t = this.theme;
+		const list = this.filtered();
+		if (this.selected >= list.length) this.selected = Math.max(0, list.length - 1);
+		this.scroll = visibleWindow(this.selected, VIEWPORT, list.length, this.scroll);
+		const w = this.inner() - 1;
+
+		this.addChild(new Text(t.fg("accent", t.bold(this.title)), 1, 0));
+		const counter = t.fg("dim", `type to filter · ${list.length}/${this.options.length}`);
+		const q = this.query ? t.fg("accent", `  «${this.query}»`) : "";
+		this.addChild(new Text(`${counter}${q}`, 1, 0));
+		this.addChild(new Spacer(1));
+
+		if (list.length === 0) {
+			this.addChild(new Text(t.fg("dim", "(no model matches — backspace to widen)"), 1, 0));
+		} else {
+			const end = Math.min(list.length, this.scroll + VIEWPORT);
+			if (this.scroll > 0) this.addChild(new Text(t.fg("dim", `▲ ${this.scroll} above`), 1, 0));
+			for (let i = this.scroll; i < end; i++) {
+				const opt = list[i] as string;
+				const star = this.sessionProvider && opt.startsWith(`${this.sessionProvider}/`) ? "★ " : "  ";
+				const text = truncateToWidth(`${star}${opt}`, w);
+				const row = i === this.selected ? t.fg("accent", `▸ ${text}`) : `  ${text}`;
+				this.addChild(new Text(row, 1, 0));
+			}
+			if (end < list.length) this.addChild(new Text(t.fg("dim", `▼ ${list.length - end} below`), 1, 0));
+		}
+
+		this.addChild(new Spacer(1));
+		this.addChild(new Text(t.fg("dim", "↑↓ move   ·   ⏎ select   ·   esc keep default"), 1, 0));
+	}
+
+	handleInput(keyData: string): void {
+		const kb = getKeybindings();
+		const list = this.filtered();
+		if (kb.matches(keyData, "tui.select.up")) {
+			this.selected = Math.max(0, this.selected - 1);
+			this.refresh();
+		} else if (kb.matches(keyData, "tui.select.down")) {
+			this.selected = Math.min(Math.max(0, list.length - 1), this.selected + 1);
+			this.refresh();
+		} else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n" || keyData === "\r") {
+			this.done(list[this.selected]);
+		} else if (kb.matches(keyData, "tui.select.cancel")) {
+			this.done(undefined);
+		} else if (keyData === "\x7f" || keyData === "\b") {
+			if (this.query) {
+				this.query = this.query.slice(0, -1);
+				this.selected = 0;
+				this.refresh();
+			}
+		} else if (isPrintable(keyData)) {
+			this.query += keyData;
+			this.selected = 0;
+			this.refresh();
+		}
+	}
+}

package/src/ui/presentation.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared terminal-presentation helpers. These functions shape what a human sees;
+ * they never mutate the semantic payload delivered to the supervisor.
+ */
+
+import { sliceByColumn, visibleWidth } from "@earendil-works/pi-tui";
+
+// Every alternative is bounded, in two ways that matter.
+//
+// The OSC payload stops at the next ESC as well as at BEL: without that an `ESC ]` a child
+// never terminates makes the class run to end-of-string and backtrack from *every* such
+// position — quadratic, on the synchronous render path. The length cap below does not make
+// that exclusion redundant: it is also what keeps each introducer's erase region disjoint, so
+// a child cannot fold an arbitrary run of its report — sequences included — behind one
+// introducer by delaying the BEL.
+//
+// It also stops after OSC_MAX_PAYLOAD characters, and the CSI parameter run after its own
+// cap. Erasing an OSC payload is what makes `ESC ]0;` a way to *hide* text, so an unbounded
+// one lets a child fold its entire report behind one introducer. A bound also makes "might
+// this still be opening?" a question with a finite answer — the property AgentOverlay's row
+// cache needs to reuse wrapped rows across a chunk boundary. Past the cap the sequence is
+// not a sequence: the introducer is stripped as a C1 byte and the body stays visible text.
+const OSC_MAX_PAYLOAD = 4096;
+const CSI_MAX_PARAMS = 255;
+const CSI_MAX_INTERMEDIATES = 15;
+const ANSI_SEQUENCE = new RegExp(
+	`\\u001B(?:\\][^\\u0007\\u001B]{0,${OSC_MAX_PAYLOAD}}(?:\\u0007|\\u001B\\\\)` +
+		`|\\[[0-?]{0,${CSI_MAX_PARAMS}}[ -/]{0,${CSI_MAX_INTERMEDIATES}}[@-~]|[@-_])`,
+	"g",
+);
+
+/**
+ * The proper prefixes of ANSI_SEQUENCE: text that may still turn into a control sequence once
+ * more of the stream arrives. Exported for incremental consumers (AgentOverlay) that split a
+ * growing buffer and must not put the split inside a sequence. Because the bodies above are
+ * capped, this stops being true a bounded distance after the introducer.
+ */
+export const OPEN_SEQUENCE_TAIL = new RegExp(
+	`\\u001B(?:\\][^\\u0007\\u001B]{0,${OSC_MAX_PAYLOAD}}` +
+		`|\\[[0-?]{0,${CSI_MAX_PARAMS}}[ -/]{0,${CSI_MAX_INTERMEDIATES}})?$`,
+);
+const TERMINAL_CONTROLS = /[\u0000-\u0009\u000B-\u001F\u007F-\u009F]/g;
+
+const PRESENTATION_WRAPPERS = new Set([
+	"Sub-agent output (untrusted data):",
+	"Peer message (untrusted data; equal-status collaborator, not your supervisor):",
+	"Peer data · untrusted equal-status collaborator:",
+]);
+
+export interface CompactVisibleTextOptions {
+	maxLines?: number;
+	/** Historical option name; the bound is terminal display columns, not JS string length. */
+	maxLineChars?: number;
+}
+
+export interface CompactVisibleTextResult {
+	text: string;
+	truncated: boolean;
+	omittedLines: number;
+	originalChars: number;
+}
+
+export interface CompactInlineTextOptions {
+	maxChars?: number;
+}
+
+/** Hard ceiling for one-line collapsed card chrome and previews. */
+export const MAX_COLLAPSED_CARD_COLUMNS = 100;
+
+/**
+ * Clip to at most `units` code units without cutting an astral character in half. A lone
+ * surrogate draws as a replacement glyph, and every clip here puts it directly before the
+ * ellipsis — the most visible position in the line.
+ */
+function clipCodeUnits(text: string, units: number): string {
+	if (units >= text.length) return text;
+	const last = text.charCodeAt(units - 1);
+	return text.slice(0, last >= 0xd800 && last <= 0xdbff ? units - 1 : units);
+}
+
+/**
+ * Sanitize and bound trusted UI chrome such as labels, model names, and error causes.
+ * `maxChars` bounds both code units and *display columns*: a CJK label passes a character
+ * count at twice the width, and a widget row "bounded" by characters alone then wraps
+ * over several terminal rows and pushes the conversation off the screen.
+ */
+export function compactInlineText(input: string, opts: CompactInlineTextOptions = {}): string {
+	const maxChars = Math.max(16, Math.floor(opts.maxChars ?? 160));
+	const compact = sanitizeTerminalText(input).replace(/\s+/g, " ").trim();
+	// Clip by code units first, so the column measurement below never walks a whole report.
+	const clipped = compact.length > maxChars ? `${clipCodeUnits(compact, maxChars - 1)}…` : compact;
+	if (visibleWidth(clipped) <= maxChars) return clipped;
+	// pi-tui's truncateToWidth would splice in ANSI resets, and chrome must stay escape-free.
+	return `${sliceByColumn(clipped, 0, maxChars - 1, true)}…`;
+}
+
+/** Clip an already-composed terminal row without counting wide glyphs as one column. */
+export function compactVisibleLine(input: string, maxColumns = MAX_COLLAPSED_CARD_COLUMNS): string {
+	const limit = Math.max(16, Math.floor(maxColumns));
+	if (visibleWidth(input) <= limit) return input;
+	return `${sliceByColumn(input, 0, limit - visibleWidth("…"), true)}…`;
+}
+
+/** Bound a persistent widget: one stable header, a fair prefix of rows, then one drill-down row. */
+export function boundDisplayRows(
+	header: string,
+	rows: readonly string[],
+	maxRows: number,
+	detailHint: string,
+): string[] {
+	const limit = Math.max(2, Math.floor(maxRows));
+	if (rows.length + 1 <= limit) return [header, ...rows];
+	const visibleCount = limit - 2;
+	const omitted = rows.length - visibleCount;
+	return [
+		header,
+		...rows.slice(0, visibleCount),
+		`… +${omitted} more · ${detailHint}`,
+	];
+}
+
+/** Strip control sequences a child could otherwise use to repaint or spoof terminal chrome. */
+export function sanitizeTerminalText(text: string): string {
+	return text
+		.replace(/\r\n?/g, "\n")
+		.replace(ANSI_SEQUENCE, "")
+		.replace(TERMINAL_CONTROLS, "");
+}
+
+/**
+ * Produce a small, semantic preview for a collapsed Pi card. Boilerplate fence
+ * headings are omitted, while quoted payload lines remain visibly quoted.
+ */
+export function compactVisibleText(
+	input: string,
+	opts: CompactVisibleTextOptions = {},
+): CompactVisibleTextResult {
+	const maxLines = Math.max(1, Math.floor(opts.maxLines ?? 4));
+	const maxLineColumns = Math.max(16, Math.floor(opts.maxLineChars ?? 160));
+	const sanitized = sanitizeTerminalText(input);
+	const source = sanitized
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0 && !PRESENTATION_WRAPPERS.has(line));
+
+	let lineTruncated = false;
+	const clamp = (line: string): string => {
+		if (visibleWidth(line) <= maxLineColumns) return line;
+		lineTruncated = true;
+		return `${sliceByColumn(line, 0, maxLineColumns - visibleWidth("…"), true)}…`;
+	};
+
+	let omittedLines = 0;
+	let visible: string[];
+	if (source.length > maxLines) {
+		const contentLines = Math.max(0, maxLines - 1);
+		omittedLines = source.length - contentLines;
+		visible = source.slice(0, contentLines).map(clamp);
+		visible.push(clamp(`… +${omittedLines} more line${omittedLines === 1 ? "" : "s"}`));
+	} else {
+		visible = source.map(clamp);
+	}
+
+	return {
+		text: visible.join("\n") || "(no output)",
+		truncated: lineTruncated || omittedLines > 0,
+		omittedLines,
+		originalChars: input.length,
+	};
+}