pi-crew 0.9.53 → 0.9.55

package/src/ui/dashboard-panes/cancellation-pane.ts

@@ -0,0 +1,66 @@
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
+
+export interface CancellationPaneOptions {
+	maxReasons?: number;
+}
+
+export function renderCancellationPane(manifest: TeamRunManifest, tasks: TeamTaskState[], opts: CancellationPaneOptions = {}): string[] {
+	const maxReasons = opts.maxReasons ?? 5;
+	if (manifest.status !== "cancelled" && manifest.status !== "blocked") {
+		const cancellingTasks = tasks.filter((t) => t.status === "cancelled");
+		if (cancellingTasks.length === 0) return ["Cancellation pane: no active cancellations"];
+	}
+
+	const lines: string[] = ["Cancellation pane"];
+
+	if (manifest.status === "cancelled") {
+		lines.push(`  Run status: cancelled`);
+	} else if (manifest.status === "blocked") {
+		lines.push(`  Run status: blocked`);
+	}
+
+	const cancelledTasks = tasks.filter((t) => t.status === "cancelled");
+	if (cancelledTasks.length > 0) {
+		lines.push(`  Cancelled tasks (${cancelledTasks.length}):`);
+		for (const task of cancelledTasks.slice(0, maxReasons)) {
+			const reason = task.error ?? "unknown";
+			lines.push(`    ✗ ${task.id}: ${reason}`);
+		}
+		if (cancelledTasks.length > maxReasons) {
+			lines.push(`    ... and ${cancelledTasks.length - maxReasons} more`);
+		}
+	}
+
+	if (manifest.policyDecisions?.length) {
+		const decisions = manifest.policyDecisions.slice(0, maxReasons);
+		lines.push(`  Policy decisions (${manifest.policyDecisions.length}):`);
+		for (const d of decisions) {
+			lines.push(`    ${d.action}: ${d.message}`);
+		}
+	}
+
+	return lines;
+}
+
+/**
+ * D-1 / L-2 — a one-line terminal-run reason for the dashboard detail row.
+ *
+ * Surfaces *why* a failed/cancelled/stopped run ended without forcing the
+ * user to switch panes. This also gives this module a real consumer (it was
+ * previously zero-importer dead code per the UI/UX review), wiring it in as
+ * the natural home for cancellation/failure reason display.
+ *
+ * Resolution order: structured `run.cancelled` event reason → first failed
+ * task's error → first policy-decision message.
+ */
+export function summarizeTerminalReason(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+	cancellationReason?: string,
+): string | undefined {
+	if (cancellationReason) return cancellationReason;
+	const failed = tasks.find((task) => task.status === "failed" && task.error);
+	if (failed?.error) return failed.error;
+	if (manifest.policyDecisions?.length) return manifest.policyDecisions[0]?.message;
+	return undefined;
+}

package/src/ui/dashboard-panes/capability-pane.ts

@@ -0,0 +1,77 @@
+import type { PiTeamsConfig } from "../../config/config.ts";
+import type { CapabilityItem } from "../../runtime/capability-inventory.ts";
+import { buildCapabilityInventory } from "../../runtime/capability-inventory.ts";
+
+export interface CapabilityPaneOptions {
+	config?: PiTeamsConfig;
+	filter?: string;
+}
+
+function kindIcon(kind: string): string {
+	switch (kind) {
+		case "team":
+			return "👥";
+		case "workflow":
+			return "📋";
+		case "agent":
+			return "🤖";
+		case "skill":
+			return "🔧";
+		case "tool":
+			return "🛠";
+		case "runtime":
+			return "⚙";
+		default:
+			return "•";
+	}
+}
+
+function stateLabel(state: string): string {
+	switch (state) {
+		case "active":
+			return "";
+		case "disabled":
+			return " [DISABLED]";
+		case "shadowed":
+			return " [SHADOWED]";
+		case "missing":
+			return " [MISSING]";
+		default:
+			return "";
+	}
+}
+
+export function renderCapabilityPane(cwd: string, opts: CapabilityPaneOptions = {}): string[] {
+	const inventory = buildCapabilityInventory(cwd, opts.config);
+	const filtered = opts.filter
+		? inventory.filter(
+				(item) =>
+					item.kind.includes(opts.filter!.toLowerCase()) ||
+					item.name.toLowerCase().includes(opts.filter!.toLowerCase()) ||
+					item.id.toLowerCase().includes(opts.filter!.toLowerCase()),
+			)
+		: inventory;
+
+	if (filtered.length === 0) return ["Capability pane: no items found"];
+
+	const byKind = new Map<string, CapabilityItem[]>();
+	for (const item of filtered) {
+		const group = byKind.get(item.kind) ?? [];
+		group.push(item);
+		byKind.set(item.kind, group);
+	}
+
+	const lines = [`Capability pane: ${filtered.length} item(s) (filter: ${opts.filter ?? "none"})`];
+	for (const [kind, items] of byKind) {
+		lines.push(`  ${kindIcon(kind)} ${kind} (${items.length}):`);
+		for (const item of items.slice(0, 10)) {
+			const icon = item.state === "active" ? "✓" : "✗";
+			lines.push(`    ${icon} ${item.name}${stateLabel(item.state)} [${item.source}]`);
+		}
+		if (items.length > 10) lines.push(`    ... and ${items.length - 10} more`);
+	}
+
+	const disabled = filtered.filter((i) => i.state === "disabled").length;
+	if (disabled > 0) lines.push(`  Disabled: ${disabled}`);
+	return lines;
+}

package/src/ui/dashboard-panes/health-pane.ts

@@ -0,0 +1,31 @@
+import { summarizeHeartbeats } from "../heartbeat-aggregator.ts";
+import type { RunUiSnapshot } from "../snapshot-types.ts";
+
+export interface HealthPaneOptions {
+	staleMs?: number;
+	deadMs?: number;
+	isForeground?: boolean;
+	now?: number | Date;
+}
+
+function seconds(ms: number): string {
+	return `${Math.round(ms / 1000)}s`;
+}
+
+export function renderHealthPane(snapshot: RunUiSnapshot | undefined, opts: HealthPaneOptions = {}): string[] {
+	if (!snapshot) return ["Health pane: snapshot unavailable"];
+	const summary = summarizeHeartbeats(snapshot, opts);
+	const lines = [
+		`Health pane: ${summary.healthy}/${summary.totalTasks} healthy · stale=${summary.stale} · dead=${summary.dead} · missing=${summary.missing}`,
+	];
+	if (summary.worstStaleMs > 0) lines.push(`Worst stale: ${seconds(summary.worstStaleMs)} ago`);
+	const hints: string[] = [];
+	const foreground = opts.isForeground !== false;
+	if ((summary.dead > 0 || summary.missing > 0) && foreground) hints.push("R recovery");
+	if ((summary.dead > 0 || summary.stale > 0) && foreground) hints.push("K kill stale");
+	hints.push("D diagnostic export");
+	lines.push(`Actions: ${hints.join(" · ")}`);
+	if (!foreground && (summary.dead > 0 || summary.missing > 0 || summary.stale > 0))
+		lines.push("Async run: R/K disabled — inspect process manually or use /team-api.");
+	return lines;
+}

package/src/ui/dashboard-panes/mailbox-pane.ts

@@ -0,0 +1,35 @@
+import type { RunUiSnapshot } from "../snapshot-types.ts";
+
+export function renderMailboxPane(snapshot: RunUiSnapshot | undefined): string[] {
+	if (!snapshot) return ["Mailbox pane: snapshot unavailable"];
+	const mailbox = snapshot.mailbox;
+	const approx = mailbox.approximate ? " · approximate (tail)" : "";
+	const lines: string[] = [
+		`Mailbox pane: inbox unread=${mailbox.inboxUnread} · outbox pending=${mailbox.outboxPending} · attention=${mailbox.needsAttention}${approx}`,
+	];
+	// Kind-separated breakdown
+	const kindParts: string[] = [];
+	const steer = mailbox.steerUnread ?? 0;
+	const followUp = mailbox.followUpUnread ?? 0;
+	const response = mailbox.responseUnread ?? 0;
+	const message = mailbox.messageUnread ?? 0;
+	if (steer > 0) kindParts.push(`steer=${steer}`);
+	if (followUp > 0) kindParts.push(`follow-up=${followUp}`);
+	if (response > 0) kindParts.push(`response=${response}`);
+	if (message > 0) kindParts.push(`message=${message}`);
+	if (kindParts.length > 0) {
+		lines.push(`  Breakdown: ${kindParts.join(" · ")}`);
+		if (steer > 0) {
+			lines.push("  ⚠ Urgent: steering messages require immediate attention.");
+		}
+		if (followUp > 0) {
+			lines.push(`  📋 ${followUp} follow-up(s) pending review.`);
+		}
+	}
+	if (mailbox.needsAttention > 0) {
+		lines.push("Needs attention: press Enter for detail · A ack · N nudge · C compose · X ack all.");
+	} else {
+		lines.push("No mailbox items need attention. Press Enter for detail or C compose.");
+	}
+	return lines;
+}

package/src/ui/dashboard-panes/metrics-pane.ts

@@ -0,0 +1,37 @@
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import type { HistogramPoint, MetricLabels, MetricPoint } from "../../observability/metrics-primitives.ts";
+import type { RunUiSnapshot } from "../snapshot-types.ts";
+
+export interface MetricsPaneOptions {
+	registry?: MetricRegistry;
+	maxCounters?: number;
+}
+
+function labelsText(labels: MetricLabels): string {
+	const entries = Object.entries(labels);
+	return entries.length ? `{${entries.map(([key, value]) => `${key}=${value}`).join(",")}}` : "";
+}
+
+function isHistogramPoint(point: MetricPoint | HistogramPoint): point is HistogramPoint {
+	return "quantiles" in point;
+}
+
+export function renderMetricsPane(_snapshot: RunUiSnapshot | undefined, opts: MetricsPaneOptions = {}): string[] {
+	if (!opts.registry) return ["Metrics pane: registry unavailable"];
+	const snapshots = opts.registry.snapshot();
+	if (!snapshots.length) return ["Metrics pane: no metrics recorded"];
+	const lines = ["Metrics pane: top metrics"];
+	for (const snapshot of snapshots.slice(0, opts.maxCounters ?? 10)) {
+		const first = snapshot.values[0];
+		if (!first) {
+			lines.push(`${snapshot.name}: empty`);
+			continue;
+		}
+		if (isHistogramPoint(first))
+			lines.push(
+				`${snapshot.name}${labelsText(first.labels)} count=${first.count} p95=${Number.isFinite(first.quantiles.p95) ? Math.round(first.quantiles.p95) : "n/a"}`,
+			);
+		else lines.push(`${snapshot.name}${labelsText(first.labels)} ${first.value}`);
+	}
+	return lines;
+}

package/src/ui/dashboard-panes/progress-pane.ts

@@ -0,0 +1,38 @@
+import { computePhaseProgress, formatPhaseProgressLine } from "../../runtime/phase-progress.ts";
+import { renderDwfPhaseLines } from "../dwf-phase-display.ts";
+import type { RunUiSnapshot } from "../snapshot-types.ts";
+
+export function renderProgressPane(snapshot: RunUiSnapshot | undefined): string[] {
+	if (!snapshot) return ["Progress pane: snapshot unavailable"];
+	const progress = snapshot.progress;
+	const groupJoins = snapshot.groupJoins ?? [];
+	const groupJoinLines = groupJoins.length
+		? groupJoins.map((item) => `group join ${item.partial ? "partial" : "completed"}: ${item.requestId} ack=${item.ack}`)
+		: ["group joins: none"];
+	const cancellationLine = snapshot.cancellationReason ? [`cancelled: reason=${snapshot.cancellationReason}`] : [];
+	const runProgress = computePhaseProgress(snapshot.tasks);
+	const phaseLines =
+		runProgress.phases.length > 0
+			? runProgress.phases.map((p) => {
+					const done = p.completed + p.failed;
+					const status = p.running > 0 ? "running" : p.queued > 0 ? "queued" : done >= p.total ? "done" : "waiting";
+					return `  Phase ${p.index + 1} ${p.phase}: ${p.percentage}% (${done}/${p.total}) [${status}]`;
+				})
+			: [];
+	const phaseHeader = phaseLines.length > 0 ? [formatPhaseProgressLine(runProgress), ...phaseLines] : [];
+	// DWF logical phases (round-15 P1-4): derived from dwf.phase_* events.
+	// Null/absent for non-DWF runs → zero visible change.
+	const dwfPhaseLines = snapshot.dwfPhaseState ? renderDwfPhaseLines(snapshot.dwfPhaseState) : [];
+	return [
+		`Progress pane: ${progress.completed}/${progress.total} completed · running=${progress.running} queued=${progress.queued} failed=${progress.failed}`,
+		...dwfPhaseLines,
+		...phaseHeader,
+		...cancellationLine,
+		...groupJoinLines,
+		...snapshot.recentEvents.slice(-10).map((event) => {
+			const seq = event.metadata?.seq !== undefined ? `#${event.metadata.seq}` : "#?";
+			return `${seq} ${event.time} ${event.type}${event.taskId ? ` ${event.taskId}` : ""}${event.message ? ` · ${event.message}` : ""}`;
+		}),
+		...(snapshot.recentEvents.length ? [] : ["No recent events"]),
+	];
+}

package/src/ui/dashboard-panes/transcript-pane.ts

@@ -0,0 +1,10 @@
+import type { RunUiSnapshot } from "../snapshot-types.ts";
+
+export function renderTranscriptPane(snapshot: RunUiSnapshot | undefined): string[] {
+	if (!snapshot) return ["Output pane: snapshot unavailable"];
+	return [
+		`Output pane: ${snapshot.recentOutputLines.length} recent lines · press v for transcript viewer · o for raw output`,
+		...snapshot.recentOutputLines.slice(-12).map((line) => `⎿ ${line}`),
+		...(snapshot.recentOutputLines.length ? [] : ["No recent output"]),
+	];
+}

package/src/ui/deploy-bundled-themes.ts

@@ -0,0 +1,71 @@
+/**
+ * Deploy pi-crew's bundled themes to ~/.pi/agent/themes/ so Pi's theme
+ * loader discovers them (Pi scans that directory for custom themes).
+ *
+ * Best-effort and idempotent: compares content to avoid unnecessary writes,
+ * logs errors but never crashes registration.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { packageRoot, userPiRoot } from "../utils/paths.ts";
+
+/** Directory containing pi-crew's bundled theme JSON files. */
+function bundledThemesDir(): string {
+	return path.join(packageRoot(), "themes");
+}
+
+/** Target directory: ~/.pi/agent/themes/ (where Pi loads custom themes from). */
+function customThemesDir(): string {
+	return path.join(userPiRoot(), "themes");
+}
+
+function readIfExists(filePath: string): string | undefined {
+	try {
+		return fs.readFileSync(filePath, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Copy bundled themes to ~/.pi/agent/themes/, skipping files whose content
+ * already matches (idempotent). Returns the number of themes deployed/updated.
+ *
+ * Safe to call on every registration. Never throws.
+ */
+export function deployBundledThemes(): number {
+	try {
+		const srcDir = bundledThemesDir();
+		const dstDir = customThemesDir();
+
+		if (!fs.existsSync(srcDir)) return 0;
+
+		const files = (fs.readdirSync(srcDir) as string[]).filter((f) => f.endsWith(".json"));
+		if (files.length === 0) return 0;
+
+		// Ensure target directory exists
+		fs.mkdirSync(dstDir, { recursive: true });
+
+		let deployed = 0;
+		for (const file of files) {
+			const srcPath = path.join(srcDir, file);
+			const dstPath = path.join(dstDir, file);
+			const srcContent = fs.readFileSync(srcPath, "utf8");
+			const dstContent = readIfExists(dstPath);
+
+			// Skip if content matches exactly (idempotent — no churn)
+			if (dstContent !== undefined && dstContent === srcContent) continue;
+
+			try {
+				fs.writeFileSync(dstPath, srcContent, "utf8");
+				deployed++;
+			} catch {
+				// Individual file write failure — skip but continue
+			}
+		}
+
+		return deployed;
+	} catch {
+		return 0;
+	}
+}

package/src/ui/dwf-phase-display.ts

@@ -0,0 +1,151 @@
+/**
+ * DWF phase display — pure functions for extracting DWF phase state from the
+ * run's recent event window and rendering phase markers (▶/✓/⏸) in the
+ * progress pane.
+ *
+ * round-15 (P1-4). These functions are side-effect free and perform no I/O;
+ * they derive phase state entirely from the `recentEvents` slice already
+ * tailed by `run-snapshot-cache.ts`. Non-DWF runs (no `dwf.phase_*` events)
+ * yield `null`, so the progress pane stays unchanged for them.
+ */
+import type { TeamEvent } from "../state/event-log.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type DwfPhaseStatus = "running" | "completed" | "pending";
+
+export interface DwfPhaseEntry {
+	/** Phase title as passed to `ctx.phase(title)`. */
+	name: string;
+	/** Derived lifecycle status for display. */
+	status: DwfPhaseStatus;
+}
+
+export interface DwfPhaseState {
+	/** Ordered list of phases seen in the event window (first-seen order). */
+	phases: DwfPhaseEntry[];
+	/** Name of the currently running phase, or null if all are completed. */
+	currentPhase: string | null;
+}
+
+export interface RenderDwfPhaseOptions {
+	/** When true, render ASCII fallback markers instead of Unicode glyphs. */
+	ascii?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Markers
+// ---------------------------------------------------------------------------
+
+// Unicode markers — consistent with the ▸/● glyphs already used in the dashboard.
+const MARKER_RUNNING = "▶";
+const MARKER_COMPLETED = "✓";
+const MARKER_PENDING = "⏸";
+
+// ASCII fallbacks for terminals that mis-render the Unicode glyphs above.
+const MARKER_RUNNING_ASCII = "[>]";
+const MARKER_COMPLETED_ASCII = "[v]";
+const MARKER_PENDING_ASCII = "[ ]";
+
+const DWF_PHASE_HEADER = "  ── DWF Phases ──";
+
+function markerFor(status: DwfPhaseStatus, ascii: boolean): string {
+	if (ascii) {
+		if (status === "running") return MARKER_RUNNING_ASCII;
+		if (status === "completed") return MARKER_COMPLETED_ASCII;
+		return MARKER_PENDING_ASCII;
+	}
+	if (status === "running") return MARKER_RUNNING;
+	if (status === "completed") return MARKER_COMPLETED;
+	return MARKER_PENDING;
+}
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+function phaseNameFrom(event: TeamEvent): string | undefined {
+	const phase = event.data?.phase;
+	return typeof phase === "string" && phase.length > 0 ? phase : undefined;
+}
+
+/**
+ * Derive DWF phase state from a (chronological) event window.
+ *
+ * Returns `null` when the window contains no `dwf.phase_started` /
+ * `dwf.phase_completed` events — i.e. a non-DWF run — so callers can short
+ * circuit phase rendering entirely.
+ *
+ * Because the window is bounded, the oldest phase events may have scrolled
+ * off. A phase whose `dwf.phase_started` scrolled off but whose
+ * `dwf.phase_completed` is still visible is still tracked (as completed). A
+ * phase that started but whose completion scrolled off and which is not the
+ * current phase is shown as `pending` (indeterminate).
+ */
+export function extractDwfPhaseState(events: TeamEvent[]): DwfPhaseState | null {
+	const order: string[] = [];
+	const seen = new Set<string>();
+	const completed = new Set<string>();
+	let currentPhase: string | null = null;
+
+	const remember = (phase: string): void => {
+		if (!seen.has(phase)) {
+			seen.add(phase);
+			order.push(phase);
+		}
+	};
+
+	for (const event of events) {
+		if (event.type === "dwf.phase_started") {
+			const phase = phaseNameFrom(event);
+			if (phase === undefined) continue;
+			remember(phase);
+			// The most recent phase_started marks the running phase.
+			currentPhase = phase;
+		} else if (event.type === "dwf.phase_completed") {
+			const phase = phaseNameFrom(event);
+			if (phase === undefined) continue;
+			remember(phase);
+			completed.add(phase);
+			// If the phase just closed was the running one, it is no longer running.
+			if (phase === currentPhase) {
+				currentPhase = null;
+			}
+		}
+	}
+
+	if (order.length === 0) return null;
+
+	const phases: DwfPhaseEntry[] = order.map((name) => {
+		if (name === currentPhase) return { name, status: "running" as const };
+		if (completed.has(name)) return { name, status: "completed" as const };
+		return { name, status: "pending" as const };
+	});
+
+	return { phases, currentPhase };
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render phase marker lines for the progress pane.
+ *
+ * - One line per phase: `  ▶ Phase: Scan`, `  ✓ Phase: Scan`, `  ⏸ Phase: Review`.
+ * - A grouping header is emitted only when more than one phase is present.
+ * - When `options.ascii` is true, ASCII fallback markers are used.
+ *
+ * Always returns a non-empty array (the caller guarantees a non-null state).
+ */
+export function renderDwfPhaseLines(state: DwfPhaseState, options?: RenderDwfPhaseOptions): string[] {
+	const ascii = options?.ascii === true;
+	const lines: string[] = [];
+	if (state.phases.length > 1) lines.push(DWF_PHASE_HEADER);
+	for (const entry of state.phases) {
+		lines.push(`  ${markerFor(entry.status, ascii)} Phase: ${entry.name}`);
+	}
+	return lines;
+}

package/src/ui/dynamic-border.ts

@@ -0,0 +1,35 @@
+import type { CrewTheme } from "./theme-adapter.ts";
+
+export interface DynamicCrewBorderOptions {
+	color?: (value: string) => string;
+	char?: string;
+}
+
+export class DynamicCrewBorder {
+	private readonly theme: CrewTheme;
+	private readonly color?: (value: string) => string;
+	private readonly char: string;
+	private cachedWidth = -1;
+	private cachedLine = "";
+
+	constructor(theme: CrewTheme, options: DynamicCrewBorderOptions = {}) {
+		this.theme = theme;
+		this.color = options.color;
+		this.char = options.char && options.char.length > 0 ? options.char : "─";
+	}
+
+	render(width: number): string[] {
+		const w = Math.max(0, width);
+		if (w !== this.cachedWidth) {
+			const line = this.char.repeat(w);
+			this.cachedLine = this.color ? this.color(line) : this.theme.fg("border", line);
+			this.cachedWidth = w;
+		}
+		return [this.cachedLine];
+	}
+
+	invalidate(): void {
+		this.cachedWidth = -1;
+		this.cachedLine = "";
+	}
+}

package/src/ui/format-helpers.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared formatting helpers extracted from the deprecated tool-render.ts
+ * (F-21 Sprint 6 cleanup). Only the 3 utilities that are used by production
+ * code live here; the deprecated render functions were removed with tool-render.ts.
+ */
+import { truncateToWidth } from "../utils/visual.ts";
+
+export function formatTokens(n: number): string {
+	if (n < 1000) return String(n);
+	if (n < 10_000) return `${(n / 1000).toFixed(1)}k`;
+	if (n < 1_000_000) return `${Math.round(n / 1000)}k`;
+	return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+export function formatDuration(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+	const m = Math.floor(ms / 60_000),
+		s = Math.floor((ms % 60_000) / 1000);
+	return s > 0 ? `${m}m${s}s` : `${m}m`;
+}
+
+export function truncLine(text: string, maxWidth: number): string {
+	if (text.includes("\n") || text.includes("\r")) text = text.replace(/\r?\n/g, "↵ ");
+	// Round 23 (BUG 4): previously this loop counted 1 visual column per UTF-16
+	// code unit and indexed text[i], so for CJK it emitted up to 2x the visual
+	// width (frame overflow) and for emoji it split surrogate pairs (U+FFFD).
+	// Delegate to the grapheme/ANSI-aware truncateToWidth (keeps ANSI codes,
+	// respects double-wide CJK + surrogate pairs, adds the '…' ellipsis).
+	return truncateToWidth(text, maxWidth);
+}

package/src/ui/heartbeat-aggregator.ts

@@ -0,0 +1,74 @@
+import type { MetricRegistry } from "../observability/metric-registry.ts";
+import { classifyHeartbeat, heartbeatAgeMs } from "../runtime/heartbeat-gradient.ts";
+import type { TeamTaskState } from "../state/types.ts";
+import type { RunUiSnapshot } from "./snapshot-types.ts";
+
+export interface HeartbeatSummary {
+	runId: string;
+	totalTasks: number;
+	healthy: number;
+	stale: number;
+	dead: number;
+	missing: number;
+	worstStaleMs: number;
+	gradient: { healthy: number; warn: number; stale: number; dead: number };
+}
+
+export interface HeartbeatSummaryOptions {
+	staleMs?: number;
+	deadMs?: number;
+	now?: number | Date;
+	registry?: MetricRegistry;
+}
+
+function nowMs(now: number | Date | undefined): number {
+	if (typeof now === "number") return now;
+	if (now instanceof Date) return now.getTime();
+	return Date.now();
+}
+
+function isActiveTask(task: TeamTaskState): boolean {
+	return task.status === "running";
+}
+
+export function summarizeHeartbeats(snapshot: RunUiSnapshot, opts: HeartbeatSummaryOptions = {}): HeartbeatSummary {
+	const staleMs = opts.staleMs ?? 60_000;
+	const deadMs = opts.deadMs ?? 5 * 60_000;
+	const current = nowMs(opts.now);
+	const summary: HeartbeatSummary = {
+		runId: snapshot.runId,
+		totalTasks: snapshot.tasks.length,
+		healthy: 0,
+		stale: 0,
+		dead: 0,
+		missing: 0,
+		worstStaleMs: 0,
+		gradient: { healthy: 0, warn: 0, stale: 0, dead: 0 },
+	};
+	for (const task of snapshot.tasks) {
+		if (!isActiveTask(task)) continue;
+		const heartbeat = task.heartbeat;
+		if (!heartbeat) {
+			summary.missing += 1;
+			summary.gradient.dead += 1;
+			continue;
+		}
+		const age = heartbeatAgeMs(heartbeat, current);
+		if (!Number.isFinite(age)) {
+			summary.missing += 1;
+			summary.gradient.dead += 1;
+			continue;
+		}
+		summary.worstStaleMs = Math.max(summary.worstStaleMs, age);
+		const level = classifyHeartbeat(heartbeat, { warnMs: Math.max(1, Math.floor(staleMs / 2)), staleMs, deadMs }, current);
+		summary.gradient[level] += 1;
+		opts.registry
+			?.gauge("crew.heartbeat.staleness_ms", "Heartbeat elapsed since last seen, milliseconds")
+			.set({ runId: snapshot.runId, taskId: task.id }, age);
+		opts.registry?.counter("crew.heartbeat.level_total", "Heartbeat classifications by level").inc({ runId: snapshot.runId, level });
+		if (level === "dead") summary.dead += 1;
+		else if (level === "stale") summary.stale += 1;
+		else summary.healthy += 1;
+	}
+	return summary;
+}