@agentplate/cli 1.0.0

package/src/agents/overlay.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import type { OverlayConfig } from "../types.ts";
+import { generateOverlay, writeOverlay } from "./overlay.ts";
+
+/**
+ * Build a fully-populated OverlayConfig, allowing per-test overrides. Defaults
+ * exercise the "rich" path (non-empty lists, siblings, spawner); individual
+ * tests narrow to the empty/leaf cases as needed.
+ */
+function makeConfig(overrides: Partial<OverlayConfig> = {}): OverlayConfig {
+	return {
+		agentName: "builder-alpha",
+		capability: "builder",
+		taskId: "task-123",
+		specPath: ".agentplate/specs/task-123.md",
+		branchName: "agent/builder-alpha/task-123",
+		worktreePath: "/repo/.agentplate/worktrees/builder-alpha",
+		parentAgent: "lead-one",
+		depth: 1,
+		fileScope: ["src/foo.ts", "src/foo.test.ts"],
+		baseDefinition: "# Builder\nYou implement features. UNIQUE_BASE_MARKER.",
+		canSpawn: false,
+		qualityGates: [
+			{ name: "test", command: "bun test", description: "all tests pass" },
+			{ name: "lint", command: "biome check .", description: "lint clean" },
+		],
+		constraints: ["Only touch your file scope", "Never push to main"],
+		siblings: ["builder-beta", "builder-gamma"],
+		...overrides,
+	};
+}
+
+describe("generateOverlay", () => {
+	test("substitutes every placeholder (no unresolved tokens remain)", () => {
+		const out = generateOverlay(makeConfig());
+		// The single most important invariant: nothing left to substitute.
+		expect(out).not.toContain("{{");
+		expect(out).not.toContain("}}");
+	});
+
+	test("injects core assignment values", () => {
+		const out = generateOverlay(makeConfig());
+		expect(out).toContain("builder-alpha");
+		expect(out).toContain("task-123");
+		expect(out).toContain("builder"); // capability
+		expect(out).toContain("agent/builder-alpha/task-123"); // branch
+		expect(out).toContain("/repo/.agentplate/worktrees/builder-alpha"); // worktree
+		expect(out).toContain("lead-one"); // parent
+		expect(out).toContain(".agentplate/specs/task-123.md"); // spec
+	});
+
+	test("embeds the base definition verbatim", () => {
+		const out = generateOverlay(makeConfig());
+		expect(out).toContain("UNIQUE_BASE_MARKER");
+	});
+
+	test("renders file scope and constraints as bullet lists", () => {
+		const out = generateOverlay(makeConfig());
+		expect(out).toContain("- `src/foo.ts`");
+		expect(out).toContain("- `src/foo.test.ts`");
+		expect(out).toContain("- `Only touch your file scope`");
+		expect(out).toContain("- `Never push to main`");
+	});
+
+	test("renders quality gates as a numbered checklist with commands", () => {
+		const out = generateOverlay(makeConfig());
+		expect(out).toContain("1. **test:** `bun test` — all tests pass");
+		expect(out).toContain("2. **lint:** `biome check .` — lint clean");
+	});
+
+	test("empty list-shaped fields collapse to (none)", () => {
+		const out = generateOverlay(
+			makeConfig({ fileScope: [], constraints: [], qualityGates: [], siblings: [] }),
+		);
+		// All four empty sections render the sentinel; assert it appears for each.
+		// (At least four occurrences: file scope, constraints, gates, siblings.)
+		const occurrences = out.split("(none)").length - 1;
+		expect(occurrences).toBeGreaterThanOrEqual(4);
+	});
+
+	test("missing specPath renders (none)", () => {
+		const out = generateOverlay(makeConfig({ specPath: undefined }));
+		expect(out).toContain("**Spec:** (none)");
+	});
+
+	test("renders an Applicable Skills section heading", () => {
+		const out = generateOverlay(makeConfig());
+		expect(out).toContain("## Applicable Skills");
+	});
+
+	test("undefined skillsOverlay renders the (none yet) default", () => {
+		const out = generateOverlay(makeConfig({ skillsOverlay: undefined }));
+		expect(out).toContain("(none yet)");
+	});
+
+	test("provided skillsOverlay is rendered verbatim", () => {
+		const out = generateOverlay(makeConfig({ skillsOverlay: "SKILL_BLOCK_XYZ" }));
+		expect(out).toContain("SKILL_BLOCK_XYZ");
+		expect(out).not.toContain("(none yet)");
+	});
+
+	test("provided skillsOverlay appears inside the Applicable Skills section", () => {
+		// The retrieval renderer emits a self-contained block that already carries
+		// the heading; the template substitutes it verbatim.
+		const marker = "## Applicable Skills\n\nSKILL_BLOCK_INSIDE_SECTION";
+		const out = generateOverlay(makeConfig({ skillsOverlay: marker }));
+		const headingIdx = out.indexOf("## Applicable Skills");
+		const markerIdx = out.indexOf("SKILL_BLOCK_INSIDE_SECTION");
+		// The marker body must appear AFTER the section heading (and at all).
+		expect(headingIdx).toBeGreaterThanOrEqual(0);
+		expect(markerIdx).toBeGreaterThan(headingIdx);
+	});
+
+	test("siblings section names each sibling and warns about rebasing", () => {
+		const out = generateOverlay(makeConfig());
+		expect(out).toContain("- builder-beta");
+		expect(out).toContain("- builder-gamma");
+		expect(out.toLowerCase()).toContain("rebase");
+	});
+
+	test("leaf agent (canSpawn=false) states the prohibition", () => {
+		const out = generateOverlay(makeConfig({ canSpawn: false }));
+		expect(out).toContain("may NOT spawn");
+		expect(out).not.toContain("agentplate sling <task-id>");
+	});
+
+	test("spawner (canSpawn=true) shows a sling example with incremented depth", () => {
+		const out = generateOverlay(makeConfig({ canSpawn: true, depth: 1 }));
+		expect(out).toContain("agentplate sling <task-id>");
+		expect(out).toContain("--depth 2"); // depth + 1
+		expect(out).toContain("--parent builder-alpha");
+	});
+
+	test("null parentAgent falls back to coordinator", () => {
+		const out = generateOverlay(makeConfig({ parentAgent: null }));
+		expect(out).toContain("**Parent:** coordinator");
+		// And there is no literal "null" leaking into the parent line.
+		expect(out).not.toContain("**Parent:** null");
+	});
+
+	test("uses the agentplate mail CLI (not ap) for the communication protocol", () => {
+		const out = generateOverlay(makeConfig());
+		expect(out).toContain("agentplate mail check --agent builder-alpha");
+		expect(out).toContain("agentplate mail send");
+	});
+});
+
+describe("writeOverlay", () => {
+	let tempRoot: string;
+
+	beforeEach(() => {
+		// Real temp dir that contains the required worktree marker segment so the
+		// guard is satisfied for the happy path.
+		tempRoot = mkdtempSync(join(tmpdir(), "agentplate-overlay-"));
+	});
+
+	afterEach(() => {
+		rmSync(tempRoot, { recursive: true, force: true });
+	});
+
+	test("writes the rendered overlay under a real worktree path", () => {
+		const worktreePath = join(tempRoot, ".agentplate", "worktrees", "builder-alpha");
+		const instructionPath = join(".claude", "CLAUDE.md");
+		const config = makeConfig({ worktreePath });
+
+		const written = writeOverlay(config, instructionPath);
+
+		expect(written).toBe(join(worktreePath, instructionPath));
+		const onDisk = readFileSync(written, "utf8");
+		// Round-trips the generated content (creating parent dirs along the way).
+		expect(onDisk).toBe(generateOverlay(config));
+		expect(onDisk).toContain("builder-alpha");
+		expect(onDisk).not.toContain("{{");
+	});
+
+	test("throws ValidationError when the path is not a Agentplate worktree", () => {
+		// A plausible-but-wrong target: a real project root, no /.agentplate/worktrees/.
+		const config = makeConfig({ worktreePath: join(tempRoot, "some-project") });
+		expect(() => writeOverlay(config, "CLAUDE.md")).toThrow(ValidationError);
+	});
+
+	test("guard message explains why the write was refused", () => {
+		const config = makeConfig({ worktreePath: "/Users/me/Projects/real-app" });
+		expect(() => writeOverlay(config, "CLAUDE.md")).toThrow(/worktree/i);
+	});
+});

package/src/agents/overlay.ts

@@ -0,0 +1,212 @@
+/**
+ * Dynamic overlay generator.
+ *
+ * Every spawned agent gets two instruction layers: a reusable base `.md`
+ * definition (the HOW) and a per-task overlay (the WHAT). This module renders the
+ * overlay by substituting `{{PLACEHOLDER}}` tokens in
+ * `templates/overlay.md.tmpl` with values from an {@link OverlayConfig}, then
+ * writes the result into the agent's worktree at the runtime's instruction path.
+ *
+ * Design notes:
+ * - Rendering is pure and synchronous: read template, substitute, return string.
+ *   This keeps `generateOverlay` trivial to unit-test and free of side effects.
+ * - List-shaped fields (file scope, constraints, quality gates, siblings) are
+ *   rendered as readable markdown so the agent reads prose, not raw arrays. Empty
+ *   lists collapse to a clear "(none)" sentinel rather than a blank section.
+ * - `writeOverlay` refuses any target that is not under `/.agentplate/worktrees/`.
+ *   Writing an overlay to a real project root would clobber the operator's own
+ *   instruction file (e.g. `.claude/CLAUDE.md`); the guard makes that impossible
+ *   regardless of caller mistakes.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ValidationError } from "../errors.ts";
+import type { OverlayConfig, QualityGate } from "../types.ts";
+
+/** Path segment that marks a directory as a Agentplate-managed worktree. */
+const WORKTREE_MARKER = "/.agentplate/worktrees/";
+
+/** Sentinel rendered for any list-shaped field that is empty. */
+const NONE = "(none)";
+
+/**
+ * Resolve the overlay template path relative to THIS module.
+ *
+ * `import.meta.dir` is `<repo>/src/agents`; the template lives at
+ * `<repo>/templates/overlay.md.tmpl`, i.e. two levels up. Resolving relative to
+ * the module (rather than `process.cwd()`) keeps rendering correct no matter
+ * where `agentplate` is invoked from.
+ */
+function templatePath(): string {
+	return join(import.meta.dir, "..", "..", "templates", "overlay.md.tmpl");
+}
+
+/**
+ * Render a list of strings as a markdown bullet list, or the `(none)` sentinel
+ * when the list is empty. Each entry is wrapped in backticks because these are
+ * always machine-ish tokens (file paths / agent names).
+ */
+function renderBullets(items: readonly string[]): string {
+	if (items.length === 0) return NONE;
+	return items.map((item) => `- \`${item}\``).join("\n");
+}
+
+/**
+ * Render sibling agent names as a bullet list with rebase guidance, or `(none)`.
+ *
+ * Parallel siblings branch off the same pre-merge base, so whoever merges second
+ * carries a stale base unless they rebase first. We surface that here so the
+ * agent rebases BEFORE signalling it is ready to merge.
+ */
+function renderSiblings(siblings: readonly string[] | undefined): string {
+	if (!siblings || siblings.length === 0) return NONE;
+	const bullets = siblings.map((name) => `- ${name}`).join("\n");
+	return [
+		"The following sibling agents are working in parallel and may touch nearby code:",
+		"",
+		bullets,
+		"",
+		"Rebase your branch onto the latest canonical branch and re-run the quality",
+		"gates BEFORE you send your terminal mail — a sibling's work may have landed",
+		"while you were busy, and merging from a stale base can revert it.",
+	].join("\n");
+}
+
+/**
+ * Render the quality gates as a numbered checklist, or `(none)` when no gates are
+ * configured. Each gate shows its name, the exact command to run, and (when
+ * present) its description.
+ */
+function renderQualityGates(gates: readonly QualityGate[]): string {
+	if (gates.length === 0) return NONE;
+	return gates
+		.map((gate, i) => {
+			const suffix = gate.description ? ` — ${gate.description}` : "";
+			return `${i + 1}. **${gate.name}:** \`${gate.command}\`${suffix}`;
+		})
+		.join("\n");
+}
+
+/**
+ * Render the can-spawn section. Spawners get a concrete `agentplate sling` example
+ * (with the depth pre-incremented); leaf agents get an explicit prohibition so
+ * there is no ambiguity.
+ */
+function renderCanSpawn(config: OverlayConfig): string {
+	if (!config.canSpawn) {
+		return "You may NOT spawn sub-workers. You are a leaf agent.";
+	}
+	return [
+		"You may spawn sub-workers with `agentplate sling`. Example:",
+		"",
+		"```bash",
+		"agentplate sling <task-id> --capability builder --name <worker-name> \\",
+		`  --parent ${config.agentName} --depth ${config.depth + 1}`,
+		"```",
+	].join("\n");
+}
+
+/**
+ * Render the spec line shown in the assignment header: the path when one was
+ * provided, otherwise an explicit `(none)` so the agent knows to ask for detail.
+ */
+function renderSpecPath(specPath: string | undefined): string {
+	return specPath && specPath.length > 0 ? specPath : NONE;
+}
+
+/**
+ * Generate a per-task overlay by substituting every `{{PLACEHOLDER}}` token in
+ * the template.
+ *
+ * @param config - The overlay inputs (the WHAT) for this agent/task.
+ * @returns The fully rendered overlay markdown.
+ */
+export function generateOverlay(config: OverlayConfig): string {
+	const template = readTemplate();
+
+	// Map of placeholder -> replacement. Every `{{TOKEN}}` in the template MUST
+	// have an entry here; the loop below replaces all occurrences of each.
+	const replacements: Record<string, string> = {
+		AGENT_NAME: config.agentName,
+		CAPABILITY: config.capability,
+		TASK_ID: config.taskId,
+		BRANCH_NAME: config.branchName,
+		WORKTREE_PATH: config.worktreePath,
+		PARENT_AGENT: config.parentAgent ?? "coordinator",
+		DEPTH: String(config.depth),
+		FILE_SCOPE: renderBullets(config.fileScope),
+		SPEC_PATH: renderSpecPath(config.specPath),
+		CAN_SPAWN: renderCanSpawn(config),
+		QUALITY_GATES: renderQualityGates(config.qualityGates),
+		CONSTRAINTS: renderBullets(config.constraints),
+		SIBLINGS: renderSiblings(config.siblings),
+		// The skills block is self-contained (it carries its own "## Applicable
+		// Skills" heading). When no skills were retrieved, render that heading with
+		// a friendly placeholder so the section is always present and consistent.
+		SKILLS: config.skillsOverlay ?? "## Applicable Skills\n\n(none yet)",
+		BASE_DEFINITION: config.baseDefinition,
+	};
+
+	let result = template;
+	for (const [token, value] of Object.entries(replacements)) {
+		// Replace ALL occurrences — some tokens (e.g. AGENT_NAME, WORKTREE_PATH)
+		// appear more than once. A global string split/join avoids regex-escaping
+		// the value (replacement text may contain `$` from commands/paths).
+		result = result.split(`{{${token}}}`).join(value);
+	}
+
+	return result;
+}
+
+/**
+ * Generate the overlay and write it into the agent's worktree at
+ * `<worktreePath>/<instructionPath>`, creating parent directories as needed.
+ *
+ * Guard: refuses any `worktreePath` that is not a Agentplate worktree (does not
+ * contain `/.agentplate/worktrees/`). This prevents the overlay from ever
+ * overwriting an instruction file at a real project root.
+ *
+ * @param config - The overlay inputs for this agent/task.
+ * @param instructionPath - Relative path within the worktree to write to
+ *   (e.g. the runtime's `.claude/CLAUDE.md`).
+ * @returns The absolute path of the file that was written.
+ * @throws {ValidationError} If `worktreePath` is not under `/.agentplate/worktrees/`.
+ */
+export function writeOverlay(config: OverlayConfig, instructionPath: string): string {
+	// Normalize separators so the marker check works on any platform's paths.
+	const normalizedWorktree = config.worktreePath.replaceAll("\\", "/");
+	if (!normalizedWorktree.includes(WORKTREE_MARKER)) {
+		throw new ValidationError(
+			`Refusing to write overlay outside a Agentplate worktree: "${config.worktreePath}" ` +
+				`does not contain "${WORKTREE_MARKER}". Overlays must target an agent worktree, ` +
+				"never a real project root (it would overwrite the operator's instruction file).",
+		);
+	}
+
+	const content = generateOverlay(config);
+	const outputPath = join(config.worktreePath, instructionPath);
+	// writeFileSync does not create intermediate directories, so make them first.
+	// Synchronous I/O keeps writeOverlay's contract simple (returns the path, no
+	// Promise) and matches the rest of Agentplate's file handling (config, secrets).
+	mkdirSync(dirname(outputPath), { recursive: true });
+	writeFileSync(outputPath, content);
+	return outputPath;
+}
+
+/**
+ * Read the overlay template from disk synchronously.
+ *
+ * Separated from {@link generateOverlay} so the (rare) missing-template failure
+ * surfaces as a typed {@link ValidationError} with the resolved path, which is
+ * far easier to diagnose than a raw ENOENT. A synchronous `readFileSync` keeps
+ * the whole generator synchronous; the template is a small committed asset that
+ * always exists in a real install.
+ */
+function readTemplate(): string {
+	const path = templatePath();
+	if (!existsSync(path)) {
+		throw new ValidationError(`Overlay template not found: ${path}`);
+	}
+	return readFileSync(path, "utf8");
+}

package/src/agents/system-prompt.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildCoordinatorSystemPrompt, writeCoordinatorSystemPrompt } from "./system-prompt.ts";
+
+const ctx = {
+	projectName: "demo",
+	runId: "run-abc",
+	agentName: "coordinator",
+	canonicalBranch: "main",
+	instructionPath: "GEMINI.md",
+};
+
+describe("buildCoordinatorSystemPrompt", () => {
+	test("includes the run context + key CLI verbs", () => {
+		const text = buildCoordinatorSystemPrompt(ctx);
+		expect(text).toContain("demo");
+		expect(text).toContain("run-abc");
+		expect(text).toContain("agentplate mail check --agent coordinator");
+		expect(text).toContain("agentplate sling");
+		// Appends the bundled coordinator base definition.
+		expect(text.toLowerCase()).toContain("coordinator");
+	});
+
+	test("is provider-agnostic: references the runtime's overlay file, not CLAUDE.md", () => {
+		expect(buildCoordinatorSystemPrompt(ctx)).toContain("GEMINI.md");
+		expect(buildCoordinatorSystemPrompt({ ...ctx, instructionPath: "AGENTS.md" })).toContain(
+			"AGENTS.md",
+		);
+	});
+
+	test("mandates dispatch-only fan-out (never edit; multiple agents)", () => {
+		const text = buildCoordinatorSystemPrompt(ctx).toLowerCase();
+		expect(text).toContain("never edit");
+		expect(text).toContain("at least two leads");
+		expect(text).toContain("dispatcher, not an implementer");
+	});
+});
+
+describe("writeCoordinatorSystemPrompt", () => {
+	test("writes the prompt under the agent state dir", () => {
+		const root = mkdtempSync(join(tmpdir(), "agentplate-sp-"));
+		try {
+			const { path, text } = writeCoordinatorSystemPrompt(root, ctx);
+			expect(existsSync(path)).toBe(true);
+			expect(readFileSync(path, "utf8")).toBe(text);
+			expect(path).toContain(join(".agentplate", "agents", "coordinator"));
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+});

package/src/agents/system-prompt.ts

@@ -0,0 +1,95 @@
+/**
+ * Assemble a persistent agent's interactive system prompt.
+ *
+ * For attended sessions (e.g. `coordinator start`) we don't write a worktree
+ * overlay — the agent runs at the project root and is primed via the runtime's
+ * `--append-system-prompt`. This combines the reusable base definition
+ * (`agents/<capability>.md`) with a short run-context header so the live agent
+ * knows the project, its run id, and the exact CLI verbs to use.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { agentStateDir, packageAgentDefPath } from "../paths.ts";
+import type { Capability } from "../types.ts";
+
+export interface CoordinatorPromptContext {
+	projectName: string;
+	runId: string;
+	agentName: string;
+	canonicalBranch: string;
+	/**
+	 * The runtime's overlay instruction file (e.g. `.claude/CLAUDE.md`,
+	 * `AGENTS.md`, `GEMINI.md`) so the prompt is provider-agnostic instead of
+	 * hardcoding a Claude path.
+	 */
+	instructionPath: string;
+}
+
+/** Read a bundled base agent definition (empty string if missing). */
+function readBaseDefinition(capability: Capability): string {
+	const path = packageAgentDefPath(`${capability}.md`);
+	return existsSync(path) ? readFileSync(path, "utf8") : "";
+}
+
+/** Build the coordinator's interactive system prompt text. */
+export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string {
+	const header = [
+		"# Run context",
+		"",
+		`You are **${ctx.agentName}**, the COORDINATOR for the Agentplate project ` +
+			`**${ctx.projectName}**.`,
+		`Active run: \`${ctx.runId}\` · canonical branch: \`${ctx.canonicalBranch}\`.`,
+		"",
+		"You run as an interactive session: the operator chats with you here. Your ONLY",
+		"job is to HIRE and COORDINATE a team of agents. You are a dispatcher, not an",
+		"implementer.",
+		"",
+		"## Hard rules (always apply, every provider)",
+		"",
+		"1. **Never edit, write, or create files yourself, and never run the build/tests",
+		"   to 'just fix it'.** You have no implementation role — every change is made by",
+		"   an agent you dispatch. If you catch yourself about to edit a file, sling an",
+		"   agent instead.",
+		"2. **Always fan out into multiple agents.** Decompose the goal into INDEPENDENT,",
+		"   parallel slices and dispatch one lead per slice. For anything beyond a single",
+		"   trivial change, dispatch **at least TWO leads** so work proceeds in parallel.",
+		"3. **Spawn ONLY with `agentplate sling`** (run it through your shell/Bash tool).",
+		"   Do NOT use any built-in sub-agent / Task / Workflow tool — agents created that",
+		"   way bypass Agentplate's session store, mail bus, and merge queue, so they",
+		"   never appear in `ap serve`/`ap tui` and their work is not tracked or merged.",
+		"",
+		"Key commands:",
+		"",
+		`- Check mail: \`agentplate mail check --agent ${ctx.agentName}\``,
+		`- Dispatch a lead: \`agentplate sling <task-id> --capability lead --parent ${ctx.agentName} --spec .agentplate/specs/<task-id>.md\``,
+		"- Fleet status: `agentplate status`",
+		"- Merge completed work: `agentplate merge --all`",
+		"",
+		`Your per-run goal and constraints live in your overlay instruction file ` +
+			`(\`${ctx.instructionPath}\`) and the task tracker — read them first.`,
+		"",
+		"Begin by greeting the operator and asking what to build, then DECOMPOSE the goal",
+		"into parallel slices and dispatch a lead for each. The reusable role definition",
+		"follows.",
+		"",
+		"---",
+		"",
+	].join("\n");
+	return `${header}${readBaseDefinition("coordinator")}`;
+}
+
+/**
+ * Write the assembled system prompt to the agent's state dir and return its path.
+ * (Persisted so it can be inspected; the runtime receives the text, not the path.)
+ */
+export function writeCoordinatorSystemPrompt(
+	root: string,
+	ctx: CoordinatorPromptContext,
+): { path: string; text: string } {
+	const text = buildCoordinatorSystemPrompt(ctx);
+	const path = `${agentStateDir(root, ctx.agentName)}/system-prompt.md`;
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, text, "utf8");
+	return { path, text };
+}

package/src/agents/turn-runner.ts

@@ -0,0 +1,79 @@
+/**
+ * Spawn-per-turn engine.
+ *
+ * Runs ONE headless turn of an agent: build the runtime's argv, spawn it in the
+ * worktree, drain its output (parsing events when the runtime supports it, so we
+ * can capture the resume session id and feed the event store), and return when
+ * the process exits. The orchestration layer decides when to run the next turn
+ * (driven by mail) — this module owns a single turn only.
+ */
+
+import type { AgentEvent, AgentRuntime } from "../runtimes/types.ts";
+import { resolveArgv } from "../utils/detect.ts";
+
+export interface RunTurnOptions {
+	runtime: AgentRuntime;
+	/** Worktree directory the turn runs in. */
+	worktreePath: string;
+	/** Concrete model id. */
+	model: string;
+	/** The user-turn text (dispatch/mail/nudge). */
+	prompt: string;
+	/** Provider env vars (merged over process.env for the child). */
+	env?: Record<string, string>;
+	/** Prior runtime session id, to resume across turns. */
+	resumeSessionId?: string;
+	/** Called for each parsed event (e.g. to record tool calls). */
+	onEvent?: (event: AgentEvent) => void;
+}
+
+export interface TurnResult {
+	exitCode: number;
+	/** Runtime session id captured from the event stream (for --resume). */
+	runtimeSessionId: string | null;
+	/** Captured stderr (already bounded by the child). */
+	stderr: string;
+}
+
+/** Run a single headless turn and resolve when the child process exits. */
+export async function runTurn(opts: RunTurnOptions): Promise<TurnResult> {
+	const argv = opts.runtime.buildDirectSpawn({
+		cwd: opts.worktreePath,
+		model: opts.model,
+		instructionPath: opts.runtime.instructionPath,
+		resumeSessionId: opts.resumeSessionId,
+		prompt: opts.prompt,
+		env: opts.env,
+	});
+
+	// Let the runtime contribute env beyond the resolved provider key — e.g.
+	// OpenCode injects OPENCODE_PERMISSION so an unattended worker auto-approves
+	// tool actions instead of deadlocking on a permission prompt. For runtimes that
+	// add nothing this equals `opts.env`, so the behavior is unchanged.
+	const runtimeEnv = opts.runtime.buildEnv({ model: opts.model, env: opts.env });
+	const proc = Bun.spawn(resolveArgv(argv), {
+		cwd: opts.worktreePath,
+		env: { ...process.env, ...runtimeEnv },
+		stdout: "pipe",
+		stderr: "pipe",
+		stdin: "ignore",
+	});
+
+	// Read stderr concurrently so a full pipe buffer can't deadlock the child.
+	const stderrPromise = new Response(proc.stderr).text();
+
+	let runtimeSessionId: string | null = null;
+	if (opts.runtime.parseEvents) {
+		for await (const event of opts.runtime.parseEvents(proc.stdout)) {
+			if (event.sessionId) runtimeSessionId = event.sessionId;
+			opts.onEvent?.(event);
+		}
+	} else {
+		// No event parser (e.g. the mock runtime): just drain stdout.
+		await new Response(proc.stdout).text();
+	}
+
+	const stderr = await stderrPromise;
+	const exitCode = await proc.exited;
+	return { exitCode, runtimeSessionId, stderr };
+}