@os-eco/overstory-cli 0.9.4 → 0.10.3

package/src/doctor/consistency.ts

@@ -212,7 +212,9 @@ export async function checkConsistency(
 
 	// 8. Check for SessionStore entries with missing tmux sessions
 	const existingTmuxNames = new Set(tmuxSessions.map((s) => s.name));
-	const missingTmux = liveSessions.filter((s) => !existingTmuxNames.has(s.tmuxSession));
+	const missingTmux = liveSessions.filter(
+		(s) => s.tmuxSession.length > 0 && !existingTmuxNames.has(s.tmuxSession),
+	);
 
 	if (missingTmux.length > 0) {
 		checks.push({
@@ -232,6 +234,51 @@ export async function checkConsistency(
 		});
 	}
 
+	// 8b. Check for orphaned claude spawn PIDs (overstory-505d).
+	//
+	// An orphan is a session whose pid is still alive but should not be:
+	//   - the session reached a terminal state (completed/zombie) yet the
+	//     spawn didn't exit, or
+	//   - the tmux container is gone but the claude child survived (was
+	//     reparented to init when its bash wrapper got SIGHUP).
+	// Run `ov clean --all` to reap. Distinct from `dead-pids` (the inverse:
+	// session is live but its pid already died).
+	const orphanedSpawns: Array<{ session: AgentSession; reason: string }> = [];
+	for (const s of storeSessions) {
+		if (s.pid === null || !isProcessAliveFn(s.pid)) continue;
+		if (s.state === "completed" || s.state === "zombie") {
+			orphanedSpawns.push({
+				session: s,
+				reason: `state=${s.state} but pid ${s.pid} still alive`,
+			});
+			continue;
+		}
+		if (s.tmuxSession.length > 0 && !existingTmuxNames.has(s.tmuxSession)) {
+			orphanedSpawns.push({
+				session: s,
+				reason: `tmux session "${s.tmuxSession}" missing but pid ${s.pid} alive`,
+			});
+		}
+	}
+
+	if (orphanedSpawns.length > 0) {
+		checks.push({
+			name: "orphan-spawns",
+			category: "consistency",
+			status: "warn",
+			message: `Found ${orphanedSpawns.length} orphaned spawn process(es) — run "ov clean --all" to reap`,
+			details: orphanedSpawns.map(({ session, reason }) => `${session.agentName}: ${reason}`),
+			fixable: true,
+		});
+	} else {
+		checks.push({
+			name: "orphan-spawns",
+			category: "consistency",
+			status: "pass",
+			message: "No orphaned spawn processes detected",
+		});
+	}
+
 	// 9. Check reviewer-to-builder ratio per lead
 	const parentGroups = new Map<string, { builders: number; reviewers: number }>();
 	for (const session of storeSessions) {

package/src/doctor/serve.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { OverstoryConfig } from "../types.ts";
+import { checkServe } from "./serve.ts";
+
+describe("checkServe", () => {
+	let tempDir: string;
+	let mockConfig: OverstoryConfig;
+
+	beforeEach(() => {
+		tempDir = mkdtempSync(join(tmpdir(), "overstory-serve-doctor-test-"));
+		mockConfig = {
+			project: { name: "test", root: tempDir, canonicalBranch: "main" },
+			agents: {
+				manifestPath: "",
+				baseDir: "",
+				maxConcurrent: 5,
+				staggerDelayMs: 100,
+				maxDepth: 2,
+				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
+			},
+			worktrees: { baseDir: "" },
+			taskTracker: { backend: "auto", enabled: true },
+			mulch: { enabled: true, domains: [], primeFormat: "markdown" },
+			merge: { aiResolveEnabled: false, reimagineEnabled: false },
+			providers: {
+				anthropic: { type: "native" },
+			},
+			watchdog: {
+				tier0Enabled: false,
+				tier0IntervalMs: 30000,
+				tier1Enabled: false,
+				tier2Enabled: false,
+				staleThresholdMs: 300000,
+				zombieThresholdMs: 600000,
+				nudgeIntervalMs: 60000,
+			},
+			models: {},
+			logging: { verbose: false, redactSecrets: true },
+		};
+	});
+
+	afterEach(() => {
+		rmSync(tempDir, { recursive: true, force: true });
+	});
+
+	test("ui/dist missing — returns warn about missing build", async () => {
+		const checks = await checkServe(mockConfig, tempDir);
+		const distCheck = checks.find((c) => c.name === "serve ui/dist");
+
+		expect(distCheck).toBeDefined();
+		expect(distCheck?.status).toBe("warn");
+		expect(distCheck?.message).toContain("ui/dist not found");
+		expect(distCheck?.details?.some((d) => d.includes("ui/dist"))).toBe(true);
+	});
+
+	test("ui/dist exists but index.html missing — returns warn about incomplete build", async () => {
+		mkdirSync(join(tempDir, "ui", "dist"), { recursive: true });
+		const checks = await checkServe(mockConfig, tempDir);
+		const distCheck = checks.find((c) => c.name === "serve ui/dist");
+
+		expect(distCheck).toBeDefined();
+		expect(distCheck?.status).toBe("warn");
+		expect(distCheck?.message).toContain("index.html is missing");
+	});
+
+	test("ui/dist with index.html — returns pass", async () => {
+		mkdirSync(join(tempDir, "ui", "dist"), { recursive: true });
+		writeFileSync(join(tempDir, "ui", "dist", "index.html"), "<html></html>");
+		const checks = await checkServe(mockConfig, tempDir);
+		const distCheck = checks.find((c) => c.name === "serve ui/dist");
+
+		expect(distCheck).toBeDefined();
+		expect(distCheck?.status).toBe("pass");
+		expect(distCheck?.message).toContain("index.html");
+	});
+
+	test("port check included in results", async () => {
+		const checks = await checkServe(mockConfig, tempDir);
+		const portCheck = checks.find((c) => c.name === "serve port");
+
+		expect(portCheck).toBeDefined();
+		// Server not running — should warn (or pass if something happens to be on the default port)
+		expect(portCheck?.status === "warn" || portCheck?.status === "pass").toBe(true);
+	});
+
+	test("returns exactly 2 checks (ui/dist + port)", async () => {
+		const checks = await checkServe(mockConfig, tempDir);
+		expect(checks).toHaveLength(2);
+		expect(checks.map((c) => c.category).every((cat) => cat === "serve")).toBe(true);
+	});
+});

package/src/doctor/serve.ts

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_SERVE_PORT } from "../commands/serve.ts";
+import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
+
+/**
+ * ov serve subsystem health checks.
+ * Validates ui/dist build output and port reachability.
+ */
+export const checkServe: DoctorCheckFn = async (config, _overstoryDir): Promise<DoctorCheck[]> => {
+	const checks: DoctorCheck[] = [];
+
+	// Check 1: ui/dist directory exists (only relevant if a UI has been built)
+	const uiDistPath = join(config.project.root, "ui", "dist");
+	const uiDistExists = existsSync(uiDistPath);
+	const indexHtmlExists = uiDistExists && existsSync(join(uiDistPath, "index.html"));
+
+	if (!uiDistExists) {
+		checks.push({
+			name: "serve ui/dist",
+			category: "serve",
+			status: "warn",
+			message: "ui/dist not found — run the UI build before starting ov serve",
+			details: [`Expected: ${uiDistPath}`],
+		});
+	} else if (!indexHtmlExists) {
+		checks.push({
+			name: "serve ui/dist",
+			category: "serve",
+			status: "warn",
+			message: "ui/dist exists but index.html is missing — UI build may be incomplete",
+			details: [`Expected: ${join(uiDistPath, "index.html")}`],
+		});
+	} else {
+		checks.push({
+			name: "serve ui/dist",
+			category: "serve",
+			status: "pass",
+			message: "ui/dist is present with index.html",
+		});
+	}
+
+	// Check 2: default port reachability (non-blocking probe)
+	const port = DEFAULT_SERVE_PORT;
+	const host = "127.0.0.1";
+	const reachable = await probePort(host, port);
+	if (reachable) {
+		checks.push({
+			name: "serve port",
+			category: "serve",
+			status: "pass",
+			message: `ov serve is reachable on ${host}:${port}`,
+		});
+	} else {
+		checks.push({
+			name: "serve port",
+			category: "serve",
+			status: "warn",
+			message: `ov serve is not running on ${host}:${port}`,
+			details: [`Start with: ov serve --port ${port}`],
+		});
+	}
+
+	return checks;
+};
+
+/**
+ * Probe whether a TCP port is open by attempting an HTTP connection.
+ * Returns true if the server responds, false on any error.
+ */
+async function probePort(host: string, port: number): Promise<boolean> {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 1000);
+		try {
+			const res = await fetch(`http://${host}:${port}/healthz`, {
+				signal: controller.signal,
+			});
+			return res.ok || res.status < 500;
+		} finally {
+			clearTimeout(timeout);
+		}
+	} catch {
+		return false;
+	}
+}

package/src/doctor/types.ts

@@ -15,7 +15,8 @@ export type DoctorCategory =
 	| "version"
 	| "ecosystem"
 	| "providers"
-	| "watchdog";
+	| "watchdog"
+	| "serve";
 
 /** Result of a single doctor health check. */
 export interface DoctorCheck {

package/src/doctor/watchdog.ts

@@ -3,6 +3,7 @@ import { stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { getRuntime } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
+import { findRunningWatchdogProcesses } from "../utils/process-scan.ts";
 import { isProcessRunning } from "../watchdog/health.ts";
 import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
 
@@ -134,7 +135,62 @@ export const checkWatchdog: DoctorCheckFn = async (
 		}
 	}
 
-	// Check 6: Tier 1 triage available if tier1Enabled
+	// Check 6: multi-daemon detection (overstory-8ef6).
+	// Earlier releases had no exclusion lock, so multiple `ov watch` daemons
+	// could run simultaneously. We scan the process table for `ov watch`
+	// processes and flag any case with more than one. This is observational —
+	// even with the lock now in place, a corrupted/missing PID file could
+	// still let a foreign daemon slip past, and we want doctor to catch it.
+	try {
+		const watchProcs = await findRunningWatchdogProcesses();
+		if (watchProcs.length > 1) {
+			const lockOwner = existsSync(pidFilePath)
+				? Number.parseInt((await Bun.file(pidFilePath).text()).trim(), 10)
+				: Number.NaN;
+			const lockOwnerLabel = Number.isFinite(lockOwner) ? `${lockOwner}` : "(none)";
+			const pidList = watchProcs.map((p) => p.pid).join(", ");
+			checks.push({
+				name: "watchdog multi-daemon",
+				category: "watchdog",
+				status: "fail",
+				message: `${watchProcs.length} 'ov watch' daemons running concurrently — only one should be live`,
+				details: [
+					`Live PIDs: ${pidList}`,
+					`PID-file owner: ${lockOwnerLabel}`,
+					"Run 'ov watch --kill-others' to terminate the foreign daemons.",
+				],
+				fixable: true,
+				fix: async () => {
+					const ownerPid = Number.isFinite(lockOwner) ? lockOwner : null;
+					const messages: string[] = [];
+					for (const proc of watchProcs) {
+						if (proc.pid === ownerPid) continue;
+						try {
+							process.kill(proc.pid, "SIGTERM");
+							messages.push(`Killed foreign watchdog PID ${proc.pid}`);
+						} catch {
+							messages.push(`PID ${proc.pid} already gone`);
+						}
+					}
+					if (messages.length === 0) {
+						messages.push("No foreign watchdogs to kill — fix is a no-op");
+					}
+					return messages;
+				},
+			});
+		}
+	} catch {
+		// Process scan failure is non-fatal — leave a soft warning instead of
+		// failing the whole doctor run.
+		checks.push({
+			name: "watchdog multi-daemon",
+			category: "watchdog",
+			status: "warn",
+			message: "Could not scan process table for foreign 'ov watch' daemons",
+		});
+	}
+
+	// Check 7: Tier 1 triage available if tier1Enabled
 	if (config.watchdog.tier1Enabled) {
 		try {
 			getRuntime(config?.runtime?.printCommand ?? config?.runtime?.default, config);

package/src/events/tailer.test.ts

@@ -13,8 +13,9 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createSessionStore, type SessionStore } from "../sessions/store.ts";
 import { cleanupTempDir } from "../test-helpers.ts";
-import type { EventStore } from "../types.ts";
+import type { AgentSession, EventStore } from "../types.ts";
 import { createEventStore } from "./store.ts";
 import type { TailerHandle, TailerOptions } from "./tailer.ts";
 import { findLatestStdoutLog, startEventTailer } from "./tailer.ts";
@@ -484,3 +485,235 @@ describe("daemon tailer integration", () => {
 		await cleanupTempDir(tmpDir);
 	});
 });
+
+// === session_id capture (overstory-7b8c Phase 1) ===
+
+describe("startEventTailer session_id capture", () => {
+	let tmpDir: string;
+	let eventStore: EventStore;
+	let eventsDbPath: string;
+	let sessionStore: SessionStore;
+	let sessionsDbPath: string;
+
+	function makeSession(agentName: string): AgentSession {
+		const now = new Date().toISOString();
+		return {
+			id: `id-${agentName}`,
+			agentName,
+			capability: "builder",
+			worktreePath: "/tmp/wt",
+			branchName: "test-branch",
+			taskId: "task-1",
+			tmuxSession: "",
+			state: "working",
+			pid: 12345,
+			parentAgent: null,
+			depth: 0,
+			runId: null,
+			startedAt: now,
+			lastActivity: now,
+			escalationLevel: 0,
+			stalledSince: null,
+			transcriptPath: null,
+		};
+	}
+
+	beforeEach(async () => {
+		tmpDir = await createTempDir();
+		eventsDbPath = join(tmpDir, "events.db");
+		eventStore = createEventStore(eventsDbPath);
+		sessionsDbPath = join(tmpDir, "sessions.db");
+		sessionStore = createSessionStore(sessionsDbPath);
+	});
+
+	afterEach(async () => {
+		eventStore.close();
+		sessionStore.close();
+		await cleanupTempDir(tmpDir);
+	});
+
+	test("parses system event session_id and calls updateClaudeSessionId once", async () => {
+		const agentName = "agent-sid-1";
+		sessionStore.upsert(makeSession(agentName));
+		const logPath = await createAgentLogDir(tmpDir, agentName);
+
+		const sysLine = JSON.stringify({
+			type: "system",
+			subtype: "init",
+			session_id: "sess-first-pin",
+			timestamp: new Date().toISOString(),
+		});
+		await writeFile(logPath, `${sysLine}\n`);
+
+		const handle = startEventTailer({
+			stdoutLogPath: logPath,
+			agentName,
+			runId: null,
+			eventsDbPath,
+			pollIntervalMs: 50,
+			_eventStore: eventStore,
+			_sessionStore: sessionStore,
+		});
+
+		try {
+			await waitFor(() => sessionStore.getByName(agentName)?.claudeSessionId === "sess-first-pin");
+			expect(sessionStore.getByName(agentName)?.claudeSessionId).toBe("sess-first-pin");
+		} finally {
+			handle.stop();
+		}
+	});
+
+	test("ignores subsequent system events with the same session_id (single-fire)", async () => {
+		const agentName = "agent-sid-2";
+		sessionStore.upsert(makeSession(agentName));
+		const logPath = await createAgentLogDir(tmpDir, agentName);
+
+		// Three system events all carrying the same session_id.
+		const lines = [
+			JSON.stringify({
+				type: "system",
+				subtype: "init",
+				session_id: "sess-stable",
+				timestamp: new Date().toISOString(),
+			}),
+			JSON.stringify({
+				type: "system",
+				subtype: "ping",
+				session_id: "sess-stable",
+				timestamp: new Date().toISOString(),
+			}),
+			JSON.stringify({
+				type: "system",
+				subtype: "ping",
+				session_id: "sess-stable",
+				timestamp: new Date().toISOString(),
+			}),
+		].join("\n");
+		await writeFile(logPath, `${lines}\n`);
+
+		// Wrap the SessionStore so we can count update calls without altering behaviour.
+		let updateCalls = 0;
+		const proxy: SessionStore = {
+			...sessionStore,
+			upsert: (s) => sessionStore.upsert(s),
+			getByName: (n) => sessionStore.getByName(n),
+			getActive: () => sessionStore.getActive(),
+			getAll: () => sessionStore.getAll(),
+			count: () => sessionStore.count(),
+			getByRun: (r) => sessionStore.getByRun(r),
+			updateState: (n, s) => sessionStore.updateState(n, s),
+			updateLastActivity: (n) => sessionStore.updateLastActivity(n),
+			updateEscalation: (n, l, s) => sessionStore.updateEscalation(n, l, s),
+			updateTranscriptPath: (n, p) => sessionStore.updateTranscriptPath(n, p),
+			updateClaudeSessionId: (n, s) => {
+				updateCalls++;
+				sessionStore.updateClaudeSessionId(n, s);
+			},
+			remove: (n) => sessionStore.remove(n),
+			purge: (o) => sessionStore.purge(o),
+			close: () => {
+				/* owned by outer test */
+			},
+		};
+
+		const handle = startEventTailer({
+			stdoutLogPath: logPath,
+			agentName,
+			runId: null,
+			eventsDbPath,
+			pollIntervalMs: 50,
+			_eventStore: eventStore,
+			_sessionStore: proxy,
+		});
+
+		try {
+			// Wait until events.db has all three lines processed.
+			await waitFor(() => eventStore.getByAgent(agentName).length >= 3);
+			// Allow extra poll cycles to confirm no late updates sneak in.
+			await new Promise((resolve) => setTimeout(resolve, 150));
+			expect(updateCalls).toBe(1);
+			expect(sessionStore.getByName(agentName)?.claudeSessionId).toBe("sess-stable");
+		} finally {
+			handle.stop();
+		}
+	});
+
+	test("detects resume mismatch and invokes _onResumeMismatch DI hook (observed wins)", async () => {
+		const agentName = "agent-sid-3";
+		const session = makeSession(agentName);
+		session.claudeSessionId = "sess-requested-OLD";
+		sessionStore.upsert(session);
+		const logPath = await createAgentLogDir(tmpDir, agentName);
+
+		const sysLine = JSON.stringify({
+			type: "system",
+			subtype: "init",
+			session_id: "sess-observed-NEW",
+			timestamp: new Date().toISOString(),
+		});
+		await writeFile(logPath, `${sysLine}\n`);
+
+		const mismatches: Array<{ agent: string; requested: string; observed: string }> = [];
+		const handle = startEventTailer({
+			stdoutLogPath: logPath,
+			agentName,
+			runId: null,
+			eventsDbPath,
+			pollIntervalMs: 50,
+			_eventStore: eventStore,
+			_sessionStore: sessionStore,
+			_onResumeMismatch: (agent, requested, observed) =>
+				mismatches.push({ agent, requested, observed }),
+		});
+
+		try {
+			await waitFor(
+				() => sessionStore.getByName(agentName)?.claudeSessionId === "sess-observed-NEW",
+			);
+			expect(mismatches).toHaveLength(1);
+			expect(mismatches[0]).toEqual({
+				agent: agentName,
+				requested: "sess-requested-OLD",
+				observed: "sess-observed-NEW",
+			});
+			// observed wins — SessionStore is overwritten with the new id.
+			expect(sessionStore.getByName(agentName)?.claudeSessionId).toBe("sess-observed-NEW");
+		} finally {
+			handle.stop();
+		}
+	});
+
+	test("backward compat: tailer with no sessionsDbPath performs no SessionStore writes", async () => {
+		const agentName = "agent-sid-4";
+		sessionStore.upsert(makeSession(agentName));
+		const logPath = await createAgentLogDir(tmpDir, agentName);
+
+		const sysLine = JSON.stringify({
+			type: "system",
+			subtype: "init",
+			session_id: "sess-should-not-pin",
+			timestamp: new Date().toISOString(),
+		});
+		await writeFile(logPath, `${sysLine}\n`);
+
+		// No sessionsDbPath, no _sessionStore — tailer must still process events.
+		const handle = startEventTailer({
+			stdoutLogPath: logPath,
+			agentName,
+			runId: null,
+			eventsDbPath,
+			pollIntervalMs: 50,
+			_eventStore: eventStore,
+		});
+
+		try {
+			await waitFor(() => eventStore.getByAgent(agentName).length >= 1);
+			// Give the tailer extra time to confirm no late writes occur.
+			await new Promise((resolve) => setTimeout(resolve, 150));
+			// SessionStore must remain untouched.
+			expect(sessionStore.getByName(agentName)?.claudeSessionId ?? null).toBeNull();
+		} finally {
+			handle.stop();
+		}
+	});
+});

package/src/events/tailer.ts

@@ -14,6 +14,7 @@
 
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
+import { createSessionStore, type SessionStore } from "../sessions/store.ts";
 import type { EventStore, EventType } from "../types.ts";
 import { createEventStore } from "./store.ts";
 
@@ -66,10 +67,26 @@ export interface TailerOptions {
 	runId: string | null;
 	/** Absolute path to events.db. The tailer opens its own connection. */
 	eventsDbPath: string;
+	/**
+	 * Absolute path to sessions.db. When present and not equal to ":memory:",
+	 * the tailer opens a dedicated SessionStore to persist the runtime-provided
+	 * session_id (e.g. Claude stream-json `session_id`). Omit (or set to
+	 * ":memory:") for tailers that should not write to SessionStore.
+	 */
+	sessionsDbPath?: string;
 	/** Poll interval in milliseconds (default: 500). */
 	pollIntervalMs?: number;
 	/** DI: injected EventStore for testing (overrides eventsDbPath). */
 	_eventStore?: EventStore;
+	/** DI: injected SessionStore for testing (overrides sessionsDbPath). */
+	_sessionStore?: SessionStore;
+	/**
+	 * DI: invoked exactly once per tailer when an observed session_id differs
+	 * from the prior claudeSessionId stored in SessionStore. Receives the agent
+	 * name, the prior (requested) id, and the newly observed id. Production
+	 * code logs a warning to stderr instead.
+	 */
+	_onResumeMismatch?: (agentName: string, requested: string, observed: string) => void;
 }
 
 /**
@@ -109,6 +126,28 @@ export function startEventTailer(opts: TailerOptions): TailerHandle {
 		}
 	}
 
+	// Open a dedicated SessionStore for this tailer's lifetime when a real
+	// sessionsDbPath is provided. Tailers that omit sessionsDbPath (or pass
+	// ":memory:") skip session_id persistence entirely — backward compat for
+	// callers that don't yet route through the watchdog wiring.
+	let sessionStore: SessionStore | null = opts._sessionStore ?? null;
+	let ownedSessionStore = false;
+	if (!sessionStore && opts.sessionsDbPath && opts.sessionsDbPath !== ":memory:") {
+		try {
+			sessionStore = createSessionStore(opts.sessionsDbPath);
+			ownedSessionStore = true;
+		} catch {
+			// SessionStore failure is non-fatal — events still flow.
+			sessionStore = null;
+		}
+	}
+
+	// Single-fire guard for session_id pinning. Mirrors claude.ts:312
+	// `sessionIdPinned` so that updateClaudeSessionId is called at most once
+	// per tailer lifetime, even if many system events stream by.
+	let sessionIdPinned = false;
+	const onResumeMismatch = opts._onResumeMismatch;
+
 	let stopped = false;
 	let byteOffset = 0;
 	let timer: ReturnType<typeof setTimeout> | null = null;
@@ -154,6 +193,48 @@ export function startEventTailer(opts: TailerOptions): TailerHandle {
 
 					const toolDurationMs = typeof event.duration_ms === "number" ? event.duration_ms : null;
 
+					// Extract session_id from stream-json system events (e.g. Claude Code
+					// emits `{type:"system", subtype:"init", session_id:"sess-..."}` on
+					// every spawn — including --resume spawns, which assign a fresh id).
+					// The "result" event also carries session_id; treat both as authoritative.
+					// Single-fire per tailer lifetime so we don't churn writes.
+					if (!sessionIdPinned && sessionStore !== null) {
+						const sid =
+							typeof event.session_id === "string" && event.session_id.length > 0
+								? event.session_id
+								: null;
+						if (sid !== null && (type === "system" || type === "result")) {
+							sessionIdPinned = true;
+							let prior: string | null = null;
+							try {
+								prior = sessionStore.getByName(agentName)?.claudeSessionId ?? null;
+							} catch {
+								prior = null;
+							}
+							try {
+								sessionStore.updateClaudeSessionId(agentName, sid);
+							} catch {
+								// Non-fatal: SessionStore write failure must not break tailing.
+							}
+							// Resume mismatch: requested != observed. The observed id wins
+							// (claude assigns fresh ids on --resume), but operators need to
+							// know — log a warning, and call DI hook for tests.
+							if (prior !== null && prior !== sid) {
+								if (onResumeMismatch) {
+									try {
+										onResumeMismatch(agentName, prior, sid);
+									} catch {
+										// DI hook errors must not crash the tailer.
+									}
+								} else {
+									process.stderr.write(
+										`[tailer] resume mismatch for ${agentName}: requested=${prior} observed=${sid}\n`,
+									);
+								}
+							}
+						}
+					}
+
 					try {
 						eventStore?.insert({
 							runId,
@@ -201,6 +282,15 @@ export function startEventTailer(opts: TailerOptions): TailerHandle {
 				}
 				eventStore = null;
 			}
+			// Close only the SessionStore this tailer owns.
+			if (ownedSessionStore && sessionStore) {
+				try {
+					sessionStore.close();
+				} catch {
+					// Non-fatal.
+				}
+				sessionStore = null;
+			}
 		},
 	};
 }