@oh-my-pi/pi-tui 18.2.4 → 18.2.5

package/src/overlays/agent-activity.ts

@@ -0,0 +1,113 @@
+import type { AgentProgress } from "../tools/task";
+
+export type AgentActivityKind = "response" | "tool" | "irc" | "lifecycle";
+export type AgentActivityStatus = "pending" | "success" | "error" | "aborted";
+
+export interface AgentActivityRow {
+	id: string;
+	agentId: string;
+	timestamp: number;
+	kind: AgentActivityKind;
+	title: string;
+	summary: string;
+	status?: AgentActivityStatus;
+	entryId?: string;
+	toolCallId?: string;
+	toolName?: string;
+	from?: string;
+	to?: string;
+	replyTo?: string;
+	source: "live" | "transcript" | "irc";
+}
+
+export interface AgentActivityQuery {
+	agentIds?: ReadonlySet<string>;
+	kinds?: ReadonlySet<AgentActivityKind>;
+	search?: string;
+	before?: { timestamp: number; id: string };
+	limit?: number;
+}
+
+/** Activity index surface rendered by the agent hub. */
+export interface AgentActivitySource {
+	setLive(agentId: string, rows: AgentActivityRow[]): void;
+	sync(agentId: string, sessionFile: string | null): Promise<void>;
+	query(query: AgentActivityQuery): AgentActivityRow[];
+	recent(agentId: string, limit: number): AgentActivityRow[];
+}
+
+/** Collapse an activity label to one readable terminal line. */
+export function activityOneLine(value: string): string {
+	return value
+		.replace(/[\r\n\t]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/** Stable timestamp ordering for merged activity rows. */
+export function compareActivityRows(a: AgentActivityRow, b: AgentActivityRow): number {
+	return a.timestamp - b.timestamp || a.id.localeCompare(b.id);
+}
+
+export function activityRowsFromProgress(progress: AgentProgress, lastUpdate = Date.now()): AgentActivityRow[] {
+	const rows: AgentActivityRow[] = [];
+	const recentTools = progress.recentTools ?? [];
+	for (let index = recentTools.length - 1; index >= 0; index--) {
+		const tool = recentTools[index]!;
+		rows.push({
+			id: `live:${progress.id}:tool:${tool.endMs}:${index}`,
+			agentId: progress.id,
+			timestamp: tool.endMs,
+			kind: "tool",
+			title: tool.tool,
+			summary: tool.args || tool.tool,
+			status: "success",
+			toolName: tool.tool,
+			source: "live",
+		});
+	}
+	if (progress.currentTool) {
+		rows.push({
+			id: `live:${progress.id}:current-tool`,
+			agentId: progress.id,
+			timestamp: progress.currentToolStartMs ?? lastUpdate,
+			kind: "tool",
+			title: progress.currentTool,
+			summary: progress.lastIntent ?? progress.currentToolArgs ?? progress.currentTool,
+			status: "pending",
+			toolName: progress.currentTool,
+			source: "live",
+		});
+	}
+	rows.push({
+		id: `live:${progress.id}:lifecycle`,
+		agentId: progress.id,
+		timestamp: lastUpdate,
+		kind: "lifecycle",
+		title: progress.status ?? "running",
+		summary: progress.task ?? progress.description ?? "Agent activity",
+		status:
+			progress.status === "completed"
+				? "success"
+				: progress.status === "failed"
+					? "error"
+					: progress.status === "aborted"
+						? "aborted"
+						: "pending",
+		source: "live",
+	});
+	const response = activityOneLine((progress.recentOutput ?? []).join(" "));
+	if (response) {
+		rows.push({
+			id: `live:${progress.id}:response`,
+			agentId: progress.id,
+			timestamp: lastUpdate,
+			kind: "response",
+			title: "Response",
+			summary: response,
+			status: progress.status === "failed" ? "error" : progress.status === "aborted" ? "aborted" : "pending",
+			source: "live",
+		});
+	}
+	return rows.sort(compareActivityRows);
+}

package/src/overlays/agent-hub-projection.ts

@@ -0,0 +1,250 @@
+import type { AgentMetricsSummary, AgentRecordLike, AgentStatus } from "./agent-hub-types";
+import { MAIN_AGENT_ID } from "./agent-hub-types";
+import type { ObservableSession } from "./session-observer-registry";
+
+export type AgentMetrics = AgentMetricsSummary;
+
+export interface AggregateMetrics extends AgentMetrics {
+	reportedAgents: number;
+	/** Rows whose duration is an observer-measured active runtime. */
+	activeDurationAgents: number;
+}
+
+interface AgentTreeProjection<TRecord extends AgentRecordLike> {
+	rows: TRecord[];
+	depthById: Map<string, number>;
+	parentById: Map<string, string>;
+	lastSiblingById: Map<string, boolean>;
+}
+
+export const STATUS_ORDER: Record<AgentStatus, number> = { running: 0, idle: 1, parked: 2, aborted: 3 };
+
+function finiteMetric(value: number | undefined): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/** Exact observer usage for one roster entry. */
+export function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined {
+	const progress = observed?.progress;
+	if (!progress) return undefined;
+	const { tokens, requests, toolCount: tools, cost, durationMs } = progress;
+	if (
+		typeof tokens !== "number" ||
+		!Number.isFinite(tokens) ||
+		typeof requests !== "number" ||
+		!Number.isFinite(requests) ||
+		typeof tools !== "number" ||
+		!Number.isFinite(tools) ||
+		typeof cost !== "number" ||
+		!Number.isFinite(cost) ||
+		typeof durationMs !== "number" ||
+		!Number.isFinite(durationMs)
+	) {
+		return undefined;
+	}
+	return {
+		tokens,
+		requests,
+		tools,
+		cost,
+		durationMs,
+		durationKind: "active",
+		contextTokens:
+			typeof progress.contextTokens === "number" && Number.isFinite(progress.contextTokens)
+				? progress.contextTokens
+				: undefined,
+		contextWindow:
+			typeof progress.contextWindow === "number" && Number.isFinite(progress.contextWindow)
+				? progress.contextWindow
+				: undefined,
+	};
+}
+
+/**
+ * Read direct assistant usage from a live session. SessionStats also includes
+ * usage embedded in completed `task` tool results, so using it for a parent
+ * row would double-count child rows in the aggregate.
+ */
+function readSessionMetrics(session: NonNullable<AgentRecordLike["session"]>): AgentMetrics | undefined {
+	try {
+		const stats = session.getSessionStats();
+		const messages = session.agent?.state?.messages;
+		if (!Array.isArray(messages)) {
+			return {
+				tokens: stats.tokens.input + stats.tokens.output + stats.tokens.cacheWrite,
+				requests: stats.assistantMessages,
+				tools: stats.toolCalls,
+				cost: stats.cost,
+				durationMs: 0,
+				durationKind: "unknown",
+				contextTokens: stats.contextUsage?.tokens,
+				contextWindow: stats.contextUsage?.contextWindow,
+			};
+		}
+
+		let tokens = 0;
+		let requests = 0;
+		let tools = 0;
+		let cost = 0;
+		for (const message of messages) {
+			if (message.role !== "assistant") continue;
+			requests++;
+			tokens += message.usage.input + message.usage.output + message.usage.cacheWrite;
+			tools += message.content.filter(content => content.type === "toolCall").length;
+			cost += message.usage.cost.total;
+		}
+		return {
+			tokens,
+			requests,
+			tools,
+			cost,
+			durationMs: 0,
+			durationKind: "unknown",
+			contextTokens: stats.contextUsage?.tokens,
+			contextWindow: stats.contextUsage?.contextWindow,
+		};
+	} catch {
+		// Render-only doubles and sessions being torn down may not expose a
+		// complete statistics host. Missing metrics are preferable to a broken hub.
+		return undefined;
+	}
+}
+
+export function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
+	rows: readonly TRecord[];
+	observedById: ReadonlyMap<string, ObservableSession>;
+	metricsFor: (ref: TRecord, observed: ObservableSession | undefined) => AgentMetrics | undefined;
+	fallbackStatsSession: (
+		ref: TRecord,
+		observed: ObservableSession | undefined,
+	) => NonNullable<AgentRecordLike["session"]> | undefined;
+	sessionMetrics: WeakMap<object, { metrics: AgentMetrics | undefined }>;
+	refreshFallback: boolean;
+}): { metrics: AggregateMetrics; hasFallbackLiveSessions: boolean } {
+	const total: AggregateMetrics = {
+		tokens: 0,
+		requests: 0,
+		tools: 0,
+		cost: 0,
+		durationMs: 0,
+		durationKind: "active",
+		reportedAgents: 0,
+		activeDurationAgents: 0,
+	};
+	let hasFallbackLiveSessions = false;
+	const countedFallbackSessions = new Set<NonNullable<AgentRecordLike["session"]>>();
+	for (const ref of args.rows) {
+		const observed = args.observedById.get(ref.id);
+		const fallbackSession = args.fallbackStatsSession(ref, observed);
+		if (fallbackSession) {
+			hasFallbackLiveSessions = true;
+			if (args.refreshFallback || !args.sessionMetrics.has(fallbackSession)) {
+				args.sessionMetrics.set(fallbackSession, { metrics: readSessionMetrics(fallbackSession) });
+			}
+		}
+		const metrics = args.metricsFor(ref, observed);
+		if (!metrics || (fallbackSession && countedFallbackSessions.has(fallbackSession))) continue;
+		if (fallbackSession) countedFallbackSessions.add(fallbackSession);
+		total.reportedAgents++;
+		total.tokens += finiteMetric(metrics.tokens);
+		total.requests += finiteMetric(metrics.requests);
+		total.tools += finiteMetric(metrics.tools);
+		total.cost += finiteMetric(metrics.cost);
+		if (metrics.durationKind === "active") {
+			total.durationMs += finiteMetric(metrics.durationMs);
+			total.activeDurationAgents++;
+		}
+	}
+	return { metrics: total, hasFallbackLiveSessions };
+}
+
+/** Parent-before-child projection preserving the roster's stable sibling order. */
+export function projectAgentTree<TRecord extends AgentRecordLike>(
+	refs: readonly TRecord[],
+): AgentTreeProjection<TRecord> {
+	const ids = new Set<string>();
+	const operationalIndex = new Map<string, number>();
+	for (let i = 0; i < refs.length; i++) {
+		ids.add(refs[i].id);
+		operationalIndex.set(refs[i].id, i);
+	}
+
+	const parentById = new Map<string, string>();
+	const children = new Map<string, TRecord[]>();
+	for (const ref of refs) {
+		const parent =
+			ref.parentId && ref.parentId !== MAIN_AGENT_ID && ids.has(ref.parentId) ? ref.parentId : MAIN_AGENT_ID;
+		parentById.set(ref.id, parent);
+		const siblings = children.get(parent);
+		if (siblings) siblings.push(ref);
+		else children.set(parent, [ref]);
+	}
+
+	// A tree group occupies the position of its earliest operational row.
+	// Compute subtree minima iteratively so pathological lineage depth remains stack-safe.
+	const subtreeOrder = new Map<string, number>();
+	const visiting = new Set<string>();
+	const ranked = new Set<string>();
+	for (const start of refs) {
+		if (ranked.has(start.id)) continue;
+		const stack: Array<{ ref: TRecord; expanded: boolean }> = [{ ref: start, expanded: false }];
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (!current) continue;
+			if (current.expanded) {
+				let order = operationalIndex.get(current.ref.id) ?? Number.MAX_SAFE_INTEGER;
+				for (const child of children.get(current.ref.id) ?? []) {
+					order = Math.min(order, subtreeOrder.get(child.id) ?? Number.MAX_SAFE_INTEGER);
+				}
+				subtreeOrder.set(current.ref.id, order);
+				visiting.delete(current.ref.id);
+				ranked.add(current.ref.id);
+				continue;
+			}
+			if (ranked.has(current.ref.id) || visiting.has(current.ref.id)) continue;
+			visiting.add(current.ref.id);
+			stack.push({ ref: current.ref, expanded: true });
+			const descendants = children.get(current.ref.id);
+			if (!descendants) continue;
+			for (let i = descendants.length - 1; i >= 0; i--) {
+				const child = descendants[i];
+				if (!ranked.has(child.id) && !visiting.has(child.id)) stack.push({ ref: child, expanded: false });
+			}
+		}
+	}
+	for (const siblings of children.values()) {
+		siblings.sort(
+			(a, b) =>
+				(subtreeOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) - (subtreeOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER) ||
+				(operationalIndex.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
+					(operationalIndex.get(b.id) ?? Number.MAX_SAFE_INTEGER),
+		);
+	}
+
+	const lastSiblingById = new Map<string, boolean>();
+	for (const siblings of children.values()) {
+		for (let i = 0; i < siblings.length; i++) lastSiblingById.set(siblings[i].id, i === siblings.length - 1);
+	}
+
+	const rows: TRecord[] = [];
+	const visited = new Set<string>();
+	const depthById = new Map<string, number>();
+	const visit = (root: TRecord, rootDepth: number): void => {
+		const stack: Array<{ ref: TRecord; depth: number }> = [{ ref: root, depth: rootDepth }];
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (!current || visited.has(current.ref.id)) continue;
+			visited.add(current.ref.id);
+			depthById.set(current.ref.id, current.depth);
+			rows.push(current.ref);
+			const descendants = children.get(current.ref.id);
+			if (!descendants) continue;
+			for (let i = descendants.length - 1; i >= 0; i--)
+				stack.push({ ref: descendants[i], depth: current.depth + 1 });
+		}
+	};
+	for (const root of children.get(MAIN_AGENT_ID) ?? []) visit(root, 0);
+	// Corrupt persisted parent cycles remain visible as roots instead of disappearing.
+	for (const ref of refs) visit(ref, 0);
+	return { rows, depthById, parentById, lastSiblingById };
+}

package/src/overlays/agent-hub-renderer.ts

@@ -0,0 +1,281 @@
+import { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import { Ellipsis, visibleWidth } from "../utils";
+import { formatMetricRow } from "../components/metric";
+import { renderProgressBar } from "../components/progress-bar";
+import { renderTableRow } from "../components/table";
+import { formatDuration, formatNumber } from "@oh-my-pi/pi-utils";
+import type { ThemeColor } from "../theme/theme";
+import { type AgentRecordLike, MAIN_AGENT_ID } from "./agent-hub-types";
+import { parseThinkingLevel } from "../thinking";
+import { TRUNCATE_LENGTHS, truncateToWidth } from "../render/render-utils";
+import { sanitizeDisplaySingleLine } from "./extensions/display-text";
+import type { ObservableSession } from "./session-observer-registry";
+import { theme } from "../theme/theme";
+import type { AgentMetrics } from "./agent-hub-projection";
+
+export interface RosterRender {
+	lines: string[];
+	hitRows: Array<number | undefined>;
+}
+
+/** Legacy progress snapshots may omit counters; snapshot absence remains distinct. */
+function metricNumber(value: number | undefined): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+/** Compute the max content width for the current terminal, accounting for chrome. */
+export function contentWidth(): number {
+	return Math.max(TRUNCATE_LENGTHS.SHORT, (process.stdout.columns || 80) - 6);
+}
+
+/** Sanitize a line for TUI display and truncate it to the viewport width. */
+export function sanitizeLine(text: string, maxWidth?: number): string {
+	return truncateToWidth(sanitizeDisplaySingleLine(text), maxWidth ?? contentWidth());
+}
+
+export function clampHubLine(line: string, width: number): string {
+	return truncateToWidth(line.replace(/[\r\n]+/g, " "), Math.max(1, width), Ellipsis.Omit);
+}
+
+/** Status glyph, colored per theme status conventions. The title-line counts spell out the words. */
+export function statusGlyph(status: AgentRecordLike["status"]): string {
+	switch (status) {
+		case "running":
+			return theme.fg("accent", theme.status.running);
+		case "idle":
+			return theme.fg("success", theme.status.enabled);
+		case "parked":
+			return theme.fg("muted", theme.status.shadowed);
+		case "aborted":
+			return theme.fg("error", theme.status.aborted);
+	}
+}
+
+export function statusText(status: AgentRecordLike["status"], text: string): string {
+	switch (status) {
+		case "running":
+			return theme.fg("accent", text);
+		case "idle":
+			return theme.fg("success", text);
+		case "parked":
+			return theme.fg("muted", text);
+		case "aborted":
+			return theme.fg("error", text);
+	}
+}
+
+/** Model id + thinking level (`sonnet-4-6 ◒ high`), level colored per theme. */
+function formatModelBadge(modelId: string, level: ThinkingLevel | undefined): string {
+	const model = theme.fg("muted", sanitizeDisplaySingleLine(modelId));
+	if (!level || level === ThinkingLevel.Off || level === ThinkingLevel.Inherit) return model;
+	const display = theme.thinking[level] ?? level;
+	return `${model} ${theme.getThinkingBorderColor(level)(display)}`;
+}
+
+/** Host-resolved model-role label and color. */
+export interface AgentRoleDisplay {
+	color?: ThemeColor;
+	tag?: string;
+	name?: string;
+}
+
+/** Textual model-role tag; color reinforces (but never replaces) the label. */
+export function formatRoleBadge(role: string, info: AgentRoleDisplay): string {
+	return theme.fg(info.color ?? "muted", sanitizeDisplaySingleLine(info.tag ?? info.name ?? role));
+}
+
+/** Format a resolved selector, preserving provider identity when requested. */
+function formatResolvedModelBadge(resolved: string, preserveProvider = false, fallbackLevel?: ThinkingLevel): string {
+	const cleanResolved = sanitizeDisplaySingleLine(resolved);
+	// Model ids may themselves contain colons (`qwen3:14b`), so only treat the
+	// suffix as a thinking level when it parses as one.
+	const colon = cleanResolved.lastIndexOf(":");
+	const explicitLevel = colon >= 0 ? parseThinkingLevel(cleanResolved.slice(colon + 1)) : undefined;
+	const selector = explicitLevel !== undefined ? cleanResolved.slice(0, colon) : cleanResolved;
+	const label = preserveProvider ? selector : selector.slice(selector.indexOf("/") + 1);
+	return formatModelBadge(label, explicitLevel ?? fallbackLevel);
+}
+
+/**
+ * Resolved model + reasoning level for a hub row. Exact executor progress is
+ * authoritative (and survives completion); direct live sessions are the
+ * fallback for agents without an observer snapshot — the main session has no
+ * snapshot at all, so its row is read straight off the live session.
+ *
+ * Every source reports the model that produced the row's work, never the one
+ * the session merely points at: an armed fallback that has not served yet stays
+ * attributed to whichever model last actually spoke.
+ */
+export function modelBadge(ref: AgentRecordLike, observed: ObservableSession | undefined): string | undefined {
+	const progress = observed?.progress;
+	const liveThinkingLevel = ref.session?.thinkingLevel;
+	const serving = ref.session?.servingModel;
+	const fallbackSelector =
+		(serving?.isFallback ? serving.selector : undefined) ??
+		(progress?.resolvedModelIsFallback ? progress.resolvedModel : undefined) ??
+		(ref.history?.resolvedModelIsFallback ? ref.history.resolvedModel : undefined);
+	if (fallbackSelector) {
+		return `${theme.fg("warning", "fallback →")} ${formatResolvedModelBadge(fallbackSelector, true, liveThinkingLevel)}`;
+	}
+	const resolvedModel = progress?.resolvedModel ?? ref.history?.resolvedModel ?? serving?.selector;
+	if (resolvedModel) return formatResolvedModelBadge(resolvedModel, false, liveThinkingLevel);
+	const model = ref.session?.model;
+	if (!model) return undefined;
+	const level = model.thinking ? liveThinkingLevel : undefined;
+	return formatModelBadge(model.id, level);
+}
+
+export function formatMetricDuration(metrics: AgentMetrics): string | undefined {
+	const durationMs = metricNumber(metrics.durationMs);
+	if (durationMs <= 0) return undefined;
+	const label = metrics.durationKind === "active" ? "active" : metrics.durationKind === "span" ? "span" : "duration";
+	return `${formatDuration(durationMs)} ${label}`;
+}
+
+export function formatCost(cost: number): string {
+	const amount = metricNumber(cost);
+	if (amount < 0.01) return `$${amount.toFixed(4)}`;
+	if (amount < 1) return `$${amount.toFixed(3)}`;
+	return `$${amount.toFixed(2)}`;
+}
+
+export function formatMetrics(metrics: AgentMetrics): string {
+	return formatMetricRow(
+		[
+			{ value: formatCost(metrics.cost) },
+			{ value: formatMetricDuration(metrics) ?? "time —" },
+			{ value: `${formatNumber(metrics.requests)} req` },
+			{ value: `${formatNumber(metrics.tools)} tools` },
+			{ value: `${formatNumber(metrics.tokens)} tok` },
+		],
+		{ separator: theme.sep.dot },
+	);
+}
+
+/** Row-grid variant of {@link formatMetrics}: fixed-width cells so every agent's metadata
+ * line shares one column layout instead of flowing after wrapped text. Cost is left-aligned
+ * so the line starts flush; the numeric cells are right-aligned so units line up. */
+export function formatMetricColumns(metrics: AgentMetrics, age: string): string {
+	return renderTableRow(
+		[
+			{ text: formatCost(metrics.cost) },
+			{ text: formatMetricDuration(metrics) ?? "—" },
+			{ text: `${formatNumber(metrics.requests)} req` },
+			{ text: `${formatNumber(metrics.tools)} tools` },
+			{ text: `${formatNumber(metrics.tokens)} tok` },
+			{ text: age },
+		],
+		[
+			{ width: 8, align: "left", overflow: "allow" },
+			{ width: 13, align: "right", overflow: "truncate" },
+			{ width: 8, align: "right", overflow: "truncate" },
+			{ width: 9, align: "right", overflow: "truncate" },
+			{ width: 8, align: "right", overflow: "truncate" },
+			{ width: 8, align: "right", overflow: "truncate" },
+		],
+		undefined,
+		{ gap: " ", fit: false },
+	);
+}
+
+export function contextGauge(tokens: number, window: number): string {
+	const ratio = Math.max(0, Math.min(1, tokens / window));
+	const bar = renderProgressBar(ratio, 10, {
+		min: 0,
+		max: 1,
+		style: {
+			filled: "━",
+			empty: "─",
+			styleFilled: text => theme.fg("accent", text),
+			styleEmpty: text => theme.fg("dim", text),
+		},
+	});
+	return `${bar} ${formatNumber(tokens)}/${formatNumber(window)} ${Math.round(ratio * 100)}%`;
+}
+
+/** Fit a child-id preview without joining an arbitrarily large child set. */
+export function formatChildIds(children: readonly AgentRecordLike[], width: number): string {
+	const max = Math.max(1, width);
+	let shown = 0;
+	let text = "";
+	while (shown < children.length) {
+		const id = sanitizeLine(children[shown].id, max);
+		const candidate = text ? `${text}, ${id}` : id;
+		const remaining = children.length - shown - 1;
+		const suffix = remaining > 0 ? `, … +${remaining}` : "";
+		if (visibleWidth(candidate + suffix) > max) {
+			const includesCurrent = text.length === 0;
+			const omitted = children.length - shown - Number(includesCurrent);
+			return truncateToWidth(`${includesCurrent ? id : text}${omitted > 0 ? `, … +${omitted}` : ""}`, max);
+		}
+		text = candidate;
+		shown++;
+	}
+	return text;
+}
+const TREE_SEGMENT_WIDTH = 4;
+const TREE_DETAIL_BASE_INDENT = 4;
+
+/** Build one bash `tree`-style ancestry prefix. Continuation rows replace the
+ * node's own branch with a rail only when a later sibling still needs it. */
+function treePrefix(
+	ref: AgentRecordLike,
+	maxWidth: number,
+	depthById: ReadonlyMap<string, number>,
+	parentById: ReadonlyMap<string, string>,
+	lastSiblingById: ReadonlyMap<string, boolean>,
+	continuation: boolean,
+): string {
+	if ((depthById.get(ref.id) ?? 0) === 0) return "";
+	const lastSibling = lastSiblingById.get(ref.id);
+	const segments: string[] = [continuation ? (lastSibling ? "    " : "│   ") : lastSibling ? "└── " : "├── "];
+	const ancestry = new Set<string>();
+	let parent = parentById.get(ref.id);
+	while (parent && parent !== MAIN_AGENT_ID && !ancestry.has(parent)) {
+		const grandparent = parentById.get(parent);
+		// A bare top-level parent (drawn without a connector, just its dot) has no
+		// rail column — its children's connectors sit directly under that dot.
+		if (!grandparent || grandparent === MAIN_AGENT_ID) break;
+		ancestry.add(parent);
+		segments.push(lastSiblingById.get(parent) ? "    " : "│   ");
+		parent = grandparent;
+	}
+	const maxSegments = Math.max(1, Math.floor(Math.max(TREE_SEGMENT_WIDTH, maxWidth - 2) / TREE_SEGMENT_WIDTH));
+	const omitted = Math.max(0, segments.length - maxSegments);
+	const prefix = segments.slice(0, maxSegments).reverse().join("");
+	const omittedPrefix = omitted > 0 ? (continuation ? "  " : "… ") : "";
+	return theme.fg("dim", `${omittedPrefix}${prefix}`);
+}
+
+/** Bash `tree`-style branch for an agent's identity row. */
+export function treeBranch(
+	ref: AgentRecordLike,
+	maxWidth: number,
+	depthById: ReadonlyMap<string, number>,
+	parentById: ReadonlyMap<string, string>,
+	lastSiblingById: ReadonlyMap<string, boolean>,
+): string {
+	return treePrefix(ref, maxWidth, depthById, parentById, lastSiblingById, false);
+}
+
+/** Ancestry rails for the task and metrics rows beneath an agent identity. */
+export function treeContinuation(
+	ref: AgentRecordLike,
+	maxWidth: number,
+	depthById: ReadonlyMap<string, number>,
+	parentById: ReadonlyMap<string, string>,
+	lastSiblingById: ReadonlyMap<string, boolean>,
+): string {
+	return treePrefix(ref, maxWidth, depthById, parentById, lastSiblingById, true);
+}
+/** One roster-wide origin for metric columns, independent of tree depth. */
+export function treeMetadataIndent(maxWidth: number, maxDepth: number): number {
+	return Math.min(Math.max(0, maxWidth - 1), TREE_DETAIL_BASE_INDENT + Math.max(0, maxDepth) * TREE_SEGMENT_WIDTH);
+}
+
+/** Right-align `text` inside a fixed-width cell, truncating overflow. */
+export function alignRightCell(text: string, width: number): string {
+	return renderTableRow([{ text }], [{ width, align: "right", overflow: "truncate" }], undefined, {
+		fit: false,
+	});
+}