@ag-eco/agentplate-cli 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ag-eco/agentplate-cli",
-	"version": "0.14.0",
+	"version": "0.15.0",
 	"description": "Multi-agent orchestration for AI coding agents — spawn workers in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution. Pluggable runtime adapters for Claude Code, Pi, and more.",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/commands/coordinator.test.ts

@@ -28,6 +28,7 @@ import {
 	coordinatorCommand,
 	createCoordinatorCommand,
 	resolveAttach,
+	resolveHeadless,
 	startCoordinatorSession,
 } from "./coordinator.ts";
 import {
@@ -710,6 +711,88 @@ describe("startCoordinator", () => {
 		).rejects.toThrow(ValidationError);
 	});
 
+	test("--headless uses the direct-spawn path instead of tmux", async () => {
+		const { deps, calls } = makeDeps();
+		const spawnCalls: string[][] = [];
+		deps._spawnHeadless = async (argv) => {
+			spawnCalls.push(argv);
+			return { pid: 4321, stdin: { write: () => 0 }, stdout: null };
+		};
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() =>
+				coordinatorCommand(["start", "--no-attach", "--json", "--headless"], deps),
+			);
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Headless path: the runtime is spawned directly; tmux is never touched.
+		expect(spawnCalls).toHaveLength(1);
+		expect(calls.createSession).toHaveLength(0);
+		// Session is recorded with an empty tmuxSession and the direct-spawn pid.
+		const sessions = loadSessionsFromDb();
+		expect(sessions[0]?.tmuxSession).toBe("");
+		expect(sessions[0]?.pid).toBe(4321);
+	});
+
+	test("--headless with a tmux-only runtime (codex) is rejected with ValidationError", async () => {
+		const { deps } = makeDeps();
+		await expect(
+			coordinatorCommand(["start", "--no-attach", "--headless", "--runtime", "codex"], deps),
+		).rejects.toThrow(ValidationError);
+	});
+
+	test("--headless --runtime pi spawns RPC mode and frames the prompt via the connection", async () => {
+		const { deps, calls } = makeDeps();
+		const stdinWrites: string[] = [];
+		const spawnArgvs: string[][] = [];
+		deps._spawnHeadless = async (argv) => {
+			spawnArgvs.push(argv);
+			return {
+				pid: 5678,
+				stdin: {
+					write: (d: string | Uint8Array) => {
+						stdinWrites.push(typeof d === "string" ? d : new TextDecoder().decode(d));
+						return 0;
+					},
+				},
+				// RPC path requires a piped stdout; an immediately-closing stream is enough
+				// for the fire-and-forget sendPrompt used at startup.
+				stdout: new ReadableStream<Uint8Array>({
+					start(c) {
+						c.close();
+					},
+				}),
+			};
+		};
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() =>
+				coordinatorCommand(
+					["start", "--no-attach", "--json", "--headless", "--runtime", "pi"],
+					deps,
+				),
+			);
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		// Headless RPC: spawned `pi --mode rpc`, never touched tmux.
+		expect(calls.createSession).toHaveLength(0);
+		expect(spawnArgvs[0]?.slice(0, 3)).toEqual(["pi", "--mode", "rpc"]);
+		// The prompt is delivered as a framed Pi command, not raw stdin text.
+		expect(stdinWrites.some((w) => w.includes('"type":"prompt"'))).toBe(true);
+		// Session recorded headless (no tmux pane) with the spawn pid.
+		const sessions = loadSessionsFromDb();
+		expect(sessions[0]?.tmuxSession).toBe("");
+		expect(sessions[0]?.pid).toBe(5678);
+	});
+
 	test("--json outputs JSON with expected fields", async () => {
 		const { deps } = makeDeps();
 		const originalSleep = Bun.sleep;
@@ -1451,6 +1534,24 @@ describe("resolveAttach", () => {
 	});
 });
 
+describe("resolveHeadless", () => {
+	test("explicit flag wins on every platform", () => {
+		expect(resolveHeadless(true, "darwin")).toBe(true);
+		expect(resolveHeadless(true, "win32")).toBe(true);
+		expect(resolveHeadless(false, "win32")).toBe(false);
+		expect(resolveHeadless(false, "linux")).toBe(false);
+	});
+
+	test("defaults to headless on native Windows when unset", () => {
+		expect(resolveHeadless(undefined, "win32")).toBe(true);
+	});
+
+	test("defaults to tmux on non-Windows platforms when unset", () => {
+		expect(resolveHeadless(undefined, "darwin")).toBe(false);
+		expect(resolveHeadless(undefined, "linux")).toBe(false);
+	});
+});
+
 describe("watchdog integration", () => {
 	describe("startCoordinator with --watchdog", () => {
 		test("calls watchdog.start() when --watchdog flag is present", async () => {

package/src/commands/coordinator.ts

@@ -24,7 +24,8 @@ import { jsonOutput } from "../json.ts";
 import { printHint, printSuccess, printWarning } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
 import { createMailStore } from "../mail/store.ts";
-import { getRuntime, getRuntimeNames } from "../runtimes/registry.ts";
+import { setConnection } from "../runtimes/connections.ts";
+import { getHeadlessRuntimeNames, getRuntime, getRuntimeNames } from "../runtimes/registry.ts";
 import { openSessionStore } from "../sessions/compat.ts";
 import { createRunStore, createSessionStore } from "../sessions/store.ts";
 import { resolveBackend, trackerCliName } from "../tracker/factory.ts";
@@ -322,6 +323,20 @@ export function resolveAttach(args: string[], isTTY: boolean): boolean {
 	return isTTY;
 }
 
+/**
+ * Resolve whether to spawn the coordinator headless (no tmux).
+ *
+ * An explicit flag wins (`--headless` → true, `--no-headless` → false). When
+ * unspecified, default to headless on native Windows — where tmux does not
+ * exist — and to the tmux path everywhere else.
+ *
+ * @param flag - Explicit flag value (true | false) or undefined when unset.
+ * @param platform - process.platform of the host running `ap`.
+ */
+export function resolveHeadless(flag: boolean | undefined, platform: NodeJS.Platform): boolean {
+	return flag ?? platform === "win32";
+}
+
 /**
  * Options for the reusable coordinator session startup core.
  * Used by startCoordinatorSession() and consumed by commands like ap discover.
@@ -420,6 +435,12 @@ export async function startCoordinatorSession(
 		);
 	}
 
+	// Resolve the effective spawn mode. An explicit --headless/--no-headless wins;
+	// otherwise default to headless on native Windows (where tmux is unavailable)
+	// and tmux everywhere else. Programmatic callers that pass an explicit boolean
+	// (e.g. the web UI's headless: true) are unaffected.
+	const useHeadless = resolveHeadless(headlessFlag, process.platform);
+
 	if (isRunningAsRoot()) {
 		throw new AgentError(
 			"Cannot spawn agents as root (UID 0). The claude CLI rejects --permission-mode bypassPermissions when run as root, causing the tmux session to die immediately. Run agentplate as a non-root user.",
@@ -528,10 +549,16 @@ export async function startCoordinatorSession(
 		// Headless start path: bypass tmux entirely and spawn the coordinator
 		// process directly via runtime.buildDirectSpawn(). Same hooks, identity,
 		// and run-tracking as the tmux path — only the spawn mechanism differs.
-		if (headlessFlag === true) {
+		if (useHeadless) {
 			if (!runtime.buildDirectSpawn) {
+				const headlessCapable = getHeadlessRuntimeNames().join(", ");
+				const winHint =
+					process.platform === "win32"
+						? ` On native Windows, tmux is unavailable, so tmux-only runtimes like "${runtime.id}" cannot run as a coordinator — use --runtime claude, or run agentplate under WSL2.`
+						: "";
 				throw new ValidationError(
-					`Headless coordinator start requires a runtime with buildDirectSpawn (got: ${runtime.id})`,
+					`Runtime "${runtime.id}" cannot run a headless coordinator (no direct-spawn support). ` +
+						`Headless-capable runtimes: ${headlessCapable}.${winHint}`,
 					{ field: "runtime", value: runtime.id },
 				);
 			}
@@ -555,16 +582,8 @@ export async function startCoordinatorSession(
 			const headlessLogDir = join(agentplateDir, "logs", "coordinator", logTimestamp);
 			await mkdir(headlessLogDir, { recursive: true });
 
-			const headlessProc = await spawnHeadless(argv, {
-				cwd: projectRoot,
-				env: { ...(process.env as Record<string, string>), ...directEnv },
-				stdoutFile: join(headlessLogDir, "stdout.log"),
-				stderrFile: join(headlessLogDir, "stderr.log"),
-				agentName: coordinatorName,
-			});
-
-			// Build the initial stdin prompt from agent definition + pending dispatch
-			// mail + activation beacon. Replaces SessionStart hooks (no-op headless).
+			// Build the initial prompt from agent definition + pending dispatch mail +
+			// activation beacon. Replaces SessionStart hooks (no-op headless).
 			const agentDefPath = join(projectRoot, ".agentplate", "agent-defs", agentDefFile);
 			const agentDefHandle = Bun.file(agentDefPath);
 			const primeContext = (await agentDefHandle.exists()) ? await agentDefHandle.text() : "";
@@ -588,7 +607,46 @@ export async function startCoordinatorSession(
 				mailSection || undefined,
 				beacon,
 			);
-			await headlessProc.stdin.write(initialPrompt);
+
+			const spawnEnv = { ...(process.env as Record<string, string>), ...directEnv };
+			let headlessProc: Awaited<ReturnType<typeof spawnHeadless>>;
+			if (runtime.connect) {
+				// EXPERIMENTAL RPC runtime (e.g. Pi --mode rpc): stdout must be a pipe so
+				// the connection's reader can route get_state responses, and the prompt +
+				// mail are delivered as framed RPC commands rather than raw stdin text.
+				// We register the runtime's own connection instead of the generic
+				// stdin-writer (no agentName → spawnHeadless skips that registration).
+				// Trade-off: Pi event lines are not file-logged in this path yet.
+				headlessProc = await spawnHeadless(argv, {
+					cwd: projectRoot,
+					env: spawnEnv,
+					stderrFile: join(headlessLogDir, "stderr.log"),
+				});
+				if (!headlessProc.stdout) {
+					throw new AgentError(
+						`Runtime "${runtime.id}" needs a piped stdout for RPC mode but none was provided`,
+						{ agentName: coordinatorName },
+					);
+				}
+				const connection = runtime.connect({
+					stdin: headlessProc.stdin,
+					stdout: headlessProc.stdout,
+				});
+				setConnection(coordinatorName, connection);
+				await connection.sendPrompt(initialPrompt);
+			} else {
+				// Stream-json runtimes (Claude): the generic HeadlessClaudeConnection
+				// (registered by agentName) writes the prompt + mail as raw stdin text,
+				// and stdout is captured to a log file for `ap logs`.
+				headlessProc = await spawnHeadless(argv, {
+					cwd: projectRoot,
+					env: spawnEnv,
+					stdoutFile: join(headlessLogDir, "stdout.log"),
+					stderrFile: join(headlessLogDir, "stderr.log"),
+					agentName: coordinatorName,
+				});
+				await headlessProc.stdin.write(initialPrompt);
+			}
 
 			// Create run record + current-run.txt + session row.
 			const sessionId = `session-${Date.now()}-${coordinatorName}`;
@@ -894,6 +952,7 @@ async function startPersistentAgent(
 		monitor: boolean;
 		profile?: string;
 		runtime?: string;
+		headless?: boolean;
 		acceptExistingWatchdog?: boolean;
 	},
 	deps: CoordinatorDeps = {},
@@ -1678,6 +1737,11 @@ export function createPersistentAgentCommand(
 			"--runtime <name>",
 			"Runtime adapter: claude | codex | pi | opencode | gemini (default: config or claude)",
 		)
+		.option(
+			"--headless",
+			"Spawn without tmux (direct subprocess). Required on native Windows; runtime must be headless-capable (claude, or pi via experimental --mode rpc)",
+		)
+		.option("--no-headless", "Force the tmux spawn path (overrides the Windows headless default)")
 		.option("--json", "Output as JSON")
 		.action(
 			async (opts: {
@@ -1688,6 +1752,7 @@ export function createPersistentAgentCommand(
 				json?: boolean;
 				profile?: string;
 				runtime?: string;
+				headless?: boolean;
 			}) => {
 				// opts.attach = true if --attach, false if --no-attach, undefined if neither
 				const shouldAttach = opts.attach !== undefined ? opts.attach : !!process.stdout.isTTY;
@@ -1701,6 +1766,8 @@ export function createPersistentAgentCommand(
 						monitor: opts.monitor ?? false,
 						profile: opts.profile,
 						runtime: opts.runtime,
+						// true (--headless) | false (--no-headless) | undefined (platform default)
+						headless: opts.headless,
 					},
 					deps,
 				);

package/src/runtimes/pi.test.ts

@@ -787,3 +787,84 @@ describe("PiRuntime integration: registry resolves 'pi'", () => {
 		expect(() => getRuntime("does-not-exist")).toThrow('Unknown runtime: "does-not-exist"');
 	});
 });
+
+describe("PiRuntime headless RPC: buildDirectSpawn", () => {
+	const runtime = new PiRuntime();
+
+	test("returns `pi --mode rpc` with no --model when model omitted", () => {
+		expect(runtime.buildDirectSpawn({ cwd: "/x", env: {}, instructionPath: "AGENTS.md" })).toEqual([
+			"pi",
+			"--mode",
+			"rpc",
+		]);
+	});
+
+	test("appends the expanded --model when provided", () => {
+		expect(
+			runtime.buildDirectSpawn({
+				cwd: "/x",
+				env: {},
+				model: "opus",
+				instructionPath: "AGENTS.md",
+			}),
+		).toEqual(["pi", "--mode", "rpc", "--model", "anthropic/claude-opus-4-6"]);
+	});
+});
+
+describe("PiRuntime headless RPC: connect() command framing", () => {
+	const runtime = new PiRuntime();
+
+	function fakeProc(emit?: string): {
+		proc: { stdin: { write(d: string | Uint8Array): number }; stdout: ReadableStream<Uint8Array> };
+		writes: string[];
+	} {
+		const writes: string[] = [];
+		const stdout = new ReadableStream<Uint8Array>({
+			start(c) {
+				if (emit) c.enqueue(new TextEncoder().encode(emit));
+				c.close();
+			},
+		});
+		const stdin = {
+			write: (d: string | Uint8Array): number => {
+				writes.push(typeof d === "string" ? d : new TextDecoder().decode(d));
+				return 0;
+			},
+		};
+		return { proc: { stdin, stdout }, writes };
+	}
+
+	test("sendPrompt frames a `prompt` command", async () => {
+		const { proc, writes } = fakeProc();
+		const conn = runtime.connect(proc);
+		await conn.sendPrompt("hello");
+		conn.close();
+		expect(writes).toContain('{"type":"prompt","message":"hello"}\n');
+	});
+
+	test("followUp frames a `follow_up` command", async () => {
+		const { proc, writes } = fakeProc();
+		const conn = runtime.connect(proc);
+		await conn.followUp("more work");
+		conn.close();
+		expect(writes).toContain('{"type":"follow_up","message":"more work"}\n');
+	});
+
+	test("abort frames an `abort` command", async () => {
+		const { proc, writes } = fakeProc();
+		const conn = runtime.connect(proc);
+		await conn.abort();
+		conn.close();
+		expect(writes).toContain('{"type":"abort"}\n');
+	});
+
+	test("getState maps an isStreaming response to working", async () => {
+		const { proc } = fakeProc(
+			'{"type":"response","id":0,"command":"get_state","data":{"isStreaming":true}}\n',
+		);
+		const conn = runtime.connect(proc);
+		const state = await conn.getState();
+		expect(state.status).toBe("working");
+		conn.close();
+	});
+});

package/src/runtimes/pi.ts

@@ -7,9 +7,13 @@ import type { PiRuntimeConfig, ResolvedModel } from "../types.ts";
 import { generatePiGuardExtension } from "./pi-guards.ts";
 import type {
 	AgentRuntime,
+	ConnectionState,
+	DirectSpawnOpts,
 	HooksDef,
 	OverlayContent,
 	ReadyState,
+	RpcProcessHandle,
+	RuntimeConnection,
 	SpawnOpts,
 	TranscriptSummary,
 } from "./types.ts";
@@ -24,12 +28,174 @@ const DEFAULT_PI_CONFIG: PiRuntimeConfig = {
 	},
 };
 
+/** Pending get_state request awaiting its NDJSON response. */
+interface PiPendingRequest {
+	resolve: (state: ConnectionState) => void;
+	reject: (err: Error) => void;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * RPC connection to a running `pi --mode rpc` process.
+ *
+ * Pi's RPC mode is a long-lived loop that reads newline-delimited JSON commands
+ * on stdin and emits NDJSON events + responses on stdout (see Pi's
+ * `src/modes/rpc/rpc-mode.ts`). This maps the agentplate RuntimeConnection
+ * contract onto Pi's command vocabulary:
+ *
+ * - sendPrompt → `{ type: "prompt", message }`
+ * - followUp   → `{ type: "follow_up", message }`
+ * - abort      → `{ type: "abort" }`
+ * - getState   → `{ type: "get_state", id }` → `{ type: "response", id, data }`
+ *
+ * A background reader drains stdout, routing `type: "response"` lines with a
+ * matching numeric `id` to pending getState() waiters and discarding the
+ * agent event stream (observability for Pi events is a follow-up).
+ *
+ * EXPERIMENTAL: validated against Pi's documented RPC protocol but not yet
+ * exercised end-to-end. Not exported — constructed only by PiRuntime.connect().
+ */
+class PiConnection implements RuntimeConnection {
+	private nextId = 0;
+	private readonly pending = new Map<number, PiPendingRequest>();
+	private closed = false;
+	private readonly proc: RpcProcessHandle;
+	private readonly timeoutMs: number;
+
+	constructor(proc: RpcProcessHandle, timeoutMs = 5000) {
+		this.proc = proc;
+		this.timeoutMs = timeoutMs;
+		this.drainStdout();
+	}
+
+	/** Background reader: route `type:"response"` lines to pending getState waiters. */
+	private drainStdout(): void {
+		const reader = this.proc.stdout.getReader();
+		const decoder = new TextDecoder();
+		let buffer = "";
+
+		const processLine = (line: string): void => {
+			const trimmed = line.trim();
+			if (!trimmed) return;
+			let parsed: Record<string, unknown>;
+			try {
+				parsed = JSON.parse(trimmed) as Record<string, unknown>;
+			} catch {
+				return; // partial write or non-JSON debug line
+			}
+			// Pi responses: { type: "response", id, command, success, data }
+			if (parsed.type === "response" && typeof parsed.id === "number") {
+				const waiter = this.pending.get(parsed.id);
+				if (waiter) {
+					clearTimeout(waiter.timer);
+					this.pending.delete(parsed.id);
+					waiter.resolve(mapPiState(parsed.data));
+				}
+			}
+			// Agent event lines are discarded here (Pi event observability is TODO).
+		};
+
+		const read = async (): Promise<void> => {
+			try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					buffer += decoder.decode(value, { stream: true });
+					const lines = buffer.split("\n");
+					buffer = lines.pop() ?? "";
+					for (const line of lines) processLine(line);
+				}
+				if (buffer.trim()) processLine(buffer);
+			} catch {
+				// stream error — reject all pending below
+			} finally {
+				reader.releaseLock();
+				for (const [, waiter] of this.pending) {
+					clearTimeout(waiter.timer);
+					waiter.reject(new Error("connection closed"));
+				}
+				this.pending.clear();
+			}
+		};
+
+		read().catch(() => {
+			// handled in finally
+		});
+	}
+
+	/** Write one NDJSON command line to stdin (fire-and-forget). */
+	private writeMsg(msg: Record<string, unknown>): void {
+		const result = this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
+		if (result instanceof Promise) {
+			result.catch(() => {
+				// non-fatal for fire-and-forget control messages
+			});
+		}
+	}
+
+	async sendPrompt(text: string): Promise<void> {
+		this.writeMsg({ type: "prompt", message: text });
+	}
+
+	async followUp(text: string): Promise<void> {
+		this.writeMsg({ type: "follow_up", message: text });
+	}
+
+	async abort(): Promise<void> {
+		this.writeMsg({ type: "abort" });
+	}
+
+	getState(): Promise<ConnectionState> {
+		if (this.closed) return Promise.reject(new Error("connection closed"));
+		const id = this.nextId++;
+		return new Promise<ConnectionState>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error("getState timed out"));
+			}, this.timeoutMs);
+			this.pending.set(id, { resolve, reject, timer });
+			const result = this.proc.stdin.write(`${JSON.stringify({ type: "get_state", id })}\n`);
+			if (result instanceof Promise) {
+				result.catch(() => {
+					clearTimeout(timer);
+					this.pending.delete(id);
+					reject(new Error("write failed"));
+				});
+			}
+		});
+	}
+
+	close(): void {
+		this.closed = true;
+		for (const [, waiter] of this.pending) {
+			clearTimeout(waiter.timer);
+			waiter.reject(new Error("connection closed"));
+		}
+		this.pending.clear();
+	}
+}
+
+/**
+ * Map a Pi get_state response payload to the agentplate ConnectionState.
+ * Pi reports `isStreaming` (a turn is in flight); everything else is idle.
+ */
+function mapPiState(data: unknown): ConnectionState {
+	const streaming =
+		typeof data === "object" && data !== null && (data as { isStreaming?: unknown }).isStreaming;
+	return { status: streaming ? "working" : "idle" };
+}
+
 /**
  * Pi runtime adapter.
  *
  * Implements AgentRuntime for the `pi` CLI (Mario Zechner's Pi coding agent).
  * Security is enforced via Pi guard extensions rather than permission-mode flags —
  * Pi has no --permission-mode equivalent.
+ *
+ * Pi runs in two modes here: an interactive TUI in a tmux pane
+ * (buildSpawnCommand) and a headless `--mode rpc` subprocess (buildDirectSpawn +
+ * connect) for tmux-less hosts such as native Windows. The RPC path is
+ * experimental.
  */
 export class PiRuntime implements AgentRuntime {
 	/** Unique identifier for this runtime. */
@@ -111,6 +277,42 @@ export class PiRuntime implements AgentRuntime {
 		return cmd;
 	}
 
+	/**
+	 * Build the argv for a long-lived headless Pi process in RPC mode.
+	 *
+	 * `pi --mode rpc` reads newline-delimited JSON commands on stdin and emits
+	 * NDJSON events/responses on stdout, staying alive across turns — the shape a
+	 * tmux-less coordinator needs (e.g. native Windows). Pi reads its task from
+	 * AGENTS.md (instructionPath) in the cwd; prompts/mail are delivered as RPC
+	 * commands via connect(), not argv.
+	 *
+	 * EXPERIMENTAL: the RPC headless path is not yet validated end-to-end.
+	 *
+	 * @param opts - Direct spawn options (cwd, env, model handled by the caller)
+	 * @returns Argv array for Bun.spawn — do not shell-interpolate
+	 */
+	buildDirectSpawn(opts: DirectSpawnOpts): string[] {
+		const argv = ["pi", "--mode", "rpc"];
+		if (opts.model !== undefined) {
+			argv.push("--model", this.expandModel(opts.model));
+		}
+		return argv;
+	}
+
+	/**
+	 * Establish a JSON-command RPC connection to a running `pi --mode rpc` process.
+	 *
+	 * Returns a PiConnection that frames sendPrompt/followUp/abort as NDJSON
+	 * commands on stdin and routes get_state responses from stdout. Used by the
+	 * headless coordinator path in place of tmux send-keys.
+	 *
+	 * @param process - Stdin/stdout handles from the spawned Pi subprocess
+	 * @returns RuntimeConnection for framed control + health checks
+	 */
+	connect(process: RpcProcessHandle): RuntimeConnection {
+		return new PiConnection(process);
+	}
+
 	/**
 	 * Deploy per-agent instructions and guards to a worktree.
 	 *

package/src/runtimes/registry.test.ts

@@ -7,7 +7,7 @@ import { CursorRuntime } from "./cursor.ts";
 import { GeminiRuntime } from "./gemini.ts";
 import { OpenCodeRuntime } from "./opencode.ts";
 import { PiRuntime } from "./pi.ts";
-import { getRuntime, getRuntimeNames } from "./registry.ts";
+import { getHeadlessRuntimeNames, getRuntime, getRuntimeNames } from "./registry.ts";
 
 describe("getRuntime", () => {
 	it("returns a ClaudeRuntime by default (no args)", () => {
@@ -209,3 +209,24 @@ describe("getRuntimeNames", () => {
 		}
 	});
 });
+
+describe("getHeadlessRuntimeNames", () => {
+	it("includes claude (buildDirectSpawn), sapling (static headless), and pi (rpc)", () => {
+		const names = getHeadlessRuntimeNames();
+		expect(names).toContain("claude");
+		expect(names).toContain("sapling");
+		// Pi gained a headless RPC path (buildDirectSpawn + connect via `pi --mode rpc`).
+		expect(names).toContain("pi");
+	});
+
+	it("excludes tmux-only runtimes like codex", () => {
+		expect(getHeadlessRuntimeNames()).not.toContain("codex");
+	});
+
+	it("every headless name actually resolves to a headless-capable runtime", () => {
+		for (const name of getHeadlessRuntimeNames()) {
+			const rt = getRuntime(name);
+			expect(typeof rt.buildDirectSpawn === "function" || rt.headless === true).toBe(true);
+		}
+	});
+});

package/src/runtimes/registry.ts

@@ -67,6 +67,21 @@ export function getRuntimeNames(): string[] {
 	return [...runtimes.keys()];
 }
 
+/**
+ * Names of runtimes that can spawn an agent without tmux — i.e. those that
+ * implement `buildDirectSpawn()` or statically declare `headless = true`.
+ *
+ * These are the only runtimes usable for a headless coordinator (the no-tmux
+ * path), which matters on native Windows where tmux is unavailable.
+ *
+ * @returns Array of headless-capable runtime names (e.g. "claude", "sapling").
+ */
+export function getHeadlessRuntimeNames(): string[] {
+	return getAllRuntimes()
+		.filter((r) => typeof r.buildDirectSpawn === "function" || r.headless === true)
+		.map((r) => r.id);
+}
+
 /**
  * Resolve a runtime adapter by name.
  *

package/src/version.ts

@@ -2,4 +2,4 @@
  * Single source of truth for the package version, shared by every bundled bin
  * (ap/agentplate, lm/loam, sr, tl). Updated by scripts/version-bump.ts.
  */
-export const VERSION = "0.14.0";
+export const VERSION = "0.15.0";

package/src/worktree/tmux.ts

@@ -598,10 +598,24 @@ export async function waitForTuiReady(
  * Throws AgentError with a clear message if tmux is not available.
  */
 export async function ensureTmuxAvailable(): Promise<void> {
-	const { exitCode } = await runCommand(["tmux", "-V"]);
-	if (exitCode !== 0) {
+	// Bun.spawn throws (rather than returning a non-zero exit) when the tmux
+	// binary isn't on PATH — e.g. native Windows, where tmux does not exist. Catch
+	// that so the operator gets actionable guidance instead of a raw
+	// "Executable not found in $PATH" stack.
+	let available = false;
+	try {
+		const { exitCode } = await runCommand(["tmux", "-V"]);
+		available = exitCode === 0;
+	} catch {
+		available = false;
+	}
+	if (!available) {
+		const winHint =
+			process.platform === "win32"
+				? " On native Windows, tmux is unavailable — start the coordinator with --headless (claude runtime), or run agentplate under WSL2."
+				: "";
 		throw new AgentError(
-			"tmux is not installed or not on PATH. Install tmux to use agentplate agent orchestration.",
+			`tmux is not installed or not on PATH. Install tmux to use agentplate agent orchestration.${winHint}`,
 		);
 	}
 }