@tangle-network/agent-runtime 0.174.1 → 0.177.0

package/dist/coordination-driver-xO1tkxy-.js

@@ -0,0 +1,3063 @@
+import { d as providerAttemptEvidence } from "./materialization-CekWK6OO.js";
+import { f as RuntimeRunStateError, m as ValidationError } from "./errors-CDZ8XsVj.js";
+import { t as detachedFrozen } from "./snapshot-CTAf4uuA.js";
+import { b as workerTraceAnalysisStore, i as InMemorySpawnJournal, n as FileSpawnJournal, r as InMemoryResultBlobStore, t as FileResultBlobStore, y as parseWorkerToolTraceArtifact } from "./spawn-journal--N8Ten1q.js";
+import { _ as unmeteredSpend, r as chargedTokens, u as promptCacheTokenClasses } from "./util-D6ZEuBMi.js";
+import { i as writeAllBytes, n as parseCommittedJsonLines, r as prepareJsonlAppend, t as isNoEntError } from "./jsonl-file-CDfsCI5s.js";
+import { At as isLiveNodeStatus, Et as createPeerMailbox, H as freeSlots, Ut as runBrainLoop, at as createExecutorRegistry, c as pickBestDelivered, f as withDriverExecutor, g as meterRuntimeOwnedProviderAttempt, jt as isTerminalNodeStatus, l as runFinalizer, o as bestDelivered, q as assertValidBudget, u as runTree, xt as createInbox } from "./supervisor-ChLgoYhG.js";
+import { A as writeWorkerCancellation, M as writeWorkerSteerAcknowledgement, c as readWorkerCancelRequests, d as readWorkerSteerRequests, k as writeRunCancellation, l as readWorkerCancellation, o as readRunCancelRequest, r as claimWorkerSteerDelivery, s as readRunCancellation, u as readWorkerSteerAcknowledgement } from "./run-layout-Cd_l2XWV.js";
+import { agentProfileSchema, canonicalCandidateDigest } from "@tangle-network/agent-interface";
+import { argHash, errorStreakDetector, observeAll, repeatedActionDetector } from "@tangle-network/agent-eval";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+//#region src/runtime/supervise/detector-monitor.ts
+/**
+*
+* The ONLINE analyst: watch a `TraceSource` and fold each tool span through agent-eval's published
+* streaming detector kernel (`repeatedActionDetector`/`errorStreakDetector` — the SAME kernel the
+* control loop folds), firing `onSignal` the moment a worker loops or error-storms. Substrate-
+* agnostic: it consumes spans from any source (owned router/bridge loop OR a sandbox box session),
+* never the raw tool seam. Detection logic + the failure taxonomy live in agent-eval; not reimplemented.
+*
+* @experimental
+*/
+/** The default online panel for a tool-call pipe: a worker repeating the same call, or hammering
+*  consecutive errors. (No-progress needs a domain progress-probe, so it is opt-in, not default.)
+*
+*  Coverage note: `repeated-action` works for EVERY harness (it needs only tool name + args, which
+*  every adapter provides). `error-streak` needs per-call status — opencode carries it inline
+*  (`state.status`, VALIDATED live), but claude-code/codex tool-call parts do NOT (their errors live
+*  in separate result blocks not yet decoded), so error-streak is silent for those until result-block
+*  decoding is added + live-validated. It is in the panel because it is correct where status exists. */
+function defaultToolDetectors() {
+	return [repeatedActionDetector({ maxRepeated: 3 }), errorStreakDetector({ maxErrors: 3 })];
+}
+/** Subscribe to a `TraceSource` and run the streaming detectors over its live spans. Returns an
+*  unsubscribe. A defensive `argHash` failure (circular args) never throws out of the side-channel. */
+function watchTrace(source, opts = {}) {
+	const detectors = opts.detectors ?? defaultToolDetectors();
+	return source.onSpan((span) => {
+		let fingerprint;
+		try {
+			fingerprint = `${span.toolName}|${argHash(span.args)}`;
+		} catch {
+			fingerprint = `${span.toolName}|<unhashable>`;
+		}
+		const signals = observeAll(detectors, {
+			actionFingerprint: fingerprint,
+			...span.status ? { status: span.status } : {},
+			label: span.toolName
+		});
+		for (const s of signals) opts.onSignal?.(s, span);
+	});
+}
+//#endregion
+//#region src/runtime/supervise/event-bus.ts
+/** Create the child→parent coordination bus: one typed pipe for settled outputs, questions, and analyst findings, with a priority-ordered pull queue and a pass-through subscribe lane.
+* @experimental In-process queue; durability is a transport swap that does not exist yet. */
+function createEventBus(now = Date.now) {
+	const queue = [];
+	const log = [];
+	const subscribers = [];
+	const byKind = {};
+	const staged = /* @__PURE__ */ new WeakMap();
+	let seq = 0;
+	let published = 0;
+	let pulled = 0;
+	const matches = (r, kinds) => !kinds || kinds.includes(r.event.type);
+	const bestIndex = (kinds) => {
+		let best = -1;
+		let bestPriority = Number.NEGATIVE_INFINITY;
+		for (let i = 0; i < queue.length; i++) {
+			const r = queue[i];
+			if (!r || !matches(r, kinds)) continue;
+			if (r.priority > bestPriority) {
+				best = i;
+				bestPriority = r.priority;
+			}
+		}
+		return best;
+	};
+	return {
+		async publish(event, opts) {
+			const record = staged.get(event) ?? {
+				seq: seq++,
+				at: now(),
+				priority: opts?.priority ?? 0,
+				event
+			};
+			staged.set(event, record);
+			for (const handler of subscribers) await handler(record);
+			staged.delete(event);
+			if (opts?.queue !== false) queue.push(record);
+			log.push(record);
+			published += 1;
+			byKind[event.type] = (byKind[event.type] ?? 0) + 1;
+			return record;
+		},
+		pull(kinds) {
+			const i = bestIndex(kinds);
+			if (i < 0) return void 0;
+			pulled++;
+			return queue.splice(i, 1)[0]?.event;
+		},
+		subscribe(handler) {
+			subscribers.push(handler);
+			return () => {
+				const i = subscribers.indexOf(handler);
+				if (i >= 0) subscribers.splice(i, 1);
+			};
+		},
+		pending(kinds) {
+			return kinds ? queue.filter((r) => matches(r, kinds)).length : queue.length;
+		},
+		history() {
+			return log;
+		},
+		stats() {
+			return {
+				published,
+				pulled,
+				byKind: { ...byKind }
+			};
+		}
+	};
+}
+//#endregion
+//#region src/mcp/tools/coordination.ts
+/**
+*
+* MCP binding for a live `Scope`. A sandbox driver gets the same small verbs
+* the in-process driver has: spawn, observe, await, steer, ask/answer, analyze,
+* and stop. Settled outputs remain Scope artifacts; product code can project
+* them into any UI/report envelope it needs.
+*
+* @experimental
+*/
+/** Where a question this driver cannot answer goes next. `answer_question` accepts these and
+*  nothing else, so the decision type states them and nothing else. */
+const questionEscalationTargets = ["parent", "user"];
+const isQuestionEscalationTarget = (value) => questionEscalationTargets.includes(value);
+/** Producer-side cleanliness for the `finding` event. The findings payload is arbitrary analyst
+*  output, the digest a subscriber computes (RFC 8785) throws on ANY `undefined` value — nested
+*  included — and a throwing subscriber leaves the event invisible to EVERY subscriber. The
+*  producer, not the digest, owns keeping the event canonical: an `undefined` payload is stripped
+*  to key-absence, everything else is JSON round-tripped (nested `undefined` object values drop,
+*  `undefined` array slots become `null`), and a payload JSON cannot represent at all (cycle,
+*  BigInt, bare function) becomes a record OF that fact — degraded findings beat a vanished
+*  event. */
+function canonicalFindingEvent(finding) {
+	if (finding.findings === void 0) {
+		const { findings: _absent, ...present } = finding;
+		return present;
+	}
+	try {
+		return {
+			...finding,
+			findings: JSON.parse(JSON.stringify(finding.findings))
+		};
+	} catch (error) {
+		return {
+			...finding,
+			findings: { nonCanonicalFindings: error instanceof Error ? error.message : String(error) }
+		};
+	}
+}
+/** Normalize the two spellings of an analyst-on-settle entry to the route form. */
+function normalizeAnalyzeOnSettle(entry) {
+	return typeof entry === "string" ? { kind: entry } : entry;
+}
+/** Every cause at zero — a pre-flight publishes its whole ledger from the first read. */
+function emptyPreflightCounts() {
+	return {
+		"model-route": 0,
+		"bridge-full": 0,
+		"unmountable-tool": 0
+	};
+}
+/** Default ceiling for a single `await_event` block (ms). Chosen well under any reasonable remote
+*  MCP client request timeout so the call returns a `pending` liveness snapshot instead of erroring;
+*  the supervisor re-polls until the worker settles. */
+const DEFAULT_AWAIT_EVENT_TIMEOUT_MS = 15e3;
+/** The reserved coordination verb names — the complete set `createCoordinationTools` can emit
+*  (the analyst pair is conditional but still reserved). A driver's extra WORK tools must not
+*  collide with any of these, or it could no longer coordinate; callers validate eagerly against
+*  this set so the conflict fails loud at construction, not buried in a swallowed `act()` throw. */
+const coordinationVerbNames = [
+	"spawn_agent",
+	"observe_agent",
+	"steer_agent",
+	"await_event",
+	"list_questions",
+	"answer_question",
+	"ask_parent",
+	"submit_result",
+	"stop",
+	"list_analysts",
+	"run_analyst"
+];
+/**
+* The `CoordinationEvent` kinds a driver may name in `await_event`. The pull queue carries the
+* UP-leg only: `steer` / `answer` / `instruction` / `delivery-attempt` are recorded `queue: false`
+* (history and subscribers, never pulled back), and `mail` is delivered to its addressee's inbox.
+*
+* Declared once because the tool advertises this list in its JSON Schema AND filters on it at
+* dispatch. Written twice, the two drift and the schema promises a kind the filter drops — a
+* driver then blocks on a queue that already holds its event.
+*/
+const awaitableEventKinds = [
+	"settled",
+	"question",
+	"finding"
+];
+function isAwaitableEventKind(value) {
+	return awaitableEventKinds.includes(value);
+}
+const idArg = {
+	type: "string",
+	description: "The workerId returned by spawn_agent."
+};
+/**
+* Strip zod's object-KEY CODEC artifact from a derived JSON Schema, at every depth.
+*
+* `z.record(z.string(), …)` converts to `propertyNames: { type: 'string', pattern:
+* '^u(?:[0-9a-f]{4})*$' }` — a marker of the lossy key round-trip, not a constraint anything
+* enforces: `agentProfileSchema.safeParse({ name: 'r', tools: { bash: true, Read: false } })`
+* succeeds with those plain keys. Published verbatim it reads to a model as "every key must be a
+* run of hex quads", and the model either emits hex-encoded garbage keys or drops the field —
+* on `tools`, `permissions`, `metadata`, `mcp`, `mcp.*.env`, and `model.metadata`, which is most
+* of what a parent actually configures.
+*
+* Every `propertyNames` in the canonical profile schema is this artifact (25 of 25 at Interface
+* 0.40), and the canonical schema constrains no key by pattern, so dropping the keyword outright
+* loses nothing real and cannot be defeated by zod changing the encoding's exact regex.
+*
+* Rebuilds rather than mutates: the canonical conversion output must stay untouched for callers
+* that compare against it.
+*/
+const stripKeyCodecArtifacts = (node) => {
+	if (Array.isArray(node)) return node.map(stripKeyCodecArtifacts);
+	if (!node || typeof node !== "object") return node;
+	return Object.fromEntries(Object.entries(node).filter(([key]) => key !== "propertyNames").map(([key, value]) => [key, stripKeyCodecArtifacts(value)]));
+};
+/** The canonical profile fields a spawning parent actually sets on a child, in the order a reader
+*  needs them, each with the description published alongside it. Everything else stays legal to
+*  pass — see {@link deriveSpawnProfileArg}.
+*
+*  Why these eleven, with the measured numbers (serialized JSON bytes, Interface 0.40). The
+*  canonical `properties` map is 10629 bytes, against 2424 bytes for every argument of every other
+*  coordination tool COMBINED — publishing it whole makes one parameter four times the rest of the
+*  surface a driver re-reads each turn. Of the seven omitted fields (tags, connections, subagents,
+*  hooks, modes, confidential, extensions) none is something a parent hands a worker; `permissions`
+*  (321 bytes) IS, so it is published — a child that must not touch the network or the filesystem
+*  is fenced there and nowhere else. `mcp` (2663 bytes) and `resources` (3122 bytes) are the two a
+*  parent is least likely to author inline and were together 85% of the published cost, so they
+*  carry a brief shape plus a description naming the full form instead of the canonical sub-tree. */
+const spawnProfileFields = [
+	{
+		name: "name",
+		description: "Short identifier for this child, e.g. \"researcher\" or \"patch-writer\". A child normally sets it to its role; it shows up in traces and worker labels."
+	},
+	{
+		name: "description",
+		description: "One line saying what this child is for. Read by humans and by a parent listing its workers."
+	},
+	{
+		name: "version",
+		description: "Optional version string for this profile, so two revisions of the same role are distinguishable in evidence. A child usually omits it."
+	},
+	{
+		name: "harness",
+		description: "Which coding backend runs the child. Omit to inherit the run default; set it only when this child needs a specific backend (e.g. a long refactor on \"claude-code\")."
+	},
+	{
+		name: "model",
+		description: "Model routing: `default` model id, optional `small` for cheap sub-calls, `provider`, and `reasoningEffort`. A child typically sets `default` and `reasoningEffort` — raise effort for a hard reasoning task, lower it for bulk mechanical work."
+	},
+	{
+		name: "prompt",
+		description: "The child's standing instructions: `systemPrompt` (who it is and how it works) and `instructions` (durable rules). This is the role; the separate `task` argument carries what to do right now. A child with no systemPrompt has no role — always set one."
+	},
+	{
+		name: "tools",
+		description: "Per-tool on/off map keyed by tool name, e.g. `{ \"bash\": true, \"webfetch\": false }`. Omit to inherit the backend's default tool set; set it to narrow a child to the tools its task needs. Keys are plain tool names."
+	},
+	{
+		name: "permissions",
+		description: "Per-tool permission decisions: each tool name maps to \"allow\", \"deny\", or \"ask\", or to a nested map of finer-grained rules. This is where a parent fences a child it does not fully trust — a read-only child denies write and network tools here, not in `tools`."
+	},
+	{
+		name: "mcp",
+		description: "MCP tool servers to mount for the child, keyed by server name. Brief form: each value is either `{ transport: \"stdio\", command, args?, env?, cwd? }` or `{ transport: \"sse\" | \"http\", url, headers? }`. A child normally sets this only when it needs a tool server the task requires; the canonical AgentProfile schema carries the full form (secret-ref values for env/headers, per-server metadata) and governs validation.",
+		brief: {
+			type: "object",
+			additionalProperties: { type: "object" }
+		}
+	},
+	{
+		name: "resources",
+		description: "Files, tools, skills, and agents materialized into the child workspace before it starts. Brief form: `{ files?, tools?, skills?, agents? }`, each an array whose entries are `{ kind: \"inline\", name, content }` or `{ kind: \"github\", repository?, path, ref? }` (`files` entries wrap that as `{ path, resource, executable? }`). A child typically gets `files` for seed inputs and `skills` for a procedure it must follow; the canonical AgentProfile schema carries the full form and governs validation.",
+		brief: {
+			type: "object",
+			properties: {
+				files: {
+					type: "array",
+					items: { type: "object" }
+				},
+				tools: {
+					type: "array",
+					items: { type: "object" }
+				},
+				skills: {
+					type: "array",
+					items: { type: "object" }
+				},
+				agents: {
+					type: "array",
+					items: { type: "object" }
+				}
+			},
+			additionalProperties: true
+		}
+	},
+	{
+		name: "metadata",
+		description: "Free-form key/value bag carried with the profile (plain string keys). Use it for run bookkeeping a reader will want later; it does not change how the child executes."
+	}
+];
+/**
+* Build the published shape of `spawn_agent`'s `profile` argument from the canonical
+* `agentProfileSchema` conversion's `properties` map, so it cannot drift from the profile the
+* runtime materializes.
+*
+* DEGRADES, never throws. A canonical field that is absent — renamed or removed upstream — is
+* simply omitted from the published shape, and a canonical schema that is no longer an object
+* publishes no properties at all. This function is reached from a statically-imported module, so a
+* throw here bricks `import '@tangle-network/agent-runtime/kernel'` for every consumer over an
+* upstream rename that costs them, at worst, one advisory field. The drift itself is still caught
+* loudly — as a test assertion in `tests/kernel/coordination.test.ts`, in CI, where it is our
+* problem rather than at a consumer's import, where it is theirs.
+*
+* Permissive on purpose: `additionalProperties: true` with no `required` list, so every canonical
+* field this shape omits stays legal to pass. This tool layer performs no profile validation.
+*
+* @internal exported for the drift and degradation tests; not part of the package's public API.
+*/
+function deriveSpawnProfileArg(canonicalProperties) {
+	const published = [];
+	for (const field of spawnProfileFields) {
+		const canonical = canonicalProperties?.[field.name];
+		if (canonical === void 0) continue;
+		const shape = field.brief ?? stripKeyCodecArtifacts(canonical);
+		published.push([field.name, {
+			...shape,
+			description: field.description
+		}]);
+	}
+	return {
+		type: "object",
+		description: "The child agent profile to run — this is the shape the DEFAULT worker seam accepts; a run wired with a custom makeWorkerAgent may accept a different one. The properties below are derived from the canonical AgentProfile schema and reduced to what a spawning parent sets (`mcp` and `resources` in a brief form); every other canonical field — tags, connections, subagents, hooks, modes, confidential, extensions — may still be passed. This tool does not validate the profile: the canonical AgentProfile schema governs validation downstream.",
+		properties: Object.fromEntries(published),
+		additionalProperties: true
+	};
+}
+spawnProfileFields.map((f) => f.name);
+let spawnProfileArgCache;
+/** The published `profile` shape, computed on FIRST tool-definition access and memoized — not at
+*  module load. The conversion walks the whole canonical profile tree, and the strip walk rebuilds
+*  it: 3.5ms on the first `createCoordinationTools`, 0.017ms on every later one (measured, Interface
+*  0.40, node 24). `src/runtime/index.ts` imports this module statically, so paying that at import
+*  taxes every consumer of the kernel entrypoint — including the ones that never build a
+*  coordination toolbox. The memo keeps it at once per process for the ones that do.
+*
+*  Conversion choices. `io: 'input'` is the CALLER's view — pre-default, pre-transform — which is
+*  what a spawning parent may pass, not what the runtime ends up holding. `unrepresentable: 'any'`
+*  keeps the conversion total: the canonical schema contains transforms with no JSON Schema form,
+*  and zod's default is to throw on them, which would leave the tool with no published shape. */
+function spawnProfileArg() {
+	if (!spawnProfileArgCache) spawnProfileArgCache = detachedFrozen(deriveSpawnProfileArg(agentProfileSchema.toJSONSchema({
+		io: "input",
+		target: "draft-07",
+		unrepresentable: "any"
+	}).properties));
+	return spawnProfileArgCache;
+}
+/** Build the driver's MCP tools over a live scope. */
+function createCoordinationTools(opts) {
+	const deliverable = opts.deliverable;
+	let stopped = false;
+	let reason;
+	let stopNotified = false;
+	let submitted;
+	let questionSeq = 0;
+	const ledger = [];
+	const questions = [...opts.priorQuestions ?? []];
+	const questionPolicy = opts.questionPolicy ?? "auto";
+	const notifyStop = () => {
+		if (stopNotified) return;
+		stopNotified = true;
+		opts.onStop?.(reason);
+	};
+	const completedKeys = /* @__PURE__ */ new Set();
+	const keyByWorker = /* @__PURE__ */ new Map();
+	const profileNameByWorker = /* @__PURE__ */ new Map();
+	const liveHandles = /* @__PURE__ */ new Map();
+	let unkeyedAssignmentOrdinal = nextUnkeyedAssignmentOrdinal(opts.scope);
+	const preflightCounts = emptyPreflightCounts();
+	for (const [key, prior] of opts.scope.resume?.keys ?? []) if (prior.state === "completed") completedKeys.add(key);
+	const nodeForWorker = (id) => opts.scope.view.nodes.find((node) => node.id === id) ?? opts.scope.resume?.view.nodes.find((node) => node.id === id);
+	const projectSettled = (settled, resumed = false) => {
+		const node = nodeForWorker(settled.handle.id);
+		const assignmentId = settled.handle.assignmentId ?? node?.assignmentId;
+		const identity = settled.handle.identity ?? node?.identity;
+		const materialization = settled.handle.materialization ?? node?.materialization;
+		const executionBindings = settled.handle.executionBindings ?? node?.executionBindings;
+		const settledAt = settled.settledAt ?? node?.settledAt;
+		const trace = settled.trace ?? node?.trace ?? {
+			status: "unavailable",
+			reason: "legacy-settlement-without-trace-evidence"
+		};
+		const common = {
+			id: settled.handle.id,
+			...assignmentId === void 0 ? {} : { assignmentId },
+			...identity === void 0 ? {} : { identity },
+			...materialization === void 0 ? {} : { materialization },
+			...executionBindings === void 0 ? {} : { executionBindings },
+			...settledAt === void 0 ? {} : { settledAt },
+			trace,
+			...resumed ? { resumed: true } : {}
+		};
+		return detachedFrozen(settled.kind === "done" ? {
+			...common,
+			status: "done",
+			spent: settled.spent,
+			...settled.verdict?.score === void 0 ? {} : { score: settled.verdict.score },
+			...settled.verdict?.valid === void 0 ? {} : { valid: settled.verdict.valid },
+			outRef: settled.outRef
+		} : {
+			...common,
+			status: "down",
+			...node?.spent === void 0 ? {} : { spent: node.spent },
+			reason: settled.reason
+		});
+	};
+	const resumedWorkers = [];
+	for (const s of opts.scope.resume?.settled ?? []) {
+		const worker = projectSettled(s, true);
+		resumedWorkers.push(worker);
+		ledger.push(worker);
+	}
+	const bus = createEventBus();
+	if (opts.onEvent) {
+		const cb = opts.onEvent;
+		bus.subscribe((rec) => cb(rec.event, rec));
+	}
+	const resumeEvents = opts.replaySettlements ? resumedWorkers.map((worker) => detachedFrozen({
+		type: "settled",
+		worker
+	})) : [];
+	let resumeEventIndex = 0;
+	let readyInFlight;
+	const ready = () => {
+		if (resumeEventIndex >= resumeEvents.length) return Promise.resolve();
+		if (readyInFlight) return readyInFlight;
+		readyInFlight = (async () => {
+			while (resumeEventIndex < resumeEvents.length) {
+				const event = resumeEvents[resumeEventIndex];
+				if (!event) break;
+				await bus.publish(event);
+				resumeEventIndex += 1;
+			}
+		})().finally(() => {
+			readyInFlight = void 0;
+		});
+		return readyInFlight;
+	};
+	const urgencyPriority = (u) => u === "blocks-run" ? 20 : u === "blocks-step" ? 10 : 0;
+	const str = (v, field) => {
+		if (typeof v !== "string" || v.length === 0) throw new Error(`coordination tools: "${field}" must be a non-empty string`);
+		return v;
+	};
+	const obj = (raw) => {
+		if (!raw || typeof raw !== "object") throw new Error("coordination tools: arguments must be an object");
+		return raw;
+	};
+	const mergeBudget = (base, raw) => {
+		if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("coordination tools: \"budget\" must be an object");
+		const o = raw;
+		const field = (name) => {
+			const v = o[name];
+			if (v === void 0) return void 0;
+			if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`coordination tools: "budget.${name}" must be a finite number`);
+			return v;
+		};
+		const maxIterations = field("maxIterations");
+		const maxTokens = field("maxTokens");
+		const maxUsd = field("maxUsd");
+		const deadlineMs = field("deadlineMs");
+		const merged = {
+			maxIterations: maxIterations ?? base.maxIterations,
+			maxTokens: maxTokens ?? base.maxTokens,
+			...(maxUsd ?? base.maxUsd) === void 0 ? {} : { maxUsd: maxUsd ?? base.maxUsd },
+			...(deadlineMs ?? base.deadlineMs) === void 0 ? {} : { deadlineMs: deadlineMs ?? base.deadlineMs }
+		};
+		assertValidBudget(merged, "coordination tools: budget");
+		return merged;
+	};
+	const level = (v) => {
+		if (v === "worker" || v === "driver" || v === "loop") return v;
+		throw new Error("coordination tools: \"level\" must be worker, driver, or loop");
+	};
+	const urgency = (v) => {
+		if (v === "continue-without" || v === "blocks-step" || v === "blocks-run") return v;
+		throw new Error("coordination tools: \"urgency\" must be continue-without, blocks-step, or blocks-run");
+	};
+	const commitSettled = (s, w) => {
+		const settledKey = keyByWorker.get(s.handle.id);
+		if (settledKey !== void 0 && s.kind === "done") completedKeys.add(settledKey);
+		ledger.push(w);
+		unwatchWorker(w.id);
+	};
+	let pendingSettlement;
+	const analystRuns = /* @__PURE__ */ new Map();
+	let analystRunOrdinal = 0;
+	/** The `finding` event an analyst-agent settlement becomes: its settle OUTPUT is the findings
+	*  (a failed run publishes the failure as findings — degraded beats vanished). */
+	const analystRunFinding = (run, settled) => detachedFrozen({
+		type: "finding",
+		finding: canonicalFindingEvent({
+			fromWorker: run.sourceWorker,
+			analyst: run.route.kind,
+			findings: settled.kind === "done" ? settled.out : { analystRunFailed: settled.reason }
+		})
+	});
+	/**
+	* Spawn one analyst-AGENT run over a settled worker's evidence, through the SAME spawn
+	* machinery a driver spawn uses (`scope.spawn` + `makeWorkerAgent`): the analyst's spend
+	* reserves from the conserved pool, its node is journaled/traced like any worker, and a
+	* node-pinning seam sees `context.analyst`. Its task is the route directive plus the settled
+	* worker's persisted tool-trace spans. A refused spawn publishes a finding RECORDING the
+	* refusal — observable, never silent — and must never take down the settlement path.
+	*/
+	const spawnAnalystRun = async (route, worker) => {
+		let spansText = "";
+		let spanCount = 0;
+		if (worker.trace.status === "available") try {
+			const artifact = parseWorkerToolTraceArtifact(await opts.blobs.get(worker.trace.traceRef), worker.trace.traceRef);
+			spanCount = artifact.spans.length;
+			spansText = safeJsonText(artifact.spans);
+		} catch {
+			spansText = "";
+		}
+		const task = [
+			...route.directive === void 0 || route.directive.length === 0 ? [] : [route.directive],
+			`Evidence — settled worker '${worker.id}' tool trace (${spanCount} spans):`,
+			spansText.length === 0 ? "(no tool spans available)" : spansText
+		].join("\n\n");
+		const assignmentId = `analyst:${route.kind}:o${analystRunOrdinal++}`;
+		const label = `analyst:${route.kind}`;
+		const context = Object.freeze({
+			assignmentId,
+			parentNodeId: opts.scope.view.root,
+			budget: opts.perWorker,
+			task,
+			label,
+			analyst: route.kind,
+			continuity: "fresh"
+		});
+		let refusal;
+		let spawnedId;
+		try {
+			const res = opts.scope.spawn(() => opts.makeWorkerAgent(route.agent, context), task, {
+				budget: opts.perWorker,
+				label,
+				assignmentId
+			});
+			if (res.ok) spawnedId = res.handle.id;
+			else refusal = String(res.reason);
+		} catch (cause) {
+			refusal = cause instanceof Error ? cause.message : String(cause);
+		}
+		if (spawnedId === void 0) {
+			await bus.publish({
+				type: "finding",
+				finding: canonicalFindingEvent({
+					fromWorker: worker.id,
+					analyst: route.kind,
+					findings: { analystSpawnRefused: refusal ?? "unknown" }
+				})
+			});
+			return;
+		}
+		analystRuns.set(spawnedId, {
+			route,
+			sourceWorker: worker.id
+		});
+		watchWorker(spawnedId);
+	};
+	const workerRouteNames = (workerId) => {
+		const names = /* @__PURE__ */ new Set();
+		const profileName = profileNameByWorker.get(workerId);
+		if (profileName !== void 0) names.add(profileName);
+		const label = nodeForWorker(workerId)?.label;
+		if (label !== void 0) names.add(label);
+		return names;
+	};
+	/** The LIVE worker a route destination names, by profile name first, label second. */
+	const liveWorkerIdNamed = (destination) => {
+		const live = opts.scope.view.nodes.filter((node) => isLiveNodeStatus(node.status));
+		return live.find((node) => profileNameByWorker.get(node.id) === destination)?.id ?? live.find((node) => node.label === destination)?.id;
+	};
+	const liveWorkerForNode = (name) => opts.scope.view.nodes.find((node) => isLiveNodeStatus(node.status) && profileNameByWorker.get(node.id) === name)?.id;
+	const latestSettledWorkerForNode = (name) => {
+		for (let i = ledger.length - 1; i >= 0; i -= 1) {
+			const worker = ledger[i];
+			if (profileNameByWorker.get(worker.id) === name) return worker.id;
+		}
+	};
+	const nodeSpawnCount = (name) => {
+		let count = 0;
+		for (const profileName of profileNameByWorker.values()) if (profileName === name) count += 1;
+		return count;
+	};
+	const parseContinuity = (v) => {
+		if (v === void 0) return void 0;
+		if (v === "fresh" || v === "resume") return v;
+		throw new Error("coordination tools: \"continuity\" must be \"fresh\" or \"resume\"");
+	};
+	/**
+	* Resolve the EFFECTIVE continuity of one spawn: the per-call request wins, else the profile
+	* name's declared default, else `'fresh'`. Every refusal is loud and actionable:
+	*   - an EXPLICIT `'resume'` with no settled prior worker refuses (`resume-no-prior`) — the
+	*     DECLARED default degrades to `'fresh'` instead, so a resume edge's first traversal is
+	*     simply the first spawn;
+	*   - resume while a prior worker of the node is still LIVE refuses (`resume-while-live`) —
+	*     that is what steer is for, and the error says so;
+	*   - resume under a semantic `key` refuses (`resume-with-key`) — a key makes an assignment
+	*     run-once, resume explicitly runs the node again.
+	*/
+	const resolveContinuity = (requested, profileName, key) => {
+		const declared = profileName === void 0 ? "fresh" : opts.continuityByProfile?.[profileName] ?? "fresh";
+		if (!(requested === "resume" || requested === void 0 && declared === "resume")) return { continuity: "fresh" };
+		if (profileName === void 0 || profileName.length === 0) return {
+			error: "resume-unnamed-profile",
+			hint: "Resume targets a node by profile.name — the stable node identity — and this profile has none. Name the profile, or spawn fresh."
+		};
+		if (key !== void 0) return {
+			error: "resume-with-key",
+			hint: "A semantic key makes an assignment run-once (a completed key returns its committed result instead of running again); resume explicitly runs the node AGAIN. Drop the key to resume, or keep the key and spawn fresh."
+		};
+		const live = liveWorkerForNode(profileName);
+		if (live !== void 0) return {
+			error: "resume-while-live",
+			hint: `Worker '${live}' on node '${profileName}' is still LIVE — resume re-attaches to a SETTLED session. To redirect the live worker, use steer_agent (that is the live-worker channel); to run a parallel sibling instead, pass continuity: 'fresh'.`
+		};
+		const prior = latestSettledWorkerForNode(profileName);
+		if (prior === void 0) {
+			if (requested === void 0) return { continuity: "fresh" };
+			return {
+				error: "resume-no-prior",
+				hint: `Node '${profileName}' has no settled prior worker in this process to resume — resume continues a FINISHED session. Spawn the node fresh first (omit continuity or pass 'fresh').`
+			};
+		}
+		return {
+			continuity: "resume",
+			resume: {
+				ofWorker: prior,
+				sequence: nodeSpawnCount(profileName) + 1
+			}
+		};
+	};
+	/**
+	* Deliver one routed analyst finding to its destination worker through the SAME authorized
+	* steer machinery a driver steer uses, so the delivery is recorded (`steer` event carrying
+	* `analyst`) and its outcome is a fact. No live destination ⇒ a record-only failed steer —
+	* observable, never a silent drop. A throw here must not kill the settle path: failures are
+	* recorded on the bus (a `steer` with `delivered: false`) before being swallowed, with ONE
+	* narrow exception — a bus that refuses the `delivery-attempt` record itself leaves only the
+	* `instruction` receipt (an attempt with no outcome = explicitly unknown, per
+	* recordDeliveryAttempt's own contract).
+	*/
+	const deliverRoutedFinding = async (route, findings) => {
+		const destination = route.to;
+		const text = route.directive === void 0 || route.directive.length === 0 ? safeJsonText(findings) : `${route.directive}\n\n${safeJsonText(findings)}`;
+		const targetId = liveWorkerIdNamed(destination);
+		if (targetId === void 0) {
+			await bus.publish({
+				type: "steer",
+				down: detachedFrozen({
+					receiptId: randomUUID(),
+					toWorker: destination,
+					instruction: text,
+					instructionDigest: canonicalCandidateDigest(text),
+					delivered: false,
+					outcome: "unknown-worker"
+				}),
+				analyst: route.kind
+			}, { queue: false });
+			return;
+		}
+		let instruction;
+		try {
+			instruction = authorizeInstruction("steer", targetId, text, false);
+			await recordInstruction(instruction);
+		} catch (cause) {
+			try {
+				await sendDown("steer", detachedFrozen({
+					receiptId: randomUUID(),
+					toWorker: targetId,
+					instruction: text,
+					instructionDigest: canonicalCandidateDigest(text),
+					delivered: false,
+					outcome: "runtime-error",
+					error: cause instanceof Error ? cause.message : String(cause)
+				}), route.kind);
+			} catch {}
+			return;
+		}
+		try {
+			await attemptDelivery(instruction, {
+				steer: instruction.instruction,
+				interrupt: false
+			}, { analyst: route.kind });
+		} catch {}
+	};
+	const flushPendingSettlement = async () => {
+		const pending = pendingSettlement;
+		if (!pending) return false;
+		await bus.publish(pending.event);
+		if (pending.analystRun) {
+			analystRuns.delete(pending.worker.id);
+			unwatchWorker(pending.worker.id);
+			pendingSettlement = void 0;
+			const { route } = pending.analystRun;
+			if (route.to !== void 0 && pending.event.type === "finding") await deliverRoutedFinding({
+				kind: route.kind,
+				to: route.to
+			}, pending.event.finding.findings);
+			return true;
+		}
+		commitSettled(pending.settled, pending.worker);
+		pendingSettlement = void 0;
+		if (pending.analyze && pending.worker.status === "done" && pending.worker.trace.status === "available" && opts.analyzeOnSettle?.length) {
+			const routes = opts.analyzeOnSettle.map(normalizeAnalyzeOnSettle);
+			const sourceNames = workerRouteNames(pending.worker.id);
+			const applicable = routes.filter((route) => route.over === void 0 || route.over.some((name) => sourceNames.has(name)));
+			const lensRoutes = applicable.filter((route) => route.agent === void 0);
+			const agentRoutes = applicable.filter((route) => route.agent !== void 0);
+			if (lensRoutes.length > 0 && opts.analysts) {
+				const trace = await workerTraceAnalysisStore(pending.worker.trace, opts.blobs);
+				for (const route of lensRoutes) {
+					const findings = await opts.analysts.run(route.kind, trace);
+					await bus.publish({
+						type: "finding",
+						finding: canonicalFindingEvent({
+							fromWorker: pending.worker.id,
+							analyst: route.kind,
+							findings
+						})
+					});
+					if (route.to !== void 0) await deliverRoutedFinding(route, findings);
+				}
+			}
+			for (const route of agentRoutes) await spawnAnalystRun(route, pending.worker);
+		}
+		return true;
+	};
+	const drainSettlement = async () => {
+		if (!pendingSettlement) {
+			const settled = await opts.scope.next();
+			if (!settled) return false;
+			const worker = projectSettled(settled);
+			const run = analystRuns.get(settled.handle.id);
+			pendingSettlement = run ? {
+				settled,
+				worker,
+				event: analystRunFinding(run, settled),
+				analyze: false,
+				analystRun: run
+			} : {
+				settled,
+				worker,
+				event: detachedFrozen({
+					type: "settled",
+					worker
+				}),
+				analyze: true
+			};
+		}
+		return flushPendingSettlement();
+	};
+	const drainResolved = async () => {
+		let drained = 0;
+		for (;;) {
+			if (!pendingSettlement) {
+				const settled = await opts.scope.nextResolved();
+				if (!settled) return drained;
+				const worker = projectSettled(settled);
+				const run = analystRuns.get(settled.handle.id);
+				pendingSettlement = run ? {
+					settled,
+					worker,
+					event: analystRunFinding(run, settled),
+					analyze: false,
+					analystRun: run
+				} : {
+					settled,
+					worker,
+					event: detachedFrozen({
+						type: "settled",
+						worker
+					}),
+					analyze: false
+				};
+			}
+			await flushPendingSettlement();
+			drained += 1;
+		}
+	};
+	async function sendDown(type, down, questionIdOrAnalyst) {
+		await bus.publish(type === "answer" ? {
+			type,
+			down,
+			questionId: str(questionIdOrAnalyst, "questionId")
+		} : questionIdOrAnalyst !== void 0 ? {
+			type,
+			down,
+			analyst: questionIdOrAnalyst
+		} : {
+			type,
+			down
+		}, { queue: false });
+	}
+	const authorizeInstruction = (kind, workerId, instruction, interrupt, questionId) => {
+		const workerIdentity = opts.scope.view.nodes.find((node) => node.id === workerId)?.identity;
+		let authorizedInstruction = instruction;
+		if (opts.authorizeDownMessage) {
+			if (workerIdentity === void 0) throw new Error(`coordination tools: cannot authorize ${kind} for worker ${JSON.stringify(workerId)} without durable identity`);
+			const decision = detachedFrozen(opts.authorizeDownMessage(detachedFrozen({
+				kind,
+				workerId,
+				workerIdentity,
+				instruction,
+				interrupt,
+				...questionId !== void 0 ? { questionId } : {}
+			})));
+			if (typeof decision !== "object" || decision === null || Array.isArray(decision) || typeof decision.instruction !== "string" || decision.instruction.length === 0) throw new Error("coordination tools: authorizeDownMessage must return an instruction");
+			authorizedInstruction = decision.instruction;
+		}
+		return detachedFrozen({
+			receiptId: randomUUID(),
+			kind,
+			toWorker: workerId,
+			instruction: authorizedInstruction,
+			instructionDigest: canonicalCandidateDigest(authorizedInstruction),
+			...workerIdentity !== void 0 ? { workerIdentity } : {},
+			interrupt,
+			...questionId !== void 0 ? { questionId } : {}
+		});
+	};
+	/** Publish before `scope.send`: an awaited durable subscriber therefore commits the exact bytes
+	* before the worker can observe them. */
+	const recordInstruction = async (instruction) => {
+		await bus.publish({
+			type: "instruction",
+			instruction
+		}, { queue: false });
+	};
+	/** Commit delivery intent after the authorization receipt and before `Scope.send`. An attempt with
+	* no matching outcome after a crash is explicitly unknown and must never be replayed. */
+	const recordDeliveryAttempt = async (instruction) => {
+		const attempt = detachedFrozen({
+			receiptId: instruction.receiptId,
+			kind: instruction.kind,
+			toWorker: instruction.toWorker,
+			instructionDigest: instruction.instructionDigest,
+			interrupt: instruction.interrupt,
+			...instruction.questionId !== void 0 ? { questionId: instruction.questionId } : {}
+		});
+		await bus.publish({
+			type: "delivery-attempt",
+			attempt
+		}, { queue: false });
+		return attempt;
+	};
+	const deliveryOutcome = (workerId, delivered) => {
+		if (delivered) return "delivered";
+		if (opts.scope.signal.aborted) return "scope-stopped";
+		const node = opts.scope.view.nodes.find((candidate) => candidate.id === workerId);
+		if (!node) return "unknown-worker";
+		if (!isLiveNodeStatus(node.status)) return "already-settled";
+		return "runtime-has-no-inbox";
+	};
+	const attemptDelivery = async (instruction, message, origin) => {
+		await recordDeliveryAttempt(instruction);
+		let delivered = false;
+		let outcome;
+		let error;
+		try {
+			delivered = opts.scope.send(instruction.toWorker, message);
+			outcome = deliveryOutcome(instruction.toWorker, delivered);
+		} catch (cause) {
+			outcome = "runtime-error";
+			error = cause instanceof Error ? cause.message : String(cause);
+		}
+		const down = detachedFrozen({
+			receiptId: instruction.receiptId,
+			toWorker: instruction.toWorker,
+			instruction: instruction.instruction,
+			instructionDigest: instruction.instructionDigest,
+			delivered,
+			outcome,
+			...error !== void 0 ? { error } : {}
+		});
+		if (instruction.kind === "answer") await sendDown("answer", down, str(instruction.questionId, "questionId"));
+		else await sendDown("steer", down, origin?.analyst);
+		if (error !== void 0) throw new Error(`coordination tools: delivery failed: ${error}`);
+		return down;
+	};
+	const steerWorker = async (workerId, instruction, options = {}) => {
+		const interrupt = options.interrupt === true;
+		const authorized = authorizeInstruction("steer", workerId, instruction, interrupt);
+		await recordInstruction(authorized);
+		return await attemptDelivery(authorized, {
+			steer: authorized.instruction,
+			interrupt
+		});
+	};
+	const projectEvent = (ev) => {
+		if (ev.type === "settled") {
+			const { id, status, ...evidence } = ev.worker;
+			return {
+				type: "settled",
+				settled: id,
+				status,
+				...evidence
+			};
+		}
+		if (ev.type === "question") return {
+			type: "question",
+			question: ev.question
+		};
+		if (ev.type === "finding") return {
+			type: "finding",
+			...ev.finding
+		};
+		if (ev.type === "answer") return {
+			type: "answer",
+			...ev.down,
+			questionId: ev.questionId
+		};
+		if (ev.type === "instruction") return {
+			type: "instruction",
+			...ev.instruction
+		};
+		if (ev.type === "delivery-attempt") return {
+			type: "delivery-attempt",
+			...ev.attempt
+		};
+		if (ev.type === "mail") return {
+			type: "mail",
+			...ev.mail
+		};
+		return {
+			type: ev.type,
+			...ev.down
+		};
+	};
+	const peerMail = opts.peerMail ? createPeerMailbox({
+		scope: opts.scope,
+		publish: (mail) => bus.publish({
+			type: "mail",
+			mail
+		}, { queue: false }).then(() => void 0),
+		...opts.peerMail.limits ? { limits: opts.peerMail.limits } : {}
+	}) : void 0;
+	const nextQuestionId = (from) => {
+		for (;;) {
+			const id = `${from}:q${questionSeq++}`;
+			if (!questions.some((question) => question.id === id)) return id;
+		}
+	};
+	const normalizeQuestion = (q, fallbackFrom) => {
+		const from = str(q.from ?? fallbackFrom, "from");
+		return {
+			id: typeof q.id === "string" && q.id.length > 0 ? q.id : nextQuestionId(from),
+			from,
+			level: level(q.level),
+			question: str(q.question, "question"),
+			reason: str(q.reason, "reason"),
+			...q.options ? { options: q.options } : {},
+			urgency: urgency(q.urgency)
+		};
+	};
+	const addQuestion = (raw, fallbackFrom, decision) => {
+		const q = normalizeQuestion(raw, fallbackFrom);
+		const existing = questions.find((x) => x.id === q.id);
+		if (existing) return {
+			question: existing,
+			added: false
+		};
+		const effectiveDecision = decision ?? (questionPolicy === "bubble" ? {
+			kind: "escalate",
+			to: "parent",
+			reason: "question policy bubbled to parent"
+		} : void 0);
+		const status = effectiveDecision?.kind === "answer" ? "answered" : effectiveDecision?.kind === "defer" ? "deferred" : effectiveDecision?.kind === "escalate" ? "escalated" : "open";
+		const record = {
+			...q,
+			status,
+			openedAt: Date.now(),
+			...effectiveDecision ? { decision: effectiveDecision } : {}
+		};
+		questions.push(record);
+		return {
+			question: record,
+			added: true
+		};
+	};
+	const emitNewQuestion = async (record) => {
+		if (record.added) await bus.publish({
+			type: "question",
+			question: record.question
+		}, { priority: urgencyPriority(record.question.urgency) });
+		return record.question;
+	};
+	const decideQuestion = (questionId, decision) => {
+		const idx = questions.findIndex((q) => q.id === questionId);
+		if (idx < 0) throw new Error(`unknown questionId ${JSON.stringify(questionId)}`);
+		const prior = questions[idx];
+		const status = decision.kind === "answer" ? "answered" : decision.kind === "defer" ? "deferred" : "escalated";
+		const next = {
+			...prior,
+			status,
+			decision
+		};
+		questions[idx] = next;
+		return next;
+	};
+	const blockingQuestionsForStop = () => {
+		if (questionPolicy === "auto" || questionPolicy === "bubble") return [];
+		return questions.filter((q) => {
+			if (!(q.urgency === "blocks-step" || q.urgency === "blocks-run")) return false;
+			if (questionPolicy === "mustDecide") return q.status === "open";
+			return q.status !== "answered" && q.status !== "deferred";
+		});
+	};
+	const maxLiveWorkers = opts.maxLiveWorkers;
+	const localLiveWorkerCount = () => opts.scope.view.nodes.filter((n) => isLiveNodeStatus(n.status)).length;
+	const sharedWorkerCapacity = () => {
+		return opts.scope.workerCapacity;
+	};
+	const usesTreeWideLimit = () => {
+		const capacity = sharedWorkerCapacity();
+		return capacity !== void 0 && capacity.freeSlots !== null;
+	};
+	const liveWorkerCount = () => usesTreeWideLimit() ? sharedWorkerCapacity()?.live ?? localLiveWorkerCount() : localLiveWorkerCount();
+	const projectNodeEvidence = (node, resumed = false) => ({
+		id: node.id,
+		status: node.status,
+		...node.assignmentId === void 0 ? {} : { assignmentId: node.assignmentId },
+		...node.identity === void 0 ? {} : { identity: node.identity },
+		...node.materialization === void 0 ? {} : { materialization: node.materialization },
+		...node.executionBindings === void 0 ? {} : { executionBindings: node.executionBindings },
+		spent: node.spent,
+		...node.settledAt === void 0 ? {} : { settledAt: node.settledAt },
+		...node.outRef === void 0 ? {} : { outRef: node.outRef },
+		...node.trace === void 0 ? {} : { trace: node.trace },
+		...resumed ? { resumed: true } : {}
+	});
+	const liveSnapshot = () => opts.scope.view.nodes.filter((n) => isLiveNodeStatus(n.status)).map((n) => projectNodeEvidence(n));
+	const freeWorkerSlots = () => usesTreeWideLimit() ? sharedWorkerCapacity()?.freeSlots ?? null : freeSlots(localLiveWorkerCount(), maxLiveWorkers);
+	const readProgress = (id) => {
+		const scope = opts.scope;
+		if (typeof scope.progress !== "function") return void 0;
+		try {
+			return scope.progress(id, opts.stallAfterMs !== void 0 ? { stallAfterMs: opts.stallAfterMs } : {});
+		} catch {
+			return;
+		}
+	};
+	const watchers = /* @__PURE__ */ new Map();
+	const watchWorker = (id) => {
+		const watch = opts.watchWorkers;
+		if (!watch) return;
+		const scope = opts.scope;
+		if (typeof scope.traceSource !== "function") return;
+		let source;
+		try {
+			source = scope.traceSource(id);
+		} catch {
+			return;
+		}
+		if (!source) return;
+		const cap = watch.maxFindingsPerWorker ?? 3;
+		let raised = 0;
+		const unsub = watchTrace(source, {
+			...watch.detectors ? { detectors: watch.detectors } : {},
+			onSignal: async (signal, span) => {
+				if (cap > 0 && raised >= cap) return;
+				raised += 1;
+				await bus.publish({
+					type: "finding",
+					finding: canonicalFindingEvent({
+						fromWorker: id,
+						analyst: `online:${signal.detector}`,
+						findings: {
+							detector: signal.detector,
+							severity: signal.severity,
+							reason: signal.reason,
+							streak: signal.streak,
+							...signal.failureClass ? { failureClass: signal.failureClass } : {},
+							toolName: span.toolName,
+							at: span.endedAt,
+							progress: readProgress(id)
+						}
+					})
+				});
+			}
+		});
+		watchers.set(id, unsub);
+	};
+	const unwatchWorker = (id) => {
+		const unsub = watchers.get(id);
+		if (!unsub) return;
+		watchers.delete(id);
+		try {
+			unsub();
+		} catch {}
+	};
+	const awaitTimeoutMs = opts.awaitTimeoutMs ?? 15e3;
+	let inFlightDrain = null;
+	const ensureDrain = () => {
+		if (!inFlightDrain) inFlightDrain = drainSettlement().finally(() => {
+			inFlightDrain = null;
+		});
+		return inFlightDrain;
+	};
+	const raceDrainWithTimeout = async (drain) => {
+		if (awaitTimeoutMs <= 0) return { drained: await drain };
+		let timer;
+		const timeout = new Promise((resolve) => {
+			timer = setTimeout(() => resolve(void 0), awaitTimeoutMs);
+			if (typeof timer?.unref === "function") timer.unref();
+		});
+		try {
+			return await Promise.race([drain.then((drained) => ({ drained })), timeout]);
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	};
+	const tools = [
+		{
+			name: "spawn_agent",
+			description: "Start a worker the driver will drive. `profile` is the worker or another driver; `task` is what it should do. Reserves budget from the conserved pool and fails closed. Pass an optional `budget` (per-field) to give a hard sub-task more than the default — it merges over the per-worker default; the conserved pool is still the hard fence. When a max-live-workers cap is set it also fails closed (`error: \"max-live-workers\"`) while that many workers are still in flight — settle or steer one before spawning another. Pass a `key` naming the assignment to make it run-once ACROSS restarts: a key that already completed returns the finished result (`resumed: \"completed\"` — no work re-runs, nothing is spent), a key whose prior attempt failed or was lost with a dead process spawns fresh and says so (`resumed: \"retried\" | \"lost\"`), and a key still running is refused (`error: \"duplicate-key\"`). Returns `freeSlots`: how many MORE workers you can start right now (`null` = uncapped). While `freeSlots > 0` there is idle capacity — call this again to fill it rather than waiting; parallel workers finish the run sooner than one at a time.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					profile: spawnProfileArg(),
+					task: { description: "The task the worker should perform." },
+					label: {
+						type: "string",
+						description: "Optional trace label."
+					},
+					key: {
+						type: "string",
+						description: "Optional semantic name for this assignment (e.g. \"summarize-ch3\"). The same key never runs twice: completed keys return their committed result, even after a coordinator restart."
+					},
+					continuity: {
+						type: "string",
+						enum: ["fresh", "resume"],
+						description: "How this spawn continues the node's prior work. \"fresh\" (the default) starts a brand-new session. \"resume\" re-attaches to the node's most recent SETTLED worker: a NEW live worker is spawned whose session continues where that worker stopped (the backend receives the prior workerId and the resume sequence). Resume fails closed when the node has no settled prior worker (`error: \"resume-no-prior\"` — spawn it fresh first), while a prior worker of the node is still live (`error: \"resume-while-live\"` — steer_agent is the live-worker channel), and under a `key` (`error: \"resume-with-key\"` — keys are run-once, resume runs again). Omit to use the run's declared default for this profile name."
+					},
+					budget: {
+						type: "object",
+						description: "Optional per-spawn budget that merges over the per-worker default (per field). Only set the ceilings this sub-task needs raised; the conserved pool still fences.",
+						properties: {
+							maxIterations: {
+								type: "number",
+								minimum: 0
+							},
+							maxTokens: {
+								type: "number",
+								minimum: 0
+							},
+							maxUsd: {
+								type: "number",
+								minimum: 0
+							},
+							deadlineMs: {
+								type: "number",
+								minimum: 0
+							}
+						}
+					}
+				},
+				required: ["profile", "task"]
+			},
+			handler: async (raw) => {
+				const a = obj(raw);
+				const key = a.key === void 0 ? void 0 : str(a.key, "key");
+				if (!(key !== void 0 && completedKeys.has(key)) && !usesTreeWideLimit() && maxLiveWorkers !== void 0 && maxLiveWorkers > 0 && liveWorkerCount() >= maxLiveWorkers) return Promise.resolve({
+					error: "max-live-workers",
+					live: liveWorkerCount(),
+					freeSlots: freeWorkerSlots()
+				});
+				const parsedProfile = agentProfileSchema.safeParse(a.profile);
+				if (!parsedProfile.success) return Promise.resolve({
+					error: "invalid-profile",
+					issues: parsedProfile.error.issues.map((issue) => ({
+						path: issue.path.join("."),
+						message: issue.message
+					}))
+				});
+				const profile = detachedFrozen(parsedProfile.data);
+				const continuity = resolveContinuity(parseContinuity(a.continuity), profile.name, key);
+				if ("error" in continuity) return Promise.resolve({
+					error: continuity.error,
+					hint: continuity.hint,
+					live: liveWorkerCount(),
+					freeSlots: freeWorkerSlots()
+				});
+				const task = detachedFrozen(a.task);
+				const label = typeof a.label === "string" ? a.label : "worker";
+				if (opts.preflightSpawn) {
+					const preflightProfile = opts.resolveSpawnProfile ? detachedFrozen(opts.resolveSpawnProfile(profile)) : profile;
+					const refusal = await opts.preflightSpawn(preflightProfile, {
+						label,
+						...key !== void 0 ? { key } : {},
+						task
+					});
+					if (refusal) {
+						preflightCounts[refusal.cause] += 1;
+						return {
+							error: "preflight-refused",
+							cause: refusal.cause,
+							detail: refusal.detail,
+							live: liveWorkerCount(),
+							freeSlots: freeWorkerSlots()
+						};
+					}
+				}
+				const budget = Object.freeze(a.budget === void 0 ? opts.perWorker : mergeBudget(opts.perWorker, a.budget));
+				const assignmentId = key !== void 0 ? `key:${key}` : `ordinal:${unkeyedAssignmentOrdinal++}`;
+				const peerMailUrl = peerMail?.mintCapability(assignmentId);
+				const context = Object.freeze({
+					assignmentId,
+					parentNodeId: opts.scope.view.root,
+					budget,
+					task,
+					label,
+					...key !== void 0 ? { key } : {},
+					continuity: continuity.continuity,
+					...continuity.continuity === "resume" ? { resume: continuity.resume } : {},
+					...peerMailUrl !== void 0 ? { peerMailUrl } : {}
+				});
+				const res = opts.scope.spawn(() => opts.makeWorkerAgent(profile, context), task, {
+					budget,
+					label,
+					assignmentId,
+					...key !== void 0 ? { key } : {}
+				});
+				if (res.ok && res.prior?.state === "completed") {
+					const s = res.prior.settled;
+					if (key !== void 0) completedKeys.add(key);
+					const { id, status, resumed: _resumed, ...evidence } = projectSettled(s);
+					return Promise.resolve({
+						workerId: id,
+						resumed: "completed",
+						status,
+						...evidence,
+						live: liveWorkerCount(),
+						freeSlots: freeWorkerSlots()
+					});
+				}
+				if (res.ok) {
+					watchWorker(res.handle.id);
+					liveHandles.set(res.handle.id, res.handle);
+					peerMail?.bindCapability(assignmentId, res.handle.id);
+					if (key !== void 0) keyByWorker.set(res.handle.id, key);
+					if (typeof profile.name === "string" && profile.name.length > 0) profileNameByWorker.set(res.handle.id, profile.name);
+				}
+				const priorHistory = res.ok && res.prior !== void 0 && res.prior.state !== "completed" ? {
+					resumed: res.prior.state,
+					priorWorkerId: res.prior.priorId,
+					...res.prior.state === "retried" ? { priorReason: res.prior.reason } : {}
+				} : {};
+				return Promise.resolve(res.ok ? {
+					workerId: res.handle.id,
+					assignmentId: res.handle.assignmentId ?? assignmentId,
+					...res.handle.identity === void 0 ? {} : { identity: res.handle.identity },
+					...res.handle.materialization === void 0 ? {} : { materialization: res.handle.materialization },
+					...res.handle.executionBindings === void 0 ? {} : { executionBindings: res.handle.executionBindings },
+					continuity: continuity.continuity,
+					...continuity.continuity === "resume" ? { resume: continuity.resume } : {},
+					live: liveWorkerCount(),
+					freeSlots: freeWorkerSlots(),
+					...priorHistory
+				} : {
+					error: res.reason,
+					...res.reason === "usd-unbudgeted" ? { hint: "This run's root budget declares no maxUsd, so a child budget naming maxUsd can never be admitted — at any amount. Retrying with a smaller maxUsd will fail identically. Spawn with a budget that omits maxUsd, or ask the caller to give the run a root maxUsd." } : {},
+					live: liveWorkerCount(),
+					freeSlots: freeWorkerSlots()
+				});
+			}
+		},
+		{
+			name: "observe_agent",
+			description: "Inspect a worker WHILE IT RUNS, not only after it finishes: status, spend so far, and `progress` — how long since it last did anything (`idleMs`), whether that counts as stalled, how many turns it has taken, the last tools/files it touched (`recentActivity`), what its executor CHANGED about the profile you gave it (`derived` — an MCP config it materialized, an extension it had to add), whether a steer can even reach it (`steerable`), and how many steers it has not yet read (`pendingMessages`). Returns the settled output artifact once it exists. Use this BEFORE steer_agent: a steer is only worth sending when the progress says the worker is on the wrong path or has stopped making any.",
+			inputSchema: {
+				type: "object",
+				properties: { workerId: idArg },
+				required: ["workerId"]
+			},
+			handler: async (raw) => {
+				const id = str(obj(raw).workerId, "workerId");
+				const node = opts.scope.view.nodes.find((n) => n.id === id);
+				if (!node) {
+					const resumed = opts.scope.resume?.view.nodes.find((n) => n.id === id);
+					if (!resumed) return { error: `unknown workerId ${JSON.stringify(id)}` };
+					const output = resumed.outRef ? await opts.blobs.get(resumed.outRef) : void 0;
+					return {
+						...projectNodeEvidence(resumed, true),
+						outRef: resumed.outRef ?? null,
+						output: output ?? null,
+						progress: null
+					};
+				}
+				const output = node.outRef ? await opts.blobs.get(node.outRef) : void 0;
+				const progress = readProgress(id);
+				return {
+					...projectNodeEvidence(node),
+					outRef: node.outRef ?? null,
+					output: output ?? null,
+					progress: progress ?? null
+				};
+			}
+		},
+		{
+			name: "steer_agent",
+			description: "Send a message DOWN to a still-LIVE worker (parent→child): a new instruction, a course correction, or a continuation. The worker drains it at its next step boundary — and before it may settle, so it cannot finish while a message it never read is pending. A worker that already settled is gone (returns delivered:false) — spawn a fresh one instead.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					workerId: idArg,
+					instruction: {
+						type: "string",
+						description: "What the worker should do next."
+					},
+					interrupt: {
+						type: "boolean",
+						description: "true = forceful: abort the worker’s in-flight inference so it re-plans on the NEXT turn (a tool already mid-execution finishes first; only the owned tool-loop honors this). false/omitted = queued: it flushes at the next step boundary (and before it may settle)."
+					}
+				},
+				required: ["workerId", "instruction"]
+			},
+			handler: async (raw) => {
+				const a = obj(raw);
+				const workerId = str(a.workerId, "workerId");
+				const instruction = str(a.instruction, "instruction");
+				const delivery = await steerWorker(workerId, instruction, { interrupt: a.interrupt === true });
+				if (delivery.delivered) return {
+					delivered: true,
+					progress: readProgress(workerId) ?? null
+				};
+				return {
+					delivered: false,
+					reason: delivery.outcome,
+					progress: readProgress(workerId) ?? null
+				};
+			}
+		},
+		{
+			name: "await_event",
+			description: "Wait for and pull the next message a worker, sub-driver, or analyst sent up — the unified inbox. An event is one of: a settled worker output ('settled'), a question needing your answer ('question', from ask_parent / the worker's ask-user), or a trace-analyst finding ('finding', from analyze-on-settle). Pass kinds:['settled'] for just the next finished worker; omit `kinds` to also receive questions and findings. Returns { idle: true } when nothing is queued and no workers are live. If a worker is still running when the wait elapses, returns { pending: true, live: [...] } (the workers still in flight) instead of blocking indefinitely — call await_event again to keep waiting; the settlement is not lost. Every reply carries `freeSlots`: how many more workers you can start right now (`null` = uncapped). A settled worker frees its slot, so `freeSlots > 0` means capacity is sitting idle — spawn into it before waiting again.",
+			inputSchema: {
+				type: "object",
+				properties: { kinds: {
+					type: "array",
+					items: {
+						type: "string",
+						enum: [...awaitableEventKinds]
+					},
+					description: "Restrict to these event kinds (any if omitted)."
+				} }
+			},
+			handler: async (raw) => {
+				const k = obj(raw).kinds;
+				const kinds = Array.isArray(k) ? k.filter(isAwaitableEventKind) : void 0;
+				let ev = bus.pull(kinds);
+				if (ev) return {
+					...projectEvent(ev),
+					freeSlots: freeWorkerSlots()
+				};
+				const raced = await raceDrainWithTimeout(ensureDrain());
+				if (raced === void 0) return {
+					pending: true,
+					live: liveSnapshot(),
+					freeSlots: freeWorkerSlots()
+				};
+				ev = bus.pull(kinds);
+				if (!ev) return {
+					idle: !raced.drained,
+					freeSlots: freeWorkerSlots()
+				};
+				return {
+					...projectEvent(ev),
+					freeSlots: freeWorkerSlots()
+				};
+			}
+		},
+		{
+			name: "list_questions",
+			description: "List questions raised by workers, drivers, or analysts. Blocking stop behavior follows questionPolicy.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			},
+			handler: () => Promise.resolve({ questions })
+		},
+		{
+			name: "answer_question",
+			description: "Record an answer, deferral, or escalation for a loop question.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					questionId: { type: "string" },
+					answer: { type: "string" },
+					by: {
+						type: "string",
+						description: "Node id or \"user\"."
+					},
+					deferReason: { type: "string" },
+					escalateTo: {
+						type: "string",
+						enum: questionEscalationTargets
+					},
+					escalateReason: { type: "string" }
+				},
+				required: ["questionId"]
+			},
+			handler: async (raw) => {
+				const a = obj(raw);
+				const questionId = str(a.questionId, "questionId");
+				if (typeof a.answer === "string" && a.answer.length > 0) {
+					const answer = a.answer;
+					const pendingQuestion = questions.find((question) => question.id === questionId);
+					if (pendingQuestion === void 0) throw new Error(`unknown questionId ${JSON.stringify(questionId)}`);
+					const interrupt = pendingQuestion.urgency === "blocks-run" || pendingQuestion.urgency === "blocks-step";
+					const authorized = authorizeInstruction("answer", pendingQuestion.from, answer, interrupt, questionId);
+					await recordInstruction(authorized);
+					const delivery = await attemptDelivery(authorized, {
+						answer: authorized.instruction,
+						questionId,
+						interrupt
+					});
+					return {
+						question: delivery.delivered ? decideQuestion(questionId, {
+							kind: "answer",
+							answer: authorized.instruction,
+							by: typeof a.by === "string" && a.by.length > 0 ? a.by : "user"
+						}) : pendingQuestion,
+						delivered: delivery.delivered,
+						...delivery.delivered ? {} : { reason: delivery.outcome }
+					};
+				}
+				if (typeof a.deferReason === "string" && a.deferReason.length > 0) return Promise.resolve({ question: decideQuestion(questionId, {
+					kind: "defer",
+					reason: a.deferReason
+				}) });
+				if (typeof a.escalateTo === "string" && a.escalateTo.length > 0) {
+					if (!isQuestionEscalationTarget(a.escalateTo)) throw new Error(`answer_question: escalateTo must be one of ${questionEscalationTargets.join(", ")}; received ${JSON.stringify(a.escalateTo)}`);
+					const escalateReason = typeof a.escalateReason === "string" && a.escalateReason.length > 0 ? a.escalateReason : "driver escalated";
+					return Promise.resolve({ question: decideQuestion(questionId, {
+						kind: "escalate",
+						to: a.escalateTo,
+						reason: escalateReason
+					}) });
+				}
+				throw new Error("answer_question: provide answer, deferReason, or escalateTo");
+			}
+		},
+		{
+			name: "ask_parent",
+			description: "Raise a question to the parent driver/Pi/user when this driver cannot decide.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					from: { type: "string" },
+					level: {
+						type: "string",
+						enum: [
+							"worker",
+							"driver",
+							"loop"
+						]
+					},
+					question: { type: "string" },
+					reason: { type: "string" },
+					urgency: {
+						type: "string",
+						enum: [
+							"continue-without",
+							"blocks-step",
+							"blocks-run"
+						]
+					}
+				},
+				required: [
+					"from",
+					"level",
+					"question",
+					"reason",
+					"urgency"
+				]
+			},
+			handler: async (raw) => {
+				const a = obj(raw);
+				const from = str(a.from, "from");
+				return { question: await emitNewQuestion(addQuestion({
+					from,
+					level: level(a.level),
+					question: str(a.question, "question"),
+					reason: str(a.reason, "reason"),
+					urgency: urgency(a.urgency)
+				}, from, {
+					kind: "escalate",
+					to: "parent",
+					reason: "asked parent"
+				})) };
+			}
+		},
+		...deliverable ? [{
+			name: "submit_result",
+			description: [
+				"Submit the complete result to the injected independent check.",
+				"The first passing result is retained; stop work when accepted.",
+				...deliverable.describe ? [`Expected result: ${deliverable.describe}`] : []
+			].join(" "),
+			inputSchema: {
+				type: "object",
+				properties: { result: { description: "The complete result in the form requested by the task." } },
+				required: ["result"],
+				additionalProperties: false
+			},
+			handler: async (raw) => {
+				if (submitted) return {
+					accepted: true,
+					retained: "earlier-passing-result",
+					stop: true
+				};
+				const a = obj(raw);
+				if (!Object.hasOwn(a, "result")) throw new Error("submit_result: \"result\" is required");
+				const result = structuredClone(a.result);
+				let accepted = false;
+				try {
+					accepted = await deliverable.check(result) === true;
+				} catch {
+					accepted = false;
+				}
+				if (!accepted) return {
+					accepted: false,
+					stop: false
+				};
+				if (submitted) return {
+					accepted: true,
+					retained: "earlier-passing-result",
+					stop: true
+				};
+				submitted = Object.freeze({ result });
+				stopped = true;
+				reason = "result-accepted";
+				notifyStop();
+				return {
+					accepted: true,
+					retained: "this-result",
+					stop: true
+				};
+			}
+		}] : [],
+		{
+			name: "stop",
+			description: "Declare the run complete.",
+			inputSchema: {
+				type: "object",
+				properties: { reason: {
+					type: "string",
+					description: "Why you are stopping."
+				} }
+			},
+			handler: (raw) => {
+				const blocking = blockingQuestionsForStop();
+				if (blocking.length) return Promise.resolve({
+					stopped: false,
+					error: "unresolved-blocking-questions",
+					questions: blocking
+				});
+				stopped = true;
+				const r = obj(raw).reason;
+				reason = typeof r === "string" ? r : void 0;
+				notifyStop();
+				return Promise.resolve({ stopped: true });
+			}
+		}
+	];
+	if (opts.analysts) {
+		tools.push({
+			name: "list_analysts",
+			description: "List trace-analyst lenses available to run over a settled worker.",
+			inputSchema: {
+				type: "object",
+				properties: {}
+			},
+			handler: () => Promise.resolve({ analysts: opts.analysts?.kinds })
+		});
+		tools.push({
+			name: "run_analyst",
+			description: "Apply an analyst lens to a settled worker trace.",
+			inputSchema: {
+				type: "object",
+				properties: {
+					kind: {
+						type: "string",
+						description: "The analyst kind id."
+					},
+					workerId: idArg
+				},
+				required: ["kind", "workerId"]
+			},
+			handler: async (raw) => {
+				const a = obj(raw);
+				const id = str(a.workerId, "workerId");
+				const node = nodeForWorker(id);
+				if (!node) return { error: `unknown workerId ${JSON.stringify(id)}` };
+				if (isLiveNodeStatus(node.status)) return { error: `worker ${JSON.stringify(id)} has not settled — no trace to analyze yet` };
+				const trace = ledger.find((worker) => worker.id === id)?.trace ?? node.trace ?? {
+					status: "unavailable",
+					reason: "legacy-settlement-without-trace-evidence"
+				};
+				let store;
+				try {
+					store = await workerTraceAnalysisStore(trace, opts.blobs);
+				} catch (error) {
+					return {
+						error: error instanceof Error ? error.message : String(error),
+						trace
+					};
+				}
+				return { findings: await opts.analysts?.run(str(a.kind, "kind"), store) };
+			}
+		});
+	}
+	const abortWorker = (ref, reason) => {
+		const live = opts.scope.view.nodes.filter((node) => isLiveNodeStatus(node.status));
+		const target = live.find((node) => node.id === ref) ?? live.find((node) => profileNameByWorker.get(node.id) === ref) ?? live.find((node) => node.label === ref);
+		if (target === void 0) return void 0;
+		const handle = liveHandles.get(target.id);
+		if (handle === void 0) return void 0;
+		handle.abort(reason);
+		return {
+			id: target.id,
+			label: target.label
+		};
+	};
+	return {
+		tools,
+		ready,
+		history: () => bus.history(),
+		raiseFinding: (finding) => bus.publish({
+			type: "finding",
+			finding: canonicalFindingEvent(finding)
+		}).then(() => void 0),
+		steerWorker,
+		stats: () => opts.preflightSpawn === void 0 ? bus.stats() : {
+			...bus.stats(),
+			preflight: { ...preflightCounts }
+		},
+		isStopped: () => stopped,
+		stopReason: () => reason,
+		submittedResult: () => submitted,
+		settled: () => ledger,
+		questions: () => questions,
+		drainResolved,
+		abortWorker,
+		...peerMail ? { peerMail } : {}
+	};
+}
+function nextUnkeyedAssignmentOrdinal(scope) {
+	let next = 0;
+	const views = [scope.resume?.view, scope.view];
+	for (const view of views) {
+		if (view === void 0) continue;
+		for (const node of view.nodes) {
+			const match = /^ordinal:(\d+)$/.exec(node.assignmentId ?? "");
+			if (match === null) continue;
+			const ordinal = Number(match[1]);
+			if (!Number.isSafeInteger(ordinal)) throw new Error(`coordination: durable assignment id '${node.assignmentId}' exceeds the safe ordinal range`);
+			next = Math.max(next, ordinal + 1);
+		}
+	}
+	if (!Number.isSafeInteger(next)) throw new Error("coordination: durable assignment ordinal space is exhausted");
+	return next;
+}
+/** Stringify a findings payload for a routed delivery; never throws (a cyclic payload degrades to
+*  its String form rather than killing the settle path). */
+function safeJsonText(value) {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+//#region src/runtime/supervise/coordination-log.ts
+/**
+* Durable side-log for coordination evidence the spawn journal does not own: questions, analyst
+* findings, answer decisions, authorized continuation receipts, delivery-attempt markers, and
+* delivery outcomes. A durable run
+* (`supervise({ runDir })`) appends them as they publish and loads them on resume, so a restarted
+* coordinator retains the exact evidence produced by prior processes.
+*
+* Answer down-events also fold status on load: a question answered before the crash reloads as
+* `answered`, not as a re-blocking `open`. Settled events are skipped (the spawn journal is their
+* ledger). A receipt followed by an attempt but no outcome proves the process died in the delivery
+* window; that outcome remains unknown and no prior instruction is auto-delivered.
+*
+* JSONL, one fsynced record per event, keyed by `runId` — several runs may share one log file
+* exactly as they share one spawn-journal file.
+*
+* @experimental
+*/
+/** Persist prior context plus exact continuation authorization, attempt, and result evidence.
+* Settlements have their own journal. */
+function persisted(event) {
+	return event.type !== "settled";
+}
+/** FS-backed `CoordinationLog`: append-only JSONL, fsynced per record. */
+var FileCoordinationLog = class {
+	path;
+	appendTail = Promise.resolve();
+	constructor(path) {
+		this.path = path;
+	}
+	async append(runId, record, ownerId) {
+		if (!persisted(record.event)) return;
+		const append = this.appendTail.then(() => this.appendRecord(runId, record, ownerId));
+		this.appendTail = append.catch(() => void 0);
+		return append;
+	}
+	async appendRecord(runId, busRecord, ownerId) {
+		const fs = await import("node:fs/promises");
+		const path = await import("node:path");
+		await fs.mkdir(path.dirname(this.path), { recursive: true });
+		const record = {
+			runId,
+			...ownerId !== void 0 ? { ownerId } : {},
+			...busRecord
+		};
+		const needsSeparator = await prepareJsonlAppend(this.path);
+		const fh = await fs.open(this.path, "a");
+		try {
+			await writeAllBytes(fh, `${needsSeparator ? "\n" : ""}${JSON.stringify(record)}\n`);
+			await fh.sync();
+		} finally {
+			await fh.close();
+		}
+	}
+	async load(runId, ownerId) {
+		const fs = await import("node:fs/promises");
+		let text;
+		try {
+			text = await fs.readFile(this.path, "utf8");
+		} catch (err) {
+			if (isNoEntError(err)) return emptyPriorCoordination(ownerId);
+			throw err;
+		}
+		const byId = /* @__PURE__ */ new Map();
+		const findings = [];
+		const continuations = [];
+		const deliveryEvidence = [];
+		const mail = [];
+		const records = [];
+		let legacySeq = 0;
+		for (const stored of parseCommittedJsonLines(text, this.path)) {
+			if (stored.runId !== runId) continue;
+			if (ownerId !== void 0 && stored.ownerId !== ownerId) continue;
+			const record = "seq" in stored ? {
+				seq: stored.seq,
+				at: stored.at,
+				priority: stored.priority,
+				event: stored.event
+			} : {
+				seq: legacySeq++,
+				at: Date.parse(stored.at),
+				priority: 0,
+				event: stored.event
+			};
+			records.push(record);
+			const ev = record.event;
+			if (ev.type === "delivery-attempt" || ev.type === "steer" || ev.type === "answer") deliveryEvidence.push(ev);
+			if (ev.type === "question") byId.set(ev.question.id, ev.question);
+			else if (ev.type === "finding") findings.push(ev.finding);
+			else if (ev.type === "answer") {
+				const prior = byId.get(ev.questionId);
+				if (prior && ev.down.delivered) byId.set(ev.questionId, {
+					...prior,
+					status: "answered",
+					decision: {
+						kind: "answer",
+						answer: ev.down.instruction,
+						by: "prior-run"
+					}
+				});
+			} else if (ev.type === "instruction") continuations.push(ev.instruction);
+			else if (ev.type === "mail") mail.push(ev.mail);
+		}
+		return {
+			...ownerId !== void 0 ? { ownerId } : {},
+			questions: [...byId.values()],
+			findings,
+			continuations,
+			deliveryEvidence,
+			mail,
+			records
+		};
+	}
+};
+function emptyPriorCoordination(ownerId) {
+	return {
+		...ownerId !== void 0 ? { ownerId } : {},
+		questions: [],
+		findings: [],
+		continuations: [],
+		deliveryEvidence: [],
+		mail: [],
+		records: []
+	};
+}
+//#endregion
+//#region src/runtime/supervise/run-context.ts
+/**
+*
+* `createInMemoryRunContext` — the one-call bundle of the in-memory stores a
+* `createSupervisor().run(root, task, opts)` needs: a fresh `InMemorySpawnJournal`
+* (the event-sourced spawn log), a fresh `InMemoryResultBlobStore` (the
+* content-addressed `outRef` payload store the driver's `observe`/`finalize` reads
+* settled outputs through), and a fresh `createExecutorRegistry()` (the open
+* `AgentSpec → Executor` resolver).
+*
+* It exists to kill the boilerplate every offline/local supervised run repeats by
+* hand — three constructors threaded into `SupervisorOpts` — and to single-source the
+* ONE wiring invariant that is easy to get wrong: when the root is the recursive
+* `driverAgent` LLM-driver brain AND it may spawn DRIVER children (agents
+* driving agents), the registry MUST be wrapped with `withDriverExecutor` so a
+* `role: 'driver'` child resolves to the nested-scope executor — and that SAME blob
+* store MUST be the one passed to `driverAgent({ blobs })`, or the driver
+* reads from a different store than the scope writes to. Pass `{ withDriver: true }`
+* and reuse the returned `blobs` for both.
+*
+* The spread shape matches `SupervisorOpts` exactly, so the call site reads:
+*   const run = createInMemoryRunContext()
+*   await createSupervisor().run(root, task, { budget, runId, ...run })
+*
+* @experimental
+*/
+/**
+* Build a fresh in-memory run context. Every call returns NEW stores (no shared global
+* state between runs), so two runs never cross-contaminate their journals/blobs.
+*/
+function createInMemoryRunContext(opts = {}) {
+	const base = createExecutorRegistry();
+	return {
+		journal: new InMemorySpawnJournal(),
+		blobs: new InMemoryResultBlobStore(),
+		executors: opts.withDriver ? withDriverExecutor(base) : base
+	};
+}
+/**
+* Build a DURABLE run context: the spawn journal and the result blobs are file-backed (fsynced
+* per append/write) under `dir`, and the context carries `resume: true` so spreading it into
+* `SupervisorOpts` makes the supervisor `loadTree`-first. A run that dies mid-flight therefore
+* resumes when it is re-run with the SAME `runId` and the SAME `dir`: the committed children come
+* back on `Scope.resume` (rehydrated by `replaySpawnTree`) instead of being re-executed.
+*
+* Layout: `${dir}/spawn-journal.jsonl` (one JSONL record per event), `${dir}/blobs/` (one
+* content-addressed JSON file per settled result), and `${dir}/coordination-log.jsonl`
+* (questions, findings, answer decisions, and authorized continuation receipts retained as
+* evidence). The directory is created on first write.
+*
+* Opt-in by construction — `createInMemoryRunContext()` is unchanged and stays the default, so no
+* existing consumer writes to disk or resumes unless it asks for this.
+*/
+function createFileRunContext(dir, opts = {}) {
+	const base = createExecutorRegistry();
+	return {
+		journal: new FileSpawnJournal(`${dir}/spawn-journal.jsonl`),
+		blobs: new FileResultBlobStore(`${dir}/blobs`),
+		executors: opts.withDriver ? withDriverExecutor(base) : base,
+		resume: true,
+		coordinationLog: new FileCoordinationLog(`${dir}/coordination-log.jsonl`)
+	};
+}
+//#endregion
+//#region src/runtime/anytime.ts
+/**
+* The best-so-far fold — the ONE definition of "how good was the run after k results", shared by
+* the post-run anytime report below and by the LIVE progress-based stop rules
+* (`supervise/stop-rules.ts`). Given the observed objective per settled result in order, it returns
+* the running maximum. A result with no objective (`undefined` — it failed, or it was never
+* scored) carries the previous best forward rather than resetting it.
+*
+* It is extracted rather than duplicated on purpose: a stop rule that decides a run has plateaued
+* must agree, number for number, with the report that later says whether stopping was right.
+*/
+function bestSoFar(values) {
+	const out = [];
+	let best = 0;
+	for (const v of values) {
+		if (typeof v === "number" && v > best) best = v;
+		out.push(best);
+	}
+	return out;
+}
+/** Mean of a best-so-far curve — the anytime AUC when the curve is normalized to [0,1]. Higher =
+*  the run climbed earlier. Shared with the stop rules so "improving" means one thing. */
+function areaUnderCurve(curve) {
+	if (curve.length === 0) return 0;
+	return curve.reduce((s, v) => s + v, 0) / curve.length;
+}
+/**
+* How many trailing entries of a best-so-far curve are within `minDelta` of the curve's value
+* `window` steps back — i.e. the length of the current PLATEAU, in settles. `0` means the most
+* recent settle improved the best by more than `minDelta`.
+*
+* The plateau math the live stop rules read. Defined here, beside the report that measures whether
+* the plateau was real, so there is exactly one notion of "not improving".
+*/
+function plateauLength(curve, minDelta) {
+	if (curve.length === 0) return 0;
+	const last = curve[curve.length - 1];
+	let i = curve.length - 1;
+	while (i > 0 && last - curve[i - 1] <= minDelta) i -= 1;
+	return curve.length - 1 - i;
+}
+const median = (xs) => {
+	if (xs.length === 0) return null;
+	const s = [...xs].sort((a, b) => a - b);
+	const mid = Math.floor(s.length / 2);
+	return s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+};
+/** Derive anytime metrics from waterfall spans. `targets` are the satisficing score
+*  bars (default [1] = fully resolved; COCO-style multi-target: [0.5, 0.8, 1]);
+*  `targetFor` overrides the bar per task (task-specific satisfaction) — when set, the
+*  per-task bar replaces every entry of `targets` for that task. */
+function anytimeReport(spans, opts) {
+	const targets = opts?.targets ?? [1];
+	const byRun = /* @__PURE__ */ new Map();
+	for (const s of spans) {
+		if (!s.label.startsWith("shot:")) continue;
+		const list = byRun.get(s.runId) ?? [];
+		list.push(s);
+		byRun.set(s.runId, list);
+	}
+	const perTask = [];
+	for (const [runId, shots] of byRun) {
+		const m = runId.match(/^agentic:(.+):(.+)$/);
+		const strategy = m?.[1] ?? runId;
+		const taskId = m?.[2] ?? runId;
+		const ordered = [...shots].sort((a, b) => (a.endMs ?? a.startMs) - (b.endMs ?? b.startMs));
+		const t0 = Math.min(...ordered.map((s) => s.startMs));
+		const taskTargets = opts?.targetFor ? [opts.targetFor(taskId)] : targets;
+		const bests = bestSoFar(ordered.map((s) => typeof s.score === "number" ? s.score : void 0));
+		let cumUsd = 0;
+		const points = [];
+		const hits = {};
+		for (const t of taskTargets) hits[String(t)] = null;
+		for (const [i, s] of ordered.entries()) {
+			cumUsd += s.usd;
+			const best = bests[i];
+			const elapsedMs = (s.endMs ?? s.startMs) - t0;
+			points.push({
+				elapsedMs,
+				cumUsd,
+				best
+			});
+			for (const t of taskTargets) if (hits[String(t)] === null && best >= t) hits[String(t)] = {
+				ms: elapsedMs,
+				shots: points.length,
+				usd: cumUsd
+			};
+		}
+		perTask.push({
+			taskId,
+			strategy,
+			points,
+			hits
+		});
+	}
+	const byStrategy = /* @__PURE__ */ new Map();
+	for (const t of perTask) {
+		const list = byStrategy.get(t.strategy) ?? [];
+		list.push(t);
+		byStrategy.set(t.strategy, list);
+	}
+	const perStrategy = [];
+	for (const [strategy, tasks] of byStrategy) {
+		const totalMs = tasks.reduce((s, t) => s + (t.points[t.points.length - 1]?.elapsedMs ?? 0), 0);
+		const totalUsd = tasks.reduce((s, t) => s + (t.points[t.points.length - 1]?.cumUsd ?? 0), 0);
+		const maxShots = Math.max(0, ...tasks.map((t) => t.points.length));
+		const curveByShot = [];
+		for (let i = 0; i < maxShots; i += 1) {
+			const vals = tasks.map((t) => t.points[Math.min(i, t.points.length - 1)].best);
+			curveByShot.push(vals.reduce((s, v) => s + v, 0) / vals.length);
+		}
+		const auc = areaUnderCurve(curveByShot);
+		const summaryTargets = opts?.targetFor ? [NaN] : targets;
+		for (const t of summaryTargets) {
+			const key = (taskCurve) => opts?.targetFor ? Object.values(taskCurve.hits)[0] ?? null : taskCurve.hits[String(t)] ?? null;
+			const reached = tasks.filter((x) => key(x) !== null);
+			perStrategy.push({
+				strategy,
+				target: t,
+				tasks: tasks.length,
+				reachedTarget: reached.length,
+				medianTttMs: median(reached.map((x) => key(x).ms)),
+				medianShotsToTarget: median(reached.map((x) => key(x).shots)),
+				ertMs: reached.length > 0 ? totalMs / reached.length : null,
+				erUsd: reached.length > 0 ? totalUsd / reached.length : null,
+				curveByShot,
+				auc
+			});
+		}
+	}
+	perStrategy.sort((a, b) => a.strategy.localeCompare(b.strategy) || a.target - b.target);
+	return {
+		targets,
+		perTask,
+		perStrategy
+	};
+}
+/** One row per (strategy, satisficing target): the shareable time-to-satisfactory table. */
+function renderAnytimeTable(report) {
+	const lines = [`anytime metrics · satisficing targets [${report.targets.join(", ")}] · ERT = Σ all wall-time / #successes (COCO)`, "strategy            ≥tgt   reach   med-TTT   med-shots   ERT(all-in)   $/success   AUC   curve"];
+	for (const s of report.perStrategy) {
+		const curve = s.curveByShot.map((v) => "▁▂▃▄▅▆▇█"[Math.min(7, Math.floor(v * 8))]).join("");
+		const tgt = Number.isNaN(s.target) ? "task" : s.target.toFixed(2);
+		lines.push(`${s.strategy.padEnd(19)} ${tgt.padStart(4)} ${String(s.reachedTarget).padStart(4)}/${String(s.tasks).padEnd(3)} ${s.medianTttMs === null ? "      —" : `${(s.medianTttMs / 1e3).toFixed(1).padStart(6)}s`}   ${s.medianShotsToTarget === null ? "    —" : String(s.medianShotsToTarget).padStart(5)}   ${s.ertMs === null ? "         —" : `${(s.ertMs / 1e3).toFixed(1).padStart(9)}s`}   ${s.erUsd === null ? "       —" : `$${s.erUsd.toFixed(4)}`}   ${s.auc.toFixed(2)}   ${curve}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/runtime/supervise/stop-rules.ts
+/**
+*
+* PROGRESS-BASED STOP RULES — end a long-horizon run for the right reason.
+*
+* Every existing bound is a CEILING: iterations, tokens, dollars, an absolute deadline, a turn
+* cap. A ceiling answers "may this run continue?" and never "is this run still getting anywhere?".
+* So a supervision tree that stopped learning at settle 4 keeps buying workers until it hits a
+* wall — the run ends on exhaustion, and the operator cannot tell a run that finished from a run
+* that ran out.
+*
+* A stop rule reads the run's own PROGRESS and decides. Three signals feed it:
+*   - the objective curve over settled work (best-so-far, from `anytime.ts` — see below),
+*   - the LIVE worker feed (`WorkerProgress`: `idleMs`, `stalled`, `turns`, `tokens`),
+*   - tree-level shape (how many are in flight, how many are waiting, when the last settle landed).
+*
+* ── Two boundaries this module holds deliberately ───────────────────────────────────────────────
+*
+* ENFORCEMENT lives here; THRESHOLDS do not. "Stop after 5 settles with no improvement" is a
+* judgment about a domain — how noisy its scores are, how expensive a worker is, how much a late
+* breakthrough is worth. That belongs to the caller (a loop, a bench, a product). Every rule below
+* takes its thresholds as required options with no hidden defaults for the numbers that decide;
+* the module ships the MECHANISM and refuses to ship the judgment.
+*
+* A stop rule can only ADD a stop, never remove one. The driver evaluates the hard ceilings
+* (`poolStarved`, `deadlinePassed`, abort, the driver's own stop) FIRST and independently; the
+* rule is consulted only when they all say "continue". So no rule can talk a run past its budget.
+*
+* ── What is reused, not re-derived ──────────────────────────────────────────────────────────────
+*
+* `anytime.ts` already computed best-so-far curves, their area, and plateau detection — but only
+* after a run was over, from waterfall spans. Rather than write a second copy for the live path,
+* `bestSoFar` / `areaUnderCurve` / `plateauLength` were extracted there and are imported here. A
+* stop rule that calls a run plateaued therefore agrees, number for number, with the report that
+* later judges whether stopping was right.
+*
+* @experimental
+*/
+const CONTINUE = { stop: false };
+/** Build the settled-work ledger a `StopRule` decides from: record each settlement (idempotent by
+*  id) and materialize a `ProgressView` combining the best-so-far curve with the live worker feed. */
+function createProgressTracker(opts = {}) {
+	const now = opts.now ?? Date.now;
+	const requireDelivered = opts.requireDelivered ?? true;
+	const minImprovement = opts.minImprovement ?? 0;
+	const seen = /* @__PURE__ */ new Set();
+	const recorded = [];
+	return {
+		record(sample) {
+			if (seen.has(sample.id)) return false;
+			seen.add(sample.id);
+			recorded.push(sample);
+			return true;
+		},
+		samples: () => [...recorded],
+		view(scope, viewOpts) {
+			const curve = bestSoFar(recorded.map((s) => requireDelivered && !s.delivered ? void 0 : s.objective));
+			const best = curve.length > 0 ? curve[curve.length - 1] : 0;
+			let lastImprovementAt = 0;
+			let lastImprovementIdx = -1;
+			let prev = 0;
+			for (const [i, value] of curve.entries()) {
+				if (value - prev > minImprovement) {
+					lastImprovementAt = recorded[i].at;
+					lastImprovementIdx = i;
+				}
+				prev = value;
+			}
+			const treeView = scope?.view;
+			const workers = [];
+			if (scope && treeView) for (const node of treeView.nodes) {
+				if (isTerminalNodeStatus(node.status)) continue;
+				if (node.status === "waiting") continue;
+				const p = scope.progress(node.id, viewOpts?.stallAfterMs !== void 0 ? {
+					now: now(),
+					stallAfterMs: viewOpts.stallAfterMs
+				} : { now: now() });
+				if (p) workers.push(p);
+			}
+			return {
+				now: now(),
+				settles: recorded.length,
+				delivered: recorded.filter((s) => s.delivered).length,
+				curve,
+				best,
+				auc: areaUnderCurve(curve),
+				lastSettleAt: recorded.length > 0 ? recorded[recorded.length - 1].at : 0,
+				lastImprovementAt,
+				settlesSinceImprovement: lastImprovementIdx < 0 ? recorded.length : recorded.length - 1 - lastImprovementIdx,
+				workers,
+				inFlight: treeView?.inFlight ?? 0,
+				waiting: treeView?.waiting ?? 0
+			};
+		},
+		evaluate(rule, scope, viewOpts) {
+			return rule(this.view(scope, viewOpts));
+		}
+	};
+}
+/** Build a `ProgressSample` from a scope settlement. The objective is the verdict score and
+*  `delivered` is the verdict's `valid` — the SAME single delivery signal `finalizeBestDelivered`
+*  and `defaultSelectWinner` use, so "progress" and "winner" cannot disagree. */
+function sampleFromSettled(settled, at) {
+	if (settled.kind === "down") return {
+		id: settled.handle.id,
+		at,
+		delivered: false
+	};
+	return {
+		id: settled.handle.id,
+		at,
+		...settled.verdict?.score !== void 0 ? { objective: settled.verdict.score } : {},
+		delivered: settled.verdict?.valid === true
+	};
+}
+/**
+* "Nothing new has happened." Fires when the run has produced no new settled work for `ms`, or no
+* IMPROVEMENT over the last `settles` settlements.
+*
+* A tree whose only remaining nodes are armed WAITS is exempt from the time bound: a run waiting
+* on CI is not a run that stopped making progress, and killing it there would defeat mechanic C.
+*/
+function noProgressFor(opts) {
+	if (opts.ms === void 0 && opts.settles === void 0) throw new ValidationError("noProgressFor: set at least one of { ms, settles }");
+	if (opts.ms !== void 0 && opts.ms <= 0) throw new ValidationError("noProgressFor: ms must be > 0");
+	if (opts.settles !== void 0 && opts.settles < 1) throw new ValidationError("noProgressFor: settles must be >= 1");
+	const minSettles = opts.minSettles ?? 1;
+	return (v) => {
+		if (v.settles < minSettles) return CONTINUE;
+		if (opts.settles !== void 0 && v.settlesSinceImprovement >= opts.settles) return {
+			stop: true,
+			reason: `no-progress: ${v.settlesSinceImprovement} settles with no improvement (limit ${opts.settles}), best=${v.best}`
+		};
+		if (opts.ms !== void 0 && v.waiting === 0 && v.lastSettleAt > 0) {
+			const idle = v.now - v.lastSettleAt;
+			if (idle >= opts.ms) return {
+				stop: true,
+				reason: `no-progress: ${idle}ms since the last settlement (limit ${opts.ms}ms)`
+			};
+		}
+		return CONTINUE;
+	};
+}
+/**
+* "The objective has stopped climbing." Fires when the best-so-far curve has risen by no more than
+* `minDelta` across the last `window` settlements.
+*
+* Built on `anytime.plateauLength` — the same plateau math the post-run anytime report uses, so a
+* rule that stops a run and a report that grades the decision cannot disagree about whether the
+* run was flat.
+*/
+function plateau(opts) {
+	if (!Number.isInteger(opts.window) || opts.window < 1) throw new ValidationError("plateau: window must be a positive integer");
+	if (!Number.isFinite(opts.minDelta) || opts.minDelta < 0) throw new ValidationError("plateau: minDelta must be >= 0");
+	const minSettles = opts.minSettles ?? opts.window;
+	return (v) => {
+		if (v.settles < minSettles) return CONTINUE;
+		const flat = plateauLength(v.curve, opts.minDelta);
+		if (flat >= opts.window) return {
+			stop: true,
+			reason: `plateau: best-so-far rose <= ${opts.minDelta} over the last ${flat} settles (window ${opts.window}), best=${v.best}, auc=${v.auc.toFixed(3)}`
+		};
+		return CONTINUE;
+	};
+}
+/**
+* "Everyone is stuck." Fires when every live worker reads `stalled` — no metered activity for
+* longer than the stall threshold — and none of the tree is merely waiting.
+*
+* `stalled` is a derived read at observation time, never a background watchdog; this rule only
+* reads it. A tree with armed waits never fires: waiting is not stalling.
+*/
+function allWorkersStalled(opts = {}) {
+	const minWorkers = opts.minWorkers ?? 1;
+	return (v) => {
+		if (v.waiting > 0) return CONTINUE;
+		if (v.workers.length < minWorkers) return CONTINUE;
+		if (!v.workers.every((w) => w.stalled)) return CONTINUE;
+		const worst = Math.max(...v.workers.map((w) => w.idleMs));
+		return {
+			stop: true,
+			reason: `all-stalled: ${v.workers.length} live workers idle, worst ${worst}ms`
+		};
+	};
+}
+/** Stop when ANY rule stops — the ordinary composition (each rule is a separate reason to end). */
+function anyOf(...rules) {
+	return (v) => {
+		for (const rule of rules) {
+			const d = rule(v);
+			if (d.stop) return d;
+		}
+		return CONTINUE;
+	};
+}
+/** Stop only when EVERY rule stops — for a conservative gate that needs corroboration. */
+function allOf(...rules) {
+	if (rules.length === 0) throw new ValidationError("allOf: needs at least one rule");
+	return (v) => {
+		const reasons = [];
+		for (const rule of rules) {
+			const d = rule(v);
+			if (!d.stop) return CONTINUE;
+			reasons.push(d.reason);
+		}
+		return {
+			stop: true,
+			reason: reasons.join(" AND ")
+		};
+	};
+}
+/**
+* Evaluate a rule against the run's settled work — the ONE evaluator both supervisor arms call.
+*
+* The router arm calls it before each driver inference turn; the harness arm calls it on each
+* worker settle. Ordering is the contract in both: the hard ceilings (`poolStarved`,
+* `deadlinePassed`, abort, the driver's own stop) are checked first and independently, so a stop
+* rule can only ever ADD a stop — it can never keep a run alive past a budget it has exhausted.
+*
+* Folding the whole roster each call is idempotent by worker id, so it costs O(settled) and never
+* double-counts. `settledAt` carries the instant the ledger recorded a settlement; `now()` is the
+* fallback resolution a per-turn guard has.
+*/
+function progressStop(tracker, rule, ledger, scope, now, stallAfterMs) {
+	for (const w of ledger.settled()) tracker.record({
+		id: w.id,
+		at: w.settledAt ?? now(),
+		...w.score !== void 0 ? { objective: w.score } : {},
+		delivered: w.status === "done" && w.valid === true
+	});
+	return tracker.evaluate(rule, scope, stallAfterMs !== void 0 ? { stallAfterMs } : void 0);
+}
+//#endregion
+//#region src/runtime/supervise/coordination-driver.ts
+/**
+*
+* `driverAgent` — the driver's BRAIN.
+*
+* The recursive driver-executor (`driver-executor.ts`) runs a driver `Agent.act` inside a
+* nested `Scope`; this is the intelligent `act`: it mounts the coordination MCP verbs
+* (`createCoordinationTools`) over that scope and runs an LLM tool-loop, so the driver
+* REASONS — spawn / observe / steer / await / stop — about how to drive its children,
+* instead of running a fixed script. Each turn: ask the driver LLM for tool calls, run them
+* against the live scope, fold the results back, repeat until the driver stops (no tool
+* calls) or the turn cap forces a keep-best finalize.
+*
+* Recursion composes through `makeWorkerAgent`: `spawn_agent` resolves a `profile` to a
+* worker LEAF or — when the profile is a driver — a `driverChild` wrapping ANOTHER
+* `driverAgent` over its own nested scope (see `driver-executor.ts`). So an agent
+* drives an agent that drives an agent, each an LLM tool-loop, all on one conserved-budget
+* tree.
+*
+* Two seams are INJECTED so the loop runs offline with no creds and stays decoupled:
+*  - `brain` (`ToolLoopChat`) — one driver-LLM turn over the canonical tool-loop seam; a test
+*    drives a scripted mock, production passes the router's tool-calling (`routerBrain`), a
+*    sandboxed harness drives the verbs as MCP tools. The same seam every tool-loop uses.
+*  - `systemPrompt` — the driver's stance (the agent-eval worker-driver prompt / the prompt
+*    generator). Injected, never hardcoded — the prompt is a pluggable role.
+*
+* @experimental
+*/
+/** The default chapter-close prompt: the brain summarizes its OWN progress for its future self before
+*  the detailed history is dropped. Emphasis on PENDING work — the part a too-eager chapter-close
+*  loses (the coding-burn counter-finding: closing after one fix leaves integration bugs uncircled). */
+const distillInstruction = "CONTEXT COMPACTION. Your detailed turn-by-turn history is about to be discarded to free your context window. Write a COMPLETE, compact handoff note for your future self so you can keep going without it. Cover: (1) what you have accomplished; (2) every worker you spawned and its current status/result; (3) what subtasks remain unfinished, failing, or unverified — be specific and exhaustive here, this is the part you must not lose; (4) your immediate next action. Do not call any tools; respond with the note only.";
+/** Factual ground truth for the digest — the live worker roster from Scope plus the delivered-result
+*  ledger, independent of whatever the brain's prose summary captures. */
+function summarizeRoster(view, settled) {
+	if (view.nodes.length === 0) return "Workers in current live scope: none yet.";
+	const settledById = new Map(settled.map((w) => [w.id, w]));
+	const lines = view.nodes.map((node) => formatRosterNode(node, settledById.get(node.id)));
+	return `Workers in current live scope (ground truth from the run, ${view.nodes.length} total, ${view.inFlight} in flight):\n${lines.join("\n")}`;
+}
+function formatRosterNode(node, settled) {
+	const result = settled?.status === "done" ? `, delivered=${settled.valid ?? false}${settled.score !== void 0 ? `, score=${settled.score}` : ""}${settled.outRef ? `, outRef=${settled.outRef}` : ""}` : settled?.status === "down" ? `, reason=${settled.reason ?? "unknown"}` : node.outRef ? `, outRef=${node.outRef}` : "";
+	return `- ${node.id}: ${node.status}, label=${node.label}, runtime=${node.runtime}${result}`;
+}
+/** Spawn-progress is impossible: the pool can't afford another worker AND nothing is in flight to
+*  await. A long-horizon driver bounded by the conserved pool stops here instead of spinning (the
+*  in-loop budget guard the turn cap alone never provided). Checks BOTH conserved channels: tokens
+*  (can't afford a worker) and usd (a usd-capped pool whose ceiling the driver's own metered
+*  inference has drained — `meter` debits usd, so without this a huge-token/small-usd pool would
+*  overspend usd up to the turn tripwire). */
+function poolStarved(scope, perWorker) {
+	const b = scope.budget;
+	if (scope.view.inFlight > 0 || scope.view.waiting > 0) return false;
+	const tokenStarved = b.tokensLeft < perWorker.maxTokens;
+	const iterationStarved = b.iterationsLeft <= 0;
+	const usdStarved = b.usdCapped && (b.usdLeft <= 0 || perWorker.maxUsd !== void 0 && b.usdLeft < perWorker.maxUsd);
+	return tokenStarved || iterationStarved || usdStarved;
+}
+/** The absolute wall-clock deadline (when the root set one) has passed. */
+function deadlinePassed(scope, now) {
+	const b = scope.budget;
+	return b.deadlineMs > 0 && now() >= b.deadlineMs;
+}
+/** The USD-denominated members of {@link PromptCacheUsage} — the schema, not a guess. Every
+*  other known member (`readTokens`, `writeTokens`, `missTokens`) is a token COUNT. */
+const PROMPT_CACHE_USD_FIELDS = /* @__PURE__ */ new Set(["readSavingsUsd"]);
+/** Dollar amounts above this are provider nonsense, not evidence. The old all-integer rule
+*  rejected them as a side effect; keeping an explicit ceiling preserves that protection
+*  without pretending a dollar amount is an integer. */
+const MAX_PROMPT_CACHE_USD = 1e6;
+/**
+* Validate provider-reported prompt-cache evidence.
+*
+* Prompt-cache carries two kinds of number and they obey different rules: token COUNTS are
+* integers, and USD amounts are fractional by nature. Applying the count rule to a dollar
+* field refuses every provider that reports cache savings in dollars — a healthy router
+* response carrying `readSavingsUsd: 0.0034` failed the driver outright before this split.
+*
+* Classification is schema-first: a field named in {@link PromptCacheUsage} is validated by
+* what that member IS. `promptCache` is an open record (the sandbox path forwards provider
+* fields verbatim), so an unknown field falls back to the `usd` name-suffix convention —
+* documented here as the contract a provider must follow to report dollars.
+*
+* Returns the refusal, or `undefined` when the evidence is acceptable.
+*/
+function validateDriverPromptCache(promptCache) {
+	for (const [field, value] of Object.entries(promptCache ?? {})) {
+		if (typeof value !== "number") continue;
+		if (PROMPT_CACHE_USD_FIELDS.has(field) || /usd$/i.test(field)) {
+			if (!Number.isFinite(value) || value < 0 || value > MAX_PROMPT_CACHE_USD) return new ValidationError(`driverAgent: prompt-cache field ${JSON.stringify(field)} must be a non-negative finite number of dollars`);
+			continue;
+		}
+		if (!Number.isSafeInteger(value) || value < 0) return new ValidationError(`driverAgent: prompt-cache field ${JSON.stringify(field)} must be a non-negative safe integer`);
+	}
+}
+/** The journal file `createFileRunContext` writes inside the run directory. The acknowledger
+*  reads it as EVIDENCE for the terminated-descendants set — the nested trees of a cancelled
+*  lead journal their terminal records there before the lead settles into this scope. */
+const SPAWN_JOURNAL_FILE = "spawn-journal.jsonl";
+/**
+* Apply externally admitted steers once from the owning manager's turn loop.
+*
+* The `unknown` acknowledgement lands before authorization or delivery. A crash after that write
+* can lose this steer, but a restarted manager never delivers it again. This is the same
+* at-most-once crash boundary as coordination instruction receipts: no duplicate instruction is
+* safer than replaying a mutation whose first delivery may already have succeeded.
+*/
+function createSteerAcknowledger(deps) {
+	const iso = () => new Date(deps.now()).toISOString();
+	const directChildId = (ref) => ref.startsWith(`${deps.ownerId}:s`) && /^s\d+$/.test(ref.slice(deps.ownerId.length + 1));
+	const base = (request) => ({
+		schemaVersion: 1,
+		operationId: request.operationId,
+		requestDigest: request.requestDigest,
+		worker: request.worker,
+		requestedAt: request.at
+	});
+	return { async pass(phase) {
+		for (const request of readWorkerSteerRequests(deps.dir)) {
+			if (!directChildId(request.worker)) continue;
+			if (readWorkerSteerAcknowledgement(deps.dir, request.operationId) !== void 0) continue;
+			if (phase === "final") {
+				writeWorkerSteerAcknowledgement(deps.dir, {
+					...base(request),
+					effect: "not_live",
+					observedAt: iso(),
+					detail: "run ended before the steer was applied"
+				});
+				continue;
+			}
+			if (!claimWorkerSteerDelivery(deps.dir, {
+				...base(request),
+				effect: "unknown",
+				observedAt: iso(),
+				detail: "delivery admitted; outcome not yet known"
+			})) continue;
+			try {
+				const outcome = await deps.coord.steerWorker(request.worker, request.message, { interrupt: request.interrupt });
+				const effect = outcome.delivered ? "delivered" : outcome.outcome === "runtime-has-no-inbox" ? "unsupported" : outcome.outcome === "unknown-worker" || outcome.outcome === "already-settled" || outcome.outcome === "scope-stopped" ? "not_live" : "unknown";
+				writeWorkerSteerAcknowledgement(deps.dir, {
+					...base(request),
+					effect,
+					observedAt: iso(),
+					detail: steerAcknowledgementDetail(outcome)
+				});
+			} catch (error) {
+				writeWorkerSteerAcknowledgement(deps.dir, {
+					...base(request),
+					effect: "unknown",
+					observedAt: iso(),
+					detail: "delivery outcome is unknown after a runtime error"
+				});
+			}
+		}
+	} };
+}
+function steerAcknowledgementDetail(outcome) {
+	switch (outcome.outcome) {
+		case "delivered": return "the owning manager delivered the steer to the exact live worker";
+		case "runtime-has-no-inbox": return "the exact worker does not expose a steer inbox";
+		case "unknown-worker": return "the owning manager does not know the exact worker";
+		case "already-settled": return "the exact worker settled before delivery";
+		case "scope-stopped": return "the owning manager stopped before delivery";
+		case "runtime-error": return "delivery outcome is unknown after a runtime error";
+	}
+}
+/**
+* The worker-cancel ACKNOWLEDGER — the runtime-side half of `run-layout`'s `cancelWorker`
+* contract, run from the coordination driver's turn loop (one cancellation-inbox read per turn,
+* no new process, no poller, no extra lifetime). Every manager with a `controlDir` mounts one;
+* OWNERSHIP keeps them from colliding: a request naming a node id is owned by the manager whose
+* own id is that node's parent, and a label/profile-name reference is owned by the `'run'`-scoped
+* (root) manager only — so exactly one acknowledger can ever apply one operation.
+*
+* Two-phase, honestly reported: `cancel_requested` is written the moment a live worker's abort is
+* issued (through the per-child abort chain the scope already owns, so siblings are untouched);
+* `cancelled` is written only when that worker's settlement is DELIVERED on the settle path with
+* a terminal `down`, and then the record names every subtree node id proven terminated. A worker
+* that already settled — or that settles `done` despite the abort — records `not_live`; a
+* reference matching nothing this manager owns stays pending (`cancelWorker` reports it
+* `unknown`). No path reports success for a missing worker.
+*
+* Expiry is run end, not a clock: `finish()` (after the final post-drain pass) writes `not_live`
+* for every owned request never applied and `unknown` for an issued abort whose settle the run
+* ended too soon to observe. A pending request can therefore never outlive its run and abort a
+* future spawn that happens to reuse a label.
+*
+* Idempotency is a lookup, in-process and across processes: an operation with a durable
+* acknowledgement is returned as-is and never re-applied.
+*/
+function createCancelAcknowledger(deps) {
+	const tracked = /* @__PURE__ */ new Map();
+	let runTracked;
+	const abortIssuedAt = /* @__PURE__ */ new Map();
+	const iso = () => new Date(deps.now()).toISOString();
+	const write = (record) => {
+		writeWorkerCancellation(deps.dir, record);
+		tracked.set(record.operationId, record);
+	};
+	/** `ref` is exactly one of THIS manager's direct-child node ids (`${ownerId}:s<seq>`). */
+	const directChildId = (ref) => ref.startsWith(`${deps.ownerId}:s`) && /^s\d+$/.test(ref.slice(deps.ownerId.length + 1));
+	/** Whether this acknowledger owns `ref`. A node id deeper in this subtree belongs to the nested
+	*  manager that parents it; anything that is not a node id under this manager is a
+	*  label/profile-name reference, owned by the `'run'`-scoped manager alone. */
+	const owned = (ref) => {
+		if (directChildId(ref)) return true;
+		if (deps.controlScope !== "run") return false;
+		return !ref.startsWith(`${deps.ownerId}:`) && ref !== deps.ownerId;
+	};
+	const deliveredTerminal = (id) => {
+		const row = deps.coord.settled().find((w) => w.id === id);
+		if (row !== void 0) return row.status;
+		const node = deps.scope.view.nodes.find((n) => n.id === id);
+		if (node === void 0) return void 0;
+		if (node.status === "done") return "done";
+		if (node.status === "failed" || node.status === "cancelled") return "down";
+	};
+	const apply = (request) => {
+		const aborted = deps.coord.abortWorker(request.worker, request.reason ?? "cancel requested");
+		const base = {
+			operationId: request.operationId,
+			worker: request.worker,
+			requestedAt: request.at,
+			observedAt: iso(),
+			...request.reason === void 0 ? {} : { reason: request.reason }
+		};
+		if (aborted !== void 0) {
+			abortIssuedAt.set(request.operationId, base.observedAt);
+			write({
+				...base,
+				effect: "cancel_requested",
+				workerId: aborted.id,
+				detail: `abort issued to live worker '${aborted.label}' (${aborted.id}); termination not yet proven`,
+				terminated: []
+			});
+			return;
+		}
+		const goneId = deps.scope.view.nodes.find((n) => (n.id === request.worker || n.label === request.worker) && isTerminalNodeStatus(n.status))?.id ?? deps.coord.settled().find((w) => w.id === request.worker)?.id;
+		if (goneId !== void 0) write({
+			...base,
+			effect: "not_live",
+			workerId: goneId,
+			detail: `worker '${goneId}' had already settled before this operation was applied`,
+			terminated: []
+		});
+	};
+	/** The proven-terminated set for one record: the worker plus every subtree id with a terminal
+	*  journal record at/after the abort was issued. Union with what the record already names, so
+	*  the set only ever grows (a late teardown journal adds; nothing removes). */
+	const provenTerminated = (record, workerId) => {
+		const since = abortIssuedAt.get(record.operationId) ?? record.observedAt;
+		return [.../* @__PURE__ */ new Set([
+			...record.terminated,
+			workerId,
+			...terminatedDescendants(deps.dir, workerId, since)
+		])].sort();
+	};
+	const reconcile = (record) => {
+		const workerId = record.workerId;
+		if (workerId === void 0) return;
+		const terminal = deliveredTerminal(workerId);
+		if (terminal === void 0) return;
+		if (terminal === "down") {
+			write({
+				...record,
+				effect: "cancelled",
+				observedAt: iso(),
+				terminated: provenTerminated(record, workerId),
+				detail: `worker '${workerId}' reached a terminal down state on the settle path`
+			});
+			return;
+		}
+		write({
+			...record,
+			effect: "not_live",
+			observedAt: iso(),
+			terminated: [],
+			detail: `worker '${workerId}' settled done despite the abort request; nothing was terminated`
+		});
+	};
+	/** Re-scan a `cancelled` record while the manager still turns: a descendant whose teardown
+	*  journals after the lead's settle joins the set on a later pass instead of being lost. Only
+	*  a grown set is re-written; the window needs the in-process abort instant, so a record a
+	*  PRIOR process closed stays as that process proved it. */
+	const regrow = (record) => {
+		const workerId = record.workerId;
+		if (workerId === void 0 || !abortIssuedAt.has(record.operationId)) return;
+		const terminated = provenTerminated(record, workerId);
+		if (terminated.length > record.terminated.length) write({
+			...record,
+			observedAt: iso(),
+			terminated
+		});
+	};
+	/**
+	* The RUN-scoped request: seen once, `cancel_requested` written the moment the run's cascading
+	* abort is issued through the one controller the run already has. The `supervise()` settle path
+	* records what the run then actually did — this manager cannot observe its own tree's terminal
+	* state from inside `act`.
+	*
+	* Applied only at a TURN boundary, never on the final post-drain pass: by then the driver has
+	* finished and drained, so a root abort could only void work that is already delivered. A
+	* request that arrives that late expires in `finish()` instead — it terminated nothing.
+	*/
+	const passRun = () => {
+		if (deps.controlScope !== "run" || deps.abortRun === void 0) return;
+		const request = readRunCancelRequest(deps.dir);
+		if (request === void 0) return;
+		if (runTracked !== void 0) return;
+		const prior = readRunCancellation(deps.dir, request.operationId);
+		if (prior !== void 0) {
+			runTracked = prior;
+			return;
+		}
+		const record = {
+			operationId: request.operationId,
+			effect: "cancel_requested",
+			requestedAt: request.at,
+			observedAt: iso(),
+			...request.reason === void 0 ? {} : { reason: request.reason },
+			detail: "root abort issued to the whole run; termination not yet proven"
+		};
+		writeRunCancellation(deps.dir, record);
+		runTracked = record;
+		deps.abortRun(request.reason ?? "run cancel requested");
+	};
+	const pass = (phase) => {
+		if (phase === "turn") passRun();
+		for (const request of readWorkerCancelRequests(deps.dir)) {
+			if (!owned(request.worker)) continue;
+			let record = tracked.get(request.operationId);
+			if (record === void 0) {
+				record = readWorkerCancellation(deps.dir, request.operationId);
+				if (record !== void 0) tracked.set(request.operationId, record);
+			}
+			if (record === void 0) {
+				apply(request);
+				continue;
+			}
+			if (record.effect === "cancel_requested") reconcile(record);
+			else if (record.effect === "cancelled") regrow(record);
+		}
+	};
+	return {
+		pass,
+		finish() {
+			const runRequest = deps.controlScope === "run" && deps.abortRun !== void 0 ? readRunCancelRequest(deps.dir) : void 0;
+			if (runRequest !== void 0 && readRunCancellation(deps.dir, runRequest.operationId) === void 0) writeRunCancellation(deps.dir, {
+				operationId: runRequest.operationId,
+				effect: "not_live",
+				requestedAt: runRequest.at,
+				observedAt: iso(),
+				...runRequest.reason === void 0 ? {} : { reason: runRequest.reason },
+				detail: "run ended before the request was applied"
+			});
+			for (const request of readWorkerCancelRequests(deps.dir)) {
+				if (!owned(request.worker)) continue;
+				const record = tracked.get(request.operationId) ?? readWorkerCancellation(deps.dir, request.operationId);
+				if (record === void 0) {
+					write({
+						operationId: request.operationId,
+						worker: request.worker,
+						effect: "not_live",
+						requestedAt: request.at,
+						observedAt: iso(),
+						...request.reason === void 0 ? {} : { reason: request.reason },
+						detail: "run ended before the request was applied",
+						terminated: []
+					});
+					continue;
+				}
+				if (record.effect === "cancel_requested") write({
+					...record,
+					effect: "unknown",
+					observedAt: iso(),
+					detail: "abort issued; run ended before termination was observed"
+				});
+			}
+		}
+	};
+}
+/**
+* Subtree node ids with a terminal `down`/`cancelled` journal record at or after `sinceIso` —
+* the abort-issue instant (the acknowledger's own `observedAt` on the `cancel_requested` record,
+* runtime clock), never the client's `requestedAt` — read from the durable spawn journal beside
+* the run layout. The set is proven at acknowledgement time and is approximate about post-abort
+* causation: a descendant that died of its OWN cause after the abort was issued is
+* indistinguishable from the cascade and may be included; one whose teardown journals late joins
+* on a later acknowledger pass; a teardown journal still absent when the run ends is absent from
+* the set. Ids are hierarchical (`parent:sN`), so `${nodeId}:` prefixes exactly the subtree.
+* Tolerant of a missing or partially-written journal: evidence that cannot be read names fewer
+* nodes, never wrong ones.
+*/
+function terminatedDescendants(dir, nodeId, sinceIso) {
+	let raw;
+	try {
+		raw = readFileSync(join(dir, SPAWN_JOURNAL_FILE), "utf8");
+	} catch {
+		return [];
+	}
+	const prefix = `${nodeId}:`;
+	const ids = /* @__PURE__ */ new Set();
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch {
+			continue;
+		}
+		if (parsed.kind !== "event" || parsed.event === void 0) continue;
+		const event = parsed.event;
+		if (!(event.kind === "settled" && event.status === "down" || event.kind === "cancelled")) continue;
+		if (typeof event.id !== "string" || !event.id.startsWith(prefix)) continue;
+		if (typeof event.at !== "string" || event.at < sinceIso) continue;
+		ids.add(event.id);
+	}
+	return [...ids].sort();
+}
+/**
+* Build the intelligent recursive driver. Its `act` is the LLM tool-loop; spawn it as a
+* `driverChild` (`driver-executor.ts`) to run it inside a nested scope, recursively.
+*/
+function driverAgent(opts) {
+	if (typeof opts.brain !== "function") throw new ValidationError("driverAgent: opts.brain must be a function");
+	if ((opts.extraTools?.length ?? 0) > 0 && typeof opts.executeExtraTool !== "function") throw new ValidationError("driverAgent: extraTools requires executeExtraTool (how to run a work-tool call)");
+	if ((opts.analyzeOnSettle ?? []).map(normalizeAnalyzeOnSettle).some((route) => route.agent === void 0) && !opts.analysts) throw new ValidationError("driverAgent: analyzeOnSettle requires analysts (the lens registry the kinds resolve against)");
+	const reserved = new Set(coordinationVerbNames);
+	for (const tool of opts.nodeTools ?? []) {
+		if (reserved.has(tool.name)) throw new ValidationError(`driverAgent: node tool "${tool.name}" collides with a coordination verb or another node tool`);
+		reserved.add(tool.name);
+	}
+	for (const t of opts.extraTools ?? []) {
+		if (reserved.has(t.name)) throw new ValidationError(`driverAgent: extra work tool "${t.name}" collides with a coordination verb or node tool`);
+		reserved.add(t.name);
+	}
+	if (opts.maxTurns !== void 0 && opts.maxTurns < 0) throw new ValidationError("driverAgent: maxTurns must be >= 0 (0 lifts the turn cap; bounds become the conserved pool + deadline + abort)");
+	const maxTurns = opts.maxTurns ?? 16;
+	const now = opts.now ?? Date.now;
+	const inbox = opts.inbox ?? createInbox();
+	return {
+		name: opts.name,
+		deliver(message) {
+			return inbox.deliver(message);
+		},
+		async act(task, scope) {
+			const coord = createCoordinationTools({
+				scope,
+				blobs: opts.blobs,
+				makeWorkerAgent: opts.makeWorkerAgent,
+				...opts.authorizeDownMessage ? { authorizeDownMessage: opts.authorizeDownMessage } : {},
+				perWorker: opts.perWorker,
+				...opts.deliverable ? { deliverable: opts.deliverable } : {},
+				...opts.maxLiveWorkers !== void 0 ? { maxLiveWorkers: opts.maxLiveWorkers } : {},
+				...opts.analysts ? { analysts: opts.analysts } : {},
+				...opts.analyzeOnSettle ? { analyzeOnSettle: opts.analyzeOnSettle } : {},
+				...opts.watchWorkers ? { watchWorkers: opts.watchWorkers } : {},
+				...opts.stallAfterMs !== void 0 ? { stallAfterMs: opts.stallAfterMs } : {},
+				...opts.continuityByProfile ? { continuityByProfile: opts.continuityByProfile } : {},
+				...opts.preflightSpawn ? { preflightSpawn: opts.preflightSpawn } : {},
+				...opts.resolveSpawnProfile ? { resolveSpawnProfile: opts.resolveSpawnProfile } : {},
+				...opts.onEvent ? { onEvent: opts.onEvent } : {},
+				...opts.replaySettlements ? { replaySettlements: true } : {},
+				...opts.priorCoordination?.questions.length ? { priorQuestions: opts.priorCoordination.questions } : {}
+			});
+			await coord.ready();
+			opts.onCoordinationTools?.(coord.tools);
+			const acknowledger = opts.controlDir === void 0 ? void 0 : createCancelAcknowledger({
+				dir: opts.controlDir,
+				coord,
+				scope,
+				now,
+				ownerId: scope.view.root,
+				controlScope: opts.controlScope ?? "run",
+				...opts.abortRun ? { abortRun: opts.abortRun } : {}
+			});
+			const steerAcknowledger = opts.controlDir === void 0 ? void 0 : createSteerAcknowledger({
+				dir: opts.controlDir,
+				coord,
+				now,
+				ownerId: scope.view.root
+			});
+			for (const w of scope.resume?.waits ?? []) {
+				const rearmed = scope.wait(w.spec, { label: w.label });
+				if (!rearmed.ok) throw new RuntimeRunStateError(`driverAgent: cannot re-arm resumed wait '${w.label}' (${rearmed.reason})`);
+			}
+			const byName = new Map([...coord.tools, ...opts.nodeTools ?? []].map((t) => [t.name, t]));
+			const toolSpecs = [
+				...coord.tools.map((t) => ({
+					type: "function",
+					function: {
+						name: t.name,
+						description: t.description,
+						parameters: t.inputSchema
+					}
+				})),
+				...(opts.nodeTools ?? []).map((t) => ({
+					type: "function",
+					function: {
+						name: t.name,
+						description: t.description,
+						parameters: t.inputSchema
+					}
+				})),
+				...(opts.extraTools ?? []).map((t) => ({
+					type: "function",
+					function: {
+						name: t.name,
+						description: t.description,
+						parameters: t.parameters
+					}
+				}))
+			];
+			const system = typeof opts.systemPrompt === "function" ? opts.systemPrompt(task) : opts.systemPrompt;
+			const tracker = opts.stopRule ? createProgressTracker({ now }) : void 0;
+			let progressStopReason;
+			let driverTurn = 0;
+			let driverCall = 0;
+			const meteredBrain = async (messages, tools, detail) => {
+				let res;
+				const call = driverCall;
+				driverCall += 1;
+				const callContext = Object.freeze({
+					signal: scope.signal,
+					callId: `${scope.view.root}:brain:${crypto.randomUUID()}`,
+					correlationId: scope.view.root
+				});
+				try {
+					res = await opts.brain(messages, tools, callContext);
+				} catch (error) {
+					opts.onProviderModel?.(void 0);
+					await meterRuntimeOwnedProviderAttempt(scope, unmeteredSpend(0), providerAttemptEvidence(void 0), {
+						driver: opts.name,
+						inferenceFailed: true,
+						call,
+						callId: callContext.callId,
+						correlationId: callContext.correlationId,
+						...detail
+					});
+					throw error;
+				}
+				let evidenceError;
+				opts.onProviderModel?.(res.model);
+				if (opts.expectedModel !== void 0) {
+					if (res.model === void 0) evidenceError = new ValidationError(`driverAgent: Router response omitted model identity; expected ${JSON.stringify(opts.expectedModel)}`);
+					else if (res.model !== opts.expectedModel) evidenceError = new ValidationError(`driverAgent: Router response reported model ${JSON.stringify(res.model)}; expected ${JSON.stringify(opts.expectedModel)}`);
+				}
+				if (res.transportAttempts !== void 0 && (!Number.isSafeInteger(res.transportAttempts) || res.transportAttempts < 1)) evidenceError = new ValidationError("driverAgent: transportAttempts must be a positive safe integer when reported");
+				evidenceError = validateDriverPromptCache(res.promptCache) ?? evidenceError;
+				const trustedCost = res.costProvenance === "provider-receipt" || res.costProvenance === "billing-receipt";
+				const cacheUsage = promptCacheTokenClasses(res.usage?.input, res.promptCache);
+				await meterRuntimeOwnedProviderAttempt(scope, {
+					iterations: 0,
+					tokens: {
+						input: res.usage?.input ?? 0,
+						output: res.usage?.output ?? 0,
+						...cacheUsage
+					},
+					...res.usage === void 0 ? { tokensKnown: false } : {},
+					usd: trustedCost ? res.costUsd ?? 0 : 0,
+					...trustedCost && res.costUsd !== void 0 ? {} : { usdKnown: false },
+					ms: 0
+				}, providerAttemptEvidence(res.model), {
+					driver: opts.name,
+					call,
+					callId: callContext.callId,
+					correlationId: callContext.correlationId,
+					toolCalls: (res.toolCalls ?? []).map((c) => c.name),
+					...res.model !== void 0 ? { model: res.model } : {},
+					...res.transportAttempts !== void 0 ? { transportAttempts: res.transportAttempts } : {},
+					...res.usage?.reasoning !== void 0 ? { reasoningTokens: res.usage.reasoning } : {},
+					...res.promptCache !== void 0 ? { promptCache: res.promptCache } : {},
+					...res.usageUnknown === true ? { streamUsageMissing: true } : {},
+					...res.costProvenance === "catalog-estimate" ? { estimatedCostUsd: res.costUsd } : {},
+					...detail
+				});
+				if (evidenceError !== void 0) throw evidenceError;
+				return res;
+			};
+			const chat = async (messages, tools) => {
+				const res = await meteredBrain(messages, tools, {
+					kind: "driver-inference",
+					turn: driverTurn
+				});
+				driverTurn += 1;
+				return res;
+			};
+			const compaction = opts.compaction ? {
+				thresholdTokens: opts.compaction.thresholdTokens,
+				distill: opts.compaction.distill ?? (async (msgs) => {
+					const roster = summarizeRoster(scope.view, coord.settled());
+					try {
+						const narrative = ((await meteredBrain([...msgs, {
+							role: "user",
+							content: distillInstruction
+						}], [], {
+							kind: "driver-compaction",
+							compactingTurn: driverTurn
+						})).content ?? "").trim();
+						return narrative ? `${roster}\n\n## Progress notes\n${narrative}` : roster;
+					} catch (e) {
+						return `${roster}\n\n## Progress notes\nSummary unavailable: ${errMessage(e)}`;
+					}
+				}),
+				...opts.compaction.onCompact ? { onCompact: opts.compaction.onCompact } : {},
+				...opts.compaction.preserveHead !== void 0 ? { preserveHead: opts.compaction.preserveHead } : {},
+				...opts.compaction.estimateTokens ? { estimateTokens: opts.compaction.estimateTokens } : {}
+			} : void 0;
+			await runBrainLoop({
+				chat,
+				tools: toolSpecs,
+				...compaction ? { compaction } : {},
+				execute: async (name, args) => {
+					if (opts.executeExtraTool) {
+						const worked = await runExtraTool(opts.executeExtraTool, name, args);
+						if (worked !== null && worked !== void 0) return worked;
+					}
+					const tool = byName.get(name);
+					return safeJson(tool ? await runTool(tool, args) : { error: `unknown tool: ${name}` });
+				},
+				initialMessages: [
+					{
+						role: "system",
+						content: system
+					},
+					{
+						role: "user",
+						content: stringifyTask(task)
+					},
+					...scope.resume ? [{
+						role: "user",
+						content: resumeBrief(scope.resume, opts.priorCoordination)
+					}] : hasPriorCoordination(opts.priorCoordination) ? [{
+						role: "user",
+						content: priorCoordinationBrief(opts.priorCoordination)
+					}] : []
+				],
+				maxTurns,
+				hooks: {
+					beforeTurn: async (_turn, messages) => {
+						await steerAcknowledger?.pass("turn");
+						acknowledger?.pass("turn");
+						const pending = inbox.drain();
+						if (pending.length > 0) messages.push({
+							role: "user",
+							content: inbox.fold(pending)
+						});
+					},
+					stopBefore: () => {
+						if (coord.isStopped() || scope.signal.aborted || poolStarved(scope, opts.perWorker) || deadlinePassed(scope, now)) return true;
+						if (!opts.stopRule || !tracker) return false;
+						const decision = progressStop(tracker, opts.stopRule, coord, scope, now, opts.stallAfterMs);
+						if (!decision.stop) return false;
+						if (progressStopReason === void 0) {
+							progressStopReason = decision.reason;
+							opts.onProgressStop?.(decision.reason);
+						}
+						return true;
+					}
+				}
+			});
+			await coord.drainResolved();
+			await steerAcknowledger?.pass("final");
+			acknowledger?.pass("final");
+			acknowledger?.finish();
+			const submitted = coord.submittedResult();
+			if (submitted) return submitted.result;
+			return runFinalizer(opts.finalizer ?? bestDelivered, {
+				settled: coord.settled(),
+				blobs: opts.blobs,
+				tree: runTree(scope),
+				budget: scope.budget
+			});
+		}
+	};
+}
+/**
+* The factual context a resumed driver starts from — everything the durable stores prove about
+* the prior process(es): committed settlements, per-key states (completed / lost / failed),
+* re-armed waits, carried-over questions/findings/continuation receipts, and spend already paid.
+* Injected as the brain's first user-context on a resumed run so it continues from unresolved work;
+* old continuation receipts are evidence and are never auto-delivered.
+*/
+function resumeBrief(resume, prior) {
+	const lines = [
+		"RESUME: this run continues a prior coordinator process. Its committed work is restored",
+		"below and already counts toward the deliverable — do NOT redo it. Continue from the",
+		"unresolved work only.",
+		"",
+		`Committed workers (${resume.settled.length}):`
+	];
+	if (resume.settled.length === 0) lines.push("- none");
+	for (const s of resume.settled) lines.push(s.kind === "done" ? `- ${s.handle.id} (${s.handle.label}): done, score=${s.verdict?.score ?? 0}, valid=${s.verdict?.valid ?? false}, outRef=${s.outRef}` : `- ${s.handle.id} (${s.handle.label}): down, reason=${s.reason}`);
+	const byState = (state) => [...resume.keys].filter(([, v]) => v.state === state);
+	const completed = byState("completed");
+	const lost = byState("in-doubt");
+	const failed = byState("down");
+	if (completed.length > 0) lines.push("", "COMPLETED keys — spawn_agent with the same key returns the finished result, spending nothing:", ...completed.map(([k, v]) => `- ${k} → ${v.id} (${v.label})`));
+	if (lost.length > 0) lines.push("", "Keys LOST in flight with the prior process — this is the unresolved work; spawn_agent with the same key starts a fresh attempt:", ...lost.map(([k, v]) => `- ${k} (prior attempt ${v.id}, ${v.label})`));
+	if (failed.length > 0) lines.push("", "Keys whose prior attempt FAILED (settled down) — spawn_agent with the same key retries:", ...failed.map(([k, v]) => `- ${k} (prior attempt ${v.id}, ${v.label})`));
+	if (resume.waits.length > 0) lines.push("", "Pending waits RE-ARMED on their original deadlines (they settle through await_event):", ...resume.waits.map((w) => `- ${w.label} (${w.spec.kind})`));
+	appendPriorCoordination(lines, prior);
+	const spent = resume.priorSpend;
+	lines.push("", "Budget the run ALREADY spent before this process (it counts toward the run total):", `- child work: tokens charged=${chargedTokens(spent.childWork.tokens)} (in=${spent.childWork.tokens.input} out=${spent.childWork.tokens.output}), usd=${spent.childWork.usd}, iterations=${spent.childWork.iterations}`, `- driver inference: tokens charged=${chargedTokens(spent.driverInference.tokens)} (in=${spent.driverInference.tokens.input} out=${spent.driverInference.tokens.output}), usd=${spent.driverInference.usd}`);
+	return lines.join("\n");
+}
+function hasPriorCoordination(prior) {
+	return prior !== void 0 && (prior.questions.length > 0 || prior.findings.length > 0 || prior.continuations.length > 0 || prior.deliveryEvidence.length > 0);
+}
+function priorCoordinationBrief(prior) {
+	const lines = [
+		"PRIOR COORDINATION EVIDENCE: this logical supervisor ran in an earlier process.",
+		"Use the evidence below as context. Never auto-deliver an old continuation; issue a new",
+		"authorized instruction only when current live state still warrants it."
+	];
+	appendPriorCoordination(lines, prior);
+	return lines.join("\n");
+}
+function appendPriorCoordination(lines, prior) {
+	const openQuestions = (prior?.questions ?? []).filter((q) => q.status === "open" || q.status === "escalated");
+	if (openQuestions.length > 0) lines.push("", "Questions carried over, still undecided (answer_question decides them; list_questions shows all):", ...openQuestions.map((q) => `- [${q.id}] from=${q.from}, urgency=${q.urgency}: ${q.question}`));
+	if ((prior?.findings.length ?? 0) > 0) lines.push("", "Analyst findings from the prior process:", ...(prior?.findings ?? []).map((f) => `- ${f.analyst} on ${f.fromWorker}: ${safeJson(f.findings)}`));
+	if ((prior?.continuations.length ?? 0) > 0) {
+		const attempts = new Set((prior?.deliveryEvidence ?? []).filter((event) => event.type === "delivery-attempt").map((event) => event.attempt.receiptId));
+		const outcomes = new Map((prior?.deliveryEvidence ?? []).filter((event) => event.type === "steer" || event.type === "answer").map((event) => [event.down.receiptId, event.down.outcome]));
+		lines.push("", "Authorized continuations committed by the prior process (evidence only; never replayed automatically):", ...(prior?.continuations ?? []).map((continuation) => {
+			const delivery = outcomes.get(continuation.receiptId) ?? (attempts.has(continuation.receiptId) ? "unknown-after-crash" : "not-attempted-before-crash");
+			return `- receipt=${continuation.receiptId}, ${continuation.kind} → ${continuation.toWorker}, instruction=${continuation.instructionDigest}, delivery=${delivery}`;
+		}));
+	}
+}
+/** Run a work tool. A throw is data to the driver (it can recover next turn), not a crash — fold
+*  the error back as a string result. null/undefined passes through (the caller treats it as "not
+*  handled" and falls to the coordination dispatch). */
+async function runExtraTool(execute, name, args) {
+	try {
+		return await execute(name, args);
+	} catch (e) {
+		return `error: ${e instanceof Error ? e.message : String(e)}`;
+	}
+}
+async function runTool(tool, args) {
+	try {
+		return await tool.handler(args);
+	} catch (e) {
+		return { error: e instanceof Error ? e.message : String(e) };
+	}
+}
+/** Keep-best finalize under the completion-oracle: return the highest-scoring DELIVERED child's
+*  output (settled `done` AND `valid` — its deliverable check passed). Returns undefined when no
+*  child delivered — an honest "the driver produced nothing", never a high-scoring result that
+*  ran without passing its check (Foreman's 0/18 lesson). `valid` is the single delivery signal,
+*  matching `defaultSelectWinner`'s valid-first rule; the oracle just doesn't fall back to an
+*  unchecked best-effort. The same argmax as the `bestDelivered` finalizer (`pickBestDelivered`);
+*  this direct form serves callers that hold a bare ledger + blob store. */
+async function finalizeBestDelivered(settled, blobs) {
+	const best = pickBestDelivered(settled.filter((w) => w.status === "done" && w.valid === true));
+	if (best === void 0) return void 0;
+	return best.outRef ? await blobs.get(best.outRef) : void 0;
+}
+function stringifyTask(task) {
+	return typeof task === "string" ? task : safeJson(task);
+}
+function safeJson(v) {
+	try {
+		return JSON.stringify(v) ?? String(v);
+	} catch {
+		return String(v);
+	}
+}
+function errMessage(e) {
+	return e instanceof Error ? e.message : String(e);
+}
+//#endregion
+export { coordinationVerbNames as C, createEventBus as D, questionEscalationTargets as E, defaultToolDetectors as O, canonicalFindingEvent as S, normalizeAnalyzeOnSettle as T, renderAnytimeTable as _, allOf as a, FileCoordinationLog as b, createProgressTracker as c, progressStop as d, sampleFromSettled as f, plateauLength as g, bestSoFar as h, finalizeBestDelivered as i, watchTrace as k, noProgressFor as l, areaUnderCurve as m, createSteerAcknowledger as n, allWorkersStalled as o, anytimeReport as p, driverAgent as r, anyOf as s, createCancelAcknowledger as t, plateau as u, createFileRunContext as v, createCoordinationTools as w, DEFAULT_AWAIT_EVENT_TIMEOUT_MS as x, createInMemoryRunContext as y };
+
+//# sourceMappingURL=coordination-driver-xO1tkxy-.js.map