@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/sessions/store.ts

@@ -7,7 +7,50 @@
  */
 
 import { Database } from "bun:sqlite";
-import type { AgentSession, AgentState, InsertRun, Run, RunStatus, RunStore } from "../types.ts";
+import type {
+	AgentSession,
+	AgentState,
+	InsertRun,
+	Run,
+	RunStatus,
+	RunStore,
+	TransitionOutcome,
+} from "../types.ts";
+
+/**
+ * Allowed predecessor states for each target state, enforced by
+ * `tryTransitionState` via an atomic SQL compare-and-swap.
+ *
+ * Invariants:
+ *   - `completed` is sticky: nothing transitions out of it. The watchdog cannot
+ *     reclassify a properly-completed agent as zombie.
+ *   - `zombie` is durable except `ov stop` may promote it to `completed` for
+ *     cleanup. A turn-runner that "settles to working" after watchdog already
+ *     wrote zombie is rejected — last writer no longer wins.
+ *   - Idempotent self-transitions (e.g. `working → working`) are allowed.
+ *   - `booting` is set only by the initial `upsert` and never re-entered.
+ *
+ * See overstory-a993 for the race symptoms this guard prevents.
+ */
+const TRANSITION_ALLOWED_FROM: Record<AgentState, readonly AgentState[]> = {
+	booting: [],
+	working: ["booting", "working", "stalled"],
+	stalled: ["booting", "working", "stalled"],
+	completed: ["booting", "working", "stalled", "zombie", "completed"],
+	zombie: ["booting", "working", "stalled", "zombie"],
+};
+
+/**
+ * States in which an agent's tmux session no longer exists. When a session
+ * lands in one of these, `tmux_session` is cleared to `''` so the agents-side
+ * view stops surfacing tmux session names that have been torn down.
+ *
+ * The live `tmuxSessions` array on `ov status` reflects what tmux actually
+ * reports; the stored `tmux_session` column is what the agents-side view reads.
+ * Without this clear, completed/zombie agents carry stale tmux strings forever
+ * (overstory-14c0).
+ */
+const TERMINAL_STATES: readonly AgentState[] = ["completed", "zombie"];
 
 export interface SessionStore {
 	/** Insert or update a session. Uses agent_name as the unique key. */
@@ -22,14 +65,32 @@ export interface SessionStore {
 	count(): number;
 	/** Get sessions belonging to a specific run. */
 	getByRun(runId: string): AgentSession[];
-	/** Update only the state of a session. */
+	/**
+	 * Update only the state of a session.
+	 *
+	 * Unconditional override — does not validate the prev → next transition.
+	 * Reserved for forced cleanup paths (`ov clean`, `ov sling` startup failure,
+	 * supervisor/coordinator/monitor self-management). For race-prone writers
+	 * (turn-runner settle, `ov stop`, watchdog), use `tryTransitionState`.
+	 */
 	updateState(agentName: string, state: AgentState): void;
+	/**
+	 * Atomically transition a session's state, validated against the matrix in
+	 * `TRANSITION_ALLOWED_FROM`. Implemented as a single `UPDATE ... WHERE state
+	 * IN (...)` so concurrent writers cannot both succeed against the same row.
+	 *
+	 * Returns a discriminated outcome describing whether the write landed and,
+	 * on rejection, whether the row was missing or the transition was illegal.
+	 */
+	tryTransitionState(agentName: string, newState: AgentState): TransitionOutcome;
 	/** Update lastActivity to current ISO timestamp. */
 	updateLastActivity(agentName: string): void;
 	/** Update escalation level and stalled timestamp. */
 	updateEscalation(agentName: string, level: number, stalledSince: string | null): void;
 	/** Update the transcript path for a session. */
 	updateTranscriptPath(agentName: string, path: string): void;
+	/** Update the runtime-provided session_id (e.g. Claude stream-json session_id). */
+	updateClaudeSessionId(agentName: string, sessionId: string): void;
 	/** Remove a session by agent name. */
 	remove(agentName: string): void;
 	/** Purge sessions matching criteria. Returns count of deleted rows. */
@@ -58,6 +119,7 @@ interface SessionRow {
 	stalled_since: string | null;
 	transcript_path: string | null;
 	prompt_version: string | null;
+	claude_session_id: string | null;
 }
 
 /** Row shape for runs table as stored in SQLite (snake_case columns). */
@@ -91,7 +153,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   escalation_level INTEGER NOT NULL DEFAULT 0,
   stalled_since TEXT,
   transcript_path TEXT,
-  prompt_version TEXT
+  prompt_version TEXT,
+  claude_session_id TEXT
 )`;
 
 const CREATE_INDEXES = `
@@ -135,6 +198,7 @@ function rowToSession(row: SessionRow): AgentSession {
 		stalledSince: row.stalled_since,
 		transcriptPath: row.transcript_path,
 		...(row.prompt_version !== null ? { promptVersion: row.prompt_version } : {}),
+		...(row.claude_session_id !== null ? { claudeSessionId: row.claude_session_id } : {}),
 	};
 }
 
@@ -175,6 +239,18 @@ function migrateAddPromptVersion(db: Database): void {
 	}
 }
 
+/**
+ * Migrate an existing sessions table to add the claude_session_id column.
+ * Safe to call multiple times — only adds the column if it does not exist.
+ */
+function migrateAddClaudeSessionId(db: Database): void {
+	const rows = db.prepare("PRAGMA table_info(sessions)").all() as Array<{ name: string }>;
+	const existingColumns = new Set(rows.map((r) => r.name));
+	if (!existingColumns.has("claude_session_id")) {
+		db.exec("ALTER TABLE sessions ADD COLUMN claude_session_id TEXT");
+	}
+}
+
 /**
  * Migrate an existing sessions table from bead_id to task_id column.
  * Safe to call multiple times — only renames if bead_id exists and task_id does not.
@@ -209,6 +285,7 @@ export function createSessionStore(dbPath: string): SessionStore {
 	migrateBeadIdToTaskId(db);
 	migrateAddTranscriptPath(db);
 	migrateAddPromptVersion(db);
+	migrateAddClaudeSessionId(db);
 	migrateAddCoordinatorName(db);
 
 	// Now safe to create indexes (all columns exist).
@@ -237,18 +314,19 @@ export function createSessionStore(dbPath: string): SessionStore {
 			$stalled_since: string | null;
 			$transcript_path: string | null;
 			$prompt_version: string | null;
+			$claude_session_id: string | null;
 		}
 	>(`
 		INSERT INTO sessions
 			(id, agent_name, capability, worktree_path, branch_name, task_id,
 			 tmux_session, state, pid, parent_agent, depth, run_id,
 			 started_at, last_activity, escalation_level, stalled_since, transcript_path,
-			 prompt_version)
+			 prompt_version, claude_session_id)
 		VALUES
 			($id, $agent_name, $capability, $worktree_path, $branch_name, $task_id,
 			 $tmux_session, $state, $pid, $parent_agent, $depth, $run_id,
 			 $started_at, $last_activity, $escalation_level, $stalled_since, $transcript_path,
-			 $prompt_version)
+			 $prompt_version, $claude_session_id)
 		ON CONFLICT(agent_name) DO UPDATE SET
 			id = excluded.id,
 			capability = excluded.capability,
@@ -266,7 +344,8 @@ export function createSessionStore(dbPath: string): SessionStore {
 			escalation_level = excluded.escalation_level,
 			stalled_since = excluded.stalled_since,
 			transcript_path = excluded.transcript_path,
-			prompt_version = excluded.prompt_version
+			prompt_version = excluded.prompt_version,
+			claude_session_id = excluded.claude_session_id
 	`);
 
 	const getByNameStmt = db.prepare<SessionRow, { $agent_name: string }>(`
@@ -290,10 +369,39 @@ export function createSessionStore(dbPath: string): SessionStore {
 		SELECT * FROM sessions WHERE run_id = $run_id ORDER BY started_at ASC
 	`);
 
+	// Clear tmux_session when landing in a terminal state — the tmux session
+	// has already been torn down by ov stop / watchdog / coordinator cleanup,
+	// so the stored string is stale (overstory-14c0).
+	const terminalInList = TERMINAL_STATES.map((s) => `'${s}'`).join(",");
 	const updateStateStmt = db.prepare<void, { $agent_name: string; $state: string }>(`
-		UPDATE sessions SET state = $state WHERE agent_name = $agent_name
+		UPDATE sessions
+		SET state = $state,
+		    tmux_session = CASE WHEN $state IN (${terminalInList}) THEN '' ELSE tmux_session END
+		WHERE agent_name = $agent_name
 	`);
 
+	// Per-target-state CAS statements. The IN-list values come from a static
+	// matrix we control (TRANSITION_ALLOWED_FROM), so inlining as literals is
+	// safe and lets bun:sqlite re-use the prepared plan without dynamic params.
+	const tryTransitionStmts = (() => {
+		const stmts: Partial<
+			Record<AgentState, ReturnType<typeof db.prepare<void, { $agent_name: string }>>>
+		> = {};
+		const terminalSet = new Set<AgentState>(TERMINAL_STATES);
+		for (const target of Object.keys(TRANSITION_ALLOWED_FROM) as AgentState[]) {
+			const allowed = TRANSITION_ALLOWED_FROM[target];
+			if (allowed.length === 0) continue;
+			const inList = allowed.map((s) => `'${s}'`).join(",");
+			const setClause = terminalSet.has(target)
+				? `state = '${target}', tmux_session = ''`
+				: `state = '${target}'`;
+			stmts[target] = db.prepare<void, { $agent_name: string }>(
+				`UPDATE sessions SET ${setClause} WHERE agent_name = $agent_name AND state IN (${inList})`,
+			);
+		}
+		return stmts;
+	})();
+
 	const updateLastActivityStmt = db.prepare<void, { $agent_name: string; $last_activity: string }>(`
 		UPDATE sessions SET last_activity = $last_activity WHERE agent_name = $agent_name
 	`);
@@ -322,6 +430,13 @@ export function createSessionStore(dbPath: string): SessionStore {
 		UPDATE sessions SET transcript_path = $transcript_path WHERE agent_name = $agent_name
 	`);
 
+	const updateClaudeSessionIdStmt = db.prepare<
+		void,
+		{ $agent_name: string; $claude_session_id: string }
+	>(`
+		UPDATE sessions SET claude_session_id = $claude_session_id WHERE agent_name = $agent_name
+	`);
+
 	return {
 		upsert(session: AgentSession): void {
 			upsertStmt.run({
@@ -343,6 +458,7 @@ export function createSessionStore(dbPath: string): SessionStore {
 				$stalled_since: session.stalledSince,
 				$transcript_path: session.transcriptPath,
 				$prompt_version: session.promptVersion ?? null,
+				$claude_session_id: session.claudeSessionId ?? null,
 			});
 		},
 
@@ -375,6 +491,37 @@ export function createSessionStore(dbPath: string): SessionStore {
 			updateStateStmt.run({ $agent_name: agentName, $state: state });
 		},
 
+		tryTransitionState(agentName: string, newState: AgentState): TransitionOutcome {
+			// Read prev for diagnostic accuracy before the CAS. The read is racy
+			// against another writer landing first, but the CAS that follows is
+			// authoritative — `changes === 0` means the CAS rejected against
+			// whatever the row holds NOW, regardless of what we read here.
+			const before = getByNameStmt.get({ $agent_name: agentName });
+			if (before === null) {
+				return { ok: false, reason: "not_found", attempted: newState };
+			}
+			const stmt = tryTransitionStmts[newState];
+			if (stmt !== undefined) {
+				const result = stmt.run({ $agent_name: agentName });
+				if (result.changes > 0) {
+					return { ok: true, prev: before.state as AgentState, next: newState };
+				}
+			}
+			// CAS rejected (or no stmt for this target, e.g. booting). Re-read to
+			// report the state that actually blocked us — another writer may have
+			// landed between our `before` read and the CAS.
+			const after = getByNameStmt.get({ $agent_name: agentName });
+			if (after === null) {
+				return { ok: false, reason: "not_found", attempted: newState };
+			}
+			return {
+				ok: false,
+				reason: "illegal_transition",
+				prev: after.state as AgentState,
+				attempted: newState,
+			};
+		},
+
 		updateLastActivity(agentName: string): void {
 			updateLastActivityStmt.run({
 				$agent_name: agentName,
@@ -394,6 +541,10 @@ export function createSessionStore(dbPath: string): SessionStore {
 			updateTranscriptPathStmt.run({ $agent_name: agentName, $transcript_path: path });
 		},
 
+		updateClaudeSessionId(agentName: string, sessionId: string): void {
+			updateClaudeSessionIdStmt.run({ $agent_name: agentName, $claude_session_id: sessionId });
+		},
+
 		remove(agentName: string): void {
 			removeStmt.run({ $agent_name: agentName });
 		},
@@ -473,7 +624,12 @@ export function createRunStore(dbPath: string): RunStore {
 	db.exec("PRAGMA synchronous = NORMAL");
 	db.exec("PRAGMA busy_timeout = 5000");
 
-	// Create schema (idempotent — safe if SessionStore already created these)
+	// Create schema (idempotent — safe if SessionStore already created these).
+	// `agent_count` is derived from the sessions table at read time, so the
+	// sessions table must exist when the run-read statements are prepared
+	// — even if the caller only opens a RunStore and never opens a SessionStore.
+	db.exec(CREATE_TABLE);
+	db.exec(CREATE_INDEXES);
 	db.exec(CREATE_RUNS_TABLE);
 
 	// Migrate: add coordinator_name column BEFORE creating indexes that reference it.
@@ -499,26 +655,35 @@ export function createRunStore(dbPath: string): RunStore {
 		VALUES ($id, $started_at, $completed_at, $agent_count, $coordinator_session_id, $coordinator_name, $status)
 	`);
 
+	// `agent_count` is derived from the sessions table at read time rather than
+	// read from the column. The cached column value drifted because only sling
+	// incremented it — coordinator startup never did, so for every run with a
+	// coordinator the count was off by one (overstory-8e69). Sourcing from
+	// sessions makes the count match `SELECT * FROM sessions WHERE run_id = ?`
+	// and removes the writer/reader asymmetry. The column is still written so
+	// older overstory binaries pointed at the same db can keep functioning.
+	const RUN_COLUMNS = `
+		id, started_at, completed_at,
+		(SELECT COUNT(*) FROM sessions WHERE sessions.run_id = runs.id) AS agent_count,
+		coordinator_session_id, coordinator_name, status
+	`;
+
 	const getRunStmt = db.prepare<RunRow, { $id: string }>(`
-		SELECT * FROM runs WHERE id = $id
+		SELECT ${RUN_COLUMNS} FROM runs WHERE id = $id
 	`);
 
 	const getActiveRunStmt = db.prepare<RunRow, Record<string, never>>(`
-		SELECT * FROM runs WHERE status = 'active'
+		SELECT ${RUN_COLUMNS} FROM runs WHERE status = 'active'
 		ORDER BY started_at DESC
 		LIMIT 1
 	`);
 
 	const getActiveRunForCoordinatorStmt = db.prepare<RunRow, { $coordinator_name: string }>(`
-		SELECT * FROM runs WHERE status = 'active' AND coordinator_name = $coordinator_name
+		SELECT ${RUN_COLUMNS} FROM runs WHERE status = 'active' AND coordinator_name = $coordinator_name
 		ORDER BY started_at DESC
 		LIMIT 1
 	`);
 
-	const incrementAgentCountStmt = db.prepare<void, { $id: string }>(`
-		UPDATE runs SET agent_count = agent_count + 1 WHERE id = $id
-	`);
-
 	const completeRunStmt = db.prepare<
 		void,
 		{ $id: string; $status: string; $completed_at: string }
@@ -565,15 +730,15 @@ export function createRunStore(dbPath: string): RunStore {
 
 			const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
 			const limitClause = opts?.limit !== undefined ? `LIMIT ${opts.limit}` : "";
-			const query = `SELECT * FROM runs ${whereClause} ORDER BY started_at DESC ${limitClause}`;
+			const query = `SELECT ${RUN_COLUMNS} FROM runs ${whereClause} ORDER BY started_at DESC ${limitClause}`;
 
 			const rows = db.prepare<RunRow, Record<string, string | number>>(query).all(params);
 			return rows.map(rowToRun);
 		},
 
-		incrementAgentCount(runId: string): void {
-			incrementAgentCountStmt.run({ $id: runId });
-		},
+		// Kept for API stability but a no-op: `agent_count` is now derived from
+		// the sessions table on every read (see RUN_COLUMNS above).
+		incrementAgentCount(_runId: string): void {},
 
 		completeRun(runId: string, status: "completed" | "failed"): void {
 			completeRunStmt.run({

package/src/test-setup.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Regression test for overstory-6d42: bun test must not be redirectable to a
+ * real .overstory/ via inherited OVERSTORY_PROJECT_ROOT (or sibling) env vars.
+ *
+ * The preload in bunfig.toml runs src/test-setup.ts before any test loads,
+ * deleting OVERSTORY_* env vars and clearing the project-root override. By
+ * the time this test executes, those values must already be gone — even if a
+ * worker agent's environment had them set when bun test was invoked.
+ */
+
+import { expect, test } from "bun:test";
+import { getProjectRootOverride } from "./config.ts";
+
+const ENV_KEYS = [
+	"OVERSTORY_PROJECT_ROOT",
+	"OVERSTORY_AGENT_NAME",
+	"OVERSTORY_WORKTREE_PATH",
+	"OVERSTORY_TASK_ID",
+	"OVERSTORY_PROFILE",
+	"OVERSTORY_RUN_ID",
+] as const;
+
+for (const key of ENV_KEYS) {
+	test(`${key} is unset by the test preload`, () => {
+		expect(process.env[key]).toBeUndefined();
+	});
+}
+
+test("project-root override is cleared by the test preload", () => {
+	expect(getProjectRootOverride()).toBeUndefined();
+});

package/src/test-setup.ts

@@ -0,0 +1,28 @@
+/**
+ * Global test preload (referenced from bunfig.toml [test] preload).
+ *
+ * Prevents test runs from leaking into a real .overstory/ when bun test is
+ * executed inside an agent worktree (where ov sling injects OVERSTORY_PROJECT_ROOT
+ * into the spawned process — see src/commands/sling.ts:928).
+ *
+ * Without this preload, resolveProjectRoot() short-circuits to the env var
+ * before consulting the per-test temp dir, so tests calling cleanCommand,
+ * coordinatorCommand, mailCommand, etc. silently target the live project.
+ * That's how overstory-6d42 contamination occurred: a worker agent ran
+ * bun test, clean.test.ts wiped the live .overstory/, coordinator.test.ts
+ * left dozens of bogus runs, and mail.test.ts inserted fixture messages.
+ *
+ * Tests that need OVERSTORY_PROJECT_ROOT set (e.g. config.test.ts) set it
+ * explicitly inside the test body and restore it in afterEach.
+ */
+
+import { clearProjectRootOverride } from "./config.ts";
+
+delete process.env.OVERSTORY_PROJECT_ROOT;
+delete process.env.OVERSTORY_AGENT_NAME;
+delete process.env.OVERSTORY_WORKTREE_PATH;
+delete process.env.OVERSTORY_TASK_ID;
+delete process.env.OVERSTORY_PROFILE;
+delete process.env.OVERSTORY_RUN_ID;
+
+clearProjectRootOverride();

package/src/types.ts

@@ -108,6 +108,7 @@ export interface OverstoryConfig {
 		rpcTimeoutMs?: number; // Timeout for RPC getState() calls (default 5_000)
 		triageTimeoutMs?: number; // Timeout for Tier 1 AI triage calls (default 30_000)
 		maxEscalationLevel?: number; // Maximum escalation level before termination (default 3)
+		notifyParentOnDeath?: boolean; // Send synthetic worker_died mail to parent on watchdog termination (default true)
 	};
 	models: Partial<Record<string, ModelRef>>;
 	logging: {
@@ -141,6 +142,13 @@ export interface OverstoryConfig {
 		 * Default: 0 (no delay).
 		 */
 		shellInitDelayMs?: number;
+		/**
+		 * Project-level default for spawning Claude Code agents in headless mode
+		 * (Bun.spawn + stream-json) instead of the tmux interactive runtime.
+		 * Per-spawn `--headless` / `--no-headless` flags on `ov sling` override this.
+		 * Default: false (tmux).
+		 */
+		claudeHeadlessByDefault?: boolean;
 	};
 }
 
@@ -181,6 +189,22 @@ export type Capability = (typeof SUPPORTED_CAPABILITIES)[number];
 
 export type AgentState = "booting" | "working" | "completed" | "stalled" | "zombie";
 
+/**
+ * Result of a guarded state transition attempt (`SessionStore.tryTransitionState`).
+ *
+ * Discriminated by `ok`. When `ok` is false, `reason` distinguishes:
+ *   - `not_found`: no session exists for the given name.
+ *   - `illegal_transition`: a session exists but the matrix forbids prev → attempted.
+ *
+ * `prev` is always the state observed by the SQL CAS. For `illegal_transition` it
+ * is the state that blocked the write (which may differ from what the caller read,
+ * if another writer landed first).
+ */
+export type TransitionOutcome =
+	| { ok: true; prev: AgentState; next: AgentState }
+	| { ok: false; reason: "not_found"; attempted: AgentState }
+	| { ok: false; reason: "illegal_transition"; prev: AgentState; attempted: AgentState };
+
 export interface AgentSession {
 	id: string; // Unique session ID
 	agentName: string; // Unique per-session name
@@ -200,6 +224,7 @@ export interface AgentSession {
 	stalledSince: string | null; // ISO timestamp when agent first entered stalled state
 	transcriptPath: string | null; // Runtime-provided transcript JSONL path (decoupled from ~/.claude/)
 	promptVersion?: string | null; // Canopy prompt version used at sling time (e.g. "builder@17")
+	claudeSessionId?: string | null; // Runtime-provided session_id (Claude stream-json), eagerly pinned on first event
 }
 
 // === Agent Identity ===
@@ -225,6 +250,7 @@ export type MailSemanticType = "status" | "question" | "result" | "error";
 /** Protocol message types for structured agent coordination. */
 export type MailProtocolType =
 	| "worker_done"
+	| "worker_died"
 	| "merge_ready"
 	| "merged"
 	| "merge_failed"
@@ -244,6 +270,7 @@ export const MAIL_MESSAGE_TYPES: readonly MailMessageType[] = [
 	"result",
 	"error",
 	"worker_done",
+	"worker_died",
 	"merge_ready",
 	"merged",
 	"merge_failed",
@@ -278,6 +305,33 @@ export interface WorkerDonePayload {
 	filesModified: string[];
 }
 
+/**
+ * Watchdog signals the parent that one of its children was terminated.
+ *
+ * Synthetic mail injected by the Tier 0 daemon when it transitions a worker
+ * to `zombie` (overstory-c111). Without this, the parent — typically a lead
+ * waiting for `worker_done` from this child — would block indefinitely on
+ * mail that will never arrive. The parent reads this on its next mail-injector
+ * tick and decides whether to retry, escalate, or report up.
+ */
+export interface WorkerDiedPayload {
+	agentName: string;
+	capability: string;
+	taskId: string;
+	/** Reason the watchdog or runner terminated the child (e.g. "Process terminated"). */
+	reason: string;
+	/** ISO timestamp of the child's last observed activity. */
+	lastActivity: string;
+	/**
+	 * Source that detected the failure.
+	 * - `tier0`/`tier1`: watchdog daemon detected a dead/stuck process out-of-band.
+	 * - `runner`: the per-turn runner observed an in-band failure — either an
+	 *   abort/stall that forced SIGTERM/SIGKILL, or a clean exit without the
+	 *   capability's terminal mail (silent-no-op, overstory-4159 / overstory-c772).
+	 */
+	terminatedBy: "tier0" | "tier1" | "runner";
+}
+
 /** Supervisor signals branch is verified and ready for merge. */
 export interface MergeReadyPayload {
 	branch: string;
@@ -349,6 +403,7 @@ export interface DecisionGatePayload {
 /** Maps protocol message types to their payload interfaces. */
 export interface MailPayloadMap {
 	worker_done: WorkerDonePayload;
+	worker_died: WorkerDiedPayload;
 	merge_ready: MergeReadyPayload;
 	merged: MergedPayload;
 	merge_failed: MergeFailedPayload;
@@ -446,7 +501,7 @@ export interface HealthCheck {
 	pidAlive: boolean | null; // null when pid is unavailable
 	lastActivity: string;
 	state: AgentState;
-	action: "none" | "escalate" | "terminate" | "investigate";
+	action: "none" | "escalate" | "terminate" | "investigate" | "complete";
 	/** Describes any conflict between observable state and recorded state. */
 	reconciliationNote: string | null;
 }

package/src/utils/pid.test.ts

@@ -3,7 +3,7 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { cleanupTempDir } from "../test-helpers.ts";
-import { readPidFile, removePidFile, writePidFile } from "./pid.ts";
+import { acquirePidLock, readPidFile, removePidFile, writePidFile } from "./pid.ts";
 
 let tempDir: string;
 
@@ -66,3 +66,87 @@ describe("removePidFile", () => {
 		// No throw = pass
 	});
 });
+
+describe("acquirePidLock", () => {
+	const alwaysAlive = (_pid: number) => true;
+	const alwaysDead = (_pid: number) => false;
+
+	test("acquires when no lock file exists", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("creates parent directory if missing", async () => {
+		const pidPath = join(tempDir, "nested", "deeper", "lock.pid");
+		const result = await acquirePidLock(pidPath, 555, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(555);
+	});
+
+	test("refuses when a live foreign PID owns the lock", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "9999\n");
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(false);
+		if (!result.acquired) {
+			expect(result.existingPid).toBe(9999);
+		}
+		// File untouched.
+		expect(await readPidFile(pidPath)).toBe(9999);
+	});
+
+	test("idempotent when file already contains caller's own PID", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "1234\n");
+		// alwaysAlive would say 1234 is alive, but acquirePidLock should detect
+		// own-PID first and accept.
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("reclaims stale lock with dead PID", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "9999\n");
+		const result = await acquirePidLock(pidPath, 1234, alwaysDead);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("reclaims unreadable/corrupted lock file", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		await Bun.write(pidPath, "garbage-not-a-pid\n");
+		const result = await acquirePidLock(pidPath, 1234, alwaysAlive);
+		expect(result.acquired).toBe(true);
+		expect(await readPidFile(pidPath)).toBe(1234);
+	});
+
+	test("two simultaneous acquirers — only one wins", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		const [a, b] = await Promise.all([
+			acquirePidLock(pidPath, 1111, alwaysAlive),
+			acquirePidLock(pidPath, 2222, alwaysAlive),
+		]);
+		const winners = [a, b].filter((r) => r.acquired);
+		const losers = [a, b].filter((r) => !r.acquired);
+		expect(winners.length).toBe(1);
+		expect(losers.length).toBe(1);
+		const loser = losers[0];
+		if (loser && !loser.acquired) {
+			expect([1111, 2222]).toContain(loser.existingPid);
+		}
+	});
+
+	test("two simultaneous acquirers — file content matches the winner", async () => {
+		const pidPath = join(tempDir, "lock.pid");
+		const [a, b] = await Promise.all([
+			acquirePidLock(pidPath, 1111, alwaysAlive),
+			acquirePidLock(pidPath, 2222, alwaysAlive),
+		]);
+		const fileContent = await readPidFile(pidPath);
+		const winnerPid = a.acquired ? 1111 : b.acquired ? 2222 : -1;
+		expect(fileContent).toBe(winnerPid);
+	});
+});