pi-crew 0.11.1 → 0.11.2

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,6 +64,13 @@ export interface ObservabilityDeps {
 	getManifestCache: (cwd: string) => ReturnType<typeof import("../../runtime/manifest-cache.ts").createManifestCache>;
 	notifyOperator: (notification: NotificationDescriptor) => void;
 	isCleanedUp: () => boolean;
+	/**
+	 * 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[];
 	reconcileOrphanedTempWorkspaces: (now: number, opts: { cleanupOrphanedTempDirs?: boolean }) => unknown;
 	cleanupOrphanTempDirs: () => { cleaned: number; scanned: number; failed: number };
@@ -94,43 +108,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 +186,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 +223,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
@@ -273,7 +322,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 +345,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/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 };
+}

package/src/extension/run-export.ts

@@ -5,6 +5,8 @@ import * as path from "node:path";
 import { readEvents, type TeamEvent } from "../state/event-log/event-log.ts";
 import { writeArtifact } from "../state/stores/artifact-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { aggregateUsage, formatCost, formatTokens } from "../state/usage.ts";
+import { formatDuration } from "../ui/format-helpers.ts";
 import { redactSecrets } from "../utils/redaction.ts";
 
 /** Replace absolute paths containing home directory with ~/ */
@@ -36,14 +38,30 @@ export interface ExportedRunBundle {
 	artifactPaths: string[];
 }
 
-export function exportRunBundle(manifest: TeamRunManifest, tasks: TeamTaskState[]): { jsonPath: string; markdownPath: string } {
+/**
+ * Export a run bundle (JSON + markdown report).
+ *
+ * US-022 (2026-09-22): `now` is injectable so repeated exports of the same run
+ * are byte-identical. `exportedAt` sits INSIDE the hashed payload, so a
+ * wall-clock stamp made both the JSON and its sha256 (and the markdown
+ * `Exported:` line) drift on every export — harmless for import (run-import
+ * recomputes the hash minus `sha256`) but fatal for byte-diffing and for
+ * reproducing a bundle in tests. Mirrors `createRunManifest`'s `now?: () => Date`.
+ */
+export function exportRunBundle(
+	manifest: TeamRunManifest,
+	tasks: TeamTaskState[],
+	now?: () => Date,
+): { jsonPath: string; markdownPath: string } {
 	const events = readEvents(manifest.eventsPath);
 	const safeManifest = redactHomePaths(manifest);
 	const safeTasks = redactHomePaths(tasks);
 	const safeEvents = redactHomePaths(events);
+	// US-022: aggregate usage once (tasks already in hand) for the Cost section.
+	const usageTotal = aggregateUsage(safeTasks as TeamTaskState[]);
 	const bundle: ExportedRunBundle = {
 		schemaVersion: 1,
-		exportedAt: new Date().toISOString(),
+		exportedAt: (now ? now() : new Date()).toISOString(),
 		manifest: safeManifest as TeamRunManifest,
 		tasks: safeTasks as TeamTaskState[],
 		events: safeEvents as TeamEvent[],
@@ -71,10 +89,24 @@ export function exportRunBundle(manifest: TeamRunManifest, tasks: TeamTaskState[
 			`Workflow: ${safeManifest.workflow ?? "(none)"}`,
 			`Goal: ${safeManifest.goal}`,
 			"",
+			"## Cost",
+			...(usageTotal
+				? [
+						`- tokens: ${formatTokens((usageTotal.input ?? 0) + (usageTotal.output ?? 0))} (in ${formatTokens(usageTotal.input ?? 0)} / out ${formatTokens(usageTotal.output ?? 0)})`,
+						`- cost: ${formatCost(usageTotal.cost)}`,
+					]
+				: ["- (no usage recorded)"]),
+			"",
 			"## Tasks",
-			...safeTasks.map(
-				(task) => `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${task.error ? ` - ${task.error}` : ""}`,
-			),
+			...safeTasks.map((task) => {
+				// US-022: surface model + duration inline (data was already in hand).
+				const duration =
+					task.startedAt && task.finishedAt
+						? ` [${formatDuration(new Date(task.finishedAt).getTime() - new Date(task.startedAt).getTime())}]`
+						: "";
+				const model = task.model ? ` <${task.model}>` : "";
+				return `- ${task.id}: ${task.status} (${task.role} -> ${task.agent})${model}${duration}${task.error ? ` - ${task.error}` : ""}`;
+			}),
 			"",
 			"## Artifacts",
 			...(safeManifest.artifacts.length