@katyella/legio 0.1.3 → 0.2.2

package/src/commands/coordinator.ts

@@ -22,9 +22,9 @@ import { collectProviderEnv, loadConfig } from "../config.ts";
 import { AgentError, isRunningAsRoot, ValidationError } from "../errors.ts";
 import { HeadlessCoordinator } from "../server/headless.ts";
 import { openSessionStore } from "../sessions/compat.ts";
-import { createRunStore } from "../sessions/store.ts";
+import { createRunStore, type SessionStore } from "../sessions/store.ts";
 import type { AgentSession, HeadlessCoordinatorConfig } from "../types.ts";
-import { isProcessRunning } from "../watchdog/health.ts";
+import { isProcessRunning } from "../watchman/health.ts";
 import {
 	createSession,
 	isSessionAlive,
@@ -113,7 +113,7 @@ export interface CoordinatorDeps {
 			opts?: { timeout?: number; interval?: number },
 		) => Promise<void>;
 	};
-	_watchdog?: {
+	_watchman?: {
 		start: () => Promise<{ pid: number } | null>;
 		stop: () => Promise<boolean>;
 		isRunning: () => Promise<boolean>;
@@ -130,11 +130,11 @@ export interface CoordinatorDeps {
 }
 
 /**
- * Read the PID from the watchdog PID file.
+ * Read the PID from the watchman PID file.
  * Returns null if the file doesn't exist or can't be parsed.
  */
-async function readWatchdogPid(projectRoot: string): Promise<number | null> {
-	const pidFilePath = join(projectRoot, ".legio", "watchdog.pid");
+async function readWatchmanPid(projectRoot: string): Promise<number | null> {
+	const pidFilePath = join(projectRoot, ".legio", "watchman.pid");
 	if (!(await fileExists(pidFilePath))) {
 		return null;
 	}
@@ -152,10 +152,10 @@ async function readWatchdogPid(projectRoot: string): Promise<number | null> {
 }
 
 /**
- * Remove the watchdog PID file.
+ * Remove the watchman PID file.
  */
-async function removeWatchdogPid(projectRoot: string): Promise<void> {
-	const pidFilePath = join(projectRoot, ".legio", "watchdog.pid");
+async function removeWatchmanPid(projectRoot: string): Promise<void> {
+	const pidFilePath = join(projectRoot, ".legio", "watchman.pid");
 	try {
 		await unlink(pidFilePath);
 	} catch {
@@ -164,25 +164,25 @@ async function removeWatchdogPid(projectRoot: string): Promise<void> {
 }
 
 /**
- * Default watchdog implementation for production use.
- * Starts/stops the watchdog daemon via `legio watch --background`.
+ * Default watchman implementation for production use.
+ * Starts/stops the watchman daemon via `legio watchman start --background`.
  */
-function createDefaultWatchdog(projectRoot: string): NonNullable<CoordinatorDeps["_watchdog"]> {
+function createDefaultWatchman(projectRoot: string): NonNullable<CoordinatorDeps["_watchman"]> {
 	return {
 		async start(): Promise<{ pid: number } | null> {
-			// Check if watchdog is already running
-			const existingPid = await readWatchdogPid(projectRoot);
+			// Check if watchman is already running
+			const existingPid = await readWatchmanPid(projectRoot);
 			if (existingPid !== null && isProcessRunning(existingPid)) {
 				return null; // Already running
 			}
 
 			// Clean up stale PID file
 			if (existingPid !== null) {
-				await removeWatchdogPid(projectRoot);
+				await removeWatchmanPid(projectRoot);
 			}
 
-			// Start watchdog in background
-			const { exitCode } = await runProcess(["legio", "watch", "--background"], {
+			// Start watchman in background
+			const { exitCode } = await runProcess(["legio", "watchman", "start", "--background"], {
 				cwd: projectRoot,
 			});
 			if (exitCode !== 0) {
@@ -190,7 +190,7 @@ function createDefaultWatchdog(projectRoot: string): NonNullable<CoordinatorDeps
 			}
 
 			// Read the PID file that was written by the background process
-			const pid = await readWatchdogPid(projectRoot);
+			const pid = await readWatchmanPid(projectRoot);
 			if (pid === null) {
 				return null; // PID file wasn't created
 			}
@@ -199,7 +199,7 @@ function createDefaultWatchdog(projectRoot: string): NonNullable<CoordinatorDeps
 		},
 
 		async stop(): Promise<boolean> {
-			const pid = await readWatchdogPid(projectRoot);
+			const pid = await readWatchmanPid(projectRoot);
 			if (pid === null) {
 				return false; // No PID file
 			}
@@ -207,7 +207,7 @@ function createDefaultWatchdog(projectRoot: string): NonNullable<CoordinatorDeps
 			// Check if process is running
 			if (!isProcessRunning(pid)) {
 				// Process is dead, clean up PID file
-				await removeWatchdogPid(projectRoot);
+				await removeWatchmanPid(projectRoot);
 				return false;
 			}
 
@@ -219,12 +219,12 @@ function createDefaultWatchdog(projectRoot: string): NonNullable<CoordinatorDeps
 			}
 
 			// Remove PID file
-			await removeWatchdogPid(projectRoot);
+			await removeWatchmanPid(projectRoot);
 			return true;
 		},
 
 		async isRunning(): Promise<boolean> {
-			const pid = await readWatchdogPid(projectRoot);
+			const pid = await readWatchmanPid(projectRoot);
 			if (pid === null) {
 				return false;
 			}
@@ -281,10 +281,11 @@ export function buildCoordinatorBeacon(): string {
 	const timestamp = new Date().toISOString();
 	const parts = [
 		`[LEGIO] ${COORDINATOR_NAME} (coordinator) ${timestamp}`,
+		"You are a coordinator agent in the legio multi-agent orchestration system. legio is a CLI tool installed on this machine that coordinates multiple Claude Code agents via tmux, SQLite mail, and git worktrees.",
 		"Depth: 0 | Parent: none | Role: persistent orchestrator",
 		"HIERARCHY: You ONLY spawn leads (legio sling --capability lead). Leads spawn scouts, builders, reviewers. NEVER spawn non-lead agents directly.",
 		"DELEGATION: For any exploration/scouting, spawn a lead who will spawn scouts. Do NOT explore the codebase yourself beyond initial planning.",
-		`Startup: run mulch prime, check mail (legio mail check --agent ${COORDINATOR_NAME}), check bd ready, check legio group status, then begin work`,
+		`Startup: run mulch prime, check mail (legio mail check --agent ${COORDINATOR_NAME}), check legio status, then begin work`,
 	];
 	return parts.join(" — ");
 }
@@ -310,6 +311,46 @@ export function resolveAttach(args: string[], isTTY: boolean): boolean {
 	return isTTY;
 }
 
+/**
+ * Verify that the coordinator beacon was delivered by polling the session state.
+ * If the session remains in "booting" after 10 seconds, retries the beacon once.
+ * Logs a warning if delivery cannot be confirmed.
+ *
+ * Must be awaited before the SessionStore is closed (called inside the try block).
+ */
+async function verifyBeaconDelivery(
+	store: SessionStore,
+	tmux: NonNullable<CoordinatorDeps["_tmux"]>,
+	tmuxSession: string,
+	beacon: string,
+	sleep: (ms: number) => Promise<void>,
+): Promise<void> {
+	const MAX_CHECKS = 10;
+	const INTERVAL_MS = 2_000;
+
+	for (let i = 0; i < MAX_CHECKS; i++) {
+		await sleep(INTERVAL_MS);
+		const session = store.getByName(COORDINATOR_NAME);
+		if (session && session.state !== "booting") {
+			// Beacon confirmed — coordinator transitioned out of booting
+			return;
+		}
+	}
+
+	// Still booting after MAX_CHECKS — retry beacon once
+	process.stderr.write("[legio] Beacon delivery unconfirmed — retrying beacon\n");
+	await tmux.sendKeys(tmuxSession, beacon);
+	await sleep(500);
+	await tmux.sendKeys(tmuxSession, "");
+
+	// One final check after retry
+	await sleep(INTERVAL_MS);
+	const finalSession = store.getByName(COORDINATOR_NAME);
+	if (!finalSession || finalSession.state === "booting") {
+		process.stderr.write("[legio] Warning: coordinator beacon delivery could not be confirmed\n");
+	}
+}
+
 async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Promise<void> {
 	const tmux = deps._tmux ?? {
 		createSession,
@@ -332,13 +373,13 @@ async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Pro
 
 	const json = args.includes("--json");
 	const shouldAttach = resolveAttach(args, !!process.stdout.isTTY);
-	const watchdogFlag = args.includes("--watchdog");
+	const watchmanFlag = args.includes("--watchman") || args.includes("--watchdog");
 	const monitorFlag = args.includes("--monitor");
 	const headlessFlag = args.includes("--headless");
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
-	const watchdog = deps._watchdog ?? createDefaultWatchdog(projectRoot);
+	const watchman = deps._watchman ?? createDefaultWatchman(projectRoot);
 	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
 	const tmuxSession = coordinatorTmuxSession(config.project.name);
 
@@ -533,7 +574,7 @@ async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Pro
 			tmuxSession,
 			projectRoot,
 			pid,
-			watchdog: false,
+			watchman: false,
 			monitor: false,
 		};
 
@@ -560,13 +601,17 @@ async function startCoordinator(args: string[], deps: CoordinatorDeps = {}): Pro
 		await sleep(500);
 		await tmux.sendKeys(tmuxSession, "");
 
-		// Auto-start watchdog if --watchdog flag is present
-		if (watchdogFlag) {
-			const watchdogResult = await watchdog.start();
-			if (watchdogResult) {
-				if (!json) process.stdout.write(`  Watchdog: started (PID ${watchdogResult.pid})\n`);
+		// Verify beacon delivery: poll store until state transitions out of booting.
+		// Must complete before the finally block closes the store.
+		await verifyBeaconDelivery(store, tmux, tmuxSession, beacon, sleep);
+
+		// Auto-start watchman if --watchman/--watchdog flag is present
+		if (watchmanFlag) {
+			const watchmanResult = await watchman.start();
+			if (watchmanResult) {
+				if (!json) process.stdout.write(`  Watchman: started (PID ${watchmanResult.pid})\n`);
 			} else {
-				if (!json) process.stderr.write("  Watchdog: failed to start or already running\n");
+				if (!json) process.stderr.write("  Watchman: failed to start or already running\n");
 			}
 		}
 
@@ -605,7 +650,7 @@ async function stopCoordinator(args: string[], deps: CoordinatorDeps = {}): Prom
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
-	const watchdog = deps._watchdog ?? createDefaultWatchdog(projectRoot);
+	const watchman = deps._watchman ?? createDefaultWatchman(projectRoot);
 	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
 
 	const legioDir = join(projectRoot, ".legio");
@@ -662,8 +707,8 @@ async function stopCoordinator(args: string[], deps: CoordinatorDeps = {}): Prom
 			}
 		}
 
-		// Always attempt to stop watchdog
-		const watchdogStopped = await watchdog.stop();
+		// Always attempt to stop watchman
+		const watchmanStopped = await watchman.stop();
 
 		// Always attempt to stop monitor
 		const monitorStopped = await monitor.stop();
@@ -699,14 +744,14 @@ async function stopCoordinator(args: string[], deps: CoordinatorDeps = {}): Prom
 
 		if (json) {
 			process.stdout.write(
-				`${JSON.stringify({ stopped: true, sessionId: session.id, watchdogStopped, monitorStopped, runCompleted })}\n`,
+				`${JSON.stringify({ stopped: true, sessionId: session.id, watchmanStopped, monitorStopped, runCompleted })}\n`,
 			);
 		} else {
 			process.stdout.write(`Coordinator stopped (session: ${session.id})\n`);
-			if (watchdogStopped) {
-				process.stdout.write("Watchdog stopped\n");
+			if (watchmanStopped) {
+				process.stdout.write("Watchman stopped\n");
 			} else {
-				process.stdout.write("No watchdog running\n");
+				process.stdout.write("No watchman running\n");
 			}
 			if (monitorStopped) {
 				process.stdout.write("Monitor stopped\n");
@@ -736,14 +781,14 @@ async function statusCoordinator(args: string[], deps: CoordinatorDeps = {}): Pr
 	const cwd = process.cwd();
 	const config = await loadConfig(cwd);
 	const projectRoot = config.project.root;
-	const watchdog = deps._watchdog ?? createDefaultWatchdog(projectRoot);
+	const watchman = deps._watchman ?? createDefaultWatchman(projectRoot);
 	const monitor = deps._monitor ?? createDefaultMonitor(projectRoot);
 
 	const legioDir = join(projectRoot, ".legio");
 	const { store } = openSessionStore(legioDir);
 	try {
 		const session = store.getByName(COORDINATOR_NAME);
-		const watchdogRunning = await watchdog.isRunning();
+		const watchmanRunning = await watchman.isRunning();
 		const monitorRunning = await monitor.isRunning();
 
 		if (
@@ -754,12 +799,12 @@ async function statusCoordinator(args: string[], deps: CoordinatorDeps = {}): Pr
 		) {
 			if (json) {
 				process.stdout.write(
-					`${JSON.stringify({ running: false, watchdogRunning, monitorRunning })}\n`,
+					`${JSON.stringify({ running: false, watchmanRunning, monitorRunning })}\n`,
 				);
 			} else {
 				process.stdout.write("Coordinator is not running\n");
-				if (watchdogRunning) {
-					process.stdout.write("Watchdog: running\n");
+				if (watchmanRunning) {
+					process.stdout.write("Watchman: running\n");
 				}
 				if (monitorRunning) {
 					process.stdout.write("Monitor: running\n");
@@ -794,7 +839,7 @@ async function statusCoordinator(args: string[], deps: CoordinatorDeps = {}): Pr
 			pid: session.pid,
 			startedAt: session.startedAt,
 			lastActivity: session.lastActivity,
-			watchdogRunning,
+			watchmanRunning,
 			monitorRunning,
 		};
 
@@ -808,7 +853,7 @@ async function statusCoordinator(args: string[], deps: CoordinatorDeps = {}): Pr
 			process.stdout.write(`  PID:       ${session.pid}\n`);
 			process.stdout.write(`  Started:   ${session.startedAt}\n`);
 			process.stdout.write(`  Activity:  ${session.lastActivity}\n`);
-			process.stdout.write(`  Watchdog:  ${watchdogRunning ? "running" : "not running"}\n`);
+			process.stdout.write(`  Watchman:  ${watchmanRunning ? "running" : "not running"}\n`);
 			process.stdout.write(`  Monitor:   ${monitorRunning ? "running" : "not running"}\n`);
 		}
 	} finally {
@@ -830,7 +875,8 @@ Start options:
   --no-attach              Never attach to tmux session after start
                            Default: attach when running in an interactive TTY
   --headless               Start without tmux — use PTY subprocess (no terminal UI)
-  --watchdog               Auto-start watchdog daemon with coordinator
+  --watchman               Auto-start watchman daemon with coordinator
+  --watchdog               Alias for --watchman
   --monitor                Auto-start monitor agent (Tier 2) with coordinator
 
 General options:
@@ -841,7 +887,7 @@ The coordinator runs at the project root and orchestrates work by:
   - Decomposing objectives into beads issues
   - Dispatching agents via legio sling
   - Tracking batches via task groups
-  - Handling escalations from agents and watchdog`;
+  - Handling escalations from agents and watchman`;
 
 /**
  * Entry point for `legio coordinator <subcommand>`.

package/src/commands/costs.test.ts

@@ -11,7 +11,7 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { ValidationError } from "../errors.ts";
 import { createMetricsStore } from "../metrics/store.ts";
 import { createSessionStore } from "../sessions/store.ts";
@@ -44,7 +44,6 @@ describe("costsCommand", () => {
 	let chunks: string[];
 	let originalWrite: typeof process.stdout.write;
 	let tempDir: string;
-	let originalCwd: string;
 
 	beforeEach(async () => {
 		// Spy on stdout
@@ -64,14 +63,11 @@ describe("costsCommand", () => {
 			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
 		);
 
-		// Change to temp dir so loadConfig() works
-		originalCwd = process.cwd();
-		process.chdir(tempDir);
+		vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 	});
 
 	afterEach(async () => {
 		process.stdout.write = originalWrite;
-		process.chdir(originalCwd);
 		await rm(tempDir, { recursive: true, force: true });
 	});
 

package/src/commands/dashboard.test.ts

@@ -9,7 +9,7 @@
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { ValidationError } from "../errors.ts";
 import { dashboardCommand } from "./dashboard.ts";
 
@@ -74,10 +74,9 @@ describe("dashboardCommand", () => {
 		// throws BEFORE the infinite while loop starts. This proves validation passed
 		// (no ValidationError about interval) while preventing the loop from leaking.
 
-		const originalCwd = process.cwd();
+		vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 
 		try {
-			process.chdir(tempDir);
 			await dashboardCommand(["--interval", "500"]);
 		} catch (err) {
 			// If it's a ValidationError about interval, the test should fail
@@ -85,8 +84,6 @@ describe("dashboardCommand", () => {
 				throw new Error("Interval validation should have passed for value 500");
 			}
 			// Other errors (like from loadConfig) are expected - they occur after validation passed
-		} finally {
-			process.chdir(originalCwd);
 		}
 
 		// If we reach here without throwing a ValidationError about interval, validation passed

package/src/commands/doctor.test.ts

@@ -12,7 +12,7 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { ValidationError } from "../errors.ts";
 import { doctorCommand } from "./doctor.ts";
 
@@ -20,7 +20,6 @@ describe("doctorCommand", () => {
 	let chunks: string[];
 	let originalWrite: typeof process.stdout.write;
 	let tempDir: string;
-	let originalCwd: string;
 
 	beforeEach(async () => {
 		// Spy on stdout
@@ -40,14 +39,11 @@ describe("doctorCommand", () => {
 			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
 		);
 
-		// Change to temp dir so loadConfig() works
-		originalCwd = process.cwd();
-		process.chdir(tempDir);
+		vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 	});
 
 	afterEach(async () => {
 		process.stdout.write = originalWrite;
-		process.chdir(originalCwd);
 		await rm(tempDir, { recursive: true, force: true });
 	});
 

package/src/commands/down.ts

@@ -3,7 +3,7 @@
  *
  * Single command to cleanly stop the full legio stack:
  * 1. Stop coordinator (if running) via legio coordinator stop
- *    This also stops the watchdog and monitor agents.
+ *    This also stops the watchman and monitor agents.
  * 2. Stop gateway (if running) via legio gateway stop
  * 3. Stop server (if running) via legio server stop
  *
@@ -63,7 +63,7 @@ Options:
   --json         JSON output
   --help, -h     Show this help
 
-legio down stops the coordinator (including watchdog and monitor), the
+legio down stops the coordinator (including watchman and monitor), the
 gateway agent, and the server. Running legio down when nothing is running
 is a safe no-op.`;
 
@@ -87,7 +87,7 @@ export async function downCommand(args: string[], deps: DownDeps = {}): Promise<
 	let gatewayStopped = false;
 	let serverStopped = false;
 
-	// 1. Stop coordinator (if running) — also stops watchdog + monitor
+	// 1. Stop coordinator (if running) — also stops watchman + monitor
 	const coordStop = await run(["legio", "coordinator", "stop"], { cwd: projectRoot });
 	if (coordStop.exitCode === 0) {
 		coordinatorStopped = true;

package/src/commands/errors.test.ts

@@ -11,7 +11,7 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import type { InsertEvent } from "../types.ts";
@@ -37,7 +37,6 @@ describe("errorsCommand", () => {
 	let chunks: string[];
 	let originalWrite: typeof process.stdout.write;
 	let tempDir: string;
-	let originalCwd: string;
 
 	beforeEach(async () => {
 		// Spy on stdout
@@ -57,14 +56,11 @@ describe("errorsCommand", () => {
 			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
 		);
 
-		// Change to temp dir so loadConfig() works
-		originalCwd = process.cwd();
-		process.chdir(tempDir);
+		vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 	});
 
 	afterEach(async () => {
 		process.stdout.write = originalWrite;
-		process.chdir(originalCwd);
 		await rm(tempDir, { recursive: true, force: true });
 	});
 

package/src/commands/feed.test.ts

@@ -11,7 +11,7 @@
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import type { InsertEvent } from "../types.ts";
@@ -37,7 +37,6 @@ describe("feedCommand", () => {
 	let chunks: string[];
 	let originalWrite: typeof process.stdout.write;
 	let tempDir: string;
-	let originalCwd: string;
 
 	beforeEach(async () => {
 		// Spy on stdout
@@ -57,14 +56,11 @@ describe("feedCommand", () => {
 			`project:\n  name: test\n  root: ${tempDir}\n  canonicalBranch: main\n`,
 		);
 
-		// Change to temp dir so loadConfig() works
-		originalCwd = process.cwd();
-		process.chdir(tempDir);
+		vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 	});
 
 	afterEach(async () => {
 		process.stdout.write = originalWrite;
-		process.chdir(originalCwd);
 		await rm(tempDir, { recursive: true, force: true });
 	});
 

package/src/commands/gateway.test.ts

@@ -13,7 +13,7 @@
 
 import { access, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { AgentError, ValidationError } from "../errors.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { cleanupTempDir, createTempGitRepo } from "../test-helpers.ts";
@@ -68,6 +68,7 @@ function makeFakeTmux(sessionAliveMap: Record<string, boolean> = {}): {
 		sendKeys: async (name: string, keys: string): Promise<void> => {
 			calls.sendKeys.push({ name, keys });
 		},
+		waitForTuiReady: async (): Promise<void> => {},
 	};
 
 	return { tmux, calls };
@@ -77,7 +78,6 @@ function makeFakeTmux(sessionAliveMap: Record<string, boolean> = {}): {
 
 let tempDir: string;
 let legioDir: string;
-const originalCwd = process.cwd();
 
 /** Save sessions to the SessionStore (sessions.db) for test setup. */
 function saveSessionsToDb(sessions: AgentSession[]): void {
@@ -102,10 +102,6 @@ function loadSessionsFromDb(): AgentSession[] {
 }
 
 beforeEach(async () => {
-	// Restore cwd FIRST so createTempGitRepo's git operations don't fail
-	// if a prior test's tempDir was already cleaned up.
-	process.chdir(originalCwd);
-
 	tempDir = await realpath(await createTempGitRepo());
 	legioDir = join(tempDir, ".legio");
 	await mkdir(legioDir, { recursive: true });
@@ -141,12 +137,10 @@ beforeEach(async () => {
 	);
 	await writeFile(join(agentDefsDir, "gateway.md"), "# Gateway\n");
 
-	// Override cwd so gateway commands find our temp project
-	process.chdir(tempDir);
+	vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 }, 30000); // 30s timeout: createTempGitRepo can be slow on first run
 
 afterEach(async () => {
-	process.chdir(originalCwd);
 	await cleanupTempDir(tempDir);
 });
 
@@ -317,7 +311,7 @@ describe("startGateway", () => {
 		expect(config.hooks.Stop).toBeDefined();
 	});
 
-	test("hooks use gateway agent name for event logging", async () => {
+	test("hooks use LEGIO_AGENT_NAME env var for event logging", async () => {
 		const { deps } = makeDeps();
 
 		await captureStdout(() => gatewayCommand(["start", "--no-attach"], deps));
@@ -325,8 +319,8 @@ describe("startGateway", () => {
 		const settingsPath = join(tempDir, ".claude", "settings.local.json");
 		const content = await readFile(settingsPath, "utf-8");
 
-		// The hooks should reference the gateway agent name
-		expect(content).toContain("--agent gateway");
+		// Hooks reference the agent via $LEGIO_AGENT_NAME env var (not hardcoded)
+		expect(content).toContain("--agent $LEGIO_AGENT_NAME");
 	});
 
 	test("hooks include ENV_GUARD to avoid affecting user's Claude Code session", async () => {
@@ -509,6 +503,38 @@ describe("startGateway", () => {
 		// The new session should have a different ID than the dead one
 		expect(newSession?.id).not.toBe("session-dead-gateway");
 	});
+
+	test("re-sends beacon when session stays in booting state", async () => {
+		const { deps, calls } = makeDeps();
+
+		await captureStdout(() => gatewayCommand(["start", "--no-attach"], deps));
+
+		// verifyBeaconDelivery polls store 10 times (all return "booting" since no hooks run),
+		// then retries the full beacon + follow-up Enter.
+		// Total sendKeys calls: 1 (initial beacon) + 1 (follow-up Enter) + 1 (retry beacon) + 1 (retry Enter)
+		const beaconCalls = calls.sendKeys.filter((c) => c.keys.includes("[LEGIO]"));
+		expect(beaconCalls).toHaveLength(2); // initial + retry
+		const enterCalls = calls.sendKeys.filter((c) => c.keys === "");
+		expect(enterCalls).toHaveLength(2); // follow-up Enter + retry Enter
+	});
+
+	test("sends greeting mail to human after beacon delivery", async () => {
+		const { deps } = makeDeps();
+		await captureStdout(() => gatewayCommand(["start", "--no-attach"], deps));
+		// Verify mail.db has the greeting
+		const { createMailStore } = await import("../mail/store.ts");
+		const mailDb = createMailStore(join(legioDir, "mail.db"));
+		try {
+			const msgs = mailDb.getAll({ from: "gateway", to: "human" });
+			expect(msgs).toHaveLength(1);
+			expect(msgs[0]?.subject).toBe("Gateway online");
+			expect(msgs[0]?.body).toContain("online and ready");
+			expect(msgs[0]?.type).toBe("status");
+			expect(msgs[0]?.audience).toBe("human");
+		} finally {
+			mailDb.close();
+		}
+	});
 });
 
 describe("stopGateway", () => {
@@ -687,21 +713,21 @@ describe("buildGatewayBeacon", () => {
 
 	test("includes ISSUES notice", () => {
 		const beacon = buildGatewayBeacon();
-		expect(beacon).toContain("ISSUES: Use bd create");
+		expect(beacon).toContain("ISSUES:");
+		expect(beacon).toContain("legio status");
 	});
 
 	test("includes startup instructions", () => {
 		const beacon = buildGatewayBeacon();
-		expect(beacon).toContain("mulch prime");
 		expect(beacon).toContain("legio mail check --agent gateway");
-		expect(beacon).toContain("respond to user");
+		expect(beacon).toContain("respond to user via BOTH terminal AND mail");
 	});
 
 	test("parts are joined with em-dash separator", () => {
 		const beacon = buildGatewayBeacon();
-		// Should have exactly 4 " — " separators (5 parts)
+		// Should have exactly 5 " — " separators (6 parts)
 		const dashes = beacon.split(" — ");
-		expect(dashes).toHaveLength(5);
+		expect(dashes).toHaveLength(6);
 	});
 
 	test("default (no args) does not include FIRST_RUN", () => {