pi-crew 0.11.0 → 0.11.2

package/src/extension/registration/runtime-cleanup.ts

@@ -93,7 +93,14 @@ function buildCleanupSessionResourcesOnly(ctx: RegistrationContext): () => void
 		void disposeObservability(ctx.observabilityState, ctx.cleanedUp);
 		ctx.lifecycleState.deliveryCoordinator?.dispose();
 		clearHooksScoped();
-		uninstallCrewGlobalRegistry();
+		// F13 (RR-018): RPC + the crew global registry are EXTENSION-lifetime
+		// resources — they are NOT torn down on a session switch. The RPC
+		// handle resolves the current session context at request time
+		// (wire-cross-extension.ts), and session_start rebinds the registry to
+		// the current session's manifest cache (refreshCrossExtensionWiringForSession).
+		// Removing them here used to kill RPC permanently for the process
+		// lifetime (4 pi-crew:rpc:* subscriptions → 0 after the first switch,
+		// never reinstalled). Full teardown still happens in cleanupRuntime.
 		ctx.lifecycleState.overflowTracker?.dispose();
 		ctx.lifecycleState.deliveryCoordinator = undefined;
 		ctx.lifecycleState.overflowTracker = undefined;
@@ -104,8 +111,7 @@ function buildCleanupSessionResourcesOnly(ctx: RegistrationContext): () => void
 		ctx.renderScheduler = undefined;
 		ctx.autoRecoveryLast.clear();
 		disposeNotifications(ctx.lifecycleState);
-		ctx.rpcHandle?.unsubscribe();
-		ctx.rpcHandle = undefined;
+		// F13: ctx.rpcHandle stays installed here (extension lifetime).
 		ctx.disposeI18n();
 		ctx.sessionGeneration += 1;
 		ctx.currentCtx = undefined;

package/src/extension/registration/subagent-helpers.ts

@@ -123,3 +123,41 @@ export function __test__subagentSpawnParams(params: Record<string, unknown>, ctx
 		batchId: typeof params.batch_id === "string" && params.batch_id.trim() ? params.batch_id.trim() : undefined,
 	};
 }
+
+/**
+ * FINDING 6 (2026-09-23 battery): when a notification is cleared (e.g. the
+ * health monitor resolved a false/stale alert), copies of the ORIGINAL
+ * warning may still sit in the host session's follow-up queue — the host
+ * drains queued follow-ups one per turn boundary, so stale copies kept
+ * dripping into the parent conversation for hours after the clear.
+ *
+ * Feature-detected purge: newer pi runtimes expose
+ * `clearQueuedUserMessagesMatching(predicate)` (agent-session), which removes
+ * still-QUEUED messages whose text matches. Duck-typed here because the
+ * installed runtime surface (0.87.0) does not export it yet — on such hosts
+ * this is a documented no-op (returns false); the fire-cap policy in
+ * health-notify-policy.ts is the defense that works on all hosts.
+ */
+interface QueuePurgeCapablePi {
+	clearQueuedUserMessagesMatching?: (predicate: (text: string) => boolean) => { steering: string[]; followUp: string[] };
+	session?: {
+		clearQueuedUserMessagesMatching?: (predicate: (text: string) => boolean) => { steering: string[]; followUp: string[] };
+	};
+}
+
+export function purgeQueuedAmbientNotifications(pi: ExtensionAPI, match: (text: string) => boolean): boolean {
+	const api = pi as unknown as QueuePurgeCapablePi;
+	const surface =
+		typeof api.clearQueuedUserMessagesMatching === "function"
+			? api.clearQueuedUserMessagesMatching
+			: typeof api.session?.clearQueuedUserMessagesMatching === "function"
+				? api.session.clearQueuedUserMessagesMatching
+				: undefined;
+	if (!surface) return false;
+	try {
+		const removed = surface.call(api.session ?? api, match);
+		return (removed?.followUp?.length ?? 0) + (removed?.steering?.length ?? 0) > 0;
+	} catch {
+		return false;
+	}
+}

package/src/extension/registration/subagent-tools.ts

@@ -291,7 +291,7 @@ export function registerSubagentTools(
 							}),
 							t("agent.retrieveHint"),
 						].join("\n"),
-						{ agentId: record.id, status: record.status },
+						{ agentId: record.id, agentName: record.type, status: record.status },
 					),
 					terminate: true,
 				};
@@ -322,6 +322,7 @@ export function registerSubagentTools(
 				].join("\n"),
 				{
 					agentId: record.id,
+					agentName: record.type,
 					runId: record.runId,
 					status: record.status,
 				},
@@ -459,6 +460,7 @@ export function registerSubagentTools(
 				text,
 				{
 					agentId: current.id,
+					agentName: current.type,
 					runId: current.runId,
 					status: current.status,
 				},
@@ -531,14 +533,14 @@ export function registerSubagentTools(
 			if (!manifestTask) {
 				return subagentToolResult(
 					`Task '${taskId}' not found in the owning run; cannot steer.`,
-					{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+					{ agentId: record.id, agentName: record.type, runId: record.runId, taskId, status: record.status },
 					true,
 				);
 			}
 			if (TEAM_TERMINAL_TASK_STATUSES.has(manifestTask.status)) {
 				return subagentToolResult(
 					`Task '${taskId}' is ${manifestTask.status}; cannot steer.`,
-					{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+					{ agentId: record.id, agentName: record.type, runId: record.runId, taskId, status: record.status },
 					true,
 				);
 			}
@@ -560,7 +562,7 @@ export function registerSubagentTools(
 				if (existingBytes + Buffer.byteLength(line) > MAX_STEERING_BYTES) {
 					return subagentToolResult(
 						`Steering file for task '${taskId}' has reached its size cap (${(MAX_STEERING_BYTES / 1024).toFixed(0)}KiB); steer refused.`,
-						{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+						{ agentId: record.id, agentName: record.type, runId: record.runId, taskId, status: record.status },
 						true,
 					);
 				}
@@ -579,7 +581,7 @@ export function registerSubagentTools(
 				);
 				return subagentToolResult(
 					`Steer write failed for task '${taskId}': ${err instanceof Error ? err.message : String(err)} (see pi-crew error log)`,
-					{ agentId: record.id, runId: record.runId, taskId, status: record.status },
+					{ agentId: record.id, agentName: record.type, runId: record.runId, taskId, status: record.status },
 					true,
 				);
 			}
@@ -590,6 +592,7 @@ export function registerSubagentTools(
 				].join("\n"),
 				{
 					agentId: record.id,
+					agentName: record.type,
 					runId: record.runId,
 					taskId,
 					status: record.status,
@@ -666,7 +669,14 @@ function startAgentToolProgress(cwd: string, agentRecordId: string, onUpdate: On
 				agents,
 				error: record.error,
 			});
-			onUpdate({ content: [{ type: "text", text }] });
+			// W2: carry identity in the partial payload too — the renderer's
+			// streaming branch reads `result.details.agentName` to label the
+			// card. Pi's onUpdate TYPE is content-only; extra keys pass through
+			// to renderResult at runtime, hence the deliberate cast.
+			onUpdate({
+				content: [{ type: "text", text }],
+				details: { agentId: record.id, agentName: record.type, runId: record.runId, status: record.status },
+			} as never);
 		} catch (error) {
 			logInternalError("subagent-tools.progress", error, `agentId=${agentRecordId}`);
 		}

package/src/extension/registration/team-tool.ts

@@ -10,7 +10,7 @@ import type { createManifestCache } from "../../runtime/manifest-cache.ts";
 import { TeamToolParams, type TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
 import { updatePiCrewPowerbar } from "../../ui/powerbar-publisher.ts";
 import type { createRunSnapshotCache } from "../../ui/run-snapshot-cache.ts";
-import { statusIcon, type ToolRenderContext, teamToolRenderer } from "../../ui/tool-renderers/index.ts";
+import { type ToolRenderContext, teamToolRenderer } from "../../ui/tool-renderers/index.ts";
 import type { CrewWidgetState } from "../../ui/widget/index.ts";
 import { updateCrewWidget } from "../../ui/widget/index.ts";
 import { safeAbort } from "../../utils/safe-abort.ts";
@@ -260,6 +260,11 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 					onJsonEvent: deps.onJsonEvent,
 					getRunSnapshotCache: deps.getRunSnapshotCache,
 				});
+				// W5: surface the team name on the collapsed run card — the renderer
+				// reads `details.team`; enrich (non-destructively) for run results.
+				if (resolved.action === "run" && !output.isError && output.details && typeof output.details === "object") {
+					(output.details as unknown as Record<string, unknown>).team ??= resolved.team ?? resolved.agent ?? "";
+				}
 				if (resolved.action === "run" && !output.isError && typeof output.details?.runId === "string") {
 					pi.appendEntry("crew:run-started", {
 						runId: output.details.runId,
@@ -296,8 +301,10 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 					theme,
 					context as ToolRenderContext,
 				);
-			} catch {
-				return new Text(statusIcon("completed", theme) + " done", 0, 0);
+			} catch (e) {
+				// W1: fail-visible at the adapter layer too — never fake a "done".
+				const msg = e instanceof Error ? e.message : String(e);
+				return new Text(theme.fg("error", `✖ team render error: ${msg.slice(0, 60)}`), 0, 0);
 			}
 		},
 	};

package/src/extension/registration/terminal-status-wiring.ts

@@ -0,0 +1,172 @@
+/**
+ * M3-1 (UI-AUDIT P0-2/P1-1): wire the terminal-status controller (tab title +
+ * Ghostty OSC 9;4 progress) to the runEventBus.
+ *
+ * History: `src/ui/terminal-status.ts` shipped in v0.8.3 (819d71ad) with unit
+ * tests but NO construction site — `ctx.terminalStatus` was never assigned, so
+ * the feature never ran. This module is the missing wire, installed once from
+ * `register.ts` in place of the old no-op cleanup handler.
+ *
+ * Design:
+ *   - Subscribe to `runEventBus.onAny` and debounce evaluation (250ms) so a
+ *     burst of task events collapses into one state transition.
+ *   - State is derived from `listLiveAgents()`: >0 live → active; 0 → idle.
+ *     `ctx.terminalStatusActive` (already in RegistrationContext) is the single
+ *     source of truth for the current phase, so `runtime-cleanup.ts` resetting
+ *     it also resets this state machine on the next event.
+ *   - On the idle transition, `onRunCompleted()` fires the green Ghostty flash
+ *     and `onIdle()` runs COMPLETE_FLASH_MS later (title restore + re-assert
+ *     loop), so the flash is visible before the bar clears.
+ *   - The `TerminalStatusUi` adapter reads `ctx.currentCtx` dynamically (getter
+ *     + call-time lookup), so a session swap never leaves the controller
+ *     holding a stale session's `ui.setTitle` (the P1-10 class of bug).
+ *   - Everything is best-effort and guarded by `hasUI`: headless / subagent
+ *     contexts evaluate to a no-op and write nothing.
+ *   - All timers are `unref()`-ed; dispose unsubscribes, clears timers and
+ *     disposes the controller (registered via `registerCleanupHandler`, which
+ *     replaces the old no-op `disposeTerminalStatus` handler in register.ts).
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
+import { runEventBus } from "../../ui/run-event-bus.ts";
+import {
+	buildCrewTitleSegment,
+	COMPLETE_FLASH_MS,
+	createTerminalStatusController,
+	setTerminalTitle,
+	type TerminalStatusController,
+	type TerminalStatusUi,
+} from "../../ui/terminal-status.ts";
+import { registerCleanupHandler } from "../crew-cleanup.ts";
+
+/**
+ * Structural subset of RegistrationContext this module needs. Declared
+ * locally (not imported) so tests can pass a 3-field fake without building
+ * the full context, while `register.ts` passes the real context unchanged.
+ */
+export interface TerminalStatusWiringDeps {
+	currentCtx: { hasUI: boolean; ui: { setTitle(title: string): void } } | undefined;
+	terminalStatus: TerminalStatusController | undefined;
+	terminalStatusActive: boolean;
+}
+
+/** Debounce window that collapses an event burst into one evaluation. */
+const EVAL_DEBOUNCE_MS = 250;
+
+/**
+ * Live-agent probe (dependency inversion for tests). Production reads the real
+ * registry; tests inject a deterministic count source.
+ */
+let liveAgentProbe: () => number = () => listLiveAgents().length;
+
+/** @internal Re-subscribe guard: unsubscribe fn from a previous registration. */
+let currentUnsubscribe: (() => void) | undefined;
+/** @internal Latest install's full dispose (unsubscribe + timers + controller). */
+let currentDispose: (() => void) | undefined;
+
+/** Test seam: override the live-agent source (restore with `() => default`). */
+export function __test__setLiveAgentProbe(probe: () => number): void {
+	liveAgentProbe = probe;
+}
+
+/** Test seam: fully dispose any wiring left by a previous install in this process. */
+export function __test__resetTerminalStatusWiring(): void {
+	currentDispose?.();
+	currentDispose = undefined;
+	currentUnsubscribe = undefined;
+}
+
+export function installTerminalStatus(pi: ExtensionAPI, deps: TerminalStatusWiringDeps): void {
+	// A previous registration in this process must not leave a second
+	// subscription behind (registerCleanupHandler only keeps the latest
+	// dispose fn, so an older subscription would leak otherwise).
+	currentUnsubscribe?.();
+
+	// Dynamic adapter: resolves the CURRENT session's UI at call time, so the
+	// controller never captures a session-scoped reference.
+	const adapter: TerminalStatusUi = {
+		get hasUI(): boolean {
+			return deps.currentCtx?.hasUI ?? false;
+		},
+		ui: {
+			setTitle(title: string): void {
+				deps.currentCtx?.ui.setTitle(title);
+			},
+		},
+	};
+
+	let evalTimer: ReturnType<typeof setTimeout> | undefined;
+	let idleTimer: ReturnType<typeof setTimeout> | undefined;
+	let lastSegment = "";
+
+	const clearTimers = (): void => {
+		if (evalTimer) {
+			clearTimeout(evalTimer);
+			evalTimer = undefined;
+		}
+		if (idleTimer) {
+			clearTimeout(idleTimer);
+			idleTimer = undefined;
+		}
+	};
+
+	const evaluate = (): void => {
+		evalTimer = undefined;
+		if (!adapter.hasUI) return;
+		if (!deps.terminalStatus) deps.terminalStatus = createTerminalStatusController(adapter);
+		const controller = deps.terminalStatus;
+
+		if (liveAgentProbe() > 0) {
+			// Active: cancel any pending idle transition, then (re)assert.
+			if (idleTimer) {
+				clearTimeout(idleTimer);
+				idleTimer = undefined;
+			}
+			if (!deps.terminalStatusActive) {
+				deps.terminalStatusActive = true;
+				controller.onRunsActive(); // title (best-effort) + Ghostty INDETERMINATE
+				lastSegment = buildCrewTitleSegment();
+				return;
+			}
+			// Still active: refresh the title only when the role summary changed
+			// (never re-emit the OSC sequence — state 3 persists on its own).
+			const segment = buildCrewTitleSegment();
+			if (segment && segment !== lastSegment) {
+				lastSegment = segment;
+				setTerminalTitle(adapter, segment);
+			}
+			return;
+		}
+
+		if (deps.terminalStatusActive) {
+			deps.terminalStatusActive = false;
+			lastSegment = "";
+			controller.onRunCompleted(); // green flash, self-re-evaluates after COMPLETE_FLASH_MS
+			idleTimer = setTimeout(() => {
+				idleTimer = undefined;
+				controller.onIdle(); // title restore + idle re-assert loop + Ghostty CLEAR
+			}, COMPLETE_FLASH_MS);
+			idleTimer.unref?.();
+		}
+	};
+
+	const unsubscribe = runEventBus.onAny(() => {
+		if (evalTimer) return;
+		evalTimer = setTimeout(evaluate, EVAL_DEBOUNCE_MS);
+		evalTimer.unref?.();
+	});
+	currentUnsubscribe = unsubscribe;
+	const dispose = (): void => {
+		unsubscribe();
+		currentUnsubscribe = undefined;
+		currentDispose = undefined;
+		clearTimers();
+		deps.terminalStatus?.dispose();
+		deps.terminalStatus = undefined;
+		deps.terminalStatusActive = false;
+	};
+	currentDispose = dispose;
+
+	registerCleanupHandler(pi, { disposeTerminalStatus: dispose });
+}

package/src/extension/registration/viewers.ts

@@ -90,10 +90,16 @@ export async function openLiveConversation(
 					return overlay.render(width);
 				},
 				handleInput(data: string) {
+					// Close keys stay exactly as they were: close the overlay and
+					// resolve the custom() promise.
 					if (matchesKey(data, "escape") || matchesKey(data, "q")) {
 						overlay.close();
 						done(undefined);
+						return;
 					}
+					// Everything else scrolls the live transcript (P1-3):
+					// j/k, ↓/↑, g/G, PgUp/PgDn and the `a` auto-scroll toggle.
+					overlay.handleInput(data);
 				},
 				invalidate() {
 					/* overlay polls */

package/src/extension/registration/wire-cross-extension.ts

@@ -35,3 +35,31 @@ export function installCrossExtensionWiring(pi: ExtensionAPI, ctx: RegistrationC
 		});
 	});
 }
+
+/**
+ * F13 (RR-018): refresh the extension-lifetime cross-extension wiring for a
+ * new session. Called on every `session_start`.
+ *
+ * The RPC handle is installed ONCE at registration and survives session
+ * switches — its `getCtx` closure resolves the CURRENT session context at
+ * request time, so nothing needs reinstalling (re-registering would double
+ * the pi-crew:rpc:* subscriptions). The crew global registry IS rebound to
+ * the current session's manifest cache so a cross-project switch never
+ * leaves it reading a stale project's runs. Idempotent and cheap (a plain
+ * object construction — installCrewGlobalRegistry swaps the module-scoped
+ * singleton atomically).
+ */
+export function refreshCrossExtensionWiringForSession(pi: ExtensionAPI, ctx: RegistrationContext): void {
+	if (!ctx.rpcHandle) {
+		// Edge: registration never installed the handle (or a full shutdown
+		// removed it) — install it once, idempotently.
+		installCrossExtensionWiring(pi, ctx);
+		return;
+	}
+	void import("../team-tool.ts").then(({ installCrewGlobalRegistry }) => {
+		installCrewGlobalRegistry({
+			manifestCache: ctx.getManifestCache(ctx.currentCtx?.cwd ?? process.cwd()),
+			cwdProvider: () => ctx.currentCtx?.cwd ?? process.cwd(),
+		});
+	});
+}

package/src/extension/run-compare.ts

@@ -0,0 +1,220 @@
+import { readEvents } from "../state/event-log/event-log.ts";
+import { writeArtifact } from "../state/stores/artifact-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { formatCost, formatTokens } from "../state/usage.ts";
+import { formatDuration } from "../ui/format-helpers.ts";
+
+/**
+ * US-021 (2026-09-22) — run comparison (before/after diff of two runs).
+ *
+ * Scope per spec docs/specs/US-021.md: status delta, per-task
+ * status/duration/tokens/cost deltas, event-type set diff, model routing diff.
+ * NOT in scope: visual UI, git integration.
+ *
+ * Determinism: the markdown body contains NO wall-clock (the spec pins this so
+ * comparisons are byte-diffable — same pattern as US-022's injectable `now`).
+ * Everything rendered derives from run data; the artifact's own write time is
+ * filesystem metadata, not content. The output also deliberately contains NO
+ * absolute paths (ids, statuses and deltas only), so the run-export
+ * `redactHomePaths` pass is unnecessary here — noted because the spec asked.
+ */
+
+export interface TaskDelta {
+	id: string;
+	statusA?: string;
+	statusB?: string;
+	/** b − a; undefined when either side lacks the data (task missing, or no timestamps). */
+	durationDeltaMs?: number;
+	/** b − a; undefined when either side lacks usage. */
+	tokensDelta?: number;
+	/** b − a; undefined when either side lacks cost. */
+	costDelta?: number;
+}
+
+export interface ModelRoutingDiff {
+	taskId: string;
+	modelA?: string;
+	modelB?: string;
+}
+
+export interface RunComparison {
+	runA: string;
+	runB: string;
+	status: { a: string; b: string };
+	/** True when every compared field matches (the self-diff invariant). */
+	identical: boolean;
+	/** One row per task id present in EITHER run. */
+	tasks: TaskDelta[];
+	tasksOnlyInA: string[];
+	tasksOnlyInB: string[];
+	events: { addedTypes: string[]; removedTypes: string[] };
+	models: ModelRoutingDiff[];
+	usage: { tokensDelta: number; costDelta: number; tokensA: number; tokensB: number; costA: number; costB: number };
+}
+
+function taskDurationMs(task: TeamTaskState): number | undefined {
+	if (!task.startedAt || !task.finishedAt) return undefined;
+	const ms = new Date(task.finishedAt).getTime() - new Date(task.startedAt).getTime();
+	return Number.isFinite(ms) ? ms : undefined;
+}
+
+function taskTokens(task: TeamTaskState): number | undefined {
+	if (!task.usage) return undefined;
+	const { input, output } = task.usage;
+	if (input === undefined && output === undefined) return undefined;
+	return (input ?? 0) + (output ?? 0);
+}
+
+function taskCost(task: TeamTaskState): number | undefined {
+	const cost = task.usage?.cost;
+	return typeof cost === "number" && Number.isFinite(cost) ? cost : undefined;
+}
+
+function sumTokens(tasks: TeamTaskState[]): number {
+	return tasks.reduce((acc, task) => acc + (taskTokens(task) ?? 0), 0);
+}
+
+function sumCost(tasks: TeamTaskState[]): number {
+	return tasks.reduce((acc, task) => acc + (taskCost(task) ?? 0), 0);
+}
+
+function eventTypeSet(eventsPath: string): Set<string> {
+	const types = new Set<string>();
+	for (const event of readEvents(eventsPath)) {
+		if (event.type) types.add(event.type);
+	}
+	return types;
+}
+
+export function compareRuns(
+	manifestA: TeamRunManifest,
+	tasksA: TeamTaskState[],
+	manifestB: TeamRunManifest,
+	tasksB: TeamTaskState[],
+): RunComparison {
+	const byIdA = new Map(tasksA.map((task) => [task.id, task] as const));
+	const byIdB = new Map(tasksB.map((task) => [task.id, task] as const));
+	const allIds = [...new Set([...byIdA.keys(), ...byIdB.keys()])].sort();
+
+	const tasks: TaskDelta[] = allIds.map((id) => {
+		const a = byIdA.get(id);
+		const b = byIdB.get(id);
+		const delta: TaskDelta = { id };
+		if (a) delta.statusA = a.status;
+		if (b) delta.statusB = b.status;
+		const durA = a ? taskDurationMs(a) : undefined;
+		const durB = b ? taskDurationMs(b) : undefined;
+		if (durA !== undefined && durB !== undefined) delta.durationDeltaMs = durB - durA;
+		const tokA = a ? taskTokens(a) : undefined;
+		const tokB = b ? taskTokens(b) : undefined;
+		if (tokA !== undefined && tokB !== undefined) delta.tokensDelta = tokB - tokA;
+		const costA = a ? taskCost(a) : undefined;
+		const costB = b ? taskCost(b) : undefined;
+		if (costA !== undefined && costB !== undefined) delta.costDelta = costB - costA;
+		return delta;
+	});
+
+	const typesA = eventTypeSet(manifestA.eventsPath);
+	const typesB = eventTypeSet(manifestB.eventsPath);
+
+	const models: ModelRoutingDiff[] = allIds
+		.filter((id) => {
+			const a = byIdA.get(id)?.model;
+			const b = byIdB.get(id)?.model;
+			return a !== undefined || b !== undefined;
+		})
+		.map((id) => ({ taskId: id, modelA: byIdA.get(id)?.model, modelB: byIdB.get(id)?.model }))
+		.filter((diff) => diff.modelA !== diff.modelB);
+
+	const statusEqual = manifestA.status === manifestB.status;
+	const noTaskDeltas = tasks.every(
+		(delta) =>
+			delta.statusA === delta.statusB &&
+			(delta.durationDeltaMs ?? 0) === 0 &&
+			(delta.tokensDelta ?? 0) === 0 &&
+			(delta.costDelta ?? 0) === 0,
+	);
+	const tokensA = sumTokens(tasksA);
+	const tokensB = sumTokens(tasksB);
+	const costA = sumCost(tasksA);
+	const costB = sumCost(tasksB);
+
+	return {
+		runA: manifestA.runId,
+		runB: manifestB.runId,
+		status: { a: manifestA.status, b: manifestB.status },
+		identical:
+			statusEqual && noTaskDeltas && tasksA.length === tasksB.length && tokensA === tokensB && costA === costB && models.length === 0,
+		tasks,
+		tasksOnlyInA: tasksA.map((t) => t.id).filter((id) => !byIdB.has(id)),
+		tasksOnlyInB: tasksB.map((t) => t.id).filter((id) => !byIdA.has(id)),
+		events: {
+			addedTypes: [...typesB].filter((t) => !typesA.has(t)).sort(),
+			removedTypes: [...typesA].filter((t) => !typesB.has(t)).sort(),
+		},
+		models,
+		usage: { tokensDelta: tokensB - tokensA, costDelta: costB - costA, tokensA, tokensB, costA, costB },
+	};
+}
+
+function signed(value: number, format: (abs: number) => string): string {
+	if (value === 0) return "0";
+	return value > 0 ? `+${format(value)}` : `-${format(-value)}`;
+}
+
+export function renderComparisonMarkdown(comparison: RunComparison): string {
+	const lines: string[] = [
+		`# pi-crew comparison ${comparison.runA} vs ${comparison.runB}`,
+		"",
+		`Status: a=${comparison.status.a} b=${comparison.status.b}`,
+		`Comparison: ${comparison.identical ? "identical" : "different"}`,
+		"",
+		"## Tasks",
+		...(comparison.tasks.length
+			? comparison.tasks.map((delta) => {
+					const parts = [`- ${delta.id}: a=${delta.statusA ?? "(absent)"} b=${delta.statusB ?? "(absent)"}`];
+					if (delta.durationDeltaMs !== undefined) parts.push(`Δdur=${signed(delta.durationDeltaMs, formatDuration)}`);
+					if (delta.tokensDelta !== undefined) parts.push(`Δtok=${signed(delta.tokensDelta, formatTokens)}`);
+					if (delta.costDelta !== undefined) parts.push(`Δcost=${signed(delta.costDelta, formatCost)}`);
+					return parts.join(" ");
+				})
+			: ["- (none)"]),
+		`Only in a: ${comparison.tasksOnlyInA.length ? comparison.tasksOnlyInA.join(", ") : "(none)"}`,
+		`Only in b: ${comparison.tasksOnlyInB.length ? comparison.tasksOnlyInB.join(", ") : "(none)"}`,
+		"",
+		"## Models",
+		...(comparison.models.length
+			? comparison.models.map((m) => `- ${m.taskId}: ${m.modelA ?? "(none)"} -> ${m.modelB ?? "(none)"}`)
+			: ["- (no routing differences)"]),
+		"",
+		"## Events",
+		`Added types: ${comparison.events.addedTypes.length ? comparison.events.addedTypes.join(", ") : "(none)"}`,
+		`Removed types: ${comparison.events.removedTypes.length ? comparison.events.removedTypes.join(", ") : "(none)"}`,
+		"",
+		"## Totals",
+		`Tokens: a=${formatTokens(comparison.usage.tokensA)} b=${formatTokens(comparison.usage.tokensB)} Δ=${signed(comparison.usage.tokensDelta, formatTokens)}`,
+		`Cost: a=${formatCost(comparison.usage.costA)} b=${formatCost(comparison.usage.costB)} Δ=${signed(comparison.usage.costDelta, formatCost)}`,
+		"",
+	];
+	return lines.join("\n");
+}
+
+/**
+ * Compare two runs and write the markdown artifact under the FIRST run's
+ * artifactsRoot (spec AC-5) at `compare/<runA>__<runB>.md`.
+ */
+export function runCompareBundle(
+	manifestA: TeamRunManifest,
+	tasksA: TeamTaskState[],
+	manifestB: TeamRunManifest,
+	tasksB: TeamTaskState[],
+): { comparison: RunComparison; markdownPath: string } {
+	const comparison = compareRuns(manifestA, tasksA, manifestB, tasksB);
+	const artifact = writeArtifact(manifestA.artifactsRoot, {
+		kind: "summary",
+		relativePath: `compare/${manifestA.runId}__${manifestB.runId}.md`,
+		producer: "run-compare",
+		content: renderComparisonMarkdown(comparison),
+	});
+	return { comparison, markdownPath: artifact.path };
+}