@os-eco/overstory-cli 0.9.4 → 0.10.3

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.4";
+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", () => {

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