@katyella/legio 0.1.3 → 0.2.2

package/src/commands/mail.test.ts

@@ -8,7 +8,7 @@
 import { access, mkdir, mkdtemp, readdir, readFile, 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 { createEventStore } from "../events/store.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
@@ -17,7 +17,6 @@ import { mailCommand } from "./mail.ts";
 
 describe("mailCommand", () => {
 	let tempDir: string;
-	let origCwd: string;
 	let origWrite: typeof process.stdout.write;
 	let origStderrWrite: typeof process.stderr.write;
 	let output: string;
@@ -44,9 +43,7 @@ describe("mailCommand", () => {
 		});
 		client.close();
 
-		// Change cwd to temp dir so the command finds .legio/mail.db
-		origCwd = process.cwd();
-		process.chdir(tempDir);
+		vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 
 		// Capture stdout
 		output = "";
@@ -68,7 +65,6 @@ describe("mailCommand", () => {
 	afterEach(async () => {
 		process.stdout.write = origWrite;
 		process.stderr.write = origStderrWrite;
-		process.chdir(origCwd);
 		await rm(tempDir, { recursive: true, force: true });
 	});
 
@@ -546,240 +542,105 @@ describe("mailCommand", () => {
 		});
 	});
 
-	describe("mail check debounce", () => {
-		test("mail check without --debounce flag always executes", async () => {
-			// Send first message
-			const store = createMailStore(join(tempDir, ".legio", "mail.db"));
-			const client = createMailClient(store);
-			client.send({
-				from: "orchestrator",
-				to: "test-agent",
-				subject: "Message 1",
-				body: "First message",
-			});
-			client.close();
-
-			// First check
+	describe("mail check --signal", () => {
+		test("--signal skips DB query when no signal file exists", async () => {
 			output = "";
-			await mailCommand(["check", "--inject", "--agent", "test-agent"]);
-			const firstOutput = output;
-
-			// Send second message
-			const store2 = createMailStore(join(tempDir, ".legio", "mail.db"));
-			const client2 = createMailClient(store2);
-			client2.send({
-				from: "orchestrator",
-				to: "test-agent",
-				subject: "Message 2",
-				body: "Second message",
-			});
-			client2.close();
-
-			// Second check immediately after
-			output = "";
-			await mailCommand(["check", "--inject", "--agent", "test-agent"]);
-			const secondOutput = output;
-
-			// Both should execute (no debouncing without flag)
-			expect(firstOutput).toContain("Message 1");
-			expect(secondOutput).toContain("Message 2");
-		});
-
-		test("mail check with --debounce skips second check within window", async () => {
-			// First check with debounce (large window to survive concurrency)
-			output = "";
-			await mailCommand(["check", "--agent", "builder-1", "--debounce", "10000"]);
-			expect(output).toContain("Build task");
-
-			// Second check immediately (within debounce window)
-			output = "";
-			await mailCommand(["check", "--agent", "builder-1", "--debounce", "10000"]);
-			// Should be skipped silently
+			await mailCommand(["check", "--inject", "--agent", "builder-1", "--signal"]);
+			// No signal file = no output, no DB query
 			expect(output).toBe("");
 		});
 
-		test("mail check with --debounce allows check after window expires", async () => {
-			// Send first message
-			const store = createMailStore(join(tempDir, ".legio", "mail.db"));
-			const client = createMailClient(store);
-			client.send({
-				from: "orchestrator",
-				to: "debounce-test",
-				subject: "First",
-				body: "First check",
-			});
-			client.close();
-
-			// First check with debounce
-			output = "";
-			await mailCommand(["check", "--inject", "--agent", "debounce-test", "--debounce", "100"]);
-			expect(output).toContain("First check");
-
-			// Wait for debounce window to expire
-			await new Promise((resolve) => setTimeout(resolve, 150));
-
-			// Send second message
-			const store2 = createMailStore(join(tempDir, ".legio", "mail.db"));
-			const client2 = createMailClient(store2);
-			client2.send({
-				from: "orchestrator",
-				to: "debounce-test",
-				subject: "Second",
-				body: "Second check",
-			});
-			client2.close();
+		test("--signal queries DB and injects when signal file exists", async () => {
+			// Write a signal file for builder-1
+			const nudgeDir = join(tempDir, ".legio", "pending-nudges");
+			await mkdir(nudgeDir, { recursive: true });
+			await writeFile(
+				join(nudgeDir, "builder-1.json"),
+				JSON.stringify({
+					from: "orchestrator",
+					reason: "status",
+					subject: "Build task",
+					messageId: "test-msg-1",
+					createdAt: new Date().toISOString(),
+				}),
+			);
 
-			// Second check after debounce window
 			output = "";
-			await mailCommand(["check", "--inject", "--agent", "debounce-test", "--debounce", "100"]);
-			expect(output).toContain("Second check");
+			await mailCommand(["check", "--inject", "--agent", "builder-1", "--signal"]);
+			// Should inject the message AND show priority banner
+			expect(output).toContain("Build task");
+			expect(output).toContain("PRIORITY");
 		});
 
-		test("mail check with --debounce 0 disables debouncing", async () => {
-			// Send first message
-			const store = createMailStore(join(tempDir, ".legio", "mail.db"));
-			const client = createMailClient(store);
-			client.send({
-				from: "orchestrator",
-				to: "zero-debounce",
-				subject: "Msg 1",
-				body: "Message one",
-			});
-			client.close();
-
-			// First check with --debounce 0
-			output = "";
-			await mailCommand(["check", "--inject", "--agent", "zero-debounce", "--debounce", "0"]);
-			expect(output).toContain("Message one");
+		test("--signal clears signal file after check", async () => {
+			// Write a signal file
+			const nudgeDir = join(tempDir, ".legio", "pending-nudges");
+			await mkdir(nudgeDir, { recursive: true });
+			const signalPath = join(nudgeDir, "builder-1.json");
+			await writeFile(
+				signalPath,
+				JSON.stringify({
+					from: "orchestrator",
+					reason: "status",
+					subject: "Build task",
+					messageId: "test-msg-1",
+					createdAt: new Date().toISOString(),
+				}),
+			);
 
-			// Send second message immediately
-			const store2 = createMailStore(join(tempDir, ".legio", "mail.db"));
-			const client2 = createMailClient(store2);
-			client2.send({
-				from: "orchestrator",
-				to: "zero-debounce",
-				subject: "Msg 2",
-				body: "Message two",
-			});
-			client2.close();
+			await mailCommand(["check", "--inject", "--agent", "builder-1", "--signal"]);
 
-			// Second check immediately (should work with debounce 0)
-			output = "";
-			await mailCommand(["check", "--inject", "--agent", "zero-debounce", "--debounce", "0"]);
-			expect(output).toContain("Message two");
+			// Signal file should be cleared by readAndClearPendingNudge
+			await expect(access(signalPath)).rejects.toThrow();
 		});
 
-		test("mail check debounce is per-agent", async () => {
-			// Check for builder-1 with debounce (large window to survive concurrency)
-			output = "";
-			await mailCommand(["check", "--agent", "builder-1", "--debounce", "10000"]);
-			expect(output).toContain("Build task");
-
-			// Check for scout-1 immediately (different agent, should NOT be debounced)
-			output = "";
-			await mailCommand(["check", "--agent", "scout-1", "--debounce", "10000"]);
-			expect(output).toContain("Explore API");
-
-			// Check for builder-1 again (should be debounced)
+		test("--signal without --inject still respects signal gating", async () => {
+			// No signal file — should skip
 			output = "";
-			await mailCommand(["check", "--agent", "builder-1", "--debounce", "10000"]);
+			await mailCommand(["check", "--agent", "builder-1", "--signal"]);
 			expect(output).toBe("");
-		});
-
-		test("mail check --debounce with invalid value throws ValidationError", async () => {
-			try {
-				await mailCommand(["check", "--agent", "builder-1", "--debounce", "invalid"]);
-				expect(true).toBe(false); // Should not reach here
-			} catch (err) {
-				expect(err).toBeInstanceOf(Error);
-				if (err instanceof Error) {
-					expect(err.message).toContain("must be a non-negative integer");
-				}
-			}
-		});
 
-		test("mail check --debounce with negative value throws ValidationError", async () => {
-			try {
-				await mailCommand(["check", "--agent", "builder-1", "--debounce", "-100"]);
-				expect(true).toBe(false);
-			} catch (err) {
-				expect(err).toBeInstanceOf(Error);
-				if (err instanceof Error) {
-					expect(err.message).toContain("must be a non-negative integer");
-				}
-			}
-		});
+			// With signal file — should show messages
+			const nudgeDir = join(tempDir, ".legio", "pending-nudges");
+			await mkdir(nudgeDir, { recursive: true });
+			await writeFile(
+				join(nudgeDir, "builder-1.json"),
+				JSON.stringify({
+					from: "orchestrator",
+					reason: "status",
+					subject: "Build task",
+					messageId: "test-msg-1",
+					createdAt: new Date().toISOString(),
+				}),
+			);
 
-		test("mail check --inject with --debounce skips check within window", async () => {
-			// First inject check with debounce
 			output = "";
-			await mailCommand(["check", "--inject", "--agent", "builder-1", "--debounce", "500"]);
+			await mailCommand(["check", "--agent", "builder-1", "--signal"]);
 			expect(output).toContain("Build task");
-
-			// Second inject check immediately (should be debounced)
-			output = "";
-			await mailCommand(["check", "--inject", "--agent", "builder-1", "--debounce", "500"]);
-			expect(output).toBe("");
 		});
 
-		test("mail check debounce state persists across invocations", async () => {
-			// First check
-			output = "";
+		test("--debounce flag emits deprecation warning", async () => {
+			stderrOutput = "";
 			await mailCommand(["check", "--agent", "builder-1", "--debounce", "500"]);
-			expect(output).toContain("Build task");
-
-			// Verify state file was created
-			const statePath = join(tempDir, ".legio", "mail-check-state.json");
-			{
-				let _e = false;
-				try {
-					await access(statePath);
-					_e = true;
-				} catch {}
-				expect(_e).toBe(true);
-			}
-
-			const state = JSON.parse(await readFile(statePath, "utf-8")) as Record<string, number>;
-			expect(state["builder-1"]).toBeTruthy();
-			expect(typeof state["builder-1"]).toBe("number");
+			expect(stderrOutput).toContain("--debounce is deprecated");
 		});
 
-		test("corrupted debounce state file is handled gracefully", async () => {
-			// Write corrupted state file
-			const statePath = join(tempDir, ".legio", "mail-check-state.json");
-			await writeFile(statePath, "not valid json");
+		test("without --signal flag always executes (backward compat)", async () => {
+			// Send first message
+			const store = createMailStore(join(tempDir, ".legio", "mail.db"));
+			const client = createMailClient(store);
+			client.send({
+				from: "orchestrator",
+				to: "test-agent",
+				subject: "Message 1",
+				body: "First message",
+			});
+			client.close();
 
-			// Should not throw, should treat as fresh state
+			// Check without --signal flag — always queries DB
 			output = "";
-			await mailCommand(["check", "--agent", "builder-1", "--debounce", "500"]);
-			expect(output).toContain("Build task");
-
-			// State should be corrected
-			const state = JSON.parse(await readFile(statePath, "utf-8")) as Record<string, number>;
-			expect(state["builder-1"]).toBeTruthy();
-		});
-
-		test("mail check debounce only records timestamp when flag is provided", async () => {
-			const statePath = join(tempDir, ".legio", "mail-check-state.json");
-
-			// Check without debounce flag
-			await mailCommand(["check", "--agent", "builder-1"]);
-
-			// State file should not be created
-			await expect(access(statePath)).rejects.toThrow();
-
-			// Check with debounce flag
-			await mailCommand(["check", "--agent", "builder-1", "--debounce", "500"]);
-
-			// Now state file should exist
-			{
-				let _e = false;
-				try {
-					await access(statePath);
-					_e = true;
-				} catch {}
-				expect(_e).toBe(true);
-			}
+			await mailCommand(["check", "--inject", "--agent", "test-agent"]);
+			expect(output).toContain("Message 1");
 		});
 	});
 

package/src/commands/mail.ts

@@ -6,13 +6,19 @@
  * and various filters for listing messages.
  */
 
-import { access, readFile, writeFile } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveProjectRoot } from "../config.ts";
 import { MailError, ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { isGroupAddress, resolveGroupAddress } from "../mail/broadcast.ts";
 import { createMailClient } from "../mail/client.ts";
+import {
+	isAgentIdle,
+	pendingNudgeDir,
+	readAndClearPendingNudge,
+	writePendingNudge,
+} from "../mail/pending.ts";
 import { createMailStore } from "../mail/store.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { MailAudience, MailMessage } from "../types.ts";
@@ -56,7 +62,15 @@ function hasFlag(args: string[], flag: string): boolean {
 }
 
 /** Boolean flags that do NOT consume the next arg as a value. */
-const BOOLEAN_FLAGS = new Set(["--json", "--inject", "--unread", "--all", "--help", "-h"]);
+const BOOLEAN_FLAGS = new Set([
+	"--json",
+	"--inject",
+	"--unread",
+	"--all",
+	"--signal",
+	"--help",
+	"-h",
+]);
 
 /**
  * Extract positional arguments from an args array, skipping flag-value pairs.
@@ -141,165 +155,6 @@ function openStore(cwd: string) {
 	return createMailStore(dbPath);
 }
 
-// === Pending Nudge Markers ===
-//
-// Instead of sending tmux keys (which corrupt tool I/O), auto-nudge writes
-// a JSON marker file per agent. The `mail check --inject` flow reads and
-// clears these markers, prepending a priority banner to the injected output.
-
-/** Directory where pending nudge markers are stored. */
-function pendingNudgeDir(cwd: string): string {
-	return join(cwd, ".legio", "pending-nudges");
-}
-
-/**
- * Check if an agent is idle (not actively executing a tool).
- *
- * An agent is considered idle when `.legio/agent-busy/{agentName}` does NOT exist.
- * The busy marker is written by hooks during active tool execution and removed when idle.
- * Idle agents can receive a direct tmux nudge; busy agents only get the pending marker.
- */
-async function isAgentIdle(cwd: string, agentName: string): Promise<boolean> {
-	const busyPath = join(cwd, ".legio", "agent-busy", agentName);
-	try {
-		await access(busyPath);
-		return false; // busy marker present — agent is actively working
-	} catch {
-		return true; // no busy marker — agent is idle
-	}
-}
-
-/** Shape of a pending nudge marker file. */
-interface PendingNudge {
-	from: string;
-	reason: string;
-	subject: string;
-	messageId: string;
-	createdAt: string;
-}
-
-/**
- * Write a pending nudge marker for an agent.
- *
- * Creates `.legio/pending-nudges/{agent}.json` so that the next
- * `mail check --inject` call surfaces a priority banner for this message.
- * Overwrites any existing marker (only the latest nudge matters).
- */
-async function writePendingNudge(
-	cwd: string,
-	agentName: string,
-	nudge: Omit<PendingNudge, "createdAt">,
-): Promise<void> {
-	const dir = pendingNudgeDir(cwd);
-	const { mkdir } = await import("node:fs/promises");
-	await mkdir(dir, { recursive: true });
-
-	const marker: PendingNudge = {
-		...nudge,
-		createdAt: new Date().toISOString(),
-	};
-	const filePath = join(dir, `${agentName}.json`);
-	await writeFile(filePath, `${JSON.stringify(marker, null, "\t")}\n`);
-}
-
-/**
- * Read and clear pending nudge markers for an agent.
- *
- * Returns the pending nudge (if any) and removes the marker file.
- * Called by `mail check --inject` to prepend a priority banner.
- */
-async function readAndClearPendingNudge(
-	cwd: string,
-	agentName: string,
-): Promise<PendingNudge | null> {
-	const filePath = join(pendingNudgeDir(cwd), `${agentName}.json`);
-	try {
-		await access(filePath);
-	} catch {
-		return null;
-	}
-	try {
-		const text = await readFile(filePath, "utf-8");
-		const nudge = JSON.parse(text) as PendingNudge;
-		const { unlink } = await import("node:fs/promises");
-		await unlink(filePath);
-		return nudge;
-	} catch {
-		// Corrupt or race condition — clear it and move on
-		try {
-			const { unlink } = await import("node:fs/promises");
-			await unlink(filePath);
-		} catch {
-			// Already gone
-		}
-		return null;
-	}
-}
-
-// === Mail Check Debounce ===
-//
-// Prevents excessive mail checking by tracking the last check timestamp per agent.
-// When --debounce flag is provided, mail check will skip if called within the
-// debounce window.
-
-/**
- * Path to the mail check debounce state file.
- */
-function mailCheckStatePath(cwd: string): string {
-	return join(cwd, ".legio", "mail-check-state.json");
-}
-
-/**
- * Check if a mail check for this agent is within the debounce window.
- *
- * @param cwd - Project root directory
- * @param agentName - Agent name
- * @param debounceMs - Debounce interval in milliseconds
- * @returns true if the last check was within the debounce window
- */
-async function isMailCheckDebounced(
-	cwd: string,
-	agentName: string,
-	debounceMs: number,
-): Promise<boolean> {
-	const statePath = mailCheckStatePath(cwd);
-	try {
-		await access(statePath);
-	} catch {
-		return false;
-	}
-	try {
-		const text = await readFile(statePath, "utf-8");
-		const state = JSON.parse(text) as Record<string, number>;
-		const lastCheck = state[agentName];
-		if (lastCheck === undefined) {
-			return false;
-		}
-		return Date.now() - lastCheck < debounceMs;
-	} catch {
-		return false;
-	}
-}
-
-/**
- * Record a mail check timestamp for debounce tracking.
- *
- * @param cwd - Project root directory
- * @param agentName - Agent name
- */
-async function recordMailCheck(cwd: string, agentName: string): Promise<void> {
-	const statePath = mailCheckStatePath(cwd);
-	let state: Record<string, number> = {};
-	try {
-		const text = await readFile(statePath, "utf-8");
-		state = JSON.parse(text) as Record<string, number>;
-	} catch {
-		// File does not exist or corrupt state — start fresh
-	}
-	state[agentName] = Date.now();
-	await writeFile(statePath, `${JSON.stringify(state, null, "\t")}\n`);
-}
-
 /**
  * Open a mail client connected to the project's mail.db.
  * The cwd must already be resolved to the canonical project root.
@@ -336,7 +191,14 @@ async function handleSend(args: string[], cwd: string): Promise<void> {
 	}
 
 	const type = rawType as MailMessage["type"];
-	const priority = rawPriority as MailMessage["priority"];
+	let priority = rawPriority as MailMessage["priority"];
+
+	// escalation and dispatch default to high priority when no explicit --priority was given
+	const HIGH_PRIORITY_DEFAULT_TYPES = new Set(["escalation", "dispatch"]);
+	const explicitPriority = getFlag(args, "--priority") !== undefined;
+	if (!explicitPriority && HIGH_PRIORITY_DEFAULT_TYPES.has(type)) {
+		priority = "high";
+	}
 
 	// Parse --audience flag (optional, auto-derived from type if not specified)
 	const rawAudience = getFlag(args, "--audience");
@@ -628,8 +490,17 @@ async function handleCheck(args: string[], cwd: string): Promise<void> {
 	const agent = getFlag(args, "--agent") ?? "orchestrator";
 	const inject = hasFlag(args, "--inject");
 	const json = hasFlag(args, "--json");
-	const debounceFlag = getFlag(args, "--debounce");
+	const signal = hasFlag(args, "--signal");
 	const audience = getFlag(args, "--audience");
+
+	// --debounce is deprecated (no-op). Accept silently for backward compat.
+	// The --signal flag replaces debounce — signal files are the authoritative trigger.
+	if (getFlag(args, "--debounce") !== undefined) {
+		process.stderr.write(
+			"⚠️  --debounce is deprecated and ignored. Use --signal for signal-gated mail checks.\n",
+		);
+	}
+
 	if (audience !== undefined && !(VALID_AUDIENCES as readonly string[]).includes(audience)) {
 		throw new ValidationError(
 			`Invalid --audience "${audience}". Must be one of: ${VALID_AUDIENCES.join(", ")}`,
@@ -637,24 +508,14 @@ async function handleCheck(args: string[], cwd: string): Promise<void> {
 		);
 	}
 
-	// Parse debounce interval if provided
-	let debounceMs: number | undefined;
-	if (debounceFlag !== undefined) {
-		const parsed = Number.parseInt(debounceFlag, 10);
-		if (Number.isNaN(parsed) || parsed < 0) {
-			throw new ValidationError(
-				`--debounce must be a non-negative integer (milliseconds), got: ${debounceFlag}`,
-				{ field: "debounce", value: debounceFlag },
-			);
-		}
-		debounceMs = parsed;
-	}
-
-	// Check debounce if enabled
-	if (debounceMs !== undefined) {
-		const debounced = await isMailCheckDebounced(cwd, agent, debounceMs);
-		if (debounced) {
-			// Silent skip — no output when debounced
+	// Signal-gated mode: skip DB query entirely if no signal file exists.
+	// The signal file is the pending nudge marker written by `mail send`.
+	if (signal) {
+		const signalPath = join(pendingNudgeDir(cwd), `${agent}.json`);
+		try {
+			await access(signalPath);
+		} catch {
+			// No signal file — no new mail. Exit immediately (zero cost).
 			return;
 		}
 	}
@@ -712,11 +573,6 @@ async function handleCheck(args: string[], cwd: string): Promise<void> {
 				}
 			}
 		}
-
-		// Record this check for debounce tracking (only if debounce is enabled)
-		if (debounceMs !== undefined) {
-			await recordMailCheck(cwd, agent);
-		}
 	} finally {
 		client.close();
 	}
@@ -869,7 +725,7 @@ Subcommands:
            Audience: defaults to 'agent' for protocol types, 'both' for semantic types
   check    Check inbox (unread messages)
              [--agent <name>] [--audience <human|agent|both>]
-             [--inject] [--json]
+             [--inject] [--signal] [--json]
   list     List messages with filters
              [--from <name>] [--to <name>] [--agent <name> (alias for --to)]
              [--audience <human|agent|both>] [--unread] [--json]