@oisincoveney/pipeline 2.3.1 → 2.5.0

package/dist/runtime/agent-node/agent-node.js

@@ -8,6 +8,8 @@ import { emit, emitAgentFinish, emitAgentStart } from "../events/events.js";
 import "../events/index.js";
 import { gatewayServerForProfile } from "../../mcp/gateway.js";
 import { selectNodeModel } from "../../model-resolver.js";
+import { estimateTokens } from "../../token-estimator.js";
+import { handoffFinalizerPrompt, parseHandoff, renderHandoff, synthesizeMinimalHandoff } from "../handoff.js";
 import { readFileSync } from "node:fs";
 //#region src/runtime/agent-node/agent-node.ts
 async function executeAgentNode(node, context, attempt) {
@@ -17,7 +19,17 @@ async function executeAgentNode(node, context, attempt) {
 		output: ""
 	};
 	const prompt = renderAgentPrompt(node, context);
-	const modelSelection = selectNodeModel(node);
+	const decision = decideNodeModel(prompt, node, context.config.token_budget);
+	if (decision.overBudget) return {
+		evidence: [
+			`agent boundary node=${node.id} profile=${node.profile}`,
+			`over token budget: ${decision.selection.reason}`,
+			...decision.selection.skipped.length ? [`model fallbacks skipped: ${decision.selection.skipped.join(", ")}`] : []
+		],
+		exitCode: 1,
+		output: ""
+	};
+	const modelSelection = decision.selection;
 	const plan = createRunnerLaunchPlan(context.config, {
 		model: modelSelection.model,
 		nodeId: node.id,
@@ -52,9 +64,11 @@ async function executeAgentNode(node, context, attempt) {
 		result,
 		attempt
 	});
-	return {
+	const handoff = await maybeDeriveHandoff(context, node, finalized.output, attempt);
+	return withOptionalHandoff({
 		evidence: [
 			`agent boundary node=${node.id} profile=${node.profile} runner=${plan.runnerId}`,
+			`estimated context tokens: ${decision.estimatedTokens}`,
 			`model selection: ${modelSelection.model ?? "profile/default"} (${modelSelection.reason})`,
 			...modelSelection.skipped.length ? [`model fallbacks skipped: ${modelSelection.skipped.join(", ")}`] : [],
 			...finalized.evidence,
@@ -64,6 +78,85 @@ async function executeAgentNode(node, context, attempt) {
 		exitCode: result.exitCode,
 		output: finalized.output,
 		timedOut: result.timedOut
+	}, handoff);
+}
+function withOptionalHandoff(result, handoff) {
+	return handoff ? {
+		...result,
+		handoff
+	} : result;
+}
+function profileRunner(context, node) {
+	return node.profile ? context.config.profiles[node.profile]?.runner : void 0;
+}
+/**
+* PIPE-83.1: derive a structured NodeHandoff for this node when context_handoff
+* is enabled. Fast-path reuses an already-handoff-shaped output; otherwise a
+* cheap read-only finalizer (mirroring createOutputRepairPlan) summarizes the
+* raw output, falling back to a synthesized minimal handoff. Returns undefined
+* when disabled so behaviour is unchanged.
+*/
+async function maybeDeriveHandoff(context, node, rawOutput, attempt) {
+	if (!context.config.context_handoff?.enabled) return;
+	return parseHandoff(rawOutput) ?? await runHandoffFinalizer(context, node, rawOutput, attempt);
+}
+async function runHandoffFinalizer(context, node, rawOutput, attempt) {
+	const runner = profileRunner(context, node);
+	if (!(runner && rawOutput.trim())) return synthesizeMinimalHandoff(rawOutput);
+	const plan = createHandoffFinalizerPlan(context, node, runner, rawOutput);
+	context.agentInvocations.push(plan);
+	emitAgentStart(context, plan, attempt);
+	const result = await context.executor(plan, { signal: context.signal });
+	emitAgentFinish(context, plan, attempt, result);
+	return parseHandoff(normalizeAgentOutput(plan, result.stdout).output) ?? synthesizeMinimalHandoff(rawOutput);
+}
+function createHandoffFinalizerPlan(context, node, runner, rawOutput) {
+	const finalizerProfileId = `${node.id}:handoff`;
+	const finalizerConfig = {
+		...context.config,
+		profiles: {
+			...context.config.profiles,
+			[finalizerProfileId]: {
+				filesystem: { mode: "read-only" },
+				instructions: { inline: "Summarize the agent output into a NodeHandoff JSON." },
+				network: { mode: "disabled" },
+				output: { format: "text" },
+				runner,
+				tools: []
+			}
+		}
+	};
+	const model = context.config.context_handoff?.model;
+	return createRunnerLaunchPlan(finalizerConfig, {
+		nodeId: finalizerProfileId,
+		profileId: finalizerProfileId,
+		prompt: handoffFinalizerPrompt(rawOutput),
+		worktreePath: context.worktreePath,
+		...model ? { model } : {}
+	});
+}
+/**
+* Pure model-routing decision for a node: estimate the assembled prompt size and
+* pick the smallest fallback model whose window holds it within the context cap.
+* A node with no fallback array keeps the legacy (size-unaware) selection. A node
+* with a fallback array but no fitting model is `overBudget` — the caller fails
+* it fast rather than truncating.
+*/
+function decideNodeModel(prompt, node, budget) {
+	const estimatedTokens = estimateTokens(prompt);
+	if (!(budget && node.models?.length)) return {
+		estimatedTokens,
+		overBudget: false,
+		selection: selectNodeModel(node)
+	};
+	const selection = selectNodeModel(node, {
+		budget,
+		estimatedTokens
+	});
+	return {
+		estimatedTokens,
+		overBudget: !selection.model,
+		selection
 	};
 }
 async function finalizeAgentOutput(inputs) {
@@ -238,9 +331,18 @@ function renderAgentPrompt(node, context) {
 		"",
 		...inheritedOutputSections(node, context),
 		"Dependency outputs:",
-		...node.needs.map((need) => `## ${need}\n${context.nodeStateStore.outputText(need)}`)
+		...node.needs.map((need) => renderDependencySection(need, context))
 	].filter(Boolean).join("\n");
 }
+/**
+* PIPE-83.5: render a dependency's curated NodeHandoff when one was derived
+* (PIPE-83.1), otherwise fall back to its raw output text. The fallback keeps
+* behaviour identical when context_handoff is disabled (no handoffs recorded).
+*/
+function renderDependencySection(nodeId, context) {
+	const handoff = context.nodeStateStore.handoff(nodeId);
+	return handoff ? renderHandoff(nodeId, handoff) : `## ${nodeId}\n${context.nodeStateStore.outputText(nodeId)}`;
+}
 function renderGateOutputContract(node) {
 	const gates = node.gates ?? [];
 	const hasAcceptanceGate = gates.some((gate) => gate.kind === "acceptance" && (gate.target === void 0 || gate.target === "stdout"));
@@ -283,7 +385,7 @@ function inheritedOutputSections(node, context) {
 	if (inherited.length === 0) return [];
 	return [
 		"Inherited dependency outputs:",
-		...inherited.map((id) => `## ${id}\n${context.nodeStateStore.outputText(id)}`),
+		...inherited.map((id) => renderDependencySection(id, context)),
 		""
 	];
 }

package/dist/runtime/builtins/builtins.js

@@ -1,10 +1,12 @@
 import { runFallow, runJscpd, runLint, runSemgrep, runTests, runTypecheck } from "../../gates.js";
 import { executeDrainMergeBuiltin } from "../drain-merge/drain-merge.js";
 import "../drain-merge/index.js";
+import { executeSelectCandidateBuiltin } from "../select-candidate/select-candidate.js";
 //#region src/runtime/builtins/builtins.ts
 async function executeBuiltin(builtin, context, node) {
 	switch (builtin) {
 		case "drain-merge": return executeDrainMergeBuiltin(context, node);
+		case "select-candidate": return executeSelectCandidateBuiltin(context, node);
 		case "test": {
 			const result = await runTests(context.worktreePath, context.signal);
 			return {

package/dist/runtime/handoff.d.ts

@@ -0,0 +1 @@
+import { z } from "zod";

package/dist/runtime/handoff.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+//#region src/runtime/handoff.ts
+/**
+* NodeHandoff (PIPE-83.1) — the curated, typed envelope a node hands to its
+* dependents in place of its raw transcript. PIPE-83.5 makes renderAgentPrompt
+* consume these instead of re-hydrating every upstream node's full output text;
+* PIPE-83.10 persists them durably as the unit of cross-node state.
+*
+* Produced by DERIVING from a node's raw output via a cheap finalizer (see
+* agent-node), with a synthesized minimal fallback when no structured handoff
+* is available so existing consumers keep working unchanged.
+*/
+const MARKDOWN_JSON_FENCE_RE = /^\s*```(?:json)?\s*\r?\n([\s\S]*?)\r?\n```\s*$/i;
+const SUMMARY_FALLBACK_MAX_CHARS = 600;
+const handoffArtifactSchema = z.object({
+	lineRange: z.tuple([z.number().int().nonnegative(), z.number().int().nonnegative()]).optional(),
+	path: z.string().min(1)
+});
+const nodeHandoffSchema = z.object({
+	artifacts: z.array(handoffArtifactSchema).default([]),
+	decisions: z.array(z.string()).default([]),
+	openQuestions: z.array(z.string()).default([]),
+	summary: z.string(),
+	testNames: z.array(z.string()).default([])
+});
+/**
+* Parse a candidate handoff JSON string (tolerant of a Markdown ```json fence).
+* Returns null when the text is not JSON or does not satisfy the schema, so the
+* caller can fall back rather than throw.
+*/
+function parseHandoff(raw) {
+	const source = MARKDOWN_JSON_FENCE_RE.exec(raw.trim())?.[1].trim() ?? raw.trim();
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		return null;
+	}
+	const result = nodeHandoffSchema.safeParse(value);
+	return result.success ? result.data : null;
+}
+/**
+* Minimal handoff synthesized from a node's raw output text. Used when no
+* structured handoff is derived, preserving the pre-PIPE-83 behaviour (the
+* summary stands in for the raw text downstream consumers used to receive).
+*/
+function synthesizeMinimalHandoff(outputText) {
+	return {
+		artifacts: [],
+		decisions: [],
+		openQuestions: [],
+		summary: outputText.trim().slice(0, SUMMARY_FALLBACK_MAX_CHARS),
+		testNames: []
+	};
+}
+/**
+* Render a handoff into the compact text a dependent node receives (PIPE-83.5):
+* the curated summary + non-empty sections, in place of the full raw transcript.
+*/
+function renderHandoff(nodeId, handoff) {
+	const sections = [
+		["Decisions:", handoff.decisions],
+		["Artifacts:", handoff.artifacts.map((a) => a.lineRange ? `${a.path}:${a.lineRange[0]}-${a.lineRange[1]}` : a.path)],
+		["Tests:", handoff.testNames],
+		["Open questions:", handoff.openQuestions]
+	];
+	const lines = [`## ${nodeId}`, handoff.summary];
+	for (const [heading, items] of sections) if (items.length > 0) lines.push(heading, ...items.map((item) => `- ${item}`));
+	return lines.join("\n");
+}
+/** Prompt for the cheap finalizer that derives a handoff from raw node output. */
+function handoffFinalizerPrompt(rawOutput) {
+	return [
+		"You are a handoff summarizer for a pipeline node.",
+		"Read the agent output below and return ONLY a JSON object describing what a",
+		"downstream node needs to continue — no Markdown fences, no prose outside JSON.",
+		"",
+		"Fields:",
+		"- \"summary\": string — concise description of what this node accomplished.",
+		"- \"decisions\": string[] — explicit choices made (libraries, APIs, approaches).",
+		"- \"artifacts\": {\"path\": string, \"lineRange\"?: [number, number]}[] — files touched.",
+		"- \"testNames\": string[] — tests added or changed.",
+		"- \"openQuestions\": string[] — unresolved items the next node should know.",
+		"Use empty arrays where nothing applies. Preserve facts; do not invent.",
+		"",
+		"Agent output:",
+		rawOutput
+	].join("\n");
+}
+//#endregion
+export { handoffFinalizerPrompt, parseHandoff, renderHandoff, synthesizeMinimalHandoff };

package/dist/runtime/node-state-store.js

@@ -1,11 +1,13 @@
 //#region src/runtime/node-state-store.ts
 var NodeStateStore = class NodeStateStore {
+	handoffByNode;
 	inheritedOutputNodeIds;
 	lastOutputByNode;
 	nodeSnapshots;
 	nodeStates;
 	structuredOutputs;
 	constructor(input = {}) {
+		this.handoffByNode = input.handoffByNode ?? /* @__PURE__ */ new Map();
 		this.inheritedOutputNodeIds = input.inheritedOutputNodeIds ?? /* @__PURE__ */ new Set();
 		this.lastOutputByNode = input.lastOutputByNode ?? /* @__PURE__ */ new Map();
 		this.nodeSnapshots = input.nodeSnapshots ?? /* @__PURE__ */ new Map();
@@ -14,6 +16,7 @@ var NodeStateStore = class NodeStateStore {
 	}
 	forkForParallelChildren(children) {
 		return new NodeStateStore({
+			handoffByNode: new Map(this.handoffByNode),
 			inheritedOutputNodeIds: new Set(this.lastOutputByNode.keys()),
 			lastOutputByNode: new Map(this.lastOutputByNode),
 			nodeSnapshots: /* @__PURE__ */ new Map(),
@@ -34,6 +37,9 @@ var NodeStateStore = class NodeStateStore {
 	getOutput(nodeId) {
 		return this.lastOutputByNode.get(nodeId);
 	}
+	handoff(nodeId) {
+		return this.handoffByNode.get(nodeId);
+	}
 	outputText(nodeId) {
 		return this.lastOutputByNode.get(nodeId) ?? "";
 	}
@@ -47,6 +53,9 @@ var NodeStateStore = class NodeStateStore {
 	markInheritedOutput(nodeId) {
 		this.inheritedOutputNodeIds.add(nodeId);
 	}
+	recordHandoff(nodeId, handoff) {
+		if (handoff) this.handoffByNode.set(nodeId, handoff);
+	}
 	recordOutput(nodeId, output) {
 		this.lastOutputByNode.set(nodeId, output);
 	}

package/dist/runtime/opencode-session-executor.js

@@ -26,6 +26,9 @@ function createOpencodeExecutor(deps) {
 		}
 	};
 }
+function sessionDirectory(deps, plan) {
+	return plan.cwd ?? deps.directory;
+}
 async function driveSession(deps, plan, options) {
 	const sessionId = await resolveSessionId(deps, plan);
 	deps.onSession?.(plan.nodeId, sessionId);
@@ -34,7 +37,7 @@ async function driveSession(deps, plan, options) {
 		const data = unwrap(await deps.client.session.prompt({
 			body: promptBody(plan),
 			path: { id: sessionId },
-			query: { directory: deps.directory }
+			query: { directory: sessionDirectory(deps, plan) }
 		}));
 		return {
 			...data.info ? { assistant: data.info } : {},
@@ -50,7 +53,7 @@ async function resolveSessionId(deps, plan) {
 	if (existing) return existing;
 	const session = unwrap(await deps.client.session.create({
 		body: { title: `moka:${plan.nodeId}` },
-		query: { directory: deps.directory }
+		query: { directory: plan.cwd ?? deps.directory }
 	}));
 	deps.registry.sessions.set(plan.nodeId, session.id);
 	return session.id;

package/dist/runtime/parallel-node/parallel-node.js

@@ -1,5 +1,6 @@
 import { childReporter } from "../events/events.js";
 import "../events/index.js";
+import { createChildWorktree, gcParallelWorktrees } from "../parallel-worktrees/parallel-worktrees.js";
 import pLimit from "p-limit";
 //#region src/runtime/parallel-node/parallel-node.ts
 async function executeParallelNode(node, context, runtime) {
@@ -9,6 +10,7 @@ async function executeParallelNode(node, context, runtime) {
 		exitCode: 1,
 		output: ""
 	};
+	gcStaleWorktrees(context);
 	const linkedAbort = createLinkedAbortController(context.signal);
 	const childContext = createParallelChildContext(context, node.id, children, context.plan.execution.failFast ? linkedAbort.controller.signal : context.signal);
 	try {
@@ -23,6 +25,37 @@ async function executeParallelNode(node, context, runtime) {
 		linkedAbort.cleanup();
 	}
 }
+function gcStaleWorktrees(context) {
+	if (context.config.parallel_worktrees?.enabled) gcParallelWorktrees(context.worktreePath);
+}
+/**
+* PIPE-83.4: run a parallel child in its own git worktree when enabled, so
+* concurrent candidate edits can't collide. The lease is created inside the
+* per-child callback (not before scheduling) so failFast-cleared children never
+* allocate a worktree; release retains dirty/unpushed work for downstream
+* selection. Default-off path is byte-identical to the prior behaviour.
+*/
+function runChildInWorktree(child, context, runtime) {
+	return context.config.parallel_worktrees?.enabled ? runInLease(child, context, runtime, createChildLease(child, context)) : runtime.executeNode(child, context);
+}
+function createChildLease(child, context) {
+	return createChildWorktree({
+		childNodeId: child.id,
+		parentNodeId: context.parentParallelNodeId ?? "parallel",
+		repoRoot: context.worktreePath,
+		...context.runId ? { runId: context.runId } : {}
+	});
+}
+async function runInLease(child, context, runtime, lease) {
+	try {
+		return await runtime.executeNode(child, {
+			...context,
+			worktreePath: lease.path
+		});
+	} finally {
+		lease.release();
+	}
+}
 function createParallelChildContext(context, parentNodeId, children, signal) {
 	return {
 		...context,
@@ -60,9 +93,9 @@ function createLinkedAbortController(signal) {
 }
 function executeParallelChildren(children, context, runtime) {
 	for (const child of children) runtime.markNodeReady(context, child.id);
-	if (!context.maxParallelNodes) return Promise.all(children.map((child) => runtime.executeNode(child, context)));
+	if (!context.maxParallelNodes) return Promise.all(children.map((child) => runChildInWorktree(child, context, runtime)));
 	const limit = pLimit(context.maxParallelNodes);
-	return Promise.all(children.map((child) => limit(() => runtime.executeNode(child, context))));
+	return Promise.all(children.map((child) => limit(() => runChildInWorktree(child, context, runtime))));
 }
 async function executeFailFastParallelChildren(children, context, abortController, runtime) {
 	for (const child of children) runtime.markNodeReady(context, child.id);
@@ -71,7 +104,7 @@ async function executeFailFastParallelChildren(children, context, abortControlle
 		rejectOnClear: true
 	});
 	return (await Promise.allSettled(children.map((child) => limit(async () => {
-		const result = await runtime.executeNode(child, context);
+		const result = await runChildInWorktree(child, context, runtime);
 		if (result.status === "failed") {
 			abortController.abort();
 			limit.clearQueue();

package/dist/runtime/parallel-worktrees/parallel-worktrees.js

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region src/runtime/parallel-worktrees/parallel-worktrees.ts
+/**
+* PIPE-83.4: git-worktree isolation for parallel candidate nodes. Each parallel
+* child runs in its own worktree on an auto-named branch so concurrent edits do
+* not collide. Teardown is idempotent and crash-safe: a worktree with dirty or
+* unpushed work is RETAINED (never deleted), and orphaned worktrees are GC'd on
+* startup using the same safety guard. A worktree is NOT a sandbox — node_modules
+* and build state are shared; real isolation remains k8s mode.
+*/
+const WORKTREE_ROOT = ".pipeline/worktrees";
+const REGISTRY_DIR = join(WORKTREE_ROOT, "registry");
+const OWNER = "oisin-pipeline";
+function git(cwd, args) {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf8"
+	}).trim();
+}
+function sanitize(id) {
+	return id.replace(/[^A-Za-z0-9._-]/g, "-");
+}
+function writeManifest(path, manifest) {
+	writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+function readManifest(path) {
+	return JSON.parse(readFileSync(path, "utf8"));
+}
+function createChildWorktree(opts) {
+	const runSeg = sanitize(opts.runId ?? "local");
+	const parentSeg = sanitize(opts.parentNodeId);
+	const childSeg = sanitize(opts.childNodeId);
+	const baseSha = git(opts.repoRoot, ["rev-parse", "HEAD"]);
+	const relPath = join(WORKTREE_ROOT, "trees", runSeg, parentSeg, childSeg);
+	const absPath = join(opts.repoRoot, relPath);
+	const branch = `pipeline/worktrees/${runSeg}/${parentSeg}/${childSeg}`;
+	const leaseId = `${runSeg}__${parentSeg}__${childSeg}`;
+	const registryAbs = join(opts.repoRoot, REGISTRY_DIR);
+	mkdirSync(registryAbs, { recursive: true });
+	const manifestPath = join(registryAbs, `${leaseId}.json`);
+	const manifest = {
+		baseSha,
+		branch,
+		childNodeId: opts.childNodeId,
+		leaseId,
+		owner: OWNER,
+		parentNodeId: opts.parentNodeId,
+		path: relPath,
+		runId: opts.runId,
+		schemaVersion: 1,
+		state: "creating"
+	};
+	writeManifest(manifestPath, manifest);
+	if (!existsSync(absPath)) git(opts.repoRoot, [
+		"worktree",
+		"add",
+		"-b",
+		branch,
+		absPath,
+		baseSha
+	]);
+	writeManifest(manifestPath, {
+		...manifest,
+		state: "active"
+	});
+	return {
+		baseSha,
+		branch,
+		leaseId,
+		path: absPath,
+		release: () => releaseWorktree(opts.repoRoot, manifestPath)
+	};
+}
+/** Idempotent, crash-safe teardown. Retains (never deletes) dirty/unpushed work. */
+function releaseWorktree(repoRoot, manifestPath) {
+	if (!existsSync(manifestPath)) return "removed";
+	const manifest = readManifest(manifestPath);
+	const absPath = join(repoRoot, manifest.path);
+	git(repoRoot, ["worktree", "prune"]);
+	if (!existsSync(absPath)) {
+		writeManifest(manifestPath, {
+			...manifest,
+			state: "removed"
+		});
+		return "removed";
+	}
+	const guarded = retentionState(absPath, manifest.baseSha);
+	if (guarded) {
+		writeManifest(manifestPath, {
+			...manifest,
+			state: guarded
+		});
+		return guarded;
+	}
+	git(repoRoot, [
+		"worktree",
+		"remove",
+		"--force",
+		absPath
+	]);
+	git(repoRoot, [
+		"branch",
+		"-D",
+		manifest.branch
+	]);
+	writeManifest(manifestPath, {
+		...manifest,
+		state: "removed"
+	});
+	return "removed";
+}
+/** Returns a retention reason when the worktree must be kept, else undefined. */
+function retentionState(absPath, baseSha) {
+	if (git(absPath, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	]).length > 0) return "retained-dirty";
+	if (git(absPath, ["rev-parse", "HEAD"]) !== baseSha) return "retained-unpushed";
+}
+/** Startup GC: release every pipeline-owned lease using the same safety guard. */
+function gcParallelWorktrees(repoRoot) {
+	const registryAbs = join(repoRoot, REGISTRY_DIR);
+	if (!existsSync(registryAbs)) return [];
+	const results = readdirSync(registryAbs).sort().filter((file) => file.endsWith(".json")).map((file) => join(registryAbs, file)).filter((manifestPath) => readManifest(manifestPath).owner === OWNER).map((manifestPath) => releaseWorktree(repoRoot, manifestPath));
+	git(repoRoot, ["worktree", "prune"]);
+	return results;
+}
+//#endregion
+export { createChildWorktree, gcParallelWorktrees };

package/dist/runtime/scheduler.js

@@ -15,10 +15,12 @@ var LocalScheduler = class {
 			emitWorkflowStarted: () => options.emitWorkflowStarted(context),
 			executeWorkflow: () => runWorkflowScheduler({
 				failFast: plan.execution.failFast,
+				fanOutWidth: context.config.token_budget?.fan_out_width,
 				isCancelled: () => options.isCancelled(context),
 				markNodeReady: (nodeId) => options.markNodeReady(nodeId, context),
 				maxParallelNodes: context.maxParallelNodes,
 				nodes: plan.topologicalOrder.map((node) => ({
+					category: node.category,
 					dependents: node.dependents,
 					id: node.id,
 					index: node.index,
@@ -38,6 +40,7 @@ async function runWorkflowScheduler(input) {
 		blocked: [],
 		completed: [],
 		failFast: input.failFast,
+		fanOutWidth: input.fanOutWidth,
 		maxParallelNodes: input.maxParallelNodes,
 		nodes: orderedNodes(input.nodes),
 		running: [],
@@ -107,7 +110,7 @@ function unstartedBlockingDescendants(nodeId, context) {
 function launchReadyNodes(input, state, running) {
 	const capacity = workflowNodeCapacity(state);
 	if (capacity <= 0) return;
-	for (const nodeId of readyNodeIds(state).slice(0, capacity)) {
+	for (const nodeId of selectLaunchableNodes(state, capacity)) {
 		input.markNodeReady(nodeId);
 		state.running = [...state.running, nodeId];
 		running.set(nodeId, {
@@ -116,6 +119,50 @@ function launchReadyNodes(input, state, running) {
 		});
 	}
 }
+/**
+* Choose which ready nodes to launch this tick within the global capacity and
+* the per-category fan-out caps. A category at its cap defers its remaining
+* ready nodes to a later tick (it does not drop them). Nodes without a category
+* are bounded only by the global capacity. Without a fanOutWidth (e.g. in tests
+* or configs with no token_budget), this is the prior `slice(0, capacity)`.
+*/
+function selectLaunchableNodes(state, capacity) {
+	const ready = readyNodeIds(state);
+	return state.fanOutWidth ? cappedSelection(ready, capacity, state, state.fanOutWidth) : ready.slice(0, capacity);
+}
+function cappedSelection(ready, capacity, state, fanOut) {
+	const categoryOf = new Map(state.nodes.map((node) => [node.id, node.category]));
+	const counts = categoryRunCounts(state.running, categoryOf);
+	const selected = [];
+	for (const nodeId of ready) {
+		if (selected.length >= capacity) break;
+		if (claimCategorySlot(categoryOf.get(nodeId), fanOut, counts)) selected.push(nodeId);
+	}
+	return selected;
+}
+function categoryCap(category, fanOut) {
+	return fanOut.by_category[category] ?? fanOut.default;
+}
+/**
+* Whether a node of the given category may launch now, consuming a slot from
+* `counts` when it can. Uncategorized nodes always may; a category at its cap
+* may not.
+*/
+function claimCategorySlot(category, fanOut, counts) {
+	if (!category) return true;
+	const current = counts.get(category) ?? 0;
+	if (current >= categoryCap(category, fanOut)) return false;
+	counts.set(category, current + 1);
+	return true;
+}
+function categoryRunCounts(running, categoryOf) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const nodeId of running) {
+		const category = categoryOf.get(nodeId);
+		if (category) counts.set(category, (counts.get(category) ?? 0) + 1);
+	}
+	return counts;
+}
 function dependencyPassed(nodeId, context) {
 	const result = (context.completed ?? []).find((item) => item.nodeId === nodeId);
 	return result ? context.shouldContinueAfterNodeResult?.(result) ?? result.status !== "failed" : false;

package/dist/runtime/select-candidate/select-candidate.js

@@ -0,0 +1,58 @@
+import { parseJsonObject } from "../json-validation/json-validation.js";
+import "../json-validation/index.js";
+//#region src/runtime/select-candidate/select-candidate.ts
+function selectBestCandidate(candidates) {
+	const passing = candidates.filter((candidate) => candidate.status === "PASS");
+	if (passing.length === 0) return null;
+	return passing.reduce((best, candidate) => (candidate.judgeScore ?? 0) > (best.judgeScore ?? 0) ? candidate : best);
+}
+function executeSelectCandidateBuiltin(context, node) {
+	const candidates = readCandidates(context, node?.needs.at(0) ?? null);
+	const selected = selectBestCandidate(candidates);
+	if (!selected) return {
+		evidence: [`select-candidate: no passing candidate among ${candidates.length}`, ...candidates.map((candidate) => `- ${candidate.nodeId}: FAIL`)],
+		exitCode: 1,
+		output: ""
+	};
+	return {
+		evidence: [`select-candidate: selected '${selected.nodeId}' (judge=${selected.judgeScore ?? "n/a"}) from ${candidates.length} candidates`],
+		exitCode: 0,
+		output: selected.output
+	};
+}
+function readCandidates(context, upstreamNodeId) {
+	if (!upstreamNodeId) return [];
+	const upstream = context.plan.graph.node(upstreamNodeId);
+	const childrenOutput = parseJsonObject(parseJsonObject(context.nodeStateStore.getOutput(upstreamNodeId)).children);
+	return (upstream?.children ?? []).flatMap((child) => {
+		const raw = childrenOutput[child.id];
+		return raw === void 0 ? [] : [parseCandidate(child.id, raw)];
+	});
+}
+function parseCandidate(nodeId, raw) {
+	const output = typeof raw === "string" ? raw : JSON.stringify(raw);
+	const parsed = safeParseObject(output);
+	return {
+		judgeScore: candidateJudgeScore(parsed),
+		nodeId,
+		output,
+		status: candidateStatus(parsed)
+	};
+}
+function candidateStatus(parsed) {
+	if (!parsed) return "PASS";
+	return parsed.verdict === "FAIL" || parsed.status === "FAIL" ? "FAIL" : "PASS";
+}
+function candidateJudgeScore(parsed) {
+	return typeof parsed?.judge_score === "number" ? parsed.judge_score : null;
+}
+function safeParseObject(text) {
+	try {
+		const value = JSON.parse(text);
+		return value && typeof value === "object" ? value : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { executeSelectCandidateBuiltin };