@agentplate/cli 1.0.0

package/src/wizard/setup.ts

@@ -0,0 +1,254 @@
+/**
+ * Interactive setup wizard (the Hermes-style onboarding).
+ *
+ * Walks the user through: provider selection → credentials → model → runtime,
+ * then returns the resulting config plus an optional secret for the caller to
+ * persist. Pure config construction is delegated to `providers/apply.ts`; this
+ * module owns only the interactive I/O.
+ */
+
+import * as p from "@clack/prompts";
+import { applyProviderSelection, buildProviderConfig } from "../providers/apply.ts";
+import { getProviderSpec, listProviders, meetsContextFloor } from "../providers/registry.ts";
+import type { AgentplateConfig, AuthMode } from "../types.ts";
+import { commandOnPath, detectDefaultRuntime } from "../utils/detect.ts";
+
+/** Runtimes the wizard can offer. */
+const RUNTIME_CHOICES: ReadonlyArray<{ value: string; label: string; cli: string }> = [
+	{ value: "claude", label: "Claude Code", cli: "claude" },
+	{ value: "opencode", label: "OpenCode", cli: "opencode" },
+	{ value: "codex", label: "OpenAI Codex", cli: "codex" },
+	{ value: "gemini", label: "Gemini CLI", cli: "gemini" },
+	{ value: "cursor", label: "Cursor", cli: "cursor-agent" },
+];
+
+/** Map a runtime id to the CLI binary that provides its login. */
+function runtimeCli(runtime: string): string {
+	return RUNTIME_CHOICES.find((r) => r.value === runtime)?.cli ?? runtime;
+}
+
+export interface WizardResult {
+	/** The new config to persist. */
+	config: AgentplateConfig;
+	/** A secret to store (env-var name → value), if the user provided one. */
+	secret?: { key: string; value: string };
+}
+
+/** Abort the wizard cleanly if the user cancelled a prompt. */
+function ensure<T>(value: T | symbol): T {
+	if (p.isCancel(value)) {
+		p.cancel("Setup cancelled. No changes written.");
+		process.exit(0);
+	}
+	return value;
+}
+
+/** Run the interactive wizard. Returns the config + optional secret to persist. */
+export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<WizardResult> {
+	p.intro("Agentplate setup");
+
+	// 1. Provider ----------------------------------------------------------
+	const providerId = ensure(
+		await p.select({
+			message: "Choose your AI provider",
+			initialValue: currentConfig.activeProvider,
+			options: listProviders().map((spec) => ({
+				value: spec.id,
+				label: spec.label,
+				hint: spec.description,
+			})),
+		}),
+	);
+	const spec = getProviderSpec(providerId);
+	if (!spec) {
+		p.cancel(`Unknown provider "${providerId}".`);
+		process.exit(1);
+	}
+
+	// 2. Base URL (custom endpoints only) ----------------------------------
+	let baseUrl: string | undefined;
+	if (spec.requiresBaseUrl) {
+		baseUrl = ensure(
+			await p.text({
+				message: "Base URL for the endpoint",
+				placeholder: "https://my-endpoint.example.com/v1",
+				validate: (v) => (v.trim().length === 0 ? "A base URL is required" : undefined),
+			}),
+		);
+	} else {
+		baseUrl = spec.defaultBaseUrl;
+	}
+
+	// 3. Authentication method --------------------------------------------
+	// Offer the same kind of choice Claude Code shows: use an existing
+	// subscription/CLI login, an existing env var, or enter an API key.
+	let secret: WizardResult["secret"];
+	let authMode: AuthMode;
+
+	if (spec.keyless) {
+		authMode = "none";
+		p.note("This provider runs locally and needs no credentials.", spec.label);
+	} else {
+		const envPresent = Boolean(process.env[spec.authEnvVar]?.length);
+		const subInstalled = spec.subscriptionRuntime
+			? await commandOnPath(runtimeCli(spec.subscriptionRuntime))
+			: false;
+
+		const options: Array<{ value: AuthMode; label: string; hint?: string }> = [];
+		if (spec.supportsSubscription) {
+			options.push({
+				value: "subscription",
+				label: spec.subscriptionLabel ?? `${spec.label} subscription / CLI login`,
+				hint: subInstalled ? "CLI detected — uses its login" : "requires the CLI to be logged in",
+			});
+		}
+		if (envPresent) {
+			options.push({
+				value: "env",
+				label: `Use existing ${spec.authEnvVar} from your environment`,
+				hint: "already set — nothing stored",
+			});
+		}
+		options.push({
+			value: "api-key",
+			label: "Enter an API key (pay-per-token)",
+			hint: "stored in .agentplate/secrets.local.yaml (gitignored)",
+		});
+
+		// Default to the most convenient available method.
+		const initialAuth: AuthMode = spec.supportsSubscription
+			? "subscription"
+			: envPresent
+				? "env"
+				: "api-key";
+
+		authMode =
+			options.length === 1
+				? "api-key"
+				: ensure(
+						await p.select({
+							message: `How should Agentplate authenticate with ${spec.label}?`,
+							initialValue: initialAuth,
+							options,
+						}),
+					);
+
+		if (authMode === "subscription") {
+			const cli = spec.subscriptionRuntime ? runtimeCli(spec.subscriptionRuntime) : spec.id;
+			if (!subInstalled) {
+				p.note(
+					`Agentplate will use your ${spec.subscriptionLabel ?? "CLI"} login.\n` +
+						`Make sure \`${cli}\` is installed and logged in (run \`${cli}\` once to sign in).`,
+					"Subscription auth",
+				);
+			} else {
+				p.note(`Using your existing \`${cli}\` login — no API key stored.`, "Subscription auth");
+			}
+		} else if (authMode === "api-key") {
+			const key = ensure(
+				await p.password({
+					message: `Enter your ${spec.label} API key (${spec.authEnvVar})`,
+					validate: (v) => (v.trim().length === 0 ? "An API key is required" : undefined),
+				}),
+			);
+			secret = { key: spec.authEnvVar, value: key.trim() };
+		}
+		// authMode === "env": nothing to store; resolved from the environment at run time.
+	}
+
+	// 4. Model -------------------------------------------------------------
+	const eligible = spec.models.filter(meetsContextFloor);
+	let model: string;
+	if (eligible.length > 0) {
+		const choice = ensure(
+			await p.select({
+				message: "Choose a default model",
+				options: [
+					...eligible.map((m) => ({
+						value: m.id,
+						label: m.label,
+						hint: `${Math.round(m.contextWindow / 1000)}k context`,
+					})),
+					{ value: "__custom__", label: "Custom model id…", hint: "type your own" },
+				],
+			}),
+		);
+		model =
+			choice === "__custom__"
+				? ensure(
+						await p.text({
+							message: "Model id",
+							validate: (v) => (v.trim().length === 0 ? "A model id is required" : undefined),
+						}),
+					).trim()
+				: choice;
+	} else {
+		model = ensure(
+			await p.text({
+				message: "Model id",
+				placeholder: "provider/model-name",
+				validate: (v) => (v.trim().length === 0 ? "A model id is required" : undefined),
+			}),
+		).trim();
+	}
+
+	// 5. Runtime -----------------------------------------------------------
+	const detected = await detectDefaultRuntime();
+	const installed = new Set<string>();
+	await Promise.all(
+		RUNTIME_CHOICES.map(async (r) => {
+			if (await commandOnPath(r.cli)) installed.add(r.value);
+		}),
+	);
+	// When the user picked subscription/OAuth auth, the login lives in the
+	// provider's own CLI (e.g. a ChatGPT login in `codex`, a Google login in
+	// `gemini`). Default the runtime to that CLI so the OAuth credentials are
+	// actually reused — otherwise a mismatched runtime (e.g. `claude` driving a
+	// GPT model with no key) would silently break the login.
+	const initialRuntime =
+		authMode === "subscription" && spec.subscriptionRuntime ? spec.subscriptionRuntime : detected;
+	const runtime = ensure(
+		await p.select({
+			message: "Which coding-agent runtime should drive workers?",
+			initialValue: initialRuntime,
+			options: RUNTIME_CHOICES.map((r) => ({
+				value: r.value,
+				label: r.label,
+				hint: installed.has(r.value) ? "installed" : "not detected on PATH",
+			})),
+		}),
+	);
+
+	// 6. Summary -----------------------------------------------------------
+	const previewProvider = buildProviderConfig(spec, model, authMode, baseUrl);
+	const authSummary: Record<AuthMode, string> = {
+		subscription: `subscription / ${runtimeCli(spec.subscriptionRuntime ?? runtime)} login (no key stored)`,
+		"api-key": `${spec.authEnvVar} → secrets.local.yaml`,
+		env: `${spec.authEnvVar} (from environment)`,
+		none: "none (local)",
+	};
+	p.note(
+		[
+			`provider:  ${spec.label} (${providerId})`,
+			`model:     ${model}`,
+			`runtime:   ${runtime}`,
+			`auth:      ${authSummary[authMode]}`,
+			previewProvider.baseUrl ? `base URL:  ${previewProvider.baseUrl}` : undefined,
+		]
+			.filter(Boolean)
+			.join("\n"),
+		"Configuration",
+	);
+
+	const config = applyProviderSelection(currentConfig, {
+		providerId,
+		spec,
+		model,
+		authMode,
+		baseUrl,
+		runtime,
+	});
+
+	p.outro("Ready to write configuration.");
+	return secret ? { config, secret } : { config };
+}

package/src/worktree/manager.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { WorktreeError } from "../errors.ts";
+import { createWorktree, listWorktrees, removeWorktree, worktreeExists } from "./manager.ts";
+
+// We use REAL git repos in temp dirs (no mocks) so the porcelain parsing and
+// `git worktree` semantics are exercised exactly as in production.
+
+/** Run git in `cwd`, fail the test helper loudly on non-zero exit. */
+async function runGit(cwd: string, args: string[]): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+	const [stdout, stderr, code] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+	if (code !== 0) {
+		throw new Error(`git ${args.join(" ")} failed (${code}): ${stderr.trim()}`);
+	}
+	return stdout.trim();
+}
+
+/**
+ * Create a real git repo in a fresh temp dir with a deterministic identity and
+ * one initial commit (so HEAD exists and worktrees have a base to branch from).
+ */
+async function createTempGitRepo(): Promise<string> {
+	// realpathSync resolves symlinks in the temp root. On macOS tmpdir() is
+	// /tmp -> /private/tmp; `git worktree list --porcelain` reports the resolved
+	// form, so we canonicalize here to keep the test's constructed paths in sync
+	// with git's output (createWorktree itself is path-agnostic — it just joins).
+	const dir = realpathSync(mkdtempSync(join(tmpdir(), "agentplate-wt-")));
+	await runGit(dir, ["init"]);
+	// Pin a deterministic identity so commits succeed in CI.
+	await runGit(dir, ["config", "user.email", "test@agentplate.dev"]);
+	await runGit(dir, ["config", "user.name", "Agentplate Test"]);
+	writeFileSync(join(dir, "README.md"), "# temp repo\n");
+	await runGit(dir, ["add", "README.md"]);
+	await runGit(dir, ["commit", "-m", "initial commit"]);
+	// Force the initial branch to "main" regardless of the host's
+	// init.defaultBranch (master vs main). `branch -M` renames in place and is a
+	// no-op-safe rename even if the branch is already called "main", so this is
+	// portable across git versions.
+	await runGit(dir, ["branch", "-M", "main"]);
+	return dir;
+}
+
+describe("worktree manager", () => {
+	let repoRoot: string;
+
+	beforeEach(async () => {
+		repoRoot = await createTempGitRepo();
+	});
+
+	afterEach(() => {
+		rmSync(repoRoot, { recursive: true, force: true });
+	});
+
+	test("createWorktree creates the dir on the right branch and returns its path", async () => {
+		const result = await createWorktree(repoRoot, "alice", "agent/alice");
+
+		const expectedPath = join(repoRoot, ".agentplate", "worktrees", "alice");
+		expect(result.path).toBe(expectedPath);
+		expect(result.branchName).toBe("agent/alice");
+
+		// The directory exists on disk.
+		expect(await worktreeExists(repoRoot, expectedPath)).toBe(true);
+
+		// HEAD inside the worktree resolves to the new branch.
+		const currentBranch = await runGit(result.path, ["rev-parse", "--abbrev-ref", "HEAD"]);
+		expect(currentBranch).toBe("agent/alice");
+	});
+
+	test("createWorktree creates the .agentplate/worktrees parent if missing", async () => {
+		// No pre-existing .agentplate dir — createWorktree must mkdir -p the parents.
+		const result = await createWorktree(repoRoot, "bob", "agent/bob");
+		expect(await worktreeExists(repoRoot, result.path)).toBe(true);
+	});
+
+	test("createWorktree throws WorktreeError when the path already exists", async () => {
+		await createWorktree(repoRoot, "dup", "agent/dup-1");
+
+		// A second create for the same agent name targets the same dir -> collide.
+		await expect(createWorktree(repoRoot, "dup", "agent/dup-2")).rejects.toBeInstanceOf(
+			WorktreeError,
+		);
+	});
+
+	test("createWorktree branches off an explicit baseBranch", async () => {
+		// Make a divergent branch with a marker file, return to main.
+		await runGit(repoRoot, ["checkout", "-b", "feature-base"]);
+		writeFileSync(join(repoRoot, "marker.txt"), "from base\n");
+		await runGit(repoRoot, ["add", "marker.txt"]);
+		await runGit(repoRoot, ["commit", "-m", "base-only commit"]);
+		await runGit(repoRoot, ["checkout", "main"]);
+
+		const result = await createWorktree(repoRoot, "carol", "agent/carol", "feature-base");
+
+		// The worktree should see the marker file that only exists on feature-base.
+		expect(await worktreeExists(repoRoot, join(result.path, "marker.txt"))).toBe(true);
+	});
+
+	test("listWorktrees parses porcelain output including the main worktree", async () => {
+		await createWorktree(repoRoot, "alice", "agent/alice");
+
+		const list = await listWorktrees(repoRoot);
+
+		// Main worktree + the one we created.
+		expect(list.length).toBe(2);
+
+		const alice = list.find((w) => w.branch === "agent/alice");
+		expect(alice).toBeDefined();
+		expect(alice?.path).toBe(join(repoRoot, ".agentplate", "worktrees", "alice"));
+		// HEAD is a 40-char SHA.
+		expect(alice?.head).toMatch(/^[0-9a-f]{40}$/);
+
+		const mainEntry = list.find((w) => w.branch === "main");
+		expect(mainEntry).toBeDefined();
+	});
+
+	test("a commit made inside the worktree is visible on its branch", async () => {
+		const { path: wtPath } = await createWorktree(repoRoot, "writer", "agent/writer");
+
+		// Commit a file from INSIDE the worktree.
+		writeFileSync(join(wtPath, "work.txt"), "agent output\n");
+		await runGit(wtPath, ["add", "work.txt"]);
+		await runGit(wtPath, ["commit", "-m", "agent work"]);
+
+		// The branch tip (queried from the main repo) must contain that commit.
+		const subject = await runGit(repoRoot, ["log", "-1", "--format=%s", "agent/writer"]);
+		expect(subject).toBe("agent work");
+
+		// And the file is part of that branch's tree.
+		const tree = await runGit(repoRoot, ["ls-tree", "--name-only", "agent/writer"]);
+		expect(tree.split("\n")).toContain("work.txt");
+	});
+
+	test("worktreeExists reflects creation and removal", async () => {
+		const missing = join(repoRoot, ".agentplate", "worktrees", "ghost");
+		expect(await worktreeExists(repoRoot, missing)).toBe(false);
+
+		const { path } = await createWorktree(repoRoot, "ghost", "agent/ghost");
+		expect(await worktreeExists(repoRoot, path)).toBe(true);
+
+		await removeWorktree(repoRoot, path);
+		expect(await worktreeExists(repoRoot, path)).toBe(false);
+	});
+
+	test("removeWorktree removes a clean worktree without force", async () => {
+		const { path } = await createWorktree(repoRoot, "tmp", "agent/tmp");
+
+		await removeWorktree(repoRoot, path);
+
+		// Gone from disk...
+		expect(await worktreeExists(repoRoot, path)).toBe(false);
+		// ...and de-registered from git's worktree list.
+		const list = await listWorktrees(repoRoot);
+		expect(list.find((w) => w.path === path)).toBeUndefined();
+	});
+
+	test("removeWorktree requires force when the worktree is dirty", async () => {
+		const { path } = await createWorktree(repoRoot, "dirty", "agent/dirty");
+
+		// Introduce an uncommitted change; git refuses a non-forced remove.
+		writeFileSync(join(path, "scratch.txt"), "uncommitted\n");
+
+		await expect(removeWorktree(repoRoot, path)).rejects.toBeInstanceOf(WorktreeError);
+
+		// With force it succeeds.
+		await removeWorktree(repoRoot, path, { force: true });
+		expect(await worktreeExists(repoRoot, path)).toBe(false);
+	});
+
+	test("removeWorktree throws WorktreeError for an unknown path", async () => {
+		const bogus = join(repoRoot, ".agentplate", "worktrees", "does-not-exist");
+		await expect(removeWorktree(repoRoot, bogus)).rejects.toBeInstanceOf(WorktreeError);
+	});
+});

package/src/worktree/manager.ts

@@ -0,0 +1,229 @@
+import { mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { SubprocessError, WorktreeError } from "../errors.ts";
+
+// Where every agent's isolated worktree lives, relative to the repo root.
+// Mirrors agentplate's layout (.agentplate/worktrees/<agent>) so the rest of
+// Agentplate can reason about paths deterministically without consulting git.
+const WORKTREES_SUBDIR = join(".agentplate", "worktrees");
+
+/** A single entry parsed from `git worktree list --porcelain`. */
+export interface WorktreeEntry {
+	/** Absolute path to the worktree directory. */
+	path: string;
+	/** Branch ref (short name, e.g. "feature/x") or "" for detached HEAD. */
+	branch: string;
+	/** Commit SHA the worktree currently points at. */
+	head: string;
+}
+
+/**
+ * Run a git subcommand in `repoRoot` and return trimmed stdout.
+ *
+ * Centralised here (rather than per-function) so every git call shares the same
+ * argv-array invocation, output capture, and typed-error handling. We never use
+ * a shell string: argv arrays avoid quoting/injection issues entirely.
+ *
+ * On a non-zero exit we throw SubprocessError carrying stderr so callers (and
+ * the higher-level WorktreeError translation) have the real git diagnostic.
+ */
+async function git(repoRoot: string, args: string[]): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], {
+		cwd: repoRoot,
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	// Drain both streams before awaiting exit. Reading after `await proc.exited`
+	// is fine for small outputs, but draining first avoids any chance of a
+	// pipe-buffer stall on large `git worktree list` output.
+	const [stdout, stderr, exitCode] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+		proc.exited,
+	]);
+
+	if (exitCode !== 0) {
+		const detail = stderr.trim() || stdout.trim() || `exit code ${exitCode}`;
+		throw new SubprocessError(`git ${args.join(" ")} failed: ${detail}`);
+	}
+
+	return stdout.trim();
+}
+
+/**
+ * Create an isolated git worktree for an agent on a brand-new branch.
+ *
+ * Layout: `<repoRoot>/.agentplate/worktrees/<agentName>` checked out on a freshly
+ * created `branchName` based off `baseBranch` (default: current HEAD).
+ *
+ * We mkdir the parent (`.agentplate/worktrees`) up front because git refuses to
+ * create a worktree under a non-existent parent directory. If the target path
+ * already exists we fail fast with WorktreeError rather than letting git emit a
+ * confusing "already exists"/"not a valid object" message — a pre-existing path
+ * almost always means a stale or duplicate agent and the caller must clean up.
+ */
+export async function createWorktree(
+	repoRoot: string,
+	agentName: string,
+	branchName: string,
+	baseBranch?: string,
+): Promise<{ path: string; branchName: string }> {
+	const parentDir = join(repoRoot, WORKTREES_SUBDIR);
+	const worktreePath = join(parentDir, agentName);
+
+	// Guard against clobbering an existing worktree directory. We check before
+	// touching git so the error is precise and no partial state is created.
+	if (await worktreeExists(repoRoot, worktreePath)) {
+		throw new WorktreeError(`Worktree path already exists: ${worktreePath}`);
+	}
+
+	// Ensure `.agentplate/worktrees/` exists (recursive == mkdir -p, no error if
+	// the parent chain already exists from a prior agent).
+	await mkdir(parentDir, { recursive: true });
+
+	// `git worktree add -b <branch> <path> [<base>]` creates the branch and the
+	// worktree atomically. Omitting <base> makes git use the current HEAD, which
+	// matches our documented default.
+	const addArgs = ["worktree", "add", "-b", branchName, worktreePath];
+	if (baseBranch !== undefined) {
+		addArgs.push(baseBranch);
+	}
+
+	try {
+		await git(repoRoot, addArgs);
+	} catch (error) {
+		// Translate the low-level subprocess failure into the domain error the
+		// rest of Agentplate expects, preserving the original git message.
+		const message = error instanceof Error ? error.message : String(error);
+		throw new WorktreeError(`Failed to create worktree for ${agentName}: ${message}`);
+	}
+
+	return { path: worktreePath, branchName };
+}
+
+/**
+ * List all worktrees registered with this repository.
+ *
+ * Parses `git worktree list --porcelain`, whose stable, machine-readable format
+ * emits one record per worktree separated by a blank line. Each record looks
+ * like:
+ *
+ *   worktree /abs/path
+ *   HEAD <sha>
+ *   branch refs/heads/<name>        (omitted/replaced by `detached` if detached)
+ *
+ * We intentionally parse the porcelain (not the human format) so output is
+ * locale- and version-stable.
+ */
+export async function listWorktrees(
+	repoRoot: string,
+): Promise<Array<{ path: string; branch: string; head: string }>> {
+	const output = await git(repoRoot, ["worktree", "list", "--porcelain"]);
+	if (output === "") {
+		return [];
+	}
+
+	const entries: WorktreeEntry[] = [];
+	// Records are separated by blank lines. Split on a blank line and process
+	// each block independently so a malformed/extra field never bleeds across
+	// records.
+	const blocks = output.split("\n\n");
+
+	for (const block of blocks) {
+		const trimmedBlock = block.trim();
+		if (trimmedBlock === "") {
+			continue;
+		}
+
+		let path: string | undefined;
+		let head = "";
+		let branch = "";
+
+		for (const line of trimmedBlock.split("\n")) {
+			if (line.startsWith("worktree ")) {
+				path = line.slice("worktree ".length).trim();
+			} else if (line.startsWith("HEAD ")) {
+				head = line.slice("HEAD ".length).trim();
+			} else if (line.startsWith("branch ")) {
+				// git prints the full ref ("refs/heads/foo"); expose the short name.
+				const ref = line.slice("branch ".length).trim();
+				branch = ref.startsWith("refs/heads/") ? ref.slice("refs/heads/".length) : ref;
+			}
+			// `detached`, `bare`, `locked`, etc. carry no fields we surface; ignore.
+		}
+
+		// A record without a `worktree` line is not something git emits; skip it
+		// defensively so the return type's `path` is always a real string.
+		if (path === undefined) {
+			continue;
+		}
+
+		entries.push({ path, branch, head });
+	}
+
+	return entries;
+}
+
+/**
+ * Remove a worktree via `git worktree remove`.
+ *
+ * `--force` is required when the worktree has uncommitted changes or is locked;
+ * callers opt in via `opts.force`. We do NOT delete the branch here — branch
+ * lifecycle (merge/cleanup) is a separate concern handled elsewhere.
+ */
+export async function removeWorktree(
+	repoRoot: string,
+	worktreePath: string,
+	opts?: { force?: boolean },
+): Promise<void> {
+	const args = ["worktree", "remove"];
+	if (opts?.force === true) {
+		args.push("--force");
+	}
+	args.push(worktreePath);
+
+	try {
+		await git(repoRoot, args);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new WorktreeError(`Failed to remove worktree ${worktreePath}: ${message}`);
+	}
+}
+
+/**
+ * Force-delete a local branch via `git branch -D`. Used to fully clean up a
+ * reaped agent's `agentplate/<name>` branch after its worktree is removed. Uses
+ * `-D` (not `-d`) because the branch is typically unmerged. The branch must no
+ * longer be checked out by any worktree (remove the worktree first).
+ */
+export async function deleteBranch(repoRoot: string, branchName: string): Promise<void> {
+	try {
+		await git(repoRoot, ["branch", "-D", branchName]);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new WorktreeError(`Failed to delete branch ${branchName}: ${message}`);
+	}
+}
+
+/**
+ * Report whether a worktree directory currently exists on disk.
+ *
+ * We answer from the filesystem (not `git worktree list`) on purpose: callers
+ * use this to decide whether `createWorktree` would collide, and a leftover
+ * directory from an interrupted/aborted run can exist even when git no longer
+ * tracks it as a worktree. A filesystem check catches both cases.
+ */
+export async function worktreeExists(_repoRoot: string, worktreePath: string): Promise<boolean> {
+	// We stat the path directly (rather than Bun.file().exists(), which reports
+	// false for directories) so the check is correct for the common case where a
+	// worktree is a directory. Any stat error — ENOENT and friends — means the
+	// path is absent for our collision-detection purposes.
+	try {
+		await stat(worktreePath);
+		return true;
+	} catch {
+		return false;
+	}
+}