@os-eco/overstory-cli 0.9.3 → 0.10.3

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;
+			}
 		},
 	};
 }

package/src/index.ts

@@ -36,6 +36,7 @@ import { createOrchestratorCommand } from "./commands/orchestrator.ts";
 import { primeCommand } from "./commands/prime.ts";
 import { createReplayCommand } from "./commands/replay.ts";
 import { createRunCommand } from "./commands/run.ts";
+import { createServeCommand } from "./commands/serve.ts";
 import { slingCommand } from "./commands/sling.ts";
 import { specWriteCommand } from "./commands/spec.ts";
 import { createStatusCommand } from "./commands/status.ts";
@@ -51,7 +52,7 @@ import { ConfigError, OverstoryError, WorktreeError } from "./errors.ts";
 import { jsonError } from "./json.ts";
 import { brand, chalk, muted, setQuiet } from "./logging/color.ts";
 
-export const VERSION = "0.9.3";
+export const VERSION = "0.10.3";
 
 const rawArgs = process.argv.slice(2);
 
@@ -103,6 +104,7 @@ const COMMANDS = [
 	"run",
 	"costs",
 	"metrics",
+	"serve",
 	"update",
 	"upgrade",
 	"completions",
@@ -204,9 +206,12 @@ program
 		},
 	});
 
-// Apply global flags before any command action runs
-program.hook("preAction", (thisCmd) => {
-	const opts = thisCmd.optsWithGlobals();
+// Apply global flags before any command action runs.
+// `actionCommand` is the deepest command whose action is about to run (e.g.
+// `coordinator start`); reading `optsWithGlobals()` on it walks up through
+// every parent so subcommand-level `--project` flags are also seen.
+program.hook("preAction", (_thisCmd, actionCommand) => {
+	const opts = actionCommand.optsWithGlobals();
 	if (opts.quiet) {
 		setQuiet(true);
 	}
@@ -225,8 +230,9 @@ program.hook("preAction", (thisCmd) => {
 		timingStart = performance.now();
 	}
 });
-program.hook("postAction", () => {
-	if (program.opts().timing && timingStart !== undefined) {
+program.hook("postAction", (_thisCmd, actionCommand) => {
+	const opts = actionCommand.optsWithGlobals();
+	if (opts.timing && timingStart !== undefined) {
 		const elapsed = performance.now() - timingStart;
 		const formatted =
 			elapsed < 1000 ? `${Math.round(elapsed)}ms` : `${(elapsed / 1000).toFixed(2)}s`;
@@ -246,6 +252,7 @@ program.addCommand(createWorktreeCommand());
 program.addCommand(createLogCommand());
 program.addCommand(createWatchCommand());
 program.addCommand(createGroupCommand());
+program.addCommand(createServeCommand());
 program.addCommand(createCompletionsCommand());
 
 // Unmigrated commands — passthrough pattern
@@ -292,6 +299,14 @@ program
 	.option("--runtime <name>", "Runtime adapter (default: config or claude)")
 	.option("--base-branch <branch>", "Base branch for worktree creation (default: current HEAD)")
 	.option("--profile <name>", "Canopy profile to apply to agent overlay")
+	.option(
+		"--headless",
+		"Spawn through Bun.spawn (stream-json) instead of tmux. Requires runtime with buildDirectSpawn.",
+	)
+	.option(
+		"--recover",
+		"Allow dispatch against a task in any tracker status (e.g. closed). Use when a prior owner exited and the task needs a fresh agent.",
+	)
 	.option("--json", "Output result as JSON")
 	.action(async (taskId, opts) => {
 		await slingCommand(taskId, opts);
@@ -359,6 +374,7 @@ program
 program
 	.command("mail")
 	.description("Mail system (send/check/list/read/reply)")
+	.helpOption(false)
 	.allowUnknownOption()
 	.allowExcessArguments()
 	.action(async (_opts, cmd) => {
@@ -422,6 +438,37 @@ program.addCommand(createUpdateCommand());
 
 program.addCommand(createUpgradeCommand());
 
+// Propagate root-level globals to every (sub)command so they can appear before
+// or after the command name. With `enablePositionalOptions()`, options declared
+// on the root program are not accepted after a subcommand name; copying them
+// onto each command lets `ov status --project /path` work the same as
+// `ov --project /path status`. Skips the delegated `mail`/`nudge`/`logs`/`trace`
+// commands, which use `allowUnknownOption()` and forward args to an inner
+// Commander parser. The preAction hook reads `actionCommand.optsWithGlobals()`,
+// so it sees these regardless of which level they were parsed at.
+const DELEGATED_COMMANDS = new Set(["mail", "nudge", "logs", "trace"]);
+const PROPAGATED_GLOBALS: ReadonlyArray<readonly [string, string]> = [
+	["--project <path>", "Target project root (overrides auto-detection)"],
+	["-q, --quiet", "Suppress non-error output"],
+	["--timing", "Print command execution time to stderr"],
+];
+function propagateGlobalOptions(cmd: Command): void {
+	for (const sub of cmd.commands) {
+		if (sub === cmd) continue;
+		if (!DELEGATED_COMMANDS.has(sub.name())) {
+			for (const [flag, desc] of PROPAGATED_GLOBALS) {
+				const long = flag.split(/[\s,]+/).find((p) => p.startsWith("--"));
+				const alreadyDeclared = sub.options.some((o) => o.long === long);
+				if (!alreadyDeclared) {
+					sub.option(flag, desc);
+				}
+			}
+		}
+		propagateGlobalOptions(sub);
+	}
+}
+propagateGlobalOptions(program);
+
 // Handle unknown commands with Levenshtein fuzzy-match suggestions
 program.on("command:*", (operands) => {
 	const unknown = operands[0] ?? "";

package/src/json.ts

@@ -22,3 +22,32 @@ export function jsonOutput(command: string, data: Record<string, unknown>): void
 export function jsonError(command: string, error: string): void {
 	process.stdout.write(`${JSON.stringify({ success: false, command, error })}\n`);
 }
+
+/**
+ * Build a JSON success Response for HTTP API handlers.
+ * Envelope: { success: true, command: 'serve', data, nextCursor? }
+ */
+export function apiJson(
+	data: unknown,
+	init?: { status?: number; nextCursor?: string | null },
+): Response {
+	const envelope: Record<string, unknown> = { success: true, command: "serve", data };
+	if (init?.nextCursor != null) {
+		envelope.nextCursor = init.nextCursor;
+	}
+	return new Response(JSON.stringify(envelope), {
+		status: init?.status ?? 200,
+		headers: { "Content-Type": "application/json" },
+	});
+}
+
+/**
+ * Build a JSON error Response for HTTP API handlers.
+ * Envelope: { success: false, command: 'serve', error }
+ */
+export function apiError(message: string, status: number): Response {
+	return new Response(JSON.stringify({ success: false, command: "serve", error: message }), {
+		status,
+		headers: { "Content-Type": "application/json" },
+	});
+}

package/src/mail/client.ts

@@ -7,7 +7,7 @@
  */
 
 import { MailError } from "../errors.ts";
-import type { MailMessage, MailPayloadMap, MailProtocolType } from "../types.ts";
+import type { MailMessage, MailMessageType, MailPayloadMap, MailProtocolType } from "../types.ts";
 import type { MailStore } from "./store.ts";
 
 export interface MailClient {
@@ -42,7 +42,12 @@ export interface MailClient {
 	checkInject(agentName: string): string;
 
 	/** List messages with optional filters. */
-	list(filters?: { from?: string; to?: string; unread?: boolean }): MailMessage[];
+	list(filters?: {
+		from?: string;
+		to?: string;
+		unread?: boolean;
+		type?: MailMessageType;
+	}): MailMessage[];
 
 	/** Mark a message as read by ID. Returns whether the message was already read. */
 	markRead(id: string): { alreadyRead: boolean };
@@ -50,6 +55,9 @@ export interface MailClient {
 	/** Reply to a message. Returns the new message ID. */
 	reply(messageId: string, body: string, from: string): string;
 
+	/** Delete a single message by id. Returns true if a row was deleted. */
+	deleteById(id: string): boolean;
+
 	/** Close the underlying store. */
 	close(): void;
 }
@@ -75,6 +83,7 @@ export function parsePayload<T extends MailProtocolType>(
 /** Protocol types that represent structured coordination messages. */
 const PROTOCOL_TYPES = new Set<string>([
 	"worker_done",
+	"worker_died",
 	"merge_ready",
 	"merged",
 	"merge_failed",
@@ -187,6 +196,10 @@ export function createMailClient(store: MailStore): MailClient {
 			return { alreadyRead: false };
 		},
 
+		deleteById(id): boolean {
+			return store.deleteById(id);
+		},
+
 		reply(messageId, body, from): string {
 			const original = store.getById(messageId);
 			if (!original) {

package/src/mail/store.test.ts

@@ -437,6 +437,88 @@ describe("createMailStore", () => {
 			expect(filtered).toHaveLength(1);
 			expect(filtered[0]?.subject).toBe("msg1");
 		});
+
+		test("filters by type", () => {
+			store.insert({
+				id: "",
+				from: "lead-a",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready",
+				type: "merge_ready",
+				priority: "normal",
+				threadId: null,
+			});
+			store.insert({
+				id: "",
+				from: "builder-a",
+				to: "lead-a",
+				subject: "Worker done",
+				body: "done",
+				type: "worker_done",
+				priority: "normal",
+				threadId: null,
+			});
+			store.insert({
+				id: "",
+				from: "lead-a",
+				to: "coordinator",
+				subject: "status",
+				body: "still going",
+				type: "status",
+				priority: "normal",
+				threadId: null,
+			});
+
+			const mr = store.getAll({ type: "merge_ready" });
+			expect(mr).toHaveLength(1);
+			expect(mr[0]?.subject).toBe("merge_ready: t1");
+
+			const wd = store.getAll({ type: "worker_done" });
+			expect(wd).toHaveLength(1);
+			expect(wd[0]?.subject).toBe("Worker done");
+		});
+
+		test("combines type with from filter", () => {
+			store.insert({
+				id: "",
+				from: "lead-a",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready",
+				type: "merge_ready",
+				priority: "normal",
+				threadId: null,
+			});
+			store.insert({
+				id: "",
+				from: "lead-b",
+				to: "coordinator",
+				subject: "merge_ready: t2",
+				body: "ready",
+				type: "merge_ready",
+				priority: "normal",
+				threadId: null,
+			});
+
+			const mine = store.getAll({ from: "lead-a", type: "merge_ready" });
+			expect(mine).toHaveLength(1);
+			expect(mine[0]?.from).toBe("lead-a");
+		});
+
+		test("returns empty array when no rows match the type filter", () => {
+			store.insert({
+				id: "",
+				from: "agent-a",
+				to: "orchestrator",
+				subject: "msg",
+				body: "body",
+				type: "status",
+				priority: "normal",
+				threadId: null,
+			});
+			expect(store.getAll({ type: "merge_ready" })).toHaveLength(0);
+		});
 	});
 
 	describe("getByThread", () => {