@katyella/legio 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-03-02
+
+### Fixed
+- Coordinator and sling beacons now explain what legio is — previously Claude Code on fresh machines rejected thin beacons as "unrecognized" foreign content (same fix as gateway in v0.2.1)
+- Coordinator beacon startup instructions use `legio status` instead of `bd ready` / `legio group status` (doesn't assume beads is installed)
+- `legio doctor` no longer flags persistent agent identity files (coordinator, gateway, monitor) as stale — they legitimately exist outside the agent manifest
+- Gateway greeting mail ("Gateway is online and ready") is only sent after confirmed beacon delivery — previously it was sent even when the beacon was rejected
+- 2399 tests across 79 test files (up from 2397 across 79)
+
+## [0.2.2] - 2026-03-02
+
+### Fixed
+- Coordinator and sling beacons now explain what legio is — previously Claude Code on fresh machines rejected thin beacons as "unrecognized" foreign content (same fix as gateway in v0.2.1)
+- Coordinator beacon startup instructions use `legio status` instead of `bd ready` / `legio group status` (doesn't assume beads is installed)
+- `legio doctor` no longer flags persistent agent identity files (coordinator, gateway, monitor) as stale — they legitimately exist outside the agent manifest
+- 2398 tests across 79 test files (up from 2397 across 79)
+
+## [0.2.1] - 2026-03-02
+
+### Fixed
+- Gateway beacon now explains what legio is — previously Claude Code on fresh machines rejected the thin beacon as "unrecognized" foreign content
+- Gateway tmux session now receives provider env vars (`collectProviderEnv()`) — was the only agent type missing them
+- Removed hardcoded `bd create` from gateway beacon (not all users have beads)
+- `legio doctor` checks for bun availability with install instructions (required runtime for seeds and mulch)
+- `legio doctor` marks sd, mulch, and bd as optional dependencies (warn instead of fail)
+- Doctor install hints explain what each tool does and note bun requirement
+- README requirements section separates required (Node, Claude Code, git, tmux) from optional (sd, mulch, bd) dependencies
+
 ## [0.2.0] - 2026-03-02
 
 ### Added
@@ -182,7 +210,10 @@ Initial public release on npm as [`@katyella/legio`](https://www.npmjs.com/packa
 - E2E lifecycle tests via Playwright
 - Vitest test runner with forks pool for CI compatibility
 
-[Unreleased]: https://github.com/katyella/legio/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/katyella/legio/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/katyella/legio/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/katyella/legio/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/katyella/legio/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/katyella/legio/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/katyella/legio/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/katyella/legio/compare/v0.1.1...v0.1.2

package/README.md

@@ -116,8 +116,12 @@ npm link
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
 - git
 - tmux
-- [bd (beads)](https://github.com/steveyegge/beads) — issue tracking CLI
-- [mulch](https://github.com/jayminwest/mulch) — structured expertise management CLI (`npm install -g @os-eco/mulch-cli`)
+
+### Optional
+
+- [sd (seeds)](https://github.com/jayminwest/seeds) — issue tracking CLI (`bun install -g @os-eco/seeds-cli`) — requires [Bun](https://bun.sh)
+- [mulch](https://github.com/jayminwest/mulch) — structured expertise management CLI (`bun install -g @os-eco/mulch-cli`) — requires [Bun](https://bun.sh)
+- [bd (beads)](https://github.com/steveyegge/beads) — legacy issue tracker (alternative to seeds)
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@katyella/legio",
-	"version": "0.2.0",
+	"version": "0.2.3",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Matthew Wojtowicz",
 	"license": "MIT",

package/src/commands/coordinator.test.ts

@@ -875,8 +875,7 @@ describe("buildCoordinatorBeacon", () => {
 		const beacon = buildCoordinatorBeacon();
 		expect(beacon).toContain("mulch prime");
 		expect(beacon).toContain("legio mail check --agent coordinator");
-		expect(beacon).toContain("bd ready");
-		expect(beacon).toContain("legio group status");
+		expect(beacon).toContain("legio status");
 	});
 
 	test("includes hierarchy enforcement instruction", () => {
@@ -891,11 +890,17 @@ describe("buildCoordinatorBeacon", () => {
 		expect(beacon).toContain("spawn a lead who will spawn scouts");
 	});
 
+	test("explains what legio is", () => {
+		const beacon = buildCoordinatorBeacon();
+		expect(beacon).toContain("legio multi-agent orchestration system");
+		expect(beacon).toContain("CLI tool installed on this machine");
+	});
+
 	test("parts are joined with em-dash separator", () => {
 		const beacon = buildCoordinatorBeacon();
-		// 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);
 	});
 });
 

package/src/commands/coordinator.ts

@@ -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(" — ");
 }

package/src/commands/gateway.test.ts

@@ -518,8 +518,26 @@ describe("startGateway", () => {
 		expect(enterCalls).toHaveLength(2); // follow-up Enter + retry Enter
 	});
 
-	test("sends greeting mail to human after beacon delivery", async () => {
-		const { deps } = makeDeps();
+	test("sends greeting mail to human after confirmed beacon delivery", async () => {
+		const { tmux } = makeFakeTmux();
+		// Simulate hooks transitioning session out of "booting" after a few sleep calls
+		let sleepCount = 0;
+		const deps: GatewayDeps = {
+			_tmux: tmux,
+			_sleep: async () => {
+				sleepCount++;
+				// After 3 sleeps (waitForTuiReady + follow-up Enter delay + first poll),
+				// transition session to "working" like hooks would
+				if (sleepCount === 3) {
+					const { store } = openSessionStore(legioDir);
+					try {
+						store.updateState("gateway", "working");
+					} finally {
+						store.close();
+					}
+				}
+			},
+		};
 		await captureStdout(() => gatewayCommand(["start", "--no-attach"], deps));
 		// Verify mail.db has the greeting
 		const { createMailStore } = await import("../mail/store.ts");
@@ -535,6 +553,20 @@ describe("startGateway", () => {
 			mailDb.close();
 		}
 	});
+
+	test("does not send greeting mail when beacon delivery fails", async () => {
+		const { deps } = makeDeps();
+		await captureStdout(() => gatewayCommand(["start", "--no-attach"], deps));
+		// verifyBeaconDelivery returns false (session stays in "booting"), so no greeting mail
+		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(0);
+		} finally {
+			mailDb.close();
+		}
+	});
 });
 
 describe("stopGateway", () => {
@@ -713,21 +745,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 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", () => {

package/src/commands/gateway.ts

@@ -18,7 +18,7 @@ import { join } from "node:path";
 import { deployHooks } from "../agents/hooks-deployer.ts";
 import { createIdentity, loadIdentity } from "../agents/identity.ts";
 import { createManifestLoader, resolveModel } from "../agents/manifest.ts";
-import { loadConfig } from "../config.ts";
+import { collectProviderEnv, loadConfig } from "../config.ts";
 import { AgentError, ValidationError } from "../errors.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import type { SessionStore } from "../sessions/store.ts";
@@ -82,10 +82,11 @@ export function buildGatewayBeacon(isFirstRun = false): string {
 	const timestamp = new Date().toISOString();
 	const parts = [
 		`[LEGIO] ${GATEWAY_NAME} (gateway) ${timestamp}`,
-		"Depth: 0 | Role: planning companion",
-		"READONLY: No Write/Edit",
-		"ISSUES: Use bd create",
-		`Startup: run mulch prime, check mail (legio mail check --agent ${GATEWAY_NAME}), respond to user via BOTH terminal AND mail (legio mail send --to human --subject "chat" --body "..." --type status --agent ${GATEWAY_NAME}) so replies appear in dashboard chat`,
+		"You are a gateway 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 | Role: planning companion | READONLY: No Write/Edit tool access",
+		'COMMUNICATION: Use legio mail for all inter-agent messaging. Check your inbox with: legio mail check --agent gateway. Send replies via: legio mail send --to human --subject "chat" --body "..." --type status --agent gateway',
+		"ISSUES: If a task tracker is configured, use it to create issues for work decomposition. Check legio status for current agent fleet.",
+		`Startup: check mail (legio mail check --agent ${GATEWAY_NAME}), respond to user via BOTH terminal AND mail so replies appear in dashboard chat`,
 	];
 	if (isFirstRun) {
 		parts.push("FIRST_RUN: true — Follow the First Run workflow in your agent definition");
@@ -117,7 +118,7 @@ async function verifyBeaconDelivery(
 	tmuxSession: string,
 	beacon: string,
 	sleep: (ms: number) => Promise<void>,
-): Promise<void> {
+): Promise<boolean> {
 	const MAX_CHECKS = 10;
 	const INTERVAL_MS = 2_000;
 
@@ -126,7 +127,7 @@ async function verifyBeaconDelivery(
 		const session = store.getByName(GATEWAY_NAME);
 		if (session && session.state !== "booting") {
 			// Beacon confirmed — gateway transitioned out of booting
-			return;
+			return true;
 		}
 	}
 
@@ -141,7 +142,9 @@ async function verifyBeaconDelivery(
 	const finalSession = store.getByName(GATEWAY_NAME);
 	if (!finalSession || finalSession.state === "booting") {
 		process.stderr.write("[legio] Warning: gateway beacon delivery could not be confirmed\n");
+		return false;
 	}
+	return true;
 }
 
 /**
@@ -238,6 +241,7 @@ async function startGateway(args: string[], deps: GatewayDeps = {}): Promise<voi
 		await writeFile(settingsPath, JSON.stringify(settings), "utf-8");
 		const claudeCmd = `claude --model ${model} --dangerously-skip-permissions --settings ${settingsPath}`;
 		const pid = await tmux.createSession(tmuxSession, projectRoot, claudeCmd, {
+			...collectProviderEnv(),
 			LEGIO_AGENT_NAME: GATEWAY_NAME,
 		});
 
@@ -303,25 +307,27 @@ async function startGateway(args: string[], deps: GatewayDeps = {}): Promise<voi
 
 		// Verify 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);
-
-		// Send greeting mail to human
-		const { createMailStore } = await import("../mail/store.ts");
-		const mailDb = createMailStore(join(legioDir, "mail.db"));
-		try {
-			mailDb.insert({
-				id: "",
-				from: GATEWAY_NAME,
-				to: "human",
-				subject: "Gateway online",
-				body: "Gateway is online and ready. Send a message to start chatting.",
-				type: "status",
-				priority: "normal",
-				threadId: null,
-				audience: "human",
-			});
-		} finally {
-			mailDb.close();
+		const confirmed = await verifyBeaconDelivery(store, tmux, tmuxSession, beacon, sleep);
+
+		// Send greeting mail to human only after confirmed beacon delivery
+		if (confirmed) {
+			const { createMailStore } = await import("../mail/store.ts");
+			const mailDb = createMailStore(join(legioDir, "mail.db"));
+			try {
+				mailDb.insert({
+					id: "",
+					from: GATEWAY_NAME,
+					to: "human",
+					subject: "Gateway online",
+					body: "Gateway is online and ready. Send a message to start chatting.",
+					type: "status",
+					priority: "normal",
+					threadId: null,
+					audience: "human",
+				});
+			} finally {
+				mailDb.close();
+			}
 		}
 
 		if (shouldAttach) {

package/src/commands/sling.test.ts

@@ -399,12 +399,17 @@ describe("buildBeacon", () => {
 		expect(beacon).toContain("Depth: 0 | Parent: none");
 	});
 
+	test("explains what legio is", () => {
+		const beacon = buildBeacon(makeBeaconOpts());
+		expect(beacon).toContain("legio multi-agent orchestration system");
+		expect(beacon).toContain("CLI tool installed on this machine");
+	});
+
 	test("includes startup instructions with agent name and task ID", () => {
 		const opts = makeBeaconOpts({ agentName: "scout-1", taskId: "legio-xyz" });
 		const beacon = buildBeacon(opts);
 
 		expect(beacon).toContain("read .claude/CLAUDE.md");
-		expect(beacon).toContain("mulch prime");
 		expect(beacon).toContain("legio mail check --agent scout-1");
 		expect(beacon).toContain("begin task legio-xyz");
 	});

package/src/commands/sling.ts

@@ -115,8 +115,9 @@ export function buildBeacon(opts: BeaconOptions): string {
 	const parent = opts.parentAgent ?? "none";
 	const parts = [
 		`[LEGIO] ${opts.agentName} (${opts.capability}) ${timestamp} task:${opts.taskId}`,
+		"You are an 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: ${opts.depth} | Parent: ${parent}`,
-		`Startup: read .claude/CLAUDE.md, run mulch prime, check mail (legio mail check --agent ${opts.agentName}), then begin task ${opts.taskId}`,
+		`Startup: read .claude/CLAUDE.md, check mail (legio mail check --agent ${opts.agentName}), then begin task ${opts.taskId}`,
 	];
 	return parts.join(" — ");
 }

package/src/doctor/agents.test.ts

@@ -375,6 +375,51 @@ sessionsCompleted: -5
 		expect(identityCheck?.details?.some((d) => d.includes("sessionsCompleted"))).toBe(true);
 	});
 
+	test("does not flag persistent agent identities as stale", async () => {
+		const manifest = {
+			version: "1.0",
+			agents: {
+				scout: {
+					file: "scout.md",
+					model: "haiku",
+					tools: ["Read"],
+					capabilities: ["explore"],
+					canSpawn: false,
+					constraints: [],
+				},
+			},
+			capabilityIndex: {
+				explore: ["scout"],
+			},
+		};
+
+		await mkdir(join(legioDir, "agent-defs"), { recursive: true });
+		await mkdir(join(legioDir, "agents", "gateway"), { recursive: true });
+		await mkdir(join(legioDir, "agents", "coordinator"), { recursive: true });
+		await writeFile(join(legioDir, "agent-manifest.json"), JSON.stringify(manifest, null, 2));
+		await writeFile(join(legioDir, "agent-defs", "scout.md"), "# Scout");
+
+		const identity = `name: gateway
+capability: gateway
+created: "2024-01-01T00:00:00Z"
+sessionsCompleted: 3
+`;
+		await writeFile(join(legioDir, "agents", "gateway", "identity.yaml"), identity);
+
+		const coordIdentity = `name: coordinator
+capability: coordinator
+created: "2024-01-01T00:00:00Z"
+sessionsCompleted: 10
+`;
+		await writeFile(join(legioDir, "agents", "coordinator", "identity.yaml"), coordIdentity);
+
+		const checks = await checkAgents(mockConfig, legioDir);
+
+		const staleCheck = checks.find((c) => c.name === "Stale identities");
+		// Should not warn — persistent agents are expected to have identity files
+		expect(staleCheck?.status).not.toBe("warn");
+	});
+
 	test("warns about stale identity files", async () => {
 		const manifest = {
 			version: "1.0",

package/src/doctor/agents.ts

@@ -5,6 +5,8 @@ import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
 
 const VALID_MODELS = new Set(["sonnet", "opus", "haiku"]);
 const VALID_NAME_REGEX = /^[a-zA-Z0-9_-]+$/;
+/** Persistent agents create identity files but are not registered in the agent manifest. */
+const PERSISTENT_AGENTS = new Set(["coordinator", "gateway", "monitor"]);
 
 /**
  * Check if a path exists.
@@ -313,8 +315,8 @@ export const checkAgents: DoctorCheckFn = async (_config, legioDir): Promise<Doc
 
 			identityFileCount++;
 
-			// Check if agent still exists in manifest
-			if (!manifest.agents[agentName]) {
+			// Check if agent still exists in manifest (persistent agents are not manifest-registered)
+			if (!manifest.agents[agentName] && !PERSISTENT_AGENTS.has(agentName)) {
 				staleIdentities.push(agentName);
 				continue;
 			}

package/src/doctor/dependencies.test.ts

@@ -56,46 +56,26 @@ describe("checkDependencies", () => {
 		const checks = await checkDependencies(mockConfig, "/tmp/.legio");
 
 		expect(Array.isArray(checks)).toBe(true);
-		expect(checks.length).toBeGreaterThanOrEqual(5);
+		expect(checks.length).toBeGreaterThanOrEqual(6);
 
 		// Verify we have checks for each tool
 		const toolNames = checks.map((c) => c.name);
 		expect(toolNames).toContain("git availability");
 		expect(toolNames).toContain("node availability");
 		expect(toolNames).toContain("tmux availability");
+		expect(toolNames).toContain("bun availability");
 		expect(toolNames).toContain("sd availability");
 		expect(toolNames).toContain("mulch availability");
 		expect(toolNames).toContain("bd availability");
 	});
 
-	test("sd is required when backend is auto", async () => {
+	test("bun, sd, mulch, and bd are all optional (warn if missing)", async () => {
 		const checks = await checkDependencies(mockConfig, "/tmp/.legio");
-		const sdCheck = checks.find((c) => c.name === "sd availability");
-		// sd should be required (fail if missing) when backend is "auto"
-		if (sdCheck?.status !== "pass") {
-			expect(sdCheck?.status).toBe("fail");
-		}
-	});
-
-	test("bd is optional when backend is auto", async () => {
-		const checks = await checkDependencies(mockConfig, "/tmp/.legio");
-		const bdCheck = checks.find((c) => c.name === "bd availability");
-		// bd should be optional (warn if missing) when backend is "auto"
-		if (bdCheck?.status !== "pass") {
-			expect(bdCheck?.status).toBe("warn");
-		}
-	});
-
-	test("bd is required when backend is beads", async () => {
-		const beadsConfig = {
-			...mockConfig,
-			taskTracker: { backend: "beads" as const, enabled: true },
-		};
-		const checks = await checkDependencies(beadsConfig, "/tmp/.legio");
-		const bdCheck = checks.find((c) => c.name === "bd availability");
-		// bd should be required (fail if missing) when backend is "beads"
-		if (bdCheck?.status !== "pass") {
-			expect(bdCheck?.status).toBe("fail");
+		for (const name of ["bun", "sd", "mulch", "bd"]) {
+			const check = checks.find((c) => c.name === `${name} availability`);
+			if (check?.status !== "pass") {
+				expect(check?.status).toBe("warn");
+			}
 		}
 	});
 

package/src/doctor/dependencies.ts

@@ -8,33 +8,38 @@ import type { DoctorCheck, DoctorCheckFn } from "./types.ts";
  * bd is checked as optional (legacy tracker backend).
  */
 export const checkDependencies: DoctorCheckFn = async (
-	config: LegioConfig,
+	_config: LegioConfig,
 	_legioDir,
 ): Promise<DoctorCheck[]> => {
-	const backend = config.taskTracker.backend;
-
 	const requiredTools = [
 		{ name: "git", versionFlag: "--version", required: true },
 		{ name: "node", versionFlag: "--version", required: true },
 		{ name: "tmux", versionFlag: "-V", required: true },
+		{
+			name: "bun",
+			versionFlag: "--version",
+			required: false,
+			installHint: "curl -fsSL https://bun.sh/install | bash — required runtime for sd and mulch",
+		},
 		{
 			name: "sd",
 			versionFlag: "--version",
-			required: backend === "auto" || backend === "seeds",
-			installHint: "npm install -g @os-eco/seeds-cli — https://github.com/jayminwest/seeds",
+			required: false,
+			installHint:
+				"bun install -g @os-eco/seeds-cli — issue tracker for agent task dispatch (requires Bun)",
 		},
 		{
 			name: "mulch",
 			versionFlag: "--version",
-			required: true,
-			installHint: "npm install -g @os-eco/mulch-cli — https://github.com/jayminwest/mulch",
+			required: false,
+			installHint:
+				"bun install -g @os-eco/mulch-cli — structured expertise/memory across sessions (requires Bun)",
 		},
 		{
 			name: "bd",
 			versionFlag: "--version",
-			required: backend === "beads",
-			installHint:
-				"https://github.com/steveyegge/beads (legacy — consider migrating to seeds: sd migrate-from-beads)",
+			required: false,
+			installHint: "https://github.com/steveyegge/beads — legacy issue tracker (alternative to sd)",
 		},
 	];
 

package/src/index.ts

@@ -45,7 +45,7 @@ import { worktreeCommand } from "./commands/worktree.ts";
 import { LegioError, WorktreeError } from "./errors.ts";
 import { setQuiet } from "./logging/color.ts";
 
-const VERSION = "0.2.0";
+const VERSION = "0.2.3";
 
 const HELP = `legio v${VERSION} — Multi-agent orchestration for Claude Code