@katyella/legio 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +201,9 @@ 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.2...HEAD
+[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.2",
 	"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

@@ -713,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 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");
@@ -238,6 +239,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,
 		});
 

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.2";
 
 const HELP = `legio v${VERSION} — Multi-agent orchestration for Claude Code