@os-eco/overstory-cli 0.9.4 → 0.11.0

package/src/commands/stop.test.ts

@@ -15,9 +15,11 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir, realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { AgentError, ValidationError } from "../errors.ts";
+import { createMailClient } from "../mail/client.ts";
+import { createMailStore } from "../mail/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
-import type { AgentSession } from "../types.ts";
+import type { AgentSession, MergeReadyPayload } from "../types.ts";
 import { type StopDeps, stopCommand } from "./stop.ts";
 
 // --- Fake Git (for branch deletion) ---
@@ -472,6 +474,258 @@ describe("stopCommand stop behavior", () => {
 		store.close();
 		expect(updated?.state).toBe("completed");
 	});
+
+	test("stopping a lead writes lead_completed pending-nudge for coordinator", async () => {
+		// Regression test for overstory-49a7:
+		// The lead_completed nudge now fires from `ov stop` (real completion signal),
+		// not from the per-turn Stop hook, which was spamming the coordinator.
+		const session = makeAgentSession({
+			agentName: "lead-alpha",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-alpha",
+		});
+		saveSessionsToDb([session]);
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-alpha", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const markerFile = Bun.file(markerPath);
+		expect(await markerFile.exists()).toBe(true);
+
+		const marker = JSON.parse(await markerFile.text());
+		expect(marker.from).toBe("lead-alpha");
+		expect(marker.reason).toBe("lead_completed");
+		expect(marker.subject).toContain("lead-alpha");
+		expect(marker.messageId).toContain("auto-nudge-lead-alpha-");
+		expect(marker.createdAt).toBeDefined();
+	});
+
+	test("lead exiting without merge_ready gets 'no merge_ready sent' subject (overstory-41fe)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-beta",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-beta",
+		});
+		saveSessionsToDb([session]);
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-beta", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toBe(
+			"Lead lead-beta exited — no merge_ready sent, needs coordinator follow-up",
+		);
+	});
+
+	test("lead with one merge_ready gets branch-specific subject (overstory-41fe)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-gamma",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-gamma",
+		});
+		saveSessionsToDb([session]);
+
+		// Seed mail.db with a merge_ready message from this lead
+		const mailStore = createMailStore(join(overstoryDir, "mail.db"));
+		const mailClient = createMailClient(mailStore);
+		const payload: MergeReadyPayload = {
+			branch: "overstory/lead-gamma/bead-42",
+			taskId: "bead-42",
+			agentName: "lead-gamma",
+			filesModified: ["src/foo.ts"],
+		};
+		mailClient.sendProtocol({
+			from: "lead-gamma",
+			to: "coordinator",
+			subject: "merge_ready: bead-42",
+			body: "ready",
+			type: "merge_ready",
+			payload,
+		});
+		mailClient.close();
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-gamma", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toBe(
+			"Lead lead-gamma sent merge_ready for branch overstory/lead-gamma/bead-42",
+		);
+	});
+
+	test("lead with multiple merge_ready messages lists all unique branches (overstory-41fe)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-delta",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-delta",
+		});
+		saveSessionsToDb([session]);
+
+		const mailStore = createMailStore(join(overstoryDir, "mail.db"));
+		const mailClient = createMailClient(mailStore);
+		for (const branch of ["overstory/worker-a/t1", "overstory/worker-b/t2"]) {
+			mailClient.sendProtocol({
+				from: "lead-delta",
+				to: "coordinator",
+				subject: `merge_ready: ${branch}`,
+				body: "ready",
+				type: "merge_ready",
+				payload: {
+					branch,
+					taskId: branch.split("/")[2] ?? "unknown",
+					agentName: "lead-delta",
+					filesModified: [],
+				},
+			});
+		}
+		mailClient.close();
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-delta", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toContain("Lead lead-delta sent 2 merge_ready");
+		expect(marker.subject).toContain("overstory/worker-a/t1");
+		expect(marker.subject).toContain("overstory/worker-b/t2");
+	});
+
+	test("merge_ready messages from other agents do not influence the subject (overstory-41fe)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-eps",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-eps",
+		});
+		saveSessionsToDb([session]);
+
+		// A *different* lead has merge_ready in the same mail.db — should be ignored
+		const mailStore = createMailStore(join(overstoryDir, "mail.db"));
+		const mailClient = createMailClient(mailStore);
+		mailClient.sendProtocol({
+			from: "some-other-lead",
+			to: "coordinator",
+			subject: "merge_ready: x",
+			body: "ready",
+			type: "merge_ready",
+			payload: {
+				branch: "overstory/other/x",
+				taskId: "x",
+				agentName: "some-other-lead",
+				filesModified: [],
+			},
+		});
+		mailClient.close();
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-eps", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toBe(
+			"Lead lead-eps exited — no merge_ready sent, needs coordinator follow-up",
+		);
+	});
+
+	test("lead falls back to historical subject when mail store cannot be opened (overstory-7291)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-zeta",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-zeta",
+		});
+		saveSessionsToDb([session]);
+
+		// Make mail.db un-openable by creating a directory at that path. SQLite
+		// cannot open a directory as a database, so createMailStore() throws and
+		// buildLeadCompletedSubject hits its outer-catch fallback.
+		const mailDbPath = join(overstoryDir, "mail.db");
+		await mkdir(mailDbPath, { recursive: true });
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-zeta", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toBe(
+			"Lead lead-zeta completed — check mail for merge_ready/worker_done",
+		);
+	});
+
+	test("lead with malformed merge_ready payload skips that message (overstory-7291)", async () => {
+		const session = makeAgentSession({
+			agentName: "lead-eta",
+			capability: "lead",
+			state: "working",
+			tmuxSession: "overstory-lead-eta",
+		});
+		saveSessionsToDb([session]);
+
+		// Insert two merge_ready rows directly via the store: one with a valid
+		// MergeReadyPayload, one with a non-JSON payload string. sendProtocol
+		// would JSON.stringify any payload, so it cannot produce a malformed
+		// row — the low-level store accepts the payload column verbatim. The
+		// loop must skip the malformed one (inner catch + continue) and use
+		// the valid one, yielding the single-branch subject variant.
+		const mailStore = createMailStore(join(overstoryDir, "mail.db"));
+		const validPayload: MergeReadyPayload = {
+			branch: "overstory/lead-eta/bead-99",
+			taskId: "bead-99",
+			agentName: "lead-eta",
+			filesModified: ["src/x.ts"],
+		};
+		mailStore.insert({
+			id: "msg-valid",
+			from: "lead-eta",
+			to: "coordinator",
+			subject: "merge_ready: bead-99",
+			body: "ready",
+			type: "merge_ready",
+			priority: "normal",
+			threadId: null,
+			payload: JSON.stringify(validPayload),
+		});
+		mailStore.insert({
+			id: "msg-malformed",
+			from: "lead-eta",
+			to: "coordinator",
+			subject: "merge_ready: broken",
+			body: "ready",
+			type: "merge_ready",
+			priority: "normal",
+			threadId: null,
+			payload: "not-json{",
+		});
+		mailStore.close();
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("lead-eta", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const marker = JSON.parse(await Bun.file(markerPath).text());
+		expect(marker.subject).toBe(
+			"Lead lead-eta sent merge_ready for branch overstory/lead-eta/bead-99",
+		);
+	});
+
+	test("stopping a non-lead agent does NOT write lead_completed pending-nudge", async () => {
+		const session = makeAgentSession({ state: "working", capability: "builder" });
+		saveSessionsToDb([session]);
+
+		const { deps } = makeDeps({ [session.tmuxSession]: true });
+		await stopCommand("my-builder", {}, deps);
+
+		const markerPath = join(overstoryDir, "pending-nudges", "coordinator.json");
+		const markerFile = Bun.file(markerPath);
+		expect(await markerFile.exists()).toBe(false);
+	});
 });
 
 describe("stopCommand --json output", () => {

package/src/commands/stop.ts

@@ -12,12 +12,16 @@
  * With --clean-worktree, completed agents skip the kill step and proceed to cleanup.
  */
 
+import { unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { jsonOutput } from "../json.ts";
 import { printSuccess, printWarning } from "../logging/color.ts";
+import { createMailStore } from "../mail/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
+import type { MergeReadyPayload } from "../types.ts";
+import { readPidFile } from "../utils/pid.ts";
 import { removeWorktree } from "../worktree/manager.ts";
 import { isProcessAlive, isSessionAlive, killProcessTree, killSession } from "../worktree/tmux.ts";
 
@@ -49,6 +53,56 @@ export interface StopDeps {
 	};
 }
 
+/**
+ * Build the lead_completed nudge subject based on whether the lead actually sent
+ * merge_ready before exiting (overstory-41fe). The merge_ready close-gate
+ * (commit 3e21338) prevents leads from running `sd close` without it, but a
+ * lead can still exit (process termination, watchdog kill, manual `ov stop`)
+ * without ever having sent one. The coordinator's surfacing of this nudge
+ * needs to distinguish those two cases.
+ */
+function buildLeadCompletedSubject(agentName: string, mailDbPath: string): string {
+	let mergeReadyBranches: string[] = [];
+	let mergeReadyCount = 0;
+	try {
+		const store = createMailStore(mailDbPath);
+		try {
+			const messages = store.getAll({ from: agentName, type: "merge_ready" });
+			mergeReadyCount = messages.length;
+			for (const msg of messages) {
+				if (msg.payload === null) continue;
+				try {
+					const parsed = JSON.parse(msg.payload) as Partial<MergeReadyPayload>;
+					if (typeof parsed.branch === "string" && parsed.branch.length > 0) {
+						mergeReadyBranches.push(parsed.branch);
+					}
+				} catch {
+					// Skip messages with unparseable payloads
+				}
+			}
+		} finally {
+			store.close();
+		}
+	} catch {
+		// If the mail store can't be opened (corrupt db, permissions), fall back
+		// to the historical ambiguous phrasing rather than blocking the stop.
+		return `Lead ${agentName} completed — check mail for merge_ready/worker_done`;
+	}
+
+	if (mergeReadyCount === 0) {
+		return `Lead ${agentName} exited — no merge_ready sent, needs coordinator follow-up`;
+	}
+	// Dedupe in case a lead resent merge_ready for the same branch
+	mergeReadyBranches = Array.from(new Set(mergeReadyBranches));
+	if (mergeReadyBranches.length === 0) {
+		return `Lead ${agentName} sent ${mergeReadyCount} merge_ready (branch unknown)`;
+	}
+	if (mergeReadyBranches.length === 1) {
+		return `Lead ${agentName} sent merge_ready for branch ${mergeReadyBranches[0]}`;
+	}
+	return `Lead ${agentName} sent ${mergeReadyBranches.length} merge_ready (branches: ${mergeReadyBranches.join(", ")})`;
+}
+
 /** Delete a git branch (best-effort, non-fatal). */
 async function deleteBranchBestEffort(repoRoot: string, branch: string): Promise<boolean> {
 	try {
@@ -115,20 +169,35 @@ export async function stopCommand(
 		}
 
 		const isZombie = session.state === "zombie";
-		const isHeadless = session.tmuxSession === "" && session.pid !== null;
+		// Headless task-scoped agents (Phase 3 spawn-per-turn): tmuxSession is ""
+		// and session.pid is null between turns. The live PID for an in-flight
+		// turn is published at .overstory/agents/<name>/turn.pid. Sapling RPC
+		// agents still use session.pid for their long-lived process.
+		const isHeadless = session.tmuxSession === "";
+		const turnPidPath = join(overstoryDir, "agents", agentName, "turn.pid");
 
 		let tmuxKilled = false;
 		let pidKilled = false;
 
 		// Skip kill operations for already-completed agents (process/tmux already gone)
 		if (!isAlreadyCompleted) {
-			if (isHeadless && session.pid !== null) {
-				// Headless agent: kill via process tree instead of tmux
-				const alive = proc.isAlive(session.pid);
-				if (alive) {
-					await proc.killTree(session.pid);
+			if (isHeadless) {
+				// Prefer the per-turn PID file (Phase 3) — this catches an in-flight
+				// claude turn for any task-scoped capability. Fall back to the
+				// session row's pid for legacy/long-lived headless runtimes (Sapling).
+				const turnPid = await readPidFile(turnPidPath);
+				const targetPid = turnPid ?? session.pid;
+				if (targetPid !== null && proc.isAlive(targetPid)) {
+					await proc.killTree(targetPid);
 					pidKilled = true;
 				}
+				// Reap the turn.pid file so a subsequent ov stop / mail injector
+				// doesn't see a stale entry. Idempotent.
+				try {
+					await unlink(turnPidPath);
+				} catch {
+					// already gone — non-fatal
+				}
 			} else {
 				// TUI agent: kill via tmux session
 				const alive = await tmux.isSessionAlive(session.tmuxSession);
@@ -138,9 +207,39 @@ export async function stopCommand(
 				}
 			}
 
-			// Mark session as completed
-			store.updateState(agentName, "completed");
+			// Mark session as completed via the guarded transition. `completed` is
+			// reachable from every non-completed state (including zombie, so `ov
+			// stop` can promote a watchdog-flagged zombie to a clean completion),
+			// so the only way this rejects is if state is already `completed` —
+			// which is the no-op we want anyway. Race-safe under overstory-a993.
+			store.tryTransitionState(agentName, "completed");
 			store.updateLastActivity(agentName);
+
+			// Auto-nudge coordinator when a lead truly completes so it wakes up
+			// to process merge_ready / worker_done messages without waiting for
+			// user input. Fires from `ov stop` (real completion signal) rather
+			// than the per-turn Stop hook, which was spamming the coordinator
+			// (overstory-49a7).
+			if (session.capability === "lead") {
+				try {
+					const mailDbPath = join(overstoryDir, "mail.db");
+					const subject = buildLeadCompletedSubject(agentName, mailDbPath);
+					const nudgesDir = join(overstoryDir, "pending-nudges");
+					const { mkdir } = await import("node:fs/promises");
+					await mkdir(nudgesDir, { recursive: true });
+					const markerPath = join(nudgesDir, "coordinator.json");
+					const marker = {
+						from: agentName,
+						reason: "lead_completed",
+						subject,
+						messageId: `auto-nudge-${agentName}-${Date.now()}`,
+						createdAt: new Date().toISOString(),
+					};
+					await Bun.write(markerPath, `${JSON.stringify(marker, null, "\t")}\n`);
+				} catch {
+					// Non-fatal: nudge failure should not break stop
+				}
+			}
 		}
 
 		// Optionally remove worktree and branch (best-effort, non-fatal)

package/src/commands/watch.test.ts

@@ -88,6 +88,7 @@ describe("watchCommand", () => {
 		expect(out).toContain("watch");
 		expect(out).toContain("--interval");
 		expect(out).toContain("--background");
+		expect(out).toContain("--kill-others");
 		expect(out).toContain("Tier 0");
 	});
 
@@ -113,6 +114,48 @@ describe("watchCommand", () => {
 		expect(process.exitCode).toBe(1);
 	});
 
+	test("foreground mode: refuses when a live foreign PID owns the lock", async () => {
+		// Spawn a long-running child to act as the "foreign live process". Its
+		// PID will not match our own, so acquirePidLock should refuse rather
+		// than treat the existing PID as idempotent self-ownership. The
+		// foreground path used to overwrite this file unconditionally — the
+		// overstory-8ef6 fix forces it to refuse.
+		const sleeper = Bun.spawn(["sleep", "30"], {
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		try {
+			const pidFilePath = join(tempDir, ".overstory", "watchdog.pid");
+			await Bun.write(pidFilePath, `${sleeper.pid}\n`);
+
+			// --json for structured output. No --background, so this exercises
+			// the foreground exclusion path. A correctly contested lock returns
+			// immediately (exit 1) without starting the daemon loop.
+			await watchCommand(["--json"]);
+
+			const out = output();
+			const jsonLine = out
+				.split("\n")
+				.map((l) => l.trim())
+				.find((l) => l.startsWith("{"));
+			expect(jsonLine).toBeDefined();
+			if (jsonLine) {
+				const parsed = JSON.parse(jsonLine);
+				expect(parsed.running).toBe(true);
+				expect(parsed.pid).toBe(sleeper.pid);
+				expect(parsed.error).toContain("already running");
+			}
+			expect(process.exitCode).toBe(1);
+
+			// PID file untouched — still the foreign owner's PID.
+			const fileContent = await Bun.file(pidFilePath).text();
+			expect(fileContent.trim()).toBe(`${sleeper.pid}`);
+		} finally {
+			sleeper.kill("SIGTERM");
+			await sleeper.exited.catch(() => {});
+		}
+	});
+
 	test("background mode: stale PID cleanup", async () => {
 		// Write a PID file with a non-running process (999999 is very unlikely to exist)
 		const pidFilePath = join(tempDir, ".overstory", "watchdog.pid");