@agentplate/cli 1.1.0 → 1.3.0

package/src/commands/watch.ts

@@ -0,0 +1,151 @@
+/**
+ * `agentplate watch` — the mail pump that makes warm-start automatic.
+ *
+ * Each tick it finds **idle** agents (paused after a turn, awaiting mail) that now
+ * have **unread mail**, and runs each one's next turn via {@link driveAgentTurn},
+ * which **resumes** the runtime session (warm start). Detection is non-destructive
+ * (`mail.check(..., { unreadOnly })`); the turn itself injects + marks the mail
+ * read. Each pass drives eligible agents concurrently, capped at the fleet's
+ * `maxConcurrent`; a failing turn is logged and the loop continues.
+ *
+ * Modes: `--once` (single pass), `--until-idle` (loop until no active agents
+ * remain — the run drained), or the default (loop until Ctrl-C).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { Command } from "commander";
+import { driveAgentTurn } from "../agents/drive.ts";
+import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
+import { ValidationError } from "../errors.ts";
+import { createEventStore } from "../events/store.ts";
+import { jsonOutput } from "../json.ts";
+import { brand, muted, printInfo, printSuccess, printWarning } from "../logging/color.ts";
+import { createMailClient } from "../mail/client.ts";
+import { currentRunPath, eventsDbPath, sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentSession } from "../types.ts";
+
+interface WatchOptions {
+	run?: string;
+	interval?: string;
+	once?: boolean;
+	untilIdle?: boolean;
+	json?: boolean;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Current run id from `.agentplate/current-run.txt`, or undefined (= all runs). */
+function readCurrentRun(root: string): string | undefined {
+	const path = currentRunPath(root);
+	if (!existsSync(path)) return undefined;
+	return readFileSync(path, "utf8").trim() || undefined;
+}
+
+export function createWatchCommand(): Command {
+	return new Command("watch")
+		.description("Auto-advance idle agents: run their next (resumed) turn when they have mail")
+		.option("--run <id>", "scope to a run (default: the current run)")
+		.option("--interval <ms>", "poll interval in milliseconds", "2000")
+		.option("--once", "run a single pass, then exit")
+		.option("--until-idle", "exit once no active agents remain (the run has drained)")
+		.option("--json", "output a JSON summary")
+		.action(async (opts: WatchOptions, command: Command) => {
+			const useJson = command.optsWithGlobals().json === true;
+			const root = findProjectRoot();
+			if (!isInitialized(root)) {
+				throw new ValidationError("Not initialized. Run `agentplate setup` first.");
+			}
+			const config = loadConfig(root);
+			const interval = Number(opts.interval ?? "2000");
+			if (!Number.isFinite(interval) || interval < 0) {
+				throw new ValidationError("--interval must be a non-negative number of milliseconds.");
+			}
+			const runId = opts.run ?? readCurrentRun(root);
+
+			const store = createSessionStore(sessionsDbPath(root));
+			const mail = createMailClient(root);
+			const events = createEventStore(eventsDbPath(root));
+
+			let stop = false;
+			const onSigint = (): void => {
+				stop = true;
+			};
+			process.once("SIGINT", onSigint);
+
+			let totalDriven = 0;
+			const drivenLog: Array<{ agent: string; state: string }> = [];
+			// Cap simultaneous turns at the fleet's maxConcurrent (>= 1).
+			const concurrency = Math.max(1, config.agents.maxConcurrent);
+
+			/** Drive one agent's next turn, recording the outcome. */
+			const driveOne = async (session: AgentSession): Promise<void> => {
+				try {
+					const { finalState } = await driveAgentTurn({
+						root,
+						config,
+						session,
+						store,
+						events,
+						mail,
+					});
+					totalDriven++;
+					drivenLog.push({ agent: session.agentName, state: finalState });
+					if (!useJson) printInfo(`  ${brand(session.agentName)} → ${finalState}`);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					if (!useJson) printWarning(`  ${session.agentName}: turn failed — ${message}`);
+				}
+			};
+
+			/**
+			 * One pass: drive every idle agent that has unread mail, up to `concurrency`
+			 * turns at a time. Returns the number driven.
+			 */
+			const pass = async (): Promise<number> => {
+				const eligible = store
+					.listSessions({ runId, state: "idle" })
+					.filter((s) => mail.check(s.agentName, { unreadOnly: true }).length > 0);
+				let next = 0;
+				const worker = async (): Promise<void> => {
+					while (!stop) {
+						const session = eligible[next++];
+						if (!session) break;
+						await driveOne(session);
+					}
+				};
+				const lanes = Math.min(concurrency, eligible.length);
+				await Promise.all(Array.from({ length: lanes }, () => worker()));
+				return eligible.length;
+			};
+
+			try {
+				if (opts.once) {
+					await pass();
+				} else {
+					if (!useJson) {
+						printInfo(
+							`Watching${runId ? ` run ${muted(runId)}` : " all runs"} (every ${interval}ms; Ctrl-C to stop)…`,
+						);
+					}
+					while (!stop) {
+						await pass();
+						if (opts.untilIdle && store.countActive(runId) === 0) break;
+						if (stop) break;
+						await sleep(interval);
+					}
+				}
+			} finally {
+				process.removeListener("SIGINT", onSigint);
+				events.close();
+				mail.close();
+				store.close();
+			}
+
+			if (useJson) {
+				jsonOutput({ runId: runId ?? null, driven: totalDriven, turns: drivenLog });
+				return;
+			}
+			printSuccess(`Watch finished — drove ${totalDriven} turn(s).`);
+		});
+}

package/src/config.test.ts

@@ -45,6 +45,13 @@ describe("loadConfig", () => {
 		expect(cfg.merge.aiResolveEnabled).toBe(true);
 	});
 
+	test("an old config without merge.autoMerge inherits the 'off' default (deep merge)", () => {
+		writeConfig(root, "config.yaml", "merge:\n  aiResolveEnabled: true\n");
+		const cfg = loadConfig(root);
+		expect(cfg.merge.autoMerge).toBe("off");
+		expect(cfg.merge.aiResolveEnabled).toBe(true);
+	});
+
 	test("config.local.yaml overrides config.yaml", () => {
 		writeConfig(root, "config.yaml", "runtime:\n  default: claude\n");
 		writeConfig(root, "config.local.yaml", "runtime:\n  default: gemini\n");
@@ -74,6 +81,31 @@ describe("validateConfig", () => {
 	test("accepts the defaults", () => {
 		expect(() => validateConfig(structuredClone(DEFAULT_CONFIG))).not.toThrow();
 	});
+
+	test("auto-merge defaults to off", () => {
+		expect(DEFAULT_CONFIG.merge.autoMerge).toBe("off");
+	});
+
+	test("rejects an unknown merge.autoMerge mode", () => {
+		const cfg = structuredClone(DEFAULT_CONFIG);
+		// @ts-expect-error intentionally invalid value
+		cfg.merge.autoMerge = "always";
+		expect(() => validateConfig(cfg)).toThrow();
+	});
+
+	test("turn timeout + skip defaults are off", () => {
+		expect(DEFAULT_CONFIG.agents.turnTimeoutMinutes).toBe(0);
+		expect(DEFAULT_CONFIG.agents.skipScout).toBe(false);
+		expect(DEFAULT_CONFIG.agents.skipReview).toBe(false);
+		expect(DEFAULT_CONFIG.agents.skipGates).toBe(false);
+		expect(DEFAULT_CONFIG.agents.skipSkills).toBe(false);
+	});
+
+	test("rejects a negative turnTimeoutMinutes", () => {
+		const cfg = structuredClone(DEFAULT_CONFIG);
+		cfg.agents.turnTimeoutMinutes = -1;
+		expect(() => validateConfig(cfg)).toThrow();
+	});
 });
 
 describe("isInitialized / serializeConfig", () => {

package/src/config.ts

@@ -13,7 +13,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import yaml from "js-yaml";
 import { ConfigError } from "./errors.ts";
-import type { AgentplateConfig } from "./types.ts";
+import type { AgentplateConfig, AutoMergeMode } from "./types.ts";
 
 /** Directory (relative to project root) holding all Agentplate state. */
 export const AGENTPLATE_DIR = ".agentplate";
@@ -43,9 +43,15 @@ export const DEFAULT_CONFIG: AgentplateConfig = {
 		maxDepth: 2,
 		maxAgentsPerLead: 5,
 		idleTimeoutMinutes: 10,
+		turnTimeoutMinutes: 0,
+		skipScout: false,
+		skipReview: false,
+		skipGates: false,
+		skipSkills: false,
 	},
 	merge: {
 		aiResolveEnabled: true,
+		autoMerge: "off",
 	},
 	skills: {
 		enabled: true,
@@ -175,6 +181,15 @@ export function validateConfig(config: AgentplateConfig): void {
 			"config.agents.idleTimeoutMinutes must be >= 0 (0 disables idle reaping)",
 		);
 	}
+	if (config.agents.turnTimeoutMinutes < 0) {
+		throw new ConfigError(
+			"config.agents.turnTimeoutMinutes must be >= 0 (0 disables the per-turn cap)",
+		);
+	}
+	const autoMergeModes: AutoMergeMode[] = ["off", "on-gates-pass", "on-complete"];
+	if (!autoMergeModes.includes(config.merge.autoMerge)) {
+		throw new ConfigError(`config.merge.autoMerge must be one of: ${autoMergeModes.join(", ")}`);
+	}
 }
 
 /**

package/src/errors.ts

@@ -63,6 +63,17 @@ export class NotFoundError extends AgentplateError {
 	}
 }
 
+/**
+ * A spawn was refused because it would exceed a configured orchestration limit
+ * (maxConcurrent / maxAgentsPerLead / maxDepth). Distinct exit code so callers
+ * (a lead/coordinator) can recognize "at capacity — back off and retry later".
+ */
+export class CapacityError extends AgentplateError {
+	constructor(message: string) {
+		super(message, "CAPACITY_EXCEEDED", 5);
+	}
+}
+
 /** Type guard: is the given value a AgentplateError? */
 export function isAgentplateError(value: unknown): value is AgentplateError {
 	return value instanceof AgentplateError;

package/src/index.ts

@@ -34,6 +34,8 @@ import { createSpecCommand } from "./commands/spec.ts";
 import { createStatusCommand } from "./commands/status.ts";
 import { createStopCommand } from "./commands/stop.ts";
 import { createTuiCommand } from "./commands/tui.ts";
+import { createTurnCommand } from "./commands/turn.ts";
+import { createWatchCommand } from "./commands/watch.ts";
 import { createWorktreeCommand } from "./commands/worktree.ts";
 import { setProjectRootOverride } from "./config.ts";
 import { isAgentplateError } from "./errors.ts";
@@ -96,6 +98,8 @@ function buildProgram(): Command {
 	// Orchestration
 	program.addCommand(createCoordinatorCommand());
 	program.addCommand(createSlingCommand());
+	program.addCommand(createTurnCommand());
+	program.addCommand(createWatchCommand());
 	program.addCommand(createSpecCommand());
 	program.addCommand(createStatusCommand());
 	program.addCommand(createMailCommand());

package/src/insights/quality-gates.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Tests for runQualityGates. Real subprocesses (no mocks) — gates are shell
+ * commands, so we use `true`/`false`/`sleep` to exercise pass/fail/partial and to
+ * prove the gates run concurrently (wall-clock < sum of durations).
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { QualityGate } from "../types.ts";
+import { runQualityGates } from "./quality-gates.ts";
+
+const gate = (name: string, command: string): QualityGate => ({ name, command });
+
+describe("runQualityGates", () => {
+	test("returns null when there are no gates", async () => {
+		expect(await runQualityGates([], process.cwd())).toBeNull();
+	});
+
+	test("all passing → success", async () => {
+		const out = await runQualityGates([gate("a", "true"), gate("b", "true")], process.cwd());
+		expect(out?.status).toBe("success");
+		expect(out?.results.every((r) => r.passed)).toBe(true);
+	});
+
+	test("all failing → failure", async () => {
+		const out = await runQualityGates([gate("a", "false"), gate("b", "false")], process.cwd());
+		expect(out?.status).toBe("failure");
+	});
+
+	test("mixed → partial", async () => {
+		const out = await runQualityGates([gate("ok", "true"), gate("bad", "false")], process.cwd());
+		expect(out?.status).toBe("partial");
+		// Order is preserved across the concurrent run.
+		expect(out?.results.map((r) => r.name)).toEqual(["ok", "bad"]);
+	});
+
+	test("gates run concurrently (wall-clock well under the sum)", async () => {
+		const gates = [gate("s1", "sleep 0.3"), gate("s2", "sleep 0.3"), gate("s3", "sleep 0.3")];
+		const out = await runQualityGates(gates, process.cwd());
+		expect(out?.status).toBe("success");
+		// Sequential would be ~900ms; concurrent should be well under that.
+		expect(out?.totalDurationMs ?? Number.POSITIVE_INFINITY).toBeLessThan(700);
+	});
+});

package/src/insights/quality-gates.ts

@@ -34,37 +34,36 @@ export async function runQualityGates(
 ): Promise<QualityGateOutcome | null> {
 	if (gates.length === 0) return null;
 
-	const results: GateResult[] = [];
-	let total = 0;
-	for (const gate of gates) {
-		const started = performance.now();
-		let exitCode = 1;
-		try {
-			// Run the gate through the platform shell: `cmd /c` on Windows (no bash
-			// there), `bash -lc` elsewhere. `.cmd` shims (biome/tsc) resolve under both.
-			const shellArgv =
-				process.platform === "win32"
-					? ["cmd", "/d", "/s", "/c", gate.command]
-					: ["bash", "-lc", gate.command];
-			const proc = Bun.spawn(shellArgv, {
-				cwd,
-				stdout: "pipe",
-				stderr: "pipe",
-			});
-			exitCode = await proc.exited;
-		} catch {
-			exitCode = 1;
-		}
-		const durationMs = Math.round(performance.now() - started);
-		total += durationMs;
-		results.push({
-			name: gate.name,
-			command: gate.command,
-			passed: exitCode === 0,
-			exitCode,
-			durationMs,
-		});
-	}
+	// Gates are independent checks, so run them concurrently and measure the
+	// outcome by wall-clock — `totalDurationMs` is the elapsed time of the whole
+	// batch (the slowest gate), not the sum of all gates.
+	const overallStart = performance.now();
+	const results: GateResult[] = await Promise.all(
+		gates.map(async (gate): Promise<GateResult> => {
+			const started = performance.now();
+			let exitCode = 1;
+			try {
+				// Run the gate through the platform shell: `cmd /c` on Windows (no bash
+				// there), `bash -lc` elsewhere. `.cmd` shims (biome/tsc) resolve under both.
+				const shellArgv =
+					process.platform === "win32"
+						? ["cmd", "/d", "/s", "/c", gate.command]
+						: ["bash", "-lc", gate.command];
+				const proc = Bun.spawn(shellArgv, { cwd, stdout: "pipe", stderr: "pipe" });
+				exitCode = await proc.exited;
+			} catch {
+				exitCode = 1;
+			}
+			return {
+				name: gate.name,
+				command: gate.command,
+				passed: exitCode === 0,
+				exitCode,
+				durationMs: Math.round(performance.now() - started),
+			};
+		}),
+	);
+	const total = Math.round(performance.now() - overallStart);
 
 	const passed = results.filter((r) => r.passed).length;
 	const status: OutcomeStatus =

package/src/merge/auto.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Tests for auto-merge (maybeAutoMerge).
+ *
+ * Real git repos in temp dirs (per "never mock what you can use for real"), the
+ * real merge queue + lock, and a recording mail stub so we can assert the outcome
+ * notifications without a mail DB. Covers the mode gate, the capability skip, the
+ * gates-pass fail-closed rule, a clean landing, and a reported conflict.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Capability, NewMail } from "../types.ts";
+import { type AutoMergeParams, maybeAutoMerge } from "./auto.ts";
+
+let repo: string;
+
+async function git(...args: string[]): Promise<string> {
+	const proc = Bun.spawn(["git", ...args], { cwd: repo, 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 Error(`git ${args.join(" ")} failed (${exitCode}): ${stderr}`);
+	return stdout;
+}
+
+/** Recording mail stub satisfying the `{ send }` surface maybeAutoMerge needs. */
+function recordingMail() {
+	const sent: Array<{ type: string; subject: string; to: string }> = [];
+	return {
+		sent,
+		send: (m: NewMail) => {
+			sent.push({ type: m.type, subject: m.subject, to: m.to });
+		},
+	};
+}
+
+/** Build params with sensible defaults; override per test. */
+function params(
+	over: Partial<AutoMergeParams> & { mail: ReturnType<typeof recordingMail> },
+): AutoMergeParams {
+	return {
+		root: repo,
+		branchName: "agentplate/builder-x",
+		targetBranch: "main",
+		capability: "builder" as Capability,
+		agentName: "builder-x",
+		taskId: "task-x",
+		parent: "lead-1",
+		mode: "on-complete",
+		aiResolveEnabled: true,
+		gateStatus: null,
+		...over,
+	};
+}
+
+beforeEach(async () => {
+	repo = mkdtempSync(join(tmpdir(), "agentplate-automerge-"));
+	mkdirSync(join(repo, ".agentplate"), { recursive: true });
+	await git("init", "-q");
+	await git("config", "user.email", "test@agentplate.dev");
+	await git("config", "user.name", "Agentplate Test");
+	await git("checkout", "-q", "-b", "main");
+	await Bun.write(join(repo, "base.txt"), "base\n");
+	await git("add", "-A");
+	await git("commit", "-q", "-m", "initial");
+});
+
+afterEach(() => {
+	rmSync(repo, { recursive: true, force: true });
+});
+
+/** Create a worker branch with a new-file commit, then return to main. */
+async function workerBranchWithCommit(branch: string, file: string): Promise<void> {
+	await git("checkout", "-q", "-b", branch);
+	await Bun.write(join(repo, file), "from worker\n");
+	await git("add", "-A");
+	await git("commit", "-q", "-m", `add ${file}`);
+	await git("checkout", "-q", "main");
+}
+
+describe("maybeAutoMerge — gating", () => {
+	test("mode 'off' never merges", async () => {
+		const mail = recordingMail();
+		await workerBranchWithCommit("agentplate/builder-x", "feature.txt");
+		const out = await maybeAutoMerge(params({ mail, mode: "off" }));
+		expect(out).toEqual({ merged: false, reason: "disabled" });
+		expect(existsSync(join(repo, "feature.txt"))).toBe(false);
+		expect(mail.sent).toHaveLength(0);
+	});
+
+	test("read-only capabilities are skipped", async () => {
+		const mail = recordingMail();
+		for (const capability of ["scout", "merger"] as Capability[]) {
+			const out = await maybeAutoMerge(params({ mail, capability }));
+			expect(out).toEqual({ merged: false, reason: "capability-skipped" });
+		}
+		expect(mail.sent).toHaveLength(0);
+	});
+
+	test("on-gates-pass holds (fail-closed) when gates did not pass", async () => {
+		const mail = recordingMail();
+		await workerBranchWithCommit("agentplate/builder-x", "feature.txt");
+		for (const gateStatus of [null, "failure", "partial"] as const) {
+			const out = await maybeAutoMerge(params({ mail, mode: "on-gates-pass", gateStatus }));
+			expect(out).toEqual({ merged: false, reason: "gates-not-passed" });
+		}
+		expect(existsSync(join(repo, "feature.txt"))).toBe(false);
+		expect(mail.sent.every((m) => m.type === "status")).toBe(true);
+	});
+});
+
+describe("maybeAutoMerge — landing", () => {
+	test("on-complete lands the branch and reports 'merged'", async () => {
+		const mail = recordingMail();
+		await workerBranchWithCommit("agentplate/builder-x", "feature.txt");
+		const out = await maybeAutoMerge(params({ mail, mode: "on-complete" }));
+		expect(out).toEqual({ merged: true, status: "merged", tier: "clean-merge" });
+		expect(existsSync(join(repo, "feature.txt"))).toBe(true); // landed on main
+		expect(mail.sent).toHaveLength(1);
+		expect(mail.sent[0]).toMatchObject({ type: "merged", to: "lead-1" });
+	});
+
+	test("on-gates-pass merges on a clean gate success", async () => {
+		const mail = recordingMail();
+		await workerBranchWithCommit("agentplate/builder-x", "feature.txt");
+		const out = await maybeAutoMerge(
+			params({ mail, mode: "on-gates-pass", gateStatus: "success" }),
+		);
+		expect(out).toMatchObject({ merged: true, status: "merged" });
+		expect(existsSync(join(repo, "feature.txt"))).toBe(true);
+	});
+
+	test("an unresolved conflict reports 'merge_failed' (never throws)", async () => {
+		const mail = recordingMail();
+		// Both branches edit base.txt differently -> conflict; aiResolveEnabled=false
+		// makes mergeBranch abort and fail.
+		await git("checkout", "-q", "-b", "agentplate/builder-x");
+		await Bun.write(join(repo, "base.txt"), "worker change\n");
+		await git("add", "-A");
+		await git("commit", "-q", "-m", "worker edits base");
+		await git("checkout", "-q", "main");
+		await Bun.write(join(repo, "base.txt"), "main change\n");
+		await git("add", "-A");
+		await git("commit", "-q", "-m", "main edits base");
+
+		const out = await maybeAutoMerge(
+			params({ mail, mode: "on-complete", aiResolveEnabled: false }),
+		);
+		expect(out.merged).toBe(false);
+		expect(out).toMatchObject({ reason: "merge-failed" });
+		expect(mail.sent[0]).toMatchObject({ type: "merge_failed" });
+	});
+});

package/src/merge/auto.ts

@@ -0,0 +1,118 @@
+/**
+ * Auto-merge: land a completed worker's branch onto the canonical branch without
+ * an operator running `agentplate merge`. Gated by `config.merge.autoMerge`:
+ *
+ *   off            → never (manual merge by the operator/coordinator)
+ *   on-gates-pass  → merge only when the task's quality gates passed cleanly
+ *   on-complete    → merge as soon as the agent finished without error
+ *
+ * This reuses the exact same path as the manual `merge` command — the merge queue
+ * (audit), the cross-process merge lock (so parallel auto-merges serialize), and
+ * {@link mergeBranch} (clean-merge / auto-resolve per `aiResolveEnabled`). Outcomes
+ * are reported to the parent/coordinator over mail (`merged` / `merge_failed`), so
+ * the existing coordination flow still sees every landing and handles conflicts.
+ *
+ * Pulled out of `sling` into its own unit so it can be tested against a real temp
+ * git repo without driving an agent turn.
+ */
+
+import { createMailClient } from "../mail/client.ts";
+import { mergeDbPath } from "../paths.ts";
+import type { AutoMergeMode, Capability, MergeStatus, MergeTier, OutcomeStatus } from "../types.ts";
+import { withMergeLock } from "./lock.ts";
+import { createMergeQueue } from "./queue.ts";
+import { mergeBranch } from "./resolver.ts";
+
+/** Capabilities that never produce a branch worth landing on the canonical branch. */
+const NON_MERGING_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>(["scout", "merger"]);
+
+export interface AutoMergeParams {
+	root: string;
+	branchName: string;
+	targetBranch: string;
+	capability: Capability;
+	agentName: string;
+	taskId: string;
+	/** Who to notify of the outcome (falls back to the coordinator). */
+	parent: string | null;
+	mode: AutoMergeMode;
+	/** Conflict strategy passed through to `mergeBranch`. */
+	aiResolveEnabled: boolean;
+	/** The task's quality-gate outcome, or null if gates did not run. */
+	gateStatus: OutcomeStatus | null;
+	/** Mail surface for reporting the outcome (injectable for tests). */
+	mail?: { send: (m: Parameters<ReturnType<typeof createMailClient>["send"]>[0]) => unknown };
+}
+
+export type AutoMergeOutcome =
+	| { merged: true; status: MergeStatus; tier: MergeTier | null }
+	| {
+			merged: false;
+			reason: "disabled" | "capability-skipped" | "gates-not-passed" | "merge-failed";
+			conflictFiles?: string[];
+	  };
+
+/**
+ * Decide whether to auto-merge `branchName` and, if so, do it under the merge lock.
+ * Never throws on a merge conflict — it reports `merge_failed` and returns a
+ * non-merged outcome so the spawn that called it is never failed by a landing.
+ */
+export async function maybeAutoMerge(params: AutoMergeParams): Promise<AutoMergeOutcome> {
+	const mail = params.mail ?? createMailClient(params.root);
+	const to = params.parent ?? "coordinator";
+
+	if (params.mode === "off") return { merged: false, reason: "disabled" };
+	if (NON_MERGING_CAPABILITIES.has(params.capability)) {
+		return { merged: false, reason: "capability-skipped" };
+	}
+	// Fail closed: on-gates-pass merges ONLY on a clean pass. A null status (gates
+	// not configured / not run) or any non-success holds the merge for a human.
+	if (params.mode === "on-gates-pass" && params.gateStatus !== "success") {
+		mail.send({
+			from: params.agentName,
+			to,
+			subject: `Auto-merge held: ${params.branchName}`,
+			body: `Quality gates did not pass (status: ${params.gateStatus ?? "not run"}); not merging. Review and merge manually.`,
+			type: "status",
+		});
+		return { merged: false, reason: "gates-not-passed" };
+	}
+
+	const queue = createMergeQueue(mergeDbPath(params.root));
+	try {
+		const entry = queue.enqueue({
+			branchName: params.branchName,
+			agentName: params.agentName,
+			taskId: params.taskId,
+			targetBranch: params.targetBranch,
+		});
+		const result = await withMergeLock(params.root, () =>
+			mergeBranch(params.root, params.branchName, params.targetBranch, {
+				autoResolve: params.aiResolveEnabled,
+			}),
+		);
+		queue.markStatus(entry.id, result.status);
+
+		if (result.status === "merged") {
+			mail.send({
+				from: params.agentName,
+				to,
+				subject: `Auto-merged: ${params.branchName} → ${params.targetBranch}`,
+				body: `Landed via ${result.tier ?? "merge"}.`,
+				type: "merged",
+			});
+			return { merged: true, status: result.status, tier: result.tier };
+		}
+
+		mail.send({
+			from: params.agentName,
+			to,
+			subject: `Auto-merge failed: ${params.branchName}`,
+			body: `Conflicts in: ${result.conflictFiles.join(", ") || "unknown"}. Merge manually.`,
+			type: "merge_failed",
+		});
+		return { merged: false, reason: "merge-failed", conflictFiles: result.conflictFiles };
+	} finally {
+		queue.close();
+	}
+}