@agentplate/cli 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to Agentplate are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project aims to adhere to
 [Semantic Versioning](https://semver.org/).
 
+## [1.3.0] — 2026-06-02
+
+### Added
+
+- **`agentplate watch`** — the mail pump that makes warm-start automatic: it
+  advances every **idle** agent with unread mail to its next (resumed) turn,
+  driving eligible agents concurrently up to `agents.maxConcurrent`. Modes:
+  `--once`, `--until-idle`, or loop until Ctrl-C.
+- **Hard per-turn timeout** (`agents.turnTimeoutMinutes`, 0 = off) — kills a turn
+  that runs past the cap even while still streaming (idle reaping only catches
+  inactivity).
+- **Per-capability runtime** — `runtime.capabilities[capability]` now selects the
+  runtime adapter per role (previously defined but unused).
+- **Speed shortcuts** — `agents.skipScout` / `skipReview` (surfaced as lead overlay
+  constraints) and `agents.skipGates` / `skipSkills` (honored on the turn path).
+- **Wizard** — a gated "advanced limits" step (concurrency, turn-timeout, skips).
+
+### Changed
+
+- The turn path is shared via `driveTurn` / `driveAgentTurn`, used by `sling`
+  (turn 1), `agentplate turn` (single follow-up), and `agentplate watch`.
+
+## [1.2.0] — 2026-06-02
+
+### Added
+
+- **Auto-merge** (`merge.autoMerge`: `off` / `on-gates-pass` / `on-complete`,
+  default `off`). When enabled, a completed worker's branch lands on the canonical
+  branch automatically (queue + lock + tiered resolve), reporting `merged` /
+  `merge_failed` mail. Configured in `ap setup`.
+- **`agentplate turn <agent>`** — runs the next turn for an idle agent, **resuming**
+  the runtime session (warm start) instead of cold-starting. The shared `driveTurn`
+  core backs both the first turn (`sling`) and follow-ups.
+- **Per-capability model tiering** — `providers[id].models` lets a faster/cheaper
+  model drive read-only roles (scout, reviewer) while the strong model handles the
+  rest. Optional prompt in `ap setup`.
+- **Quality-gates prompt in `ap setup`** — detected from `package.json` scripts.
+
+### Changed
+
+- **Quality gates run concurrently** (was sequential); the outcome is reused for
+  both skill distillation and auto-merge.
+- **Orchestration limits are now enforced.** `agents.maxConcurrent`,
+  `maxAgentsPerLead`, and `maxDepth` were validated but ignored; `sling` now
+  refuses a spawn that would exceed them with a typed `CapacityError`.
+
 ## [1.1.0] — 2026-06-02
 
 ### Added

package/agents/coordinator.md

@@ -90,6 +90,12 @@ Discipline when dispatching:
   if integration itself is non-trivial.
 - Re-dispatch on failure: if a lead escalates something it cannot finish, decide
   whether to re-scope and re-dispatch, or escalate to the operator.
+- Auto-merge (when `merge.autoMerge` is enabled in config): a worker's branch
+  lands on the canonical branch automatically when it finishes, and you receive a
+  `merged` or `merge_failed` mail per landing. You do **not** run `agentplate merge`
+  for those slices — just act on `merge_failed` (re-dispatch a merger or resolve),
+  and still own cross-slice integration. When auto-merge is `off` (the default),
+  you drive merges yourself as below.
 
 ## Communication Protocol
 

package/agents/lead.md

@@ -50,7 +50,9 @@ Discipline when delegating:
   merge — unless your overlay says `--skip-review`.
 - **Respect the budget.** Do not exceed your `max-agents` ceiling or the
   configured depth limit. You are an internal node; your children are leaves and
-  cannot spawn further.
+  cannot spawn further. These limits are now **enforced**: a `sling` that would
+  exceed `agents.maxConcurrent`, `agents.maxAgentsPerLead`, or `agents.maxDepth`
+  is refused with a capacity error — wait for a child to finish, then retry.
 
 ## Coordinating Children
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentplate/cli",
-	"version": "1.1.0",
+	"version": "1.3.0",
 	"publishConfig": {
 		"access": "public"
 	},

package/src/agents/capacity.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Tests for assertCapacity — the spawn-time orchestration limit gate.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { CapacityError } from "../errors.ts";
+import { assertCapacity, type CapacityCheck } from "./capacity.ts";
+
+const base: CapacityCheck = {
+	depth: 1,
+	active: 0,
+	parentAgent: "lead-1",
+	parentActiveChildren: 0,
+	limits: { maxDepth: 2, maxConcurrent: 10, maxAgentsPerLead: 5 },
+};
+
+describe("assertCapacity", () => {
+	test("passes when under every limit", () => {
+		expect(() => assertCapacity(base)).not.toThrow();
+	});
+
+	test("refuses when depth exceeds maxDepth", () => {
+		expect(() => assertCapacity({ ...base, depth: 3 })).toThrow(CapacityError);
+	});
+
+	test("allows depth exactly at maxDepth", () => {
+		expect(() => assertCapacity({ ...base, depth: 2 })).not.toThrow();
+	});
+
+	test("refuses when active is at maxConcurrent", () => {
+		expect(() => assertCapacity({ ...base, active: 10 })).toThrow(CapacityError);
+		// one below the cap is still allowed
+		expect(() => assertCapacity({ ...base, active: 9 })).not.toThrow();
+	});
+
+	test("refuses when the parent is at maxAgentsPerLead", () => {
+		expect(() => assertCapacity({ ...base, parentActiveChildren: 5 })).toThrow(CapacityError);
+	});
+
+	test("ignores the per-lead cap for a top-level spawn (no parent)", () => {
+		expect(() =>
+			assertCapacity({ ...base, parentAgent: null, parentActiveChildren: 99 }),
+		).not.toThrow();
+	});
+
+	test("the error is a CapacityError with the CAPACITY_EXCEEDED code", () => {
+		try {
+			assertCapacity({ ...base, active: 10 });
+			throw new Error("expected to throw");
+		} catch (e) {
+			expect(e).toBeInstanceOf(CapacityError);
+			expect((e as CapacityError).code).toBe("CAPACITY_EXCEEDED");
+		}
+	});
+});

package/src/agents/capacity.ts

@@ -0,0 +1,50 @@
+/**
+ * Orchestration capacity limits — enforced at spawn time.
+ *
+ * `agents.maxConcurrent`, `agents.maxAgentsPerLead`, and `agents.maxDepth` are
+ * configured (and validated) but were previously decorative — nothing consulted
+ * them. {@link assertCapacity} is the single gate `sling` calls before creating a
+ * worktree, so a runaway fan-out is refused with a typed {@link CapacityError}
+ * rather than spawning unbounded agents.
+ *
+ * Pure (counts are passed in) so it is unit-tested without a session store.
+ */
+
+import { CapacityError } from "../errors.ts";
+
+export interface CapacityLimits {
+	maxDepth: number;
+	maxConcurrent: number;
+	maxAgentsPerLead: number;
+}
+
+export interface CapacityCheck {
+	/** Depth the new agent would occupy. */
+	depth: number;
+	/** Active agents in the run right now (excluding the one being spawned). */
+	active: number;
+	/** Spawning parent, or null for a top-level spawn. */
+	parentAgent: string | null;
+	/** Active children the parent already has (ignored when parentAgent is null). */
+	parentActiveChildren: number;
+	limits: CapacityLimits;
+}
+
+/** Throw {@link CapacityError} if spawning would exceed any configured limit. */
+export function assertCapacity(c: CapacityCheck): void {
+	if (c.depth > c.limits.maxDepth) {
+		throw new CapacityError(
+			`Cannot spawn at depth ${c.depth}: exceeds agents.maxDepth (${c.limits.maxDepth}).`,
+		);
+	}
+	if (c.active >= c.limits.maxConcurrent) {
+		throw new CapacityError(
+			`Cannot spawn: ${c.active} agent(s) already active, at agents.maxConcurrent (${c.limits.maxConcurrent}). Wait for some to finish.`,
+		);
+	}
+	if (c.parentAgent && c.parentActiveChildren >= c.limits.maxAgentsPerLead) {
+		throw new CapacityError(
+			`Cannot spawn: ${c.parentAgent} already has ${c.parentActiveChildren} active child(ren), at agents.maxAgentsPerLead (${c.limits.maxAgentsPerLead}).`,
+		);
+	}
+}

package/src/agents/drive.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for driveTurn — the shared turn core. Real stores + a real (mock) runtime
+ * subprocess. A SpyRuntime records the DirectSpawnOpts so we can prove the warm
+ * start: a follow-up turn threads `resumeSessionId` through to the runtime.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_CONFIG } from "../config.ts";
+import { createEventStore, type EventStore } from "../events/store.ts";
+import { createMailClient, type MailClient } from "../mail/client.ts";
+import { eventsDbPath, sessionsDbPath } from "../paths.ts";
+import { MockRuntime } from "../runtimes/mock.ts";
+import type { DirectSpawnOpts } from "../runtimes/types.ts";
+import { createSessionStore, type SessionStore } from "../sessions/store.ts";
+import type { AgentplateConfig, AgentSession } from "../types.ts";
+import { driveTurn } from "./drive.ts";
+
+/** Mock runtime that records the spawn opts (so we can assert the resume id). */
+class SpyRuntime extends MockRuntime {
+	lastOpts: DirectSpawnOpts | null = null;
+	override buildDirectSpawn(opts: DirectSpawnOpts): string[] {
+		this.lastOpts = opts;
+		return super.buildDirectSpawn(opts);
+	}
+}
+
+let root: string;
+let worktree: string;
+let store: SessionStore;
+let events: EventStore;
+let mail: MailClient;
+
+function cfg(): AgentplateConfig {
+	const c = structuredClone(DEFAULT_CONFIG);
+	c.project.root = root;
+	c.project.canonicalBranch = "main";
+	return c;
+}
+
+function makeSession(over: Partial<AgentSession> = {}): AgentSession {
+	const now = new Date().toISOString();
+	return {
+		id: `session-${crypto.randomUUID()}`,
+		agentName: "builder-1",
+		capability: "builder",
+		taskId: "task-1",
+		runId: "run-1",
+		worktreePath: worktree,
+		branchName: "agentplate/builder-1",
+		state: "idle",
+		parentAgent: "lead-1",
+		depth: 1,
+		pid: null,
+		runtimeSessionId: null,
+		startedAt: now,
+		lastActivity: now,
+		...over,
+	};
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-drive-"));
+	mkdirSync(join(root, ".agentplate"), { recursive: true });
+	worktree = mkdtempSync(join(tmpdir(), "agentplate-drive-wt-"));
+	store = createSessionStore(sessionsDbPath(root));
+	events = createEventStore(eventsDbPath(root));
+	mail = createMailClient(root);
+	process.env.AGENTPLATE_MOCK_CMD = "true"; // no-op turn, exits 0
+});
+
+afterEach(() => {
+	store.close();
+	events.close();
+	mail.close();
+	rmSync(root, { recursive: true, force: true });
+	rmSync(worktree, { recursive: true, force: true });
+	process.env.AGENTPLATE_MOCK_CMD = undefined;
+});
+
+describe("driveTurn — warm start", () => {
+	test("threads resumeSessionId through to the runtime spawn (follow-up turn)", async () => {
+		const session = makeSession();
+		store.upsertSession(session);
+		const runtime = new SpyRuntime();
+
+		const out = await driveTurn({
+			root,
+			config: cfg(),
+			runtime,
+			store,
+			events,
+			mail,
+			session,
+			model: { model: "m", env: {} },
+			prompt: "continue",
+			resumeSessionId: "sess-abc",
+		});
+
+		expect(runtime.lastOpts?.resumeSessionId).toBe("sess-abc"); // warm start
+		expect(out.finalState).toBe("idle"); // no terminal mail emitted → paused
+		expect(store.getSession(session.id)?.state).toBe("idle");
+	});
+
+	test("omits resume on the first turn (cold start)", async () => {
+		const session = makeSession();
+		store.upsertSession(session);
+		const runtime = new SpyRuntime();
+		await driveTurn({
+			root,
+			config: cfg(),
+			runtime,
+			store,
+			events,
+			mail,
+			session,
+			model: { model: "m", env: {} },
+			prompt: "begin",
+		});
+		expect(runtime.lastOpts?.resumeSessionId).toBeUndefined();
+	});
+});
+
+describe("driveTurn — state transition", () => {
+	test("becomes 'completed' when the agent has emitted its terminal mail", async () => {
+		const session = makeSession();
+		store.upsertSession(session);
+		// The agent's own worker_done mail marks the task complete.
+		mail.send({
+			from: session.agentName,
+			to: "lead-1",
+			subject: "done",
+			body: "",
+			type: "worker_done",
+		});
+
+		const config = cfg();
+		config.skills.enabled = false; // keep the completed path free of distillation work
+		const out = await driveTurn({
+			root,
+			config,
+			runtime: new SpyRuntime(),
+			store,
+			events,
+			mail,
+			session,
+			model: { model: "m", env: {} },
+			prompt: "finish",
+		});
+		expect(out.finalState).toBe("completed");
+		expect(store.getSession(session.id)?.state).toBe("completed");
+	});
+});

package/src/agents/drive.ts

@@ -0,0 +1,270 @@
+/**
+ * driveTurn — run ONE headless turn for an agent and handle its aftermath.
+ *
+ * This is the shared core behind both the first turn (`sling`, which opens a
+ * fresh runtime session) and every follow-up turn (`agentplate turn`, which
+ * **resumes** the session via `runtimeSessionId` so turns 2+ do not pay the
+ * runtime's cold-start cost — the "warm start"). Keeping it in one place means
+ * the post-turn handling (state transition, the self-improving skills loop, and
+ * auto-merge) is identical no matter which turn it is.
+ *
+ * Spawn-per-turn is preserved: each call spawns a fresh runtime subprocess
+ * (resumed when `resumeSessionId` is given) — there is no long-lived agent.
+ */
+
+import { existsSync } from "node:fs";
+import type { EventStore } from "../events/store.ts";
+import { runQualityGates } from "../insights/quality-gates.ts";
+import type { MailClient } from "../mail/client.ts";
+import { createMailStore } from "../mail/store.ts";
+import { maybeAutoMerge } from "../merge/auto.ts";
+import { mailDbPath, manifestFilePath } from "../paths.ts";
+import { getRuntime, runtimeNameForCapability } from "../runtimes/registry.ts";
+import { resolveModel } from "../runtimes/resolve.ts";
+import type { AgentRuntime } from "../runtimes/types.ts";
+import type { SessionStore } from "../sessions/store.ts";
+import { runSkillFeedbackAndDistill } from "../skills/lifecycle.ts";
+import type {
+	AgentplateConfig,
+	AgentSession,
+	Capability,
+	OutcomeStatus,
+	ResolvedModel,
+	SessionState,
+} from "../types.ts";
+import { updateIdentity } from "./identity.ts";
+import { buildDefaultManifest, getDefinition, loadManifest } from "./manifest.ts";
+import { runTurn } from "./turn-runner.ts";
+
+/** Terminal mail types whose presence marks a capability's work complete. */
+export function terminalTypesFor(capability: Capability): string[] {
+	return capability === "merger" ? ["merged", "merge_failed"] : ["worker_done"];
+}
+
+/**
+ * Resolve a turn's end state from the agent's own mail + exit code:
+ * - emitted terminal mail → `completed`
+ * - clean exit, no terminal mail → `idle` (paused, awaiting its next turn)
+ * - non-zero exit → `failed`
+ */
+export function resolveFinalState(
+	root: string,
+	name: string,
+	capability: Capability,
+	exitCode: number,
+): SessionState {
+	const terminal = terminalTypesFor(capability);
+	const store = createMailStore(mailDbPath(root));
+	try {
+		const sent = store.list({ from: name });
+		if (sent.some((m) => terminal.includes(m.type))) return "completed";
+	} finally {
+		store.close();
+	}
+	return exitCode === 0 ? "idle" : "failed";
+}
+
+export interface DriveTurnCtx {
+	root: string;
+	config: AgentplateConfig;
+	runtime: AgentRuntime;
+	store: SessionStore;
+	events: EventStore;
+	mail: MailClient;
+	/** The session this turn runs for (existing or just-created). */
+	session: AgentSession;
+	/** Resolved concrete model + provider env for this capability. */
+	model: ResolvedModel;
+	/** The user-turn text (dispatch / injected mail / nudge). */
+	prompt: string;
+	/** Prior runtime session id to resume — omit on the first turn (warm start). */
+	resumeSessionId?: string;
+}
+
+export interface DriveTurnResult {
+	finalState: SessionState;
+	exitCode: number;
+	gateStatus: OutcomeStatus | null;
+}
+
+/** Run one turn for `ctx.session` and apply the post-turn lifecycle. */
+export async function driveTurn(ctx: DriveTurnCtx): Promise<DriveTurnResult> {
+	const { root, config, runtime, store, events, mail, session, model } = ctx;
+	const {
+		id: sessionId,
+		agentName: name,
+		capability,
+		taskId,
+		runId,
+		worktreePath,
+		branchName,
+	} = session;
+
+	store.updateSessionState(sessionId, "working");
+
+	let sawError = false;
+	const turn = await runTurn({
+		runtime,
+		worktreePath,
+		model: model.model,
+		prompt: ctx.prompt,
+		env: model.env,
+		resumeSessionId: ctx.resumeSessionId,
+		timeoutMs:
+			config.agents.turnTimeoutMinutes > 0 ? config.agents.turnTimeoutMinutes * 60_000 : undefined,
+		onEvent: (event) => {
+			if (event.error || event.type === "error") sawError = true;
+			// Prefer the error message (so a failed agent's reason is visible in the
+			// feed/logs), else the token/cost JSON the Costs page aggregates.
+			const detail = event.error
+				? event.error
+				: event.usage
+					? JSON.stringify({ tokens: event.usage.tokens, cost: event.usage.costUsd })
+					: null;
+			events.record({ agentName: name, runId, type: event.type, tool: event.tool ?? null, detail });
+			// Bump last_activity on every streamed event so a long but active turn
+			// keeps itself fresh and is never reaped as "idle".
+			store.touch(sessionId);
+		},
+	});
+	if (turn.runtimeSessionId) store.setRuntimeSessionId(sessionId, turn.runtimeSessionId);
+
+	// Record a clear reason when the wall-clock cap killed the turn.
+	if (turn.timedOut) {
+		events.record({
+			agentName: name,
+			runId,
+			type: "error",
+			tool: null,
+			detail: `Turn killed: exceeded agents.turnTimeoutMinutes (${config.agents.turnTimeoutMinutes}m).`,
+		});
+	}
+
+	// A non-zero exit with no error event means the runtime failed via stderr;
+	// record it so the failure reason is visible instead of a blank "failed".
+	if (turn.exitCode !== 0 && !sawError) {
+		const reason = turn.stderr.trim();
+		if (reason) {
+			events.record({
+				agentName: name,
+				runId,
+				type: "error",
+				tool: null,
+				detail: reason.length > 1000 ? `${reason.slice(0, 1000)}…` : reason,
+			});
+		}
+	}
+
+	const finalState = resolveFinalState(root, name, capability, turn.exitCode);
+	store.updateSessionState(sessionId, finalState);
+	store.touch(sessionId);
+	updateIdentity(root, name, {
+		taskId,
+		summary: `${capability} ran a turn for ${taskId} → ${finalState}`,
+	});
+
+	// Quality gates run once when EITHER the self-improving loop or auto-merge
+	// needs them (and gates aren't skipped); the outcome feeds both. Best-effort.
+	const runSkills = config.skills.enabled && !config.agents.skipSkills;
+	const autoMergeWants =
+		config.merge.autoMerge !== "off" && capability !== "scout" && capability !== "merger";
+	const wantGates = !config.agents.skipGates && (runSkills || autoMergeWants);
+	let gateStatus: OutcomeStatus | null = null;
+	if (finalState === "completed" && (wantGates || runSkills)) {
+		try {
+			if (wantGates) {
+				const gateOutcome = await runQualityGates(config.project.qualityGates ?? [], worktreePath);
+				gateStatus = gateOutcome?.status ?? null;
+			}
+			if (runSkills) {
+				await runSkillFeedbackAndDistill({
+					root,
+					agentName: name,
+					capability,
+					taskId,
+					worktreePath,
+					baseRef: config.project.canonicalBranch,
+					runtime,
+					outcomeStatus: gateStatus,
+					skills: config.skills,
+					model: model.model,
+				});
+			}
+		} catch {
+			// Skill loop is advisory; a failure here must not fail the turn.
+		}
+	}
+
+	// Auto-merge the branch onto the canonical branch when configured (off by
+	// default). Best-effort — a landing must never fail the turn.
+	if (finalState === "completed") {
+		try {
+			await maybeAutoMerge({
+				root,
+				branchName,
+				targetBranch: config.project.canonicalBranch,
+				capability,
+				agentName: name,
+				taskId,
+				parent: session.parentAgent,
+				mode: config.merge.autoMerge,
+				aiResolveEnabled: config.merge.aiResolveEnabled,
+				gateStatus,
+				mail,
+			});
+		} catch {
+			// Auto-merge is best-effort; never fail the turn over a landing.
+		}
+	}
+
+	return { finalState, exitCode: turn.exitCode, gateStatus };
+}
+
+export interface DriveAgentTurnCtx {
+	root: string;
+	config: AgentplateConfig;
+	session: AgentSession;
+	store: SessionStore;
+	events: EventStore;
+	mail: MailClient;
+}
+
+/**
+ * Run the next (resumed) turn for an existing session: resolve its runtime + model
+ * + manifest def, inject its unread mail as the prompt, and {@link driveTurn} with
+ * the stored `runtimeSessionId` (warm start). Shared by `agentplate turn` (single)
+ * and `agentplate watch` (the mail pump). Assumes the caller has already decided
+ * the session is drivable.
+ */
+export async function driveAgentTurn(ctx: DriveAgentTurnCtx): Promise<DriveTurnResult> {
+	const { root, config, session } = ctx;
+	const manifestPath = manifestFilePath(root);
+	const manifest = existsSync(manifestPath) ? loadManifest(manifestPath) : buildDefaultManifest();
+	const def = getDefinition(manifest, session.capability);
+	const runtime = getRuntime(
+		runtimeNameForCapability(config.runtime, session.capability),
+		config.runtime.default,
+	);
+	const model = resolveModel(config, root, def.model, session.capability);
+
+	// The turn's user text is the agent's unread mail (a child's reply / operator
+	// direction); fall back to a continue nudge. checkInject marks it read.
+	const injected = ctx.mail.checkInject(session.agentName);
+	const prompt =
+		injected.trim().length > 0
+			? injected
+			: "Continue your task. If it is complete, send your terminal mail.";
+
+	return driveTurn({
+		root,
+		config,
+		runtime,
+		store: ctx.store,
+		events: ctx.events,
+		mail: ctx.mail,
+		session,
+		model,
+		prompt,
+		resumeSessionId: session.runtimeSessionId ?? undefined,
+	});
+}

package/src/agents/turn-runner.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Tests for runTurn — focused on the hard wall-clock cap. Real subprocesses via
+ * the mock runtime (a `bash -lc` snippet), so we exercise true kill behavior.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MockRuntime } from "../runtimes/mock.ts";
+import { runTurn } from "./turn-runner.ts";
+
+let cwd: string;
+const runtime = new MockRuntime();
+
+beforeEach(() => {
+	cwd = mkdtempSync(join(tmpdir(), "agentplate-turnrunner-"));
+});
+afterEach(() => {
+	rmSync(cwd, { recursive: true, force: true });
+	process.env.AGENTPLATE_MOCK_CMD = undefined;
+});
+
+describe("runTurn — turn timeout", () => {
+	test("kills a turn that exceeds timeoutMs and flags timedOut", async () => {
+		process.env.AGENTPLATE_MOCK_CMD = "sleep 10"; // would hang well past the cap
+		const started = performance.now();
+		const result = await runTurn({
+			runtime,
+			worktreePath: cwd,
+			model: "m",
+			prompt: "",
+			timeoutMs: 200,
+		});
+		const elapsed = performance.now() - started;
+
+		expect(result.timedOut).toBe(true);
+		expect(result.exitCode).not.toBe(0); // killed → non-zero
+		expect(elapsed).toBeLessThan(3000); // resolved at the cap, not after 10s
+	});
+
+	test("does not flag timedOut when the turn finishes within the cap", async () => {
+		process.env.AGENTPLATE_MOCK_CMD = "true"; // instant exit 0
+		const result = await runTurn({
+			runtime,
+			worktreePath: cwd,
+			model: "m",
+			prompt: "",
+			timeoutMs: 5000,
+		});
+		expect(result.timedOut).toBe(false);
+		expect(result.exitCode).toBe(0);
+	});
+
+	test("no cap when timeoutMs is omitted/zero", async () => {
+		process.env.AGENTPLATE_MOCK_CMD = "true";
+		const result = await runTurn({
+			runtime,
+			worktreePath: cwd,
+			model: "m",
+			prompt: "",
+			timeoutMs: 0,
+		});
+		expect(result.timedOut).toBe(false);
+		expect(result.exitCode).toBe(0);
+	});
+});