fix(coding-agent): executor review fixes (wait gating, mid-settle resume, JSON-strict guards)

Wait states are gated at the validator (the rlm.watch.* host handlers
arrive with the communication series #2351/#2356), so the executor's wait
registration/timeout/settle/cancel paths and their tests are removed
entirely; quiescence, re-entry, and fan-out are unchanged. Review fixes:
a max_transitions pause mid-settle now records the transition index and a
resume continues after it (previously the settle re-fired already-fired
transitions, duplicating spawned work); eq/ne guards compare JSON-strictly
(a bool never equals a number, numbers compare numerically); contains
requires a non-empty list value at validation and is defensively false at
runtime; the max_transitions pause fires its own max_transitions_exceeded
milestone kind (no collision with the run-budget budget_exceeded, both
notice-able); the control-loop stall reports the pending entry whose input
source never settled, with a test; EVENT_WINDOW grows 50 -> 200 (the
pr-manager happy path is ~43 events before any retry); refinement
validateEdit accepts machine-form swarm edits (either dag or machine
object, never both). Also adds optional inputs: an input flagged optional
binds a null sentinel instead of waiting when its source state never
settled, which lets loop states (review with the previous fix report) run
their first round before the fixer exists; compiled dags never emit it.

Author: sethkarten

packages/coding-agent/.changes/swarm-dag-executor.md

@@ -1 +1 @@
-- Added the swarm DAG executor: `rlm.swarm.run/status/stop/resume` validates a stored swarm, spawns ready nodes without holding the model turn open, resumes through collect polls, binds typed outputs into dependent prompts, enforces per-node and run budgets, retries failures, applies fail_fast/continue/escalate policies, cascades cancellation, and wakes the parent once per milestone.
+- Added the state-machine swarm executor: `rlm.swarm.run/status/stop/resume` canonicalizes the stored swarm (dag sugar compiles to machine form), enters entry states, and drives the machine to quiescence — every settle evaluates its guarded transitions (fan-out legal, max_entries blocking recorded as transition_blocked, re-entry re-binds inputs), with bounded re-entry, per-entry foreach/budgets/retries, fail_fast/continue/escalate policies, cancellation cascades, and one quiet notice per milestone (finished/failed/paused/budget_exceeded/max_transitions_exceeded). `status()` reports per-state entries_used/max_entries and a transitions_fired usage count over a 200-event window. Wait states stay specified but gated: the watch host handlers (`rlm.watch.*`) arrive with the communication series, so the validator rejects wait blocks until then.

packages/coding-agent/src/core/messages.ts

@@ -271,7 +271,7 @@ Command: ${JSON.stringify(details.command)}`,
 
 export interface SwarmProgressDetails {
 	runId: string;
-	kind: "finished" | "failed" | "paused" | "budget_exceeded";
+	kind: "finished" | "failed" | "paused" | "budget_exceeded" | "max_transitions_exceeded";
 	node?: string;
 	detail: string;
 }

packages/coding-agent/src/core/refinement/refinement.ts

@@ -1067,10 +1067,15 @@ function validateEdit(edit: RefinementEdit, computedId?: string): string | undef
 	}
 	if (edit.action !== "delete" && edit.kind === "swarm") {
 		// Structural check only: the kernel validator (rlm.swarm) enforces the full
-		// DAG semantics at write time; do not reimplement it here.
+		// machine semantics at write time; do not reimplement it here.
 		const dag = edit.arguments?.dag;
-		if (typeof dag !== "object" || dag === null || Array.isArray(dag)) {
-			return "swarm entry requires a dag object in arguments";
+		const machine = edit.arguments?.machine;
+		if (dag !== undefined && machine !== undefined) {
+			return "pass either dag or machine form, not both";
+		}
+		const spec = machine ?? dag;
+		if (typeof spec !== "object" || spec === null || Array.isArray(spec)) {
+			return "swarm entry requires a dag or machine object in arguments";
 		}
 	}
 	return undefined;

packages/coding-agent/src/core/rlm-runtime.ts

@@ -126,7 +126,7 @@ interface AsyncBashConsumedRequest {
 
 type AsyncBashConsumedHandler = (request: AsyncBashConsumedRequest) => void | Promise<void>;
 
-export type SwarmProgressKind = "finished" | "failed" | "paused" | "budget_exceeded";
+export type SwarmProgressKind = "finished" | "failed" | "paused" | "budget_exceeded" | "max_transitions_exceeded";
 
 export interface SwarmProgressRequest {
 	runId: string;
@@ -137,7 +137,13 @@ export interface SwarmProgressRequest {
 
 export type SwarmProgressHandler = (request: SwarmProgressRequest) => void | Promise<void>;
 
-const SWARM_PROGRESS_KINDS: readonly SwarmProgressKind[] = ["finished", "failed", "paused", "budget_exceeded"];
+const SWARM_PROGRESS_KINDS: readonly SwarmProgressKind[] = [
+	"finished",
+	"failed",
+	"paused",
+	"budget_exceeded",
+	"max_transitions_exceeded",
+];
 
 function isSwarmProgressKind(value: unknown): value is SwarmProgressKind {
 	return typeof value === "string" && (SWARM_PROGRESS_KINDS as readonly string[]).includes(value);

packages/coding-agent/test/refinement.test.ts

@@ -100,6 +100,18 @@ const swarmDag = {
 	],
 };
 
+const swarmMachine = {
+	states: [
+		{ id: "collect", entry: true, subagent: "researcher", outputs: [{ name: "findings", type: "text" }] },
+		{
+			id: "review",
+			subagent: { prompt: "Review the findings." },
+			inputs: [{ name: "draft", type: "text", from: "collect.findings" }],
+		},
+	],
+	transitions: [{ from: "collect", to: "review" }],
+};
+
 function proposal(summary: string, edits: RefinementProposal["edits"]): RefinementProposal {
 	return {
 		summary,
@@ -296,12 +308,12 @@ describe("harness refinement", () => {
 		expect(state.refinements.at(-1)?.changes).toEqual([`delete ${kind}:${id}`]);
 	});
 
-	it("requires a dag object in arguments for swarm creates and updates", () => {
+	it("requires exactly one dag or machine object in arguments for swarm creates and updates", () => {
 		const state = loadHarnessState(makeTempDir());
 
-		const missingDag = applyRefinementProposal(
+		const missingSpec = applyRefinementProposal(
 			state,
-			proposal("Create swarm without a dag", [
+			proposal("Create swarm without a spec", [
 				{
 					action: "create",
 					kind: "swarm",
@@ -313,9 +325,9 @@ describe("harness refinement", () => {
 			{ id: "refine_swarm_missing_dag" },
 		);
 
-		expect(missingDag.appliedEdits[0]).toMatchObject({
+		expect(missingSpec.appliedEdits[0]).toMatchObject({
 			applied: false,
-			error: "swarm entry requires a dag object in arguments",
+			error: "swarm entry requires a dag or machine object in arguments",
 		});
 		expect(state.entries.swarm.swarm_entry).toBeUndefined();
 		expect(state.refinements.at(-1)?.changes).toEqual([]);
@@ -337,8 +349,29 @@ describe("harness refinement", () => {
 
 		expect(nonObjectDag.appliedEdits[0]).toMatchObject({
 			applied: false,
-			error: "swarm entry requires a dag object in arguments",
+			error: "swarm entry requires a dag or machine object in arguments",
+		});
+
+		const bothForms = applyRefinementProposal(
+			state,
+			proposal("Create swarm with both forms", [
+				{
+					action: "create",
+					kind: "swarm",
+					id: "swarm_entry",
+					title: "Swarm title",
+					content: "Swarm content",
+					arguments: { dag: swarmDag, machine: swarmMachine },
+				},
+			]),
+			{ id: "refine_swarm_both_forms" },
+		);
+
+		expect(bothForms.appliedEdits[0]).toMatchObject({
+			applied: false,
+			error: "pass either dag or machine form, not both",
 		});
+		expect(state.entries.swarm.swarm_entry).toBeUndefined();
 
 		const created = applyRefinementProposal(
 			state,
@@ -360,9 +393,27 @@ describe("harness refinement", () => {
 		expect(created.appliedEdits[0].applied).toBe(true);
 		expect(state.entries.swarm.swarm_entry.arguments).toEqual({ dag: swarmDag });
 
-		const updateWithoutDag = applyRefinementProposal(
+		const machineCreated = applyRefinementProposal(
+			state,
+			proposal("Create swarm with a machine", [
+				{
+					action: "create",
+					kind: "swarm",
+					id: "swarm_machine_entry",
+					title: "Swarm machine",
+					content: "Swarm machine content",
+					arguments: { machine: swarmMachine },
+				},
+			]),
+			{ id: "refine_swarm_machine_valid" },
+		);
+
+		expect(machineCreated.appliedEdits[0].applied).toBe(true);
+		expect(state.entries.swarm.swarm_machine_entry.arguments).toEqual({ machine: swarmMachine });
+
+		const updateWithoutSpec = applyRefinementProposal(
 			state,
-			proposal("Update swarm without a dag", [
+			proposal("Update swarm without a spec", [
 				{
 					action: "update",
 					kind: "swarm",
@@ -374,9 +425,9 @@ describe("harness refinement", () => {
 			{ id: "refine_swarm_update_missing_dag" },
 		);
 
-		expect(updateWithoutDag.appliedEdits[0]).toMatchObject({
+		expect(updateWithoutSpec.appliedEdits[0]).toMatchObject({
 			applied: false,
-			error: "swarm entry requires a dag object in arguments",
+			error: "swarm entry requires a dag or machine object in arguments",
 		});
 		expect(state.entries.swarm.swarm_entry.title).toBe("Swarm title");
 	});

packages/coding-agent/test/swarm-executor.test.ts

@@ -24,6 +24,17 @@ describe("swarm progress", () => {
 		]);
 	});
 
+	it("renders the max_transitions pause kind verbatim (distinct from budget_exceeded)", () => {
+		const message = createSwarmProgressMessage({
+			runId: "run-2",
+			kind: "max_transitions_exceeded",
+			detail: "max_transitions 1 exceeded; no new entries",
+		});
+		expect(message.content).toBe(
+			"[swarm-progress run:run-2] max_transitions_exceeded: max_transitions 1 exceeded; no new entries",
+		);
+	});
+
 	it("renders the finished, failed, and paused milestone kinds verbatim", () => {
 		expect(createSwarmProgressMessage({ runId: "r", kind: "finished", detail: "all 3 nodes done" }).content).toBe(
 			"[swarm-progress run:r] finished: all 3 nodes done",