pi-crew 0.9.53 → 0.9.55

package/src/extension/registration/lifecycle.ts

@@ -0,0 +1,259 @@
+/**
+ * Lifecycle installer (H3 + L2 — Phase 4 of cleanup plan).
+ *
+ * Owns the run-lifecycle subscriptions that should fire ONLY when a run is
+ * active. This is the "lazy" half of H3 — the heavy heartbeat/auto-repair
+ * graph stays out of cold start until a run actually starts.
+ *
+ * Extracted from src/extension/register.ts. State holder is `LifecycleState`;
+ * installer is `startLifecycleWatchers(ctx, state, deps)` which fires on
+ * session_start (when the first run becomes possible) and is no-op when
+ * `activeRunCount === 0`.
+ *
+ * Also owns DeliveryCoordinator + OverflowRecoveryTracker + NotificationRouter
+ * wiring since these are all "delivery lifecycle" services that share the
+ * same per-session install/dispose pattern.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import { DEFAULT_NOTIFICATIONS, DEFAULT_UI } from "../../config/defaults.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import type { AsyncNotifierState } from "../async-notifier.ts";
+import type { NotificationDescriptor, NotificationRouter } from "../notification-router.ts";
+import type { NotificationSink } from "../notification-sink.ts";
+
+/**
+ * Mutable state owned by register.ts and read/written by this module.
+ * Tracks whether the async notifier is currently running so we can
+ * safely no-op duplicate calls.
+ */
+export interface LifecycleState {
+	notifierStarted: boolean;
+	notificationSink: NotificationSink | undefined;
+	notificationRouter: NotificationRouter | undefined;
+	deliveryCoordinator: import("../../runtime/delivery-coordinator.ts").DeliveryCoordinator | undefined;
+	overflowTracker: import("../../runtime/overflow-recovery.ts").OverflowRecoveryTracker | undefined;
+}
+
+/** Dependencies passed in by register.ts so this module stays decoupled. */
+export interface LifecycleDeps {
+	pi: ExtensionAPI;
+	notifierState: AsyncNotifierState;
+	isCleanedUp: () => boolean;
+	isContextCurrent: (ctx: ExtensionContext, ownerGeneration: number) => boolean;
+	ownerGeneration: number;
+}
+
+/**
+ * Start the async-run notifier. Idempotent — repeated calls while running
+ * are no-ops. Returns true if started now, false if already running or
+ * skipped due to config gate.
+ *
+ * NOTE: This module does NOT start heartbeat watchers or auto-repair timers.
+ * Those live in `observability.ts` (configurable + resource-heavy). This
+ * module only manages the lightweight async-run poller.
+ */
+export function startLifecycleWatchers(ctx: ExtensionContext, state: LifecycleState, deps: LifecycleDeps): boolean {
+	if (state.notifierStarted) return false;
+	const loadedConfig = loadConfig(ctx.cwd);
+	state.notifierStarted = true;
+	try {
+		// LAZY: async-notifier pulls in debounce + cron helpers — defer
+		// until the first lifecycle install (deferred import within module).
+		void import("../async-notifier.ts").then(({ startAsyncRunNotifier }) => {
+			if (deps.isCleanedUp()) return;
+			startAsyncRunNotifier(ctx, deps.notifierState, loadedConfig.config.notifierIntervalMs ?? DEFAULT_UI.notifierIntervalMs, {
+				generation: deps.ownerGeneration,
+				isCurrent: (generation) => generation === deps.ownerGeneration && deps.isContextCurrent(ctx, deps.ownerGeneration),
+			});
+		});
+		return true;
+	} catch (error) {
+		state.notifierStarted = false;
+		logInternalError("register.startLifecycleWatchers", error);
+		return false;
+	}
+}
+
+/**
+ * Stop the async-run notifier. Safe to call when not started.
+ */
+export function stopLifecycleWatchers(state: LifecycleState, deps: LifecycleDeps): void {
+	if (!state.notifierStarted) return;
+	state.notifierStarted = false;
+	try {
+		void import("../async-notifier.ts").then(({ stopAsyncRunNotifier }) => {
+			stopAsyncRunNotifier(deps.notifierState);
+		});
+	} catch (error) {
+		logInternalError("register.stopLifecycleWatchers", error);
+	}
+}
+
+/** Dependencies for configureNotifications (UI-facing delivery wiring). */
+export interface NotificationsDeps {
+	pi: ExtensionAPI;
+	widgetState: { notificationCount?: number };
+	getCurrentCtx: () => ExtensionContext | undefined;
+	getManifestCache: (cwd: string) => ReturnType<typeof import("../../runtime/manifest-cache.ts").createManifestCache>;
+	getRunSnapshotCache: (cwd: string) => ReturnType<typeof import("../../ui/run-snapshot-cache.ts").createRunSnapshotCache>;
+	requestPowerbarUpdate: (
+		events: Parameters<typeof import("../../ui/powerbar-publisher.ts").requestPowerbarUpdate>[0],
+		cwd: string,
+		uiConfig: Parameters<typeof import("../../ui/powerbar-publisher.ts").requestPowerbarUpdate>[2],
+		manifestCache: Parameters<typeof import("../../ui/powerbar-publisher.ts").requestPowerbarUpdate>[3],
+		snapshotCache: Parameters<typeof import("../../ui/powerbar-publisher.ts").requestPowerbarUpdate>[4],
+		ctx: ExtensionContext,
+		notificationCount: number,
+	) => void;
+}
+
+/**
+ * Configure the notification router + JSONL sink. Idempotent — caller should
+ * dispose prior state first. Pulled out of register.ts as part of H3-L2.
+ *
+ * Gates:
+ *  - `config.notifications?.enabled === false` → no-op.
+ */
+export async function configureNotifications(ctx: ExtensionContext, state: LifecycleState, deps: NotificationsDeps): Promise<void> {
+	state.notificationRouter?.dispose();
+	state.notificationSink?.dispose();
+	state.notificationRouter = undefined;
+	state.notificationSink = undefined;
+	const config = loadConfig(ctx.cwd).config;
+	if (config.notifications?.enabled === false) return;
+
+	// LAZY: notification router — wires events to sinks
+	const { NotificationRouter } = await import("../notification-router.ts");
+	// LAZY: JSONL sink — file-backed notification storage
+	const { createJsonlSink } = await import("../notification-sink.ts");
+	// LAZY: follow-up helpers — shared with subagent handoff
+	const { sendFollowUp } = await import("./subagent-helpers.ts");
+	// LAZY: widget updater — refreshes the TUI status widget
+	const { updateCrewWidget } = await import("../../ui/widget/index.ts");
+
+	if (config.telemetry?.enabled !== false) {
+		state.notificationSink = createJsonlSink(
+			projectCrewRoot(ctx.cwd),
+			config.notifications?.sinkRetentionDays ?? DEFAULT_NOTIFICATIONS.sinkRetentionDays,
+		);
+	}
+	state.notificationRouter = new NotificationRouter(
+		{
+			dedupWindowMs: config.notifications?.dedupWindowMs ?? DEFAULT_NOTIFICATIONS.dedupWindowMs,
+			batchWindowMs: config.notifications?.batchWindowMs ?? DEFAULT_NOTIFICATIONS.batchWindowMs,
+			quietHours: config.notifications?.quietHours,
+			severityFilter: config.notifications?.severityFilter ?? [...DEFAULT_NOTIFICATIONS.severityFilter],
+			sink: (notification) => state.notificationSink?.write(notification),
+		},
+		(notification: NotificationDescriptor) => {
+			deps.widgetState.notificationCount = (deps.widgetState.notificationCount ?? 0) + 1;
+			sendFollowUp(
+				deps.pi,
+				[notification.title, notification.body, notification.runId ? `Run: ${notification.runId}` : undefined]
+					.filter((line): line is string => Boolean(line))
+					.join("\n"),
+			);
+			const currentCtx = deps.getCurrentCtx();
+			if (currentCtx) {
+				const uiConfig = loadConfig(currentCtx.cwd).config.ui;
+				updateCrewWidget(
+					currentCtx,
+					deps.widgetState as Parameters<typeof updateCrewWidget>[1],
+					uiConfig,
+					deps.getManifestCache(currentCtx.cwd),
+					deps.getRunSnapshotCache(currentCtx.cwd),
+				);
+				deps.requestPowerbarUpdate(
+					deps.pi.events,
+					currentCtx.cwd,
+					uiConfig,
+					deps.getManifestCache(currentCtx.cwd),
+					deps.getRunSnapshotCache(currentCtx.cwd),
+					currentCtx,
+					deps.widgetState.notificationCount ?? 0,
+				);
+			}
+		},
+	);
+}
+
+/** Dispose notification router + sink. */
+export function disposeNotifications(state: LifecycleState): void {
+	state.notificationRouter?.dispose();
+	state.notificationRouter = undefined;
+	state.notificationSink?.dispose();
+	state.notificationSink = undefined;
+}
+
+/** Dependencies for configureDeliveryCoordinator. */
+export interface DeliveryDeps {
+	pi: ExtensionAPI;
+	observabilityState: { metricRegistry?: import("../../observability/metric-registry.ts").MetricRegistry };
+	notifyOperator: (notification: NotificationDescriptor) => void;
+	sendFollowUp: (pi: ExtensionAPI, message: string) => void;
+	sendAgentWakeUp: (pi: ExtensionAPI, message: string) => void;
+}
+
+/**
+ * Configure the delivery coordinator + overflow tracker. Extracted from
+ * register.ts as part of H3-L2 (delivery lifecycle service).
+ */
+export async function configureDeliveryCoordinator(state: LifecycleState, deps: DeliveryDeps): Promise<void> {
+	state.deliveryCoordinator?.dispose();
+	state.deliveryCoordinator = undefined;
+	state.overflowTracker?.dispose();
+	state.overflowTracker = undefined;
+	// LAZY: delivery coordinator — batches notification fan-out
+	const { DeliveryCoordinator } = await import("../../runtime/delivery-coordinator.ts");
+	// LAZY: overflow tracker — recovers from backlog overflow
+	const { OverflowRecoveryTracker } = await import("../../runtime/overflow-recovery.ts");
+	state.deliveryCoordinator = new DeliveryCoordinator({
+		emit: (event, data) => {
+			deps.pi.events?.emit?.(event, data);
+		},
+		sendFollowUp: (title, body) => {
+			deps.sendFollowUp(deps.pi, [title, body].filter((line): line is string => Boolean(line)).join("\n"));
+		},
+		sendWakeUp: (message) => {
+			deps.sendAgentWakeUp(deps.pi, message);
+		},
+	});
+	state.overflowTracker = new OverflowRecoveryTracker({
+		onPhaseChange: (phaseState, previousPhase) => {
+			if (deps.observabilityState.metricRegistry) {
+				deps.observabilityState.metricRegistry
+					.counter("crew.task.overflow_recovery_total", "Overflow recovery phase transitions")
+					.inc({
+						phase: phaseState.phase,
+						previous_phase: previousPhase,
+					});
+			}
+			deps.pi.events?.emit?.("crew.task.overflow", {
+				runId: phaseState.runId,
+				taskId: phaseState.taskId,
+				phase: phaseState.phase,
+				previousPhase,
+			});
+		},
+		onTimeout: (phaseState) => {
+			deps.notifyOperator({
+				id: `overflow_timeout_${phaseState.taskId}`,
+				severity: "warning",
+				source: "overflow-recovery",
+				runId: phaseState.runId,
+				title: `Task ${phaseState.taskId} overflow recovery timed out`,
+				body: `Phase: ${phaseState.phase}, compaction_count: ${phaseState.compactionCount}, retry_count: ${phaseState.retryCount}. The task may be stuck.`,
+			});
+		},
+	});
+}
+
+/** Dispose delivery coordinator + overflow tracker. */
+export function disposeDeliveryCoordinator(state: LifecycleState): void {
+	state.deliveryCoordinator?.dispose();
+	state.deliveryCoordinator = undefined;
+	state.overflowTracker?.dispose();
+	state.overflowTracker = undefined;
+}

package/src/extension/registration/observability.ts

@@ -0,0 +1,322 @@
+/**
+ * Observability installer (H3 + L2 — Phase 4 of cleanup plan).
+ *
+ * Owns the observability lifecycle for the pi-crew extension:
+ *   - MetricRegistry + EventToMetricSubscription (wireEventToMetrics)
+ *   - Metric file sink (JSONL writer)
+ *   - OTLPExporter (lazy-imported when otlp.enabled=true)
+ *   - HeartbeatWatcher (per-session, polling)
+ *   - Auto-repair timers (stale-reconcile + orphan-temp-dirs cleanup)
+ *
+ * Extracted from src/extension/register.ts so the orchestrator stays thin.
+ * The module exports `ObservabilityState` (mutable state holder) and
+ * `configureObservability(ctx, state, deps)` (the install function). The
+ * orchestrator keeps ownership of `state` so cleanupRuntime can dispose
+ * via `disposeObservability(state, isCleanedUp)`.
+ *
+ * This file is a TARGET for lazy loading (H3 follow-up): on systems where
+ * observability.enabled === false, `installObservability()` is never
+ * imported — the heavy observability module graph stays out of cold start.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../../config/config.ts";
+import type { EventToMetricSubscription } from "../../observability/event-to-metric.ts";
+import type { MetricRegistry } from "../../observability/metric-registry.ts";
+import type { MetricSink } from "../../observability/metric-sink.ts";
+import type { HeartbeatWatcher } from "../../runtime/heartbeat-watcher.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import type { NotificationDescriptor } from "../notification-router.ts";
+
+/** Type-only alias for the lazy-loaded OTLPExporter (avoid static import). */
+type OTLPExporterInstance = import("../../observability/exporters/otlp-exporter.ts").OTLPExporter;
+type OTLPExporterCtor = new (
+	opts: import("../../observability/exporters/otlp-exporter.ts").OTLPExporterOptions,
+	registry: import("../../observability/metric-registry.ts").MetricRegistry,
+) => OTLPExporterInstance;
+
+/**
+ * Mutable state owned by register.ts and read/written by this module.
+ * Pass this same object to `configureObservability` and `disposeObservability`
+ * so they can mutate the fields in-place.
+ */
+export interface ObservabilityState {
+	metricRegistry: MetricRegistry | undefined;
+	eventMetricSub: EventToMetricSubscription | undefined;
+	metricSink: MetricSink | undefined;
+	heartbeatWatcher: HeartbeatWatcher | undefined;
+	autoRepairTimer: ReturnType<typeof setInterval> | undefined;
+	tempReconcileTimer: ReturnType<typeof setInterval> | undefined;
+	otlpExporter: OTLPExporterInstance | undefined;
+}
+
+/** Dependencies passed in by register.ts so this module stays decoupled. */
+export interface ObservabilityDeps {
+	pi: ExtensionAPI;
+	getManifestCache: (cwd: string) => ReturnType<typeof import("../../runtime/manifest-cache.ts").createManifestCache>;
+	notifyOperator: (notification: NotificationDescriptor) => void;
+	isCleanedUp: () => boolean;
+	reconcileStaleRuns: (cwd: string, cache: ReturnType<ObservabilityDeps["getManifestCache"]>) => unknown[];
+	reconcileOrphanedTempWorkspaces: (now: number, opts: { cleanupOrphanedTempDirs?: boolean }) => unknown;
+	cleanupOrphanTempDirs: () => { cleaned: number; scanned: number; failed: number };
+	cleanupLegacyOrphanTempDirs: () => { cleaned: number; scanned: number; failed: number };
+	appendDeadletter: (
+		manifest: import("../../state/types.ts").TeamRunManifest,
+		entry: { taskId: string; runId: string; reason: string; attempts: number; timestamp: string },
+	) => void;
+	importCrashRecovery: () => Promise<{
+		detectInterruptedRuns: (
+			cwd: string,
+			cache: ReturnType<ObservabilityDeps["getManifestCache"]>,
+		) => Iterable<{ runId: string; resumableTasks: unknown[] }>;
+	}>;
+}
+
+let _cachedOTLPExporter: OTLPExporterCtor | undefined;
+async function importOTLPExporter(): Promise<OTLPExporterCtor> {
+	if (!_cachedOTLPExporter) {
+		// LAZY: opt-in OTLP metric export — load only when otlp.enabled=true.
+		const mod = await import("../../observability/exporters/otlp-exporter.ts");
+		_cachedOTLPExporter = mod.OTLPExporter as unknown as OTLPExporterCtor;
+	}
+	return _cachedOTLPExporter;
+}
+
+/**
+ * Configure the observability stack for the current session. Idempotent
+ * (caller should call `disposeObservability` first on each session_start
+ * cycle to avoid stacking watchers).
+ *
+ * Gates:
+ *  - `config.observability?.enabled === false` → no-op (skips all init).
+ *  - `config.telemetry?.enabled !== false` → installs metric file sink.
+ *  - `config.otlp?.enabled === true` → lazy-loads OTLPExporter.
+ *  - `config.reliability?.autoRepairIntervalMs > 0` → starts reconcile timers.
+ *  - `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> {
+	// Always start from a clean slate: dispose any prior-session state first.
+	await disposeObservability(state, deps.isCleanedUp());
+
+	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");
+	// LAZY: event→metric bridge
+	const { wireEventToMetrics } = await import("../../observability/event-to-metric.ts");
+	// LAZY: file-backed metric sink
+	const { createMetricFileSink } = await import("../../observability/metric-sink.ts");
+
+	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,
+		});
+	}
+
+	// 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;
+		// 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(
+					{
+						endpoint: otlpEndpoint,
+						headers: otlpHeaders,
+						intervalMs: otlpInterval,
+					},
+					owningRegistry,
+				);
+				state.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-watcher.ts");
+	state.heartbeatWatcher = new HeartbeatWatcher({
+		cwd: ctx.cwd,
+		pollIntervalMs: config.observability?.pollIntervalMs ?? 5000,
+		manifestCache: deps.getManifestCache(ctx.cwd),
+		registry: state.metricRegistry,
+		router: {
+			enqueue: (notification) => {
+				deps.notifyOperator(notification);
+				return true;
+			},
+		},
+		deadletterTickThreshold: config.reliability?.deadletterThreshold ?? 3,
+		onDeadletterTrigger: (manifest, taskId) => {
+			deps.appendDeadletter(manifest, {
+				taskId,
+				runId: manifest.runId,
+				reason: "heartbeat-dead",
+				attempts: 0,
+				timestamp: new Date().toISOString(),
+			});
+			state.metricRegistry?.counter("crew.task.deadletter_total", "Deadletter triggers by reason").inc({ reason: "heartbeat-dead" });
+			deps.pi.events?.emit?.("crew.task.deadletter", {
+				runId: manifest.runId,
+				taskId,
+				reason: "heartbeat-dead",
+			});
+		},
+	});
+	state.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));
+			} catch (error) {
+				logInternalError("register.autoRepair.turnHook", error);
+			}
+		});
+	} catch {
+		/* older Pi without before_agent_start — rely on the interval alone */
+	}
+
+	// Auto-repair timers: stale-run reconcile + orphan-temp cleanup.
+	// RT-F2: default raised from 60_000ms to 5 minutes (300_000ms). The previous
+	// 60s default was wasted work for idle sessions (Pi never had a UI to render
+	// between user turns), and .unref() meant it never fired at all when the
+	// event loop was idle. 5min balances "catch up after idle gap" against
+	// "don't waste cycles on sessions that aren't doing anything". The
+	// before_agent_start hook above covers the user-active case.
+	const autoRepairIntervalMs = config.reliability?.autoRepairIntervalMs ?? 300_000;
+	if (autoRepairIntervalMs > 0) {
+		state.autoRepairTimer = setInterval(() => {
+			if (deps.isCleanedUp()) return;
+			try {
+				const staleResults = deps.reconcileStaleRuns(ctx.cwd, deps.getManifestCache(ctx.cwd));
+				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 ?? "",
+							});
+						}
+					}
+				}
+			} catch (error) {
+				logInternalError("register.autoRepair", error);
+			}
+		}, autoRepairIntervalMs);
+		state.autoRepairTimer.unref();
+
+		// Less frequent (5x interval) — clean orphan temp dirs.
+		state.tempReconcileTimer = setInterval(() => {
+			if (deps.isCleanedUp()) return;
+			try {
+				deps.reconcileOrphanedTempWorkspaces(Date.now(), {
+					cleanupOrphanedTempDirs:
+						typeof config.reliability?.cleanupOrphanedTempDirs === "boolean"
+							? config.reliability.cleanupOrphanedTempDirs
+							: undefined,
+				});
+				const orphanResult = deps.cleanupOrphanTempDirs();
+				if (orphanResult.cleaned > 0) {
+					deps.notifyOperator({
+						id: `layer4_temp_cleanup_${Date.now()}`,
+						severity: "info",
+						source: "temp-cleanup",
+						title: `Layer 4: cleaned ${orphanResult.cleaned} orphan temp dir(s)`,
+						body: `~/.pi/agent/pi-crew/tmp/ orphans older than 24h removed (scanned ${orphanResult.scanned}, failed ${orphanResult.failed}).`,
+					});
+				}
+				const legacyResult = deps.cleanupLegacyOrphanTempDirs();
+				if (legacyResult.cleaned > 0) {
+					deps.notifyOperator({
+						id: `layer5_legacy_temp_cleanup_${Date.now()}`,
+						severity: "info",
+						source: "temp-cleanup",
+						title: `Layer 5: cleaned ${legacyResult.cleaned} legacy /tmp/pi-crew-* orphan(s)`,
+						body: `Pre-fix /tmp/pi-crew-* prompt/task orphans (no .crew/state/runs/, >24h) removed (scanned ${legacyResult.scanned}, failed ${legacyResult.failed}).`,
+					});
+				}
+			} catch (error) {
+				logInternalError("register.tempAutoRepair", error);
+			}
+		}, autoRepairIntervalMs * 5);
+		state.tempReconcileTimer.unref();
+	}
+
+	// autoRecover → on session_start, lazy-import crash-recovery and prompt the
+	// operator about interrupted runs. Defers to a microtask so it never blocks
+	// session_start.
+	if (config.reliability?.autoRecover === true) {
+		const cwdSnapshot = ctx.cwd;
+		const cacheSnapshot = deps.getManifestCache(cwdSnapshot);
+		void deps
+			.importCrashRecovery()
+			.then(({ detectInterruptedRuns }) => {
+				if (deps.isCleanedUp()) return;
+				for (const plan of detectInterruptedRuns(cwdSnapshot, cacheSnapshot)) {
+					deps.notifyOperator({
+						id: `recovery_prompt_${plan.runId}`,
+						severity: "warning",
+						source: "crash-recovery",
+						runId: plan.runId,
+						title: `Run ${plan.runId} was interrupted`,
+						body: `${plan.resumableTasks.length} tasks pending recovery. Open dashboard to inspect before resuming.`,
+					});
+				}
+			})
+			.catch((error: unknown) => logInternalError("register.crash-recovery-lazy-import", error));
+	}
+}
+
+/**
+ * Dispose all observability resources. Safe to call when state is already
+ * partially or fully disposed. Caller passes `isCleanedUp` so timers can be
+ * gated by the orchestrator's overall cleanup state.
+ */
+export async function disposeObservability(state: ObservabilityState, _isCleanedUp: boolean): Promise<void> {
+	state.heartbeatWatcher?.dispose();
+	state.heartbeatWatcher = undefined;
+	if (state.autoRepairTimer) {
+		clearInterval(state.autoRepairTimer);
+		state.autoRepairTimer = undefined;
+	}
+	if (state.tempReconcileTimer) {
+		clearInterval(state.tempReconcileTimer);
+		state.tempReconcileTimer = undefined;
+	}
+	state.metricSink?.dispose();
+	state.metricSink = undefined;
+	state.eventMetricSub?.dispose();
+	state.eventMetricSub = undefined;
+	// OBS-3: await OTLPExporter.dispose() so an in-flight HTTP push isn't cut short on
+	// shutdown (interface contract changed to Promise<void>; OTLPExporter awaits its
+	// in-flight push). The async work still completes even when callers discard the
+	// returned promise (fire-and-forget cleanup), because Node keeps the event loop
+	// alive for pending I/O.
+	await state.otlpExporter?.dispose();
+	state.otlpExporter = undefined;
+	state.metricRegistry?.dispose();
+	state.metricRegistry = undefined;
+}