@agentplate/cli 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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

package/package.json

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

package/src/agents/drive.ts

@@ -12,12 +12,15 @@
  * (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 } from "../paths.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";
@@ -30,6 +33,7 @@ import type {
 	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. */
@@ -106,6 +110,8 @@ export async function driveTurn(ctx: DriveTurnCtx): Promise<DriveTurnResult> {
 		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
@@ -123,6 +129,17 @@ export async function driveTurn(ctx: DriveTurnCtx): Promise<DriveTurnResult> {
 	});
 	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) {
@@ -147,15 +164,19 @@ export async function driveTurn(ctx: DriveTurnCtx): Promise<DriveTurnResult> {
 	});
 
 	// Quality gates run once when EITHER the self-improving loop or auto-merge
-	// needs them; the outcome feeds both. Best-effort — never fails the turn.
+	// 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" && (config.skills.enabled || autoMergeWants)) {
+	if (finalState === "completed" && (wantGates || runSkills)) {
 		try {
-			const gateOutcome = await runQualityGates(config.project.qualityGates ?? [], worktreePath);
-			gateStatus = gateOutcome?.status ?? null;
-			if (config.skills.enabled) {
+			if (wantGates) {
+				const gateOutcome = await runQualityGates(config.project.qualityGates ?? [], worktreePath);
+				gateStatus = gateOutcome?.status ?? null;
+			}
+			if (runSkills) {
 				await runSkillFeedbackAndDistill({
 					root,
 					agentName: name,
@@ -198,3 +219,52 @@ export async function driveTurn(ctx: DriveTurnCtx): Promise<DriveTurnResult> {
 
 	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);
+	});
+});

package/src/agents/turn-runner.ts

@@ -23,6 +23,8 @@ export interface RunTurnOptions {
 	env?: Record<string, string>;
 	/** Prior runtime session id, to resume across turns. */
 	resumeSessionId?: string;
+	/** Hard wall-clock cap in ms; the child is killed past it. 0/undefined = none. */
+	timeoutMs?: number;
 	/** Called for each parsed event (e.g. to record tool calls). */
 	onEvent?: (event: AgentEvent) => void;
 }
@@ -33,6 +35,8 @@ export interface TurnResult {
 	runtimeSessionId: string | null;
 	/** Captured stderr (already bounded by the child). */
 	stderr: string;
+	/** True if the turn was killed by the wall-clock cap. */
+	timedOut: boolean;
 }
 
 /** Run a single headless turn and resolve when the child process exits. */
@@ -59,6 +63,18 @@ export async function runTurn(opts: RunTurnOptions): Promise<TurnResult> {
 		stdin: "ignore",
 	});
 
+	// Hard wall-clock cap: kill a turn that runs past the limit even if it keeps
+	// streaming (idle reaping only catches inactivity). Closing the child's pipes
+	// ends the drain/parse loops below, so the turn resolves with a non-zero exit.
+	let timedOut = false;
+	const timer =
+		opts.timeoutMs && opts.timeoutMs > 0
+			? setTimeout(() => {
+					timedOut = true;
+					proc.kill(); // SIGTERM
+				}, opts.timeoutMs)
+			: null;
+
 	// Read stderr concurrently so a full pipe buffer can't deadlock the child.
 	const stderrPromise = new Response(proc.stderr).text();
 
@@ -75,5 +91,6 @@ export async function runTurn(opts: RunTurnOptions): Promise<TurnResult> {
 
 	const stderr = await stderrPromise;
 	const exitCode = await proc.exited;
-	return { exitCode, runtimeSessionId, stderr };
+	if (timer) clearTimeout(timer);
+	return { exitCode, runtimeSessionId, stderr, timedOut };
 }

package/src/commands/sling.ts

@@ -31,7 +31,7 @@ import {
 	packageAgentDefPath,
 	sessionsDbPath,
 } from "../paths.ts";
-import { getRuntime } from "../runtimes/registry.ts";
+import { getRuntime, runtimeNameForCapability } from "../runtimes/registry.ts";
 import { resolveModel } from "../runtimes/resolve.ts";
 import { createSessionStore } from "../sessions/store.ts";
 import { retrieveSkillsForSpawn } from "../skills/lifecycle.ts";
@@ -159,7 +159,18 @@ export function createSlingCommand(): Command {
 				});
 
 				// 3. Overlay (base definition + assignment + skills) → instruction file.
-				const runtime = getRuntime(opts.runtime ?? config.runtime.default, config.runtime.default);
+				const runtime = getRuntime(
+					runtimeNameForCapability(config.runtime, capability, opts.runtime),
+					config.runtime.default,
+				);
+				// Surface project skip-defaults as constraints the spawning agent obeys.
+				const skipDirectives: string[] = [];
+				if (def.canSpawn && config.agents.skipScout) {
+					skipDirectives.push("Skip the scout step — dispatch builders directly (--skip-scout).");
+				}
+				if (def.canSpawn && config.agents.skipReview) {
+					skipDirectives.push("Skip the reviewer step before integrating (--skip-review).");
+				}
 				const overlayConfig: OverlayConfig = {
 					agentName: name,
 					capability,
@@ -173,7 +184,7 @@ export function createSlingCommand(): Command {
 					baseDefinition: readBaseDefinition(root, def.file),
 					canSpawn: def.canSpawn,
 					qualityGates: config.project.qualityGates ?? [],
-					constraints: def.constraints,
+					constraints: [...def.constraints, ...skipDirectives],
 					siblings: opts.siblings ? opts.siblings.split(",").map((s) => s.trim()) : undefined,
 					skillsOverlay: skillsOverlay || undefined,
 				};

package/src/commands/turn.ts

@@ -12,19 +12,15 @@
  * call is one fresh, resumed runtime subprocess.
  */
 
-import { existsSync } from "node:fs";
 import { Command } from "commander";
-import { driveTurn } from "../agents/drive.ts";
-import { buildDefaultManifest, getDefinition, loadManifest } from "../agents/manifest.ts";
+import { driveAgentTurn } from "../agents/drive.ts";
 import { findProjectRoot, isInitialized, loadConfig } from "../config.ts";
 import { NotFoundError, ValidationError } from "../errors.ts";
 import { createEventStore } from "../events/store.ts";
 import { jsonOutput } from "../json.ts";
 import { brand, muted, printInfo, printSuccess } from "../logging/color.ts";
 import { createMailClient } from "../mail/client.ts";
-import { eventsDbPath, manifestFilePath, sessionsDbPath } from "../paths.ts";
-import { getRuntime } from "../runtimes/registry.ts";
-import { resolveModel } from "../runtimes/resolve.ts";
+import { eventsDbPath, sessionsDbPath } from "../paths.ts";
 import { createSessionStore } from "../sessions/store.ts";
 import type { SessionState } from "../types.ts";
 
@@ -60,34 +56,13 @@ export function createTurnCommand(): Command {
 					);
 				}
 
-				const manifestPath = manifestFilePath(root);
-				const manifest = existsSync(manifestPath)
-					? loadManifest(manifestPath)
-					: buildDefaultManifest();
-				const def = getDefinition(manifest, session.capability);
-				const runtime = getRuntime(config.runtime.default, config.runtime.default);
-				const model = resolveModel(config, root, def.model, session.capability);
-
-				// The next turn's user text is the agent's unread mail (e.g. a child's
-				// reply or operator direction); fall back to a continue nudge.
-				const injected = mail.checkInject(agent);
-				const prompt =
-					injected.trim().length > 0
-						? injected
-						: "Continue your task. If it is complete, send your terminal mail.";
-
-				const { finalState, exitCode } = await driveTurn({
+				const { finalState, exitCode } = await driveAgentTurn({
 					root,
 					config,
-					runtime,
+					session,
 					store,
 					events,
 					mail,
-					session,
-					model,
-					prompt,
-					// Warm start: resume the runtime session captured on a prior turn.
-					resumeSessionId: session.runtimeSessionId ?? undefined,
 				});
 
 				if (useJson) {

package/src/commands/watch.test.ts

@@ -0,0 +1,136 @@
+/**
+ * `agentplate watch` tests. Real initialized temp project + real (mock) turns,
+ * driven deterministically via `--once`. Asserts which idle agents get advanced.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	AGENTPLATE_DIR,
+	CONFIG_FILE,
+	DEFAULT_CONFIG,
+	serializeConfig,
+	setProjectRootOverride,
+} from "../config.ts";
+import { createMailClient } from "../mail/client.ts";
+import { sessionsDbPath } from "../paths.ts";
+import { createSessionStore } from "../sessions/store.ts";
+import type { AgentSession } from "../types.ts";
+import { createWatchCommand } from "./watch.ts";
+
+let root: string;
+let worktree: string;
+
+function seedSession(over: Partial<AgentSession>): void {
+	const store = createSessionStore(sessionsDbPath(root));
+	const now = new Date().toISOString();
+	try {
+		store.upsertSession({
+			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: "sess-prior",
+			startedAt: now,
+			lastActivity: now,
+			...over,
+		});
+	} finally {
+		store.close();
+	}
+}
+
+function sendMailTo(agent: string): void {
+	const mail = createMailClient(root);
+	try {
+		mail.send({ from: "lead-1", to: agent, subject: "ping", body: "continue", type: "status" });
+	} finally {
+		mail.close();
+	}
+}
+
+/** Run `watch --once --json` and return the parsed summary. */
+async function watchOnce(): Promise<{ driven: number; turns: Array<{ agent: string }> }> {
+	const original = process.stdout.write.bind(process.stdout);
+	let out = "";
+	process.stdout.write = (chunk: string | Uint8Array): boolean => {
+		out += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+		return true;
+	};
+	try {
+		await createWatchCommand().parseAsync(["--once", "--json"], { from: "user" });
+	} finally {
+		process.stdout.write = original;
+	}
+	// jsonOutput wraps the payload in the standard { ok, data } envelope.
+	return JSON.parse(out.trim()).data;
+}
+
+beforeEach(() => {
+	root = mkdtempSync(join(tmpdir(), "agentplate-watch-"));
+	worktree = mkdtempSync(join(tmpdir(), "agentplate-watch-wt-"));
+	mkdirSync(join(root, AGENTPLATE_DIR), { recursive: true });
+	const config = structuredClone(DEFAULT_CONFIG);
+	config.runtime.default = "mock";
+	writeFileSync(join(root, AGENTPLATE_DIR, CONFIG_FILE), serializeConfig(config), "utf8");
+	setProjectRootOverride(root);
+	process.env.AGENTPLATE_MOCK_CMD = "true";
+});
+
+afterEach(() => {
+	setProjectRootOverride(null);
+	rmSync(root, { recursive: true, force: true });
+	rmSync(worktree, { recursive: true, force: true });
+	process.env.AGENTPLATE_MOCK_CMD = undefined;
+});
+
+describe("agentplate watch --once", () => {
+	test("drives an idle agent that has unread mail", async () => {
+		seedSession({ agentName: "builder-1", state: "idle" });
+		sendMailTo("builder-1");
+		const out = await watchOnce();
+		expect(out.driven).toBe(1);
+		expect(out.turns[0]?.agent).toBe("builder-1");
+	});
+
+	test("skips an idle agent with no unread mail", async () => {
+		seedSession({ agentName: "builder-1", state: "idle" });
+		const out = await watchOnce();
+		expect(out.driven).toBe(0);
+	});
+
+	test("never drives a terminal agent, even with mail", async () => {
+		seedSession({ agentName: "builder-1", state: "completed" });
+		sendMailTo("builder-1");
+		const out = await watchOnce();
+		expect(out.driven).toBe(0);
+	});
+
+	test("drives only the idle-with-mail agents in a mixed fleet", async () => {
+		seedSession({ agentName: "has-mail", state: "idle" });
+		seedSession({ agentName: "no-mail", state: "idle" });
+		sendMailTo("has-mail");
+		const out = await watchOnce();
+		expect(out.driven).toBe(1);
+		expect(out.turns.map((t) => t.agent)).toEqual(["has-mail"]);
+	});
+
+	test("drives multiple idle-with-mail agents in one pass (concurrent)", async () => {
+		for (const a of ["a1", "a2", "a3"]) {
+			seedSession({ agentName: a, state: "idle" });
+			sendMailTo(a);
+		}
+		const out = await watchOnce();
+		expect(out.driven).toBe(3);
+		expect(out.turns.map((t) => t.agent).sort()).toEqual(["a1", "a2", "a3"]);
+	});
+});

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

@@ -92,6 +92,20 @@ describe("validateConfig", () => {
 		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

@@ -43,6 +43,11 @@ export const DEFAULT_CONFIG: AgentplateConfig = {
 		maxDepth: 2,
 		maxAgentsPerLead: 5,
 		idleTimeoutMinutes: 10,
+		turnTimeoutMinutes: 0,
+		skipScout: false,
+		skipReview: false,
+		skipGates: false,
+		skipSkills: false,
 	},
 	merge: {
 		aiResolveEnabled: true,
@@ -176,6 +181,11 @@ 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/index.ts

@@ -35,6 +35,7 @@ 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";
@@ -98,6 +99,7 @@ function buildProgram(): Command {
 	program.addCommand(createCoordinatorCommand());
 	program.addCommand(createSlingCommand());
 	program.addCommand(createTurnCommand());
+	program.addCommand(createWatchCommand());
 	program.addCommand(createSpecCommand());
 	program.addCommand(createStatusCommand());
 	program.addCommand(createMailCommand());

package/src/runtimes/registry.test.ts

@@ -1,15 +1,29 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { ValidationError } from "../errors.ts";
-import type { ResolvedModel } from "../types.ts";
+import type { ResolvedModel, RuntimeConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CursorRuntime } from "./cursor.ts";
 import { GeminiRuntime } from "./gemini.ts";
 import { MockRuntime } from "./mock.ts";
 import { OpenCodeRuntime, opencodeModel } from "./opencode.ts";
-import { getRuntime, getRuntimeNames } from "./registry.ts";
+import { getRuntime, getRuntimeNames, runtimeNameForCapability } from "./registry.ts";
 import type { AgentEvent, DirectSpawnOpts } from "./types.ts";
 
+describe("runtimeNameForCapability", () => {
+	const rt: RuntimeConfig = { default: "claude", capabilities: { scout: "codex" } };
+	test("explicit override wins over everything", () => {
+		expect(runtimeNameForCapability(rt, "scout", "gemini")).toBe("gemini");
+	});
+	test("per-capability override applies when set", () => {
+		expect(runtimeNameForCapability(rt, "scout")).toBe("codex");
+	});
+	test("falls back to the default runtime", () => {
+		expect(runtimeNameForCapability(rt, "builder")).toBe("claude");
+		expect(runtimeNameForCapability({ default: "opencode" }, "scout")).toBe("opencode");
+	});
+});
+
 // Minimal DirectSpawnOpts builder for argv-shape assertions. `cwd` and
 // `instructionPath` are required by the type but irrelevant to argv here.
 function spawnOpts(overrides: Partial<DirectSpawnOpts> = {}): DirectSpawnOpts {

package/src/runtimes/registry.ts

@@ -8,6 +8,7 @@
  */
 
 import { ValidationError } from "../errors.ts";
+import type { Capability, RuntimeConfig } from "../types.ts";
 import { ClaudeRuntime } from "./claude.ts";
 import { CodexRuntime } from "./codex.ts";
 import { CursorRuntime } from "./cursor.ts";
@@ -54,6 +55,18 @@ export function getRuntime(name?: string, fallback?: string): AgentRuntime {
 	return factory();
 }
 
+/**
+ * Resolve which runtime adapter drives a given capability: an explicit `override`
+ * wins, then a per-capability entry in `runtime.capabilities`, then the default.
+ */
+export function runtimeNameForCapability(
+	runtime: RuntimeConfig,
+	capability: Capability,
+	override?: string,
+): string {
+	return override ?? runtime.capabilities?.[capability] ?? runtime.default;
+}
+
 /**
  * Names of all registered runtimes, in registration order. Used to validate a
  * user-supplied runtime name and to render the choices in help / errors.

package/src/types.ts

@@ -153,6 +153,20 @@ export interface AgentsConfig {
 	 * `0` disables idle reaping. Default 10.
 	 */
 	idleTimeoutMinutes: number;
+	/**
+	 * Hard wall-clock cap on a SINGLE turn, in minutes. Unlike idle reaping (which
+	 * needs inactivity), this kills a turn that keeps streaming but never finishes.
+	 * `0` disables the cap. Default 0.
+	 */
+	turnTimeoutMinutes: number;
+	/** Default: leads skip the scout step (go straight to builders). */
+	skipScout: boolean;
+	/** Default: leads skip the reviewer step before integrating. */
+	skipReview: boolean;
+	/** Skip the post-turn quality-gate run (speed; disables `on-gates-pass` merge). */
+	skipGates: boolean;
+	/** Skip the post-turn skill-distillation loop. */
+	skipSkills: boolean;
 }
 
 /**

package/src/version.ts

@@ -4,4 +4,4 @@
  * Kept as a plain constant (not read from package.json at runtime) so the value
  * is available without filesystem access and survives bundling.
  */
-export const VERSION = "1.2.0";
+export const VERSION = "1.3.0";

package/src/wizard/setup.ts

@@ -321,6 +321,71 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 		);
 	}
 
+	// 6b. Advanced limits — gated so the common path stays short.
+	const agents = { ...currentConfig.agents };
+	const tuneAdvanced = ensure(
+		await p.confirm({
+			message: "Tune advanced limits (concurrency, timeouts, skip steps)?",
+			initialValue: false,
+		}),
+	);
+	if (tuneAdvanced) {
+		const posInt = (v: string | undefined): string | undefined =>
+			v && Number.isInteger(Number(v)) && Number(v) >= 0 ? undefined : "Enter a whole number ≥ 0";
+		agents.maxConcurrent = Number(
+			ensure(
+				await p.text({
+					message: "Max agents running at once",
+					initialValue: String(agents.maxConcurrent),
+					validate: (v) => (v && Number(v) >= 1 ? undefined : "Enter a number ≥ 1"),
+				}),
+			),
+		);
+		agents.maxAgentsPerLead = Number(
+			ensure(
+				await p.text({
+					message: "Max workers per lead",
+					initialValue: String(agents.maxAgentsPerLead),
+					validate: (v) => (v && Number(v) >= 1 ? undefined : "Enter a number ≥ 1"),
+				}),
+			),
+		);
+		agents.turnTimeoutMinutes = Number(
+			ensure(
+				await p.text({
+					message: "Per-turn timeout in minutes (0 = no cap)",
+					initialValue: String(agents.turnTimeoutMinutes),
+					validate: posInt,
+				}),
+			),
+		);
+		const skips = ensure(
+			await p.multiselect({
+				message: "Default speed shortcuts (leave empty for none)",
+				options: [
+					{
+						value: "skipScout",
+						label: "Skip scout step",
+						hint: "leads dispatch builders directly",
+					},
+					{ value: "skipReview", label: "Skip review step", hint: "no reviewer before integrate" },
+					{
+						value: "skipGates",
+						label: "Skip quality gates",
+						hint: "faster; disables on-gates-pass merge",
+					},
+					{ value: "skipSkills", label: "Skip skill distillation" },
+				],
+				initialValues: [],
+				required: false,
+			}),
+		) as string[];
+		agents.skipScout = skips.includes("skipScout");
+		agents.skipReview = skips.includes("skipReview");
+		agents.skipGates = skips.includes("skipGates");
+		agents.skipSkills = skips.includes("skipSkills");
+	}
+
 	// 7. Summary -----------------------------------------------------------
 	const previewProvider = buildProviderConfig(spec, model, authMode, baseUrl);
 	const authSummary: Record<AuthMode, string> = {
@@ -356,6 +421,7 @@ export async function runSetupWizard(currentConfig: AgentplateConfig): Promise<W
 		runtime,
 	});
 	config.merge = { ...config.merge, autoMerge };
+	config.agents = agents;
 	if (qualityGates.length) config.project = { ...config.project, qualityGates };
 	if (modelsByCapability) {
 		const pc = config.providers[providerId];