@tangle-network/agent-runtime 0.121.0 → 0.123.1

package/dist/{runtime-Bp3NwC0A.js → runtime-DZblIf3R.js}

@@ -1,16 +1,16 @@
 import { n as AnalystError, r as BackendTransportError, s as PlannerError, u as ValidationError } from "./errors-DEAvWQPy.js";
 import { i as normalizeBackendStreamEvent, o as newRuntimeSession, s as nowIso } from "./backends-CiOCyRHb.js";
-import { i as InMemorySpawnJournal, r as InMemoryResultBlobStore, v as isTraceAnalysisStore } from "./spawn-journal-IeXpidO2.js";
+import { i as InMemorySpawnJournal, r as InMemoryResultBlobStore, v as isTraceAnalysisStore } from "./spawn-journal-DsZKDqeh.js";
 import { a as randomSuffix, c as stringifySafe, f as zeroTokenUsage, r as isAbortError, s as sleep, t as addTokenUsage } from "./util-MVgdwuIS.js";
 import { i as redactProtectedValue, r as redactProtectedReason } from "./protected-redaction--F3v1oo8.js";
-import { X as rollingDispatch, dt as routerBrain, gt as runBrainLoop, l as withDriverExecutor, m as settledToIteration, n as createSupervisor, pt as routerChatWithUsage } from "./supervisor-CpT9yAxL.js";
-import { C as observe, O as strategyAuthorMethod, b as sample, v as refine, x as sampleThenRefine, y as runAgentic } from "./structural-rollout-DQHO3b2Y.js";
-import { i as notifyRuntimeHookEvent } from "./runtime-hooks-C7iJOWm3.js";
+import { _t as routerChatWithUsage, bt as runBrainLoop, en as isHarnessNativeModel, et as rollingDispatch, ht as routerBrain, l as withDriverExecutor, m as settledToIteration, n as createSupervisor } from "./supervisor-DpjO0Gmy.js";
+import { C as observe, O as strategyAuthorMethod, b as sample, v as refine, x as sampleThenRefine, y as runAgentic } from "./structural-rollout-zY0oqQzO.js";
+import { i as notifyRuntimeHookEvent, t as composeRuntimeHooks } from "./runtime-hooks-C7iJOWm3.js";
 import { a as notifySandboxEventObserver, i as mapSandboxToolEvent, r as mapSandboxEvent, t as createSandboxToolPartState } from "./sandbox-events-Yhd1GYWl.js";
-import { At as runAgentRounds, Kt as gateOnDeliverable, Mt as createSandboxLineage, Nt as probeSandboxCapabilities, bt as createExecutorRegistry, kt as defaultSelectWinner, n as supervise, wt as createPushTraceSource, xt as createWorktreeCliExecutor, yt as createExecutor } from "./supervise-BHHMtwP9.js";
+import { Ct as createWorktreeCliExecutor, Et as createPushTraceSource, Ft as probeSandboxCapabilities, Mt as runAgentRounds, Pt as createSandboxLineage, Qt as kernelPromptRegistry, St as createExecutorRegistry, Zt as formatPromptHandle, jt as defaultSelectWinner, n as supervise, nn as gateOnDeliverable, r as workerFromBackend, xt as createExecutor } from "./supervise-Cx24b3lw.js";
 import { CODING_HARNESSES, InMemoryTraceStore, OUTPUT_VALUE, benjaminiHochberg, buildTrajectory, computeFindingId as computeFindingId$1, confidenceInterval, expandProfileAxes, harnessAxisOf, makeFinding as makeFinding$1, pairedBootstrap, paretoFrontier, scoreKnowledgeReadiness, wilcoxonSignedRank, wilson } from "@tangle-network/agent-eval";
 import { heldoutSignificance, runProfileMatrix } from "@tangle-network/agent-eval/campaign";
-import { canonicalCandidateDigest, validateAgentProfileSecurity } from "@tangle-network/agent-interface";
+import { agentProfileSchema, canonicalCandidateDigest, validateAgentProfileSecurity } from "@tangle-network/agent-interface";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { appendFileSync, chmodSync, constants, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -1297,6 +1297,36 @@ function resolveSandboxClient(opts) {
 //#endregion
 //#region src/runtime/steering-drivers.ts
 /**
+* Interpret a {@link SteeringDirectiveData} as a loop `Driver` — the ONE interpreter both
+* control policies share. The directive is data; only `applyContinuation` (how the caller's
+* opaque Task carries a steering string) remains code, exactly as `taskToPrompt` does.
+*/
+function steeringDriver(directive, applyContinuation, name) {
+	const driverName = name ?? directive.kind;
+	const maxIterations = directive.maxTraversals;
+	const continuationFor = (passed) => directive.kind === "naive" ? directive.continuation : passed ? directive.onPass : directive.onFail;
+	const rationale = directive.kind === "naive" ? "naive fixed continuation (no grade signal)" : "dumb pass/fail-only continuation (no grader findings)";
+	return {
+		name: driverName,
+		plan(task, history) {
+			if (history.length === 0) return Promise.resolve([task]);
+			const passed = history[history.length - 1]?.verdict?.valid === true;
+			if (passed) return Promise.resolve([]);
+			if (history.length >= maxIterations) return Promise.resolve([]);
+			return Promise.resolve([applyContinuation(task, continuationFor(passed))]);
+		},
+		decide(history) {
+			return decideUntilValidOrCapped(history, maxIterations);
+		},
+		describePlan() {
+			return {
+				kind: "refine",
+				rationale
+			};
+		}
+	};
+}
+/**
 * Shared `decide()` for the steering drivers. Verbatim semantics of the
 * reference refine driver: a valid iteration anywhere → terminal `'pick-winner'`;
 * otherwise `'refine'` (non-terminal, run another shot) while history is under
@@ -1318,26 +1348,17 @@ function decideUntilValidOrCapped(history, maxIterations) {
 * attributable to the pass/fail bit, and any lift of `refine` over `dumb` is
 * attributable to the grader's findings.
 */
+/** Thin compatibility wrapper over {@link steeringDriver} for the naive (no-signal) control.
+*  @deprecated The policy is DATA now — build the directive and interpret it:
+*  `steeringDriver({ kind: 'naive', continuation, maxTraversals }, applyContinuation)`. This
+*  wrapper survives for existing callers and will be removed in the next major. */
 function naiveDriver(options) {
 	const { continuation, applyContinuation, maxIterations, name = "naive" } = options;
-	return {
-		name,
-		plan(task, history) {
-			if (history.length === 0) return Promise.resolve([task]);
-			if (history[history.length - 1]?.verdict?.valid) return Promise.resolve([]);
-			if (history.length >= maxIterations) return Promise.resolve([]);
-			return Promise.resolve([applyContinuation(task, continuation)]);
-		},
-		decide(history) {
-			return decideUntilValidOrCapped(history, maxIterations);
-		},
-		describePlan() {
-			return {
-				kind: "refine",
-				rationale: "naive fixed continuation (no grade signal)"
-			};
-		}
-	};
+	return steeringDriver({
+		kind: "naive",
+		continuation,
+		maxTraversals: maxIterations
+	}, applyContinuation, name);
 }
 /**
 * `dumbDriver` — the pass/fail-only steering control.
@@ -1353,28 +1374,18 @@ function naiveDriver(options) {
 * grader's `notes`, dumb reads only the pass/fail bit, so the difference is
 * exactly the value the findings add over a bare boolean.
 */
+/** Thin compatibility wrapper over {@link steeringDriver} for the dumb (pass/fail-only) control.
+*  @deprecated The policy is DATA now — build the directive and interpret it:
+*  `steeringDriver({ kind: 'dumb', onPass, onFail, maxTraversals }, applyContinuation)`. This
+*  wrapper survives for existing callers and will be removed in the next major. */
 function dumbDriver(options) {
 	const { onPass, onFail, applyContinuation, maxIterations, name = "dumb" } = options;
-	return {
-		name,
-		plan(task, history) {
-			if (history.length === 0) return Promise.resolve([task]);
-			const passed = history[history.length - 1]?.verdict?.valid === true;
-			if (passed) return Promise.resolve([]);
-			if (history.length >= maxIterations) return Promise.resolve([]);
-			const continuation = passed ? onPass : onFail;
-			return Promise.resolve([applyContinuation(task, continuation)]);
-		},
-		decide(history) {
-			return decideUntilValidOrCapped(history, maxIterations);
-		},
-		describePlan() {
-			return {
-				kind: "refine",
-				rationale: "dumb pass/fail-only continuation (no grader findings)"
-			};
-		}
-	};
+	return steeringDriver({
+		kind: "dumb",
+		onPass,
+		onFail,
+		maxTraversals: maxIterations
+	}, applyContinuation, name);
 }
 //#endregion
 //#region src/runtime/define-leaderboard.ts
@@ -1383,7 +1394,7 @@ function dumbDriver(options) {
 *
 * A product's harness×model leaderboard is always the same assembly: expand a
 * base profile across the harness×model axes (`expandProfileAxes`), run every
-* (profile, case) cell as a driven loop (`loopDispatch` + `naiveDriver`), score
+* (profile, case) cell as a driven loop (`loopDispatch` + the naive steering directive), score
 * with the domain's grader, and emit ONE `runProfileMatrix` call. Each product
 * hand-rolled that assembly (~650 lines each) and re-hit the same footguns:
 * stale cell-cache reuse, zero-token stub cells, missing model snapshots.
@@ -1572,21 +1583,22 @@ function defineLeaderboard(spec) {
 				toLoopOptions: (cellScenario, cellProfile) => {
 					const axis = harnessAxisOf(cellProfile);
 					const modelId = bareModel(axis?.model ?? models[0] ?? "");
+					const backendModel = {
+						...spec.modelBackend,
+						...!isHarnessNativeModel(modelId) || backendName === "cli-bridge" ? { model: modelId } : {}
+					};
 					return {
-						driver: naiveDriver({
+						driver: steeringDriver({
+							kind: "naive",
 							continuation: "",
-							applyContinuation: (task) => task,
-							maxIterations: shots
-						}),
+							maxTraversals: shots
+						}, (task) => task, "naive"),
 						agentRun: {
 							profile: cellProfile,
 							taskToPrompt: (s) => `${promptOf(s)}\n\n<!-- independent-attempt:${shotNonce++} -->`,
 							...axis ? { sandboxOverrides: { backend: {
 								type: axis.harness,
-								model: {
-									...spec.modelBackend,
-									model: modelId
-								}
+								...Object.keys(backendModel).length > 0 ? { model: backendModel } : {}
 							} } } : {}
 						},
 						output: { parse: (events) => spec.parseOutput ? spec.parseOutput(events, cellScenario.case) : collectAgentResponseText(events) ?? "" },
@@ -2904,7 +2916,7 @@ async function trajectoryReport(journal, blobs, root, options = {}) {
 	const events = await journal.loadTree(root);
 	if (events === void 0) throw new Error(`trajectoryReport: no journaled tree for root '${root}'`);
 	const spawns = events.filter(isNodeCreation).sort(bySeq);
-	const closes = events.filter((ev) => ev.kind !== "spawned" && ev.kind !== "waiting" && ev.kind !== "metered" && ev.kind !== "materialized" && ev.kind !== "execution-bound").sort(bySeq);
+	const closes = events.filter((ev) => ev.kind !== "spawned" && ev.kind !== "waiting" && ev.kind !== "metered" && ev.kind !== "materialized" && ev.kind !== "execution-bound" && ev.kind !== "edge" && ev.kind !== "trace-unpropagated").sort(bySeq);
 	const nodes = /* @__PURE__ */ new Map();
 	for (const ev of spawns) nodes.set(ev.id, {
 		id: ev.id,
@@ -4648,6 +4660,406 @@ function deriveTurnSignal(callerSignal, timeoutMs) {
 	};
 }
 //#endregion
+//#region src/runtime/supervise/graph.ts
+/**
+*
+* `runGraph` — agent graphs: profiles as nodes, registry-backed prompt directives as edges.
+*
+* A topology is PLAIN DATA an agent can author in a few lines: nodes are canonical
+* `AgentProfile`s (the ONLY way a node is described — no role-builder functions), edges are typed
+* values carrying versioned {@link PromptHandle} directives, `deliverable` (termination) and
+* `budget` (one conserved pool) are mandatory. Driver↔worker is the two-node cyclic instance;
+* "agent 3 analyzes 1 and 2 and reports to 1" is ONE edge, not a framework.
+*
+* NOT A SECOND SCHEDULER. `runGraph` is an interpretation layer over what already runs:
+* `supervise()` is the execution core — the same `supervisorAgent`/`driverAgent` machinery,
+* `makeWorkerAgent` seam, conserved-pool budget, and deliverable-gated settlement every
+* supervised run uses. (`runLoop` is a deprecated alias of `runAgentRounds` and is deliberately
+* NOT the substrate here.) What the graph layer ADDS is exactly what a bespoke driver loop never
+* had:
+*
+*  1. **Node pinning** — a spawn names a node (`profile.name` = node id) and the node's canonical
+*     profile is what runs; a driver cannot smuggle capabilities into a worker it did not define.
+*  2. **Observable edges** — every delegates/analyzes traversal lands in an EDGE LEDGER
+*     (`delivered | stripped | empty | unpropagated`, with byte counts), in memory on
+*     the result AND as `edge` events in the run journal. The motivating incident: a filter
+*     silently replaced 1,700-char steering with 241 chars of boilerplate for three rounds and
+*     NO artifact said so — an unobservable edge cannot be trusted and its directive cannot be
+*     optimized.
+*  3. **Directives as data** — edge text lives in the prompt registry (`<surface>/v<n>`), so every
+*     edge is a versioned optimization target, never prose hardcoded in a builder function.
+*  4. **Per-edge traversal caps** — the cyclic-graph backstop. A delegates edge whose cap is
+*     exhausted REFUSES further traversals (fail loud), so a cycle cannot spin the pool dry.
+*
+* ORACLES ARE ENVIRONMENT, NEVER NODES. Graders/verifiers must not be addressable in the graph —
+* an edge to them leaks the rubric. Analysts (`analyzes` edges) are LENSES from the environment's
+* registry reading trace evidence; they are not nodes either, and a graph that names a node id as
+* its analyst is refused.
+*
+* @experimental
+*/
+/** Default per-edge traversal cap — the cyclic-graph backstop when an edge names none. */
+const defaultEdgeTraversalCap = 32;
+/** A delegates edge exhausted its traversal cap and the run produced no winner: the cap, not the
+*  task, ended it. Carries the full evidence so failing loud loses nothing. */
+var GraphEdgeCapError = class extends Error {
+	exhaustedEdges;
+	ledger;
+	result;
+	constructor(exhaustedEdges, ledger, result) {
+		super(`runGraph: edge traversal cap exhausted on ${exhaustedEdges.join(", ")} and the run delivered no winner — the cap (the cyclic-graph backstop), not the task, ended this run. Raise maxTraversals on the edge or fix the cycle; the full edge ledger and the supervised result ride on this error.`);
+		this.name = "GraphEdgeCapError";
+		this.exhaustedEdges = exhaustedEdges;
+		this.ledger = ledger;
+		this.result = result;
+	}
+};
+function edgeId(edge) {
+	return edge.kind === "delegates" ? `delegates:${edge.from}->${edge.to}` : `analyzes:${edge.analyst}:${edge.over.join("+")}->${edge.to}`;
+}
+/** Validate the graph and resolve every directive BEFORE any compute is spent — an invalid
+*  topology or an unknown directive is a configuration fault, never a mid-run surprise. */
+function validateGraph(graph, registry, analysts) {
+	if (!Array.isArray(graph.nodes) || graph.nodes.length === 0) throw new ValidationError("runGraph: graph.nodes must be a non-empty array");
+	if (!Array.isArray(graph.edges) || graph.edges.length === 0) throw new ValidationError("runGraph: graph.edges must be a non-empty array");
+	if (typeof graph.deliverable?.check !== "function") throw new ValidationError("runGraph: graph.deliverable is mandatory (termination oracle)");
+	if (typeof graph.budget !== "object" || graph.budget === null) throw new ValidationError("runGraph: graph.budget is mandatory (the conserved pool)");
+	const byId = /* @__PURE__ */ new Map();
+	for (const node of graph.nodes) {
+		if (typeof node.id !== "string" || node.id.length === 0) throw new ValidationError("runGraph: every node needs a non-empty string id");
+		if (byId.has(node.id)) throw new ValidationError(`runGraph: duplicate node id '${node.id}'`);
+		const parsed = agentProfileSchema.safeParse(node.profile);
+		if (!parsed.success) throw new ValidationError(`runGraph: node '${node.id}' has an invalid AgentProfile: ${parsed.error.message}`);
+		if (node.profile.name !== node.id) throw new ValidationError(`runGraph: node '${node.id}' has profile.name ${JSON.stringify(node.profile.name)} — profile.name IS the node identity (node pinning and analyst routing match on it) and must equal the node id`);
+		byId.set(node.id, node);
+	}
+	const requireNode = (id, where) => {
+		const node = byId.get(id);
+		if (!node) throw new ValidationError(`runGraph: ${where} references unknown node '${id}'`);
+		return node;
+	};
+	const delegates = graph.edges.filter((edge) => edge.kind === "delegates");
+	const analyzes = graph.edges.filter((edge) => edge.kind === "analyzes");
+	if (delegates.length === 0) throw new ValidationError("runGraph: at least one delegates edge is required (who spawns whom)");
+	for (const edge of graph.edges) registry.resolve(edge.directive);
+	for (const edge of delegates) {
+		requireNode(edge.from, edgeId(edge));
+		requireNode(edge.to, edgeId(edge));
+		if (edge.from === edge.to) throw new ValidationError(`runGraph: ${edgeId(edge)} delegates to itself — the driver↔worker cycle is the settle-return loop, not a self-edge`);
+	}
+	const delegatedTo = new Set(delegates.map((edge) => edge.to));
+	const roots = [...new Set(delegates.map((edge) => edge.from))].filter((id) => !delegatedTo.has(id));
+	if (roots.length !== 1) throw new ValidationError(`runGraph: expected exactly ONE root (a node that delegates and is never delegated to), found ${roots.length === 0 ? "none — delegates edges form a cycle with no entry" : roots.join(", ")}. P0 executes driver↔worker(s); nested driver graphs are P3.`);
+	const root = requireNode(roots[0], "root resolution");
+	for (const edge of delegates) if (edge.from !== root.id) throw new ValidationError(`runGraph: ${edgeId(edge)} delegates from a non-root node — P0 executes one driver over its workers (the 2-node cyclic case, star-generalized); deeper delegation is P3`);
+	const analystIds = /* @__PURE__ */ new Set();
+	for (const edge of analyzes) {
+		if (analystIds.has(edge.analyst)) throw new ValidationError(`runGraph: two analyzes edges share analyst '${edge.analyst}' — one analyzes edge per analyst lens (traversals are ledgered by analyst id; a second edge would silently absorb the first's). Register the lens under a second id for a second edge.`);
+		analystIds.add(edge.analyst);
+		if (byId.has(edge.analyst)) throw new ValidationError(`runGraph: ${edgeId(edge)} names node '${edge.analyst}' as its analyst — oracles and analysts are ENVIRONMENT, never nodes; pass a lens id from RunGraphOptions.analysts`);
+		if (!analysts) throw new ValidationError(`runGraph: ${edgeId(edge)} needs RunGraphOptions.analysts (the lens registry its analyst resolves against)`);
+		if (!analysts.kinds.some((kind) => kind.id === edge.analyst)) throw new ValidationError(`runGraph: ${edgeId(edge)} analyst '${edge.analyst}' is not in the analysts registry (known: ${analysts.kinds.map((kind) => kind.id).join(", ") || "none"})`);
+		if (edge.over.length === 0) throw new ValidationError(`runGraph: ${edgeId(edge)} must analyze at least one node`);
+		for (const over of edge.over) requireNode(over, edgeId(edge));
+		requireNode(edge.to, edgeId(edge));
+	}
+	const workers = /* @__PURE__ */ new Map();
+	const delegatesByWorker = /* @__PURE__ */ new Map();
+	for (const edge of delegates) {
+		if (delegatesByWorker.has(edge.to)) throw new ValidationError(`runGraph: node '${edge.to}' is the target of two delegates edges — one delegation directive per worker node (version the directive instead of forking the edge)`);
+		delegatesByWorker.set(edge.to, edge);
+		workers.set(edge.to, requireNode(edge.to, edgeId(edge)));
+	}
+	for (const node of graph.nodes) if (node.id !== root.id && !workers.has(node.id)) throw new ValidationError(`runGraph: node '${node.id}' has no delegates edge to it — an unreachable node never runs`);
+	return {
+		root,
+		workers,
+		delegatesByWorker,
+		analyzes
+	};
+}
+const byteLength = (text) => Buffer.byteLength(text, "utf8");
+function stringifyPayload(payload) {
+	if (typeof payload === "string") return payload;
+	try {
+		return JSON.stringify(payload) ?? String(payload);
+	} catch {
+		return String(payload);
+	}
+}
+/**
+* Execute an {@link AgentGraph}. The root node becomes the supervisor (`supervise()` — the
+* execution core), each worker node is spawnable BY NODE ID (`spawn_agent` with
+* `profile: { name: '<node id>' }`; the node's canonical profile is pinned by the graph), each
+* delegates directive is appended to the worker profile's `prompt.instructions` per traversal,
+* and each analyzes edge becomes an analyst-on-settle route with a real DESTINATION. Every
+* traversal is ledgered and journaled.
+*/
+function runGraph(graph, opts) {
+	const registry = opts.registry ?? kernelPromptRegistry();
+	const { root, workers, delegatesByWorker, analyzes } = validateGraph(graph, registry, opts.analysts);
+	if (!opts.backend && !opts.makeWorkerAgent) throw new ValidationError("runGraph: provide opts.backend (where nodes run) or opts.makeWorkerAgent");
+	const journal = opts.journal ?? new InMemorySpawnJournal();
+	const blobs = opts.blobs ?? new InMemoryResultBlobStore();
+	const runId = opts.runId ?? `graph-${canonicalCandidateDigest(graph.nodes.map((n) => n.id)).slice(7, 19)}`;
+	const now = opts.now ?? Date.now;
+	const ledger = [];
+	const journaled = /* @__PURE__ */ new Set();
+	const traversalCounts = /* @__PURE__ */ new Map();
+	const exhausted = /* @__PURE__ */ new Set();
+	const exhaustedDelegates = /* @__PURE__ */ new Set();
+	const journalWrites = [];
+	let ledgerSeq = 0;
+	const appendJournal = (entry, nodeIdForEvent) => {
+		if (journaled.has(entry)) return Promise.resolve();
+		journaled.add(entry);
+		const write = journal.appendEvent(runId, {
+			kind: "edge",
+			id: nodeIdForEvent,
+			edge: {
+				kind: entry.kind,
+				from: entry.from,
+				to: entry.to,
+				directive: entry.directive
+			},
+			traversal: entry.traversal,
+			outcome: entry.outcome,
+			bytes: entry.bytes,
+			...entry.reason !== void 0 ? { reason: entry.reason } : {},
+			seq: ledgerSeq++,
+			at: new Date(now()).toISOString()
+		});
+		journalWrites.push(write);
+		return write;
+	};
+	const record = (entry, journalNow) => {
+		const count = (traversalCounts.get(entry.edge) ?? 0) + 1;
+		traversalCounts.set(entry.edge, count);
+		const row = {
+			...entry,
+			traversal: count
+		};
+		ledger.push(row);
+		if (journalNow) appendJournal(row, row.workerId ?? `graph:${row.to}`);
+		return row;
+	};
+	const makeLeaf = opts.makeWorkerAgent ?? workerFromBackend(opts.backend, graph.deliverable);
+	const nodeByWorkerId = /* @__PURE__ */ new Map();
+	const pendingByAssignment = /* @__PURE__ */ new Map();
+	const graphWorker = (authoredProfile, spawnContext) => {
+		const requested = typeof authoredProfile?.name === "string" ? authoredProfile.name : void 0;
+		const node = requested !== void 0 ? workers.get(requested) : void 0;
+		if (!node) throw new ValidationError(`runGraph: spawn_agent named profile ${JSON.stringify(requested)} which is not a worker node of this graph (nodes: ${[...workers.keys()].join(", ")}). Spawn by node id: profile.name selects the node; the node profile itself is pinned by the graph.`);
+		const edge = delegatesByWorker.get(node.id);
+		const id = edgeId(edge);
+		const cap = edge.maxTraversals ?? 32;
+		if ((traversalCounts.get(id) ?? 0) >= cap) {
+			exhausted.add(id);
+			exhaustedDelegates.add(id);
+			record({
+				edge: id,
+				kind: "delegates",
+				from: edge.from,
+				to: edge.to,
+				directive: formatPromptHandle(edge.directive),
+				outcome: "unpropagated",
+				bytes: 0,
+				reason: `traversal-cap-exhausted (max ${cap})`
+			}, true);
+			throw new ValidationError(`runGraph: delegates edge ${id} exhausted its traversal cap (${cap}) — the cyclic-graph backstop refused this spawn`);
+		}
+		const directiveText = registry.resolve(edge.directive).text;
+		const taskText = stringifyPayload(spawnContext?.task);
+		const bytes = byteLength(directiveText) + byteLength(taskText);
+		const row = record({
+			edge: id,
+			kind: "delegates",
+			from: edge.from,
+			to: edge.to,
+			directive: formatPromptHandle(edge.directive),
+			outcome: bytes === 0 ? "empty" : "delivered",
+			bytes,
+			...bytes === 0 ? { reason: "no directive text and no task payload" } : {}
+		}, false);
+		if (spawnContext?.assignmentId !== void 0) pendingByAssignment.set(spawnContext.assignmentId, row);
+		else appendJournal(row, `graph:${row.to}`);
+		const pinned = directiveText.length === 0 ? node.profile : {
+			...node.profile,
+			prompt: {
+				...node.profile.prompt ?? {},
+				instructions: [...node.profile.prompt?.instructions ?? [], directiveText]
+			}
+		};
+		return makeLeaf(pinned, spawnContext);
+	};
+	const routes = analyzes.map((edge) => edge.to === root.id ? {
+		kind: edge.analyst,
+		over: edge.over
+	} : {
+		kind: edge.analyst,
+		over: edge.over,
+		to: edge.to,
+		directive: registry.resolve(edge.directive).text
+	});
+	const driverAnalyzesBriefs = analyzes.filter((edge) => edge.to === root.id).map((edge) => `Findings from analyst '${edge.analyst}' (over: ${edge.over.join(", ")}) will arrive as finding events.\n${registry.resolve(edge.directive).text}`);
+	const graphBrief = [
+		"AGENT GRAPH: you are the driver node of a fixed topology. You may spawn ONLY these worker",
+		"nodes, by EXACT name (spawn_agent with profile: { name: '<node id>' }; the node's full",
+		"profile is pinned by the graph — any other profile fields you author are ignored):",
+		...[...workers.values()].map((node) => {
+			const cap = delegatesByWorker.get(node.id).maxTraversals ?? 32;
+			const description = typeof node.profile.description === "string" && node.profile.description.length > 0 ? ` — ${node.profile.description}` : "";
+			return `- '${node.id}'${description} (delegation cap: ${cap} traversals)`;
+		}),
+		...driverAnalyzesBriefs.length > 0 ? ["", ...driverAnalyzesBriefs] : []
+	].join("\n");
+	const rootProfile = {
+		...root.profile,
+		prompt: {
+			...root.profile.prompt ?? {},
+			instructions: [...root.profile.prompt?.instructions ?? [], graphBrief]
+		}
+	};
+	const strippedByDigest = /* @__PURE__ */ new Map();
+	const authorizeMessage = opts.authorizeMessage ? (input) => {
+		const decision = opts.authorizeMessage(input);
+		if (decision.instruction !== input.instruction) strippedByDigest.set(canonicalCandidateDigest(decision.instruction), { composedBytes: byteLength(input.instruction) });
+		return decision;
+	} : void 0;
+	const routedAnalyzesByAnalyst = /* @__PURE__ */ new Map();
+	const driverAnalyzesByAnalyst = /* @__PURE__ */ new Map();
+	for (const edge of analyzes) (edge.to === root.id ? driverAnalyzesByAnalyst : routedAnalyzesByAnalyst).set(edge.analyst, edge);
+	const analyzesCapReached = (edge) => {
+		const cap = edge.maxTraversals ?? 32;
+		if ((traversalCounts.get(edgeId(edge)) ?? 0) < cap) return false;
+		exhausted.add(edgeId(edge));
+		return true;
+	};
+	const ledgerAnalyzes = (edge, outcome, bytes, reason, workerId) => {
+		const capped = analyzesCapReached(edge);
+		record({
+			edge: edgeId(edge),
+			kind: "analyzes",
+			from: edge.over.join("+"),
+			to: edge.to,
+			directive: formatPromptHandle(edge.directive),
+			outcome: capped ? "unpropagated" : outcome,
+			bytes,
+			...capped ? { reason: `traversal-cap-exhausted (max ${edge.maxTraversals ?? 32})` } : reason !== void 0 ? { reason } : {},
+			...workerId !== void 0 ? { workerId } : {}
+		}, true);
+	};
+	const onCoordinationEvent = async (_context, _eventId, recordEnvelope) => {
+		const event = recordEnvelope.event;
+		if (event.type === "finding") {
+			const edge = driverAnalyzesByAnalyst.get(event.finding.analyst);
+			if (!edge) return;
+			const sourceNode = nodeByWorkerId.get(event.finding.fromWorker);
+			if (sourceNode === void 0 || !edge.over.includes(sourceNode)) return;
+			const findingsText = event.finding.findings === void 0 ? "" : stringifyPayload(event.finding.findings);
+			const directiveBytes = byteLength(registry.resolve(edge.directive).text);
+			const empty = findingsText.length === 0;
+			ledgerAnalyzes(edge, empty ? "empty" : "delivered", directiveBytes + byteLength(findingsText), empty ? "analyst returned no findings" : void 0, event.finding.fromWorker);
+			return;
+		}
+		if (event.type === "steer") {
+			const down = event.down;
+			if (event.analyst !== void 0) {
+				const edge = routedAnalyzesByAnalyst.get(event.analyst);
+				if (!edge) return;
+				ledgerAnalyzes(edge, down.delivered ? "delivered" : "unpropagated", byteLength(down.instruction), down.delivered ? void 0 : down.outcome, down.toWorker);
+				return;
+			}
+			const nodeId = nodeByWorkerId.get(down.toWorker);
+			if (nodeId === void 0) return;
+			const edge = delegatesByWorker.get(nodeId);
+			if (!edge) return;
+			const stripped = strippedByDigest.get(down.instructionDigest);
+			record({
+				edge: edgeId(edge),
+				kind: "delegates",
+				from: edge.from,
+				to: edge.to,
+				directive: formatPromptHandle(edge.directive),
+				outcome: !down.delivered ? "unpropagated" : stripped ? "stripped" : "delivered",
+				bytes: byteLength(down.instruction),
+				...!down.delivered ? { reason: down.outcome } : stripped ? { reason: `authorization narrowed ${stripped.composedBytes} composed bytes` } : {},
+				workerId: down.toWorker
+			}, true);
+		}
+	};
+	const hooks = composeRuntimeHooks({ onEvent: (event) => {
+		if (event.target !== "agent.spawn" || event.phase !== "after") return;
+		const payload = event.payload;
+		if (typeof payload?.childId !== "string" || typeof payload.assignmentId !== "string") return;
+		const pending = pendingByAssignment.get(payload.assignmentId);
+		if (!pending) return;
+		pendingByAssignment.delete(payload.assignmentId);
+		const bound = {
+			...pending,
+			workerId: payload.childId
+		};
+		ledger[ledger.indexOf(pending)] = bound;
+		nodeByWorkerId.set(payload.childId, bound.to);
+		return appendJournal(bound, payload.childId);
+	} }, opts.hooks);
+	const start = async () => {
+		const result = await supervise(rootProfile, graphTask(graph, root), {
+			budget: graph.budget,
+			deliverable: graph.deliverable,
+			makeWorkerAgent: graphWorker,
+			journal,
+			blobs,
+			runId,
+			hooks,
+			onCoordinationEvent,
+			...routes.length > 0 && opts.analysts ? {
+				analysts: opts.analysts,
+				analyzeOnSettle: routes
+			} : {},
+			...opts.router ? { router: opts.router } : {},
+			...opts.brain ? { brain: opts.brain } : {},
+			...authorizeMessage ? { authorizeMessage } : {},
+			...opts.perWorker ? { perWorker: opts.perWorker } : {},
+			...opts.maxTurns !== void 0 ? { maxTurns: opts.maxTurns } : {},
+			...opts.maxLiveWorkers !== void 0 ? { maxLiveWorkers: opts.maxLiveWorkers } : {},
+			...opts.signal ? { signal: opts.signal } : {},
+			...opts.now ? { now: opts.now } : {},
+			...opts.otel ? { otel: opts.otel } : {},
+			...opts.stallAfterMs !== void 0 ? { stallAfterMs: opts.stallAfterMs } : {},
+			...opts.allowedModels ? { allowedModels: opts.allowedModels } : {}
+		});
+		for (const pending of pendingByAssignment.values()) {
+			const refused = {
+				...pending,
+				outcome: "unpropagated",
+				bytes: 0,
+				reason: `no-live-worker-bound (spawn refused after the factory, or a keyed re-spawn deduplicated to a completed result; ${pending.bytes} composed bytes never crossed)`
+			};
+			ledger[ledger.indexOf(pending)] = refused;
+			await appendJournal(refused, `graph:${refused.to}`);
+		}
+		pendingByAssignment.clear();
+		await Promise.all(journalWrites);
+		const exhaustedEdges = Object.freeze([...exhausted]);
+		const frozenLedger = Object.freeze(ledger.map((row) => Object.freeze({ ...row })));
+		const lifecycleEnded = result.kind === "no-winner" && (result.reason === "aborted" || result.reason === "budget-exhausted");
+		if (result.kind !== "winner" && !lifecycleEnded && exhaustedDelegates.size > 0) throw new GraphEdgeCapError(Object.freeze([...exhaustedDelegates]), frozenLedger, result);
+		return {
+			result,
+			ledger: frozenLedger,
+			exhaustedEdges,
+			runId
+		};
+	};
+	return start();
+}
+/** The root task: the graph's own framing. The deliverable (mandatory) is the termination; the
+*  task names what the topology exists to produce. */
+function graphTask(graph, root) {
+	return graph.deliverable.describe ?? `Deliver the graph's deliverable by driving your worker nodes (root: '${root.id}').`;
+}
+//#endregion
 //#region src/runtime/supervise/patch-checks.ts
 const DEFAULT_MAX_DIFF_LINES = 400;
 /**
@@ -5777,6 +6189,6 @@ function tail(s) {
 	return s.slice(-400);
 }
 //#endregion
-export { verify as $, authorStrategy as A, createMcpEnvironment as At, runPersonified as B, collectAgentTurn as C, renderLeaderboardSvg as Ct, runStrategyEvolution as D, McpSpawnFault as Dt, pickChampion as E, defaultAuditorInstruction as Et, runBenchmark as F, resolveSecretEnv as Ft, InMemoryCorpus as G, createShapeRegistry as H, promotionGate as I, secretEnvOfMcpServer as It, flatWidenGate as J, renderCorpusToInstructions as K, equalKOnCost as L, SandboxRunAbortError as M, envKeyProvider as Mt, openSandboxRun as N, mcpSecretEnvMetadataKey as Nt, selectChampion as O, connectStdioMcp as Ot, printBenchmarkReport as P, resolveMcpServerLaunch as Pt, selectValidWinner as Q, trajectoryReport as R, runCoderChecks as S, renderLeaderboardMarkdown as St, discriminatingMeans as T, auditIntent as Tt, registerShape as U, builtinShapes as V, FileCorpus as W, panel as X, loopUntil as Y, pipeline as Z, settledWorkerOut as _, sentinelCompletion as _t, localShell as a, inProcessSandboxClient as at, analyzeTrace as b, pairwiseSignificance as bt, createVerifierEnvironment as c, dumbDriver as ct, worktreeFanout as d, localSandboxClient as dt, widen as et, EVIDENCE_MAX_CHARS as f, inlineSandboxClient as ft, composeWorkerEvidence as g, deterministicCompletion as gt, closingWorkerNote as h, completionAuthorizes as ht, jjWorkspace as i, registryScopeAnalyst as it, strategyAuthorContract as j, sanitizeMcpToolSchema as jt, assertStrategyContract as k, materializeLocalMcp as kt, failuresAnalyst as l, naiveDriver as lt, VERIFY_TAIL_CHARS as m, loopDispatch as mt, makeFinding$1 as n, buildSteerContext as nt, runInWorkspace as o, harvestCorpus as ot, NOTE_MAX_CHARS as p, loopCampaignDispatch as pt, fanout as q, gitWorkspace as r, createScopeAnalyst as rt, createWaterfallCollector as s, defineLeaderboard as st, computeFindingId$1 as t, assertTraceDerivedFindings as tt, superviseSurface as u, resolveSandboxClient as ut, copyUntrackedIntoClone as v, stopSentinel as vt, streamAgentTurn as w, renderPairwiseMarkdown as wt, patchDelivered as x, renderLeaderboardHtml as xt, withUntrackedArtifacts as y, leaderboard as yt, definePersona as z };
+export { panel as $, runStrategyEvolution as A, defaultAuditorInstruction as At, equalKOnCost as B, secretEnvOfMcpServer as Bt, GraphEdgeCapError as C, leaderboard as Ct, streamAgentTurn as D, renderLeaderboardSvg as Dt, collectAgentTurn as E, renderLeaderboardMarkdown as Et, SandboxRunAbortError as F, sanitizeMcpToolSchema as Ft, createShapeRegistry as G, definePersona as H, openSandboxRun as I, envKeyProvider as It, InMemoryCorpus as J, registerShape as K, printBenchmarkReport as L, mcpSecretEnvMetadataKey as Lt, assertStrategyContract as M, connectStdioMcp as Mt, authorStrategy as N, materializeLocalMcp as Nt, discriminatingMeans as O, renderPairwiseMarkdown as Ot, strategyAuthorContract as P, createMcpEnvironment as Pt, loopUntil as Q, runBenchmark as R, resolveMcpServerLaunch as Rt, runCoderChecks as S, stopSentinel as St, runGraph as T, renderLeaderboardHtml as Tt, runPersonified as U, trajectoryReport as V, builtinShapes as W, fanout as X, renderCorpusToInstructions as Y, flatWidenGate as Z, settledWorkerOut as _, loopCampaignDispatch as _t, localShell as a, buildSteerContext as at, analyzeTrace as b, deterministicCompletion as bt, createVerifierEnvironment as c, inProcessSandboxClient as ct, worktreeFanout as d, dumbDriver as dt, pipeline as et, EVIDENCE_MAX_CHARS as f, naiveDriver as ft, composeWorkerEvidence as g, inlineSandboxClient as gt, closingWorkerNote as h, localSandboxClient as ht, jjWorkspace as i, assertTraceDerivedFindings as it, selectChampion as j, McpSpawnFault as jt, pickChampion as k, auditIntent as kt, failuresAnalyst as l, harvestCorpus as lt, VERIFY_TAIL_CHARS as m, resolveSandboxClient as mt, makeFinding$1 as n, verify as nt, runInWorkspace as o, createScopeAnalyst as ot, NOTE_MAX_CHARS as p, steeringDriver as pt, FileCorpus as q, gitWorkspace as r, widen as rt, createWaterfallCollector as s, registryScopeAnalyst as st, computeFindingId$1 as t, selectValidWinner as tt, superviseSurface as u, defineLeaderboard as ut, copyUntrackedIntoClone as v, loopDispatch as vt, defaultEdgeTraversalCap as w, pairwiseSignificance as wt, patchDelivered as x, sentinelCompletion as xt, withUntrackedArtifacts as y, completionAuthorizes as yt, promotionGate as z, resolveSecretEnv as zt };
 
-//# sourceMappingURL=runtime-Bp3NwC0A.js.map
+//# sourceMappingURL=runtime-DZblIf3R.js.map