@os-eco/overstory-cli 0.9.4 → 0.10.3

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/nudge.test.ts

@@ -4,6 +4,8 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createEventStore } from "../events/store.ts";
+import { removeConnection, setConnection } from "../runtimes/connections.ts";
+import type { NudgeableConnection, NudgeResult } from "../runtimes/headless-connection.ts";
 import { createSessionStore } from "../sessions/store.ts";
 import { cleanupTempDir } from "../test-helpers.ts";
 import type { AgentSession, StoredEvent } from "../types.ts";
@@ -63,6 +65,32 @@ function makeSession(overrides: Partial<AgentSession> = {}): AgentSession {
 	};
 }
 
+describe("paneAppearsBusy", () => {
+	test("flags Claude Code mid-think pane as busy", async () => {
+		const { paneAppearsBusy } = await import("./nudge.ts");
+		const sample = [
+			"╭───────────────────────────────────────────╮",
+			"│ ✻ Cooking… (5s · ↓ 0 tokens · esc to interrupt)",
+			"╰───────────────────────────────────────────╯",
+			"  ⏵⏵ bypass permissions on (alt+m to cycle)",
+		].join("\n");
+		expect(paneAppearsBusy(sample)).toBe(true);
+	});
+
+	test("treats idle pane (no esc-to-interrupt) as not busy", async () => {
+		const { paneAppearsBusy } = await import("./nudge.ts");
+		const sample = [
+			"$ ❯ ls",
+			"src/",
+			"╭───────────────────────────────────────────╮",
+			"│ > _                                       │",
+			"╰───────────────────────────────────────────╯",
+			"  ⏵⏵ bypass permissions on (alt+m to cycle)",
+		].join("\n");
+		expect(paneAppearsBusy(sample)).toBe(false);
+	});
+});
+
 describe("nudgeAgent", () => {
 	// We dynamically import to avoid circular issues
 	async function importNudge() {
@@ -77,20 +105,28 @@ describe("nudgeAgent", () => {
 		expect(result.reason).toContain("No active session");
 	});
 
-	test("returns error when agent is zombie", async () => {
-		writeSessionsToStore(tempDir, [makeSession({ state: "zombie" })]);
+	test("returns error with recovery hint when agent is zombie", async () => {
+		writeSessionsToStore(tempDir, [
+			makeSession({ state: "zombie", capability: "lead", taskId: "task-42" }),
+		]);
 		const { nudgeAgent } = await importNudge();
 		const result = await nudgeAgent(tempDir, "test-agent");
 		expect(result.delivered).toBe(false);
 		expect(result.reason).toContain("No active session");
+		expect(result.reason).toContain("state: zombie");
+		expect(result.reason).toContain("ov sling task-42 --capability lead --recover");
 	});
 
-	test("returns error when agent is completed", async () => {
-		writeSessionsToStore(tempDir, [makeSession({ state: "completed" })]);
+	test("returns error with recovery hint when agent is completed", async () => {
+		writeSessionsToStore(tempDir, [
+			makeSession({ state: "completed", capability: "lead", taskId: "task-42" }),
+		]);
 		const { nudgeAgent } = await importNudge();
 		const result = await nudgeAgent(tempDir, "test-agent");
 		expect(result.delivered).toBe(false);
 		expect(result.reason).toContain("No active session");
+		expect(result.reason).toContain("state: completed");
+		expect(result.reason).toContain("ov sling task-42 --capability lead --recover");
 	});
 
 	test("finds active agent in working state", async () => {
@@ -230,3 +266,314 @@ describe("nudgeAgent", () => {
 		}
 	});
 });
+
+describe("nudgeAgent with headless connection", () => {
+	async function importNudge() {
+		return await import("./nudge.ts");
+	}
+
+	/** Build a NudgeableConnection stub that records calls. */
+	function makeNudgeableConn(
+		result: NudgeResult = { status: "Queued" },
+		onNudge?: (text: string) => void,
+	): NudgeableConnection {
+		return {
+			sendPrompt: async () => {},
+			followUp: async () => {},
+			abort: async () => {},
+			getState: async () => ({ status: "idle" as const }),
+			close: () => {},
+			nudge: async (text: string) => {
+				if (onNudge) onNudge(text);
+				return result;
+			},
+		};
+	}
+
+	afterEach(() => {
+		removeConnection("headless-test-agent");
+	});
+
+	test("routes nudge through connection.nudge() when connection exists", async () => {
+		let capturedText = "";
+		setConnection(
+			"headless-test-agent",
+			makeNudgeableConn({ status: "Queued" }, (t) => {
+				capturedText = t;
+			}),
+		);
+
+		const { nudgeAgent } = await importNudge();
+		const result = await nudgeAgent(tempDir, "headless-test-agent", "ping", true);
+
+		expect(result.delivered).toBe(true);
+		expect(result.queued).toBe(true);
+		expect(capturedText).toBe("ping");
+	});
+
+	test("queued=false when connection returns Delivered", async () => {
+		setConnection("headless-test-agent", makeNudgeableConn({ status: "Delivered" }));
+
+		const { nudgeAgent } = await importNudge();
+		const result = await nudgeAgent(tempDir, "headless-test-agent", "ping", true);
+
+		expect(result.delivered).toBe(true);
+		expect(result.queued).toBe(false);
+	});
+
+	test("falls back to tmux path when connection has no nudge() method", async () => {
+		// Register a plain RuntimeConnection (no nudge method)
+		setConnection("headless-test-agent", {
+			sendPrompt: async () => {},
+			followUp: async () => {},
+			abort: async () => {},
+			getState: async () => ({ status: "idle" as const }),
+			close: () => {},
+		});
+		// Also add a sessions.db entry so resolveTargetSession can find something
+		writeSessionsToStore(tempDir, [makeSession({ agentName: "headless-test-agent" })]);
+
+		const { nudgeAgent } = await importNudge();
+		const result = await nudgeAgent(tempDir, "headless-test-agent");
+		// Falls through to tmux — tmux session not alive
+		expect(result.delivered).toBe(false);
+		expect(result.reason).toContain("not alive");
+		// No queued field when tmux path runs
+		expect(result.queued).toBeUndefined();
+	});
+
+	test("debounce applies to headless nudges", async () => {
+		let nudgeCount = 0;
+		setConnection(
+			"headless-test-agent",
+			makeNudgeableConn({ status: "Queued" }, () => {
+				nudgeCount++;
+			}),
+		);
+
+		const { nudgeAgent } = await importNudge();
+		// First nudge — forced to bypass debounce and prime the state
+		await nudgeAgent(tempDir, "headless-test-agent", "first", true);
+		// Second nudge immediately — should be debounced (within 500ms window)
+		const second = await nudgeAgent(tempDir, "headless-test-agent", "second");
+
+		expect(nudgeCount).toBe(1);
+		expect(second.delivered).toBe(false);
+		expect(second.reason).toContain("Debounced");
+	});
+
+	test("records nudge event for headless delivery", async () => {
+		setConnection("headless-test-agent", makeNudgeableConn({ status: "Queued" }));
+
+		const { nudgeAgent } = await importNudge();
+		await nudgeAgent(tempDir, "headless-test-agent", "event test", true);
+
+		const eventsDbPath = join(tempDir, ".overstory", "events.db");
+		const store = createEventStore(eventsDbPath);
+		try {
+			const events: StoredEvent[] = store.getTimeline({ since: "2000-01-01T00:00:00Z" });
+			const nudgeEvent = events.find((e) => {
+				if (!e.data) return false;
+				const data = JSON.parse(e.data) as Record<string, unknown>;
+				return data.type === "nudge";
+			});
+			expect(nudgeEvent).toBeDefined();
+			expect(nudgeEvent?.agentName).toBe("headless-test-agent");
+			const data = JSON.parse(nudgeEvent?.data ?? "{}") as Record<string, unknown>;
+			expect(data.delivered).toBe(true);
+		} finally {
+			store.close();
+		}
+	});
+
+	test("tmux path: send-keys path invoked for agent with no connection", async () => {
+		writeSessionsToStore(tempDir, [makeSession({ state: "working" })]);
+
+		const { nudgeAgent } = await importNudge();
+		const result = await nudgeAgent(tempDir, "test-agent");
+		// No connection registered → tmux path → tmux session not alive
+		expect(result.delivered).toBe(false);
+		expect(result.reason).toContain("not alive");
+		expect(result.queued).toBeUndefined();
+	});
+});
+
+describe("nudgeAgent spawn-per-turn dispatch", () => {
+	async function importNudge() {
+		return await import("./nudge.ts");
+	}
+
+	function fakeLoadConfig(): typeof import("../config.ts").loadConfig {
+		return (async (root: string) => ({
+			project: { name: "test", root, canonicalBranch: "main" },
+			agents: {
+				baseDir: "agents",
+				manifestPath: ".overstory/agent-manifest.json",
+				maxConcurrent: 5,
+				maxSessionsPerRun: 0,
+				maxAgentsPerLead: 5,
+				maxDepth: 2,
+				staggerDelayMs: 0,
+				autoNudgeOnMail: false,
+			},
+			worktrees: { baseDir: ".overstory/worktrees" },
+			merge: { mode: "manual" },
+			mulch: { enabled: false, domains: {} },
+			canopy: { enabled: false },
+			taskTracker: { backend: "seeds", enabled: true },
+			watchdog: {
+				tier0Enabled: false,
+				tier0IntervalMs: 30_000,
+				tier1Enabled: false,
+				maxEscalationLevel: 3,
+			},
+			models: {},
+			logging: { verbose: false, redactSecrets: true },
+			runtime: { default: "claude" },
+			providers: {},
+		})) as unknown as typeof import("../config.ts").loadConfig;
+	}
+
+	async function writeManifest(projectRoot: string): Promise<void> {
+		mkdirSync(join(projectRoot, ".overstory"), { recursive: true });
+		mkdirSync(join(projectRoot, "agents"), { recursive: true });
+		await Bun.write(join(projectRoot, "agents", "builder.md"), "# Builder\n");
+		await Bun.write(
+			join(projectRoot, ".overstory", "agent-manifest.json"),
+			JSON.stringify(
+				{
+					version: "1",
+					agents: {
+						builder: {
+							file: "builder.md",
+							model: "claude-sonnet",
+							tools: [],
+							capabilities: ["build"],
+							canSpawn: false,
+							constraints: [],
+						},
+					},
+				},
+				null,
+				"\t",
+			),
+		);
+	}
+
+	test("routes builder nudge through runTurn when flag is on", async () => {
+		writeSessionsToStore(tempDir, [makeSession({ state: "working", capability: "builder" })]);
+		await writeManifest(tempDir);
+
+		const calls: Array<{ userTurnNdjson: string }> = [];
+		const stubRunTurn = async (opts: import("../agents/turn-runner.ts").RunTurnOpts) => {
+			calls.push({ userTurnNdjson: opts.userTurnNdjson });
+			return {
+				exitCode: 0,
+				cleanResult: true,
+				newSessionId: null,
+				resumeMismatch: false,
+				terminalMailObserved: false,
+				durationMs: 1,
+				initialState: "booting" as const,
+				finalState: "working" as const,
+				stallAborted: false,
+				terminalMailMissing: false,
+			};
+		};
+
+		const { nudgeAgent } = await importNudge();
+		const result = await nudgeAgent(tempDir, "test-agent", "please pivot", true, {
+			_loadConfig: fakeLoadConfig(),
+			_runTurnFn: stubRunTurn,
+		});
+
+		expect(result.delivered).toBe(true);
+		expect(calls.length).toBe(1);
+		const parsed = JSON.parse(calls[0]?.userTurnNdjson?.trimEnd() ?? "");
+		expect(parsed.type).toBe("user");
+		expect(parsed.message.content[0].text).toBe("please pivot");
+	});
+
+	test("task-scoped non-builder capability (scout) IS routed to spawn-per-turn", async () => {
+		writeSessionsToStore(tempDir, [
+			makeSession({ state: "working", capability: "scout", agentName: "scout-1" }),
+		]);
+		await writeManifest(tempDir);
+
+		let runTurnCalled = false;
+		const stubRunTurn = async () => {
+			runTurnCalled = true;
+			return {
+				exitCode: 0,
+				cleanResult: true,
+				newSessionId: null,
+				resumeMismatch: false,
+				terminalMailObserved: false,
+				durationMs: 1,
+				initialState: "booting" as const,
+				finalState: "working" as const,
+				stallAborted: false,
+				terminalMailMissing: false,
+			};
+		};
+
+		const { nudgeAgent } = await importNudge();
+		await nudgeAgent(tempDir, "scout-1", "ping", true, {
+			_loadConfig: fakeLoadConfig(),
+			_runTurnFn: stubRunTurn,
+		});
+
+		expect(runTurnCalled).toBe(true);
+	});
+
+	test("persistent capability (coordinator) is NOT routed to spawn-per-turn", async () => {
+		writeSessionsToStore(tempDir, [
+			makeSession({ state: "working", capability: "coordinator", agentName: "coord-1" }),
+		]);
+		await writeManifest(tempDir);
+
+		let runTurnCalled = false;
+		const stubRunTurn = async () => {
+			runTurnCalled = true;
+			return {
+				exitCode: 0,
+				cleanResult: true,
+				newSessionId: null,
+				resumeMismatch: false,
+				terminalMailObserved: false,
+				durationMs: 1,
+				initialState: "booting" as const,
+				finalState: "working" as const,
+				stallAborted: false,
+				terminalMailMissing: false,
+			};
+		};
+
+		const { nudgeAgent } = await importNudge();
+		await nudgeAgent(tempDir, "coord-1", "ping", true, {
+			_loadConfig: fakeLoadConfig(),
+			_runTurnFn: stubRunTurn,
+		});
+
+		expect(runTurnCalled).toBe(false);
+	});
+
+	test("returns delivery error when runTurn throws", async () => {
+		writeSessionsToStore(tempDir, [makeSession({ state: "working", capability: "builder" })]);
+		await writeManifest(tempDir);
+
+		const stubRunTurn = async (): Promise<never> => {
+			throw new Error("simulated spawn failure");
+		};
+
+		const { nudgeAgent } = await importNudge();
+		const result = await nudgeAgent(tempDir, "test-agent", "ping", true, {
+			_loadConfig: fakeLoadConfig(),
+			_runTurnFn: stubRunTurn,
+		});
+
+		expect(result.delivered).toBe(false);
+		expect(result.reason).toContain("Spawn-per-turn dispatch failed");
+		expect(result.reason).toContain("simulated spawn failure");
+	});
+});