@ag-eco/agentplate-cli 0.13.0

package/src/worktree/manager.ts

@@ -0,0 +1,405 @@
+import { unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { WorktreeError } from "../errors.ts";
+
+/**
+ * Run a git command and return stdout. Throws WorktreeError on non-zero exit.
+ */
+async function runGit(
+	repoRoot: string,
+	args: string[],
+	context?: { worktreePath?: string; branchName?: string },
+): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	if (exitCode !== 0) {
+		throw new WorktreeError(
+			`git ${args.join(" ")} failed (exit ${exitCode}): ${stderr.trim() || stdout.trim()}`,
+			{
+				worktreePath: context?.worktreePath,
+				branchName: context?.branchName,
+			},
+		);
+	}
+
+	return stdout;
+}
+
+/**
+ * Create a new git worktree for an agent.
+ *
+ * Creates a worktree at `{baseDir}/{agentName}` with a new branch
+ * named `agentplate/{agentName}/{taskId}` based on `baseBranch`.
+ *
+ * Before running `git worktree add`, rejects when the target branch is
+ * already checked out in another worktree — this avoids the silent-overwrite
+ * class of failure entirely. After `git worktree add` returns, validates
+ * that the worktree is actually registered with git AND contains tracked
+ * files; if either check fails, rolls back and throws. sling has previously
+ * hit edge cases where the dir exists but git did not populate it
+ * (agentplate-6878), trapping the agent in a non-worktree directory.
+ *
+ * @returns The absolute worktree path and branch name.
+ */
+export async function createWorktree(options: {
+	repoRoot: string;
+	baseDir: string;
+	agentName: string;
+	baseBranch: string;
+	taskId: string;
+}): Promise<{ path: string; branch: string }> {
+	const { repoRoot, baseDir, agentName, baseBranch, taskId } = options;
+
+	const worktreePath = join(baseDir, agentName);
+	const branchName = `agentplate/${agentName}/${taskId}`;
+
+	const existing = await listWorktrees(repoRoot);
+	const occupied = existing.find((entry) => entry.branch === branchName);
+	if (occupied !== undefined) {
+		throw new WorktreeError(`branch ${branchName} is already checked out at ${occupied.path}`, {
+			worktreePath,
+			branchName,
+		});
+	}
+
+	await runGit(repoRoot, ["worktree", "add", "-b", branchName, worktreePath, baseBranch], {
+		worktreePath,
+		branchName,
+	});
+
+	await validateWorktreeCreation({ repoRoot, worktreePath, branchName });
+
+	return { path: worktreePath, branch: branchName };
+}
+
+/**
+ * Verify that a freshly created worktree is registered with git and contains
+ * tracked files. Throws WorktreeError with a precise diagnostic on failure
+ * and rolls back the worktree + branch so callers don't leak state.
+ *
+ * Exported for direct testing of edge cases (empty base branches, racy
+ * cleanup) that are awkward to provoke through createWorktree end-to-end.
+ */
+export async function validateWorktreeCreation(opts: {
+	repoRoot: string;
+	worktreePath: string;
+	branchName: string;
+}): Promise<void> {
+	const { repoRoot, worktreePath, branchName } = opts;
+
+	const entries = await listWorktrees(repoRoot);
+	const registered = entries.some((entry) => entry.path === worktreePath);
+	if (!registered) {
+		await rollbackWorktree(repoRoot, worktreePath, branchName);
+		throw new WorktreeError(
+			`Worktree creation reported success but path is not registered with git: ${worktreePath}. Possible causes: pre-existing directory, branch already checked out elsewhere, or git worktree add failed silently.`,
+			{ worktreePath, branchName },
+		);
+	}
+
+	const lsFiles = await runGit(worktreePath, ["ls-files"], { worktreePath, branchName });
+	const fileCount = lsFiles.split("\n").filter((line) => line.length > 0).length;
+	if (fileCount === 0) {
+		await rollbackWorktree(repoRoot, worktreePath, branchName);
+		throw new WorktreeError(
+			`Worktree was registered but contains zero tracked files: ${worktreePath}. The base branch may be empty or the working tree was not populated.`,
+			{ worktreePath, branchName },
+		);
+	}
+}
+
+/**
+ * Roll back a worktree and its associated branch after a failed spawn.
+ *
+ * Best-effort cleanup: errors are swallowed because the caller's original
+ * error is more important. Always call this inside a catch block.
+ */
+export async function rollbackWorktree(
+	repoRoot: string,
+	worktreePath: string,
+	branchName: string,
+): Promise<void> {
+	try {
+		const removeProc = Bun.spawn(["git", "worktree", "remove", "--force", worktreePath], {
+			cwd: repoRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		await removeProc.exited;
+	} catch {
+		// Best-effort
+	}
+
+	if (branchName.length > 0) {
+		try {
+			const branchProc = Bun.spawn(["git", "branch", "-D", branchName], {
+				cwd: repoRoot,
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			await branchProc.exited;
+		} catch {
+			// Best-effort
+		}
+	}
+}
+
+/**
+ * Parsed representation of a single worktree entry from `git worktree list --porcelain`.
+ */
+interface WorktreeEntry {
+	path: string;
+	branch: string;
+	head: string;
+}
+
+/**
+ * Parse the output of `git worktree list --porcelain` into structured entries.
+ *
+ * Porcelain format example:
+ * ```
+ * worktree /path/to/main
+ * HEAD abc123
+ * branch refs/heads/main
+ *
+ * worktree /path/to/wt
+ * HEAD def456
+ * branch refs/heads/agentplate/agent/bead
+ * ```
+ */
+function parseWorktreeOutput(output: string): WorktreeEntry[] {
+	const entries: WorktreeEntry[] = [];
+	const blocks = output.trim().split("\n\n");
+
+	for (const block of blocks) {
+		if (block.trim() === "") continue;
+
+		let path = "";
+		let head = "";
+		let branch = "";
+
+		const lines = block.trim().split("\n");
+		for (const line of lines) {
+			if (line.startsWith("worktree ")) {
+				path = line.slice("worktree ".length);
+			} else if (line.startsWith("HEAD ")) {
+				head = line.slice("HEAD ".length);
+			} else if (line.startsWith("branch ")) {
+				// Strip refs/heads/ prefix to get the short branch name
+				const ref = line.slice("branch ".length);
+				branch = ref.replace(/^refs\/heads\//, "");
+			}
+		}
+
+		if (path.length > 0) {
+			entries.push({ path, head, branch });
+		}
+	}
+
+	return entries;
+}
+
+/**
+ * List all git worktrees in the repository.
+ *
+ * @returns Array of worktree entries with path, branch name, and HEAD commit.
+ */
+export async function listWorktrees(
+	repoRoot: string,
+): Promise<Array<{ path: string; branch: string; head: string }>> {
+	const stdout = await runGit(repoRoot, ["worktree", "list", "--porcelain"]);
+	return parseWorktreeOutput(stdout);
+}
+
+/**
+ * Check if a branch has been merged into a target branch.
+ * Uses `git merge-base --is-ancestor` which returns exit 0 if merged, 1 if not.
+ */
+export async function isBranchMerged(
+	repoRoot: string,
+	branch: string,
+	targetBranch: string,
+): Promise<boolean> {
+	const proc = Bun.spawn(["git", "merge-base", "--is-ancestor", branch, targetBranch], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const [stderr, exitCode] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+
+	if (exitCode === 0) return true;
+	if (exitCode === 1) return false;
+
+	throw new WorktreeError(
+		`git merge-base --is-ancestor failed (exit ${exitCode}): ${stderr.trim()}`,
+		{ branchName: branch },
+	);
+}
+
+/**
+ * Remove a git worktree and delete its associated branch.
+ *
+ * Runs `git worktree remove {path}` to remove the worktree, then
+ * deletes the branch. With `forceBranch: true`, uses `git branch -D`
+ * to force-delete even unmerged branches. Otherwise uses `git branch -d`
+ * which only deletes merged branches.
+ */
+export async function removeWorktree(
+	repoRoot: string,
+	path: string,
+	options?: { force?: boolean; forceBranch?: boolean },
+): Promise<void> {
+	// First, figure out which branch this worktree is on so we can clean it up
+	const worktrees = await listWorktrees(repoRoot);
+	const entry = worktrees.find((wt) => wt.path === path);
+	const branchName = entry?.branch ?? "";
+
+	// Remove the worktree (--force handles untracked files and uncommitted changes)
+	const removeArgs = ["worktree", "remove", path];
+	if (options?.force) {
+		removeArgs.push("--force");
+	}
+	await runGit(repoRoot, removeArgs, {
+		worktreePath: path,
+		branchName,
+	});
+
+	// Delete the associated branch after worktree removal.
+	// Use -D (force) when forceBranch is set, since the branch may not have
+	// been merged yet. Use -d (safe) otherwise, which only deletes merged branches.
+	if (branchName.length > 0) {
+		const deleteFlag = options?.forceBranch ? "-D" : "-d";
+		try {
+			await runGit(repoRoot, ["branch", deleteFlag, branchName], { branchName });
+		} catch {
+			// Branch deletion failed — may be unmerged (with -d) or checked out elsewhere.
+			// This is best-effort; the worktree itself is already removed.
+		}
+	}
+}
+
+/**
+ * Preserve .sprout/ changes from a branch into the canonical branch.
+ *
+ * Lead agent branches are never merged via the normal merge pipeline, so
+ * any .sprout/ issue files they create would be lost when the worktree is
+ * cleaned. This function extracts only the .sprout/ diff from the branch
+ * and applies it to the canonical branch via a patch.
+ *
+ * @returns `{ preserved: true }` if changes were found and committed,
+ *          `{ preserved: false }` if there were no .sprout/ changes,
+ *          `{ preserved: false, error: "..." }` if something went wrong.
+ */
+export async function preserveSproutChanges(
+	repoRoot: string,
+	branch: string,
+	canonicalBranch: string,
+	agentName: string,
+): Promise<{ preserved: boolean; error?: string }> {
+	// Step 1: Get the .sprout/ diff between canonical and the branch (three-dot diff).
+	// Three-dot diff shows changes introduced on branch since it diverged from canonicalBranch.
+	let diff: string;
+	try {
+		diff = await runGit(repoRoot, ["diff", `${canonicalBranch}...${branch}`, "--", ".sprout/"]);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { preserved: false, error: `Failed to compute .sprout/ diff: ${msg}` };
+	}
+
+	if (diff.trim() === "") {
+		// No .sprout/ changes on this branch
+		return { preserved: false };
+	}
+
+	// Step 2: Verify the repo root is currently on canonicalBranch.
+	let currentBranch: string;
+	try {
+		currentBranch = (await runGit(repoRoot, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { preserved: false, error: `Failed to determine current branch: ${msg}` };
+	}
+
+	if (currentBranch !== canonicalBranch) {
+		return {
+			preserved: false,
+			error: `Repo root is on '${currentBranch}', expected '${canonicalBranch}'. Cannot apply patch.`,
+		};
+	}
+
+	// Step 3: Check that .sprout/ is clean in the canonical branch.
+	let statusOutput: string;
+	try {
+		statusOutput = await runGit(repoRoot, ["status", "--porcelain", "--", ".sprout/"]);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		return { preserved: false, error: `Failed to check .sprout/ status: ${msg}` };
+	}
+
+	if (statusOutput.trim() !== "") {
+		return {
+			preserved: false,
+			error: `.sprout/ has uncommitted changes in canonical branch. Cannot apply patch safely.`,
+		};
+	}
+
+	// Step 4: Write diff to a temp file.
+	const tmpFile = join(repoRoot, ".agentplate", `_sprout-patch-${Date.now()}.diff`);
+	try {
+		await Bun.write(tmpFile, diff);
+
+		// Step 5: Apply the patch with --index (stages changes).
+		try {
+			await runGit(repoRoot, ["apply", "--index", tmpFile]);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			// Revert any partial changes
+			try {
+				await runGit(repoRoot, ["reset", "HEAD", "--", ".sprout/"]);
+				await runGit(repoRoot, ["checkout", "--", ".sprout/"]);
+			} catch {
+				// Best-effort revert
+			}
+			return { preserved: false, error: `Failed to apply .sprout/ patch: ${msg}` };
+		}
+
+		// Step 6: Commit the changes.
+		try {
+			await runGit(repoRoot, [
+				"commit",
+				"-m",
+				`chore: preserve .sprout/ changes from lead ${agentName}`,
+			]);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			// Revert any staged changes
+			try {
+				await runGit(repoRoot, ["reset", "HEAD", "--", ".sprout/"]);
+				await runGit(repoRoot, ["checkout", "--", ".sprout/"]);
+			} catch {
+				// Best-effort revert
+			}
+			return { preserved: false, error: `Failed to commit .sprout/ changes: ${msg}` };
+		}
+
+		return { preserved: true };
+	} finally {
+		// Step 8: Always clean up the temp file.
+		try {
+			await unlink(tmpFile);
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}

package/src/worktree/process.test.ts

@@ -0,0 +1,172 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getConnection, removeConnection } from "../runtimes/connections.ts";
+import { HeadlessClaudeConnection } from "../runtimes/headless-connection.ts";
+import { spawnHeadlessAgent } from "./process.ts";
+
+describe("spawnHeadlessAgent", () => {
+	it("spawns a command and returns a valid PID", async () => {
+		const proc = await spawnHeadlessAgent(["echo", "hello"], {
+			cwd: process.cwd(),
+			env: { ...(process.env as Record<string, string>) },
+		});
+		expect(typeof proc.pid).toBe("number");
+		expect(proc.pid).toBeGreaterThan(0);
+		expect(proc.stdout).toBeDefined();
+		expect(proc.stdin).toBeDefined();
+	});
+
+	it("throws AgentError when argv is empty", async () => {
+		await expect(spawnHeadlessAgent([], { cwd: process.cwd(), env: {} })).rejects.toThrow(
+			"empty argv",
+		);
+	});
+
+	describe("agentName connection registration", () => {
+		const registeredNames: string[] = [];
+
+		afterEach(() => {
+			for (const name of registeredNames.splice(0)) {
+				removeConnection(name);
+			}
+		});
+
+		it("registers a HeadlessClaudeConnection when agentName is provided", async () => {
+			const agentName = "test-headless-agent-xyz";
+			registeredNames.push(agentName);
+
+			const proc = await spawnHeadlessAgent(["sleep", "5"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+				agentName,
+			});
+
+			expect(proc.pid).toBeGreaterThan(0);
+			const conn = getConnection(agentName);
+			expect(conn).toBeDefined();
+			expect(conn).toBeInstanceOf(HeadlessClaudeConnection);
+
+			// Clean up the spawned process
+			try {
+				process.kill(proc.pid, "SIGTERM");
+			} catch {
+				// ignore
+			}
+		});
+
+		it("does not register a connection when agentName is omitted", async () => {
+			const proc = await spawnHeadlessAgent(["echo", "no-register"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+			});
+
+			// Drain stdout so process exits cleanly
+			if (proc.stdout) {
+				await new Response(proc.stdout).text();
+			}
+
+			// No connection was registered (use a stable lookup key that was never set)
+			expect(getConnection("never-registered-in-this-test")).toBeUndefined();
+		});
+
+		it("registered connection pid matches the spawned process pid", async () => {
+			const agentName = "test-headless-pid-check-xyz";
+			registeredNames.push(agentName);
+
+			const proc = await spawnHeadlessAgent(["sleep", "5"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+				agentName,
+			});
+
+			const conn = getConnection(agentName) as HeadlessClaudeConnection;
+			expect(conn).toBeDefined();
+			expect(conn.pid).toBe(proc.pid);
+
+			try {
+				process.kill(proc.pid, "SIGTERM");
+			} catch {
+				// ignore
+			}
+		});
+	});
+
+	describe("file redirect mode", () => {
+		let tmpDir: string;
+
+		beforeEach(async () => {
+			tmpDir = await mkdtemp(join(tmpdir(), "ap-process-test-"));
+		});
+
+		afterEach(async () => {
+			await rm(tmpDir, { recursive: true, force: true });
+		});
+
+		it("redirects stdout to file when stdoutFile is provided", async () => {
+			const stdoutFile = join(tmpDir, "stdout.log");
+			const proc = await spawnHeadlessAgent(["echo", "hello from file"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+				stdoutFile,
+			});
+
+			expect(typeof proc.pid).toBe("number");
+			expect(proc.pid).toBeGreaterThan(0);
+			// stdout is null when redirected to file — no pipe, no backpressure
+			expect(proc.stdout).toBeNull();
+			expect(proc.stdin).toBeDefined();
+
+			// Wait for process to finish, then check file content
+			const exitProc = Bun.spawn(["sh", "-c", "true"], { stdout: "pipe" });
+			await exitProc.exited;
+			// Give echo a moment to flush
+			await Bun.sleep(100);
+
+			const content = await Bun.file(stdoutFile).text();
+			expect(content.trim()).toBe("hello from file");
+		});
+
+		it("redirects stderr to file when stderrFile is provided", async () => {
+			const stderrFile = join(tmpDir, "stderr.log");
+			// Write to stderr via sh -c
+			const proc = await spawnHeadlessAgent(["sh", "-c", "echo error output >&2"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+				stderrFile,
+			});
+
+			expect(typeof proc.pid).toBe("number");
+			// stdout still piped (no stdoutFile provided)
+			expect(proc.stdout).not.toBeNull();
+
+			// Drain stdout to let process exit cleanly
+			if (proc.stdout) {
+				const reader = proc.stdout.getReader();
+				while (!(await reader.read()).done) {
+					// drain
+				}
+				reader.releaseLock();
+			}
+
+			await Bun.sleep(100);
+			const content = await Bun.file(stderrFile).text();
+			expect(content.trim()).toBe("error output");
+		});
+
+		it("stdout remains a ReadableStream when no stdoutFile provided (default mode)", async () => {
+			const proc = await spawnHeadlessAgent(["echo", "piped"], {
+				cwd: process.cwd(),
+				env: { ...(process.env as Record<string, string>) },
+			});
+
+			expect(proc.stdout).not.toBeNull();
+			expect(proc.stdout).toBeInstanceOf(ReadableStream);
+
+			// Read the content via the stream
+			const text = await new Response(proc.stdout as ReadableStream<Uint8Array>).text();
+			expect(text.trim()).toBe("piped");
+		});
+	});
+});

package/src/worktree/process.ts

@@ -0,0 +1,131 @@
+/**
+ * Headless subprocess management for non-tmux agent runtimes.
+ *
+ * Used by long-lived headless runtimes that bypass tmux (e.g., Sapling running
+ * with --json). Provides spawnHeadlessAgent() for direct Bun.spawn() invocation.
+ *
+ * Headless Claude Code does NOT use this path — under spawn-per-turn (Phase 3),
+ * Claude agents have no persistent process; each turn spawns a fresh claude
+ * inside `runTurn` (src/agents/turn-runner.ts). This module remains for
+ * runtimes that genuinely need a long-lived RPC channel.
+ *
+ * Note: isProcessAlive() and killProcessTree() for headless process lifecycle
+ * management already exist in src/worktree/tmux.ts — not duplicated here.
+ */
+
+import { AgentError } from "../errors.ts";
+import { registerHeadlessConnection } from "../runtimes/connections.ts";
+
+/**
+ * Handle to a spawned headless agent subprocess.
+ *
+ * Provides the PID for session tracking, stdin for sending input to the
+ * agent process, and stdout for consuming NDJSON event output.
+ *
+ * stdout is null when the process was spawned with a stdoutFile redirect
+ * (file-redirect mode). In that case, stdout is written directly to the
+ * log file and no pipe backpressure can occur.
+ */
+export interface HeadlessProcess {
+	/** OS-level process ID. Stored in AgentSession.pid for watchdog monitoring. */
+	pid: number;
+	/** Writable sink for sending input to the process (e.g., RPC messages). */
+	stdin: { write(data: string | Uint8Array): number | Promise<number> };
+	/**
+	 * Readable stream of the process stdout, or null when stdout was redirected
+	 * to a file via stdoutFile. Consumed via runtime.parseEvents() when piped.
+	 */
+	stdout: ReadableStream<Uint8Array> | null;
+}
+
+/**
+ * Options for spawning a headless agent subprocess.
+ *
+ * When stdoutFile or stderrFile are provided, the corresponding stream is
+ * redirected to the given file path instead of a pipe. This eliminates
+ * backpressure: the child process can write unlimited output without blocking.
+ *
+ * Log files are useful for post-mortem inspection and do not need to be
+ * consumed by the caller.
+ */
+export interface SpawnHeadlessOptions {
+	/** Working directory for the subprocess. */
+	cwd: string;
+	/** Full environment for the subprocess (no implicit merging with process.env). */
+	env: Record<string, string>;
+	/**
+	 * When set, redirect subprocess stdout to this file path instead of a pipe.
+	 * HeadlessProcess.stdout will be null in this case.
+	 */
+	stdoutFile?: string;
+	/**
+	 * When set, redirect subprocess stderr to this file path instead of a pipe.
+	 */
+	stderrFile?: string;
+	/**
+	 * When set, registers the spawned process as a `RuntimeConnection` keyed by
+	 * this agent name (sibling of Sapling's RPC connect() flow). Lets `ap nudge`,
+	 * the watchdog's liveness/abort path, etc. find the live process via
+	 * `getConnection(agentName)`.
+	 *
+	 * Same namespace as AgentSession.agentName.
+	 */
+	agentName?: string;
+}
+
+/**
+ * Spawn a headless agent subprocess directly via Bun.spawn().
+ *
+ * Used by `ap sling` when runtime.headless === true to bypass all tmux
+ * session management.
+ *
+ * **Backpressure prevention:** Pass stdoutFile (and stderrFile) to redirect
+ * output to log files instead of pipes. This is the recommended mode for
+ * `ap sling` — it prevents the OS pipe buffer (~64 KB) from filling up and
+ * blocking the child process when the caller does not actively consume stdout.
+ *
+ * When no file paths are provided (default/legacy mode), stdout is a pipe and
+ * the caller is responsible for consuming it to prevent backpressure.
+ *
+ * The provided env is used as the full subprocess environment (no implicit
+ * merging with process.env — callers should merge explicitly if needed).
+ *
+ * @param argv - Full argv array from runtime.buildDirectSpawn(); first element is the executable
+ * @param opts - Working directory, environment, and optional log file paths
+ * @returns HeadlessProcess with pid, stdin, and stdout (null if file-redirected)
+ * @throws AgentError if argv is empty
+ */
+export async function spawnHeadlessAgent(
+	argv: string[],
+	opts: SpawnHeadlessOptions,
+): Promise<HeadlessProcess> {
+	const [cmd, ...args] = argv;
+	if (!cmd) {
+		throw new AgentError("buildDirectSpawn returned empty argv array", {
+			agentName: "headless",
+		});
+	}
+
+	const stdoutTarget = opts.stdoutFile ? Bun.file(opts.stdoutFile) : "pipe";
+	const stderrTarget = opts.stderrFile ? Bun.file(opts.stderrFile) : "pipe";
+
+	const proc = Bun.spawn([cmd, ...args], {
+		cwd: opts.cwd,
+		env: opts.env,
+		stdout: stdoutTarget,
+		stderr: stderrTarget,
+		stdin: "pipe",
+	});
+
+	const result: HeadlessProcess = {
+		pid: proc.pid,
+		stdin: proc.stdin as HeadlessProcess["stdin"],
+		stdout: opts.stdoutFile ? null : (proc.stdout as ReadableStream<Uint8Array>),
+	};
+
+	if (opts.agentName) {
+		registerHeadlessConnection(opts.agentName, result);
+	}
+
+	return result;
+}