@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/commands/mail.test.ts

@@ -118,6 +118,54 @@ describe("mailCommand", () => {
 			expect(output).toContain("Explore API");
 			expect(output).toContain("Total: 2 messages");
 		});
+
+		test("--type filters by message type", async () => {
+			// Add a typed message to the seeded inbox
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			client.send({
+				from: "lead-x",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready to merge",
+				type: "merge_ready",
+			});
+			client.close();
+
+			await mailCommand(["list", "--type", "merge_ready"]);
+			expect(output).toContain("merge_ready: t1");
+			expect(output).not.toContain("Build task");
+			expect(output).not.toContain("Explore API");
+			expect(output).toContain("Total: 1 message");
+		});
+
+		test("--type combined with --from filters by both", async () => {
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			client.send({
+				from: "lead-x",
+				to: "coordinator",
+				subject: "merge_ready: t1",
+				body: "ready",
+				type: "merge_ready",
+			});
+			client.send({
+				from: "lead-y",
+				to: "coordinator",
+				subject: "merge_ready: t2",
+				body: "ready",
+				type: "merge_ready",
+			});
+			client.close();
+
+			await mailCommand(["list", "--from", "lead-x", "--type", "merge_ready"]);
+			expect(output).toContain("merge_ready: t1");
+			expect(output).not.toContain("merge_ready: t2");
+		});
+
+		test("--type rejects invalid type with ValidationError", async () => {
+			await expect(mailCommand(["list", "--type", "bogus"])).rejects.toThrow(/Invalid --type/);
+		});
 	});
 
 	describe("reply", () => {
@@ -1274,6 +1322,120 @@ describe("mailCommand", () => {
 			expect(stderrOutput).toBe("");
 		});
 	});
+
+	describe("terminal-state recipient rejection (overstory-f5be)", () => {
+		async function seedRecipient(name: string, state: "working" | "completed" | "zombie") {
+			const { createSessionStore } = await import("../sessions/store.ts");
+			const sessionsDbPath = join(tempDir, ".overstory", "sessions.db");
+			const sessionStore = createSessionStore(sessionsDbPath);
+			sessionStore.upsert({
+				id: `session-${name}`,
+				agentName: name,
+				capability: "builder",
+				worktreePath: `/worktrees/${name}`,
+				branchName: name,
+				taskId: "bead-x",
+				tmuxSession: `overstory-test-${name}`,
+				state,
+				pid: 99999,
+				parentAgent: "orchestrator",
+				depth: 1,
+				runId: "run-001",
+				startedAt: new Date().toISOString(),
+				lastActivity: new Date().toISOString(),
+				escalationLevel: 0,
+				stalledSince: null,
+				transcriptPath: null,
+			});
+			sessionStore.close();
+		}
+
+		test("rejects send to recipient in completed state", async () => {
+			await seedRecipient("dead-builder", "completed");
+
+			let caught: unknown;
+			try {
+				await mailCommand([
+					"send",
+					"--to",
+					"dead-builder",
+					"--subject",
+					"Hello",
+					"--body",
+					"Are you there?",
+				]);
+			} catch (err) {
+				caught = err;
+			}
+
+			expect(caught).toBeDefined();
+			expect((caught as Error).name).toBe("MailError");
+			expect((caught as Error).message).toContain("dead-builder");
+			expect((caught as Error).message).toContain("completed");
+
+			// Confirm no message was inserted
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			const messages = client.list({ to: "dead-builder" });
+			expect(messages.length).toBe(0);
+			client.close();
+		});
+
+		test("rejects send to recipient in zombie state", async () => {
+			await seedRecipient("crashed-builder", "zombie");
+
+			let caught: unknown;
+			try {
+				await mailCommand([
+					"send",
+					"--to",
+					"crashed-builder",
+					"--subject",
+					"Status?",
+					"--body",
+					"Ping",
+				]);
+			} catch (err) {
+				caught = err;
+			}
+
+			expect(caught).toBeDefined();
+			expect((caught as Error).name).toBe("MailError");
+			expect((caught as Error).message).toContain("zombie");
+		});
+
+		test("allows send when recipient has no session row (e.g. orchestrator)", async () => {
+			// No session seeded for "orchestrator" — the existing beforeEach
+			// only inserts mail rows, not session rows.
+			await mailCommand([
+				"send",
+				"--to",
+				"orchestrator",
+				"--subject",
+				"Hello",
+				"--body",
+				"Top-level role",
+			]);
+
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			const messages = client.list({ to: "orchestrator" });
+			expect(messages.length).toBeGreaterThanOrEqual(1);
+			client.close();
+		});
+
+		test("allows send to active (working) recipient", async () => {
+			await seedRecipient("live-builder", "working");
+
+			await mailCommand(["send", "--to", "live-builder", "--subject", "Hello", "--body", "Active"]);
+
+			const store = createMailStore(join(tempDir, ".overstory", "mail.db"));
+			const client = createMailClient(store);
+			const messages = client.list({ to: "live-builder" });
+			expect(messages.length).toBe(1);
+			client.close();
+		});
+	});
 });
 
 describe("shouldAutoNudge", () => {

package/src/commands/mail.ts

@@ -7,9 +7,9 @@
  */
 
 import { join } from "node:path";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { resolveProjectRoot } from "../config.ts";
-import { ValidationError } from "../errors.ts";
+import { MailError, ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { jsonOutput } from "../json.ts";
 import { accent, printHint, printSuccess } from "../logging/color.ts";
@@ -253,6 +253,7 @@ interface ListOpts {
 	to?: string;
 	agent?: string;
 	unread?: boolean;
+	type?: string;
 	json?: boolean;
 }
 
@@ -405,6 +406,30 @@ async function handleSend(opts: SendOpts, cwd: string): Promise<void> {
 		}
 	}
 
+	// Reject sends to agents in a terminal state (completed/zombie).
+	// `installMailInjectors` reaps the per-agent dispatch loop the moment a
+	// session lands in a terminal state (serve.ts:378), so any mail addressed
+	// after that point would sit unread forever with no way to surface it.
+	// Sessions with no row at all (orchestrator, coordinator, operator roles)
+	// fall through — we only know about agents tracked in SessionStore.
+	// Group addresses already skip terminal agents via `getActive()`.
+	{
+		const overstoryDir = join(cwd, ".overstory");
+		const { store: sessionStore } = openSessionStore(overstoryDir);
+		try {
+			const recipient = sessionStore.getByName(to);
+			if (recipient && (recipient.state === "completed" || recipient.state === "zombie")) {
+				throw new MailError(
+					`Recipient "${to}" is in terminal state (${recipient.state}); message not sent. ` +
+						`The agent is no longer running, so this message would never be delivered.`,
+					{ agentName: to },
+				);
+			}
+		} finally {
+			sessionStore.close();
+		}
+	}
+
 	// Single-recipient message (existing logic)
 	const client = openClient(cwd);
 	try {
@@ -603,9 +628,20 @@ function handleList(opts: ListOpts, cwd: string): void {
 	const unread = opts.unread ? true : undefined;
 	const json = opts.json ?? false;
 
+	let type: MailMessageType | undefined;
+	if (opts.type !== undefined) {
+		if (!MAIL_MESSAGE_TYPES.includes(opts.type as MailMessageType)) {
+			throw new ValidationError(
+				`Invalid --type "${opts.type}". Must be one of: ${MAIL_MESSAGE_TYPES.join(", ")}`,
+				{ field: "type", value: opts.type },
+			);
+		}
+		type = opts.type as MailMessageType;
+	}
+
 	const client = openClient(cwd);
 	try {
-		const messages = client.list({ from, to, unread });
+		const messages = client.list({ from, to, unread, type });
 
 		if (json) {
 			jsonOutput("mail list", { messages });
@@ -732,8 +768,8 @@ export async function mailCommand(args: string[]): Promise<void> {
 
 	program
 		.command("check")
-		.description("Check inbox (unread messages)")
-		.option("--agent <name>", "Agent name")
+		.description("Check inbox for one agent and mark unread as read (per-agent scope)")
+		.option("--agent <name>", "Agent name (default: orchestrator)")
 		.option("--inject", "Inject format for hook context")
 		.option("--json", "Output as JSON")
 		.option("--debounce <ms>", "Debounce interval in milliseconds")
@@ -744,11 +780,12 @@ export async function mailCommand(args: string[]): Promise<void> {
 
 	program
 		.command("list")
-		.description("List messages with filters")
+		.description("List messages with filters (system-wide unless --to/--agent given)")
 		.option("--from <name>", "Filter by sender")
-		.option("--to <name>", "Filter by recipient")
+		.option("--to <name>", "Filter by recipient (scopes to one agent)")
 		.option("--agent <name>", "Alias for --to (filter by recipient)")
-		.option("--unread", "Show only unread messages")
+		.option("--unread", "Show only unread messages (does NOT mark them read)")
+		.option("--type <type>", "Filter by message type")
 		.option("--json", "Output as JSON")
 		.exitOverride()
 		.action((opts: ListOpts) => {
@@ -789,5 +826,23 @@ export async function mailCommand(args: string[]): Promise<void> {
 			handlePurge(opts, root);
 		});
 
-	await program.parseAsync(["node", "overstory-mail", ...args]);
+	try {
+		await program.parseAsync(["node", "overstory-mail", ...args]);
+	} catch (err) {
+		// `exitOverride()` turns Commander's help paths into thrown
+		// CommanderErrors after the help text was already written to stdout.
+		// Swallow both the explicit `--help` path (commander.helpDisplayed,
+		// exitCode 0) and the missing-subcommand path (commander.help,
+		// exitCode 1) — the user got what they asked for.
+		if (
+			err instanceof CommanderError &&
+			(err.code === "commander.helpDisplayed" || err.code === "commander.help")
+		) {
+			if (err.exitCode !== 0) {
+				process.exitCode = err.exitCode;
+			}
+			return;
+		}
+		throw err;
+	}
 }

package/src/commands/merge.test.ts

@@ -1,7 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { writeFileSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { ValidationError } from "../errors.ts";
+import { MergeError, ValidationError } from "../errors.ts";
+import { mergeLockPath } from "../merge/lock.ts";
 import { createMergeQueue } from "../merge/queue.ts";
 import {
 	cleanupTempDir,
@@ -597,6 +599,115 @@ merge:
 		});
 	});
 
+	describe("concurrent-merge lock", () => {
+		test("refuses to start when another live ov merge holds the lock for the same target", async () => {
+			await setupProject(repoDir, defaultBranch);
+			const branchName = "overstory/builder/bead-lock-1";
+			await createCleanFeatureBranch(repoDir, branchName);
+
+			// Simulate another live ov merge by writing a lock file with this
+			// process's own PID — it is guaranteed alive, so the lock-holder check
+			// must treat it as an in-flight merge.
+			const lockPath = mergeLockPath(join(repoDir, ".overstory"), defaultBranch);
+			writeFileSync(
+				lockPath,
+				JSON.stringify({
+					pid: process.pid,
+					acquiredAt: new Date().toISOString(),
+					targetBranch: defaultBranch,
+				}),
+			);
+
+			const originalWrite = process.stdout.write.bind(process.stdout);
+			process.stdout.write = (): boolean => true;
+
+			try {
+				await mergeCommand({ branch: branchName });
+				expect(true).toBe(false); // should not reach here
+			} catch (err: unknown) {
+				expect(err).toBeInstanceOf(MergeError);
+				const msg = (err as MergeError).message;
+				expect(msg).toContain("Another ov merge is already running");
+				expect(msg).toContain(defaultBranch);
+			} finally {
+				process.stdout.write = originalWrite;
+			}
+		});
+
+		test("releases the lock after a successful merge so a second run can proceed", async () => {
+			await setupProject(repoDir, defaultBranch);
+			const branchName = "overstory/builder/bead-lock-2";
+			await createCleanFeatureBranch(repoDir, branchName);
+
+			const originalWrite = process.stdout.write.bind(process.stdout);
+			process.stdout.write = (): boolean => true;
+
+			try {
+				await mergeCommand({ branch: branchName, json: true });
+			} finally {
+				process.stdout.write = originalWrite;
+			}
+
+			// After release, a fresh `ov merge --dry-run` for an unrelated branch
+			// (which doesn't take a lock) should still see no leftover lock file.
+			const lockPath = mergeLockPath(join(repoDir, ".overstory"), defaultBranch);
+			expect(await Bun.file(lockPath).exists()).toBe(false);
+		});
+
+		test("--dry-run does not acquire the lock", async () => {
+			await setupProject(repoDir, defaultBranch);
+			const branchName = "overstory/builder/bead-lock-dry";
+			await createCleanFeatureBranch(repoDir, branchName);
+
+			const originalWrite = process.stdout.write.bind(process.stdout);
+			process.stdout.write = (): boolean => true;
+
+			try {
+				await mergeCommand({ branch: branchName, dryRun: true, json: true });
+			} finally {
+				process.stdout.write = originalWrite;
+			}
+
+			const lockPath = mergeLockPath(join(repoDir, ".overstory"), defaultBranch);
+			expect(await Bun.file(lockPath).exists()).toBe(false);
+		});
+
+		test("steals a stale lock (dead PID) and proceeds", async () => {
+			await setupProject(repoDir, defaultBranch);
+			const branchName = "overstory/builder/bead-lock-stale";
+			await createCleanFeatureBranch(repoDir, branchName);
+
+			// PID 2147483647 (INT_MAX) is virtually never assigned — treat as dead.
+			const lockPath = mergeLockPath(join(repoDir, ".overstory"), defaultBranch);
+			writeFileSync(
+				lockPath,
+				JSON.stringify({
+					pid: 2147483647,
+					acquiredAt: new Date(Date.now() - 10 * 60_000).toISOString(),
+					targetBranch: defaultBranch,
+				}),
+			);
+
+			let output = "";
+			const originalWrite = process.stdout.write.bind(process.stdout);
+			process.stdout.write = (chunk: unknown): boolean => {
+				output += String(chunk);
+				return true;
+			};
+
+			try {
+				await mergeCommand({ branch: branchName, json: true });
+			} finally {
+				process.stdout.write = originalWrite;
+			}
+
+			const parsed = JSON.parse(output);
+			expect(parsed.success).toBe(true);
+			// Lock should be released after success.
+			expect(await Bun.file(lockPath).exists()).toBe(false);
+		});
+	});
+
 	describe("conflict handling", () => {
 		test("content conflict auto-resolves: same file modified on both branches, verify incoming content wins", async () => {
 			await setupProject(repoDir, defaultBranch);

package/src/commands/merge.ts

@@ -16,6 +16,7 @@ import { loadConfig } from "../config.ts";
 import { MergeError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { accent, printHint } from "../logging/color.ts";
+import { acquireMergeLock } from "../merge/lock.ts";
 import { createMergeQueue } from "../merge/queue.ts";
 import { createMergeResolver } from "../merge/resolver.ts";
 import { createMulchClient } from "../mulch/client.ts";
@@ -168,10 +169,22 @@ export async function mergeCommand(opts: MergeOptions): Promise<void> {
 		mulchClient,
 	});
 
-	if (branchName) {
-		await handleBranch(branchName, queue, resolver, config, targetBranch, dryRun, json);
-	} else {
-		await handleAll(queue, resolver, config, targetBranch, dryRun, json);
+	// Dry-run is read-only with respect to git state — no lock needed. The
+	// real merge path acquires a lock on the target branch so a parallel
+	// `ov merge` can't observe in-progress conflict markers and report a
+	// false failure (seeds: overstory-9610).
+	const lock = dryRun
+		? null
+		: acquireMergeLock(join(config.project.root, ".overstory"), targetBranch);
+
+	try {
+		if (branchName) {
+			await handleBranch(branchName, queue, resolver, config, targetBranch, dryRun, json);
+		} else {
+			await handleAll(queue, resolver, config, targetBranch, dryRun, json);
+		}
+	} finally {
+		lock?.release();
 	}
 }
 

package/src/commands/monitor.ts

@@ -29,6 +29,7 @@ import {
 	createSession,
 	isSessionAlive,
 	killSession,
+	sanitizeTmuxName,
 	sendKeys,
 	TMUX_SOCKET,
 } from "../worktree/tmux.ts";
@@ -42,7 +43,7 @@ const MONITOR_NAME = "monitor";
  * Includes the project name to prevent cross-project collisions (overstory-pcef).
  */
 function monitorTmuxSession(projectName: string): string {
-	return `overstory-${projectName}-${MONITOR_NAME}`;
+	return `overstory-${sanitizeTmuxName(projectName)}-${MONITOR_NAME}`;
 }
 
 /**