@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/commands/sling.ts

@@ -18,12 +18,13 @@
  * 14. Return AgentSession
  */
 
-import { mkdirSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { buildInitialHeadlessPrompt, formatMailSection } from "../agents/headless-prompt.ts";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
 import { writeOverlay } from "../agents/overlay.ts";
+import { runTurn } from "../agents/turn-runner.ts";
 import { createCanopyClient } from "../canopy/client.ts";
 import { loadConfig } from "../config.ts";
 import { AgentError, HierarchyError, ValidationError } from "../errors.ts";
@@ -38,9 +39,8 @@ import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore } from "../sessions/store.ts";
 import type { TrackerIssue } from "../tracker/factory.ts";
 import { createTrackerClient, resolveBackend, trackerCliName } from "../tracker/factory.ts";
-import type { AgentSession, OverlayConfig } from "../types.ts";
+import type { AgentSession, OverlayConfig, OverstoryConfig } from "../types.ts";
 import { createWorktree, rollbackWorktree } from "../worktree/manager.ts";
-import { spawnHeadlessAgent } from "../worktree/process.ts";
 import {
 	capturePaneContent,
 	checkSessionState,
@@ -48,6 +48,7 @@ import {
 	ensureTmuxAvailable,
 	isSessionAlive,
 	killSession,
+	sanitizeTmuxName,
 	sendKeys,
 	waitForTuiReady,
 } from "../worktree/tmux.ts";
@@ -155,6 +156,21 @@ export interface SlingOptions {
 	noScoutCheck?: boolean;
 	baseBranch?: string;
 	profile?: string;
+	headless?: boolean;
+	recover?: boolean;
+}
+
+const WORKABLE_STATUSES = ["open", "in_progress"] as const;
+
+/**
+ * Decide whether a task with the given tracker status can accept a fresh
+ * sling. Normal dispatch requires an `open` or `in_progress` task; passing
+ * `recover` accepts any status so a coordinator can re-dispatch against a
+ * task whose previous owner exited (e.g. closed by a dead lead). (overstory-629f)
+ */
+export function isTaskWorkable(status: string, recover: boolean): boolean {
+	if (recover) return true;
+	return (WORKABLE_STATUSES as readonly string[]).includes(status);
 }
 
 export interface AutoDispatchOptions {
@@ -464,6 +480,44 @@ export async function getCurrentBranch(repoRoot: string): Promise<string | null>
 	return branch;
 }
 
+/**
+ * Resolve whether to use the headless spawn path for a given runtime + flags + config.
+ *
+ * Precedence (highest first):
+ *   1. runtime.headless === true (statically headless runtimes always use headless)
+ *   2. Explicit --headless / --no-headless flag (boolean | undefined from commander)
+ *   3. config.runtime.claudeHeadlessByDefault (only applies when runtime.id === "claude")
+ *   4. Default: false (tmux)
+ *
+ * Throws ValidationError when --headless is explicitly true but the runtime has no
+ * buildDirectSpawn implementation.
+ */
+export function resolveUseHeadless(
+	runtime: { id: string; headless?: boolean; buildDirectSpawn?: unknown },
+	flag: boolean | undefined,
+	config: OverstoryConfig,
+): boolean {
+	if (runtime.headless === true) return true;
+
+	if (flag === true) {
+		if (typeof runtime.buildDirectSpawn !== "function") {
+			throw new ValidationError(
+				`--headless requires a runtime with headless support. Runtime "${runtime.id}" does not implement buildDirectSpawn.`,
+				{ field: "headless", value: true },
+			);
+		}
+		return true;
+	}
+	if (flag === false) return false;
+
+	if (runtime.id === "claude" && config.runtime?.claudeHeadlessByDefault === true) {
+		if (typeof runtime.buildDirectSpawn !== "function") return false;
+		return true;
+	}
+
+	return false;
+}
+
 /**
  * Entry point for `ov sling <task-id> [flags]`.
  *
@@ -489,6 +543,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 	const forceHierarchy = opts.forceHierarchy ?? false;
 	const skipScout = opts.skipScout ?? false;
 	const skipTaskCheck = opts.skipTaskCheck ?? false;
+	const recover = opts.recover ?? false;
 
 	if (Number.isNaN(depth) || depth < 0) {
 		throw new ValidationError("--depth must be a non-negative integer", {
@@ -739,13 +794,17 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				});
 			}
 
-			const workableStatuses = ["open", "in_progress"];
-			if (!workableStatuses.includes(issue.status)) {
+			if (!isTaskWorkable(issue.status, recover)) {
 				throw new ValidationError(
-					`Task "${taskId}" is not workable (status: ${issue.status}). Only open or in_progress issues can be assigned.`,
+					`Task "${taskId}" is not workable (status: ${issue.status}). Only open or in_progress issues can be assigned. Pass --recover to re-dispatch against a closed task.`,
 					{ field: "taskId", value: taskId },
 				);
 			}
+			if (recover && !(WORKABLE_STATUSES as readonly string[]).includes(issue.status)) {
+				process.stderr.write(
+					`Warning: --recover dispatching against task "${taskId}" with status "${issue.status}". Previous owner may have exited unexpectedly.\n`,
+				);
+			}
 		}
 
 		// 7. Create worktree
@@ -845,12 +904,20 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			// 9. Resolve runtime + model (needed for deployConfig, spawn, and beacon)
 			const resolvedModel = resolveModel(config, manifest, capability, agentDef.model);
 
-			// 9a. Deploy hooks config (capability-specific guards)
+			// 9a. Resolve headless mode before deployConfig so hooks can be skipped for headless agents.
+			// resolveUseHeadless is also used at 11c for spawn routing — hoisted here to share the value.
+			const useHeadless = resolveUseHeadless(runtime, opts.headless, config);
+
+			// 9b. Deploy hooks config (capability-specific guards). In headless mode we deploy
+			// a PreToolUse-only subset (security guards) — overstory-e24b. Headless Claude Code
+			// dispatches settings.local.json hooks, so dropping them would leave destructive
+			// commands unblocked.
 			await runtime.deployConfig(worktreePath, undefined, {
 				agentName: name,
 				capability,
 				worktreePath,
 				qualityGates: config.project.qualityGates,
+				isHeadless: useHeadless,
 			});
 
 			// 9b. Send auto-dispatch mail so it exists when SessionStart hook fires.
@@ -918,41 +985,48 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 			}
 
 			// 11c. Spawn: headless runtimes bypass tmux entirely; tmux path is unchanged.
-			if (runtime.headless === true && runtime.buildDirectSpawn) {
-				const directEnv = {
-					...runtime.buildEnv(resolvedModel),
-					OVERSTORY_AGENT_NAME: name,
-					OVERSTORY_WORKTREE_PATH: worktreePath,
-					OVERSTORY_TASK_ID: taskId,
-				};
-				const argv = runtime.buildDirectSpawn({
-					cwd: worktreePath,
-					env: directEnv,
-					...(resolvedModel.isExplicitOverride ? { model: resolvedModel.model } : {}),
-					instructionPath: runtime.instructionPath,
-				});
-
-				// Create a timestamped log dir for this headless agent session.
-				// Always redirect stdout to a file. This prevents SIGPIPE death:
-				// ov sling exits after spawning, closing the pipe's read end.
-				// If stdout is a pipe, the agent dies on the next write (SIGPIPE).
-				// File writes have no such limit, and the agent survives the CLI exit.
-				//
-				// Note: RPC connection wiring is intentionally omitted here. The RPC pipe
-				// is only useful when the spawner stays alive to consume it. ov sling is
-				// a short-lived CLI — any connection created here dies with the process.
-				const logTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
-				const agentLogDir = join(overstoryDir, "logs", name, logTimestamp);
-				mkdirSync(agentLogDir, { recursive: true });
-
-				const headlessProc = await spawnHeadlessAgent(argv, {
-					cwd: worktreePath,
-					env: { ...(process.env as Record<string, string>), ...directEnv },
-					stdoutFile: join(agentLogDir, "stdout.log"),
-					stderrFile: join(agentLogDir, "stderr.log"),
-				});
+			// useHeadless was resolved at step 9a (hoisted so deployConfig can skip hooks for headless).
+			if (useHeadless && runtime.buildDirectSpawn) {
+				// Phase 3 spawn-per-turn: headless agents have NO long-lived process.
+				// sling builds the initial prompt, upserts the session row in
+				// "booting", then drives the first user turn synchronously through
+				// `runTurn`. The runner spawns claude with `--resume` (when a prior
+				// session id exists), writes the prompt to a real stdin pipe, drains
+				// stream-json, captures session id, transitions state to "working"
+				// (or "completed" if terminal mail observed), and exits. No persistent
+				// process remains after this returns; subsequent turns are driven by
+				// `ov serve` (mail) or `ov nudge`.
+				const priorClaudeSessionId = store.getByName(name)?.claudeSessionId ?? null;
+
+				// Build the initial prompt (mulch expertise + pending mail + beacon)
+				// as the first user turn.
+				const pendingMailStore = createMailStore(join(overstoryDir, "mail.db"));
+				let initialPrompt: string;
+				try {
+					const pendingMailClient = createMailClient(pendingMailStore);
+					const pendingMessages = pendingMailClient.check(name);
+					const mailSection = formatMailSection(pendingMessages);
+					const beacon = buildBeacon({
+						agentName: name,
+						capability,
+						taskId,
+						parentAgent,
+						depth,
+						instructionPath: runtime.instructionPath,
+					});
+					initialPrompt = buildInitialHeadlessPrompt(
+						mulchExpertise,
+						mailSection || undefined,
+						beacon,
+					);
+				} finally {
+					pendingMailStore.close();
+				}
 
-				// 13. Record session with empty tmuxSession (no tmux pane for headless agents).
+				// 13. Record session BEFORE runTurn so the runner reads it under its
+				// lock. pid is null — there is no persistent process; the runner
+				// publishes a per-turn PID via .overstory/agents/<name>/turn.pid for
+				// the duration of each turn. Carry priorClaudeSessionId (mx-5c5ae6).
 				const session: AgentSession = {
 					id: `session-${Date.now()}-${name}`,
 					agentName: name,
@@ -962,7 +1036,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 					taskId: taskId,
 					tmuxSession: "",
 					state: "booting",
-					pid: headlessProc.pid,
+					pid: null,
 					parentAgent: parentAgent,
 					depth,
 					runId,
@@ -971,15 +1045,28 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 					escalationLevel: 0,
 					stalledSince: null,
 					transcriptPath: null,
+					...(priorClaudeSessionId !== null ? { claudeSessionId: priorClaudeSessionId } : {}),
 				};
 				store.upsert(session);
 
-				const runStore = createRunStore(join(overstoryDir, "sessions.db"));
-				try {
-					runStore.incrementAgentCount(runId);
-				} finally {
-					runStore.close();
-				}
+				// Drive the first user turn synchronously. runTurn manages spawn,
+				// stdin write+EOF, event drain, session_id capture, terminal-mail
+				// detection, and state transition.
+				const turnResult = await runTurn({
+					agentName: name,
+					capability,
+					overstoryDir,
+					worktreePath,
+					projectRoot: config.project.root,
+					taskId,
+					userTurnNdjson: initialPrompt,
+					runtime,
+					resolvedModel,
+					runId,
+					mailDbPath: join(overstoryDir, "mail.db"),
+					eventsDbPath: join(overstoryDir, "events.db"),
+					sessionsDbPath: join(overstoryDir, "sessions.db"),
+				});
 
 				// 14. Output result (headless)
 				if (opts.json ?? false) {
@@ -990,21 +1077,26 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 						branch: branchName,
 						worktree: worktreePath,
 						tmuxSession: "",
-						pid: headlessProc.pid,
+						pid: null,
+						initialTurnFinalState: turnResult.finalState,
+						claudeSessionId: turnResult.newSessionId,
 					});
 				} else {
-					printSuccess("Agent launched (headless)", name);
-					process.stdout.write(`   Task:     ${taskId}\n`);
-					process.stdout.write(`   Branch:   ${branchName}\n`);
-					process.stdout.write(`   Worktree: ${worktreePath}\n`);
-					process.stdout.write(`   PID:      ${headlessProc.pid}\n`);
+					printSuccess("Agent launched (headless, spawn-per-turn)", name);
+					process.stdout.write(`   Task:                  ${taskId}\n`);
+					process.stdout.write(`   Branch:                ${branchName}\n`);
+					process.stdout.write(`   Worktree:              ${worktreePath}\n`);
+					process.stdout.write(`   First-turn state:      ${turnResult.finalState}\n`);
+					if (turnResult.newSessionId) {
+						process.stdout.write(`   Claude session id:     ${turnResult.newSessionId}\n`);
+					}
 				}
 			} else {
 				// 11c. Preflight: verify tmux is available before attempting session creation
 				await ensureTmuxAvailable();
 
 				// 12. Create tmux session running claude in interactive mode
-				const tmuxSessionName = `overstory-${config.project.name}-${name}`;
+				const tmuxSessionName = `overstory-${sanitizeTmuxName(config.project.name)}-${name}`;
 				const spawnCmd = runtime.buildSpawnCommand({
 					model: resolvedModel.model,
 					permissionMode: "bypass",
@@ -1015,6 +1107,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 						OVERSTORY_AGENT_NAME: name,
 						OVERSTORY_WORKTREE_PATH: worktreePath,
 						OVERSTORY_TASK_ID: taskId,
+						OVERSTORY_PROJECT_ROOT: config.project.root,
 					},
 				});
 				const pid = await createSession(tmuxSessionName, worktreePath, spawnCmd, {
@@ -1022,6 +1115,7 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 					OVERSTORY_AGENT_NAME: name,
 					OVERSTORY_WORKTREE_PATH: worktreePath,
 					OVERSTORY_TASK_ID: taskId,
+					OVERSTORY_PROJECT_ROOT: config.project.root,
 				});
 
 				// 13. Record session BEFORE sending the beacon so that hook-triggered
@@ -1050,14 +1144,6 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 
 				store.upsert(session);
 
-				// Increment agent count for the run
-				const runStore = createRunStore(join(overstoryDir, "sessions.db"));
-				try {
-					runStore.incrementAgentCount(runId);
-				} finally {
-					runStore.close();
-				}
-
 				// 13b. Give slow shells time to finish initializing before polling for TUI readiness.
 				const shellDelay = config.runtime?.shellInitDelayMs ?? 0;
 				if (shellDelay > 0) {
@@ -1072,7 +1158,10 @@ export async function slingCommand(taskId: string, opts: SlingOptions): Promise<
 				);
 				if (!tuiReady) {
 					const alive = await isSessionAlive(tmuxSessionName);
-					store.updateState(name, "completed");
+					// Mark as zombie (not completed) so the watchdog detects this failed
+					// startup. 'completed' is a terminal success state that the watchdog
+					// skips entirely (overstory-c40e).
+					store.updateState(name, "zombie");
 
 					if (alive) {
 						await killSession(tmuxSessionName);

package/src/commands/status.test.ts

@@ -51,6 +51,7 @@ function makeStatusData(overrides: Partial<StatusData> = {}): StatusData {
 		worktrees: [],
 		tmuxSessions: [{ name: "overstory-test-builder", pid: 12345 }],
 		unreadMailCount: 0,
+		unreadMailScope: "orchestrator",
 		mergeQueueCount: 0,
 		recentMetricsCount: 0,
 		...overrides,
@@ -90,6 +91,12 @@ describe("printStatus", () => {
 		expect(out).not.toContain("Mail sent:");
 	});
 
+	test("Mail line names the scope agent so per-agent scope is unambiguous", () => {
+		const data = makeStatusData({ unreadMailCount: 3, unreadMailScope: "lead-1" });
+		printStatus(data);
+		expect(stripAnsi(output())).toContain("Mail: 3 unread (to lead-1)");
+	});
+
 	test("verbose: shows worktree path, logs dir, and mail timestamps", () => {
 		const detail: VerboseAgentDetail = {
 			worktreePath: "/tmp/worktrees/test-builder",
@@ -208,6 +215,7 @@ describe("--verbose --json", () => {
 			worktrees: [],
 			tmuxSessions: [],
 			unreadMailCount: 0,
+			unreadMailScope: "orchestrator",
 			mergeQueueCount: 0,
 			recentMetricsCount: 0,
 			verboseDetails: { agent: detail },
@@ -226,6 +234,7 @@ describe("--verbose --json", () => {
 			worktrees: [],
 			tmuxSessions: [],
 			unreadMailCount: 0,
+			unreadMailScope: "orchestrator",
 			mergeQueueCount: 0,
 			recentMetricsCount: 0,
 		};

package/src/commands/status.ts

@@ -84,6 +84,7 @@ export interface StatusData {
 	worktrees: Array<{ path: string; branch: string; head: string }>;
 	tmuxSessions: Array<{ name: string; pid: number }>;
 	unreadMailCount: number;
+	unreadMailScope: string;
 	mergeQueueCount: number;
 	recentMetricsCount: number;
 	verboseDetails?: Record<string, VerboseAgentDetail>;
@@ -228,6 +229,7 @@ export async function gatherStatus(
 			worktrees,
 			tmuxSessions,
 			unreadMailCount,
+			unreadMailScope: agentName,
 			mergeQueueCount,
 			recentMetricsCount,
 			verboseDetails,
@@ -260,10 +262,14 @@ export function printStatus(data: StatusData): void {
 					? new Date(agent.lastActivity).getTime()
 					: now;
 			const duration = formatDuration(endTime - new Date(agent.startedAt).getTime());
+			// See dashboard.ts for the three-topology liveness rationale (overstory-7a34).
 			const isHeadless = agent.tmuxSession === "" && agent.pid !== null;
-			const alive = isHeadless
-				? agent.pid !== null && isProcessAlive(agent.pid)
-				: tmuxSessionNames.has(agent.tmuxSession);
+			const isSpawnPerTurn = agent.tmuxSession === "" && agent.pid === null;
+			const alive = isSpawnPerTurn
+				? agent.state !== "zombie" && agent.state !== "completed"
+				: isHeadless
+					? agent.pid !== null && isProcessAlive(agent.pid)
+					: tmuxSessionNames.has(agent.tmuxSession);
 			const aliveMarker = alive ? color.green(">") : color.red("x");
 			w(`   ${aliveMarker} ${accent(agent.agentName)} [${agent.capability}] `);
 			w(`${agent.state} | ${accent(agent.taskId)} | ${duration}\n`);
@@ -293,7 +299,9 @@ export function printStatus(data: StatusData): void {
 	w("\n");
 
 	// Mail
-	w(`Mail: ${data.unreadMailCount} unread\n`);
+	// Scope is per-agent (the orchestrator by default). Differs from `ov mail list
+	// --unread` (system-wide) and `ov mail check` (per-agent, marks as read).
+	w(`Mail: ${data.unreadMailCount} unread (to ${data.unreadMailScope})\n`);
 
 	// Merge queue
 	w(`Merge queue: ${data.mergeQueueCount} pending\n`);

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,177 @@ 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("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", () => {