@ag-eco/agentplate-cli 0.13.4 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ag-eco/agentplate-cli",
-	"version": "0.13.4",
+	"version": "0.14.1",
 	"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 {
@@ -682,6 +683,68 @@ describe("startCoordinator", () => {
 		expect(cmd).not.toContain("--model opus");
 	});
 
+	test("--runtime overrides the spawned runtime adapter (pi)", async () => {
+		const { deps, calls } = makeDeps();
+		const originalSleep = Bun.sleep;
+		Bun.sleep = (() => Promise.resolve()) as typeof Bun.sleep;
+
+		try {
+			await captureStdout(() =>
+				coordinatorCommand(["start", "--no-attach", "--json", "--runtime", "pi"], deps),
+			);
+		} finally {
+			Bun.sleep = originalSleep;
+		}
+
+		expect(calls.createSession).toHaveLength(1);
+		const cmd = calls.createSession[0]?.command ?? "";
+		// Pi's buildSpawnCommand emits `pi --model <provider/model>`; the default
+		// claude runtime would not. Proves --runtime took precedence over config.
+		expect(cmd).toContain("pi --model");
+		expect(cmd).toContain("opus");
+	});
+
+	test("--runtime rejects an unknown adapter with ValidationError", async () => {
+		const { deps } = makeDeps();
+		await expect(
+			coordinatorCommand(["start", "--no-attach", "--runtime", "bogus"], deps),
+		).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 (pi) is rejected with ValidationError", async () => {
+		const { deps } = makeDeps();
+		await expect(
+			coordinatorCommand(["start", "--no-attach", "--headless", "--runtime", "pi"], deps),
+		).rejects.toThrow(ValidationError);
+	});
+
 	test("--json outputs JSON with expected fields", async () => {
 		const { deps } = makeDeps();
 		const originalSleep = Bun.sleep;
@@ -1423,6 +1486,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,7 @@ 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 } from "../runtimes/registry.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 +322,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.
@@ -332,6 +346,13 @@ export interface CoordinatorSessionOptions {
 	watchdog: boolean;
 	monitor: boolean;
 	profile?: string;
+	/**
+	 * Runtime adapter override (e.g. "claude", "codex", "pi", "opencode",
+	 * "gemini"). Takes precedence over config's per-capability and default
+	 * runtime. When omitted, resolution falls back to
+	 * runtime.capabilities[capability] → runtime.default → "claude".
+	 */
+	runtime?: string;
 	/** Override coordinator name (default: "coordinator"). */
 	coordinatorName?: string;
 	/** Generic persistent agent name override. Preferred over coordinatorName for new callers. */
@@ -386,6 +407,7 @@ export async function startCoordinatorSession(
 		watchdog: watchdogFlag,
 		monitor: monitorFlag,
 		profile: profileFlag,
+		runtime: runtimeOverride,
 		coordinatorName: coordinatorNameOpt,
 		agentName: agentNameOpt,
 		capability: capabilityOpt,
@@ -402,6 +424,22 @@ export async function startCoordinatorSession(
 	const displayName = displayNameOpt ?? COORDINATOR_SPEC.displayName;
 	const beaconBuilder = beaconBuilderOpt ?? buildCoordinatorBeacon;
 
+	// Fail fast on an unknown --runtime before doing any setup work, listing the
+	// valid adapters. getRuntime() would also reject it, but later and with a
+	// plain Error; this gives an immediate, typed, actionable message.
+	if (runtimeOverride && !getRuntimeNames().includes(runtimeOverride)) {
+		throw new ValidationError(
+			`Unknown runtime "${runtimeOverride}". Available: ${getRuntimeNames().join(", ")}`,
+			{ field: "runtime", value: runtimeOverride },
+		);
+	}
+
+	// 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.",
@@ -478,7 +516,7 @@ export async function startCoordinatorSession(
 		);
 		const manifest = await manifestLoader.load();
 		const resolvedModel = resolveModel(config, manifest, capability, "opus");
-		const runtime = getRuntime(undefined, config, capability);
+		const runtime = getRuntime(runtimeOverride, config, capability);
 
 		// Deploy hooks to the project root so the coordinator gets event logging,
 		// mail check --inject, and activity tracking via the standard hook pipeline.
@@ -510,10 +548,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 },
 				);
 			}
@@ -875,6 +919,8 @@ async function startPersistentAgent(
 		watchdog: boolean;
 		monitor: boolean;
 		profile?: string;
+		runtime?: string;
+		headless?: boolean;
 		acceptExistingWatchdog?: boolean;
 	},
 	deps: CoordinatorDeps = {},
@@ -1645,7 +1691,7 @@ export function createPersistentAgentCommand(
 
 	cmd
 		.command("start")
-		.description(`Start the ${spec.commandName} (spawns Claude Code at project root)`)
+		.description(`Start the ${spec.commandName} (spawns the configured runtime at project root)`)
 		.option("--attach", "Always attach to tmux session after start")
 		.option("--no-attach", "Never attach to tmux session after start")
 		.option("--watchdog", `Auto-start watchdog daemon with ${spec.commandName}`)
@@ -1655,6 +1701,15 @@ export function createPersistentAgentCommand(
 		)
 		.option("--monitor", `Auto-start Tier 2 monitor agent with ${spec.commandName}`)
 		.option("--profile <name>", "Trellis profile to apply to spawned agents")
+		.option(
+			"--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)",
+		)
+		.option("--no-headless", "Force the tmux spawn path (overrides the Windows headless default)")
 		.option("--json", "Output as JSON")
 		.action(
 			async (opts: {
@@ -1664,6 +1719,8 @@ export function createPersistentAgentCommand(
 				monitor?: boolean;
 				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;
@@ -1676,6 +1733,9 @@ export function createPersistentAgentCommand(
 						acceptExistingWatchdog: opts.acceptExistingWatchdog ?? false,
 						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/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 } from "./registry.ts";
+import { getHeadlessRuntimeNames, getRuntime, getRuntimeNames } from "./registry.ts";
 
 describe("getRuntime", () => {
 	it("returns a ClaudeRuntime by default (no args)", () => {
@@ -194,3 +194,37 @@ describe("getRuntime", () => {
 		});
 	});
 });
+
+describe("getRuntimeNames", () => {
+	it("lists every registered adapter, including the coordinator-supported set", () => {
+		const names = getRuntimeNames();
+		for (const expected of ["claude", "codex", "pi", "opencode", "gemini"]) {
+			expect(names).toContain(expected);
+		}
+	});
+
+	it("returns names that all resolve via getRuntime", () => {
+		for (const name of getRuntimeNames()) {
+			expect(getRuntime(name).id).toBe(name);
+		}
+	});
+});
+
+describe("getHeadlessRuntimeNames", () => {
+	it("includes claude (buildDirectSpawn) and sapling (static headless)", () => {
+		const names = getHeadlessRuntimeNames();
+		expect(names).toContain("claude");
+		expect(names).toContain("sapling");
+	});
+
+	it("excludes tmux-only runtimes like pi", () => {
+		expect(getHeadlessRuntimeNames()).not.toContain("pi");
+	});
+
+	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

@@ -55,6 +55,33 @@ export function getAllRuntimes(): AgentRuntime[] {
 	];
 }
 
+/**
+ * Names of all registered runtime adapters, in registration order.
+ *
+ * Used to validate a user-supplied `--runtime <name>` before resolution so the
+ * error can list the valid choices (see `ap coordinator start --runtime`).
+ *
+ * @returns Array of runtime names (e.g. "claude", "codex", "pi").
+ */
+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.13.4";
+export const VERSION = "0.14.1";

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}`,
 		);
 	}
 }