@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/mail/store.ts

@@ -8,7 +8,7 @@
 
 import { Database } from "bun:sqlite";
 import { MailError } from "../errors.ts";
-import type { MailMessage } from "../types.ts";
+import type { MailMessage, MailMessageType } from "../types.ts";
 import { MAIL_MESSAGE_TYPES } from "../types.ts";
 
 export interface MailStore {
@@ -16,10 +16,18 @@ export interface MailStore {
 		message: Omit<MailMessage, "read" | "createdAt" | "payload"> & { payload?: string | null },
 	): MailMessage;
 	getUnread(agentName: string): MailMessage[];
-	getAll(filters?: { from?: string; to?: string; unread?: boolean; limit?: number }): MailMessage[];
+	getAll(filters?: {
+		from?: string;
+		to?: string;
+		unread?: boolean;
+		type?: MailMessageType;
+		limit?: number;
+	}): MailMessage[];
 	getById(id: string): MailMessage | null;
 	getByThread(threadId: string): MailMessage[];
 	markRead(id: string): void;
+	/** Delete a single message by id. Returns true if a row was deleted. */
+	deleteById(id: string): boolean;
 	/** Delete messages matching the given criteria. Returns the number of messages deleted. */
 	purge(options: { all?: boolean; olderThanMs?: number; agent?: string }): number;
 	close(): void;
@@ -84,14 +92,21 @@ function migrateSchema(db: Database): void {
 	const hasPayloadColumn = row.sql.includes("payload");
 	const hasProtocolTypes = row.sql.includes("worker_done");
 	const hasDecisionGate = row.sql.includes("decision_gate");
+	const hasWorkerDied = row.sql.includes("worker_died");
 
 	// If schema is fully up to date, nothing to do
-	if (hasCheckConstraints && hasPayloadColumn && hasProtocolTypes && hasDecisionGate) {
+	if (
+		hasCheckConstraints &&
+		hasPayloadColumn &&
+		hasProtocolTypes &&
+		hasDecisionGate &&
+		hasWorkerDied
+	) {
 		return;
 	}
 
 	// If only missing the payload column (has correct CHECK constraints), use ALTER TABLE
-	if (hasCheckConstraints && hasProtocolTypes && !hasPayloadColumn) {
+	if (hasCheckConstraints && hasProtocolTypes && hasWorkerDied && !hasPayloadColumn) {
 		db.exec("ALTER TABLE messages ADD COLUMN payload TEXT");
 		return;
 	}
@@ -232,11 +247,16 @@ export function createMailStore(dbPath: string): MailStore {
 		UPDATE messages SET read = 1 WHERE id = $id
 	`);
 
+	const deleteByIdStmt = db.prepare<void, { $id: string }>(`
+		DELETE FROM messages WHERE id = $id
+	`);
+
 	// Dynamic filter queries are built at call time since the WHERE clause varies
 	function buildFilterQuery(filters?: {
 		from?: string;
 		to?: string;
 		unread?: boolean;
+		type?: MailMessageType;
 		limit?: number;
 	}): MailMessage[] {
 		const conditions: string[] = [];
@@ -254,6 +274,10 @@ export function createMailStore(dbPath: string): MailStore {
 			conditions.push("read = $read");
 			params.$read = filters.unread ? 0 : 1;
 		}
+		if (filters?.type !== undefined) {
+			conditions.push("type = $type");
+			params.$type = filters.type;
+		}
 
 		const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 		const limitClause = filters?.limit !== undefined ? ` LIMIT $limit` : "";
@@ -315,6 +339,7 @@ export function createMailStore(dbPath: string): MailStore {
 			from?: string;
 			to?: string;
 			unread?: boolean;
+			type?: MailMessageType;
 			limit?: number;
 		}): MailMessage[] {
 			return buildFilterQuery(filters);
@@ -334,6 +359,18 @@ export function createMailStore(dbPath: string): MailStore {
 			markReadStmt.run({ $id: id });
 		},
 
+		deleteById(id: string): boolean {
+			try {
+				const result = deleteByIdStmt.run({ $id: id });
+				return result.changes > 0;
+			} catch (err) {
+				throw new MailError(`Failed to delete message: ${id}`, {
+					messageId: id,
+					cause: err instanceof Error ? err : undefined,
+				});
+			}
+		},
+
 		purge(options: { all?: boolean; olderThanMs?: number; agent?: string }): number {
 			// Count matching rows before deletion so we can report accurate numbers
 			if (options.all) {

package/src/merge/lock.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MergeError } from "../errors.ts";
+import { acquireMergeLock, mergeLockPath, sanitizeBranchForFilename } from "./lock.ts";
+
+describe("sanitizeBranchForFilename", () => {
+	test("replaces forward slashes with dashes", () => {
+		expect(sanitizeBranchForFilename("feature/foo")).toBe("feature-foo");
+		expect(sanitizeBranchForFilename("a/b/c")).toBe("a-b-c");
+	});
+
+	test("replaces backslashes and colons", () => {
+		expect(sanitizeBranchForFilename("feature\\bar")).toBe("feature-bar");
+		expect(sanitizeBranchForFilename("ns:branch")).toBe("ns-branch");
+	});
+
+	test("leaves simple branch names alone", () => {
+		expect(sanitizeBranchForFilename("main")).toBe("main");
+		expect(sanitizeBranchForFilename("develop_2")).toBe("develop_2");
+	});
+});
+
+describe("mergeLockPath", () => {
+	test("composes path under .overstory/ with sanitized branch", () => {
+		expect(mergeLockPath("/tmp/.overstory", "feature/x")).toBe(
+			"/tmp/.overstory/merge-feature-x.lock",
+		);
+	});
+});
+
+describe("acquireMergeLock", () => {
+	let overstoryDir: string;
+
+	beforeEach(async () => {
+		overstoryDir = await mkdtemp(join(tmpdir(), "ov-merge-lock-"));
+		await mkdir(overstoryDir, { recursive: true });
+	});
+
+	afterEach(async () => {
+		await rm(overstoryDir, { recursive: true, force: true });
+	});
+
+	test("creates a lock file and returns a handle that removes it on release", () => {
+		const handle = acquireMergeLock(overstoryDir, "main");
+		expect(existsSync(handle.path)).toBe(true);
+
+		const payload = JSON.parse(readFileSync(handle.path, "utf8"));
+		expect(payload.pid).toBe(process.pid);
+		expect(payload.targetBranch).toBe("main");
+		expect(typeof payload.acquiredAt).toBe("string");
+
+		handle.release();
+		expect(existsSync(handle.path)).toBe(false);
+	});
+
+	test("release() is idempotent", () => {
+		const handle = acquireMergeLock(overstoryDir, "main");
+		handle.release();
+		handle.release(); // should not throw
+		expect(existsSync(handle.path)).toBe(false);
+	});
+
+	test("throws MergeError when lock is held by a live process", () => {
+		// Use this test process's own PID — it is guaranteed live.
+		const path = mergeLockPath(overstoryDir, "main");
+		writeFileSync(
+			path,
+			JSON.stringify({
+				pid: process.pid,
+				acquiredAt: new Date().toISOString(),
+				targetBranch: "main",
+			}),
+		);
+
+		try {
+			acquireMergeLock(overstoryDir, "main");
+			expect(true).toBe(false); // should not reach
+		} 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(`pid ${process.pid}`);
+			expect(msg).toContain("main");
+		}
+
+		// Lock file is still on disk — we did not steal it.
+		expect(existsSync(path)).toBe(true);
+	});
+
+	test("steals a stale lock whose PID is not alive", () => {
+		const path = mergeLockPath(overstoryDir, "main");
+		// PID 2147483647 is INT_MAX — extremely unlikely to be in use.
+		writeFileSync(
+			path,
+			JSON.stringify({
+				pid: 2147483647,
+				acquiredAt: new Date(Date.now() - 60_000).toISOString(),
+				targetBranch: "main",
+			}),
+		);
+
+		const handle = acquireMergeLock(overstoryDir, "main");
+		const payload = JSON.parse(readFileSync(handle.path, "utf8"));
+		expect(payload.pid).toBe(process.pid);
+		handle.release();
+	});
+
+	test("steals an unparseable lock file", () => {
+		const path = mergeLockPath(overstoryDir, "main");
+		writeFileSync(path, "not json");
+
+		const handle = acquireMergeLock(overstoryDir, "main");
+		const payload = JSON.parse(readFileSync(handle.path, "utf8"));
+		expect(payload.pid).toBe(process.pid);
+		handle.release();
+	});
+
+	test("locks on different target branches are independent", () => {
+		const a = acquireMergeLock(overstoryDir, "main");
+		const b = acquireMergeLock(overstoryDir, "develop");
+		expect(existsSync(a.path)).toBe(true);
+		expect(existsSync(b.path)).toBe(true);
+		expect(a.path).not.toBe(b.path);
+		a.release();
+		b.release();
+	});
+
+	test("error message includes path so operator can manually clear", () => {
+		const path = mergeLockPath(overstoryDir, "main");
+		writeFileSync(
+			path,
+			JSON.stringify({
+				pid: process.pid,
+				acquiredAt: new Date().toISOString(),
+				targetBranch: "main",
+			}),
+		);
+
+		try {
+			acquireMergeLock(overstoryDir, "main");
+			expect(true).toBe(false);
+		} catch (err: unknown) {
+			expect((err as MergeError).message).toContain(path);
+		}
+	});
+});

package/src/merge/lock.ts

@@ -0,0 +1,140 @@
+/**
+ * Sentinel-file lock to prevent concurrent `ov merge` runs against the same
+ * canonical (target) branch.
+ *
+ * Two parallel merges into the same canonical branch can produce a misleading
+ * transient view: one merge runs the git operations while the second observes
+ * conflict markers mid-merge and reports a false failure. See seeds issue
+ * overstory-9610 for the original incident.
+ *
+ * The lock is a single JSON file at `.overstory/merge-{sanitized-target}.lock`
+ * created atomically with `writeFileSync(..., { flag: "wx" })`. If the file
+ * already exists, the holder PID is checked: live → fail fast, dead → take
+ * over. Released on exit via the returned handle.
+ */
+
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { MergeError } from "../errors.ts";
+import { isProcessAlive } from "../worktree/tmux.ts";
+
+export interface MergeLockHandle {
+	/** Path to the lock file on disk (useful for diagnostics / tests). */
+	readonly path: string;
+	/** Release the lock. Idempotent — safe to call multiple times. */
+	release(): void;
+}
+
+interface LockPayload {
+	pid: number;
+	acquiredAt: string;
+	targetBranch: string;
+}
+
+/**
+ * Sanitize a branch name for use in a filename.
+ * Replaces "/", "\\", and ":" with "-" so `feature/foo` becomes `feature-foo`.
+ */
+export function sanitizeBranchForFilename(branch: string): string {
+	return branch.replace(/[/\\:]/g, "-");
+}
+
+/** Compute the lock file path for a given target branch. */
+export function mergeLockPath(overstoryDir: string, targetBranch: string): string {
+	return join(overstoryDir, `merge-${sanitizeBranchForFilename(targetBranch)}.lock`);
+}
+
+/**
+ * Acquire the merge lock for a given target branch. Throws `MergeError` if
+ * another live `ov merge` is already running against this target. Stale locks
+ * (PID no longer alive) are taken over automatically.
+ *
+ * The caller MUST call `release()` on the returned handle when done.
+ */
+export function acquireMergeLock(overstoryDir: string, targetBranch: string): MergeLockHandle {
+	const path = mergeLockPath(overstoryDir, targetBranch);
+	const payload: LockPayload = {
+		pid: process.pid,
+		acquiredAt: new Date().toISOString(),
+		targetBranch,
+	};
+	const serialized = JSON.stringify(payload);
+
+	const tryCreate = (): boolean => {
+		try {
+			writeFileSync(path, serialized, { flag: "wx" });
+			return true;
+		} catch (err: unknown) {
+			const code = (err as NodeJS.ErrnoException).code;
+			if (code === "EEXIST") return false;
+			throw err;
+		}
+	};
+
+	if (tryCreate()) {
+		return makeHandle(path);
+	}
+
+	// Lock file exists. Inspect the holder before failing.
+	const existing = readLockPayload(path);
+	const holderPid = existing?.pid;
+	const holderAlive = typeof holderPid === "number" && isProcessAlive(holderPid);
+
+	if (holderAlive) {
+		const since = existing?.acquiredAt ?? "unknown time";
+		throw new MergeError(
+			`Another ov merge is already running for "${targetBranch}" (pid ${holderPid}, acquired ${since}). Wait for it to finish, or remove ${path} if you are sure it is stale.`,
+			{ branchName: targetBranch },
+		);
+	}
+
+	// Stale or unparseable lock — remove and retry once. If a third process
+	// won the race in between, surface that as a clear retry-soon error.
+	try {
+		unlinkSync(path);
+	} catch {
+		// File may have just been removed by another cleanup — fine.
+	}
+	if (tryCreate()) {
+		return makeHandle(path);
+	}
+
+	throw new MergeError(
+		`Another ov merge raced to acquire the lock for "${targetBranch}". Retry shortly.`,
+		{ branchName: targetBranch },
+	);
+}
+
+function readLockPayload(path: string): LockPayload | null {
+	try {
+		const content = readFileSync(path, "utf8");
+		const parsed = JSON.parse(content) as unknown;
+		if (
+			parsed !== null &&
+			typeof parsed === "object" &&
+			"pid" in parsed &&
+			typeof (parsed as { pid: unknown }).pid === "number"
+		) {
+			return parsed as LockPayload;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+function makeHandle(path: string): MergeLockHandle {
+	let released = false;
+	return {
+		path,
+		release(): void {
+			if (released) return;
+			released = true;
+			try {
+				unlinkSync(path);
+			} catch {
+				// File may already be gone — not an error.
+			}
+		},
+	};
+}

package/src/runtimes/__fixtures__/claude-stream-fixture.ts

@@ -0,0 +1,22 @@
+// Fixture: emits a known sequence of Claude stream-json lines to stdout then exits.
+// Used by the ClaudeRuntime.parseEvents() integration test.
+const lines = [
+	JSON.stringify({ type: "system", subtype: "init", session_id: "sess-123" }),
+	JSON.stringify({
+		type: "assistant",
+		message: {
+			model: "claude-sonnet-4-6",
+			content: [{ type: "text", text: "hello" }],
+			usage: { input_tokens: 10, output_tokens: 5 },
+		},
+	}),
+	JSON.stringify({
+		type: "result",
+		session_id: "sess-123",
+		result: "done",
+		is_error: false,
+		duration_ms: 1234,
+		num_turns: 1,
+	}),
+];
+for (const l of lines) process.stdout.write(`${l}\n`);