pi-crew 0.11.1 → 0.11.4

package/src/extension/registration/observability.ts

@@ -49,6 +49,13 @@ export interface ObservabilityState {
 	autoRepairTimer: ReturnType<typeof setInterval> | undefined;
 	tempReconcileTimer: ReturnType<typeof setInterval> | undefined;
 	otlpExporter: OTLPExporterInstance | undefined;
+	/**
+	 * F11 (RR-018): promise of the most recent `configureObservability` run.
+	 * `disposeObservability` settles it deliberately so teardown never races a
+	 * still-suspended init continuation (which re-checks ownership after every
+	 * await and self-disposes its locals when ownership was lost).
+	 */
+	initPromise: Promise<void> | undefined;
 }
 
 /** Dependencies passed in by register.ts so this module stays decoupled. */
@@ -57,7 +64,18 @@ export interface ObservabilityDeps {
 	getManifestCache: (cwd: string) => ReturnType<typeof import("../../runtime/manifest-cache.ts").createManifestCache>;
 	notifyOperator: (notification: NotificationDescriptor) => void;
 	isCleanedUp: () => boolean;
-	reconcileStaleRuns: (cwd: string, cache: ReturnType<ObservabilityDeps["getManifestCache"]>, currentSessionId?: string) => unknown[];
+	/**
+	 * F11 (RR-018): read the RegistrationContext's `sessionGeneration`. The
+	 * generation is bumped by cleanup AND by every session_start/before_switch,
+	 * so unlike `isCleanedUp` it can never be reset back to "still owner" by a
+	 * newer session. Reuse this counter — do not invent a parallel one.
+	 */
+	getSessionGeneration: () => number;
+	reconcileStaleRuns: (
+		cwd: string,
+		cache: ReturnType<ObservabilityDeps["getManifestCache"]>,
+		currentSessionId?: string,
+	) => unknown[] | Promise<unknown[] | undefined>;
 	reconcileOrphanedTempWorkspaces: (now: number, opts: { cleanupOrphanedTempDirs?: boolean }) => unknown;
 	cleanupOrphanTempDirs: () => { cleaned: number; scanned: number; failed: number };
 	cleanupLegacyOrphanTempDirs: () => { cleaned: number; scanned: number; failed: number };
@@ -94,43 +112,77 @@ async function importOTLPExporter(): Promise<OTLPExporterCtor> {
  *  - `config.reliability?.autoRecover === true` → lazy-imports crash-recovery
  *    on a deferred setTimeout to avoid blocking session_start.
  */
-export async function configureObservability(ctx: ExtensionContext, state: ObservabilityState, deps: ObservabilityDeps): Promise<void> {
+export function configureObservability(ctx: ExtensionContext, state: ObservabilityState, deps: ObservabilityDeps): Promise<void> {
+	// F11: track the init promise so `disposeObservability` can settle it
+	// deliberately instead of racing it. The internal run first awaits any
+	// PREVIOUS init (via disposeObservability), so this assignment can never
+	// self-deadlock — state.initPromise still referenced the old run when the
+	// internal run suspended.
+	const run = configureObservabilityInternal(ctx, state, deps);
+	state.initPromise = run;
+	return run;
+}
+
+async function configureObservabilityInternal(ctx: ExtensionContext, state: ObservabilityState, deps: ObservabilityDeps): Promise<void> {
+	// F11 (RR-018): capture the session generation at configure time. Every
+	// await boundary below re-verifies ownership before touching shared state;
+	// a continuation whose generation no longer matches can never publish —
+	// even when a newer session has already reset `cleanedUp` back to false
+	// (the real ordering: cleanup sets it true, session_start resets it false).
+	const ownerGeneration = deps.getSessionGeneration();
+	const stillOwns = (): boolean => deps.getSessionGeneration() === ownerGeneration && !deps.isCleanedUp();
+
 	// Always start from a clean slate: dispose any prior-session state first.
 	await disposeObservability(state, deps.isCleanedUp());
+	if (!stillOwns()) return;
 
 	const config = loadConfig(ctx.cwd).config;
 	if (config.observability?.enabled === false) return;
 
 	// LAZY: observability stack — only paid for when observability is actually enabled
 	const { createMetricRegistry } = await import("../../observability/metric-registry.ts");
+	if (!stillOwns()) return;
 	// LAZY: event→metric bridge
 	const { wireEventToMetrics } = await import("../../observability/event-to-metric.ts");
+	if (!stillOwns()) return;
 	// LAZY: file-backed metric sink
 	const { createMetricFileSink } = await import("../../observability/metric-sink.ts");
+	if (!stillOwns()) return;
 
-	state.metricRegistry = createMetricRegistry();
-	if (deps.pi.events) {
-		state.eventMetricSub = wireEventToMetrics(deps.pi.events, state.metricRegistry);
-	}
-	if (config.telemetry?.enabled !== false) {
-		state.metricSink = createMetricFileSink({
-			crewRoot: projectCrewRoot(ctx.cwd),
-			registry: state.metricRegistry,
-			retentionDays: config.observability?.metricRetentionDays ?? 7,
-		});
+	// F11: create into LOCALS — shared state is only touched after ownership is
+	// re-verified. If ownership was lost in the gap, everything just created is
+	// disposed right here in the continuation instead of leaking (0 orphans).
+	const metricRegistry = createMetricRegistry();
+	const eventMetricSub = deps.pi.events ? wireEventToMetrics(deps.pi.events, metricRegistry) : undefined;
+	const metricSink =
+		config.telemetry?.enabled !== false
+			? createMetricFileSink({
+					crewRoot: projectCrewRoot(ctx.cwd),
+					registry: metricRegistry,
+					retentionDays: config.observability?.metricRetentionDays ?? 7,
+				})
+			: undefined;
+	if (!stillOwns()) {
+		eventMetricSub?.dispose();
+		metricSink?.dispose();
+		metricRegistry.dispose();
+		return;
 	}
+	state.metricRegistry = metricRegistry;
+	state.eventMetricSub = eventMetricSub;
+	state.metricSink = metricSink;
 
 	// OTLP export is opt-in. Lazy-loaded via dynamic import.
 	if (config.otlp?.enabled === true && config.otlp.endpoint) {
 		const otlpEndpoint = config.otlp.endpoint;
 		const otlpHeaders = config.otlp.headers;
 		const otlpInterval = config.otlp.intervalMs;
-		const owningRegistry = state.metricRegistry;
+		const owningRegistry = metricRegistry;
 		// LAZY: opt-in OTLP export — load the exporter module on first enable.
 		void importOTLPExporter()
 			.then((Ctor) => {
-				if (deps.isCleanedUp() || state.metricRegistry !== owningRegistry || !owningRegistry) return;
-				state.otlpExporter = new Ctor(
+				if (!stillOwns() || state.metricRegistry !== owningRegistry || !owningRegistry) return;
+				const otlpExporter = new Ctor(
 					{
 						endpoint: otlpEndpoint,
 						headers: otlpHeaders,
@@ -138,18 +190,20 @@ export async function configureObservability(ctx: ExtensionContext, state: Obser
 					},
 					owningRegistry,
 				);
-				state.otlpExporter?.start();
+				state.otlpExporter = otlpExporter;
+				otlpExporter.start();
 			})
 			.catch((error: unknown) => logInternalError("register.otlp-lazy-import", error));
 	}
 
 	// LAZY: heartbeat watcher — polled per-session, wires deadletter + metric events.
 	const { HeartbeatWatcher } = await import("../../runtime/heartbeat/heartbeat-watcher.ts");
-	state.heartbeatWatcher = new HeartbeatWatcher({
+	if (!stillOwns()) return;
+	const heartbeatWatcher = new HeartbeatWatcher({
 		cwd: ctx.cwd,
 		pollIntervalMs: config.observability?.pollIntervalMs ?? 5000,
 		manifestCache: deps.getManifestCache(ctx.cwd),
-		registry: state.metricRegistry,
+		registry: metricRegistry,
 		router: {
 			enqueue: (notification) => {
 				deps.notifyOperator(notification);
@@ -173,25 +227,24 @@ export async function configureObservability(ctx: ExtensionContext, state: Obser
 			});
 		},
 	});
-	state.heartbeatWatcher.start();
+	// F11: the watcher is created into a local and only published once
+	// ownership is re-verified — a lost-ownership continuation disposes it
+	// instead of publishing a live poller nobody will tear down.
+	if (!stillOwns()) {
+		heartbeatWatcher.dispose();
+		return;
+	}
+	state.heartbeatWatcher = heartbeatWatcher;
+	heartbeatWatcher.start();
 
 	// RT-F2: opportunistic stale-run reconcile hook.
-	// The .unref()'d setInterval below never fires while the event loop is idle
-	// (e.g. user has the editor open but hasn't sent a turn in an hour). Pair it
-	// with a before_agent_start hook so reconcileAllStaleRuns also fires when
-	// the user actually drives the session — bounded by user activity.
-	try {
-		deps.pi.on?.("before_agent_start", () => {
-			if (deps.isCleanedUp()) return;
-			try {
-				deps.reconcileStaleRuns(ctx.cwd, deps.getManifestCache(ctx.cwd), extractSessionId(ctx));
-			} catch (error) {
-				logInternalError("register.autoRepair.turnHook", error);
-			}
-		});
-	} catch {
-		/* older Pi without before_agent_start — rely on the interval alone */
-	}
+	// F12 (RR-018): the `before_agent_start` hook is NO LONGER registered here.
+	// It is registered exactly ONCE per extension in `lazy-configurers.ts`
+	// (installTurnReconcileHook) and resolves the CURRENT session context at
+	// fire time — per-session registration accumulated one dead hook per
+	// switch (there is no pi.off), and the stale hook re-activated with the
+	// old session's cwd, flipping the shared manifest cache back. The
+	// .unref()'d setInterval below remains the idle-time safety net.
 
 	// Auto-repair timers: stale-run reconcile + orphan-temp cleanup.
 	// RT-F2: default raised from 60_000ms to 5 minutes (300_000ms). The previous
@@ -204,26 +257,31 @@ export async function configureObservability(ctx: ExtensionContext, state: Obser
 	if (autoRepairIntervalMs > 0) {
 		state.autoRepairTimer = setInterval(() => {
 			if (deps.isCleanedUp()) return;
-			try {
-				const staleResults = deps.reconcileStaleRuns(ctx.cwd, deps.getManifestCache(ctx.cwd), extractSessionId(ctx));
-				if (Array.isArray(staleResults) && staleResults.length > 0) {
-					for (const result of staleResults) {
-						const repaired = (result as { repaired?: boolean }).repaired;
-						if (repaired) {
-							deps.notifyOperator({
-								id: `auto_repair_${(result as { runId: string }).runId}`,
-								severity: "info",
-								source: "auto-repair",
-								runId: (result as { runId: string }).runId,
-								title: `Auto-repaired stale run`,
-								body: (result as { detail?: string }).detail ?? "",
-							});
+			// RR-021 WI-1.5: reconcileStaleRuns may be async (mapConcurrent) —
+			// settle the result before inspecting, keep errors inside the log.
+			void (async () => {
+				try {
+					const settled = await deps.reconcileStaleRuns(ctx.cwd, deps.getManifestCache(ctx.cwd), extractSessionId(ctx));
+					const staleResults = Array.isArray(settled) ? settled : [];
+					if (staleResults.length > 0) {
+						for (const result of staleResults) {
+							const repaired = (result as { repaired?: boolean }).repaired;
+							if (repaired) {
+								deps.notifyOperator({
+									id: `auto_repair_${(result as { runId: string }).runId}`,
+									severity: "info",
+									source: "auto-repair",
+									runId: (result as { runId: string }).runId,
+									title: `Auto-repaired stale run`,
+									body: (result as { detail?: string }).detail ?? "",
+								});
+							}
 						}
 					}
+				} catch (error) {
+					logInternalError("register.autoRepair", error);
 				}
-			} catch (error) {
-				logInternalError("register.autoRepair", error);
-			}
+			})();
 		}, autoRepairIntervalMs);
 		state.autoRepairTimer.unref();
 
@@ -273,7 +331,7 @@ export async function configureObservability(ctx: ExtensionContext, state: Obser
 		void deps
 			.importCrashRecovery()
 			.then(({ detectInterruptedRuns }) => {
-				if (deps.isCleanedUp()) return;
+				if (!stillOwns()) return;
 				const sid = extractSessionId(ctx);
 				for (const plan of detectInterruptedRuns(cwdSnapshot, cacheSnapshot, 300_000, sid)) {
 					deps.notifyOperator({
@@ -296,6 +354,20 @@ export async function configureObservability(ctx: ExtensionContext, state: Obser
  * gated by the orchestrator's overall cleanup state.
  */
 export async function disposeObservability(state: ObservabilityState, _isCleanedUp: boolean): Promise<void> {
+	// F11 (RR-018): settle any in-flight init BEFORE disposing shared state, so
+	// teardown never races a still-suspended continuation. The continuation
+	// itself re-checks ownership after every await and self-disposes its
+	// locals, so this await only bounds the race window — it never starts new
+	// work and cannot deadlock (the previous init completes on its own).
+	const initPromise = state.initPromise;
+	state.initPromise = undefined;
+	if (initPromise) {
+		try {
+			await initPromise;
+		} catch {
+			/* configureObservabilityImpl logs its own errors */
+		}
+	}
 	state.heartbeatWatcher?.dispose();
 	state.heartbeatWatcher = undefined;
 	if (state.autoRepairTimer) {

package/src/extension/registration/registration-types.ts

@@ -37,12 +37,14 @@ export type AbortControllerMap = Map<AbortKey, AbortController>;
 /**
  * Single auto-recovery cooldown gate entry. Tracked by the render-tick
  * health notifier so the same warning doesn't fire repeatedly within a
- * 5-minute cooldown. Uses LRU-like semantics — see register.ts.
+ * 5-minute cooldown, and (FINDING 6) at most MAX_HEALTH_NOTIFY_FIRES times
+ * per unchanged fingerprint. LRU-like semantics — see register.ts and
+ * health-notify-policy.ts (the authoritative definition; re-exported here
+ * so existing imports keep working).
  */
-export interface AutoRecoveryEntry {
-	insertedAt: number;
-	lastAccessAt: number;
-}
+export type { AutoRecoveryEntry } from "./health-notify-policy.ts";
+
+import type { AutoRecoveryEntry } from "./health-notify-policy.ts";
 
 /**
  * Mutable context bag passed from the orchestrator to every

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/team-tool.ts

@@ -2,7 +2,7 @@ import { statSync } from "node:fs";
 import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { TObject } from "@sinclair/typebox";
-import { Value } from "@sinclair/typebox/value";
+import { TypeCompiler } from "@sinclair/typebox/compiler";
 import { loadConfig } from "../../config/config.ts";
 import { findClosestKey } from "../../config/suggestions.ts";
 import type { MetricRegistry } from "../../observability/metric-registry.ts";
@@ -36,6 +36,12 @@ import { withSessionId } from "../team-tool/context.ts";
 import { formatTeamToolParamError } from "../team-tool/param-error.ts";
 import { toolResult } from "../tool-result.ts";
 
+// RR-021 WI-4.3g: compile the team-tool schema ONCE. Value.Check re-walks the
+// whole (large) schema object on every tool call; TypeCompiler.Compile (STATIC
+// method on @sinclair/typebox/compiler) builds a specialized checker at module
+// load. The error formatter keeps using the schema + Value.Errors (cold path).
+const compiledTeamToolParams = TypeCompiler.Compile(TeamToolParams);
+
 /**
  * Normalize model-generated tool params before schema validation.
  *
@@ -228,7 +234,8 @@ export function registerTeamTool(pi: ExtensionAPI, deps: RegisterTeamToolDeps):
 				// validation so strict unions/patterns accept "unset" as omitted.
 				const normalized = normalizeTeamParams(params);
 				// Defense-in-depth: validate params at runtime even though Pi framework already does
-				if (!Value.Check(TeamToolParams, normalized)) {
+				// (RR-021 WI-4.3g: precompiled checker — same semantics as Value.Check.)
+				if (!compiledTeamToolParams.Check(normalized)) {
 					return toolResult(formatTeamToolParamError(TeamToolParams, normalized), { action: "list", status: "error" }, true);
 				}
 				// EXT-1: additionalProperties:true lets unknown (typo'd) keys slip past

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

@@ -28,6 +28,7 @@ export function installCrossExtensionWiring(pi: ExtensionAPI, ctx: RegistrationC
 	// in the entire runtime chain) out of the cold-start module graph. EXT-9:
 	// the registry now lives in module-scoped state, not globalThis.
 	void import("../team-tool.ts").then(({ installCrewGlobalRegistry }) => {
+		// LAZY: defer team-tool until cross-extension wiring fires
 		const manifestCacheForRegistry = ctx.getManifestCache(ctx.currentCtx?.cwd ?? process.cwd());
 		installCrewGlobalRegistry({
 			manifestCache: manifestCacheForRegistry,
@@ -35,3 +36,32 @@ 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 }) => {
+		// LAZY: defer team-tool until cross-extension wiring fires
+		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 };
+}