@warlock.js/ai 4.1.1

package/esm/supervisor/execution.mjs

@@ -0,0 +1,1868 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { SupervisorFailedError } from "../errors/supervisor-failed-error.mjs";
+import { MaxIterationsError } from "../errors/max-iterations-error.mjs";
+import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
+import { SupervisorCancelledError } from "../errors/supervisor-cancelled-error.mjs";
+import "../errors/index.mjs";
+import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import "../utils/index.mjs";
+import { isAgentResult, isWorkflowResult } from "./entries.mjs";
+import { END } from "../contracts/end.type.mjs";
+import { createCancelledError } from "./cancellation.mjs";
+import { decide } from "./decide.mjs";
+import { persistSupervisorSnapshot } from "./snapshot.mjs";
+import { log } from "@warlock.js/logger";
+
+//#region ../../@warlock.js/ai/src/supervisor/execution.ts
+const DEFAULT_MAX_ITERATIONS = 10;
+const LOG_MODULE_BASE = "ai.supervisor";
+/**
+* Per-call driver that owns the full lifecycle of one supervisor run.
+*
+* **Role.** Short-lived state container and phase orchestrator —
+* mirrors `agent/Execution` and `workflow/runWorkflow`, one level up.
+*
+* **Responsibility.**
+* - Owns: the iteration loop, per-iteration dispatch (single or
+*   fan-out), evaluate scheduling, usage aggregation across router +
+*   every branch + evaluate, snapshot collection, event emission
+*   through all three tiers, KV-store checkpointing, final result
+*   assembly (state validation against the output schema → typed data).
+* - Does NOT own: how child agents produce responses (delegated via
+*   `agent.execute` / `workflow.execute`), the routing decision
+*   itself (delegated to `decide.ts`), snapshot persistence mechanics
+*   (delegated to `snapshot.ts`), the stream queue plumbing
+*   (delegated to `supervisor-stream.ts`).
+*
+* `execute()` never throws — every unexpected failure funnels into
+* `this.error` and is returned on `result.error` with an appropriate
+* `SupervisorFailedError` / `MaxIterationsError` / `SupervisorRoutingError`
+* / `SupervisorCancelledError`.
+*
+* @example
+* // Inside supervisor.execute() — never constructed by user code directly:
+* return new SupervisorExecution(params).run();
+*/
+var SupervisorExecution = class {
+	constructor(params) {
+		this.logger = log;
+		this.snapshots = [];
+		this.childReports = [];
+		this.usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		this.startPerf = performance.now();
+		this.iteration = 0;
+		this.terminatedBy = "error";
+		this.status = "failed";
+		this.lastDispatchIntents = [];
+		this.state = {};
+		this.currentArtifacts = {};
+		this.capturedIterationArtifacts = Object.freeze({});
+		this.classifierHalted = false;
+		this.config = params.config;
+		this.entries = params.entries;
+		this.signature = params.signature;
+		this.emitter = params.emitter;
+		this.input = params.input;
+		this.runId = params.runId;
+		this.options = params.options;
+		this.streamController = params.streamController;
+		this.resumeFrom = params.resumeFrom;
+		this.maxIterations = params.config.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+		this.logModule = `${LOG_MODULE_BASE}.${params.config.name}`;
+		this.context = Object.freeze({ ...params.options?.context ?? {} });
+		this.history = Object.freeze([...params.options?.history ?? params.config.history ?? []]);
+		if (typeof params.config.goal === "string") this.goal = params.config.goal;
+		else if (params.config.goal) this.goal = params.config.goal.resolve();
+		else this.goal = void 0;
+		if (params.resumeFrom) {
+			this.snapshots.push(...params.resumeFrom.snapshots);
+			this.iteration = params.resumeFrom.iteration + 1;
+			this.startedAtIso = params.resumeFrom.startedAt;
+			const lastSnapshot = params.resumeFrom.snapshots[params.resumeFrom.snapshots.length - 1];
+			this.state = { ...lastSnapshot?.state ?? params.config.state ?? {} };
+		} else {
+			this.startedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+			this.state = { ...params.config.state ?? {} };
+		}
+	}
+	/**
+	* Resolve the history slice forwarded to a child execution (router /
+	* dispatched agent / ack). Precedence:
+	*
+	*   1. Per-entry `history` callback — full override; whatever it
+	*      returns goes through (after defensive copy).
+	*   2. `SupervisorConfig.historyWindow.<role>` — last-N slice of the
+	*      caller-supplied history.
+	*   3. Default — full history for `router`/`agents`, empty for `ack`
+	*      (receptionists rarely benefit from scroll-back).
+	*
+	* Always returns a fresh `Message[]` (the agent layer
+	* mutates by reference internally, e.g. via `messages.push(...)`).
+	*/
+	resolveHistoryFor(role, routeContext, entrySlicer) {
+		if (entrySlicer) {
+			const sliced = entrySlicer(routeContext);
+			return sliced ? [...sliced] : [];
+		}
+		const window = this.config.historyWindow?.[role];
+		if (role === "ack") {
+			if (window === void 0 || window <= 0) return [];
+			return this.history.slice(-window);
+		}
+		if (window === void 0 || window < 0) return [...this.history];
+		if (window === 0) return [];
+		return this.history.slice(-window);
+	}
+	/**
+	* Apply only the global `historyWindow.agents` slice — used by the
+	* recursive `ctx.intents.X.execute()` re-entry path where no
+	* `RouteContext` is available to feed the per-entry slicer.
+	*/
+	applyAgentsWindow() {
+		const window = this.config.historyWindow?.agents;
+		if (window === void 0 || window < 0) return [...this.history];
+		if (window === 0) return [];
+		return this.history.slice(-window);
+	}
+	/**
+	* Entry point. Drives the iteration loop, finalizes the result, and
+	* emits terminal events. Returns the uniform
+	* `{ data, report, usage, error }` shape and closes the stream if
+	* one was attached. Never throws.
+	*/
+	async run() {
+		this.emit("supervisor.starting", {
+			supervisorName: this.config.name,
+			input: this.input
+		});
+		this.logger.info(this.logModule, "starting", "supervisor starting", {
+			runId: this.runId,
+			maxIterations: this.maxIterations
+		});
+		try {
+			await this.runIterationLoop();
+		} catch (thrown) {
+			this.error = toAIError(thrown);
+			this.status = this.error instanceof SupervisorCancelledError ? "cancelled" : "failed";
+			this.terminatedBy = this.error instanceof SupervisorCancelledError ? "cancelled" : "error";
+			if (this.error instanceof SupervisorCancelledError) this.cancelledAtIso = this.error.cancelledAt;
+			if (this.error instanceof MaxIterationsError) {
+				this.status = "max-iterations";
+				this.terminatedBy = "max-iterations";
+			}
+		}
+		const result = await this.finalize();
+		if (result.error) if (this.status === "cancelled") this.emit("supervisor.cancelled", {
+			cancelledAt: this.cancelledAtIso ?? (/* @__PURE__ */ new Date()).toISOString(),
+			reason: result.error.reason
+		});
+		else this.emit("supervisor.error", { error: result.error });
+		this.emit("supervisor.completed", { result });
+		this.streamController?.end(result);
+		this.logger.info(this.logModule, "completed", "supervisor completed", {
+			runId: this.runId,
+			status: this.status,
+			iterations: this.snapshots.length,
+			duration: performance.now() - this.startPerf
+		});
+		return result;
+	}
+	/**
+	* Drive the iteration loop until a terminal condition fires:
+	* `END` / `satisfied:true` / `maxIterations` / signal abort /
+	* routing error. Between-iteration cancellation is guaranteed —
+	* the signal is checked before every iteration starts.
+	*/
+	async runIterationLoop() {
+		while (this.iteration < this.maxIterations) {
+			this.throwIfCancelled();
+			if (!await this.runIteration()) return;
+			this.iteration += 1;
+		}
+		throw new MaxIterationsError(`supervisor "${this.config.name}" exceeded maxIterations=${this.maxIterations}`, { maxIterations: this.maxIterations });
+	}
+	/**
+	* Run one iteration end-to-end: decide → dispatch → evaluate →
+	* snapshot. Returns `true` when the loop should continue to the
+	* next iteration, `false` when this iteration terminated the run
+	* (success or satisfied-verdict). Failures throw — the loop's
+	* outer catch converts them into typed errors on the result.
+	*/
+	async runIteration() {
+		const iterationStartedAt = /* @__PURE__ */ new Date();
+		const iterationStart = performance.now();
+		const iterationUsage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		this.capturedIterationArtifacts = Object.freeze({});
+		this.emit("supervisor.iteration.starting", { iteration: this.iteration });
+		const ackPromise = this.iteration === 0 && !this.resumeFrom && this.config.ack ? this.runAck() : void 0;
+		if (this.iteration === 0 && !this.resumeFrom && this.config.classifier) {
+			await this.runClassifier();
+			if (this.classifierHalted) {
+				await this.settleAck(ackPromise, iterationUsage);
+				this.terminatedBy = "classifier";
+				this.status = "completed";
+				await this.recordTerminalDecisionSnapshot({
+					kind: "end",
+					source: "classifier",
+					raw: END,
+					durationMs: 0
+				}, iterationStartedAt, iterationStart, iterationUsage);
+				return false;
+			}
+		}
+		const decision = await this.decideDispatch();
+		this.aggregateUsage(iterationUsage, decision.usage);
+		if (decision.kind === "end") {
+			await this.settleAck(ackPromise, iterationUsage);
+			this.terminatedBy = decision.source === "route" ? "route" : "router";
+			this.status = "completed";
+			await this.recordTerminalDecisionSnapshot(decision, iterationStartedAt, iterationStart, iterationUsage);
+			return false;
+		}
+		const branchSnapshots = await this.dispatchBranches(decision);
+		for (const snapshot of branchSnapshots) this.aggregateUsage(iterationUsage, snapshot.usage);
+		await this.settleAck(ackPromise, iterationUsage);
+		this.mergeBranchesIntoState(decision.intents, branchSnapshots);
+		await this.mergeArtifactsIntoState();
+		this.lastDispatchIntents = decision.intents;
+		const evaluateVerdict = await this.runEvaluate(branchSnapshots);
+		if (evaluateVerdict !== void 0 && evaluateVerdict !== null) this.emit("supervisor.evaluate.verdict", {
+			iteration: this.iteration,
+			verdict: evaluateVerdict
+		});
+		const iterationEndedAt = /* @__PURE__ */ new Date();
+		const duration = performance.now() - iterationStart;
+		const snapshot = Object.freeze({
+			iteration: this.iteration,
+			result: indexByIntent(branchSnapshots),
+			decision: {
+				source: decision.source,
+				next: decision.raw,
+				reasoning: decision.reasoning,
+				durationMs: decision.durationMs
+			},
+			evaluateVerdict,
+			state: { ...this.state },
+			artifacts: this.capturedIterationArtifacts,
+			startedAt: iterationStartedAt.toISOString(),
+			endedAt: iterationEndedAt.toISOString(),
+			duration,
+			usage: iterationUsage
+		});
+		this.snapshots.push(snapshot);
+		this.emit("supervisor.iteration.completed", {
+			iteration: this.iteration,
+			snapshot
+		});
+		await this.checkpoint("running");
+		if (evaluateVerdict?.satisfied) {
+			this.terminatedBy = "evaluate";
+			this.status = "completed";
+			return false;
+		}
+		this.carriedFeedback = evaluateVerdict;
+		if (!(evaluateVerdict?.reassignTo !== void 0 && normalizeReassign(evaluateVerdict.reassignTo).length > 0)) {
+			const collected = this.collectIntentNext(decision.intents, branchSnapshots);
+			if (collected?.kind === "end") {
+				this.terminatedBy = "route";
+				this.status = "completed";
+				this.carriedNextDispatch = void 0;
+				return false;
+			}
+			if (collected?.kind === "dispatch") this.carriedNextDispatch = { intents: collected.intents };
+		}
+		if (this.iteration === 0 && this.config.classifier && !this.config.router && !this.config.route && !this.carriedNextDispatch) {
+			this.terminatedBy = "classifier";
+			this.status = "completed";
+			return false;
+		}
+		return true;
+	}
+	/**
+	* Resolve the dispatch decision for this iteration — defers to
+	* `decide.ts`. When `carriedFeedback.reassignTo` is set the
+	* supervisor overrides the router/route decision with an
+	* evaluator-forced dispatch (design §2 — "Evaluate can override
+	* router").
+	*/
+	async decideDispatch() {
+		if (this.config.router) this.emit("supervisor.router.deciding", { iteration: this.iteration });
+		const reassignTo = normalizeReassign(this.carriedFeedback?.reassignTo);
+		if (reassignTo.length > 0) {
+			this.carriedNextDispatch = void 0;
+			for (const intent of reassignTo) if (!this.entries.has(intent)) throw new SupervisorFailedError(`evaluate.reassignTo targeted unknown agent "${intent}"`, { context: { available: [...this.entries.keys()] } });
+			const decision = {
+				kind: "dispatch",
+				intents: reassignTo,
+				source: "route",
+				raw: reassignTo.length === 1 ? reassignTo[0] : reassignTo,
+				durationMs: 0
+			};
+			this.emit("supervisor.router.decided", {
+				iteration: this.iteration,
+				next: decision.raw,
+				reasoning: this.carriedFeedback?.feedback,
+				durationMs: 0
+			});
+			return decision;
+		}
+		if (this.carriedClassifierDispatch) {
+			const carried = this.carriedClassifierDispatch;
+			this.carriedClassifierDispatch = void 0;
+			const decision = {
+				kind: "dispatch",
+				intents: [carried.intent],
+				source: "classifier",
+				raw: carried.intent,
+				durationMs: 0
+			};
+			this.emit("supervisor.router.decided", {
+				iteration: this.iteration,
+				next: decision.raw,
+				reasoning: this.classifierSnapshot?.reasoning,
+				durationMs: 0
+			});
+			return decision;
+		}
+		if (this.carriedNextDispatch) {
+			const carried = this.carriedNextDispatch;
+			this.carriedNextDispatch = void 0;
+			const decision = {
+				kind: "dispatch",
+				intents: carried.intents,
+				source: "route",
+				raw: carried.intents.length === 1 ? carried.intents[0] : carried.intents,
+				durationMs: 0
+			};
+			this.emit("supervisor.router.decided", {
+				iteration: this.iteration,
+				next: decision.raw,
+				reasoning: void 0,
+				durationMs: 0
+			});
+			return decision;
+		}
+		const decision = await decide({
+			config: this.config,
+			entries: this.entries,
+			iteration: this.iteration,
+			maxIterations: this.maxIterations,
+			iterations: this.snapshots,
+			input: this.input,
+			state: this.state,
+			context: this.context,
+			history: this.history,
+			goal: this.goal,
+			evaluateFeedback: this.carriedFeedback,
+			classifier: this.classifierSnapshot,
+			signal: this.options?.signal,
+			useInitialAgent: this.iteration === 0 && !this.resumeFrom
+		});
+		if (decision.routerReport) this.childReports.push(decision.routerReport);
+		this.emit("supervisor.router.decided", {
+			iteration: this.iteration,
+			next: decision.raw,
+			reasoning: decision.reasoning,
+			durationMs: decision.durationMs
+		});
+		return decision;
+	}
+	/**
+	* Dispatch every intent named by the decision in parallel. Per-
+	* branch errors don't abort siblings — they're recorded on the
+	* branch snapshot and let evaluate (or default termination logic)
+	* decide the response.
+	*/
+	async dispatchBranches(decision) {
+		return await Promise.all(decision.intents.map((intent) => this.dispatchOne(intent)));
+	}
+	/**
+	* Execute a single branch — resolve the input, invoke the
+	* agent / workflow / callback, apply the per-intent `output`
+	* transformer, and produce an immutable `AgentBranchSnapshot`.
+	*/
+	async dispatchOne(intent) {
+		const entry = this.entries.get(intent);
+		if (entry.type === "callback") return this.dispatchCallback(entry);
+		const routeContext = {
+			iteration: this.iteration,
+			input: this.input,
+			state: this.state,
+			iterations: this.snapshots,
+			feedback: typeof this.carriedFeedback?.feedback === "string" ? this.carriedFeedback.feedback : void 0,
+			evaluateFeedback: this.carriedFeedback,
+			context: this.context,
+			history: this.history,
+			goal: this.goal,
+			classifier: this.classifierSnapshot
+		};
+		const resolvedInput = this.resolveBranchInput(entry, routeContext);
+		const dispatchCtxForPlaceholders = this.seedDispatchContext(intent, resolvedInput, new Set([intent]), []);
+		const placeholders = entry.placeholders ? entry.placeholders(dispatchCtxForPlaceholders) : void 0;
+		this.emit("supervisor.agent.starting", {
+			iteration: this.iteration,
+			intent,
+			input: resolvedInput
+		});
+		const startedAt = /* @__PURE__ */ new Date();
+		const startPerf = performance.now();
+		let rawResult;
+		let branchError;
+		let branchUsage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		try {
+			rawResult = await this.invokeUnit(entry, resolvedInput, placeholders, routeContext);
+			if (rawResult.error) branchError = rawResult.error;
+			branchUsage = rawResult.usage;
+			if (rawResult.report) this.childReports.push(rawResult.report);
+		} catch (thrown) {
+			branchError = toAIError(thrown);
+		}
+		const sliceOutcome = await this.applyOutputSchema(entry, rawResult);
+		const transformedOutput = sliceOutcome.value;
+		if (sliceOutcome.error && !branchError) branchError = sliceOutcome.error;
+		const endedAt = /* @__PURE__ */ new Date();
+		const duration = performance.now() - startPerf;
+		const snapshot = Object.freeze({
+			intent,
+			input: resolvedInput,
+			output: transformedOutput,
+			usage: branchUsage,
+			startedAt: startedAt.toISOString(),
+			endedAt: endedAt.toISOString(),
+			duration,
+			error: branchError
+		});
+		if (branchError) this.emit("supervisor.agent.failed", {
+			iteration: this.iteration,
+			intent,
+			error: branchError
+		});
+		else this.emit("supervisor.agent.completed", {
+			iteration: this.iteration,
+			intent,
+			output: transformedOutput,
+			usage: branchUsage,
+			duration
+		});
+		return snapshot;
+	}
+	/**
+	* Dispatch a callback intent as a top-level branch — produces an
+	* `AgentBranchSnapshot` and pushes the synthesized callback report
+	* onto the supervisor's recursive children. Delegates the actual
+	* callback invocation to {@link runCallback} so nested
+	* `ctx.intents.X.execute()` calls can reuse the same machinery.
+	*
+	* Each branch dispatch starts with a fresh per-branch call stack —
+	* sibling fan-out branches don't share cycle-detection state, so
+	* branch A and branch B both invoking the same intent isn't a
+	* cycle. The branch's own intent name is seeded onto the stack so
+	* a callback that re-enters itself via `ctx.intents.X.execute()` trips
+	* cycle detection on the first recursion.
+	*/
+	async dispatchCallback(entry) {
+		const intent = entry.intent;
+		const callStack = new Set([intent]);
+		const callbackInput = entry.input ? entry.input(this.seedDispatchContext(intent, this.input, callStack, [])) : this.input;
+		const inputForSnapshot = typeof callbackInput === "string" ? callbackInput : safeStringify(callbackInput);
+		this.emit("supervisor.agent.starting", {
+			iteration: this.iteration,
+			intent,
+			input: inputForSnapshot
+		});
+		const outcome = await this.runCallback(entry, callbackInput, callStack, this.childReports);
+		const snapshot = Object.freeze({
+			intent,
+			input: inputForSnapshot,
+			output: outcome.output,
+			usage: outcome.report.usage,
+			startedAt: outcome.report.startedAt,
+			endedAt: outcome.report.endedAt,
+			duration: outcome.report.duration,
+			error: outcome.error
+		});
+		if (outcome.error) this.emit("supervisor.agent.failed", {
+			iteration: this.iteration,
+			intent,
+			error: outcome.error
+		});
+		else this.emit("supervisor.agent.completed", {
+			iteration: this.iteration,
+			intent,
+			output: outcome.output,
+			usage: outcome.report.usage,
+			duration: outcome.report.duration
+		});
+		return snapshot;
+	}
+	/**
+	* Run a callback intent and produce its leaf report + final
+	* output. Used both for top-level branch dispatch (via
+	* {@link dispatchCallback}) and for nested `dispatch.byName`
+	* recursion. The synthesized report is appended to `reportSink`,
+	* which is either `this.childReports` (top-level) or the calling
+	* callback's own `children[]` (nested) — that's what gives the
+	* unified report tree its compositional shape.
+	*
+	* Usage on the report rolls up children's usage; the callback
+	* itself contributes zero (it's dev code, no token spend).
+	*/
+	async runCallback(entry, input, callStack, reportSink) {
+		const childReports = [];
+		const dispatchCtx = this.seedDispatchContext(entry.intent, input, callStack, childReports);
+		const startedAt = /* @__PURE__ */ new Date();
+		const startPerf = performance.now();
+		let rawOutput;
+		let error;
+		try {
+			rawOutput = await entry.callback(dispatchCtx);
+		} catch (thrown) {
+			error = thrown instanceof AIError ? thrown : new SupervisorFailedError(`callback intent "${entry.intent}" threw: ${thrown instanceof Error ? thrown.message : String(thrown)}`, { cause: thrown });
+		}
+		let transformedOutput = rawOutput;
+		if (!error && entry.output) {
+			const validation = await entry.output["~standard"].validate(rawOutput);
+			if (validation.issues) {
+				error = new SchemaValidationError(`intent "${entry.intent}" output failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`, { issues: validation.issues });
+				transformedOutput = void 0;
+			} else transformedOutput = validation.value;
+		}
+		const endedAt = /* @__PURE__ */ new Date();
+		const duration = performance.now() - startPerf;
+		const rolledUsage = aggregateChildUsage(childReports);
+		const report = {
+			runId: `${this.runId}.${entry.intent}`,
+			rootRunId: this.runId,
+			name: entry.intent,
+			type: "callback",
+			status: error ? "failed" : "completed",
+			startedAt: startedAt.toISOString(),
+			endedAt: endedAt.toISOString(),
+			duration,
+			usage: rolledUsage,
+			children: childReports
+		};
+		reportSink.push(report);
+		return {
+			output: transformedOutput,
+			error,
+			report
+		};
+	}
+	/**
+	* Build a {@link DispatchContext} with a typed `intents` map of
+	* `IntentRunner` closures, each closing over the supplied call
+	* stack and report sink. Cycle detection uses the call stack —
+	* re-entering an intent already on it throws
+	* `SupervisorFailedError` with code `SUPERVISOR_DISPATCH_CYCLE`
+	* and the offending chain in the message.
+	*
+	* Replaces the Phase-3.3 `ctx.dispatch.byName` plumbing with
+	* property-access on a typed map (Q5/Q6) — autocomplete, no typo
+	* crashes, `.execute()` matches every other primitive's verb.
+	*/
+	seedDispatchContext(intent, input, callStack, reportSink) {
+		const intentsMap = {};
+		for (const target of this.entries.keys()) intentsMap[target] = {
+			execute: (override) => this.runIntent(target, override === void 0 ? input : override, callStack, reportSink),
+			stream: (override) => this.streamIntent(target, override === void 0 ? input : override, callStack, reportSink, intent)
+		};
+		return {
+			iteration: this.iteration,
+			intent,
+			input,
+			state: this.state,
+			result: {},
+			iterations: this.snapshots,
+			signal: this.options?.signal ?? new AbortController().signal,
+			intents: intentsMap,
+			context: this.context,
+			history: this.history,
+			goal: this.goal,
+			run: (executable, runInput, runOptions) => this.runInline(executable, runInput, runOptions, callStack, reportSink),
+			stream: (executable, runInput, runOptions) => this.streamInline(executable, runInput, runOptions, callStack, reportSink, intent),
+			classifier: this.classifierSnapshot
+		};
+	}
+	/**
+	* Backing implementation for `ctx.intents.X.execute(input?)`.
+	* Looks up the named intent in the supervisor's registry, asserts
+	* the call wouldn't close a cycle, and runs the dispatchable
+	* through the same machinery a top-level branch would — except
+	* the resulting report nests under the calling callback's
+	* `children[]` rather than the supervisor's top-level child list,
+	* and only the final output is returned (no snapshot).
+	*/
+	async runIntent(target, callerInput, callStack, reportSink) {
+		if (callStack.has(target)) throw new SupervisorFailedError(`ctx.intents.${target}.execute: cycle detected (${[...callStack, target].join(" → ")})`, { context: { intent: target } }, "SUPERVISOR_DISPATCH_CYCLE");
+		const entry = this.entries.get(target);
+		if (!entry) throw new SupervisorFailedError(`ctx.intents.${target}.execute: unknown intent "${target}" — must be a key in the supervisor's \`intents\` map`, { context: { intent: target } });
+		callStack.add(target);
+		try {
+			if (entry.type === "callback") {
+				const { output, error } = await this.runCallback(entry, callerInput, callStack, reportSink);
+				if (error) throw error;
+				return output;
+			}
+			const inputString = typeof callerInput === "string" ? callerInput : safeStringify(callerInput);
+			if (entry.type === "agent") {
+				const reentryHistory = this.applyAgentsWindow();
+				const result = await entry.unit.execute(inputString, {
+					signal: this.options?.signal,
+					...reentryHistory.length > 0 ? { history: reentryHistory } : {}
+				});
+				if (result.report) reportSink.push(result.report);
+				if (result.error) throw result.error;
+				return result.data ?? result.text ?? void 0;
+			}
+			const result = await entry.unit.execute(inputString, { signal: this.options?.signal });
+			if (result.report) reportSink.push(result.report);
+			if (result.error) throw result.error;
+			return result.data;
+		} finally {
+			callStack.delete(target);
+		}
+	}
+	/**
+	* Backing implementation for `ctx.intents.X.stream(input?)` (Phase 6
+	* / decisions §36). Streaming sibling of {@link runIntent} — same
+	* cycle protection, same auto-merge of supervisor-level concerns,
+	* but routes through the unit's `.stream()` method when available
+	* and bubbles deltas as `supervisor.agent.streaming` under the
+	* **calling callback's** intent name (not the dispatched intent's).
+	*/
+	streamIntent(target, callerInput, callStack, reportSink, callerIntent) {
+		if (callStack.has(target)) throw new SupervisorFailedError(`ctx.intents.${target}.stream: cycle detected (${[...callStack, target].join(" → ")})`, { context: { intent: target } }, "SUPERVISOR_DISPATCH_CYCLE");
+		const entry = this.entries.get(target);
+		if (!entry) throw new SupervisorFailedError(`ctx.intents.${target}.stream: unknown intent "${target}" — must be a key in the supervisor's \`intents\` map`, { context: { intent: target } });
+		if (entry.type === "callback") throw new SupervisorFailedError(`ctx.intents.${target}.stream: callback intents are not streamable — use \`.execute(input?)\` instead`, { context: { intent: target } });
+		callStack.add(target);
+		const inputString = typeof callerInput === "string" ? callerInput : safeStringify(callerInput);
+		return this.streamSupervisedExecutable(entry.unit, inputString, void 0, callerIntent, reportSink, () => callStack.delete(target));
+	}
+	/**
+	* Backing implementation for `ctx.run(executable, input, options?)`
+	* (Phase 6 / decisions §36). Runs an inline / un-registered
+	* executable under supervision: auto-merges `signal`, `toolCtx`,
+	* `history` defaults; nests the resulting report under the
+	* calling callback's `children[]`. Per-call options REPLACE auto-
+	* defaults — standard Warlock convention.
+	*
+	* Cycle protection by executable `name` matches the registered-
+	* intent path so a callback that recurses on the same agent trips
+	* the same error, regardless of whether the agent was looked up
+	* via `ctx.intents.X.execute()` or passed inline.
+	*/
+	async runInline(executable, input, options, callStack, reportSink) {
+		const name = executable.name;
+		if (callStack.has(name)) throw new SupervisorFailedError(`ctx.run("${name}"): cycle detected (${[...callStack, name].join(" → ")})`, { context: { intent: name } }, "SUPERVISOR_DISPATCH_CYCLE");
+		callStack.add(name);
+		try {
+			const merged = this.mergeInlineOptions(options);
+			const inputForExecutable = this.coerceInlineInput(executable, input);
+			const result = await executable.execute(inputForExecutable, merged);
+			if (result.report) reportSink.push(result.report);
+			return result;
+		} finally {
+			callStack.delete(name);
+		}
+	}
+	/**
+	* Backing implementation for `ctx.stream(executable, input, options?)`
+	* (Phase 6 / decisions §36). Streaming sibling of {@link runInline}.
+	* Routes through the executable's native `.stream()` method,
+	* subscribes to delta events, and bubbles them as
+	* `supervisor.agent.streaming` under the calling callback's intent
+	* name. The returned `StreamContract` is the executable's own —
+	* iteration and `.result` work identically.
+	*
+	* Cycle protection on entry mirrors {@link runInline}; release runs
+	* after `.result` settles so a same-callback recursion is caught
+	* regardless of which path closed the cycle.
+	*/
+	streamInline(executable, input, options, callStack, reportSink, callerIntent) {
+		const name = executable.name;
+		if (callStack.has(name)) throw new SupervisorFailedError(`ctx.stream("${name}"): cycle detected (${[...callStack, name].join(" → ")})`, { context: { intent: name } }, "SUPERVISOR_DISPATCH_CYCLE");
+		callStack.add(name);
+		return this.streamSupervisedExecutable(executable, this.coerceInlineInput(executable, input), options, callerIntent, reportSink, () => callStack.delete(name));
+	}
+	/**
+	* Shared wiring for both `ctx.intents.X.stream()` and
+	* `ctx.stream(...)`. Subscribes to the executable's stream, re-
+	* emits deltas as `supervisor.agent.streaming` under the calling
+	* callback's intent name, and pushes the inner report onto the
+	* reportSink once `.result` settles. The returned StreamContract
+	* is the executable's own — the framework attaches handlers
+	* transparently via `.on(...)`.
+	*/
+	streamSupervisedExecutable(executable, input, options, callerIntent, reportSink, release) {
+		const merged = this.mergeInlineOptions(options);
+		const stream = executable.stream(input, merged);
+		stream.on({
+			"agent.trip.streaming": ({ delta }) => {
+				this.emit("supervisor.agent.streaming", {
+					iteration: this.iteration,
+					intent: callerIntent,
+					delta
+				});
+			},
+			"supervisor.agent.streaming": ({ delta }) => {
+				this.emit("supervisor.agent.streaming", {
+					iteration: this.iteration,
+					intent: callerIntent,
+					delta
+				});
+			}
+		});
+		stream.result.then((result) => {
+			if (result?.report) reportSink.push(result.report);
+			release();
+		}, () => release());
+		return stream;
+	}
+	/**
+	* Build the options object passed into an inline `.execute()` /
+	* `.stream()` call. Auto-merges supervisor-level defaults
+	* (`signal`, `toolCtx`, `history` window) under the caller's
+	* options. Per-call values REPLACE the auto-defaults — when the
+	* dev passes `signal: undefined` they explicitly opt out.
+	*/
+	mergeInlineOptions(options) {
+		const supplied = options ?? {};
+		const merged = { ...supplied };
+		if (!("signal" in supplied)) merged.signal = this.options?.signal;
+		if (!("toolCtx" in supplied)) merged.toolCtx = {
+			artifacts: this.currentArtifacts,
+			signal: this.options?.signal
+		};
+		if (!("history" in supplied)) {
+			const window = this.applyAgentsWindow();
+			if (window.length > 0) merged.history = window;
+		}
+		return merged;
+	}
+	/**
+	* Coerce an arbitrary inline input into the shape the underlying
+	* executable expects. Agents take `string`; workflows + supervisors
+	* take whatever they declared. We safe-stringify objects only when
+	* passing to an agent — workflow / supervisor calls hand the value
+	* through unchanged so structured inputs work.
+	*/
+	coerceInlineInput(executable, input) {
+		if (!("signature" in executable) && typeof executable.execute === "function" && !this.isSupervisor(executable) && typeof input !== "string") return safeStringify(input);
+		return input;
+	}
+	/**
+	* Heuristic detection of `SupervisorContract` — the contract carries
+	* a `signature` getter same as workflows, but supervisors expose
+	* `resume()` while workflows expose `resume(runId, options)` too.
+	* Cleanest distinguisher in the public surface: supervisors carry
+	* the `asTool` method name `as` … unfortunately so do workflows.
+	* Use the `streamableType` brand if we add one in v2; for now lean
+	* on a duck-typed check that's good enough for the ctx.run path
+	* (incorrect routing for workflows would still produce a runnable
+	* call — workflow.execute accepts the same args either way).
+	*/
+	isSupervisor(executable) {
+		return typeof executable.resume === "function" && typeof executable.signature === "string" && typeof executable.stream === "function";
+	}
+	/**
+	* Invoke the underlying dispatchable unit. Agents and workflows
+	* both satisfy `ExecutableContract<string, …>` so the call shape
+	* is uniform; the `type` discriminator picks which options get
+	* threaded through (e.g. per-call stream event bubbling for
+	* agents, which we wire inline so child agent tokens surface as
+	* `supervisor.agent.streaming`).
+	*/
+	async invokeUnit(entry, input, placeholders, routeContext) {
+		const isStreaming = this.streamController !== void 0;
+		if (entry.type === "agent") {
+			const agent = entry.unit;
+			const handlers = { "agent.trip.streaming": ({ delta }) => {
+				this.emit("supervisor.agent.streaming", {
+					iteration: this.iteration,
+					intent: entry.intent,
+					delta
+				});
+			} };
+			const isStreamMode = entry.mode === "stream";
+			const resolvedHistory = this.resolveHistoryFor("agents", routeContext, entry.history);
+			const agentOptions = {
+				signal: this.options?.signal,
+				on: handlers,
+				...placeholders ? { placeholders } : {},
+				...entry.output && !isStreamMode ? { output: entry.output } : {},
+				...resolvedHistory.length > 0 ? { history: resolvedHistory } : {},
+				toolCtx: {
+					artifacts: this.currentArtifacts,
+					signal: this.options?.signal
+				}
+			};
+			if (isStreamMode || isStreaming) return agent.stream(input, agentOptions).result;
+			return agent.execute(input, agentOptions);
+		}
+		return entry.unit.execute(input, {
+			signal: this.options?.signal,
+			on: { "workflow.step.streaming": ({ delta }) => {
+				this.emit("supervisor.agent.streaming", {
+					iteration: this.iteration,
+					intent: entry.intent,
+					delta
+				});
+			} }
+		});
+	}
+	/**
+	* Build the input string passed to a branch's child execution.
+	* Default: pass the supervisor's original `ctx.input` through
+	* unchanged. The per-intent `entry.input` override is the escape
+	* hatch for the rare case where the agent's user message itself
+	* must vary per intent.
+	*
+	* Q17 lock: dropped `composeAgentInput` + `defaultComposeAgentInput`.
+	* Their three jobs (carry original / prior outputs / feedback) all
+	* have cleaner homes in the new model — original is the input
+	* itself, prior outputs are state (Stage 4b), feedback is a
+	* router-only signal (Q18).
+	*/
+	resolveBranchInput(entry, ctx) {
+		const override = entry.input?.(ctx);
+		if (typeof override === "string") return override;
+		return typeof ctx.input === "string" ? ctx.input : safeStringify(ctx.input);
+	}
+	/**
+	* Strip-merge the agent/workflow's raw output against the per-intent
+	* `output` schema (Q11/Q13). Returns the validated slice that:
+	*
+	*   1. Lands on `IterationSnapshot.result[intent].output` (so
+	*      consumers see the same shape that hit state).
+	*   2. Shallow-merges into `this.state` (handled by the caller).
+	*
+	* When `entry.output` is omitted the agent's full `data` (or `text`
+	* fallback for unstructured agents) flows through unvalidated — but
+	* is NOT auto-merged into state. State contribution is opt-in via
+	* declaring the slice schema.
+	*
+	* Validation failure surfaces as a per-branch error on the
+	* snapshot; sibling branches still run.
+	*/
+	async applyOutputSchema(entry, raw) {
+		if (!raw) return { value: void 0 };
+		const sourceValue = isAgentResult(raw) ? raw.data ?? raw.text ?? void 0 : isWorkflowResult(raw) ? raw.data : void 0;
+		if (entry.type === "agent" && entry.mode === "stream") {
+			const text = typeof sourceValue === "string" ? sourceValue : "";
+			return { value: { [entry.streamTo]: text } };
+		}
+		if (!entry.output) return { value: sourceValue };
+		const validation = await entry.output["~standard"].validate(sourceValue);
+		if (validation.issues) return {
+			value: void 0,
+			error: new SchemaValidationError(`intent "${entry.intent}" output failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`, { issues: validation.issues })
+		};
+		return { value: validation.value };
+	}
+	/**
+	* Fire the receptionist (`ack`) — runs in parallel with phase A on
+	* iteration 0 only. Accepts three shapes:
+	*
+	* - `AckEntry` — `{ agent, placeholders?, input?, output? }`. LLM
+	*   form. Streams tokens via `supervisor.ack.streaming`; report
+	*   node pushes onto `childReports[]`.
+	* - `AckRunEntry` — `{ run, output? }`. Pure-code callback. Settles
+	*   without an LLM call. No streaming events; just `.completed`.
+	* - `AckCallback` — bare `(ctx) => slice` shorthand for the
+	*   pure-code form when no schema is declared.
+	*
+	* Failures are recorded but never abort the run — the receptionist
+	* tripping doesn't stop the specialist from doing the actual job.
+	* The returned outcome is what `mergeAckIntoState` consumes.
+	*/
+	async runAck() {
+		const ack = this.config.ack;
+		if (!ack) return void 0;
+		const routeContext = {
+			iteration: this.iteration,
+			input: this.input,
+			state: this.state,
+			iterations: this.snapshots,
+			feedback: typeof this.carriedFeedback?.feedback === "string" ? this.carriedFeedback.feedback : void 0,
+			evaluateFeedback: this.carriedFeedback,
+			context: this.context,
+			history: this.history,
+			goal: this.goal,
+			classifier: this.classifierSnapshot
+		};
+		const startedAt = /* @__PURE__ */ new Date();
+		const startPerf = performance.now();
+		if (typeof ack === "function") return this.runAckCallback(ack, void 0, routeContext, startedAt, startPerf);
+		if ("run" in ack && typeof ack.run === "function") {
+			const runEntry = ack;
+			return this.runAckCallback(runEntry.run, runEntry.output, routeContext, startedAt, startPerf);
+		}
+		return this.runAckAgent(ack, routeContext, startedAt, startPerf);
+	}
+	/**
+	* Pure-code receptionist path — invokes the callback, strip-validates
+	* the return value (when an `output` schema is declared), records the
+	* snapshot, emits `supervisor.ack.completed`, returns the outcome.
+	* No streaming events fire (callbacks settle synchronously from the
+	* supervisor's POV).
+	*/
+	async runAckCallback(run, output, routeContext, startedAt, startPerf) {
+		const usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		let validatedOutput;
+		let ackError;
+		try {
+			const raw = await run(routeContext);
+			if (output) {
+				const validation = await output["~standard"].validate(raw);
+				if (validation.issues) ackError = new SchemaValidationError(`ack output failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`, { issues: validation.issues });
+				else validatedOutput = validation.value;
+			} else validatedOutput = raw;
+		} catch (thrown) {
+			ackError = toAIError(thrown);
+		}
+		const endedAt = /* @__PURE__ */ new Date();
+		const duration = performance.now() - startPerf;
+		this.ackSnapshot = Object.freeze({
+			input: typeof this.input === "string" ? this.input : safeStringify(this.input),
+			output: validatedOutput,
+			usage,
+			startedAt: startedAt.toISOString(),
+			endedAt: endedAt.toISOString(),
+			duration,
+			error: ackError
+		});
+		this.emit("supervisor.ack.completed", {
+			output: validatedOutput,
+			usage,
+			duration,
+			error: ackError
+		});
+		return {
+			output: validatedOutput,
+			usage,
+			duration,
+			error: ackError
+		};
+	}
+	/**
+	* Agent-driven receptionist path — invokes the agent, streams tokens
+	* via `supervisor.ack.streaming`, captures the report node, strip-
+	* validates against `output` (when declared), records the snapshot,
+	* emits `supervisor.ack.completed`.
+	*/
+	async runAckAgent(ack, routeContext, startedAt, startPerf) {
+		const placeholders = ack.placeholders?.(routeContext);
+		const inputForAck = ack.input?.(routeContext) ?? (typeof this.input === "string" ? this.input : safeStringify(this.input));
+		const isStreaming = this.streamController !== void 0;
+		const handlers = { "agent.trip.streaming": ({ delta }) => {
+			this.emit("supervisor.ack.streaming", { delta });
+		} };
+		const resolvedHistory = this.resolveHistoryFor("ack", routeContext, ack.history);
+		const agentOptions = {
+			signal: this.options?.signal,
+			on: handlers,
+			...placeholders ? { placeholders } : {},
+			...ack.output ? { output: ack.output } : {},
+			...resolvedHistory.length > 0 ? { history: resolvedHistory } : {}
+		};
+		let rawResult;
+		let ackError;
+		let usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		try {
+			if (isStreaming) rawResult = await ack.agent.stream(inputForAck, agentOptions).result;
+			else rawResult = await ack.agent.execute(inputForAck, agentOptions);
+			if (rawResult.error) ackError = rawResult.error;
+			usage = rawResult.usage ?? usage;
+			if (rawResult.report) this.childReports.push(rawResult.report);
+		} catch (thrown) {
+			ackError = toAIError(thrown);
+		}
+		const endedAt = /* @__PURE__ */ new Date();
+		const duration = performance.now() - startPerf;
+		let validatedOutput;
+		if (rawResult && !ackError && ack.output) {
+			const sourceValue = rawResult.data ?? rawResult.text ?? void 0;
+			const validation = await ack.output["~standard"].validate(sourceValue);
+			if (validation.issues) ackError = new SchemaValidationError(`ack output failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`, { issues: validation.issues });
+			else validatedOutput = validation.value;
+		} else if (rawResult && !ackError) validatedOutput = rawResult.data ?? rawResult.text ?? void 0;
+		this.ackSnapshot = Object.freeze({
+			input: inputForAck,
+			output: validatedOutput,
+			usage,
+			startedAt: startedAt.toISOString(),
+			endedAt: endedAt.toISOString(),
+			duration,
+			error: ackError
+		});
+		this.emit("supervisor.ack.completed", {
+			output: validatedOutput,
+			usage,
+			duration,
+			error: ackError
+		});
+		return {
+			output: validatedOutput,
+			usage,
+			duration,
+			error: ackError
+		};
+	}
+	/**
+	* Probe the ack promise non-blockingly. Yields one macrotask cycle
+	* (`setImmediate`) so an already-resolved ack wins via microtask
+	* priority; if the probe returns first, the slice is abandoned —
+	* warning logged, error captured on `report.ack`, run completes
+	* regardless. Specialists own the actual answer; the receptionist
+	* was just a reassuring preview.
+	*/
+	async settleAck(ackPromise, iterationUsage) {
+		if (!ackPromise) return;
+		const NOT_READY = Symbol("ack-not-ready");
+		const probe = await Promise.race([ackPromise, new Promise((resolve) => setTimeout(() => resolve(NOT_READY), 0))]);
+		if (probe === NOT_READY) {
+			this.logger.warn(this.logModule, "ack.abandoned", "ack receptionist did not settle before iteration completed; slice dropped");
+			const abandonedAt = /* @__PURE__ */ new Date();
+			this.ackSnapshot = Object.freeze({
+				input: typeof this.input === "string" ? this.input : safeStringify(this.input),
+				output: void 0,
+				usage: {
+					input: 0,
+					output: 0,
+					total: 0
+				},
+				startedAt: abandonedAt.toISOString(),
+				endedAt: abandonedAt.toISOString(),
+				duration: 0,
+				error: new SupervisorFailedError("ack receptionist did not settle before iteration completed", { context: { ackAbandoned: true } })
+			});
+			return;
+		}
+		const ackOutcome = probe;
+		if (ackOutcome) {
+			this.aggregateUsage(iterationUsage, ackOutcome.usage);
+			this.mergeAckIntoState(ackOutcome);
+		}
+	}
+	/**
+	* Merge the receptionist's strip-validated slice into state. Called
+	* from `settleAck` BEFORE branch merges so specialists override the
+	* receptionist on key collision — the receptionist hedges, the
+	* specialist commits.
+	*/
+	mergeAckIntoState(ackOutcome) {
+		if (ackOutcome.error || !ackOutcome.output) return;
+		if (typeof ackOutcome.output !== "object" || ackOutcome.output === null) return;
+		const slice = ackOutcome.output;
+		for (const [key, value] of Object.entries(slice)) this.state[key] = value;
+	}
+	/**
+	* Run the iter-0 classifier prelude (Phase 7 / decisions §37).
+	* Resolves the configured classifier (agent / callback / entry
+	* form), invokes it, runs the optional `refine` post-process hook,
+	* and either:
+	*
+	*   - sets `carriedClassifierDispatch` so the upcoming
+	*     `decideDispatch` short-circuits to the chosen intent, OR
+	*   - sets `classifierHalted = true` so `runIteration` terminates
+	*     before any dispatch (refine returned `END`).
+	*
+	* Captures the full forensic record on `classifierSnapshot` —
+	* surfaced on `SupervisorReport.classifier` and threaded into
+	* `ctx.classifier` on every downstream context.
+	*
+	* Errors in the classifier OR the refine hook abort the run with
+	* a `SupervisorFailedError` so issues surface loudly instead of
+	* silently falling through to router/route.
+	*/
+	async runClassifier() {
+		const startedAt = /* @__PURE__ */ new Date();
+		const startPerf = performance.now();
+		const startedAtIso = startedAt.toISOString();
+		this.emit("supervisor.classifier.starting", { iteration: 0 });
+		const ctx = this.buildClassifierContext();
+		const config = this.config.classifier;
+		let raw;
+		let usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		let executionError;
+		try {
+			const outcome = await this.invokeClassifier(config, ctx);
+			raw = outcome.output;
+			usage = outcome.usage;
+		} catch (thrown) {
+			executionError = toAIError(thrown);
+		}
+		if (executionError || !raw) {
+			const error = executionError ?? new SupervisorFailedError(`ai.supervisor("${this.config.name}"): classifier produced no output`, { context: { iteration: 0 } });
+			this.classifierSnapshot = {
+				intent: void 0,
+				refined: false,
+				halted: true,
+				raw: raw ?? { intent: "" },
+				startedAt: startedAtIso,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				duration: performance.now() - startPerf,
+				usage,
+				error
+			};
+			this.aggregateUsage(this.usage, usage);
+			this.emit("supervisor.classifier.failed", { error });
+			throw error;
+		}
+		if (!this.entries.has(raw.intent)) {
+			const error = new SupervisorFailedError(`ai.supervisor("${this.config.name}"): classifier picked unknown intent "${raw.intent}" — must be a key in \`intents\``, { context: {
+				iteration: 0,
+				available: [...this.entries.keys()]
+			} }, "SUPERVISOR_INVALID_ROUTE");
+			this.classifierSnapshot = {
+				intent: void 0,
+				refined: false,
+				halted: true,
+				raw,
+				startedAt: startedAtIso,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				duration: performance.now() - startPerf,
+				usage,
+				error
+			};
+			this.aggregateUsage(this.usage, usage);
+			this.emit("supervisor.classifier.failed", { error });
+			throw error;
+		}
+		const refineHook = this.resolveRefineHook(config);
+		let final = raw;
+		let refined = false;
+		let halted = false;
+		if (refineHook) {
+			let refineResult;
+			try {
+				refineResult = await refineHook(this.buildClassifierRefineContext(ctx, raw));
+			} catch (thrown) {
+				const error = toAIError(thrown);
+				this.classifierSnapshot = {
+					intent: void 0,
+					refined: false,
+					halted: true,
+					raw,
+					startedAt: startedAtIso,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					duration: performance.now() - startPerf,
+					usage,
+					error
+				};
+				this.aggregateUsage(this.usage, usage);
+				this.emit("supervisor.classifier.failed", { error });
+				throw error;
+			}
+			const interpretation = this.interpretRefineResult(refineResult, raw);
+			if (interpretation.error) {
+				this.classifierSnapshot = {
+					intent: void 0,
+					refined: true,
+					halted: true,
+					raw,
+					startedAt: startedAtIso,
+					endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+					duration: performance.now() - startPerf,
+					usage,
+					error: interpretation.error
+				};
+				this.aggregateUsage(this.usage, usage);
+				this.emit("supervisor.classifier.failed", { error: interpretation.error });
+				throw interpretation.error;
+			}
+			refined = interpretation.refined;
+			halted = interpretation.halted;
+			final = interpretation.final ?? raw;
+			if (interpretation.sliceToMerge) for (const [key, value] of Object.entries(interpretation.sliceToMerge)) this.state[key] = value;
+		}
+		for (const [key, value] of Object.entries(final)) this.state[key] = value;
+		this.classifierSnapshot = {
+			intent: halted ? void 0 : final.intent,
+			reasoning: final.reasoning,
+			confidence: final.confidence,
+			refined,
+			halted,
+			raw,
+			startedAt: startedAtIso,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			duration: performance.now() - startPerf,
+			usage
+		};
+		this.aggregateUsage(this.usage, usage);
+		this.emit("supervisor.classifier.completed", {
+			output: {
+				intent: this.classifierSnapshot.intent,
+				reasoning: this.classifierSnapshot.reasoning,
+				confidence: this.classifierSnapshot.confidence
+			},
+			intent: this.classifierSnapshot.intent,
+			refined,
+			halted,
+			duration: this.classifierSnapshot.duration,
+			usage
+		});
+		if (halted) {
+			this.classifierHalted = true;
+			return;
+		}
+		if (!this.entries.has(final.intent)) {
+			const error = new SupervisorFailedError(`ai.supervisor("${this.config.name}"): classifier.refine returned unknown intent "${final.intent}" — must be a key in \`intents\``, { context: {
+				iteration: 0,
+				available: [...this.entries.keys()]
+			} }, "SUPERVISOR_INVALID_ROUTE");
+			this.classifierSnapshot = {
+				...this.classifierSnapshot,
+				halted: true,
+				error
+			};
+			this.classifierHalted = true;
+			this.emit("supervisor.classifier.failed", { error });
+			throw error;
+		}
+		this.carriedClassifierDispatch = { intent: final.intent };
+	}
+	/**
+	* Resolve the configured classifier into a callable that returns
+	* `{ output, usage }`. Handles the four accepted shapes — bare
+	* agent / bare callback / agent-entry / run-entry. Pure shape
+	* normalization; no side effects.
+	*/
+	async invokeClassifier(config, ctx) {
+		if (typeof config === "function") return {
+			output: await config(ctx),
+			usage: {
+				input: 0,
+				output: 0,
+				total: 0
+			}
+		};
+		if (typeof config.run === "function") {
+			const runFn = config.run;
+			return {
+				output: await runFn(ctx),
+				usage: {
+					input: 0,
+					output: 0,
+					total: 0
+				}
+			};
+		}
+		if (typeof config.agent?.execute === "function") {
+			const entry = config;
+			return this.invokeClassifierAgent(entry.agent, ctx, entry.placeholders, entry.input, entry.history);
+		}
+		if (typeof config.execute === "function") return this.invokeClassifierAgent(config, ctx);
+		throw new SupervisorFailedError(`ai.supervisor("${this.config.name}"): \`classifier\` is not an agent, callback, or entry object`, { context: { authoring: true } });
+	}
+	/**
+	* Invoke a classifier agent with the supervisor's standard wiring
+	* — placeholders, input override, history slicing, signal,
+	* streaming bubble. Output schema validation belongs to the agent
+	* itself; we just pull the typed `data` (or fall back to parsing
+	* `text`) and assert the locked `intent` field.
+	*/
+	async invokeClassifierAgent(agent, ctx, placeholders, inputResolver, historySlicer) {
+		const inputForAgent = inputResolver?.(ctx) ?? (typeof ctx.input === "string" ? ctx.input : safeStringify(ctx.input));
+		const history = historySlicer ? [...historySlicer(ctx)] : this.applyAgentsWindow();
+		const isStreaming = this.streamController !== void 0;
+		const agentOptions = {
+			signal: this.options?.signal,
+			on: { "agent.trip.streaming": ({ delta }) => {
+				this.emit("supervisor.classifier.streaming", { delta });
+			} },
+			...placeholders ? { placeholders: placeholders(ctx) } : {},
+			...history.length > 0 ? { history } : {}
+		};
+		let result;
+		if (isStreaming) result = await agent.stream(inputForAgent, agentOptions).result;
+		else result = await agent.execute(inputForAgent, agentOptions);
+		if (result.error) throw result.error;
+		if (result.report) this.childReports.push(result.report);
+		const data = result.data ?? result.text ?? void 0;
+		return {
+			output: this.coerceClassifierOutput(data),
+			usage: result.usage
+		};
+	}
+	/**
+	* Coerce an agent's output into the locked classifier shape.
+	* Accepts a typed object with `intent` (the canonical case) or a
+	* plain string (interpreted as the intent name with no reasoning).
+	* Throws `SupervisorFailedError` if neither shape matches.
+	*/
+	coerceClassifierOutput(data) {
+		if (typeof data === "string") return { intent: data };
+		if (data && typeof data === "object" && typeof data.intent === "string") {
+			const record = data;
+			return {
+				intent: record.intent,
+				reasoning: typeof record.reasoning === "string" ? record.reasoning : void 0,
+				confidence: typeof record.confidence === "number" ? record.confidence : void 0
+			};
+		}
+		throw new SupervisorFailedError(`ai.supervisor("${this.config.name}"): classifier output missing required \`intent\` field — got ${JSON.stringify(data)?.slice(0, 200)}`, { context: { iteration: 0 } });
+	}
+	/**
+	* Build the read-only context passed to a classifier callback / agent
+	* resolvers. No dispatch helpers — registered intents haven't fired
+	* yet; pre-running them from the classifier would be confusing.
+	*/
+	buildClassifierContext() {
+		return {
+			iteration: 0,
+			input: this.input,
+			state: this.state,
+			context: this.context,
+			history: this.history,
+			signal: this.options?.signal ?? new AbortController().signal,
+			goal: this.goal
+		};
+	}
+	/**
+	* Build the refine context — extends ClassifierContext with the
+	* classifier's just-resolved output plus `run` / `stream` so the
+	* refine hook can spin up secondary classifiers / validators
+	* inline (Phase 6 features).
+	*/
+	buildClassifierRefineContext(base, raw) {
+		const callStack = /* @__PURE__ */ new Set();
+		const reportSink = this.childReports;
+		return {
+			...base,
+			result: { data: raw },
+			run: (executable, runInput, runOptions) => this.runInline(executable, runInput, runOptions, callStack, reportSink),
+			stream: (executable, runInput, runOptions) => this.streamInline(executable, runInput, runOptions, callStack, reportSink, "classifier")
+		};
+	}
+	/**
+	* Pull the optional `refine` hook off whichever classifier-config
+	* shape was supplied. Bare-callback and bare-agent forms have no
+	* refine; only entry forms do.
+	*/
+	resolveRefineHook(config) {
+		if (typeof config === "function") return;
+		const refine = config.refine;
+		return typeof refine === "function" ? refine : void 0;
+	}
+	/**
+	* Interpret a refine return value into actionable bits — final
+	* classifier output to dispatch, slice-to-merge, halted/refined
+	* flags, or an error. See {@link ClassifierRefineResult} for the
+	* accepted shapes.
+	*/
+	interpretRefineResult(refineResult, raw) {
+		if (refineResult === void 0) return {
+			final: raw,
+			refined: false,
+			halted: false
+		};
+		if (refineResult === "__warlock:end__") return {
+			refined: true,
+			halted: true
+		};
+		if (typeof refineResult !== "object" || refineResult === null) return {
+			refined: false,
+			halted: true,
+			error: new SupervisorFailedError(`ai.supervisor("${this.config.name}"): classifier.refine returned an unsupported value — expected undefined, END, or an object`, { context: { iteration: 0 } })
+		};
+		const record = refineResult;
+		const intentField = record.intent;
+		const halted = intentField === END;
+		const intentOverride = typeof intentField === "string" ? intentField : void 0;
+		const slice = {};
+		for (const [key, value] of Object.entries(record)) {
+			if (key === "intent") continue;
+			slice[key] = value;
+		}
+		const final = {
+			...raw,
+			...intentOverride ? { intent: intentOverride } : {}
+		};
+		return {
+			final: halted ? void 0 : final,
+			sliceToMerge: Object.keys(slice).length > 0 ? slice : void 0,
+			refined: true,
+			halted
+		};
+	}
+	/**
+	* Run the `evaluate` callback (when configured) after the
+	* iteration's branches settle and outputs have merged into state.
+	* Errors in the callback surface as `SupervisorFailedError` so a
+	* buggy evaluate doesn't silently swallow the whole run.
+	*
+	* Phase 3.4 (Stage 4b) — `EvaluateContext.state` carries the
+	* post-merge accumulator so verdicts can be state-aware. Q9
+	* lifted the router-only restriction; evaluate now runs in both
+	* router and route modes.
+	*/
+	async runEvaluate(branches) {
+		if (!this.config.evaluate) return;
+		const evaluateContext = {
+			iteration: this.iteration,
+			input: this.input,
+			state: this.state,
+			result: indexBranchesForEvaluate(branches),
+			iterations: this.snapshots,
+			context: this.context,
+			history: this.history,
+			goal: this.goal,
+			classifier: this.classifierSnapshot
+		};
+		try {
+			return await this.config.evaluate(evaluateContext);
+		} catch (thrown) {
+			throw new SupervisorFailedError(`evaluate callback threw: ${thrown instanceof Error ? thrown.message : String(thrown)}`, { cause: thrown });
+		}
+	}
+	/**
+	* Merge each branch's output into supervisor `state` in
+	* `decision.intents` order — Q15 conflict rule: last intent in
+	* the array wins on key collisions. Errored branches don't
+	* contribute. Non-object outputs (primitives, null) are skipped
+	* with a warning log; they can't shallow-merge into an object.
+	*
+	* For agent/workflow intents: merging is opt-in via declaring an
+	* `output` schema (the strip-merge gate). Without a schema, the
+	* raw output stays on the branch snapshot but doesn't pollute
+	* state. For callback intents: their return is already strip-merged
+	* (or pass-through) inside `runCallback` — we just merge what's on
+	* the branch snapshot.
+	*/
+	mergeBranchesIntoState(intentsOrder, branches) {
+		const indexed = /* @__PURE__ */ new Map();
+		for (const branch of branches) indexed.set(branch.intent, branch);
+		const mergedKeys = /* @__PURE__ */ new Map();
+		for (const intent of intentsOrder) {
+			const branch = indexed.get(intent);
+			if (!branch || branch.error) continue;
+			const entry = this.entries.get(intent);
+			const isStreamModeAgent = entry?.type === "agent" && entry.mode === "stream";
+			if (!(entry?.type === "callback" || entry && entry.output !== void 0 || isStreamModeAgent)) continue;
+			const slice = branch.output;
+			if (!slice || typeof slice !== "object" || Array.isArray(slice)) {
+				if (slice !== void 0) this.logger.warn(this.logModule, "state.merge.skip", `intent "${intent}" output is not a mergeable object — skipping state merge`, {
+					intent,
+					type: typeof slice
+				});
+				continue;
+			}
+			for (const [key, value] of Object.entries(slice)) {
+				const previousOwner = mergedKeys.get(key);
+				if (previousOwner !== void 0 && previousOwner !== intent) this.logger.warn(this.logModule, "state.merge.conflict", `state key "${key}" written by both "${previousOwner}" and "${intent}" — last-in-decision-array wins (Q15)`, {
+					key,
+					previousOwner,
+					currentIntent: intent
+				});
+				this.state[key] = value;
+				mergedKeys.set(key, intent);
+			}
+		}
+	}
+	/**
+	* Merge the iteration's accumulated `currentArtifacts` bag into
+	* supervisor state (Phase 5 / decisions §35). Runs once per
+	* iteration after branch slices land and before evaluate.
+	*
+	* Order of operations:
+	*
+	* 1. **Empty-bag fast path** — if no tool wrote anything, skip
+	*    validation and merge entirely; reset the bag for the next
+	*    iteration is also a no-op (already empty).
+	* 2. **Schema validation** — when `config.artifactsSchema` is set,
+	*    validate the bag against it. Failure aborts the iteration via
+	*    a thrown `SchemaValidationError`; the iteration loop's outer
+	*    catch surfaces it on `result.error`. Validation is opt-in
+	*    (no schema → no validation cost).
+	* 3. **Merge** — `config.finalizeArtifacts` when supplied, else
+	*    auto-spread `state = { ...state, ...artifacts }`. Replace
+	*    semantics under auto-spread; `finalizeArtifacts` carries
+	*    full responsibility for concat / dedupe / cross-iteration
+	*    accumulation when configured.
+	* 4. **Reset** — `currentArtifacts = {}`. The next iteration's
+	*    tool calls start with a fresh empty bag; long runs never
+	*    accumulate raw artifacts here.
+	*/
+	async mergeArtifactsIntoState() {
+		const artifacts = this.currentArtifacts;
+		const keys = Object.keys(artifacts);
+		this.capturedIterationArtifacts = Object.freeze({ ...artifacts });
+		if (keys.length === 0) return;
+		const schema = this.config.artifactsSchema;
+		if (schema) {
+			const validation = await schema["~standard"].validate(artifacts);
+			if (validation.issues) throw new SchemaValidationError(`supervisor "${this.config.name}": iteration ${this.iteration} artifacts failed validation: ${validation.issues.map((issue) => issue.message).join("; ")}`, {
+				issues: validation.issues,
+				context: { iteration: this.iteration }
+			});
+		}
+		const finalize = this.config.finalizeArtifacts;
+		if (finalize) {
+			const merged = finalize(this.state, artifacts);
+			for (const key of Object.keys(this.state)) if (!(key in merged)) delete this.state[key];
+			for (const [key, value] of Object.entries(merged)) this.state[key] = value;
+		} else for (const [key, value] of Object.entries(artifacts)) this.state[key] = value;
+		this.currentArtifacts = {};
+	}
+	/**
+	* Collect each branch's `intent.next(ctx)` directive after state
+	* merge (Stage 4d / Q24). Iterates `decision.intents` order so
+	* union resolution is deterministic.
+	*
+	* Rules:
+	* - Errored branch → silent (treated as if no `next` defined).
+	* - Branch with no `next` → silent; abstains (does NOT drag the
+	*   iteration to the router).
+	* - Branch returns `END` → supreme; terminates immediately and
+	*   discards other branches' opinions.
+	* - Branch returns `string` or `string[]` → contributes to the
+	*   union of unique intent names. Validated against the
+	*   supervisor's registry; unknown keys throw `SupervisorFailedError`.
+	* - All branches silent → returns `undefined`; caller falls back
+	*   to router/route.
+	*/
+	collectIntentNext(intentsOrder, branches) {
+		const indexed = /* @__PURE__ */ new Map();
+		for (const branch of branches) indexed.set(branch.intent, branch);
+		const collected = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const intent of intentsOrder) {
+			const branch = indexed.get(intent);
+			if (!branch || branch.error) continue;
+			const entry = this.entries.get(intent);
+			if (!entry?.next) continue;
+			const dispatchCtx = this.seedDispatchContext(intent, branch.input, new Set([intent]), []);
+			let raw;
+			try {
+				raw = entry.next(dispatchCtx);
+			} catch (thrown) {
+				throw new SupervisorFailedError(`intent "${intent}" \`next\` resolver threw: ${thrown instanceof Error ? thrown.message : String(thrown)}`, {
+					cause: thrown,
+					context: { intent }
+				});
+			}
+			if (raw === void 0) continue;
+			if (raw === "__warlock:end__") return { kind: "end" };
+			const proposed = Array.isArray(raw) ? raw : [raw];
+			for (const target of proposed) {
+				if (typeof target !== "string") throw new SupervisorFailedError(`intent "${intent}" \`next\` returned a non-string value`, { context: { intent } });
+				if (!this.entries.has(target)) throw new SupervisorFailedError(`intent "${intent}" \`next\` returned unknown intent "${target}"`, { context: {
+					intent,
+					target,
+					available: [...this.entries.keys()]
+				} });
+				if (!seen.has(target)) {
+					seen.add(target);
+					collected.push(target);
+				}
+			}
+		}
+		if (collected.length === 0) return;
+		return {
+			kind: "dispatch",
+			intents: collected
+		};
+	}
+	/**
+	* Finalize the supervisor result: validate accumulated state
+	* against the output schema and build the public `SupervisorResult`.
+	* Assemble-only — event emission and stream close happen in
+	* `run()` around this call.
+	*/
+	async finalize() {
+		if (this.status === "completed" && !this.error) try {
+			this.data = await this.buildTypedData();
+		} catch (thrown) {
+			this.error = toAIError(thrown);
+			this.status = "failed";
+			this.terminatedBy = "error";
+		}
+		const endedAt = /* @__PURE__ */ new Date();
+		const finalStatus = this.status === "max-iterations" ? "failed" : this.status;
+		await this.checkpoint(finalStatus);
+		const report = {
+			runId: this.runId,
+			rootRunId: this.runId,
+			name: this.config.name,
+			version: this.config.version,
+			type: "supervisor",
+			supervisorName: this.config.name,
+			signature: this.signature,
+			status: this.status,
+			terminatedBy: this.terminatedBy,
+			iterations: this.snapshots.length,
+			startedAt: this.startedAtIso,
+			endedAt: endedAt.toISOString(),
+			duration: performance.now() - this.startPerf,
+			cancelledAt: this.cancelledAtIso,
+			usage: this.usage,
+			children: this.childReports,
+			snapshots: this.snapshots,
+			ack: this.ackSnapshot,
+			classifier: this.classifierSnapshot
+		};
+		stampReportLineage(report, {
+			rootRunId: this.runId,
+			sessionId: this.options?.sessionId
+		});
+		return {
+			type: "supervisor",
+			data: this.data,
+			report,
+			usage: this.usage,
+			error: this.error
+		};
+	}
+	/**
+	* Build the typed `data` at finalize. Stage 4c — single mode:
+	*
+	* - When `config.output` is declared, validate the accumulated
+	*   `state` against it and return the validated value (Q8).
+	*   `result.data` always matches the schema, or `result.error`
+	*   carries the validation issues.
+	* - When `config.output` is omitted, return the raw state object.
+	*
+	* Validation failure surfaces as `SchemaValidationError` on
+	* `result.error`; the run is still considered semantically
+	* "completed" (intents ran, evaluate said done) but the typed
+	* data slot is empty.
+	*/
+	async buildTypedData() {
+		if (this.config.output) return validateOutput(this.config.output, this.state);
+		return this.state;
+	}
+	/**
+	* Record a snapshot for an iteration whose first decision was
+	* `END` — no dispatch, no evaluate, just the decision record. Keeps
+	* the snapshot log uniform so a late-route-to-END still appears in
+	* the forensic history rather than vanishing.
+	*/
+	async recordTerminalDecisionSnapshot(decision, iterationStartedAt, iterationStart, iterationUsage) {
+		const snapshot = Object.freeze({
+			iteration: this.iteration,
+			result: {},
+			decision: {
+				source: decision.source,
+				next: decision.raw,
+				reasoning: decision.reasoning,
+				durationMs: decision.durationMs
+			},
+			state: { ...this.state },
+			artifacts: this.capturedIterationArtifacts,
+			startedAt: iterationStartedAt.toISOString(),
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			duration: performance.now() - iterationStart,
+			usage: iterationUsage
+		});
+		this.snapshots.push(snapshot);
+		this.emit("supervisor.iteration.completed", {
+			iteration: this.iteration,
+			snapshot
+		});
+		await this.checkpoint("running");
+	}
+	/**
+	* Write the current run state to the configured KV store (if any).
+	* Persistence failures surface as `supervisor.error` events and
+	* logged warnings but never abort the run — checkpoint best-effort
+	* by design, matching `workflow` semantics.
+	*/
+	async checkpoint(status) {
+		if (!(await persistSupervisorSnapshot({
+			config: this.config,
+			signature: this.signature,
+			runId: this.runId,
+			input: this.input,
+			startedAt: this.startedAtIso,
+			iteration: this.snapshots.length - 1,
+			snapshots: this.snapshots,
+			status
+		})).ok) this.logger.warn(this.logModule, "persist.failed", "snapshot persist failed", { runId: this.runId });
+	}
+	/**
+	* Between-iteration cancellation check. Called at the top of
+	* every iteration; signal abort here means the loop exits before
+	* any routing happens.
+	*/
+	throwIfCancelled() {
+		if (this.options?.signal?.aborted) throw createCancelledError(this.options.signal);
+	}
+	/**
+	* Aggregate one usage record (typically a branch or a router call)
+	* into both the run-wide total and the iteration-local total.
+	*/
+	aggregateUsage(iterationUsage, partial) {
+		if (!partial) return;
+		this.usage.input += partial.input;
+		this.usage.output += partial.output;
+		this.usage.total += partial.total;
+		iterationUsage.input += partial.input;
+		iterationUsage.output += partial.output;
+		iterationUsage.total += partial.total;
+	}
+	/**
+	* Fan an event out through the three-tier emitter AND mirror it
+	* into the stream controller when streaming. Event names map 1:1
+	* to stream event types so consumers iterating the stream see the
+	* exact same surface as `.on()` / `options.on` handlers.
+	*/
+	emit(event, payload) {
+		const identity = {
+			runId: this.runId,
+			rootRunId: this.runId
+		};
+		const fullPayload = {
+			...payload,
+			...identity
+		};
+		this.emitter.emit(event, fullPayload, this.options?.on);
+		this.logEvent(event, fullPayload);
+		if (this.streamController) this.streamController.push({
+			type: event,
+			...fullPayload
+		});
+	}
+	logEvent(event, payload) {
+		const action = event.replace(/^supervisor\./, "");
+		switch (event) {
+			case "supervisor.starting":
+				this.logger.info(this.logModule, action, "supervisor starting", { runId: this.runId });
+				return;
+			case "supervisor.iteration.starting":
+				this.logger.debug(this.logModule, action, "iteration starting", { iteration: payload.iteration });
+				return;
+			case "supervisor.router.decided":
+				this.logger.debug(this.logModule, action, "router decided", {
+					iteration: payload.iteration,
+					next: payload.next
+				});
+				return;
+			case "supervisor.agent.completed": {
+				const typed = payload;
+				this.logger.success(this.logModule, action, `branch "${typed.intent}" done`, {
+					duration: typed.duration,
+					usage: typed.usage
+				});
+				return;
+			}
+			case "supervisor.agent.failed": {
+				const typed = payload;
+				this.logger.warn(this.logModule, action, `branch "${typed.intent}" failed`, {
+					code: typed.error.code,
+					message: typed.error.message
+				});
+				return;
+			}
+			case "supervisor.error": {
+				const { error } = payload;
+				this.logger.error(this.logModule, action, error.message, { code: error.code });
+				return;
+			}
+			case "supervisor.cancelled": {
+				const typed = payload;
+				this.logger.warn(this.logModule, action, "supervisor cancelled", {
+					cancelledAt: typed.cancelledAt,
+					reason: typed.reason
+				});
+				return;
+			}
+			case "supervisor.iteration.completed":
+				this.logger.debug(this.logModule, action, "iteration completed", { iteration: payload.iteration });
+				return;
+			default: return;
+		}
+	}
+};
+function indexByIntent(branches) {
+	const indexed = {};
+	for (const branch of branches) indexed[branch.intent] = branch;
+	return indexed;
+}
+function indexBranchesForEvaluate(branches) {
+	const indexed = {};
+	for (const branch of branches) indexed[branch.intent] = {
+		output: branch.output,
+		input: branch.input,
+		usage: branch.usage,
+		durationMs: branch.duration,
+		error: branch.error
+	};
+	return indexed;
+}
+function normalizeReassign(reassignTo) {
+	if (!reassignTo) return [];
+	if (Array.isArray(reassignTo)) return reassignTo;
+	return [reassignTo];
+}
+function toAIError(thrown) {
+	if (thrown instanceof AIError) return thrown;
+	return new SupervisorFailedError(thrown instanceof Error ? thrown.message : String(thrown), { cause: thrown });
+}
+/**
+* Sum a list of child `BaseReport.usage` values. Callbacks
+* themselves contribute zero own-cost (they're dev code, not LLM
+* calls); their report's `usage` equals the sum of whatever
+* agents / workflows / nested callbacks they dispatched via
+* `ctx.intents.X.execute()`. Mirrors `compositeAsTool` semantics.
+*/
+function aggregateChildUsage(children) {
+	return children.reduce((acc, child) => ({
+		input: acc.input + child.usage.input,
+		output: acc.output + child.usage.output,
+		total: acc.total + child.usage.total
+	}), {
+		input: 0,
+		output: 0,
+		total: 0
+	});
+}
+/**
+* Best-effort stringification for the snapshot's `input` field when
+* a callback intent's resolved input is a non-string value. Falls
+* back to a typed placeholder if `JSON.stringify` throws (circular
+* refs, BigInt, etc.) so a snapshot write never fails on its own.
+*/
+function safeStringify(value) {
+	if (value === void 0) return "undefined";
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return `[unserializable: ${typeof value}]`;
+	}
+}
+async function validateOutput(schema, value) {
+	const validation = await schema["~standard"].validate(value);
+	if (validation.issues) throw new SchemaValidationError(validation.issues.map((issue) => issue.message).join("; "), { issues: validation.issues });
+	return validation.value;
+}
+
+//#endregion
+export { SupervisorExecution };
+//# sourceMappingURL=execution.mjs.map