@tangle-network/agent-runtime 0.218.1 → 0.219.0

package/dist/{supervisor-DELeLQRJ.js → supervisor-WRrw0nlk.js}

@@ -708,27 +708,10 @@ function extractLlmCallEvent(event, agentRunName) {
 	if (!event || typeof event !== "object") return void 0;
 	const type = String(event.type ?? "");
 	const data = event.data && typeof event.data === "object" ? event.data : {};
-	if (type === "llm_call" || type === "cost.usage" || type === "usage") return buildLlmCall({
-		...plainRecord$1(data.usage),
-		...data
-	}, agentRunName);
-	if (isSandboxTerminalEvent(type) && sandboxTerminalUsageField(type) === "usage") {
-		const usage = data.usage;
-		if (!usage || typeof usage !== "object") return void 0;
-		return buildLlmCall({
-			...usage,
-			model: data.model ?? usage.model,
-			...usage.costUsd === void 0 && data.costUsd !== void 0 ? { costUsd: data.costUsd } : {}
-		}, agentRunName);
-	}
-	if (type === "done") {
-		const usage = plainRecord$1(data.tokenUsage) ?? plainRecord$1(data.usage) ?? {};
-		return buildLlmCall({
-			...usage,
-			...data.totalCostUsd === void 0 ? {} : { totalCostUsd: data.totalCostUsd },
-			...data.costUsd === void 0 ? {} : { costUsd: data.costUsd },
-			model: data.model ?? usage.model
-		}, agentRunName);
+	if (type === "llm_call" || type === "cost.usage" || type === "usage") return buildLlmCall(usageReceiptData(data, plainRecord$1(data.usage)), agentRunName);
+	if (type === "error" || isSandboxTerminalEvent(type)) {
+		const field = type === "error" ? "tokenUsage" : sandboxTerminalUsageField(type);
+		return buildLlmCall(usageReceiptData(data, plainRecord$1(data[field]) ?? plainRecord$1(data[field === "usage" ? "tokenUsage" : "usage"])), agentRunName);
 	}
 }
 /** A {@link SandboxUsageLedger} for one worker. Pass the worker's harness to decode with that
@@ -774,9 +757,15 @@ function createSandboxUsageLedger(harness) {
 /** Terminal totals replace already credited usage; only per-call receipts add to it. */
 function creditCanonicalUsage(event, call, credited, receipts) {
 	const declaredMode = plainRecord$1(event.data)?.usageMode;
-	const mode = declaredMode === "delta" || declaredMode === "cumulative" ? declaredMode : declaredMode === void 0 && event.type === "llm_call" ? "delta" : declaredMode === void 0 && isSandboxTerminalEvent(String(event.type)) ? "cumulative" : void 0;
+	const mode = declaredMode === "delta" || declaredMode === "cumulative" ? declaredMode : declaredMode === void 0 && event.type === "llm_call" ? "delta" : declaredMode === void 0 && (event.type === "error" || isSandboxTerminalEvent(String(event.type))) ? "cumulative" : void 0;
 	const result = { ...call };
-	if (call.tokensIn === void 0 && call.tokensOut === void 0 && !call.tokensUnknownReason) delete result.tokensKnown;
+	const data = plainRecord$1(event.data) ?? {};
+	const explicitTokensUnknown = [
+		data,
+		plainRecord$1(data.usage),
+		plainRecord$1(data.tokenUsage)
+	].some((receipt) => ["tokensKnown", "tokens_known"].some((key) => receipt?.[key] !== void 0 && receipt[key] !== true));
+	if (call.tokensIn === void 0 && call.tokensOut === void 0 && !call.tokensUnknownReason && !explicitTokensUnknown) delete result.tokensKnown;
 	let reason = mode === void 0 ? "usage receipt has no declared delta or cumulative semantics" : void 0;
 	if (event.id) {
 		const signature = JSON.stringify({
@@ -837,8 +826,7 @@ function creditCanonicalUsage(event, call, credited, receipts) {
 *     `output_tokens` — a turn reporting `output_tokens 1523` with `reasoning_output_tokens 1516`
 *     answered with about seven tokens of text — and `parseCodexUsageRecord` holds that as an
 *     invariant. The canonical `llm_call` carries no reasoning class, so the count is not
-*     forwarded to {@link buildLlmCall}, whose `reasoningTokens` input is for the sandbox
-*     `tokenUsage` record that reports reasoning BESIDE its output count.
+*     forwarded to {@link buildLlmCall}. Canonical output totals already include reasoning.
 *
 * A counter no report carried stays absent, because a zero would claim the provider measured none.
 */
@@ -927,6 +915,46 @@ function sumSandboxUsage(events, agentRunName = "agent") {
 		...unreadable === void 0 ? {} : { tokensUnknownReason: unreadable }
 	};
 }
+function usageReceiptData(envelope, usage = {}) {
+	const merged = {
+		...usage,
+		...envelope
+	};
+	for (const aliases of [
+		[
+			"tokensIn",
+			"inputTokens",
+			"prompt_tokens"
+		],
+		[
+			"tokensOut",
+			"outputTokens",
+			"completion_tokens"
+		],
+		[
+			"costUsd",
+			"totalCostUsd",
+			"cost_usd",
+			"cost"
+		],
+		["costProvenance", "cost_provenance"]
+	]) {
+		const key = aliases.find((alias) => envelope[alias] !== void 0);
+		if (key === void 0) continue;
+		for (const alias of aliases) delete merged[alias];
+		merged[key] = envelope[key];
+	}
+	for (const aliases of [["tokensKnown", "tokens_known"], [
+		"costKnown",
+		"cost_known",
+		"usdKnown",
+		"usd_known"
+	]]) {
+		const values = [usage, envelope].flatMap((receipt) => aliases.map((key) => receipt[key]).filter((value) => value !== void 0));
+		if (values.length > 0) merged[aliases[0]] = values.every((value) => value === true);
+	}
+	return merged;
+}
 function buildLlmCall(data, agentRunName) {
 	const tokensIn = pickFiniteNumber(data, [
 		"tokensIn",
@@ -939,7 +967,7 @@ function buildLlmCall(data, agentRunName) {
 		"completion_tokens"
 	]);
 	const reasoningTokens = pickFiniteNumber(data, ["reasoningTokens"]);
-	const tokensOut = outputTokens !== void 0 || reasoningTokens !== void 0 ? (outputTokens ?? 0) + (reasoningTokens ?? 0) : void 0;
+	const tokensOut = outputTokens ?? reasoningTokens;
 	const reportedCostUsd = pickFiniteNumber(data, [
 		"costUsd",
 		"totalCostUsd",
@@ -953,7 +981,7 @@ function buildLlmCall(data, agentRunName) {
 	const catalogEstimate = costProvenance === "catalog-estimate" ? explicitEstimate ?? reportedCostUsd : explicitEstimate;
 	const costUsd = costProvenance === "catalog-estimate" ? void 0 : reportedCostUsd;
 	const promptCache = readPromptCacheUsage(data);
-	const tokensKnown = explicitTokensKnown !== false && tokensIn !== void 0 && tokensOut !== void 0;
+	const tokensKnown = explicitTokensKnown !== false && tokensIn !== void 0 && outputTokens !== void 0;
 	const usdKnown = explicitCostKnown !== false && costUsd !== void 0 && (costProvenance === void 0 || costProvenance === "provider-receipt" || costProvenance === "billing-receipt");
 	if (tokensIn === void 0 && tokensOut === void 0 && costUsd === void 0 && catalogEstimate === void 0 && promptCache === void 0 && explicitTokensKnown !== false && explicitCostKnown !== false) return;
 	const event = {
@@ -7084,12 +7112,36 @@ function providerAsSandboxClient(provider, options = {}) {
 	} };
 }
 /**
+* The idle timeout this adapter sends when nothing else names one: 1,800 seconds.
+*
+* Sandbox substitutes no value of its own: an omitted field falls back to the platform's global
+* idle timeout, documented as 30 minutes unless an operator changed it, and Runtime sent none. Idle
+* means inactivity to Sandbox, which suspends the sandbox (the container stops; the workspace is
+* kept) rather than deleting it. The SDK does not define inactivity further. A request in flight
+* counts as activity: a Discovery Lab seat created with `idleTimeoutSeconds: 1800` ran one request
+* to 2,252 seconds, ended by a per-request cap, not by idling (fleet-launch-2026-08-22).
+*
+* The value restates the documented default, so it can tighten a longer operator setting but never
+* loosen the default. It is 3.8 times the longest gap between frames recorded across a healthy
+* fleet run (469 seconds, same report), and a supervised provider child is observed through an open
+* stream for its whole turn. It is a backstop for a process that dies holding an environment; the
+* settlement barrier releases retained environments itself (`Executor.releaseRetained`). It does
+* nothing on a driver with a create/delete-only lifecycle, which the SDK says skips suspension.
+*/
+const DEFAULT_SANDBOX_IDLE_TIMEOUT_SECONDS = 1800;
+function sandboxIdleTimeoutSeconds(value) {
+	if (value === void 0) return DEFAULT_SANDBOX_IDLE_TIMEOUT_SECONDS;
+	if (!Number.isSafeInteger(value) || value <= 0) throw new ValidationError(`sandboxClientAsProvider: idleTimeoutSeconds must be a positive whole number of seconds, got ${String(value)}`);
+	return value;
+}
+/**
 * Adapt a `SandboxClient` into the shared `AgentEnvironmentProvider` contract.
 * The provider declares the public SDK contract before it creates an environment.
 * Each environment exposes interactive methods only when its deployment declares every required capability.
 * @experimental */
 function sandboxClientAsProvider(client, options = {}) {
 	const providerName = options.name ?? "tangle-sandbox";
+	const idleTimeoutSeconds = sandboxIdleTimeoutSeconds(options.idleTimeoutSeconds);
 	const providerCapabilities = async () => {
 		const resolved = await (options.capabilities ? typeof options.capabilities === "function" ? options.capabilities() : options.capabilities : defaultTangleSandboxCapabilities({
 			namedProfiles: options.resolveProfile !== void 0,
@@ -7104,14 +7156,18 @@ function sandboxClientAsProvider(client, options = {}) {
 		capabilities: providerCapabilities,
 		...options.validateProfile ? { validateProfile: options.validateProfile } : {},
 		async create(input) {
-			const createOptions = options.mapCreateInput?.(input) ?? await sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode", options.resolveProfile, providerName);
+			const custom = options.mapCreateInput?.(input);
+			const createOptions = custom === void 0 ? await sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode", options.resolveProfile, providerName, idleTimeoutSeconds) : {
+				...custom,
+				idleTimeoutSeconds: custom.idleTimeoutSeconds ?? idleTimeoutSeconds
+			};
 			const capabilities = await providerCapabilities();
-			return sandboxInstanceAsEnvironment(await client.create(createOptions, input.signal === void 0 ? void 0 : { signal: input.signal }), providerName, client, capabilities);
+			return sandboxInstanceAsEnvironment(await client.create(createOptions, input.signal === void 0 ? void 0 : { signal: input.signal }), providerName, client, capabilities, idleTimeoutSeconds);
 		},
 		...hasGet(client) ? { async get(id) {
 			const capabilities = await providerCapabilities();
 			const box = await client.get(id);
-			return box ? sandboxInstanceAsEnvironment(box, providerName, client, capabilities) : null;
+			return box ? sandboxInstanceAsEnvironment(box, providerName, client, capabilities, idleTimeoutSeconds) : null;
 		} } : {},
 		...hasList(client) ? { async list(query) {
 			return (await client.list(query?.providerOptions)).map((box) => ({
@@ -7331,6 +7387,31 @@ function createProviderExecutor(provider, profile, ctx, options, placement) {
 				};
 			}
 		},
+		async releaseRetained(signal) {
+			controller.abort();
+			if (!pending) return [];
+			const environmentId = retained?.controlRef.environmentId ?? environment?.id ?? admittedEnvironmentId(retention);
+			if (environmentId === void 0) return [];
+			const receipt = (destroyed, detail) => ({
+				provider: provider.name,
+				environmentId,
+				destroyed,
+				...detail === void 0 ? {} : { detail }
+			});
+			try {
+				const target = environment ?? (provider.get === void 0 ? void 0 : await awaitAbortable$1(provider.get(environmentId), signal));
+				if (target === void 0) return [receipt(false, `providerAsExecutor(${provider.name}): no environment handle and the provider exposes no get()`)];
+				if (target !== null) {
+					if (target.destroy === void 0) return [receipt(false, `providerAsExecutor(${provider.name}): environment exposes no destroy()`)];
+					await awaitAbortable$1(target.destroy(), signal);
+				}
+				pending = false;
+				destroyed = true;
+				return [receipt(true)];
+			} catch (error) {
+				return [receipt(false, `providerAsExecutor(${provider.name}): environment.destroy() failed — ${error instanceof Error ? error.message : String(error)}`)];
+			}
+		},
 		resultArtifact() {
 			if (!artifact) throw new ValidationError(`providerAsExecutor(${provider.name}): resultArtifact() read before stream drained`);
 			return artifact;
@@ -7339,6 +7420,13 @@ function createProviderExecutor(provider, profile, ctx, options, placement) {
 	};
 	return attestRuntimeOwnedPendingExecutor(executor, runtime, plannedDeclaration, plannedBinding);
 }
+/** The environment id the latest durable admission names, when creation got that far. */
+function admittedEnvironmentId(retention) {
+	for (const admission of [...retention?.admissions ?? []].reverse()) {
+		if (admission.phase === "dispatched") return admission.controlRef.environmentId;
+		if (admission.phase === "environment") return admission.environmentId;
+	}
+}
 async function* streamProviderExecutor(args) {
 	const started = Date.now();
 	const linked = linkAbort(args.signal, args.controller.signal).signal;
@@ -7461,16 +7549,17 @@ async function* streamProviderExecutor(args) {
 		if (receipt === void 0) return;
 		const hasTokens = receipt.tokensIn !== void 0 || receipt.tokensOut !== void 0;
 		if (hasTokens && receipt.tokensIn !== void 0 && receipt.tokensOut !== void 0 && receipt.tokensKnown !== false) sawCompleteTokenReceipt = true;
-		else if (hasTokens || receipt.tokensUnknownReason) sawIncompleteTokenReceipt = true;
+		else if (hasTokens || receipt.tokensKnown === false || receipt.tokensUnknownReason) sawIncompleteTokenReceipt = true;
 		const input = receipt.tokensIn ?? 0;
 		const output = receipt.tokensOut ?? 0;
-		if (input || output) {
+		if (input || output || receipt.tokensKnown === false) {
 			tokens.input += input;
 			tokens.output += output;
 			yield {
 				kind: "tokens",
 				input,
-				output
+				output,
+				...receipt.tokensKnown === false ? { tokensKnown: false } : {}
 			};
 		}
 		if (receipt.costUsd) {
@@ -7668,7 +7757,7 @@ function createInputFromSandboxOptions(options) {
 		providerOptions: { sandboxCreateOptions: options ?? {} }
 	};
 }
-async function sandboxOptionsFromCreateInput(input, defaultBackend, resolveProfile, providerName = "tangle-sandbox") {
+async function sandboxOptionsFromCreateInput(input, defaultBackend, resolveProfile, providerName = "tangle-sandbox", idleTimeoutSeconds = DEFAULT_SANDBOX_IDLE_TIMEOUT_SECONDS) {
 	if (input.runtimeAttachments !== void 0) throw new ValidationError("Tangle Sandbox runtimeAttachments require an explicit mapCreateInput mapper; the maintained Sandbox SDK create contract does not transport them");
 	const backendType = input.backend ?? defaultBackend;
 	const workspace = WorkspaceRequestSchema.parse(input.workspace ?? {});
@@ -7682,6 +7771,7 @@ async function sandboxOptionsFromCreateInput(input, defaultBackend, resolveProfi
 	const { profile: _baseProfile, ...baseBackend } = base.backend ?? {};
 	return {
 		...base,
+		idleTimeoutSeconds: base.idleTimeoutSeconds ?? idleTimeoutSeconds,
 		...environment ? { environment } : {},
 		...workspace.repoUrl ? { git: {
 			url: workspace.repoUrl,
@@ -7782,18 +7872,27 @@ function environmentAsSandboxInstance(environment, options) {
 			let text = "";
 			let usage;
 			let terminal = false;
+			const outcomeTracker = createAgentRunOutcomeTracker();
+			let explicitFailure = false;
 			for await (const event of environment.stream(turnInputFromPrompt(message, promptOptions))) {
 				events.push(event);
 				if (isTerminalEnvironmentEvent(event)) terminal = true;
+				const failureEvent = providerFailureEvent(event, sandboxEventFromEnvironmentEvent(event));
+				if (failureEvent) {
+					explicitFailure = true;
+					outcomeTracker.observe(failureEvent);
+				}
 				text += textFromEnvironmentEvent(event);
 				usage = mergeTokenUsage(usage, event.usage);
 			}
 			if (options.requireTerminalEvent && !terminal) throw new ValidationError(`providerAsSandboxClient(${environment.provider}): prompt ended without a terminal result/done/status event`);
+			const outcome = explicitFailure ? outcomeTracker.finish() : void 0;
 			return {
 				response: resultFromEvents(events, text).content,
-				success: true,
-				status: "success",
+				success: outcome?.success ?? true,
+				status: outcome?.status ?? "success",
 				durationMs: 0,
+				...outcome?.error ? { error: outcome.error } : {},
 				...usage ? { usage } : {}
 			};
 		},
@@ -7825,7 +7924,7 @@ function environmentAsSandboxInstance(environment, options) {
 		}
 	};
 }
-async function sandboxInstanceAsEnvironment(box, providerName, client, providerCapabilities) {
+async function sandboxInstanceAsEnvironment(box, providerName, client, providerCapabilities, idleTimeoutSeconds) {
 	const capabilities = await sandboxEnvironmentCapabilities(box, providerCapabilities);
 	const interactiveAgent = capabilities.interactiveAgent;
 	return {
@@ -7912,9 +8011,10 @@ async function sandboxInstanceAsEnvironment(box, providerName, client, providerC
 			return sandboxInstanceAsEnvironment(await client.create({
 				fromSnapshot: checkpoint.id,
 				fromSandboxId: String(box.id),
+				idleTimeoutSeconds,
 				...options?.name ? { name: options.name } : {},
 				...options?.metadata ? { metadata: options.metadata } : {}
-			}), providerName, client, providerCapabilities);
+			}), providerName, client, providerCapabilities, idleTimeoutSeconds);
 		},
 		async placement() {
 			return placementInfoFromLoopPlacement(client.describePlacement?.(box), box);
@@ -8140,6 +8240,7 @@ function usageSandboxEvent(event) {
 	return {
 		type: "usage",
 		data: {
+			...event.data,
 			...usage,
 			..."usageMode" in event ? { usageMode: event.usageMode } : event.data.usageMode === void 0 ? {} : { usageMode: event.data.usageMode }
 		},
@@ -8286,7 +8387,7 @@ function isTerminalEnvironmentEvent(event) {
 	return normalized?.type === "status" && (normalized.status === "completed" || normalized.status === "failed");
 }
 function isTerminalEventShape(type, data) {
-	if (isSandboxTerminalEvent(type)) return true;
+	if (type === "error" || isSandboxTerminalEvent(type)) return true;
 	if (type.endsWith(".completed") || type.endsWith(".failed")) return true;
 	if (type !== "status") return false;
 	return data.status === "completed" || data.status === "failed" || data.status === "cancelled";
@@ -15129,6 +15230,7 @@ const outsideKinds = /* @__PURE__ */ new Set([
 	"reconciled",
 	"edge",
 	"teardown-unconfirmed",
+	"environment-teardown",
 	"trace-unpropagated",
 	"node-inputs-resolved",
 	"edge-verdict",
@@ -15197,6 +15299,7 @@ async function replaySpawnTree(journal, blobs, root) {
 		if (ev.kind === "execution-input" || ev.kind === "execution-admitted" || ev.kind === "execution-result") continue;
 		if (ev.kind === "edge") continue;
 		if (ev.kind === "teardown-unconfirmed") continue;
+		if (ev.kind === "environment-teardown") continue;
 		if (ev.kind === "trace-unpropagated") continue;
 		if (ev.kind === "node-inputs-resolved") continue;
 		if (ev.kind === "edge-verdict") continue;
@@ -19588,6 +19691,9 @@ function defaultSleep(ms, signal) {
 /** Runtime-owned provider evidence is written through this private scope capability. */
 const runtimeOwnedProviderMeters = /* @__PURE__ */ new WeakMap();
 const recoveryStarters = /* @__PURE__ */ new WeakMap();
+const retainedReleasers = /* @__PURE__ */ new WeakMap();
+/** Per-child bound on a retained release: one remote destroy, answered or abandoned. */
+const RETAINED_RELEASE_TIMEOUT_MS = 3e4;
 /** @internal Admit original children before the parent acts; do not wait for their results. */
 async function startScopeRecoveries(scope) {
 	const start = recoveryStarters.get(scope);
@@ -19596,6 +19702,22 @@ async function startScopeRecoveries(scope) {
 	await start();
 }
 /**
+* @internal Release what this scope's settled children still hold for a retained execution, and
+* confirm each one's teardown afterwards through the executor's own teardown verb.
+*
+* A retained-pending child settles `down` with its cursor slot open and its environment alive,
+* because a resumed process reconciles the paid execution inside it. The supervisor calls this
+* once the root has reached a terminal outcome that no later process resumes — never while the
+* root is live, and never on a resumable interruption, since the open slot and the live
+* environment are exactly what a resume recovers. One `environment-teardown` receipt is journaled
+* per environment, on this scope's own tree; a nested manager reaches its children through
+* `Executor.releaseRetained`, and its nested scope journals theirs.
+*/
+async function releaseRetainedEnvironments(scope) {
+	const release = retainedReleasers.get(scope);
+	if (release) await release();
+}
+/**
 * The recursion seam key. A `Scope` seeds a value of this on each child's
 * `ExecutorContext.seams` so a child whose executor is a DRIVER can mount a NESTED `Scope`
 * over the driver's reserved child allocation at `depth+1`. A leaf executor never reads it. Single-sourced
@@ -19975,6 +20097,10 @@ function createScope(args) {
 				...executor.interactive ? { readInteractive: executor.interactive.bind(executor) } : {},
 				...executor.interactiveReady ? { readInteractiveReady: executor.interactiveReady.bind(executor) } : {},
 				...executor.cancel ? { requestCancel: executor.cancel.bind(executor) } : {},
+				...executor.releaseRetained ? {
+					releaseRetained: executor.releaseRetained.bind(executor),
+					confirmTeardown: () => teardownExecutor(executor, "brutalKill", void 0, now)
+				} : {},
 				abortChild: (reason) => controller.abort(reason)
 			};
 			const recordCancellation = () => {
@@ -20581,6 +20707,33 @@ function createScope(args) {
 			throw error;
 		}
 	});
+	retainedReleasers.set(scope, async () => {
+		const held = [...children.values()].filter((child) => isTerminalNodeStatus(child.status) && !child.cleanupConfirmed && (child.recoveryPending === true || child.ownedTreeRoot !== void 0) && child.releaseRetained !== void 0 && child.confirmTeardown !== void 0);
+		const released = await Promise.all(held.map(async (child) => {
+			const bound = new AbortController();
+			const timer = setTimeout(() => bound.abort(new ValidationError$1(`retained release did not acknowledge within ${RETAINED_RELEASE_TIMEOUT_MS}ms`)), RETAINED_RELEASE_TIMEOUT_MS);
+			timer.unref?.();
+			try {
+				const receipts = await child.releaseRetained(bound.signal);
+				if (receipts.every((receipt) => receipt.destroyed)) try {
+					await child.confirmTeardown();
+					child.cleanupConfirmed = true;
+				} catch {}
+				return {
+					child,
+					receipts
+				};
+			} catch {
+				return {
+					child,
+					receipts: []
+				};
+			} finally {
+				clearTimeout(timer);
+			}
+		}));
+		for (const { child, receipts } of released) for (const receipt of receipts) await appendEnvironmentTeardown(args.journal, args.root, child.id, receipt, new Date(now()).toISOString());
+	});
 	registerScopeRetainedOwner(scope, {
 		rootId: args.root,
 		nodeId: args.parentId,
@@ -20838,6 +20991,21 @@ async function appendReconciledFloor(journal, root, id, spent, at) {
 		at
 	});
 }
+/** A release receipt has the same per-child sequence discipline: outside the cursor namespace and
+*  monotonic per node, so a run released in two processes keeps its receipts ordered. */
+async function appendEnvironmentTeardown(journal, root, id, receipt, at) {
+	const seq = await nextPerNodeSeq(journal, root, "environment-teardown", id);
+	await journal.appendEvent(root, {
+		kind: "environment-teardown",
+		id,
+		provider: receipt.provider,
+		environmentId: receipt.environmentId,
+		destroyed: receipt.destroyed,
+		...receipt.detail === void 0 ? {} : { detail: receipt.detail },
+		seq,
+		at
+	});
+}
 async function nextPerNodeSeq(journal, root, kind, id) {
 	return (await journal.loadTree(root) ?? []).reduce((max, event) => event.kind === kind && event.id === id ? Math.max(max, event.seq) : max, -1) + 1;
 }
@@ -21641,6 +21809,7 @@ const driverExecutorFactory = (rawSpec, ctx) => {
 	let cleanupFailure;
 	let unconfirmedDescendants = [];
 	let active;
+	let nestedScopeHeld;
 	const closeActive = (reason) => {
 		if (active === void 0) return Promise.resolve();
 		if (!active.close) {
@@ -21695,6 +21864,7 @@ const driverExecutorFactory = (rawSpec, ctx) => {
 				controller,
 				scope: nestedScope
 			};
+			nestedScopeHeld = nestedScope;
 			try {
 				if (recovering) {
 					await startScopeRecoveries(nestedScope);
@@ -21749,6 +21919,12 @@ const driverExecutorFactory = (rawSpec, ctx) => {
 				detail: `Nested executor cleanup is unconfirmed: ${unconfirmedDescendants.join(", ")}`
 			} : { destroyed: true };
 		},
+		async releaseRetained() {
+			if (nestedScopeHeld === void 0) return [];
+			await releaseRetainedEnvironments(nestedScopeHeld);
+			unconfirmedDescendants = nestedScopeHeld.workerCapacity.unconfirmed.map((node) => node.id);
+			return [];
+		},
 		resultArtifact() {
 			if (!artifact) throw new ValidationError$1("driverExecutor: resultArtifact() read before execute()");
 			return artifact;
@@ -22183,7 +22359,7 @@ function describeRejection(error) {
 function createSupervisor() {
 	let attached;
 	async function run(root, task, opts) {
-		const { budget, rootIdentity, rootMaterialization, runId, journal: journalStore, blobs: blobStore, executors: executorRegistry, recoverExecutor, probes, maxDepth, maxLiveWorkers, maxRestarts, withinMs, childSettleGraceMs, resume, now: suppliedNow, signal, hooks, workerTrace, workerTraceUnpropagated, interactiveBindingDir } = opts;
+		const { budget, rootIdentity, rootMaterialization, runId, journal: journalStore, blobs: blobStore, executors: executorRegistry, recoverExecutor, probes, maxDepth, maxLiveWorkers, maxRestarts, withinMs, childSettleGraceMs, resume, retainedAtSettlement: requestedRetainedAtSettlement, now: suppliedNow, signal, hooks, workerTrace, workerTraceUnpropagated, interactiveBindingDir } = opts;
 		const input = detachedSnapshot({
 			task,
 			options: {
@@ -22197,9 +22373,11 @@ function createSupervisor() {
 				...withinMs === void 0 ? {} : { withinMs },
 				...childSettleGraceMs === void 0 ? {} : { childSettleGraceMs },
 				...resume === void 0 ? {} : { resume },
+				...requestedRetainedAtSettlement === void 0 ? {} : { retainedAtSettlement: requestedRetainedAtSettlement },
 				...interactiveBindingDir === void 0 ? {} : { interactiveBindingDir }
 			}
 		}, "supervisor.run");
+		if (requestedRetainedAtSettlement !== void 0 && requestedRetainedAtSettlement !== "release" && requestedRetainedAtSettlement !== "keep") throw new ValidationError$1(`supervisor: retainedAtSettlement must be 'release' or 'keep', got ${JSON.stringify(requestedRetainedAtSettlement)}`);
 		opts = Object.freeze({
 			...input.options,
 			journal: journalStore,
@@ -22345,6 +22523,7 @@ function createSupervisor() {
 				error: new RuntimeRunStateError("supervisor: root execution did not start")
 			};
 			let teardownUnconfirmed = [];
+			const retainedAtSettlement = opts.retainedAtSettlement ?? (opts.resume === true ? "keep" : "release");
 			let teardownSeq = 0;
 			let executionAborted = controller.signal.aborted;
 			let allChildrenDownAtSettle = false;
@@ -22369,6 +22548,10 @@ function createSupervisor() {
 				const settleGraceMs = !controller.signal.aborted ? boundedSettleGrace(opts.childSettleGraceMs, rootDeadlineAtMs, now) : 0;
 				try {
 					teardownUnconfirmed = await drainLiveChildren(openScope, controller, settleGraceMs);
+					if (retainedAtSettlement === "release") {
+						await releaseRetainedEnvironments(openScope);
+						teardownUnconfirmed = openScope.workerCapacity.unconfirmed;
+					}
 					for (const node of teardownUnconfirmed) await opts.journal.appendEvent(opts.runId, {
 						kind: "teardown-unconfirmed",
 						id: node.id,
@@ -22762,6 +22945,6 @@ function isNonEmptySpend(s) {
 	return s.iterations > 0 || s.tokens.input > 0 || s.tokens.output > 0 || s.usd > 0 || s.ms > 0 || s.tokensKnown === false || s.usdKnown === false || Object.values(s.resources ?? {}).some((resource) => resource.amount > 0 || !resource.known);
 }
 //#endregion
-export { createExecutor as $, readTraceContextFromEnv as $n, finalizeRuntimeOwnedPendingExecutor as $r, createSandboxForSpec as $t, scopeRetainedOwnerPriorSpend as A, sandboxProgressEvents as Ai, withTimeout as An, AGENT_PROFILE_MATERIALIZATION_AXES as Ar, DEFAULT_STALL_AFTER_MS as At, recoverRetainedInteractiveRun as B, RunCancellationReason as Bn, renderProfileMaterializationIssues as Br, peerMailTools as Bt, pollFor as C, createSandboxUsageLedger as Ci, promptCacheTokenClasses as Cn, removeWorktree as Cr, spendFromUsageEvents as Ct, consumeScopeRetainedOwnerResult as D, mapSandboxToolEvent as Di, throwAbort as Dn, localHarnessExecutable as Dr, workerTraceHeaders as Dt, waitUntil as E, mapSandboxEvent as Ei, stringifySafe as En, harnessSupportsReasoningEffort as Er, workerTraceEnv as Et, attachWorker as F, promptFromAgentTurnInput as Fi, createPushTraceSource as Fn, profileMaterializationAxes$1 as Fr, DEFAULT_PEER_MAIL_LIMITS as Ft, queueOf as G, startRetainedRun as Gn, worktreeCliProfileMaterialization as Gr, bridgeModelRouteRefusal as Gt, destroyInteractiveEnvironment as H, linkAbort as Hn, sandboxActProfileMaterialization as Hr, isLiveNodeStatus as Ht, readWorkerInteractiveBinding as I, promptOptionsFromAgentTurnInput as Ii, decodeToolPart as In, promptControlProfileMaterialization as Ir, PEER_MAIL_WIRE_KEY as It, teardownExecutor as J, defaultRedactor as Jn, prepareJsonlAppend as Jr, harnessUsageIsEmpty as Jt, rollingDispatch as K, startRetainedRunInEnvironment as Kn, isNoEntError as Kr, addHarnessUsage as Kt, workerInteractiveBindingFile as L, providerMessageText as Li, sandboxSessionTraceSource as Ln, promptModelProfileMaterialization as Lr, claimsAuthority as Lt, interactiveAdmissionSeamKey as M, decodeHarnessUsage as Mi, addResourceSpend as Mn, controlProfileMaterialization as Mr, readWorkerProgress as Mt, readWorkerInteractiveAdmissions as N, abortError$2 as Ni, resourceTelemetry as Nn, defineProfileMaterializationContract as Nr, createInbox as Nt, prepareScopeRetainedOwnerTask as O, notifySandboxEventObserver as Oi, throwIfAborted as On, parseCodexTokenUsage as Or, workerTraceSeamKey as Ot, workerInteractiveAdmissionFile as P, awaitAbortable$1 as Pi, withBudgetResources as Pn, fullProfileMaterialization as Pr, AUTHORITY_MARKERS as Pt, cliWorktreeExecutor as Q, mergeTraceEnv as Qn, authoredProfileDigest as Qr, TERMINAL_DECISIONS as Qt, workerInteractiveBindingsDir as R, registerRetainedExecutorPreparation as Rn, promptOnlyProfileMaterialization as Rr, createPeerMailbox as Rt, isWaitOutcome as S, createSandboxToolPartState as Si, isAbortError$2 as Sn, createWorktree as Sr, createBudgetPool as St, validateWaitSpec as T, isSandboxTerminalEvent as Ti, sleep as Tn, LOCAL_HARNESSES as Tr, readWorkerTraceContext as Tt, effectiveConcurrency as U, reconnectRetainedRun as Un, unsupportedProfileDimensions as Ur, isTerminalNodeStatus as Ut, startRetainedInteractiveRun as V, abortError$1 as Vn, renderUnsupported as Vr, peerMailVerbNames as Vt, freeSlots as W, recoverRetainedRun as Wn, validateProfileMaterialization as Wr, bridgeAdmissionRefusal as Wt, captureReusableExecutorConfig as X, resolveRedactor as Xn, attestRuntimeOwnedPendingExecutor as Xr, bridgeRuntimeAttachmentsKey as Xt, bindReusableExecutorExecutionId as Y, defaultRedactorIdentityMaterial as Yn, writeAllBytes as Yr, readCodexRolloutSession as Yt, cliInPlaceExecutor as Z, createPropagatingTraceEmitter as Zn, attestRuntimeOwnedScopeOwner as Zr, bridgeStopSignalKey as Zt, recordScopeOwnerMaterialization as _, detachedSnapshot as _i, addSpend as _n, sanitizeKnowledgeReadinessReport as _r, isTraceAnalysisStore as _t, pickBestDelivered as a, recordRuntimeOwnedDriveHarnessProviderEvidence as ai, acquireSandbox as an, createOpenInferenceFileExporter as ar, createInPlaceCliExecutor as at, settledToIteration as b, assertSandboxServedModel as bi, deleteBoxSafe as bn, runWorktreeHarness as br, contentAddress as bt, driverChild as c, runtimeOwnedExecutorMaterialization as ci, routerBrain as cn, flatOtelSpan as cr, InMemoryResultBlobStore as ct, withDriverExecutor as d, runtimeOwnedScopeOwnerRuntime as di, observedModelMatchesDeclared as dn, padSpanId as dr, loadSpawnForest as dt, inheritRuntimeOwnedExecutorAttestation as ei, defaultSelectWinner as en, traceContextToEnv as er, createExecutorRegistry as et, beginScopeOwnerAttempt as f, unknownExecutionBindingReceipt as fi, createAgentEnvironmentProviderRegistry as fn, padTraceId as fr, materializeTreeView as ft, meterRuntimeOwnedProviderAttempt as g, detachedFrozen as gi, sandboxClientAsProvider as gn, sanitizeAgentRuntimeEvent as gr, captureWorkerTraceEvidence as gt, meterRuntimeOwnedAccounting as h, executableAgentSpecSnapshot as hi, resolveAgentEnvironmentProvider as hn, createRuntimeStreamEventCollector as hr, WORKER_TOOL_TRACE_SCHEMA_VERSION as ht, collectDelivered as i, providerAttemptEvidence as ii, probeSandboxCapabilities as in, buildRuntimeEventOtelSpans as ir, createSteerableSandboxSession as it, scopeRetainedOwnerResult as j, sumSandboxUsage as ji, zeroSpend as jn, assertProfileMaterialization as jr, createActivityLog as jt, scopeRetainedOwnerContext as k, sandboxEventServedBackend as ki, unmeteredSpend as kn, CodexExecutionDiagnosticError as kr, taskToPrompt as kt, driverExecutorFactory as l, runtimeOwnedExecutorProviderEvidence as li, runBrainLoop as ln, generateSpanId as lr, InMemorySpawnJournal as lt, deriveNodeExecutionIdentity as m, executableAgentProfileSnapshot as mi, providerAsSandboxClient as mn, createRuntimeEventCollector as mr, replaySpawnTree as mt, createSupervisor as n, knownMaterializationReceipt as ni, runAgentRounds as nn, buildLoopOtelSpans as nr, createWorktreeCliExecutor as nt, runFinalizer as o, runtimeOwnedDriveHarnessProviderEvidence as oi, assertBoxlessPromptOptions as on, createOtelExporter as or, FileResultBlobStore as ot, createScope as p, unknownMaterializationReceipt as pi, providerAsExecutor as pn, toOtelAttributes as pr, pendingWaits as pt, DEFAULT_SUCCESSFUL_SHUTDOWN_MS as q, retainedCreateMaterial as qn, parseCommittedJsonLines as qr, createCodexRolloutStoreReader as qt, bestDelivered as r, newExecutionAttemptId as ri, createSandboxLineage as rn, buildLoopSpanNodes as rr, DEFAULT_SANDBOX_STEERING_MAX_TURNS as rt, runTree as s, runtimeOwnedExecutorExecutionBinding as si, readPromptOptions as sn, exportEvalRuns as sr, FileSpawnJournal as st, createRootHandle as t, knownExecutionBindingReceipt as ti, isTerminalDecision as tn, INTELLIGENCE_WIRE_VERSION as tr, snapshotExecutorConfig as tt, isDriverSpec as u, runtimeOwnedPendingExecutorMaterialization as ui, canonicalObservedModelParts as un, loopEventToOtelSpan as ur, insideCursorNamespace as ut, restoreScopeOwnerAcceptedExecution as v, projectSandboxOutcome as vi, chargedTokens as vn, sanitizeRuntimeStreamEvent as vr, parseWorkerToolTraceArtifact as vt, timerAt as w, extractLlmCallEvent as wi, randomSuffix as wn, DEFAULT_LOCAL_HARNESS as wr, WORKER_TRACE_PROPAGATION as wt, createWaitProbes as x, canonicalStreamEventFromSandboxEvent as xi, hasCompleteCacheBreakdown as xn, captureWorktreeDiff as xr, assertValidBudget as xt, scopeOwnerExecutorNodeContext as y, readSandboxOutcome as yi, cloneSpend as yn, runSettledCommand as yr, workerTraceAnalysisStore as yt, reconnectRetainedInteractiveRun as z, retainedExecutorSeamKey as zn, promptResourceProfileMaterialization as zr, isPeerMailEnvelope as zt };
+export { createExecutor as $, createPropagatingTraceEmitter as $n, attestRuntimeOwnedScopeOwner as $r, createSandboxForSpec as $t, scopeRetainedOwnerPriorSpend as A, notifySandboxEventObserver as Ai, unmeteredSpend as An, parseCodexTokenUsage as Ar, DEFAULT_STALL_AFTER_MS as At, recoverRetainedInteractiveRun as B, retainedExecutorSeamKey as Bn, promptOnlyProfileMaterialization as Br, peerMailTools as Bt, pollFor as C, canonicalStreamEventFromSandboxEvent as Ci, isAbortError$2 as Cn, captureWorktreeDiff as Cr, spendFromUsageEvents as Ct, consumeScopeRetainedOwnerResult as D, isSandboxTerminalEvent as Di, stringifySafe as Dn, LOCAL_HARNESSES as Dr, workerTraceHeaders as Dt, waitUntil as E, extractLlmCallEvent as Ei, sleep as En, DEFAULT_LOCAL_HARNESS as Er, workerTraceEnv as Et, attachWorker as F, abortError$2 as Fi, withBudgetResources as Fn, defineProfileMaterializationContract as Fr, DEFAULT_PEER_MAIL_LIMITS as Ft, queueOf as G, reconnectRetainedRun as Gn, unsupportedProfileDimensions as Gr, bridgeModelRouteRefusal as Gt, destroyInteractiveEnvironment as H, abortError$1 as Hn, renderProfileMaterializationIssues as Hr, isLiveNodeStatus as Ht, readWorkerInteractiveBinding as I, awaitAbortable$1 as Ii, createPushTraceSource as In, fullProfileMaterialization as Ir, PEER_MAIL_WIRE_KEY as It, teardownExecutor as J, startRetainedRunInEnvironment as Jn, isNoEntError as Jr, harnessUsageIsEmpty as Jt, rollingDispatch as K, recoverRetainedRun as Kn, validateProfileMaterialization as Kr, addHarnessUsage as Kt, workerInteractiveBindingFile as L, promptFromAgentTurnInput as Li, decodeToolPart as Ln, profileMaterializationAxes$1 as Lr, claimsAuthority as Lt, interactiveAdmissionSeamKey as M, sandboxProgressEvents as Mi, zeroSpend as Mn, AGENT_PROFILE_MATERIALIZATION_AXES as Mr, readWorkerProgress as Mt, readWorkerInteractiveAdmissions as N, sumSandboxUsage as Ni, addResourceSpend as Nn, assertProfileMaterialization as Nr, createInbox as Nt, prepareScopeRetainedOwnerTask as O, mapSandboxEvent as Oi, throwAbort as On, harnessSupportsReasoningEffort as Or, workerTraceSeamKey as Ot, workerInteractiveAdmissionFile as P, decodeHarnessUsage as Pi, resourceTelemetry as Pn, controlProfileMaterialization as Pr, AUTHORITY_MARKERS as Pt, cliWorktreeExecutor as Q, resolveRedactor as Qn, attestRuntimeOwnedPendingExecutor as Qr, TERMINAL_DECISIONS as Qt, workerInteractiveBindingsDir as R, promptOptionsFromAgentTurnInput as Ri, sandboxSessionTraceSource as Rn, promptControlProfileMaterialization as Rr, createPeerMailbox as Rt, isWaitOutcome as S, assertSandboxServedModel as Si, hasCompleteCacheBreakdown as Sn, runWorktreeHarness as Sr, createBudgetPool as St, validateWaitSpec as T, createSandboxUsageLedger as Ti, randomSuffix as Tn, removeWorktree as Tr, readWorkerTraceContext as Tt, effectiveConcurrency as U, linkAbort as Un, renderUnsupported as Ur, isTerminalNodeStatus as Ut, startRetainedInteractiveRun as V, RunCancellationReason as Vn, promptResourceProfileMaterialization as Vr, peerMailVerbNames as Vt, freeSlots as W, runAbortable as Wn, sandboxActProfileMaterialization as Wr, bridgeAdmissionRefusal as Wt, captureReusableExecutorConfig as X, defaultRedactor as Xn, prepareJsonlAppend as Xr, bridgeRuntimeAttachmentsKey as Xt, bindReusableExecutorExecutionId as Y, retainedCreateMaterial as Yn, parseCommittedJsonLines as Yr, readCodexRolloutSession as Yt, cliInPlaceExecutor as Z, defaultRedactorIdentityMaterial as Zn, writeAllBytes as Zr, bridgeStopSignalKey as Zt, recordScopeOwnerMaterialization as _, executableAgentSpecSnapshot as _i, sandboxClientAsProvider as _n, createRuntimeStreamEventCollector as _r, isTraceAnalysisStore as _t, pickBestDelivered as a, newExecutionAttemptId as ai, acquireSandbox as an, buildLoopSpanNodes as ar, createInPlaceCliExecutor as at, settledToIteration as b, projectSandboxOutcome as bi, cloneSpend as bn, sanitizeRuntimeStreamEvent as br, contentAddress as bt, driverChild as c, runtimeOwnedDriveHarnessProviderEvidence as ci, routerBrain as cn, createOtelExporter as cr, InMemoryResultBlobStore as ct, withDriverExecutor as d, runtimeOwnedExecutorProviderEvidence as di, observedModelMatchesDeclared as dn, generateSpanId as dr, loadSpawnForest as dt, authoredProfileDigest as ei, defaultSelectWinner as en, mergeTraceEnv as er, createExecutorRegistry as et, beginScopeOwnerAttempt as f, runtimeOwnedPendingExecutorMaterialization as fi, DEFAULT_SANDBOX_IDLE_TIMEOUT_SECONDS as fn, loopEventToOtelSpan as fr, materializeTreeView as ft, meterRuntimeOwnedProviderAttempt as g, executableAgentProfileSnapshot as gi, resolveAgentEnvironmentProvider as gn, createRuntimeEventCollector as gr, captureWorkerTraceEvidence as gt, meterRuntimeOwnedAccounting as h, unknownMaterializationReceipt as hi, providerAsSandboxClient as hn, toOtelAttributes as hr, WORKER_TOOL_TRACE_SCHEMA_VERSION as ht, collectDelivered as i, knownMaterializationReceipt as ii, probeSandboxCapabilities as in, buildLoopOtelSpans as ir, createSteerableSandboxSession as it, scopeRetainedOwnerResult as j, sandboxEventServedBackend as ji, withTimeout as jn, CodexExecutionDiagnosticError as jr, createActivityLog as jt, scopeRetainedOwnerContext as k, mapSandboxToolEvent as ki, throwIfAborted as kn, localHarnessExecutable as kr, taskToPrompt as kt, driverExecutorFactory as l, runtimeOwnedExecutorExecutionBinding as li, runBrainLoop as ln, exportEvalRuns as lr, InMemorySpawnJournal as lt, deriveNodeExecutionIdentity as m, unknownExecutionBindingReceipt as mi, providerAsExecutor as mn, padTraceId as mr, replaySpawnTree as mt, createSupervisor as n, inheritRuntimeOwnedExecutorAttestation as ni, runAgentRounds as nn, traceContextToEnv as nr, createWorktreeCliExecutor as nt, runFinalizer as o, providerAttemptEvidence as oi, assertBoxlessPromptOptions as on, buildRuntimeEventOtelSpans as or, FileResultBlobStore as ot, createScope as p, runtimeOwnedScopeOwnerRuntime as pi, createAgentEnvironmentProviderRegistry as pn, padSpanId as pr, pendingWaits as pt, DEFAULT_SUCCESSFUL_SHUTDOWN_MS as q, startRetainedRun as qn, worktreeCliProfileMaterialization as qr, createCodexRolloutStoreReader as qt, bestDelivered as r, knownExecutionBindingReceipt as ri, createSandboxLineage as rn, INTELLIGENCE_WIRE_VERSION as rr, DEFAULT_SANDBOX_STEERING_MAX_TURNS as rt, runTree as s, recordRuntimeOwnedDriveHarnessProviderEvidence as si, readPromptOptions as sn, createOpenInferenceFileExporter as sr, FileSpawnJournal as st, createRootHandle as t, finalizeRuntimeOwnedPendingExecutor as ti, isTerminalDecision as tn, readTraceContextFromEnv as tr, snapshotExecutorConfig as tt, isDriverSpec as u, runtimeOwnedExecutorMaterialization as ui, canonicalObservedModelParts as un, flatOtelSpan as ur, insideCursorNamespace as ut, restoreScopeOwnerAcceptedExecution as v, detachedFrozen as vi, addSpend as vn, sanitizeAgentRuntimeEvent as vr, parseWorkerToolTraceArtifact as vt, timerAt as w, createSandboxToolPartState as wi, promptCacheTokenClasses as wn, createWorktree as wr, WORKER_TRACE_PROPAGATION as wt, createWaitProbes as x, readSandboxOutcome as xi, deleteBoxSafe as xn, runSettledCommand as xr, assertValidBudget as xt, scopeOwnerExecutorNodeContext as y, detachedSnapshot as yi, chargedTokens as yn, sanitizeKnowledgeReadinessReport as yr, workerTraceAnalysisStore as yt, reconnectRetainedInteractiveRun as z, providerMessageText as zi, registerRetainedExecutorPreparation as zn, promptModelProfileMaterialization as zr, isPeerMailEnvelope as zt };
 
-//# sourceMappingURL=supervisor-DELeLQRJ.js.map
+//# sourceMappingURL=supervisor-WRrw0nlk.js.map