@ag-eco/agentplate-cli 0.14.0 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ag-eco/agentplate-cli",
-	"version": "0.14.0",
+	"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 {
@@ -710,6 +711,40 @@ 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 (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;
@@ -1451,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, getRuntimeNames } 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.
@@ -420,6 +434,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 +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 },
 				);
 			}
@@ -894,6 +920,7 @@ async function startPersistentAgent(
 		monitor: boolean;
 		profile?: string;
 		runtime?: string;
+		headless?: boolean;
 		acceptExistingWatchdog?: boolean;
 	},
 	deps: CoordinatorDeps = {},
@@ -1678,6 +1705,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)",
+		)
+		.option("--no-headless", "Force the tmux spawn path (overrides the Windows headless default)")
 		.option("--json", "Output as JSON")
 		.action(
 			async (opts: {
@@ -1688,6 +1720,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 +1734,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/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,22 @@ describe("getRuntimeNames", () => {
 		}
 	});
 });
+
+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

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