@katyella/legio 0.1.3 → 0.2.2

package/src/{watchdog → watchman}/daemon.test.ts

@@ -1,12 +1,13 @@
 /**
- * Integration tests for the watchdog daemon tick loop.
+ * Integration tests for the unified watchman daemon (health + mail + beacon).
  *
  * Uses real filesystem (temp directories via mkdtemp) and real SessionStore
  * (better-sqlite3) for session persistence, plus real health evaluation logic.
+ * Uses real SQLite for MailStore in mail tick tests.
  *
- * Only tmux operations (isSessionAlive, killSession) are mocked via dependency
- * injection (_tmux params) because real tmux interferes with developer sessions
- * and is fragile in CI.
+ * Only tmux operations (isSessionAlive, killSession, capturePaneContent, sendKeys)
+ * are mocked via dependency injection (_tmux params) because real tmux interferes
+ * with developer sessions and is fragile in CI.
  *
  * Does NOT use mock.module() — it leaks across test files. See mulch record
  * mx-56558b for background.
@@ -17,9 +18,10 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import { createEventStore } from "../events/store.ts";
+import { createMailStore, type MailStore } from "../mail/store.ts";
 import { createSessionStore } from "../sessions/store.ts";
 import type { AgentSession, HealthCheck, SessionCheckpoint, StoredEvent } from "../types.ts";
-import { runDaemonTick } from "./daemon.ts";
+import { type AgentMailState, runDaemonTick, runMailTick, type WatchmanOptions } from "./daemon.ts";
 
 // === Test constants ===
 
@@ -119,7 +121,7 @@ function tmuxWithLiveness(aliveMap: Record<string, boolean>): {
 	};
 }
 
-// === Tests ===
+// === Health tick tests ===
 
 let tempRoot: string;
 
@@ -131,11 +133,8 @@ afterEach(async () => {
 	await rm(tempRoot, { recursive: true, force: true });
 });
 
-describe("daemon tick", () => {
-	// --- Test 1: tick with no sessions file ---
-
+describe("daemon health tick", () => {
 	test("tick with no sessions is a graceful no-op", async () => {
-		// No sessions in the store — daemon should not crash
 		const checks: HealthCheck[] = [];
 
 		await runDaemonTick({
@@ -145,12 +144,9 @@ describe("daemon tick", () => {
 			_tmux: tmuxAllAlive(),
 		});
 
-		// No health checks should have been produced (no sessions to check)
 		expect(checks).toHaveLength(0);
 	});
 
-	// --- Test 2: tick with healthy sessions ---
-
 	test("tick with healthy sessions produces no state changes", async () => {
 		const session = makeSession({
 			state: "working",
@@ -174,14 +170,11 @@ describe("daemon tick", () => {
 		expect(check?.state).toBe("working");
 		expect(check?.action).toBe("none");
 
-		// Session state should be unchanged because state didn't change.
 		const reloaded = readSessionsFromStore(tempRoot);
 		expect(reloaded).toHaveLength(1);
 		expect(reloaded[0]?.state).toBe("working");
 	});
 
-	// --- Test 3: tick with dead tmux -> zombie transition ---
-
 	test("tick with dead tmux transitions session to zombie and fires terminate", async () => {
 		const session = makeSession({
 			agentName: "dead-agent",
@@ -202,23 +195,18 @@ describe("daemon tick", () => {
 			_tmux: tmuxMock,
 		});
 
-		// Health check should detect zombie with terminate action
 		expect(checks).toHaveLength(1);
 		expect(checks[0]?.state).toBe("zombie");
 		expect(checks[0]?.action).toBe("terminate");
 
-		// tmux is dead so killSession should NOT be called (only kills if tmuxAlive)
 		expect(tmuxMock.killed).toHaveLength(0);
 
-		// Session state should be persisted as zombie
 		const reloaded = readSessionsFromStore(tempRoot);
 		expect(reloaded).toHaveLength(1);
 		expect(reloaded[0]?.state).toBe("zombie");
 	});
 
 	test("tick with alive tmux but zombie-old activity calls killSession", async () => {
-		// tmux IS alive but time-based zombie threshold is exceeded,
-		// causing a terminate action — killSession SHOULD be called.
 		const oldActivity = new Date(Date.now() - 200_000).toISOString();
 		const session = makeSession({
 			agentName: "zombie-agent",
@@ -242,16 +230,12 @@ describe("daemon tick", () => {
 		expect(checks).toHaveLength(1);
 		expect(checks[0]?.action).toBe("terminate");
 
-		// tmux was alive, so killSession SHOULD have been called
 		expect(tmuxMock.killed).toContain("legio-zombie-agent");
 
-		// Session persisted as zombie
 		const reloaded = readSessionsFromStore(tempRoot);
 		expect(reloaded[0]?.state).toBe("zombie");
 	});
 
-	// --- Test 4: session persistence round-trip ---
-
 	test("session persistence round-trip: load, modify, save, reload", async () => {
 		const sessions: AgentSession[] = [
 			makeSession({
@@ -266,7 +250,6 @@ describe("daemon tick", () => {
 				agentName: "agent-beta",
 				tmuxSession: "legio-agent-beta",
 				state: "working",
-				// Make beta's tmux dead so it transitions to zombie
 				lastActivity: new Date().toISOString(),
 			}),
 			makeSession({
@@ -282,8 +265,8 @@ describe("daemon tick", () => {
 
 		const tmuxMock = tmuxWithLiveness({
 			"legio-agent-alpha": true,
-			"legio-agent-beta": false, // Dead — should become zombie
-			"legio-agent-gamma": true, // Doesn't matter — completed is skipped
+			"legio-agent-beta": false,
+			"legio-agent-gamma": true,
 		});
 
 		const checks: HealthCheck[] = [];
@@ -295,10 +278,8 @@ describe("daemon tick", () => {
 			_tmux: tmuxMock,
 		});
 
-		// Completed sessions are skipped — only 2 health checks
 		expect(checks).toHaveLength(2);
 
-		// Reload and verify persistence
 		const reloaded = readSessionsFromStore(tempRoot);
 		expect(reloaded).toHaveLength(3);
 
@@ -306,42 +287,11 @@ describe("daemon tick", () => {
 		const beta = reloaded.find((s) => s.agentName === "agent-beta");
 		const gamma = reloaded.find((s) => s.agentName === "agent-gamma");
 
-		expect(alpha).toBeDefined();
-		expect(beta).toBeDefined();
-		expect(gamma).toBeDefined();
-
-		// Alpha: tmux alive + recent activity — stays working
 		expect(alpha?.state).toBe("working");
-
-		// Beta: tmux dead — zombie (ZFC rule 1)
 		expect(beta?.state).toBe("zombie");
-
-		// Gamma: completed — unchanged (skipped by daemon)
 		expect(gamma?.state).toBe("completed");
 	});
 
-	test("session persistence: state unchanged when nothing changes", async () => {
-		const session = makeSession({
-			state: "working",
-			lastActivity: new Date().toISOString(),
-		});
-
-		writeSessionsToStore(tempRoot, [session]);
-
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			_tmux: tmuxAllAlive(),
-		});
-
-		// Session state should remain unchanged since nothing triggered a transition
-		const reloaded = readSessionsFromStore(tempRoot);
-		expect(reloaded).toHaveLength(1);
-		expect(reloaded[0]?.state).toBe("working");
-	});
-
-	// --- Edge cases ---
-
 	test("completed sessions are skipped entirely", async () => {
 		const session = makeSession({ state: "completed" });
 
@@ -353,99 +303,15 @@ describe("daemon tick", () => {
 			root: tempRoot,
 			...THRESHOLDS,
 			onHealthCheck: (c) => checks.push(c),
-			_tmux: tmuxAllDead(), // Would be zombie if not skipped
+			_tmux: tmuxAllDead(),
 		});
 
-		// No health checks emitted for completed sessions
 		expect(checks).toHaveLength(0);
 
-		// State unchanged
 		const reloaded = readSessionsFromStore(tempRoot);
 		expect(reloaded[0]?.state).toBe("completed");
 	});
 
-	test("multiple sessions with mixed states are all processed", async () => {
-		const now = Date.now();
-		const sessions: AgentSession[] = [
-			makeSession({
-				id: "s1",
-				agentName: "healthy",
-				tmuxSession: "legio-healthy",
-				state: "working",
-				lastActivity: new Date(now).toISOString(),
-			}),
-			makeSession({
-				id: "s2",
-				agentName: "dying",
-				tmuxSession: "legio-dying",
-				state: "working",
-				lastActivity: new Date(now).toISOString(),
-			}),
-			makeSession({
-				id: "s3",
-				agentName: "stale",
-				tmuxSession: "legio-stale",
-				state: "working",
-				lastActivity: new Date(now - 60_000).toISOString(),
-			}),
-			makeSession({
-				id: "s4",
-				agentName: "done",
-				tmuxSession: "legio-done",
-				state: "completed",
-			}),
-		];
-
-		writeSessionsToStore(tempRoot, sessions);
-
-		const tmuxMock = tmuxWithLiveness({
-			"legio-healthy": true,
-			"legio-dying": false,
-			"legio-stale": true,
-			"legio-done": false,
-		});
-
-		const checks: HealthCheck[] = [];
-
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			onHealthCheck: (c) => checks.push(c),
-			_tmux: tmuxMock,
-		});
-
-		// 3 non-completed sessions processed
-		expect(checks).toHaveLength(3);
-
-		const reloaded = readSessionsFromStore(tempRoot);
-
-		const healthy = reloaded.find((s) => s.agentName === "healthy");
-		const dying = reloaded.find((s) => s.agentName === "dying");
-		const stale = reloaded.find((s) => s.agentName === "stale");
-		const done = reloaded.find((s) => s.agentName === "done");
-
-		expect(healthy?.state).toBe("working");
-		expect(dying?.state).toBe("zombie");
-		// 60s old activity is below zombieMs (120s) — session stays working
-		expect(stale?.state).toBe("working");
-		expect(done?.state).toBe("completed");
-	});
-
-	test("empty sessions array is a no-op", async () => {
-		writeSessionsToStore(tempRoot, []);
-
-		const checks: HealthCheck[] = [];
-
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			onHealthCheck: (c) => checks.push(c),
-			_tmux: tmuxAllAlive(),
-		});
-
-		expect(checks).toHaveLength(0);
-	});
-
 	test("booting session with recent activity transitions to working", async () => {
 		const session = makeSession({
 			state: "booting",
@@ -470,24 +336,8 @@ describe("daemon tick", () => {
 		expect(reloaded[0]?.state).toBe("working");
 	});
 
-	// --- Backward compatibility ---
-
-	test("sessions with default escalation fields are processed correctly", async () => {
-		// Write a session with default (zero) escalation fields
-		const session = makeSession({
-			id: "session-old",
-			agentName: "old-agent",
-			worktreePath: "/tmp/test",
-			branchName: "legio/old-agent/task",
-			beadId: "task",
-			tmuxSession: "legio-old-agent",
-			state: "working",
-			pid: process.pid,
-			escalationLevel: 0,
-			stalledSince: null,
-		});
-
-		writeSessionsToStore(tempRoot, [session]);
+	test("empty sessions array is a no-op", async () => {
+		writeSessionsToStore(tempRoot, []);
 
 		const checks: HealthCheck[] = [];
 
@@ -498,21 +348,17 @@ describe("daemon tick", () => {
 			_tmux: tmuxAllAlive(),
 		});
 
-		// Should process without errors
-		expect(checks).toHaveLength(1);
-		expect(checks[0]?.state).toBe("working");
+		expect(checks).toHaveLength(0);
 	});
 });
 
 // === Event recording tests ===
 
 describe("daemon event recording", () => {
-	/** Open the events.db in the temp root and return all events. */
 	function readEvents(root: string): StoredEvent[] {
 		const dbPath = join(root, ".legio", "events.db");
 		const store = createEventStore(dbPath);
 		try {
-			// Get all events (no agent filter — use a broad timeline)
 			return store.getTimeline({ since: "2000-01-01T00:00:00Z" });
 		} finally {
 			store.close();
@@ -520,7 +366,6 @@ describe("daemon event recording", () => {
 	}
 
 	test("run_id is included in events when current-run.txt exists", async () => {
-		// Use zombie-old activity to trigger terminate + recovery attempt events
 		const oldActivity = new Date(Date.now() - 200_000).toISOString();
 		const session = makeSession({
 			agentName: "zombie-agent",
@@ -534,7 +379,6 @@ describe("daemon event recording", () => {
 
 		writeSessionsToStore(tempRoot, [session]);
 
-		// Write a current-run.txt
 		const runId = "run-2026-02-13T10-00-00-000Z";
 		await writeFile(join(tempRoot, ".legio", "current-run.txt"), runId, "utf-8");
 
@@ -591,7 +435,6 @@ describe("daemon event recording", () => {
 
 		const checks: HealthCheck[] = [];
 
-		// Inject null EventStore — daemon should still work fine
 		await runDaemonTick({
 			root: tempRoot,
 			...THRESHOLDS,
@@ -600,112 +443,11 @@ describe("daemon event recording", () => {
 			_eventStore: null,
 		});
 
-		// Daemon should still produce health checks even without EventStore
 		expect(checks).toHaveLength(1);
 		expect(checks[0]?.action).toBe("none");
 	});
 });
 
-// === Mulch failure recording tests ===
-
-describe("daemon mulch failure recording", () => {
-	let tempRoot: string;
-
-	beforeEach(async () => {
-		tempRoot = await createTempRoot();
-	});
-
-	afterEach(async () => {
-		await rm(tempRoot, { recursive: true, force: true });
-	});
-
-	/** Track calls to the recordFailure mock. */
-	interface FailureRecord {
-		root: string;
-		session: AgentSession;
-		reason: string;
-		tier: 0 | 1;
-		triageSuggestion?: string;
-	}
-
-	function failureTracker(): {
-		calls: FailureRecord[];
-		recordFailure: (
-			root: string,
-			session: AgentSession,
-			reason: string,
-			tier: 0 | 1,
-			triageSuggestion?: string,
-		) => Promise<void>;
-	} {
-		const calls: FailureRecord[] = [];
-		return {
-			calls,
-			async recordFailure(root, session, reason, tier, triageSuggestion) {
-				calls.push({ root, session, reason, tier, triageSuggestion });
-			},
-		};
-	}
-
-	test("Tier 0: recordFailure called when action=terminate (process death)", async () => {
-		const session = makeSession({
-			agentName: "dying-agent",
-			capability: "builder",
-			beadId: "task-123",
-			tmuxSession: "legio-dying-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
-		});
-
-		writeSessionsToStore(tempRoot, [session]);
-
-		const tmuxMock = tmuxWithLiveness({ "legio-dying-agent": false });
-		const failureMock = failureTracker();
-
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			_tmux: tmuxMock,
-			_recordFailure: failureMock.recordFailure,
-		});
-
-		// recordFailure should be called with Tier 0
-		expect(failureMock.calls).toHaveLength(1);
-		expect(failureMock.calls[0]?.tier).toBe(0);
-		expect(failureMock.calls[0]?.session.agentName).toBe("dying-agent");
-		expect(failureMock.calls[0]?.session.capability).toBe("builder");
-		expect(failureMock.calls[0]?.session.beadId).toBe("task-123");
-		// Reason should be either the reconciliationNote or default "Process terminated"
-		expect(failureMock.calls[0]?.reason).toBeDefined();
-	});
-
-	test("recordFailure includes evidenceBead when beadId is present", async () => {
-		const session = makeSession({
-			agentName: "beaded-agent",
-			capability: "builder",
-			beadId: "task-789",
-			tmuxSession: "legio-beaded-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
-		});
-
-		writeSessionsToStore(tempRoot, [session]);
-
-		const tmuxMock = tmuxWithLiveness({ "legio-beaded-agent": false });
-		const failureMock = failureTracker();
-
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			_tmux: tmuxMock,
-			_recordFailure: failureMock.recordFailure,
-		});
-
-		expect(failureMock.calls).toHaveLength(1);
-		expect(failureMock.calls[0]?.session.beadId).toBe("task-789");
-	});
-});
-
 // === Recovery tests ===
 
 describe("daemon recovery", () => {
@@ -719,7 +461,6 @@ describe("daemon recovery", () => {
 		await rm(tempRoot, { recursive: true, force: true });
 	});
 
-	/** Open the events.db and return all events. */
 	function readEvents(root: string): StoredEvent[] {
 		const dbPath = join(root, ".legio", "events.db");
 		const store = createEventStore(dbPath);
@@ -730,7 +471,6 @@ describe("daemon recovery", () => {
 		}
 	}
 
-	/** Build a minimal SessionCheckpoint for a session. */
 	function makeCheckpoint(agentName: string, beadId: string): SessionCheckpoint {
 		return {
 			agentName,
@@ -745,7 +485,6 @@ describe("daemon recovery", () => {
 		};
 	}
 
-	/** Create a fake _sling that tracks calls and returns a given exit code. */
 	function slingTracker(exitCode = 0): {
 		sling: (args: string[]) => Promise<{ exitCode: number; stderr: string }>;
 		calls: string[][];
@@ -760,7 +499,6 @@ describe("daemon recovery", () => {
 		};
 	}
 
-	/** Create a fake _sendRecoveryMail that tracks calls. */
 	function mailTracker(): {
 		sendRecoveryMail: (args: string[]) => Promise<void>;
 		calls: string[][];
@@ -774,7 +512,6 @@ describe("daemon recovery", () => {
 		};
 	}
 
-	/** Read recovery count from disk. */
 	async function readRecoveryCountFromDisk(root: string, agentName: string): Promise<number> {
 		try {
 			const text = await readFile(
@@ -787,7 +524,6 @@ describe("daemon recovery", () => {
 		}
 	}
 
-	/** Write recovery count to disk to simulate prior attempts. */
 	async function writeRecoveryCountToDisk(
 		root: string,
 		agentName: string,
@@ -798,8 +534,6 @@ describe("daemon recovery", () => {
 		await writeFile(join(dir, "recovery-count"), String(count), "utf-8");
 	}
 
-	// --- Direct terminate path (tmux dead) ---
-
 	test("no checkpoint → no recovery, agent marked zombie", async () => {
 		const session = makeSession({
 			agentName: "dead-agent",
@@ -824,16 +558,13 @@ describe("daemon recovery", () => {
 			_recordFailure: async () => {},
 		});
 
-		// No sling attempted (no checkpoint)
 		expect(slingMock.calls).toHaveLength(0);
-		// No mail sent
 		expect(mailMock.calls).toHaveLength(0);
-		// Agent is zombie (existing behavior)
 		const reloaded = readSessionsFromStore(tempRoot);
 		expect(reloaded[0]?.state).toBe("zombie");
 	});
 
-	test("checkpoint exists, sling succeeds → sling called, recovery events recorded", async () => {
+	test("checkpoint exists, sling succeeds → recovery events recorded", async () => {
 		const session = makeSession({
 			agentName: "dead-agent",
 			tmuxSession: "legio-dead-agent",
@@ -869,13 +600,10 @@ describe("daemon recovery", () => {
 			eventStore.close();
 		}
 
-		// Sling was called
 		expect(slingMock.calls).toHaveLength(1);
-		// Mail sent to parent
 		expect(mailMock.calls).toHaveLength(1);
 		expect(mailMock.calls[0]).toContain("my-lead");
 
-		// recovery_attempt and recovery_success events recorded
 		const events = readEvents(tempRoot);
 		const attemptEvent = events.find((e) => {
 			if (!e.data) return false;
@@ -883,39 +611,107 @@ describe("daemon recovery", () => {
 			return d.type === "recovery_attempt";
 		});
 		expect(attemptEvent).toBeDefined();
-		expect(attemptEvent?.level).toBe("info");
-		expect(attemptEvent?.agentName).toBe("dead-agent");
 
-		const successEvent = events.find((e) => {
-			if (!e.data) return false;
-			const d = JSON.parse(e.data) as Record<string, unknown>;
-			return d.type === "recovery_success";
-		});
-		expect(successEvent).toBeDefined();
-		expect(successEvent?.level).toBe("info");
-
-		// State must be "completed" after successful recovery, not "zombie"
 		const reloaded = readSessionsFromStore(tempRoot);
-		expect(reloaded[0]?.state).not.toBe("zombie");
 		expect(reloaded[0]?.state).toBe("completed");
 	});
 
-	test("checkpoint exists, sling fails → sling called, agent stays zombie, recovery_failed event", async () => {
+	test("recovery count exhausted → no sling, agent zombified", async () => {
 		const session = makeSession({
 			agentName: "dead-agent",
 			tmuxSession: "legio-dead-agent",
 			state: "working",
 			lastActivity: new Date().toISOString(),
 			parentAgent: "my-lead",
-			beadId: "task-abc",
-			capability: "builder",
 		});
 
 		writeSessionsToStore(tempRoot, [session]);
+		await writeRecoveryCountToDisk(tempRoot, "dead-agent", 1);
 
 		const checkpoint = makeCheckpoint("dead-agent", "task-abc");
-		const slingMock = slingTracker(1); // Non-zero exit code
+		const slingMock = slingTracker(0);
+		const mailMock = mailTracker();
+
+		await runDaemonTick({
+			root: tempRoot,
+			...THRESHOLDS,
+			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
+			_loadCheckpoint: async () => checkpoint,
+			_sling: slingMock.sling,
+			_sendRecoveryMail: mailMock.sendRecoveryMail,
+			_recordFailure: async () => {},
+		});
 
+		expect(slingMock.calls).toHaveLength(0);
+		expect(mailMock.calls).toHaveLength(1);
+		const reloaded = readSessionsFromStore(tempRoot);
+		expect(reloaded[0]?.state).toBe("zombie");
+	});
+
+	test("recovery count increments after successful attempt", async () => {
+		const session = makeSession({
+			agentName: "dead-agent",
+			tmuxSession: "legio-dead-agent",
+			state: "working",
+			lastActivity: new Date().toISOString(),
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const checkpoint = makeCheckpoint("dead-agent", "task-abc");
+
+		await runDaemonTick({
+			root: tempRoot,
+			...THRESHOLDS,
+			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
+			_loadCheckpoint: async () => checkpoint,
+			_sling: slingTracker(0).sling,
+			_sendRecoveryMail: async () => {},
+			_recordFailure: async () => {},
+		});
+
+		const count = await readRecoveryCountFromDisk(tempRoot, "dead-agent");
+		expect(count).toBe(1);
+	});
+});
+
+// === Beacon safety net tests ===
+
+describe("beacon safety net", () => {
+	let tempRoot: string;
+
+	beforeEach(async () => {
+		tempRoot = await createTempRoot();
+	});
+
+	afterEach(async () => {
+		await rm(tempRoot, { recursive: true, force: true });
+	});
+
+	function readEvents(root: string): StoredEvent[] {
+		const dbPath = join(root, ".legio", "events.db");
+		const store = createEventStore(dbPath);
+		try {
+			return store.getTimeline({ since: "2000-01-01T00:00:00Z" });
+		} finally {
+			store.close();
+		}
+	}
+
+	test("sends follow-up Enter when booting agent has no activity markers", async () => {
+		// Agent has been booting for 25s (past beaconNudgeMs=20s but before bootTimeoutMs=90s)
+		const startedAt = new Date(Date.now() - 25_000).toISOString();
+		const session = makeSession({
+			agentName: "stuck-agent",
+			tmuxSession: "legio-stuck-agent",
+			state: "booting",
+			startedAt,
+			lastActivity: startedAt,
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const sendKeysCalls: Array<{ session: string; keys: string }> = [];
 		const eventsDbPath = join(tempRoot, ".legio", "events.db");
 		const eventStore = createEventStore(eventsDbPath);
 
@@ -923,311 +719,421 @@ describe("daemon recovery", () => {
 			await runDaemonTick({
 				root: tempRoot,
 				...THRESHOLDS,
-				_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-				_loadCheckpoint: async () => checkpoint,
-				_sling: slingMock.sling,
-				_sendRecoveryMail: async () => {},
-				_recordFailure: async () => {},
+				beaconNudgeMs: 20_000,
+				_tmux: tmuxWithLiveness({ "legio-stuck-agent": true }),
+				_capturePaneContent: async () => "Some prompt text sitting in buffer",
+				_sendKeys: async (sessionName, keys) => {
+					sendKeysCalls.push({ session: sessionName, keys });
+				},
 				_eventStore: eventStore,
 			});
 		} finally {
 			eventStore.close();
 		}
 
-		// Sling was called
-		expect(slingMock.calls).toHaveLength(1);
-		// Agent should be zombie (sling failed)
-		const reloaded = readSessionsFromStore(tempRoot);
-		expect(reloaded[0]?.state).toBe("zombie");
+		// Follow-up Enter should have been sent
+		expect(sendKeysCalls).toHaveLength(1);
+		expect(sendKeysCalls[0]?.session).toBe("legio-stuck-agent");
+		expect(sendKeysCalls[0]?.keys).toBe("");
 
-		// recovery_failed event recorded
+		// beacon_nudge event should be recorded
 		const events = readEvents(tempRoot);
-		const failedEvent = events.find((e) => {
+		const beaconEvent = events.find((e) => {
 			if (!e.data) return false;
 			const d = JSON.parse(e.data) as Record<string, unknown>;
-			return d.type === "recovery_failed";
+			return d.type === "beacon_nudge";
 		});
-		expect(failedEvent).toBeDefined();
-		expect(failedEvent?.level).toBe("error");
+		expect(beaconEvent).toBeDefined();
 	});
 
-	test("sling args include capability, name, spec path, files, parent, depth", async () => {
+	test("does NOT send Enter when activity markers are present", async () => {
+		const startedAt = new Date(Date.now() - 25_000).toISOString();
 		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
-			parentAgent: "my-lead",
-			beadId: "task-abc",
-			capability: "builder",
-			depth: 2,
+			agentName: "active-agent",
+			tmuxSession: "legio-active-agent",
+			state: "booting",
+			startedAt,
+			lastActivity: startedAt,
 		});
 
 		writeSessionsToStore(tempRoot, [session]);
 
-		const checkpoint: SessionCheckpoint = {
-			...makeCheckpoint("dead-agent", "task-abc"),
-			filesModified: ["src/foo.ts", "src/bar.ts"],
-		};
-		const slingMock = slingTracker(0);
+		const sendKeysCalls: Array<{ session: string; keys: string }> = [];
 
 		await runDaemonTick({
 			root: tempRoot,
 			...THRESHOLDS,
-			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-			_loadCheckpoint: async () => checkpoint,
-			_sling: slingMock.sling,
-			_sendRecoveryMail: async () => {},
-			_recordFailure: async () => {},
+			beaconNudgeMs: 20_000,
+			_tmux: tmuxWithLiveness({ "legio-active-agent": true }),
+			_capturePaneContent: async () => "⏺ Claude is thinking...",
+			_sendKeys: async (sessionName, keys) => {
+				sendKeysCalls.push({ session: sessionName, keys });
+			},
 		});
 
-		expect(slingMock.calls).toHaveLength(1);
-		const args = slingMock.calls[0] ?? [];
-		expect(args).toContain("task-abc");
-		expect(args).toContain("--capability");
-		expect(args).toContain("builder");
-		expect(args).toContain("--name");
-		expect(args).toContain("dead-agent");
-		expect(args).toContain("--spec");
-		expect(args).toContain("--files");
-		expect(args).toContain("src/foo.ts,src/bar.ts");
-		expect(args).toContain("--parent");
-		expect(args).toContain("my-lead");
-		expect(args).toContain("--depth");
-		expect(args).toContain("2");
+		// No follow-up Enter — agent shows activity
+		expect(sendKeysCalls).toHaveLength(0);
 	});
 
-	test("no files modified → --files arg omitted from sling", async () => {
+	test("does NOT send Enter when pane content is empty", async () => {
+		const startedAt = new Date(Date.now() - 25_000).toISOString();
 		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
-			capability: "builder",
+			agentName: "empty-agent",
+			tmuxSession: "legio-empty-agent",
+			state: "booting",
+			startedAt,
+			lastActivity: startedAt,
 		});
 
 		writeSessionsToStore(tempRoot, [session]);
 
-		const checkpoint: SessionCheckpoint = {
-			...makeCheckpoint("dead-agent", "task-abc"),
-			filesModified: [], // No files
-		};
-		const slingMock = slingTracker(0);
+		const sendKeysCalls: Array<{ session: string; keys: string }> = [];
 
 		await runDaemonTick({
 			root: tempRoot,
 			...THRESHOLDS,
-			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-			_loadCheckpoint: async () => checkpoint,
-			_sling: slingMock.sling,
-			_sendRecoveryMail: async () => {},
-			_recordFailure: async () => {},
+			beaconNudgeMs: 20_000,
+			_tmux: tmuxWithLiveness({ "legio-empty-agent": true }),
+			_capturePaneContent: async () => "   ",
+			_sendKeys: async (sessionName, keys) => {
+				sendKeysCalls.push({ session: sessionName, keys });
+			},
 		});
 
-		expect(slingMock.calls).toHaveLength(1);
-		const args = slingMock.calls[0] ?? [];
-		expect(args).not.toContain("--files");
+		// No follow-up Enter — pane is empty (agent hasn't started yet)
+		expect(sendKeysCalls).toHaveLength(0);
 	});
 
-	test("recovery count increments after successful attempt", async () => {
+	test("does NOT send Enter before beaconNudgeMs", async () => {
+		// Agent has been booting for only 5s (well before beaconNudgeMs=20s)
+		const startedAt = new Date(Date.now() - 5_000).toISOString();
 		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
+			agentName: "new-agent",
+			tmuxSession: "legio-new-agent",
+			state: "booting",
+			startedAt,
+			lastActivity: startedAt,
 		});
 
 		writeSessionsToStore(tempRoot, [session]);
 
-		const checkpoint = makeCheckpoint("dead-agent", "task-abc");
+		const sendKeysCalls: Array<{ session: string; keys: string }> = [];
 
 		await runDaemonTick({
 			root: tempRoot,
 			...THRESHOLDS,
-			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-			_loadCheckpoint: async () => checkpoint,
-			_sling: slingTracker(0).sling,
-			_sendRecoveryMail: async () => {},
-			_recordFailure: async () => {},
+			beaconNudgeMs: 20_000,
+			_tmux: tmuxWithLiveness({ "legio-new-agent": true }),
+			_capturePaneContent: async () => "Some text",
+			_sendKeys: async (sessionName, keys) => {
+				sendKeysCalls.push({ session: sessionName, keys });
+			},
 		});
 
-		const count = await readRecoveryCountFromDisk(tempRoot, "dead-agent");
-		expect(count).toBe(1);
+		// No follow-up Enter — too early
+		expect(sendKeysCalls).toHaveLength(0);
 	});
 
-	test("recovery count exhausted → no sling, agent zombified, escalation mail sent to parent", async () => {
+	test("capturePaneContent failure is non-fatal", async () => {
+		const startedAt = new Date(Date.now() - 25_000).toISOString();
 		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
-			parentAgent: "my-lead",
+			agentName: "error-agent",
+			tmuxSession: "legio-error-agent",
+			state: "booting",
+			startedAt,
+			lastActivity: startedAt,
 		});
 
 		writeSessionsToStore(tempRoot, [session]);
 
-		// Pre-write recovery count = 1 (default maxRecoveryAttempts=1, so exhausted)
-		await writeRecoveryCountToDisk(tempRoot, "dead-agent", 1);
-
-		const checkpoint = makeCheckpoint("dead-agent", "task-abc");
-		const slingMock = slingTracker(0);
-		const mailMock = mailTracker();
-
+		// Should not throw
 		await runDaemonTick({
 			root: tempRoot,
 			...THRESHOLDS,
-			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-			_loadCheckpoint: async () => checkpoint,
-			_sling: slingMock.sling,
-			_sendRecoveryMail: mailMock.sendRecoveryMail,
-			_recordFailure: async () => {},
+			beaconNudgeMs: 20_000,
+			_tmux: tmuxWithLiveness({ "legio-error-agent": true }),
+			_capturePaneContent: async () => {
+				throw new Error("tmux capture failed");
+			},
+			_sendKeys: async () => {},
 		});
 
-		// No sling attempted (exhausted)
-		expect(slingMock.calls).toHaveLength(0);
-		// Exhaustion error mail sent to parent
-		expect(mailMock.calls).toHaveLength(1);
-		const mailArgs = mailMock.calls[0] ?? [];
-		expect(mailArgs).toContain("my-lead");
-		expect(mailArgs).toContain("error");
-		// Agent marked zombie
-		const reloaded = readSessionsFromStore(tempRoot);
-		expect(reloaded[0]?.state).toBe("zombie");
+		// Daemon should continue without crashing
 	});
+});
 
-	test("maxRecoveryAttempts=2: second attempt allowed when count=1", async () => {
-		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
-			parentAgent: "my-lead",
+// === Mail tick tests ===
+
+describe("mail tick", () => {
+	let tempDir: string;
+	let store: MailStore;
+	let nudgeCalls: Array<{ agentName: string; message: string }>;
+	let pendingNudgeCalls: Array<{ agentName: string }>;
+
+	function makeMailOptions(overrides?: Partial<WatchmanOptions>): WatchmanOptions {
+		return {
+			root: tempDir,
+			zombieThresholdMs: 120_000,
+			_mailStore: store,
+			_nudge: async (_root, agentName, message) => {
+				nudgeCalls.push({ agentName, message });
+				return { delivered: true };
+			},
+			_isAgentIdle: async () => true,
+			_writePendingNudge: async (_cwd, agentName) => {
+				pendingNudgeCalls.push({ agentName });
+			},
+			...overrides,
+		};
+	}
+
+	beforeEach(async () => {
+		tempDir = await mkdtemp(join(tmpdir(), "legio-watchman-test-"));
+		store = createMailStore(join(tempDir, "mail.db"));
+		nudgeCalls = [];
+		pendingNudgeCalls = [];
+	});
+
+	afterEach(async () => {
+		store.close();
+		await rm(tempDir, { recursive: true, force: true });
+	});
+
+	test("no-op when no unread messages", async () => {
+		const state = new Map<string, AgentMailState>();
+		await runMailTick(makeMailOptions(), state);
+
+		expect(nudgeCalls).toHaveLength(0);
+		expect(pendingNudgeCalls).toHaveLength(0);
+		expect(state.size).toBe(0);
+	});
+
+	test("nudges agent with unread mail on first tick", async () => {
+		store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "Please build feature X",
+			type: "status",
+			priority: "normal",
+			threadId: null,
 		});
 
-		writeSessionsToStore(tempRoot, [session]);
+		const state = new Map<string, AgentMailState>();
+		await runMailTick(makeMailOptions(), state);
 
-		// count=1 but max=2, so one more attempt is allowed
-		await writeRecoveryCountToDisk(tempRoot, "dead-agent", 1);
+		expect(nudgeCalls).toHaveLength(1);
+		expect(nudgeCalls[0]?.agentName).toBe("builder-1");
+		expect(pendingNudgeCalls).toHaveLength(1);
+		expect(pendingNudgeCalls[0]?.agentName).toBe("builder-1");
+		expect(state.size).toBe(1);
+		expect(state.get("builder-1")?.nudgeCount).toBe(1);
+	});
 
-		const checkpoint = makeCheckpoint("dead-agent", "task-abc");
-		const slingMock = slingTracker(0);
+	test("does not re-nudge before reNudgeIntervalMs", async () => {
+		store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
+		});
 
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			maxRecoveryAttempts: 2,
-			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-			_loadCheckpoint: async () => checkpoint,
-			_sling: slingMock.sling,
-			_sendRecoveryMail: async () => {},
-			_recordFailure: async () => {},
+		const state = new Map<string, AgentMailState>();
+		const opts = makeMailOptions({ reNudgeIntervalMs: 60_000 });
+
+		await runMailTick(opts, state);
+		expect(nudgeCalls).toHaveLength(1);
+
+		await runMailTick(opts, state);
+		expect(nudgeCalls).toHaveLength(1);
+	});
+
+	test("re-nudges after reNudgeIntervalMs", async () => {
+		store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
 		});
 
-		// Second attempt was made
-		expect(slingMock.calls).toHaveLength(1);
-		// Count now 2
-		const count = await readRecoveryCountFromDisk(tempRoot, "dead-agent");
-		expect(count).toBe(2);
+		const state = new Map<string, AgentMailState>();
+		const opts = makeMailOptions({ reNudgeIntervalMs: 100 });
+
+		await runMailTick(opts, state);
+		expect(nudgeCalls).toHaveLength(1);
+
+		await new Promise<void>((resolve) => setTimeout(resolve, 150));
+
+		await runMailTick(opts, state);
+		expect(nudgeCalls).toHaveLength(2);
+		expect(state.get("builder-1")?.nudgeCount).toBe(2);
 	});
 
-	test("no parent agent → no mail, recovery still attempted", async () => {
-		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
-			parentAgent: null,
+	test("clears state when agent reads mail", async () => {
+		const msg = store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
 		});
 
-		writeSessionsToStore(tempRoot, [session]);
+		const state = new Map<string, AgentMailState>();
+		await runMailTick(makeMailOptions(), state);
+		expect(state.size).toBe(1);
 
-		const checkpoint = makeCheckpoint("dead-agent", "task-abc");
-		const slingMock = slingTracker(0);
-		const mailMock = mailTracker();
+		store.markRead(msg.id);
 
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-			_loadCheckpoint: async () => checkpoint,
-			_sling: slingMock.sling,
-			_sendRecoveryMail: mailMock.sendRecoveryMail,
-			_recordFailure: async () => {},
+		await runMailTick(makeMailOptions(), state);
+		expect(state.size).toBe(0);
+	});
+
+	test("nudge failure is non-fatal", async () => {
+		store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
 		});
 
-		// Sling still attempted
-		expect(slingMock.calls).toHaveLength(1);
-		// No mail (no parent)
-		expect(mailMock.calls).toHaveLength(0);
+		const state = new Map<string, AgentMailState>();
+		const opts = makeMailOptions({
+			_nudge: async () => {
+				throw new Error("tmux dead");
+			},
+		});
+
+		await runMailTick(opts, state);
+		expect(state.size).toBe(1);
+		expect(state.get("builder-1")?.nudgeCount).toBe(1);
 	});
 
-	test("recovery_attempt event includes attempt number and maxAttempts", async () => {
-		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
+	test("skips tmux nudge when agent is busy", async () => {
+		store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
 		});
 
-		writeSessionsToStore(tempRoot, [session]);
+		const state = new Map<string, AgentMailState>();
+		const opts = makeMailOptions({
+			_isAgentIdle: async () => false,
+		});
 
-		const checkpoint = makeCheckpoint("dead-agent", "task-abc");
+		await runMailTick(opts, state);
 
-		const eventsDbPath = join(tempRoot, ".legio", "events.db");
-		const eventStore = createEventStore(eventsDbPath);
+		expect(pendingNudgeCalls).toHaveLength(1);
+		expect(nudgeCalls).toHaveLength(0);
+	});
 
-		try {
-			await runDaemonTick({
-				root: tempRoot,
-				...THRESHOLDS,
-				maxRecoveryAttempts: 3,
-				_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-				_loadCheckpoint: async () => checkpoint,
-				_sling: slingTracker(0).sling,
-				_sendRecoveryMail: async () => {},
-				_recordFailure: async () => {},
-				_eventStore: eventStore,
-			});
-		} finally {
-			eventStore.close();
-		}
+	test("calls onWarn after warnAfterMs", async () => {
+		store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
+		});
 
-		const events = readEvents(tempRoot);
-		const attemptEvent = events.find((e) => {
-			if (!e.data) return false;
-			const d = JSON.parse(e.data) as Record<string, unknown>;
-			return d.type === "recovery_attempt";
+		const warnings: Array<{ agentName: string; durationMs: number }> = [];
+		const state = new Map<string, AgentMailState>();
+		const opts = makeMailOptions({
+			warnAfterMs: 50,
+			reNudgeIntervalMs: 10,
+			onWarn: (agentName, durationMs) => {
+				warnings.push({ agentName, durationMs });
+			},
 		});
-		expect(attemptEvent).toBeDefined();
-		const data = JSON.parse(attemptEvent?.data ?? "{}") as Record<string, unknown>;
-		expect(data.attempt).toBe(1);
-		expect(data.maxAttempts).toBe(3);
+
+		await runMailTick(opts, state);
+		expect(warnings).toHaveLength(0);
+
+		await new Promise<void>((resolve) => setTimeout(resolve, 100));
+
+		await runMailTick(opts, state);
+		expect(warnings).toHaveLength(1);
+		expect(warnings[0]?.agentName).toBe("builder-1");
 	});
 
-	test("existing tests unchanged: dead tmux without recovery DI still zombifies", async () => {
-		// Verify that omitting recovery DI (no _loadCheckpoint) uses default behavior —
-		// since the real loadCheckpoint would find no file, agent should still be zombified.
-		const session = makeSession({
-			agentName: "dead-agent",
-			tmuxSession: "legio-dead-agent",
-			state: "working",
-			lastActivity: new Date().toISOString(),
+	test("handles multiple agents with unread mail", async () => {
+		store.insert({
+			id: "",
+			from: "orchestrator",
+			to: "builder-1",
+			subject: "task 1",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
+		});
+		store.insert({
+			id: "",
+			from: "orchestrator",
+			to: "builder-2",
+			subject: "task 2",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
 		});
 
-		writeSessionsToStore(tempRoot, [session]);
+		const state = new Map<string, AgentMailState>();
+		await runMailTick(makeMailOptions(), state);
 
-		// Use a _loadCheckpoint that returns null (as the real impl would for no file)
-		await runDaemonTick({
-			root: tempRoot,
-			...THRESHOLDS,
-			_tmux: tmuxWithLiveness({ "legio-dead-agent": false }),
-			_loadCheckpoint: async () => null,
-			_sling: async () => ({ exitCode: 0, stderr: "" }),
-			_sendRecoveryMail: async () => {},
-			_recordFailure: async () => {},
+		expect(nudgeCalls).toHaveLength(2);
+		const nudgedAgents = nudgeCalls.map((c) => c.agentName).sort();
+		expect(nudgedAgents).toEqual(["builder-1", "builder-2"]);
+		expect(state.size).toBe(2);
+	});
+
+	test("calls onNudge callback", async () => {
+		store.insert({
+			id: "",
+			from: "agent-a",
+			to: "builder-1",
+			subject: "Build this",
+			body: "body",
+			type: "status",
+			priority: "normal",
+			threadId: null,
 		});
 
-		const reloaded = readSessionsFromStore(tempRoot);
-		expect(reloaded[0]?.state).toBe("zombie");
+		const nudgeEvents: Array<{ agentName: string; count: number }> = [];
+		const state = new Map<string, AgentMailState>();
+		const opts = makeMailOptions({
+			onNudge: (agentName, count) => {
+				nudgeEvents.push({ agentName, count });
+			},
+		});
+
+		await runMailTick(opts, state);
+
+		expect(nudgeEvents).toHaveLength(1);
+		expect(nudgeEvents[0]?.agentName).toBe("builder-1");
+		expect(nudgeEvents[0]?.count).toBe(1);
 	});
 });