@dogpile/sdk 0.3.1 → 0.4.0

package/dist/browser/index.js

@@ -193,6 +193,27 @@ function addCost(left, right) {
 		totalTokens: left.totalTokens + right.totalTokens
 	};
 }
+function resolveOnChildFailure(runOption, engineOption) {
+	return runOption ?? engineOption ?? "continue";
+}
+/**
+* Walk a parent's events and accumulate the cost contributed by every
+* sub-run (BUDGET-03 / D-06). Internal helper — not part of the public surface.
+*
+* - `sub-run-completed` events contribute `event.subResult.cost`.
+* - `sub-run-failed` events contribute `event.partialCost` (real provider
+*   spend captured before the throw).
+*
+* Used by the `parent-rollup-drift` parity check in
+* {@link recomputeAccountingFromTrace} to verify the parent's recorded
+* accounting equals `localOnly + Σ children` recursively.
+*/
+function accumulateSubRunCost(events) {
+	let total = emptyCost();
+	for (const event of events) if (event.type === "sub-run-completed") total = addCost(total, event.subResult.cost);
+	else if (event.type === "sub-run-failed") total = addCost(total, event.partialCost);
+	return total;
+}
 function createTranscriptLink(transcript) {
 	return {
 		kind: "trace-transcript",
@@ -291,7 +312,14 @@ function createReplayTraceBudgetStateChanges(events) {
 			case "model-response":
 			case "model-output-chunk":
 			case "tool-call":
-			case "tool-result": return [];
+			case "tool-result":
+			case "sub-run-started":
+			case "sub-run-completed":
+			case "sub-run-failed":
+			case "sub-run-parent-aborted":
+			case "sub-run-budget-clamped":
+			case "sub-run-queued":
+			case "sub-run-concurrency-clamped": return [];
 		}
 	});
 }
@@ -388,6 +416,24 @@ function createReplayTraceProtocolDecision(protocol, event, eventIndex, options
 			output: event.output,
 			cost: event.cost
 		};
+		case "sub-run-started": return {
+			...base,
+			input: event.intent
+		};
+		case "sub-run-completed": return {
+			...base,
+			output: event.subResult.output,
+			cost: event.subResult.cost
+		};
+		case "sub-run-failed": return { ...base };
+		case "sub-run-parent-aborted": return { ...base };
+		case "sub-run-budget-clamped": return { ...base };
+		case "sub-run-queued": return {
+			...base,
+			childRunId: event.childRunId,
+			queuePosition: event.queuePosition
+		};
+		case "sub-run-concurrency-clamped": return { ...base };
 	}
 }
 function defaultProtocolDecision(event) {
@@ -402,6 +448,13 @@ function defaultProtocolDecision(event) {
 		case "broadcast": return "collect-broadcast-round";
 		case "budget-stop": return "stop-for-budget";
 		case "final": return "finalize-output";
+		case "sub-run-started": return "start-sub-run";
+		case "sub-run-completed": return "complete-sub-run";
+		case "sub-run-failed": return "fail-sub-run";
+		case "sub-run-parent-aborted": return "mark-sub-run-parent-aborted";
+		case "sub-run-budget-clamped": return "mark-sub-run-budget-clamped";
+		case "sub-run-queued": return "queue-sub-run";
+		case "sub-run-concurrency-clamped": return "mark-sub-run-concurrency-clamped";
 	}
 }
 function eventAgentScope(event) {
@@ -467,6 +520,216 @@ function canonicalizeRunResult(result) {
 function stableJsonStringify(value) {
 	return JSON.stringify(canonicalizeSerializable(value));
 }
+/**
+* The eight numeric fields recursively verified by `recomputeAccountingFromTrace`.
+*
+* These are the only summable scalars on `RunAccounting`. Non-numeric fields
+* (`kind`, `tier`, `budget`, `termination`, `budgetStateChanges`) and derived
+* ratios (`usdCapUtilization`, `totalTokenCapUtilization`) are NOT in this set.
+*/
+var RECOMPUTE_FIELD_ORDER = [
+	"cost.usd",
+	"cost.inputTokens",
+	"cost.outputTokens",
+	"cost.totalTokens",
+	"usage.usd",
+	"usage.inputTokens",
+	"usage.outputTokens",
+	"usage.totalTokens"
+];
+var USD_FIELDS = new Set(["cost.usd", "usage.usd"]);
+var FLOAT_EPSILON = 1e-9;
+function readNumericField(accounting, field) {
+	switch (field) {
+		case "cost.usd": return accounting.cost.usd;
+		case "cost.inputTokens": return accounting.cost.inputTokens;
+		case "cost.outputTokens": return accounting.cost.outputTokens;
+		case "cost.totalTokens": return accounting.cost.totalTokens;
+		case "usage.usd": return accounting.usage.usd;
+		case "usage.inputTokens": return accounting.usage.inputTokens;
+		case "usage.outputTokens": return accounting.usage.outputTokens;
+		case "usage.totalTokens": return accounting.usage.totalTokens;
+	}
+}
+function fieldsEqual(field, a, b) {
+	if (USD_FIELDS.has(field)) return Math.abs(a - b) < FLOAT_EPSILON;
+	return a === b;
+}
+function firstDifferingField(recorded, recomputed) {
+	for (const field of RECOMPUTE_FIELD_ORDER) {
+		const a = readNumericField(recorded, field);
+		const b = readNumericField(recomputed, field);
+		if (!fieldsEqual(field, a, b)) return {
+			field,
+			recorded: a,
+			recomputed: b
+		};
+	}
+	return null;
+}
+function buildLocalAccounting(trace) {
+	return createRunAccounting({
+		tier: trace.tier,
+		...trace.budget.caps ? { budget: trace.budget.caps } : {},
+		...trace.budget.termination ? { termination: trace.budget.termination } : {},
+		cost: trace.finalOutput.cost,
+		events: trace.events
+	});
+}
+function lastCostBearingEventCost(events) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event === void 0) continue;
+		if (event.type === "final" || event.type === "agent-turn" || event.type === "broadcast" || event.type === "budget-stop") return event.cost;
+	}
+	return null;
+}
+/**
+* Recompute a parent's `RunAccounting` from a saved `Trace` for replay-time
+* tamper detection.
+*
+* @remarks
+* Returns the parent's local `RunAccounting` (built the same way `replay()`
+* builds it today, from `trace.finalOutput.cost` and `trace.events`). While
+* walking events, every `sub-run-completed` is recursed into and the
+* recomputed child accounting is compared field-by-field to the recorded
+* `event.subResult.accounting`. A mismatch on any of the eight enumerated
+* numeric fields throws `DogpileError({ code: "invalid-configuration" })`
+* with `detail.reason: "trace-accounting-mismatch"` and a concrete
+* `detail.field` identifying the first differing numeric.
+*
+* Pure: no provider calls, no I/O, no clock reads.
+*
+* Non-summed fields (`kind`, `tier`, `budget`, `termination`,
+* `budgetStateChanges`) and derived ratios (`usdCapUtilization`,
+* `totalTokenCapUtilization`) are not in the comparison set.
+*/
+function recomputeAccountingFromTrace(trace) {
+	const local = buildLocalAccounting(trace);
+	const lastEventCost = lastCostBearingEventCost(trace.events);
+	if (lastEventCost !== null) {
+		const drift = firstDifferingField(local, createRunAccounting({
+			tier: trace.tier,
+			...trace.budget.caps ? { budget: trace.budget.caps } : {},
+			...trace.budget.termination ? { termination: trace.budget.termination } : {},
+			cost: lastEventCost,
+			events: trace.events
+		}));
+		if (drift !== null) throw new DogpileError({
+			code: "invalid-configuration",
+			message: `Trace accounting mismatch at parent run ${trace.runId}: field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed}.`,
+			retryable: false,
+			detail: {
+				kind: "trace-validation",
+				reason: "trace-accounting-mismatch",
+				eventIndex: -1,
+				childRunId: trace.runId,
+				field: drift.field,
+				recorded: drift.recorded,
+				recomputed: drift.recomputed
+			}
+		});
+	}
+	for (let eventIndex = 0; eventIndex < trace.events.length; eventIndex += 1) {
+		const event = trace.events[eventIndex];
+		if (event === void 0) continue;
+		if (event.type === "sub-run-completed") {
+			const childRecordedRollup = createRunAccounting({
+				tier: trace.tier,
+				cost: event.subResult.cost,
+				events: []
+			});
+			const childRecordedAccounting = event.subResult.accounting;
+			const drift = firstDifferingField(childRecordedAccounting, childRecordedRollup);
+			if (drift !== null) throw new DogpileError({
+				code: "invalid-configuration",
+				message: `Trace parent-rollup mismatch at sub-run ${event.childRunId}: field "${drift.field}" recorded ${drift.recorded} on accounting, ${drift.recomputed} on subResult.cost.`,
+				retryable: false,
+				detail: {
+					kind: "trace-validation",
+					reason: "trace-accounting-mismatch",
+					subReason: "parent-rollup-drift",
+					eventIndex,
+					childRunId: event.childRunId,
+					field: drift.field,
+					recorded: drift.recorded,
+					recomputed: drift.recomputed
+				}
+			});
+		} else if (event.type === "sub-run-failed") {
+			const partialFromTrace = lastCostBearingEventCost(event.partialTrace.events) ?? emptyCost();
+			const drift = firstDifferingField(createRunAccounting({
+				tier: trace.tier,
+				cost: event.partialCost,
+				events: []
+			}), createRunAccounting({
+				tier: trace.tier,
+				cost: partialFromTrace,
+				events: []
+			}));
+			if (drift !== null) throw new DogpileError({
+				code: "invalid-configuration",
+				message: `Trace parent-rollup mismatch at sub-run ${event.childRunId}: partialCost field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed} from partialTrace events.`,
+				retryable: false,
+				detail: {
+					kind: "trace-validation",
+					reason: "trace-accounting-mismatch",
+					subReason: "parent-rollup-drift",
+					eventIndex,
+					childRunId: event.childRunId,
+					field: drift.field,
+					recorded: drift.recorded,
+					recomputed: drift.recomputed
+				}
+			});
+		}
+	}
+	const subRunTotal = accumulateSubRunCost(trace.events);
+	const parentTotal = trace.finalOutput.cost;
+	for (const field of RECOMPUTE_FIELD_ORDER) {
+		if (field.startsWith("usage.")) continue;
+		const [, key] = field.split(".");
+		const parentValue = parentTotal[key];
+		const childValue = subRunTotal[key];
+		if (childValue - parentValue > FLOAT_EPSILON) throw new DogpileError({
+			code: "invalid-configuration",
+			message: `Trace parent-rollup mismatch at run ${trace.runId}: field "${field}" Σ children ${childValue} exceeds parent recorded ${parentValue}.`,
+			retryable: false,
+			detail: {
+				kind: "trace-validation",
+				reason: "trace-accounting-mismatch",
+				subReason: "parent-rollup-drift",
+				eventIndex: -1,
+				childRunId: trace.runId,
+				field,
+				recorded: parentValue,
+				recomputed: childValue
+			}
+		});
+	}
+	for (let eventIndex = 0; eventIndex < trace.events.length; eventIndex += 1) {
+		const event = trace.events[eventIndex];
+		if (event === void 0 || event.type !== "sub-run-completed") continue;
+		const childRecomputed = recomputeAccountingFromTrace(event.subResult.trace);
+		const childRecorded = event.subResult.accounting;
+		const drift = firstDifferingField(childRecorded, childRecomputed);
+		if (drift !== null) throw new DogpileError({
+			code: "invalid-configuration",
+			message: `Trace accounting mismatch at sub-run ${event.childRunId}: field "${drift.field}" recorded ${drift.recorded}, recomputed ${drift.recomputed}.`,
+			retryable: false,
+			detail: {
+				kind: "trace-validation",
+				reason: "trace-accounting-mismatch",
+				eventIndex,
+				childRunId: event.childRunId,
+				field: drift.field,
+				recorded: drift.recorded,
+				recomputed: drift.recomputed
+			}
+		});
+	}
+	return local;
+}
 function canonicalizeSerializable(value) {
 	if (Array.isArray(value)) return value.map((item) => canonicalizeSerializable(item));
 	if (typeof value === "number") {
@@ -485,6 +748,24 @@ function canonicalizeSerializable(value) {
 }
 //#endregion
 //#region src/runtime/cancellation.ts
+/**
+* Classify an abort signal's reason into the BUDGET-01 / BUDGET-02
+* `detail.reason` discriminator.
+*
+* - `"timeout"` when the reason is a {@link DogpileError} with `code === "timeout"`
+*   (matches the parent-deadline abort path in `engine.ts:createTimeoutAbortLifecycle`).
+* - `"parent-aborted"` for every other reason — explicit caller abort, plain
+*   `Error`, `undefined`, or arbitrary primitive.
+*/
+function classifyAbortReason(signalReasonOrError) {
+	if (DogpileError.isInstance(signalReasonOrError) && signalReasonOrError.code === "timeout") return "timeout";
+	return "parent-aborted";
+}
+function classifyChildTimeoutSource(_error, context) {
+	if (context.isProviderError) return "provider";
+	if (context.decisionTimeoutMs !== void 0 || context.engineDefaultTimeoutMs !== void 0) return "engine";
+	return "provider";
+}
 function throwIfAborted(signal, providerId) {
 	if (!signal?.aborted) return;
 	throw createAbortErrorFromSignal(signal, providerId);
@@ -501,7 +782,7 @@ function createAbortError(providerId, detail, cause) {
 }
 function createAbortErrorFromSignal(signal, providerId) {
 	if (DogpileError.isInstance(signal.reason)) return signal.reason;
-	return createAbortError(providerId, void 0, signal.reason);
+	return createAbortError(providerId, { reason: classifyAbortReason(signal.reason) }, signal.reason);
 }
 function createTimeoutError(providerId, timeoutMs) {
 	return new DogpileError({
@@ -512,23 +793,223 @@ function createTimeoutError(providerId, timeoutMs) {
 		detail: { timeoutMs }
 	});
 }
+function createEngineDeadlineTimeoutError(providerId, timeoutMs) {
+	return new DogpileError({
+		code: "provider-timeout",
+		message: `The child engine deadline expired after ${timeoutMs}ms.`,
+		retryable: true,
+		providerId,
+		detail: {
+			timeoutMs,
+			source: "engine"
+		}
+	});
+}
 //#endregion
 //#region src/runtime/decisions.ts
-function parseAgentDecision(output) {
+var PROTOCOL_NAMES = [
+	"coordinator",
+	"sequential",
+	"broadcast",
+	"shared"
+];
+function parseAgentDecision(output, context = {}) {
+	const delegateBlock = matchDelegateBlock(output);
+	if (delegateBlock !== void 0) return parseDelegateDecision(delegateBlock, context);
+	return parseParticipateDecision(output);
+}
+function isParticipatingDecision(decision) {
+	if (decision === void 0 || isDelegateDecisionArray(decision) || decision.type !== "participate") return false;
+	return decision.participation !== "abstain";
+}
+function isDelegateDecisionArray(decision) {
+	return Array.isArray(decision);
+}
+function parseParticipateDecision(output) {
 	const selectedRole = matchLine(output, /^role_selected:\s*(.+)$/imu);
 	const participation = matchLine(output, /^participation:\s*(contribute|abstain)$/imu);
 	const rationale = matchLine(output, /^rationale:\s*(.+)$/imu);
 	const contribution = matchContribution(output);
 	if (!selectedRole || !participation || !isAgentParticipation(participation) || !rationale || !contribution) return;
 	return {
+		type: "participate",
 		selectedRole,
 		participation,
 		rationale,
 		contribution
 	};
 }
-function isParticipatingDecision(decision) {
-	return decision?.participation !== "abstain";
+/**
+* Locate a `delegate:` line followed by a fenced JSON block in the agent's
+* output. Returns the raw JSON text inside the fence, or `undefined` when no
+* delegate block is present. Tolerates ```` ```json ```` and bare ```` ``` ````.
+*/
+function matchDelegateBlock(output) {
+	return output.match(/^delegate:\s*\r?\n\s*```(?:json)?\s*\r?\n([\s\S]*?)\r?\n\s*```/imu)?.[1];
+}
+function parseDelegateDecision(jsonText, context) {
+	let parsed;
+	try {
+		parsed = JSON.parse(jsonText);
+	} catch (error) {
+		throwInvalidDelegate({
+			path: "decision",
+			message: `delegate JSON did not parse: ${error instanceof Error ? error.message : String(error)}`,
+			expected: "valid JSON object",
+			received: truncate(jsonText)
+		});
+	}
+	if (Array.isArray(parsed)) {
+		if (parsed.length === 0) throwInvalidDelegate({
+			path: "decision",
+			message: "delegate array must not be empty.",
+			expected: "array with 1..8 delegate objects",
+			received: "empty array"
+		});
+		return parsed.map((item) => parseSingleDelegateObject(item, context));
+	}
+	return parseSingleDelegateObject(parsed, context);
+}
+function parseSingleDelegateObject(parsed, context) {
+	if (parsed === null || typeof parsed !== "object") throwInvalidDelegate({
+		path: "decision",
+		message: "delegate decision must be a JSON object.",
+		expected: "object",
+		received: describe(parsed)
+	});
+	const record = parsed;
+	const protocol = record["protocol"];
+	if (typeof protocol !== "string" || !PROTOCOL_NAMES.includes(protocol)) throwInvalidDelegate({
+		path: "decision.protocol",
+		message: `protocol "${describe(protocol)}" is not a known coordination protocol.`,
+		expected: PROTOCOL_NAMES.join(" | "),
+		received: describe(protocol)
+	});
+	const intentRaw = record["intent"];
+	const intent = typeof intentRaw === "string" ? intentRaw.trim() : "";
+	if (intent.length === 0) throwInvalidDelegate({
+		path: "decision.intent",
+		message: "delegate decision must include a non-empty intent string.",
+		expected: "non-empty string",
+		received: describe(intentRaw)
+	});
+	const result = {
+		type: "delegate",
+		protocol,
+		intent
+	};
+	if (record["model"] !== void 0) {
+		const model = record["model"];
+		if (typeof model !== "string" || model.length === 0) throwInvalidDelegate({
+			path: "decision.model",
+			message: "delegate decision model must be a non-empty string when present.",
+			expected: "non-empty string",
+			received: describe(model)
+		});
+		if (context.parentProviderId !== void 0 && model !== context.parentProviderId) throwInvalidDelegate({
+			path: "decision.model",
+			message: `delegate decision model "${model}" does not match parent provider id "${context.parentProviderId}".`,
+			expected: context.parentProviderId,
+			received: model
+		});
+		result.model = model;
+	}
+	if (record["budget"] !== void 0) result.budget = parseDelegateBudget(record["budget"]);
+	if (record["maxConcurrentChildren"] !== void 0) {
+		const value = record["maxConcurrentChildren"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1) throwInvalidDelegate({
+			path: "decision.maxConcurrentChildren",
+			message: "delegate decision maxConcurrentChildren must be a positive integer when present.",
+			expected: "integer >= 1",
+			received: describe(value)
+		});
+		result.maxConcurrentChildren = value;
+	}
+	if (context.currentDepth !== void 0 && context.maxDepth !== void 0) {
+		if (context.currentDepth + 1 > context.maxDepth) throw depthOverflowError(context.currentDepth, context.maxDepth);
+	}
+	return result;
+}
+/**
+* Build the canonical depth-overflow `DogpileError`. Used by the parser (this
+* file) and the coordinator dispatcher; kept here so both call sites produce
+* the exact same error shape (D-14, D-15).
+*/
+function depthOverflowError(currentDepth, maxDepth) {
+	return new DogpileError({
+		code: "invalid-configuration",
+		message: `Depth overflow: cannot dispatch sub-run at depth ${currentDepth + 1} (maxDepth = ${maxDepth}).`,
+		retryable: false,
+		detail: {
+			kind: "delegate-validation",
+			path: "decision.protocol",
+			reason: "depth-overflow",
+			currentDepth,
+			maxDepth
+		}
+	});
+}
+/**
+* Dispatcher-time depth gate. Throws the same error shape the parser uses; the
+* dual gate (parser + dispatcher) defends against any TOCTOU window between
+* decision parsing and child-run spin-up (D-14).
+*/
+function assertDepthWithinLimit(currentDepth, maxDepth) {
+	if (currentDepth + 1 > maxDepth) throw depthOverflowError(currentDepth, maxDepth);
+}
+function parseDelegateBudget(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throwInvalidDelegate({
+		path: "decision.budget",
+		message: "delegate decision budget must be an object.",
+		expected: "object",
+		received: describe(raw)
+	});
+	const record = raw;
+	const budget = {};
+	if (record["timeoutMs"] !== void 0) {
+		const value = record["timeoutMs"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throwInvalidDelegate({
+			path: "decision.budget.timeoutMs",
+			message: "delegate decision budget.timeoutMs must be a non-negative integer.",
+			expected: "integer >= 0",
+			received: describe(value)
+		});
+		budget.timeoutMs = value;
+	}
+	if (record["maxTokens"] !== void 0) {
+		const value = record["maxTokens"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throwInvalidDelegate({
+			path: "decision.budget.maxTokens",
+			message: "delegate decision budget.maxTokens must be a non-negative integer.",
+			expected: "integer >= 0",
+			received: describe(value)
+		});
+		budget.maxTokens = value;
+	}
+	if (record["maxIterations"] !== void 0) {
+		const value = record["maxIterations"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) throwInvalidDelegate({
+			path: "decision.budget.maxIterations",
+			message: "delegate decision budget.maxIterations must be a non-negative integer.",
+			expected: "integer >= 0",
+			received: describe(value)
+		});
+		budget.maxIterations = value;
+	}
+	return budget;
+}
+function throwInvalidDelegate(failure) {
+	throw new DogpileError({
+		code: "invalid-configuration",
+		message: `Invalid Dogpile configuration at ${failure.path}: ${failure.message}`,
+		retryable: false,
+		detail: {
+			kind: "delegate-validation",
+			path: failure.path,
+			expected: failure.expected,
+			received: failure.received
+		}
+	});
 }
 function matchLine(output, pattern) {
 	return output.match(pattern)?.[1]?.trim();
@@ -540,6 +1021,15 @@ function matchContribution(output) {
 function isAgentParticipation(value) {
 	return value === "contribute" || value === "abstain";
 }
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	if (typeof value === "string") return JSON.stringify(value).slice(0, 200);
+	return typeof value;
+}
+function truncate(value) {
+	return value.length > 200 ? `${value.slice(0, 200)}…` : value;
+}
 //#endregion
 //#region src/runtime/model.ts
 async function generateModelTurn(options) {
@@ -997,6 +1487,7 @@ var budgetTiers = [
 	"balanced",
 	"quality"
 ];
+var onChildFailureModes = ["continue", "abort"];
 /**
 * Validate high-level caller options before any protocol execution starts.
 */
@@ -1015,11 +1506,25 @@ function validateDogpileOptions(options) {
 	validateOptionalFunction(options.evaluate, "evaluate");
 	validateOptionalSeed(options.seed, "seed");
 	validateOptionalAbortSignal(options.signal, "signal");
+	validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
+	validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+	validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
+	validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }
 function validateMissionIntent(intent, path = "intent") {
 	validateNonEmptyString(intent, path, "intent is required.");
 }
 /**
+* Validate per-call run/stream options (`Engine.run(intent, options)` / `Engine.stream(...)`).
+*/
+function validateRunCallOptions(options, path = "options") {
+	if (options === void 0) return;
+	const record = requireRecord(options, path);
+	validateOptionalNonNegativeInteger(record.maxDepth, `${path}.maxDepth`);
+	validateOptionalPositiveInteger(record.maxConcurrentChildren, `${path}.maxConcurrentChildren`);
+	validateOptionalOnChildFailure(record.onChildFailure, `${path}.onChildFailure`);
+}
+/**
 * Validate low-level engine configuration before normalizing reusable controls.
 */
 function validateEngineOptions(options) {
@@ -1036,6 +1541,10 @@ function validateEngineOptions(options) {
 	validateOptionalFunction(options.evaluate, "evaluate");
 	validateOptionalSeed(options.seed, "seed");
 	validateOptionalAbortSignal(options.signal, "signal");
+	validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
+	validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+	validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
+	validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }
 function validateProtocolSelection(value, path) {
 	if (typeof value === "string") {
@@ -1083,6 +1592,23 @@ function validateBudgetTier(value, path) {
 		actual: value
 	});
 }
+function validateOptionalOnChildFailure(value, path) {
+	if (value === void 0) return;
+	if (value === "continue" || value === "abort") return;
+	throw new DogpileError({
+		code: "invalid-configuration",
+		message: `Invalid onChildFailure: expected "continue" or "abort", got ${JSON.stringify(value)}`,
+		retryable: false,
+		detail: {
+			kind: "configuration-validation",
+			path,
+			rule: "enum",
+			expected: onChildFailureModes.join(" | "),
+			received: describeValue(value),
+			reason: "invalid-on-child-failure"
+		}
+	});
+}
 /**
 * Validate configured model provider definitions at registration boundaries.
 */
@@ -1092,6 +1618,21 @@ function validateModelProviderRegistration(value, path = "model") {
 	validateFunction(record.generate, `${path}.generate`);
 	validateOptionalFunction(record.stream, `${path}.stream`);
 }
+/**
+* Engine-time defense-in-depth check that a provider's optional
+* `metadata.locality` is one of the two valid values when present (Phase 3 D-03).
+* Catches user-implemented providers that bypass TypeScript checks.
+*/
+function validateProviderLocality(provider, pathPrefix = "model") {
+	const loc = provider.metadata?.locality;
+	if (loc !== void 0 && loc !== "local" && loc !== "remote") invalidConfiguration({
+		path: `${pathPrefix}.metadata.locality`,
+		rule: "enum",
+		message: `${pathPrefix}.metadata.locality must be "local" or "remote" when provided.`,
+		expected: "\"local\" | \"remote\"",
+		actual: loc
+	});
+}
 function validateOptionalAgents(value, path) {
 	if (value === void 0) return;
 	if (!Array.isArray(value)) invalidConfiguration({
@@ -1371,6 +1912,16 @@ function validateOptionalNonNegativeInteger(value, path) {
 		actual: value
 	});
 }
+function validateOptionalPositiveFiniteNumber(value, path) {
+	if (value === void 0) return;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) invalidConfiguration({
+		path,
+		rule: "positive-finite-number",
+		message: "value must be a positive finite number.",
+		expected: "finite number > 0",
+		actual: value
+	});
+}
 function validateOptionalNonNegativeNumber(value, path) {
 	if (value === void 0) return;
 	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) invalidConfiguration({
@@ -2608,19 +3159,74 @@ function responseCost$3(response) {
 }
 //#endregion
 //#region src/runtime/coordinator.ts
+/**
+* Hard-coded loop guard for the delegate dispatch in the coordinator plan
+* turn. After this many consecutive delegate decisions the coordinator throws
+* `invalid-configuration` (T-03-01). Not a public option.
+*/
+var MAX_DISPATCH_PER_TURN = 8;
+var DEFAULT_MAX_CONCURRENT_CHILDREN$1 = 4;
+function createSemaphore(maxConcurrent) {
+	let inFlight = 0;
+	const waiters = [];
+	return {
+		acquire() {
+			if (inFlight < maxConcurrent) {
+				inFlight += 1;
+				return Promise.resolve();
+			}
+			return new Promise((resolve) => {
+				waiters.push(() => {
+					inFlight += 1;
+					resolve();
+				});
+			});
+		},
+		release() {
+			inFlight -= 1;
+			const next = waiters.shift();
+			if (next !== void 0) next();
+		},
+		get inFlight() {
+			return inFlight;
+		},
+		get queued() {
+			return waiters.length;
+		}
+	};
+}
+/**
+* Walk the coordinator's active provider set and return the FIRST provider
+* whose metadata.locality === "local", or undefined if none found.
+*
+* Walk order (forward-compat): options.model first, then options.agents in
+* declaration order. AgentSpec has no `model` field today (Phase 3 D-11
+* forward-compat scaffolding); the agent walk uses optional chaining and
+* effectively no-ops until a future phase adds AgentSpec.model.
+*/
+function findFirstLocalProvider(options) {
+	if (options.model.metadata?.locality === "local") return options.model;
+	for (const agent of options.agents) {
+		const agentModel = agent.model;
+		if (agentModel?.metadata?.locality === "local") return agentModel;
+	}
+}
 async function runCoordinator(options) {
 	const runId = createRunId();
 	const events = [];
 	const transcript = [];
 	const protocolDecisions = [];
 	const providerCalls = [];
+	const dispatchedChildren = /* @__PURE__ */ new Map();
 	let totalCost = emptyCost();
+	let concurrencyClampEmitted = false;
 	const maxTurns = options.protocol.maxTurns ?? options.agents.length;
 	const activeAgents = options.agents.slice(0, maxTurns);
 	const coordinator = activeAgents[0];
 	const startedAtMs = nowMs();
 	let stopped = false;
 	let termination;
+	let triggeringFailureForAbortMode;
 	const wrapUpHint = createWrapUpHintController({
 		protocol: options.protocol,
 		tier: options.tier,
@@ -2636,6 +3242,51 @@ async function runCoordinator(options) {
 	const recordProtocolDecision = (event, decisionOptions) => {
 		protocolDecisions.push(createReplayTraceProtocolDecision("coordinator", event, events.length - 1, decisionOptions));
 	};
+	const drainOnParentAbort = (reasonSource) => {
+		const reason = classifyAbortReason(reasonSource);
+		for (const child of dispatchedChildren.values()) {
+			if (child.closed) continue;
+			const partialCost = child.started ? lastCostBearingEventCost(child.childEvents) ?? emptyCost() : emptyCost();
+			const partialTrace = buildPartialTrace({
+				childRunId: child.childRunId,
+				events: [...child.childEvents],
+				startedAtMs: child.startedAtMs,
+				protocol: child.decision.protocol,
+				tier: options.tier,
+				modelProviderId: options.model.id,
+				agents: options.agents,
+				intent: child.decision.intent,
+				temperature: options.temperature,
+				...child.childTimeoutMs !== void 0 ? { childTimeoutMs: child.childTimeoutMs } : {},
+				...options.seed !== void 0 ? { seed: options.seed } : {}
+			});
+			const failedEvent = {
+				type: "sub-run-failed",
+				runId,
+				at: (/* @__PURE__ */ new Date()).toISOString(),
+				childRunId: child.childRunId,
+				parentRunId: runId,
+				parentDecisionId: child.parentDecisionId,
+				parentDecisionArrayIndex: child.parentDecisionArrayIndex,
+				error: child.started ? {
+					code: "aborted",
+					message: "Parent run aborted.",
+					detail: { reason }
+				} : {
+					code: "aborted",
+					message: "Sibling delegate failed; queued delegate never started.",
+					detail: { reason: "sibling-failed" }
+				},
+				partialTrace,
+				partialCost
+			};
+			child.closed = true;
+			totalCost = addCost(totalCost, partialCost);
+			emit(failedEvent);
+			recordProtocolDecision(failedEvent);
+		}
+	};
+	options.registerAbortDrain?.(drainOnParentAbort);
 	const toolExecutor = createRuntimeToolExecutor({
 		runId,
 		protocol: "coordinator",
@@ -2666,24 +3317,231 @@ async function runCoordinator(options) {
 	}
 	if (coordinator) {
 		if (!stopIfNeeded()) {
-			totalCost = await runCoordinatorTurn({
-				agent: coordinator,
-				coordinator,
-				input: buildCoordinatorPlanInput(options.intent, coordinator),
-				phase: "plan",
-				options,
-				runId,
-				transcript,
-				totalCost,
-				providerCalls,
-				toolExecutor,
-				toolAvailability,
-				events,
-				startedAtMs,
-				wrapUpHint,
-				emit,
-				recordProtocolDecision
-			});
+			let dispatchInput = buildCoordinatorPlanInput(options.intent, coordinator);
+			let dispatchCount = 0;
+			while (true) {
+				const turnOutcome = await runCoordinatorTurn({
+					agent: coordinator,
+					coordinator,
+					input: dispatchInput,
+					phase: "plan",
+					options,
+					runId,
+					transcript,
+					totalCost,
+					providerCalls,
+					toolExecutor,
+					toolAvailability,
+					events,
+					startedAtMs,
+					wrapUpHint,
+					emit,
+					recordProtocolDecision
+				});
+				totalCost = turnOutcome.totalCost;
+				if (turnOutcome.decision === void 0) break;
+				const delegates = Array.isArray(turnOutcome.decision) ? turnOutcome.decision : turnOutcome.decision.type === "delegate" ? [turnOutcome.decision] : [];
+				if (delegates.length === 0) break;
+				if (dispatchCount + delegates.length > MAX_DISPATCH_PER_TURN) throw new DogpileError({
+					code: "invalid-configuration",
+					message: `Coordinator plan turn delegated ${delegates.length} more children after ${dispatchCount}; max is ${MAX_DISPATCH_PER_TURN}.`,
+					retryable: false,
+					detail: {
+						kind: "delegate-validation",
+						path: "decision",
+						reason: "loop-guard-exceeded",
+						maxDispatchPerTurn: MAX_DISPATCH_PER_TURN
+					}
+				});
+				const parentDecisionId = String(events.length - 1);
+				const parentDepth = options.currentDepth ?? 0;
+				const decisionMax = delegates.reduce((max, delegate) => Math.min(max, delegate.maxConcurrentChildren ?? Number.POSITIVE_INFINITY), Number.POSITIVE_INFINITY);
+				let effectiveForTurn = Math.min(options.effectiveMaxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN$1, decisionMax);
+				const requestedMax = effectiveForTurn;
+				const localProvider = findFirstLocalProvider(options);
+				if (localProvider !== void 0) {
+					effectiveForTurn = 1;
+					if (!concurrencyClampEmitted) {
+						const clampEvent = {
+							type: "sub-run-concurrency-clamped",
+							runId,
+							at: (/* @__PURE__ */ new Date()).toISOString(),
+							requestedMax,
+							effectiveMax: 1,
+							reason: "local-provider-detected",
+							providerId: localProvider.id
+						};
+						emit(clampEvent);
+						recordProtocolDecision(clampEvent);
+						concurrencyClampEmitted = true;
+					}
+				}
+				const semaphore = createSemaphore(effectiveForTurn);
+				const childRunIds = delegates.map(() => createRunId());
+				const dispatchedForTurn = delegates.map((delegate, index) => {
+					const childRunId = childRunIds[index];
+					if (childRunId === void 0) throw new Error("missing child run id");
+					const dispatchedChild = {
+						childRunId,
+						decision: delegate,
+						parentDecisionId,
+						parentDecisionArrayIndex: index,
+						parentDepth,
+						controller: new AbortController(),
+						removeParentListener: void 0,
+						childEvents: [],
+						started: false,
+						closed: false,
+						startedAtMs: Date.now(),
+						childTimeoutMs: void 0,
+						failure: void 0
+					};
+					dispatchedChildren.set(childRunId, dispatchedChild);
+					return dispatchedChild;
+				});
+				const dispatchResults = [];
+				let firstFailureIndex;
+				const tasks = delegates.map(async (delegate, index) => {
+					const childRunId = childRunIds[index];
+					if (childRunId === void 0) throw new Error("missing child run id");
+					if (semaphore.inFlight >= effectiveForTurn) {
+						const queuedEvent = {
+							type: "sub-run-queued",
+							runId,
+							at: (/* @__PURE__ */ new Date()).toISOString(),
+							childRunId,
+							parentRunId: runId,
+							parentDecisionId,
+							parentDecisionArrayIndex: index,
+							protocol: delegate.protocol,
+							intent: delegate.intent,
+							depth: parentDepth + 1,
+							queuePosition: semaphore.queued
+						};
+						emit(queuedEvent);
+						recordProtocolDecision(queuedEvent);
+					}
+					await semaphore.acquire();
+					try {
+						const dispatchedChild = dispatchedForTurn[index];
+						if (!dispatchedChild) throw new Error("missing dispatched child");
+						if (firstFailureIndex !== void 0) {
+							if (dispatchedChild.closed) {
+								dispatchResults.push({
+									index,
+									result: {
+										nextInput: "",
+										taggedText: `[sub-run ${childRunId}]: skipped because the parent run aborted`,
+										completedAtMs: Date.now()
+									}
+								});
+								return;
+							}
+							const partialCost = emptyCost();
+							const partialTrace = buildPartialTrace({
+								childRunId,
+								events: [],
+								startedAtMs: Date.now(),
+								protocol: delegate.protocol,
+								tier: options.tier,
+								modelProviderId: options.model.id,
+								agents: options.agents,
+								intent: delegate.intent,
+								temperature: options.temperature,
+								...options.seed !== void 0 ? { seed: options.seed } : {}
+							});
+							const failedEvent = {
+								type: "sub-run-failed",
+								runId,
+								at: (/* @__PURE__ */ new Date()).toISOString(),
+								childRunId,
+								parentRunId: runId,
+								parentDecisionId,
+								parentDecisionArrayIndex: index,
+								error: {
+									code: "aborted",
+									message: "Sibling delegate failed; queued delegate never started.",
+									detail: { reason: "sibling-failed" }
+								},
+								partialTrace,
+								partialCost
+							};
+							emit(failedEvent);
+							recordProtocolDecision(failedEvent);
+							dispatchedChild.closed = true;
+							dispatchResults.push({
+								index,
+								result: {
+									nextInput: "",
+									taggedText: `[sub-run ${childRunId}]: skipped because a sibling delegate failed`,
+									completedAtMs: Date.now()
+								}
+							});
+							return;
+						}
+						const result = await dispatchDelegate({
+							decision: delegate,
+							childRunId,
+							parentDecisionId,
+							parentDecisionArrayIndex: index,
+							parentDepth,
+							parentRunId: runId,
+							options,
+							transcript,
+							emit,
+							recordProtocolDecision,
+							recordSubRunCost: (cost) => {
+								totalCost = addCost(totalCost, cost);
+							},
+							dispatchedChild
+						});
+						dispatchResults.push({
+							index,
+							result
+						});
+					} catch (error) {
+						firstFailureIndex ??= index;
+						const failure = dispatchedForTurn[index]?.failure;
+						if (delegates.length === 1 && (options.onChildFailure === "abort" || failure === void 0 || isDelegateValidationError(error))) throw error;
+						let taggedText = `[sub-run ${childRunId} failed]: ${error instanceof Error ? error.message : String(error)}`;
+						if (failure) {
+							const error = failure.error;
+							taggedText = `[sub-run ${childRunId} failed | code=${error.code} | spent=$${failure.partialCost.usd.toFixed(3)}]: ${error.message}`;
+						}
+						dispatchResults.push({
+							index,
+							result: {
+								nextInput: "",
+								taggedText,
+								completedAtMs: Date.now()
+							}
+						});
+					} finally {
+						semaphore.release();
+					}
+				});
+				const firstRejected = (await Promise.allSettled(tasks)).find((result) => result.status === "rejected");
+				if (firstRejected?.status === "rejected" && delegates.length === 1 && (options.onChildFailure === "abort" || dispatchResults.length === 0)) throw firstRejected.reason;
+				dispatchResults.sort((a, b) => a.result.completedAtMs - b.result.completedAtMs);
+				const taggedResults = dispatchResults.map((entry) => entry.result.taggedText).join("\n\n");
+				const currentWaveFailures = dispatchedForTurn.map((child) => child.failure).filter((failure) => failure !== void 0);
+				if (options.onChildFailure === "abort" && currentWaveFailures.length > 0) {
+					triggeringFailureForAbortMode ??= currentWaveFailures[0];
+					break;
+				}
+				const failuresSection = buildFailuresSection(currentWaveFailures);
+				const coordinatorAgent = options.agents[0] ?? {
+					id: "coordinator",
+					role: "coordinator"
+				};
+				dispatchInput = [
+					buildCoordinatorPlanInput(options.intent, coordinatorAgent),
+					taggedResults,
+					failuresSection,
+					"Using the sub-run results above, decide the next step (participate or delegate)."
+				].filter((section) => Boolean(section)).join("\n\n");
+				dispatchCount += delegates.length;
+			}
 			stopIfNeeded();
 		}
 		if (!stopIfNeeded()) {
@@ -2741,7 +3599,7 @@ async function runCoordinator(options) {
 			stopIfNeeded();
 		}
 		if (!stopIfNeeded()) {
-			totalCost = await runCoordinatorTurn({
+			const synthesisOutcome = await runCoordinatorTurn({
 				agent: coordinator,
 				coordinator,
 				input: buildFinalSynthesisInput(options.intent, transcript, coordinator),
@@ -2759,6 +3617,17 @@ async function runCoordinator(options) {
 				emit,
 				recordProtocolDecision
 			});
+			totalCost = synthesisOutcome.totalCost;
+			if (Array.isArray(synthesisOutcome.decision) || synthesisOutcome.decision?.type === "delegate") throw new DogpileError({
+				code: "invalid-configuration",
+				message: "Coordinator final-synthesis turn cannot emit a delegate decision in Phase 1",
+				retryable: false,
+				detail: {
+					kind: "delegate-validation",
+					path: "decision",
+					phase: "final-synthesis"
+				}
+			});
 			stopIfNeeded();
 		}
 	}
@@ -2811,6 +3680,7 @@ async function runCoordinator(options) {
 				cost: totalCost,
 				transcript: createTranscriptLink(transcript)
 			}),
+			...triggeringFailureForAbortMode !== void 0 ? { triggeringFailureForAbortMode } : {},
 			events,
 			transcript
 		},
@@ -2868,6 +3738,9 @@ async function runCoordinator(options) {
 		recordProtocolDecision(event, { transcriptEntryCount: transcript.length });
 	}
 }
+function isDelegateValidationError(error) {
+	return DogpileError.isInstance(error) && error.code === "invalid-configuration" && error.detail?.["kind"] === "delegate-validation";
+}
 async function runCoordinatorTurn(turn) {
 	throwIfAborted(turn.options.signal, turn.options.model.id);
 	const request = {
@@ -2911,7 +3784,11 @@ async function runCoordinatorTurn(turn) {
 			turn.providerCalls.push(call);
 		}
 	});
-	const decision = parseAgentDecision(response.text);
+	const decision = parseAgentDecision(response.text, {
+		parentProviderId: turn.options.model.id,
+		currentDepth: turn.options.currentDepth ?? 0,
+		maxDepth: turn.options.effectiveMaxDepth ?? Number.POSITIVE_INFINITY
+	});
 	const totalCost = addCost(turn.totalCost, responseCost$2(response));
 	const toolCalls = await executeModelResponseToolRequests({
 		response,
@@ -2947,7 +3824,10 @@ async function runCoordinatorTurn(turn) {
 		phase: turn.phase,
 		transcriptEntryCount: turn.transcript.length
 	});
-	return totalCost;
+	return {
+		totalCost,
+		decision
+	};
 }
 async function runCoordinatorWorkerTurn(turn) {
 	throwIfAborted(turn.options.signal, turn.options.model.id);
@@ -2992,7 +3872,21 @@ async function runCoordinatorWorkerTurn(turn) {
 			turn.providerCallSlots[turn.providerCallIndex] = call;
 		}
 	});
-	const decision = parseAgentDecision(response.text);
+	const decision = parseAgentDecision(response.text, {
+		parentProviderId: turn.options.model.id,
+		currentDepth: turn.options.currentDepth ?? 0,
+		maxDepth: turn.options.effectiveMaxDepth ?? Number.POSITIVE_INFINITY
+	});
+	if (Array.isArray(decision) || decision?.type === "delegate") throw new DogpileError({
+		code: "invalid-configuration",
+		message: "Workers cannot emit delegate decisions in Phase 1",
+		retryable: false,
+		detail: {
+			kind: "delegate-validation",
+			path: "decision",
+			phase: "worker"
+		}
+	});
 	const toolCalls = await executeModelResponseToolRequests({
 		response,
 		executor: turn.toolExecutor,
@@ -3019,6 +3913,30 @@ function buildSystemPrompt$2(agent, coordinator) {
 function buildCoordinatorPlanInput(intent, coordinator) {
 	return `Mission: ${intent}\nCoordinator ${coordinator.id}: assign the work, name the plan, and provide the first contribution.`;
 }
+function buildFailuresSection(failures) {
+	if (failures.length === 0) return null;
+	return [
+		"## Sub-run failures since last decision",
+		"",
+		"```json",
+		JSON.stringify(failures, null, 2),
+		"```"
+	].join("\n");
+}
+function dispatchWaveFailureFromEvent(intent, event) {
+	const reason = typeof event.error.detail?.["reason"] === "string" ? event.error.detail["reason"] : void 0;
+	if (reason === "sibling-failed" || reason === "parent-aborted") return;
+	return {
+		childRunId: event.childRunId,
+		intent,
+		error: {
+			code: event.error.code,
+			message: event.error.message,
+			...reason !== void 0 ? { detail: { reason } } : {}
+		},
+		partialCost: { usd: event.partialCost.usd }
+	};
+}
 function buildWorkerInput(intent, transcript, coordinator) {
 	const prior = transcript.map((entry) => `${entry.role} (${entry.agentId}): ${entry.output}`).join("\n\n");
 	return `Mission: ${intent}\n\nCoordinator: ${coordinator.id}\nPrior contributions:\n${prior}\n\nFollow the coordinator-managed plan and provide your assigned contribution.`;
@@ -3035,6 +3953,382 @@ function responseCost$2(response) {
 		totalTokens: response.usage?.totalTokens ?? 0
 	};
 }
+/**
+* Dispatch a single delegate decision as a recursive sub-run.
+*
+* D-11: child reuses the parent provider object verbatim.
+* D-16: `recursive: true` flag set when both parent and child protocol are
+*   `coordinator`.
+* D-17: tagged result text appended to the next coordinator prompt.
+* D-18: synthetic transcript entry pushed for replay/provenance.
+*
+* On thrown error from the child engine, builds `partialTrace` from a locally
+* tee'd `childEvents` buffer — `runProtocol`'s error contract is unchanged.
+*/
+async function dispatchDelegate(input) {
+	const { decision, options } = input;
+	if (options.effectiveMaxDepth !== void 0) assertDepthWithinLimit(input.parentDepth, options.effectiveMaxDepth);
+	const childRunId = input.childRunId ?? createRunId();
+	const recursive = decision.protocol === "coordinator";
+	const decisionTimeoutMs = decision.budget?.timeoutMs;
+	const parentDeadlineMs = options.parentDeadlineMs;
+	const remainingMs = parentDeadlineMs !== void 0 ? Math.max(0, parentDeadlineMs - Date.now()) : void 0;
+	if (parentDeadlineMs !== void 0 && remainingMs === 0) throw new DogpileError({
+		code: "aborted",
+		message: "Parent deadline elapsed before sub-run dispatch.",
+		retryable: false,
+		providerId: options.model.id,
+		detail: { reason: "timeout" }
+	});
+	let childTimeoutMs;
+	let clampedFrom;
+	if (remainingMs !== void 0) if (decisionTimeoutMs !== void 0) if (decisionTimeoutMs > remainingMs) {
+		clampedFrom = decisionTimeoutMs;
+		childTimeoutMs = remainingMs;
+	} else childTimeoutMs = decisionTimeoutMs;
+	else childTimeoutMs = remainingMs;
+	else if (decisionTimeoutMs !== void 0) childTimeoutMs = decisionTimeoutMs;
+	else if (options.defaultSubRunTimeoutMs !== void 0) childTimeoutMs = options.defaultSubRunTimeoutMs;
+	if (!options.runProtocol) throw new DogpileError({
+		code: "invalid-configuration",
+		message: "Coordinator delegate dispatch requires the engine `runProtocol` callback. Use `Dogpile.run` / `createEngine` rather than calling `runCoordinator` directly when delegate is in play.",
+		retryable: false,
+		detail: {
+			kind: "delegate-validation",
+			path: "runProtocol"
+		}
+	});
+	const childEvents = input.dispatchedChild.childEvents;
+	const parentEmit = input.emit;
+	const teedEmit = (event) => {
+		childEvents.push(event);
+		if (input.dispatchedChild.closed) return;
+		if (options.streamEvents && options.emit) {
+			const inbound = event.parentRunIds;
+			options.emit({
+				...event,
+				parentRunIds: [input.parentRunId, ...inbound ?? []]
+			});
+		}
+	};
+	const childStartedAt = Date.now();
+	input.dispatchedChild.startedAtMs = childStartedAt;
+	if (clampedFrom !== void 0 && childTimeoutMs !== void 0) {
+		const clampEvent = {
+			type: "sub-run-budget-clamped",
+			runId: input.parentRunId,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			childRunId,
+			parentRunId: input.parentRunId,
+			parentDecisionId: input.parentDecisionId,
+			requestedTimeoutMs: clampedFrom,
+			clampedTimeoutMs: childTimeoutMs,
+			reason: "exceeded-parent-remaining"
+		};
+		input.emit(clampEvent);
+		input.recordProtocolDecision(clampEvent);
+	}
+	const startEvent = {
+		type: "sub-run-started",
+		runId: input.parentRunId,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		childRunId,
+		parentRunId: input.parentRunId,
+		parentDecisionId: input.parentDecisionId,
+		parentDecisionArrayIndex: input.parentDecisionArrayIndex,
+		protocol: decision.protocol,
+		intent: decision.intent,
+		depth: input.parentDepth + 1,
+		...recursive ? { recursive: true } : {}
+	};
+	parentEmit(startEvent);
+	input.recordProtocolDecision(startEvent);
+	const parentSignal = options.signal;
+	let removeParentAbortListener;
+	if (parentSignal !== void 0) if (parentSignal.aborted) input.dispatchedChild.controller.abort(parentSignal.reason);
+	else {
+		const handler = () => {
+			input.dispatchedChild.controller.abort(parentSignal.reason);
+		};
+		parentSignal.addEventListener("abort", handler, { once: true });
+		removeParentAbortListener = () => {
+			parentSignal.removeEventListener("abort", handler);
+		};
+	}
+	input.dispatchedChild.removeParentListener = removeParentAbortListener;
+	input.dispatchedChild.started = true;
+	input.dispatchedChild.childTimeoutMs = childTimeoutMs;
+	const childDeadlineReason = childTimeoutMs !== void 0 && parentDeadlineMs === void 0 ? createEngineDeadlineTimeoutError(options.model.id, childTimeoutMs) : void 0;
+	const childDeadlineTimer = childDeadlineReason !== void 0 ? setTimeout(() => {
+		input.dispatchedChild.controller.abort(childDeadlineReason);
+	}, childTimeoutMs) : void 0;
+	const childOptions = {
+		intent: decision.intent,
+		protocol: decision.protocol,
+		tier: options.tier,
+		model: options.model,
+		agents: options.agents,
+		tools: options.tools,
+		temperature: options.temperature,
+		...childTimeoutMs !== void 0 ? { budget: { timeoutMs: childTimeoutMs } } : {},
+		signal: input.dispatchedChild.controller.signal,
+		emit: teedEmit,
+		...options.streamEvents !== void 0 ? { streamEvents: options.streamEvents } : {},
+		currentDepth: input.parentDepth + 1,
+		...options.effectiveMaxDepth !== void 0 ? { effectiveMaxDepth: options.effectiveMaxDepth } : {},
+		...options.effectiveMaxConcurrentChildren !== void 0 ? { effectiveMaxConcurrentChildren: options.effectiveMaxConcurrentChildren } : {},
+		...options.onChildFailure !== void 0 ? { onChildFailure: options.onChildFailure } : {},
+		...parentDeadlineMs !== void 0 ? { parentDeadlineMs } : {},
+		...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {}
+	};
+	let subResult;
+	try {
+		subResult = await options.runProtocol(childOptions);
+	} catch (error) {
+		if (childDeadlineTimer !== void 0) clearTimeout(childDeadlineTimer);
+		removeParentAbortListener?.();
+		if (input.dispatchedChild.closed) {
+			const enrichedError = enrichAbortErrorWithParentReason(error, parentSignal);
+			if (DogpileError.isInstance(enrichedError)) throw enrichedError;
+			throw error;
+		}
+		const failedDecision = {
+			type: "delegate",
+			protocol: decision.protocol,
+			intent: decision.intent,
+			...decision.model !== void 0 ? { model: decision.model } : {},
+			...decision.budget !== void 0 ? { budget: decision.budget } : {}
+		};
+		const partialTrace = buildPartialTrace({
+			childRunId,
+			events: childEvents,
+			startedAtMs: childStartedAt,
+			protocol: decision.protocol,
+			tier: options.tier,
+			modelProviderId: options.model.id,
+			agents: options.agents,
+			intent: decision.intent,
+			temperature: options.temperature,
+			...childTimeoutMs !== void 0 ? { childTimeoutMs } : {},
+			...options.seed !== void 0 ? { seed: options.seed } : {}
+		});
+		const enrichedError = enrichProviderTimeoutSource(enrichAbortErrorWithParentReason(error, parentSignal), {
+			...decisionTimeoutMs !== void 0 ? { decisionTimeoutMs } : {},
+			...options.defaultSubRunTimeoutMs !== void 0 ? { engineDefaultTimeoutMs: options.defaultSubRunTimeoutMs } : {}
+		});
+		if (DogpileError.isInstance(enrichedError)) options.failureInstancesByChildRunId?.set(childRunId, enrichedError);
+		const errorPayload = errorPayloadFromUnknown(enrichedError, failedDecision);
+		const partialCost = lastCostBearingEventCost(childEvents) ?? emptyCost();
+		input.recordSubRunCost(partialCost);
+		const failEvent = {
+			type: "sub-run-failed",
+			runId: input.parentRunId,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			childRunId,
+			parentRunId: input.parentRunId,
+			parentDecisionId: input.parentDecisionId,
+			parentDecisionArrayIndex: input.parentDecisionArrayIndex,
+			error: errorPayload,
+			partialTrace,
+			partialCost
+		};
+		parentEmit(failEvent);
+		input.recordProtocolDecision(failEvent);
+		input.dispatchedChild.closed = true;
+		input.dispatchedChild.failure = dispatchWaveFailureFromEvent(decision.intent, failEvent);
+		if (DogpileError.isInstance(enrichedError)) throw enrichedError;
+		throw new DogpileError({
+			code: "invalid-configuration",
+			message: error instanceof Error ? error.message : String(error),
+			retryable: false,
+			detail: {
+				kind: "delegate-validation",
+				path: "decision",
+				reason: "child-run-failed"
+			}
+		});
+	}
+	if (childDeadlineTimer !== void 0) clearTimeout(childDeadlineTimer);
+	removeParentAbortListener?.();
+	input.recordSubRunCost(subResult.cost);
+	const completedEvent = {
+		type: "sub-run-completed",
+		runId: input.parentRunId,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		childRunId,
+		parentRunId: input.parentRunId,
+		parentDecisionId: input.parentDecisionId,
+		parentDecisionArrayIndex: input.parentDecisionArrayIndex,
+		subResult
+	};
+	parentEmit(completedEvent);
+	input.recordProtocolDecision(completedEvent);
+	input.dispatchedChild.closed = true;
+	if (parentSignal?.aborted) {
+		const abortMarker = {
+			type: "sub-run-parent-aborted",
+			runId: input.parentRunId,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			childRunId,
+			parentRunId: input.parentRunId,
+			reason: "parent-aborted"
+		};
+		parentEmit(abortMarker);
+		input.recordProtocolDecision(abortMarker);
+		throw enrichAbortErrorWithParentReason(createAbortErrorFromSignal(parentSignal, options.model.id), parentSignal);
+	}
+	const decisionAsJson = {
+		type: "delegate",
+		protocol: decision.protocol,
+		intent: decision.intent,
+		...decision.model !== void 0 ? { model: decision.model } : {},
+		...decision.budget !== void 0 ? { budget: decision.budget } : {}
+	};
+	const taggedText = renderSubRunResult(childRunId, subResult);
+	input.transcript.push({
+		agentId: `sub-run:${childRunId}`,
+		role: "delegate-result",
+		input: JSON.stringify(decisionAsJson),
+		output: taggedText
+	});
+	const coordinatorAgent = options.agents[0];
+	return {
+		nextInput: `${buildCoordinatorPlanInput(input.options.intent, coordinatorAgent ?? {
+			id: "coordinator",
+			role: "coordinator"
+		})}\n\n${taggedText}\n\nUsing the sub-run result above, decide the next step (participate or delegate).`,
+		taggedText,
+		completedAtMs: Date.now()
+	};
+}
+/**
+* D-17 prompt-injection helper. Renders a child `RunResult` as the canonical
+* tagged-result block injected into the parent coordinator's next prompt.
+*
+* Format:
+*   `[sub-run <childRunId>]: <output>`
+*   `[sub-run <childRunId> stats]: turns=<N> costUsd=<X> durationMs=<Y>`
+*
+* The stats line is a soft contract — field names stable, ordering stable.
+*/
+function renderSubRunResult(childRunId, subResult) {
+	const turns = subResult.transcript.length;
+	const costUsd = subResult.cost.usd ?? 0;
+	const startedAt = subResult.trace.events[0]?.at;
+	const endedAt = subResult.trace.events.at(-1)?.at;
+	const durationMs = startedAt && endedAt ? Math.max(0, Date.parse(endedAt) - Date.parse(startedAt)) : 0;
+	return [`[sub-run ${childRunId}]: ${subResult.output}`, `[sub-run ${childRunId} stats]: turns=${turns} costUsd=${costUsd} durationMs=${durationMs}`].join("\n");
+}
+/**
+* Build a JSON-serializable {@link Trace} for `sub-run-failed.partialTrace`
+* from a buffered tee of child emits. Keeps `runProtocol`'s error contract
+* unchanged — Plan 03 step 8.
+*/
+function buildPartialTrace(input) {
+	const protocolName = typeof input.protocol === "string" ? input.protocol : input.protocol.kind;
+	const protocolConfig = typeof input.protocol === "string" ? { kind: input.protocol } : input.protocol;
+	return {
+		schemaVersion: "1.0",
+		runId: input.childRunId,
+		protocol: protocolName,
+		tier: input.tier,
+		modelProviderId: input.modelProviderId,
+		agentsUsed: input.agents,
+		inputs: createReplayTraceRunInputs({
+			intent: input.intent,
+			protocol: protocolConfig,
+			tier: input.tier,
+			modelProviderId: input.modelProviderId,
+			agents: input.agents,
+			temperature: input.temperature
+		}),
+		budget: createReplayTraceBudget({
+			tier: input.tier,
+			...input.childTimeoutMs !== void 0 ? { caps: { timeoutMs: input.childTimeoutMs } } : {}
+		}),
+		budgetStateChanges: createReplayTraceBudgetStateChanges(input.events),
+		seed: createReplayTraceSeed(input.seed),
+		protocolDecisions: [],
+		providerCalls: [],
+		finalOutput: {
+			kind: "replay-trace-final-output",
+			output: "",
+			cost: emptyCost(),
+			completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			transcript: createTranscriptLink([])
+		},
+		events: input.events,
+		transcript: []
+	};
+}
+/**
+* BUDGET-01 / D-08: when a child sub-run threw because the parent's signal
+* aborted, lock the `detail.reason` discriminator on the resulting
+* `code: "aborted"` error. Preserves any pre-existing detail keys (e.g.,
+* `detail.status: "cancelled"` attached by `createStreamCancellationError`).
+*
+* No-op when:
+*   - parent.signal is undefined or not aborted (child failure was unrelated)
+*   - error is not a DogpileError with `code: "aborted"`
+*   - error already has a `detail.reason` set (preserve upstream classification)
+*/
+function enrichAbortErrorWithParentReason(error, parentSignal) {
+	if (parentSignal === void 0 || !parentSignal.aborted) return error;
+	if (!DogpileError.isInstance(error) || error.code !== "aborted") return error;
+	const existingDetail = error.detail ?? {};
+	if (existingDetail["reason"] !== void 0) return error;
+	const reason = classifyAbortReason(parentSignal.reason);
+	return new DogpileError({
+		code: "aborted",
+		message: error.message,
+		retryable: error.retryable ?? false,
+		...error.providerId !== void 0 ? { providerId: error.providerId } : {},
+		detail: {
+			...existingDetail,
+			reason
+		},
+		...error.cause !== void 0 ? { cause: error.cause } : {}
+	});
+}
+function enrichProviderTimeoutSource(error, context) {
+	if (!DogpileError.isInstance(error) || error.code !== "provider-timeout") return error;
+	const existingDetail = error.detail ?? {};
+	if (existingDetail["source"] !== void 0) return error;
+	const source = classifyChildTimeoutSource(error, {
+		...context,
+		isProviderError: true
+	});
+	return new DogpileError({
+		code: "provider-timeout",
+		message: error.message,
+		retryable: error.retryable ?? true,
+		...error.providerId !== void 0 ? { providerId: error.providerId } : {},
+		detail: {
+			...existingDetail,
+			source
+		},
+		...error.cause !== void 0 ? { cause: error.cause } : {}
+	});
+}
+function errorPayloadFromUnknown(error, failedDecision) {
+	if (DogpileError.isInstance(error)) {
+		const detail = {
+			...error.detail ?? {},
+			failedDecision
+		};
+		return {
+			code: error.code,
+			message: error.message,
+			...error.providerId !== void 0 ? { providerId: error.providerId } : {},
+			detail
+		};
+	}
+	return {
+		code: "invalid-configuration",
+		message: error instanceof Error ? error.message : String(error),
+		detail: { failedDecision }
+	};
+}
 //#endregion
 //#region src/runtime/sequential.ts
 async function runSequential(options) {
@@ -3173,7 +4467,8 @@ async function runSequential(options) {
 		});
 		if (stopIfNeeded()) break;
 	}
-	const output = [...transcript].reverse().find((entry) => isParticipatingDecision(entry.decision))?.output ?? "";
+	const reversed = [...transcript].reverse();
+	const output = reversed.find((entry) => isParticipatingDecision(entry.decision))?.output ?? reversed.find((entry) => entry.decision === void 0)?.output ?? "";
 	throwIfAborted(options.signal, options.model.id);
 	const final = {
 		type: "final",
@@ -3573,6 +4868,8 @@ function responseCost(response) {
 }
 //#endregion
 //#region src/runtime/engine.ts
+var DEFAULT_MAX_DEPTH = 4;
+var DEFAULT_MAX_CONCURRENT_CHILDREN = 4;
 var defaultHighLevelProtocol = "sequential";
 var defaultHighLevelTier = "balanced";
 /**
@@ -3593,9 +4890,20 @@ function createEngine(options) {
 	const temperature = options.temperature ?? tierTemperature(options.tier);
 	const agents = orderAgentsForTemperature(options.agents ?? defaultAgents(), temperature, options.seed);
 	const terminate = options.terminate ?? (options.budget ? conditionFromBudget(options.budget) : void 0);
+	const engineMaxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+	const engineMaxConcurrentChildren = options.maxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN;
+	const engineOnChildFailure = options.onChildFailure;
 	return {
-		run(intent) {
+		run(intent, runOptions) {
 			validateMissionIntent(intent);
+			validateRunCallOptions(runOptions);
+			validateProviderLocality(options.model, "model");
+			const effectiveMaxDepth = Math.min(engineMaxDepth, runOptions?.maxDepth ?? Number.POSITIVE_INFINITY);
+			assertRunDoesNotRaiseEngineMax("maxConcurrentChildren", runOptions?.maxConcurrentChildren, engineMaxConcurrentChildren);
+			const effectiveMaxConcurrentChildren = Math.min(engineMaxConcurrentChildren, runOptions?.maxConcurrentChildren ?? Number.POSITIVE_INFINITY);
+			const onChildFailure = resolveOnChildFailure(runOptions?.onChildFailure, engineOnChildFailure);
+			const startedAtMs = Date.now();
+			const parentDeadlineMs = options.budget?.timeoutMs !== void 0 ? startedAtMs + options.budget.timeoutMs : void 0;
 			return runNonStreamingProtocol({
 				intent,
 				protocol,
@@ -3609,11 +4917,23 @@ function createEngine(options) {
 				...options.signal !== void 0 ? { signal: options.signal } : {},
 				...terminate ? { terminate } : {},
 				...options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {},
-				...options.evaluate ? { evaluate: options.evaluate } : {}
+				...options.evaluate ? { evaluate: options.evaluate } : {},
+				currentDepth: 0,
+				effectiveMaxDepth,
+				effectiveMaxConcurrentChildren,
+				onChildFailure,
+				...parentDeadlineMs !== void 0 ? { parentDeadlineMs } : {},
+				...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {}
 			});
 		},
-		stream(intent) {
+		stream(intent, runOptions) {
 			validateMissionIntent(intent);
+			validateRunCallOptions(runOptions);
+			validateProviderLocality(options.model, "model");
+			const effectiveMaxDepth = Math.min(engineMaxDepth, runOptions?.maxDepth ?? Number.POSITIVE_INFINITY);
+			assertRunDoesNotRaiseEngineMax("maxConcurrentChildren", runOptions?.maxConcurrentChildren, engineMaxConcurrentChildren);
+			const effectiveMaxConcurrentChildren = Math.min(engineMaxConcurrentChildren, runOptions?.maxConcurrentChildren ?? Number.POSITIVE_INFINITY);
+			const onChildFailure = resolveOnChildFailure(runOptions?.onChildFailure, engineOnChildFailure);
 			const pendingEvents = [];
 			const pendingResolvers = [];
 			const emittedEvents = [];
@@ -3630,7 +4950,10 @@ function createEngine(options) {
 			const abortRace = createAbortRace(abortController.signal, options.model.id);
 			let complete = false;
 			let lastRunId = "";
+			let rootRunId;
 			let pendingFinalEvent;
+			let activeAbortDrain;
+			const failureInstancesByChildRunId = /* @__PURE__ */ new Map();
 			let status = "running";
 			let resolveResult;
 			let rejectResult;
@@ -3676,6 +4999,8 @@ function createEngine(options) {
 			async function execute() {
 				if (status !== "running") return;
 				try {
+					const streamStartedAtMs = Date.now();
+					const streamParentDeadlineMs = options.budget?.timeoutMs !== void 0 ? streamStartedAtMs + options.budget.timeoutMs : void 0;
 					const baseResult = await abortRace.run(runProtocol({
 						intent,
 						protocol,
@@ -3688,17 +5013,32 @@ function createEngine(options) {
 						...options.seed !== void 0 ? { seed: options.seed } : {},
 						signal: abortController.signal,
 						...terminate ? { terminate } : {},
+						currentDepth: 0,
+						effectiveMaxDepth,
+						effectiveMaxConcurrentChildren,
+						onChildFailure,
+						...streamParentDeadlineMs !== void 0 ? { parentDeadlineMs: streamParentDeadlineMs } : {},
+						...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {},
+						streamEvents: true,
 						emit(event) {
 							if (status !== "running") return;
+							const parentRunIds = event.parentRunIds;
+							if (rootRunId === void 0 && parentRunIds === void 0) rootRunId = event.runId;
 							lastRunId = event.runId;
-							if (event.type === "final") {
+							if (event.type === "final" && event.runId === rootRunId) {
 								pendingFinalEvent = event;
 								return;
 							}
 							publish(event);
-						}
+						},
+						registerAbortDrain(drain) {
+							activeAbortDrain = drain;
+						},
+						failureInstancesByChildRunId
 					}));
 					if (status !== "running") return;
+					const terminalThrow = resolveRuntimeTerminalThrow(baseResult.trace, failureInstancesByChildRunId);
+					if (terminalThrow) throw terminalThrow;
 					const finalizedResult = await abortRace.run(applyRunEvaluation(baseResult, options.evaluate));
 					if (status !== "running") return;
 					const finalEvent = finalizedResult.trace.events.at(-1);
@@ -3711,6 +5051,10 @@ function createEngine(options) {
 					if (isStreamHandleStatus(status, "cancelled")) return;
 					const runtimeError = timeoutLifecycle.translateError(error);
 					status = isCancellationError(runtimeError) ? "cancelled" : "failed";
+					if (shouldPublishAborted(runtimeError)) {
+						activeAbortDrain?.(runtimeError);
+						publish(createStreamAbortedEvent(runtimeError, lastRunId));
+					}
 					publish(createStreamErrorEvent(runtimeError, lastRunId));
 					closeStream();
 					rejectResult(runtimeError);
@@ -3719,15 +5063,18 @@ function createEngine(options) {
 			function cancelRun(cause) {
 				if (status !== "running") return;
 				const error = createStreamCancellationError(options.model.id, cause);
-				status = "cancelled";
 				abortController.abort(error);
+				activeAbortDrain?.(error);
+				publish(createStreamAbortedEvent(error, lastRunId));
 				publish(createStreamErrorEvent(error, lastRunId));
+				status = "cancelled";
 				closeStream();
 				rejectResult(error);
 			}
 			function closeStream() {
 				if (complete) return;
 				complete = true;
+				failureInstancesByChildRunId.clear();
 				removeCallerAbortListener();
 				timeoutLifecycle.cleanup();
 				abortRace.cleanup();
@@ -3783,7 +5130,8 @@ function createNonStreamingAbortLifecycle(options) {
 	const timeoutLifecycle = createTimeoutAbortLifecycle({
 		abortController,
 		timeoutMs: options.timeoutMs,
-		providerId: options.providerId
+		providerId: options.providerId,
+		timeoutErrorSource: options.timeoutErrorSource ?? "runtime"
 	});
 	const abortRace = createAbortRace(abortController.signal, options.providerId);
 	const removeCallerAbortListener = wireCallerAbortSignal(options.callerSignal, abortController, () => {
@@ -3811,7 +5159,11 @@ function createTimeoutAbortLifecycle(options) {
 		},
 		cleanup() {}
 	};
-	const timeoutError = createTimeoutError(options.providerId, options.timeoutMs);
+	const timeoutSource = classifyChildTimeoutSource(void 0, {
+		...options.timeoutErrorSource === "engine" ? { engineDefaultTimeoutMs: options.timeoutMs } : {},
+		isProviderError: false
+	});
+	const timeoutError = options.timeoutErrorSource === "engine" && timeoutSource === "engine" ? createEngineDeadlineTimeoutError(options.providerId, options.timeoutMs) : createTimeoutError(options.providerId, options.timeoutMs);
 	const timeoutId = setTimeout(() => {
 		options.abortController.abort(timeoutError);
 	}, options.timeoutMs);
@@ -3879,6 +5231,23 @@ function timeoutMsFromTermination(condition) {
 function readAbortSignalReason(signal) {
 	return signal?.aborted ? signal.reason : void 0;
 }
+function createStreamAbortedEvent(error, runId) {
+	return {
+		type: "aborted",
+		runId,
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		reason: streamAbortedReason(error)
+	};
+}
+function shouldPublishAborted(error) {
+	return DogpileError.isInstance(error) && (error.code === "aborted" || error.code === "timeout");
+}
+function streamAbortedReason(error) {
+	if (DogpileError.isInstance(error)) {
+		if (error.code === "timeout" || error.detail?.["reason"] === "timeout") return "timeout";
+	}
+	return "parent-aborted";
+}
 function createStreamErrorEvent(error, runId) {
 	if (DogpileError.isInstance(error)) return {
 		type: "error",
@@ -3911,10 +5280,12 @@ function dogpileErrorStreamDetail(error) {
 	return detail;
 }
 async function runNonStreamingProtocol(options) {
+	const failureInstancesByChildRunId = /* @__PURE__ */ new Map();
 	const abortLifecycle = createNonStreamingAbortLifecycle({
 		callerSignal: options.signal,
 		timeoutMs: runtimeTimeoutMs(options),
-		providerId: options.model.id
+		providerId: options.model.id,
+		timeoutErrorSource: options.currentDepth !== void 0 && options.currentDepth > 0 && options.parentDeadlineMs === void 0 ? "engine" : "runtime"
 	});
 	try {
 		const emittedEvents = [];
@@ -3923,7 +5294,8 @@ async function runNonStreamingProtocol(options) {
 			...abortLifecycle.signal !== void 0 ? { signal: abortLifecycle.signal } : {},
 			emit(event) {
 				emittedEvents.push(event);
-			}
+			},
+			failureInstancesByChildRunId
 		}));
 		const events = emittedEvents.length > 0 ? emittedEvents : result.trace.events;
 		const trace = {
@@ -3944,10 +5316,13 @@ async function runNonStreamingProtocol(options) {
 			eventLog: createRunEventLog(trace.runId, trace.protocol, events),
 			trace
 		};
+		const terminalThrow = resolveRuntimeTerminalThrow(runResult.trace, failureInstancesByChildRunId);
+		if (terminalThrow) throw terminalThrow;
 		return canonicalizeRunResult(await abortLifecycle.run(applyRunEvaluation(runResult, options.evaluate)));
 	} catch (error) {
 		throw abortLifecycle.translateError(error);
 	} finally {
+		failureInstancesByChildRunId.clear();
 		abortLifecycle.cleanup();
 	}
 }
@@ -4022,7 +5397,20 @@ function runProtocol(options) {
 			...options.signal !== void 0 ? { signal: options.signal } : {},
 			...options.terminate ? { terminate: options.terminate } : {},
 			...options.wrapUpHint ? { wrapUpHint: options.wrapUpHint } : {},
-			...options.emit ? { emit: options.emit } : {}
+			...options.emit ? { emit: options.emit } : {},
+			...options.streamEvents !== void 0 ? { streamEvents: options.streamEvents } : {},
+			currentDepth: options.currentDepth ?? 0,
+			effectiveMaxDepth: options.effectiveMaxDepth ?? Infinity,
+			effectiveMaxConcurrentChildren: options.effectiveMaxConcurrentChildren ?? DEFAULT_MAX_CONCURRENT_CHILDREN,
+			onChildFailure: options.onChildFailure ?? "continue",
+			...options.parentDeadlineMs !== void 0 ? { parentDeadlineMs: options.parentDeadlineMs } : {},
+			...options.defaultSubRunTimeoutMs !== void 0 ? { defaultSubRunTimeoutMs: options.defaultSubRunTimeoutMs } : {},
+			...options.registerAbortDrain !== void 0 ? { registerAbortDrain: options.registerAbortDrain } : {},
+			...options.failureInstancesByChildRunId !== void 0 ? { failureInstancesByChildRunId: options.failureInstancesByChildRunId } : {},
+			runProtocol: (childInput) => runProtocol({
+				...childInput,
+				protocol: normalizeProtocol(childInput.protocol)
+			})
 		});
 		case "shared": return runShared({
 			intent: options.intent,
@@ -4089,6 +5477,9 @@ function stream(options) {
 function replay(trace) {
 	const cost = trace.finalOutput.cost;
 	const lastEvent = trace.events.at(-1);
+	const accounting = recomputeAccountingFromTrace(trace);
+	const replayThrow = resolveReplayTerminalThrow(trace);
+	if (replayThrow) throw replayThrow;
 	const baseResult = {
 		output: trace.finalOutput.output,
 		eventLog: createRunEventLog(trace.runId, trace.protocol, trace.events),
@@ -4103,13 +5494,7 @@ function replay(trace) {
 			agentsUsed: trace.agentsUsed,
 			events: trace.events
 		}),
-		accounting: createRunAccounting({
-			tier: trace.tier,
-			...trace.budget.caps ? { budget: trace.budget.caps } : {},
-			...trace.budget.termination ? { termination: trace.budget.termination } : {},
-			cost,
-			events: trace.events
-		}),
+		accounting,
 		cost
 	};
 	if (lastEvent?.type !== "final") return baseResult;
@@ -4119,6 +5504,64 @@ function replay(trace) {
 		...lastEvent.evaluation !== void 0 ? { evaluation: lastEvent.evaluation } : {}
 	};
 }
+function resolveRuntimeTerminalThrow(trace, failureInstancesByChildRunId) {
+	if (trace.triggeringFailureForAbortMode !== void 0) return failureInstancesByChildRunId.get(trace.triggeringFailureForAbortMode.childRunId) ?? null;
+	const finalEvent = trace.events.at(-1);
+	if (finalEvent?.type !== "final" || finalEvent.termination === void 0) return null;
+	const lastFailure = findLastRealFailure(trace.events, failureInstancesByChildRunId);
+	if (lastFailure === null) return null;
+	if (hasFinalSynthesisAfterEvent(trace, lastFailure.eventIndex)) return null;
+	return lastFailure.error;
+}
+function findLastRealFailure(events, failureInstancesByChildRunId) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event?.type !== "sub-run-failed") continue;
+		const instance = failureInstancesByChildRunId.get(event.childRunId);
+		if (instance) return {
+			error: instance,
+			eventIndex: index
+		};
+	}
+	return null;
+}
+function resolveReplayTerminalThrow(trace) {
+	if (trace.triggeringFailureForAbortMode !== void 0) return dogpileErrorFromSerializedPayload(trace.triggeringFailureForAbortMode.error);
+	const finalEvent = trace.events.at(-1);
+	if (finalEvent?.type !== "final" || finalEvent.termination === void 0) return null;
+	const lastFailure = reconstructLastRealFailure(trace.events);
+	if (lastFailure === null) return null;
+	if (hasFinalSynthesisAfterEvent(trace, lastFailure.eventIndex)) return null;
+	return lastFailure.error;
+}
+function reconstructLastRealFailure(events) {
+	for (let index = events.length - 1; index >= 0; index -= 1) {
+		const event = events[index];
+		if (event?.type !== "sub-run-failed" || isSyntheticSubRunFailure(event)) continue;
+		return {
+			error: dogpileErrorFromSerializedPayload(event.error),
+			eventIndex: index
+		};
+	}
+	return null;
+}
+function hasFinalSynthesisAfterEvent(trace, eventIndex) {
+	return trace.protocolDecisions.some((decision) => {
+		return decision.phase === "final-synthesis" && decision.eventIndex > eventIndex;
+	});
+}
+function isSyntheticSubRunFailure(event) {
+	const reason = event.error.detail?.["reason"];
+	return reason === "sibling-failed" || reason === "parent-aborted";
+}
+function dogpileErrorFromSerializedPayload(input) {
+	return new DogpileError({
+		code: input.code,
+		message: input.message,
+		...input.providerId !== void 0 ? { providerId: input.providerId } : {},
+		...input.detail !== void 0 ? { detail: input.detail } : {}
+	});
+}
 /**
 * Replay a saved completed trace as a stream without invoking a model provider.
 *
@@ -4129,20 +5572,22 @@ function replay(trace) {
 * replay remains storage-free and provider-free.
 */
 function replayStream(trace) {
+	const result = Promise.resolve(replay(trace));
+	const replayEvents = replayStreamEvents(trace);
 	return {
 		get status() {
 			return "completed";
 		},
-		result: Promise.resolve(replay(trace)),
+		result,
 		cancel() {},
 		subscribe(subscriber) {
-			for (const event of trace.events) subscriber(event);
+			for (const event of replayEvents) subscriber(event);
 			return { unsubscribe() {} };
 		},
 		[Symbol.asyncIterator]() {
 			let index = 0;
 			return { next() {
-				const event = trace.events[index];
+				const event = replayEvents[index];
 				if (event) {
 					index += 1;
 					return Promise.resolve({
@@ -4158,6 +5603,22 @@ function replayStream(trace) {
 		}
 	};
 }
+function replayStreamEvents(trace, parentRunIds = []) {
+	const events = [];
+	for (const event of trace.events) {
+		if (event.type === "sub-run-completed") events.push(...replayStreamEvents(event.subResult.trace, [...parentRunIds, trace.runId]));
+		events.push(wrapReplayStreamEvent(event, parentRunIds));
+	}
+	return events;
+}
+function wrapReplayStreamEvent(event, parentRunIds) {
+	if (parentRunIds.length === 0) return event;
+	const inbound = event.parentRunIds;
+	return {
+		...event,
+		parentRunIds: [...parentRunIds, ...inbound ?? []]
+	};
+}
 function wireCallerAbortSignal(callerSignal, abortController, cancelRun) {
 	if (!callerSignal) return () => {};
 	const cancelFromCaller = () => {
@@ -4181,7 +5642,10 @@ function createStreamCancellationError(providerId, cause) {
 		retryable: false,
 		providerId,
 		...cause !== void 0 ? { cause } : {},
-		detail: { status: "cancelled" }
+		detail: {
+			status: "cancelled",
+			reason: "parent-aborted"
+		}
 	});
 }
 function isCancellationError(error) {
@@ -4195,6 +5659,20 @@ function withHighLevelDefaults(options) {
 		tier: options.tier ?? defaultHighLevelTier
 	};
 }
+function assertRunDoesNotRaiseEngineMax(path, runValue, engineValue) {
+	if (runValue === void 0 || runValue <= engineValue) return;
+	throw new DogpileError({
+		code: "invalid-configuration",
+		message: `${path} cannot raise the engine ceiling (${engineValue}).`,
+		retryable: false,
+		detail: {
+			kind: "configuration-validation",
+			path,
+			expected: `integer <= ${engineValue}`,
+			actual: runValue
+		}
+	});
+}
 /**
 * Branded high-level SDK namespace.
 *
@@ -4221,6 +5699,8 @@ function createOpenAICompatibleProvider(options) {
 	validateOptions(options);
 	const providerId = options.id ?? `openai-compatible:${options.model}`;
 	const fetchImplementation = options.fetch ?? globalThis.fetch?.bind(globalThis);
+	const detectedLocality = classifyHostLocality(new URL(String(options.baseURL ?? defaultBaseURL)).hostname);
+	const resolvedLocality = options.locality === "local" ? "local" : options.locality === "remote" ? "remote" : detectedLocality;
 	if (!fetchImplementation) throw new DogpileError({
 		code: "invalid-configuration",
 		message: "createOpenAICompatibleProvider() requires a fetch implementation in this runtime.",
@@ -4234,6 +5714,7 @@ function createOpenAICompatibleProvider(options) {
 	});
 	return {
 		id: providerId,
+		metadata: { locality: resolvedLocality },
 		async generate(request) {
 			let response;
 			try {
@@ -4246,9 +5727,11 @@ function createOpenAICompatibleProvider(options) {
 			} catch (error) {
 				throw normalizeFetchError(error, providerId);
 			}
-			const payload = await readJson(response, providerId);
-			if (!response.ok) throw createProviderError(response, payload, providerId);
-			const completion = asChatCompletionResponse(payload, providerId);
+			if (!response.ok) {
+				const payload = await readJsonLenient(response);
+				throw createProviderError(response, payload, providerId);
+			}
+			const completion = asChatCompletionResponse(await readJson(response, providerId), providerId);
 			const text = readAssistantText(completion, providerId);
 			const usage = normalizeUsage(completion.usage);
 			const finishReason = normalizeFinishReason(completion.choices?.[0]?.finish_reason);
@@ -4277,6 +5760,22 @@ function validateOptions(options) {
 	if (options.fetch !== void 0 && typeof options.fetch !== "function") throwInvalid("fetch", "a fetch-compatible function when provided");
 	if (options.maxOutputTokens !== void 0 && (!Number.isInteger(options.maxOutputTokens) || options.maxOutputTokens <= 0)) throwInvalid("maxOutputTokens", "a positive integer when provided");
 	if (options.costEstimator !== void 0 && typeof options.costEstimator !== "function") throwInvalid("costEstimator", "a function when provided");
+	if (options.locality !== void 0 && options.locality !== "local" && options.locality !== "remote") throwInvalid("locality", "\"local\" | \"remote\" when provided");
+	if (options.locality === "remote") {
+		const baseURL = new URL(String(options.baseURL ?? defaultBaseURL));
+		if (classifyHostLocality(baseURL.hostname) === "local") throw new DogpileError({
+			code: "invalid-configuration",
+			message: `locality "remote" cannot be set when baseURL resolves to a local host (${baseURL.hostname}).`,
+			retryable: false,
+			detail: {
+				kind: "configuration-validation",
+				path: "locality",
+				expected: "\"local\" (or omit to auto-detect)",
+				reason: "remote-override-on-local-host",
+				host: baseURL.hostname
+			}
+		});
+	}
 }
 function throwInvalid(path, expected) {
 	throw new DogpileError({
@@ -4290,6 +5789,38 @@ function throwInvalid(path, expected) {
 		}
 	});
 }
+/**
+* Classify a URL hostname as "local" or "remote" per Phase 3 D-02.
+* Local: localhost, *.local mDNS, IPv4 loopback (127.0.0.0/8), RFC1918
+* (10/8, 172.16/12, 192.168/16), link-local (169.254/16), IPv6 loopback (::1),
+* IPv6 ULA (fc00::/7), IPv6 link-local (fe80::/10).
+*
+* Pure function: no I/O, no side effects. Exported for tests and future reuse.
+*/
+function classifyHostLocality(host) {
+	const lower = host.toLowerCase().replace(/^\[|\]$/g, "");
+	const mappedIpv4 = ipv4MappedToDottedQuad(lower);
+	if (mappedIpv4 !== void 0) return classifyHostLocality(mappedIpv4);
+	if (lower === "localhost") return "local";
+	if (lower.endsWith(".local")) return "local";
+	if (/^127(?:\.\d{1,3}){3}$/.test(lower)) return "local";
+	if (/^10(?:\.\d{1,3}){3}$/.test(lower)) return "local";
+	if (/^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+	if (/^192\.168(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+	if (/^169\.254(?:\.\d{1,3}){2}$/.test(lower)) return "local";
+	if (lower === "::1") return "local";
+	if (/^f[cd][0-9a-f]{2}:/.test(lower)) return "local";
+	if (/^fe[89ab][0-9a-f]?:/.test(lower)) return "local";
+	return "remote";
+}
+function ipv4MappedToDottedQuad(host) {
+	const match = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+	if (match === null) return;
+	const high = Number.parseInt(match[1] ?? "", 16);
+	const low = Number.parseInt(match[2] ?? "", 16);
+	if (!Number.isFinite(high) || !Number.isFinite(low)) return;
+	return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
 function createURL(options) {
 	const baseURL = new URL(String(options.baseURL ?? defaultBaseURL));
 	const path = options.path ?? defaultPath;
@@ -4339,6 +5870,13 @@ async function readJson(response, providerId) {
 		});
 	}
 }
+async function readJsonLenient(response) {
+	try {
+		return await response.json();
+	} catch {
+		return;
+	}
+}
 function asChatCompletionResponse(payload, providerId) {
 	if (!isRecord(payload)) throw new DogpileError({
 		code: "provider-invalid-response",
@@ -4409,14 +5947,17 @@ function responseMetadata(response) {
 	});
 }
 function createProviderError(response, payload, providerId) {
+	const code = codeForStatus(response.status);
+	const timeoutSource = code === "provider-timeout" ? { source: "provider" } : {};
 	return new DogpileError({
-		code: codeForStatus(response.status),
+		code,
 		message: providerResponseErrorMessage(response, payload),
 		retryable: response.status === 408 || response.status === 429 || response.status >= 500,
 		providerId,
 		detail: removeUndefined({
 			statusCode: response.status,
 			statusText: response.statusText,
+			...timeoutSource,
 			response: isJsonValue(payload) ? payload : void 0
 		})
 	});