@tangle-network/agent-runtime 0.219.0 → 0.220.0

package/dist/{supervise-W_mtzswa.js → supervise-DRDPNM81.js}

@@ -2,9 +2,9 @@ import { $ as createExecutor, $r as attestRuntimeOwnedScopeOwner, A as scopeReta
 import { f as RuntimeRunStateError, i as ConfigError, m as ValidationError, r as BackendTransportError, t as AgentEvalError } from "./errors-DodWX-cb.js";
 import { a as concreteProfileModel, c as profileModelExecutionSettings, d as agentHarness, f as harnessRunsAgent, n as assertModelAllowed, o as enforceTokenLimits, r as assertProfileModelsAllowed, s as profileBridgeWireModel, t as assertExecutableAgentProfile } from "./model-policy-DKDyr-fc.js";
 import { t as composeRuntimeHooks } from "./runtime-hooks-tXpAarhW.js";
-import { k as writeRunCancellation, o as readRunCancelRequest, s as readRunCancellation } from "./run-layout-hZREkcfu.js";
-import { C as createCoordinationTools, F as watchRunCancellation, M as createInMemoryRunContext, P as applyRunCancellation, S as coordinationVerbNames, c as createProgressTracker, d as progressStop, j as createFileRunContext, r as driverAgent, y as DEFAULT_AWAIT_EVENT_TIMEOUT_MS } from "./coordination-driver-CvinSUI-.js";
 import { t as createStdioToolServer } from "./tool-server-BJbCPhoW.js";
+import { D as coordinationVerbNames, O as createCoordinationTools, S as watchRunCancellation, c as createProgressTracker, d as progressStop, r as driverAgent, v as createFileRunContext, w as DEFAULT_AWAIT_EVENT_TIMEOUT_MS, x as applyRunCancellation, y as createInMemoryRunContext } from "./coordination-driver-DwgDZ6nf.js";
+import { k as writeRunCancellation, o as readRunCancelRequest, s as readRunCancellation } from "./run-layout-hZREkcfu.js";
 import { agentProfileSchema, canonicalAgentProfileDigest, canonicalCandidateDigest, canonicalCandidateJson, validateAgentProfileSecurity } from "@tangle-network/agent-interface";
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { resolve } from "node:path";
@@ -142,330 +142,16 @@ function mapExecutorResult(inner, map) {
 				await settle(inner.resultArtifact(), task);
 			})();
 			return (async () => settle(await execution, task))();
-		},
-		teardown: (grace) => inner.teardown(grace),
-		resultArtifact() {
-			if (!mapped) throw new Error("mapExecutorResult: resultArtifact() read before execute()");
-			return mapped;
-		}
-	});
-}
-function isAsyncIterable$2(v) {
-	return v != null && typeof v[Symbol.asyncIterator] === "function";
-}
-//#endregion
-//#region src/runtime/supervise/otel-spans.ts
-/**
-* Supervisor tree → OTLP spans. OPT-IN, off by default.
-*
-* WHY. A supervised tree is legible today only by parsing this package's own spawn journal, so
-* every other multi-agent shape on the machine (a coding-CLI's subagents, a pi fanout, ad-hoc tool
-* parallelism) needs its own bespoke reader. A span carrying `parent_span_id` IS a tree, and any
-* system can emit one — so emitting spans makes the supervisor readable by the same viewer as
-* everything else, with no per-system reader.
-*
-* WHAT IT IS NOT. This is telemetry, never the record of truth. The spawn journal remains the sole
-* durable ledger for replay/resume and for cost; nothing here is read back, and a run whose export
-* fails is unaffected in every observable way. The two data models are deliberately separate.
-*
-* HOW IT ATTACHES. This is a pure `RuntimeHooks` observer over the lifecycle events `Scope` ALREADY
-* emits — `agent.spawn` (a node opened), `agent.child` (a node settled), `agent.turn` (a driver
-* inference turn was metered). It adds no event, mutates no journal, and changes no result. Because
-* `Scope` re-seeds the same hooks into every nested scope (`makeNestedScopeSeam`), one observer sees
-* the WHOLE recursion at arbitrary depth.
-*
-* SPAN SHAPE. One span per supervised node, opened at spawn and closed at settle, parented to its
-* parent node's span; the run root is the trace. Driver inference rides as an `LLM` child span under
-* the node that metered it. Attributes reuse the vocabulary the rest of the stack already reads
-* (`openinference.span.kind`, `agent.name`, `llm.token_count.*`, `llm.cost_usd`, `tangle.cost.usd`)
-* — see `@tangle-network/agent-eval`'s `src/trace/attribute-vocabulary.ts`, which is the consumer.
-*
-* UNKNOWN IS NEVER ZERO. `Spend.tokensKnown === false` / `usdKnown === false` mark work that
-* HAPPENED with an unreported count. Those spans OMIT the token/cost attribute entirely and set
-* `tangle.supervise.tokens_known` / `tangle.supervise.cost_known` to `false`, so a reader can never
-* mistake an unmeasured turn for a free one.
-*/
-/** OTEL status codes (`UNSET` / `OK` / `ERROR`) — the numeric wire values `OtelSpan.status` carries. */
-const STATUS_UNSET = 0;
-const STATUS_OK = 1;
-const STATUS_ERROR = 2;
-/** Longest string attribute value written from free-form detail, so an oversized turn payload
-*  cannot inflate a span. Identity/label attributes we control are never truncated. */
-const MAX_DETAIL_CHARS = 256;
-/**
-* Build the span recorder for one supervised run, or `undefined` when no exporter resolves — the
-* off-by-default path. A run that passes no `exporter` and no `exportConfig` never reaches this
-* function at all; one that passes an `exportConfig` with no endpoint (and no env endpoint) gets
-* `undefined` here, so "configured but unreachable" also costs nothing.
-*/
-function createSupervisorSpanRecorder(opts) {
-	const exporter = opts.exporter ?? createOtelExporter(opts.exportConfig);
-	if (!exporter) return void 0;
-	const ownsExporter = opts.exporter === void 0;
-	const now = opts.now ?? Date.now;
-	const traceId = normalizeTraceId(opts.traceId, opts.runId);
-	const rootSpanId = generateSpanId();
-	const rootStartMs = now();
-	const base = {
-		"tangle.run.id": opts.runId,
-		"tangle.sessionId": opts.runId,
-		...opts.attributes ?? {}
-	};
-	/** Node id → its open span. Seeded with the run id ⇒ the root span, because a depth-0 spawn's
-	*  `parentId` is the run id itself and every deeper spawn's is a real node id. */
-	const open = /* @__PURE__ */ new Map();
-	const spanIdOf = /* @__PURE__ */ new Map([[opts.runId, rootSpanId]]);
-	let finished = false;
-	/** Every export is best-effort: a throwing exporter must never reach the run. */
-	const emit = (span) => {
-		try {
-			exporter.exportSpan(span);
-		} catch {}
-	};
-	const span = (spanId, parentSpanId, name, startMs, endMs, attrs, status, message) => ({
-		traceId,
-		spanId,
-		...parentSpanId ? { parentSpanId } : {},
-		name,
-		kind: 1,
-		startTimeUnixNano: msToNano(startMs),
-		endTimeUnixNano: msToNano(Math.max(startMs, endMs)),
-		attributes: toOtelAttributes(attrs),
-		status: {
-			code: status,
-			...message ? { message } : {}
-		}
-	});
-	function onSpawn(event) {
-		const p = record(event.payload);
-		const childId = str(p.childId);
-		if (!childId) return;
-		const label = str(p.label) ?? "node";
-		const runtime = str(p.runtime);
-		const isWait = runtime === "wait";
-		const attrs = {
-			...base,
-			"openinference.span.kind": isWait ? "CHAIN" : "AGENT",
-			"agent.name": label,
-			"tangle.supervise.node.id": childId,
-			"tangle.supervise.node.label": label,
-			"tangle.supervise.node.kind": isWait ? "wait" : "agent",
-			"tangle.supervise.tree.root": event.runId
-		};
-		if (event.parentId) attrs["tangle.supervise.node.parent_id"] = event.parentId;
-		if (runtime) attrs["tangle.supervise.node.runtime"] = runtime;
-		if (typeof p.depth === "number") attrs["tangle.supervise.node.depth"] = p.depth;
-		if (typeof event.stepIndex === "number") attrs["tangle.supervise.node.ordinal"] = event.stepIndex;
-		if (p.resumed === true) attrs["tangle.supervise.node.resumed"] = true;
-		assignBudget(attrs, p.budget);
-		const spanId = generateSpanId();
-		spanIdOf.set(childId, spanId);
-		open.set(childId, {
-			spanId,
-			parentSpanId: event.parentId && spanIdOf.get(event.parentId) || rootSpanId,
-			name: label,
-			startMs: event.timestamp,
-			attrs
-		});
-	}
-	function onSettled(event) {
-		const p = record(event.payload);
-		const childId = str(p.childId);
-		if (!childId) return;
-		const node = open.get(childId);
-		if (!node) return;
-		open.delete(childId);
-		const status = str(p.status);
-		const down = status === "down";
-		const attrs = {
-			...node.attrs,
-			"tangle.supervise.node.status": status ?? "done"
-		};
-		if (typeof event.stepIndex === "number") attrs["tangle.supervise.node.seq"] = event.stepIndex;
-		if (typeof p.outRef === "string") attrs["tangle.supervise.node.out_ref"] = p.outRef;
-		if (typeof p.valid === "boolean") attrs["tangle.supervise.verdict.valid"] = p.valid;
-		if (typeof p.score === "number") attrs["tangle.supervise.verdict.score"] = p.score;
-		if (down) {
-			attrs["error.type"] = p.infra === true ? "infra" : "child-down";
-			const reason = str(p.reason);
-			if (reason) attrs["error.message"] = truncate(reason);
-			if (typeof p.infra === "boolean") attrs["tangle.supervise.node.infra"] = p.infra;
-		}
-		const wokeBy = str(record(p.wait).settled);
-		if (wokeBy) attrs["tangle.supervise.wait.settled"] = wokeBy;
-		assignSpend(attrs, p.spent);
-		emit(span(node.spanId, node.parentSpanId, node.name, node.startMs, event.timestamp, attrs, down ? STATUS_ERROR : STATUS_OK, down ? str(p.reason) ?? "child down" : void 0));
-	}
-	function onTurn(event) {
-		const p = record(event.payload);
-		const parentId = event.parentId;
-		const parentSpanId = parentId && spanIdOf.get(parentId) || rootSpanId;
-		const attrs = {
-			...base,
-			"openinference.span.kind": "LLM",
-			"inference.observation_kind": "LLM",
-			"tangle.supervise.node.kind": "inference"
-		};
-		if (parentId) attrs["tangle.supervise.node.id"] = parentId;
-		for (const [key, value] of Object.entries(p)) {
-			if (key === "spend") continue;
-			if (key === "driver" && typeof value === "string") {
-				attrs["agent.name"] = value;
-				attrs["inference.agent_name"] = value;
-				continue;
-			}
-			if (key === "model" && typeof value === "string") {
-				attrs["llm.model_name"] = value;
-				continue;
-			}
-			if (Array.isArray(value)) {
-				const scalars = value.filter((v) => typeof v === "string" || typeof v === "number");
-				if (scalars.length > 0) attrs[`tangle.supervise.turn.${key}`] = truncate(scalars.join(","));
-				continue;
-			}
-			if (typeof value === "string") attrs[`tangle.supervise.turn.${key}`] = truncate(value);
-			else if (typeof value === "number" || typeof value === "boolean") attrs[`tangle.supervise.turn.${key}`] = value;
-		}
-		const spend = assignSpend(attrs, p.spend);
-		const endMs = event.timestamp + (spend?.ms ?? 0);
-		emit(span(generateSpanId(), parentSpanId, "gen_ai.client.inference", event.timestamp, endMs, attrs, STATUS_OK));
-	}
-	return {
-		hooks: { onEvent(event) {
-			if (finished) return;
-			try {
-				if (event.phase !== "after") return;
-				if (event.target === "agent.spawn") onSpawn(event);
-				else if (event.target === "agent.child") onSettled(event);
-				else if (event.target === "agent.turn") onTurn(event);
-			} catch {}
-		} },
-		traceId,
-		rootSpanId,
-		workerTrace(spawningNodeId) {
-			return {
-				traceId,
-				parentSpanId: spanIdOf.get(spawningNodeId) ?? rootSpanId
-			};
-		},
-		async finish(outcome) {
-			if (finished) return;
-			finished = true;
-			const endMs = now();
-			try {
-				for (const [nodeId, node] of open) emit(span(node.spanId, node.parentSpanId, node.name, node.startMs, endMs, {
-					...node.attrs,
-					"tangle.supervise.node.status": "unsettled",
-					"tangle.supervise.node.settled": false,
-					"tangle.supervise.node.id": nodeId
-				}, STATUS_UNSET));
-				open.clear();
-				emit(span(rootSpanId, opts.parentSpanId, "supervisor.run", rootStartMs, endMs, rootAttrs(base, opts.agentName ?? "supervisor", outcome), rootStatus(outcome), rootMessage(outcome)));
-				await exporter.flush();
-				if (ownsExporter) await exporter.shutdown();
-			} catch {}
-		}
-	};
-}
-function rootAttrs(base, agentName, outcome) {
-	const attrs = {
-		...base,
-		"openinference.span.kind": "AGENT",
-		"inference.observation_kind": "AGENT",
-		"agent.name": agentName,
-		"inference.agent_name": agentName,
-		"tangle.supervise.node.kind": "root"
-	};
-	const result = outcome?.result;
-	if (result) {
-		attrs["tangle.supervise.result"] = result.kind;
-		if (result.kind === "no-winner") {
-			attrs["tangle.supervise.reason"] = result.reason;
-			attrs["tangle.supervise.down_count"] = result.downCount;
-			if (result.reason === "driver-failed") {
-				attrs["error.type"] = result.error.name;
-				attrs["error.message"] = truncate(result.error.message);
-			}
-		}
-		assignSpend(attrs, result.spentTotal);
-	}
-	if (outcome?.error !== void 0) {
-		attrs["tangle.supervise.result"] = "error";
-		const err = outcome.error;
-		attrs["error.type"] = err instanceof Error ? err.name : typeof err;
-		attrs["error.message"] = truncate(err instanceof Error ? err.message : String(err));
-	}
-	return attrs;
-}
-function rootStatus(outcome) {
-	if (outcome?.error !== void 0) return STATUS_ERROR;
-	if (!outcome?.result) return STATUS_UNSET;
-	return outcome.result.kind === "winner" ? STATUS_OK : STATUS_ERROR;
-}
-function rootMessage(outcome) {
-	if (outcome?.error !== void 0) return truncate(outcome.error instanceof Error ? outcome.error.message : String(outcome.error));
-	const result = outcome?.result;
-	return result && result.kind === "no-winner" ? result.reason : void 0;
-}
-/**
-* Write a `Spend` onto a span, honouring the "a missing measurement is never zero" invariant: a
-* channel marked NOT known contributes no number at all and instead flags itself, so nothing
-* downstream can sum an unmeasured turn as free. Returns the spend it read (for the duration).
-*/
-function assignSpend(attrs, value) {
-	if (!isRecord(value)) return void 0;
-	const spend = value;
-	const tokens = isRecord(spend.tokens) ? spend.tokens : void 0;
-	if (spend.tokensKnown === false) attrs["tangle.supervise.tokens_known"] = false;
-	else if (tokens) {
-		if (typeof tokens.input === "number") attrs["llm.token_count.prompt"] = tokens.input;
-		if (typeof tokens.output === "number") attrs["llm.token_count.completion"] = tokens.output;
-	}
-	if (spend.usdKnown === false) attrs["tangle.supervise.cost_known"] = false;
-	else if (typeof spend.usd === "number" && Number.isFinite(spend.usd)) {
-		attrs["llm.cost_usd"] = spend.usd;
-		attrs["tangle.cost.usd"] = spend.usd;
-	}
-	if (typeof spend.iterations === "number") attrs["tangle.supervise.iterations"] = spend.iterations;
-	if (typeof spend.ms === "number" && spend.ms > 0) attrs["tangle.supervise.duration_ms"] = spend.ms;
-	if (typeof spend.boxMinutes === "number" && Number.isFinite(spend.boxMinutes)) attrs["tangle.platform.box_minutes"] = spend.boxMinutes;
-	if (spend.boxMinutesProvenance !== void 0) {
-		attrs["tangle.platform.box_minutes_provenance"] = spend.boxMinutesProvenance;
-		attrs["tangle.platform.box_minutes_known"] = spend.boxMinutesKnown === true;
-	}
-	if (spend.tokensProvenance !== void 0) attrs["tangle.supervise.tokens_provenance"] = spend.tokensProvenance;
-	return spend;
-}
-function assignBudget(attrs, value) {
-	if (!isRecord(value)) return;
-	const budget = value;
-	if (typeof budget.maxTokens === "number") attrs["tangle.supervise.budget.max_tokens"] = budget.maxTokens;
-	if (typeof budget.maxIterations === "number") attrs["tangle.supervise.budget.max_iterations"] = budget.maxIterations;
-	if (typeof budget.maxUsd === "number") attrs["tangle.supervise.budget.max_usd"] = budget.maxUsd;
-}
-/**
-* A trace id must be 32 hex characters. A caller-supplied one is used verbatim when it already is;
-* anything else (and the default) is DERIVED from the run id by content address — deterministic, so
-* a resumed run rejoins the trace its first process opened rather than forking a new one.
-*/
-function normalizeTraceId(traceId, runId) {
-	if (traceId && /^[0-9a-f]{32}$/i.test(traceId)) return traceId.toLowerCase();
-	return contentAddress(traceId ?? runId).slice(7, 39);
-}
-function msToNano(ms) {
-	return (BigInt(Number.isFinite(ms) ? Math.floor(ms) : 0) * 1000000n).toString();
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function record(value) {
-	return isRecord(value) ? value : {};
-}
-function str(value) {
-	return typeof value === "string" && value.length > 0 ? value : void 0;
+		},
+		teardown: (grace) => inner.teardown(grace),
+		resultArtifact() {
+			if (!mapped) throw new Error("mapExecutorResult: resultArtifact() read before execute()");
+			return mapped;
+		}
+	});
 }
-function truncate(value) {
-	return value.length > MAX_DETAIL_CHARS ? `${value.slice(0, MAX_DETAIL_CHARS)}…` : value;
+function isAsyncIterable$2(v) {
+	return v != null && typeof v[Symbol.asyncIterator] === "function";
 }
 //#endregion
 //#region src/runtime/supervise/coordination-http.ts
@@ -904,6 +590,7 @@ async function serveCoordinationMcp(opts) {
 		...opts.priorAnalystDefinitions?.length ? { priorAnalystDefinitions: opts.priorAnalystDefinitions } : {},
 		...opts.preflightSpawn ? { preflightSpawn: opts.preflightSpawn } : {},
 		...opts.resolveSpawnProfile ? { resolveSpawnProfile: opts.resolveSpawnProfile } : {},
+		...opts.spawnResourceRoot ? { spawnResourceRoot: opts.spawnResourceRoot } : {},
 		...opts.peerMail ? { peerMail: typeof opts.peerMail === "object" && opts.peerMail.limits ? { limits: opts.peerMail.limits } : {} } : {}
 	});
 	await coord.ready();
@@ -978,104 +665,418 @@ async function serveCoordinationMcp(opts) {
 		await new Promise((resolve) => server.close(() => resolve()));
 		throw error;
 	}
-	const mailbox = coord.peerMail;
-	const mailListener = mailbox === void 0 ? void 0 : await servePeerMail(mailbox, host);
+	const mailbox = coord.peerMail;
+	const mailListener = mailbox === void 0 ? void 0 : await servePeerMail(mailbox, host);
+	return {
+		url,
+		port,
+		get headers() {
+			return headers;
+		},
+		get credentialExpiresAt() {
+			return credentialExpiresAt;
+		},
+		rotateCredential,
+		settled: () => coord.settled(),
+		submittedResult: () => coord.submittedResult(),
+		drainResolved: () => coord.drainResolved(),
+		isStopped: () => coord.isStopped(),
+		history: () => coord.history(),
+		stats: () => coord.stats(),
+		raiseFinding: (finding) => coord.raiseFinding(finding),
+		mailHistory: () => mailbox?.history() ?? [],
+		stopMailThread: (threadId) => mailbox?.stopThread(threadId) ?? false,
+		close: async () => {
+			closed = true;
+			await new Promise((resolve) => {
+				server.close(() => resolve());
+			});
+			await mailListener?.close();
+		}
+	};
+}
+/**
+* Stand up the peer-mail capability listener: one HTTP server, one secret path per worker, and on
+* each path a tool server carrying ONLY `send_mail` / `read_mail` with that worker's identity
+* closed over. An unknown path is a flat 404 — the path is the credential, so a request that does
+* not present a minted one is not a client to reason with.
+*
+* The host is the coordination host, which the caller has already had to justify: the loopback gate
+* above governs both listeners, and there is deliberately no way to bind mail somewhere else.
+*/
+async function servePeerMail(mailbox, host) {
+	const servers = /* @__PURE__ */ new Map();
+	const forCapability = (capabilityId) => {
+		const existing = servers.get(capabilityId);
+		if (existing) return existing;
+		const created = createStdioToolServer({
+			serverName: "peer-mail",
+			serverVersion: "1",
+			tools: mailbox.tools(capabilityId)
+		});
+		servers.set(capabilityId, created);
+		return created;
+	};
+	const listener = createServer((req, res) => {
+		const capabilityId = /^\/mail\/([0-9a-f]{32})$/.exec(req.url ?? "")?.[1];
+		if (req.method !== "POST" || capabilityId === void 0 || !mailbox.hasCapability(capabilityId)) {
+			res.writeHead(404).end();
+			return;
+		}
+		let body = "";
+		req.on("data", (chunk) => {
+			body += chunk;
+		});
+		req.on("end", () => {
+			(async () => {
+				try {
+					const message = JSON.parse(body);
+					const response = await forCapability(capabilityId).handle(message);
+					if (response === null) {
+						res.writeHead(202).end();
+						return;
+					}
+					res.writeHead(200, { "content-type": "application/json" });
+					res.end(JSON.stringify(response));
+				} catch (e) {
+					res.writeHead(200, { "content-type": "application/json" });
+					res.end(JSON.stringify({
+						jsonrpc: "2.0",
+						id: null,
+						error: {
+							code: -32700,
+							message: e instanceof Error ? e.message : "parse error"
+						}
+					}));
+				}
+			})();
+		});
+	});
+	const port = await new Promise((resolve, reject) => {
+		listener.once("error", reject);
+		listener.listen(0, host, () => {
+			const addr = listener.address();
+			resolve(typeof addr === "object" && addr ? addr.port : 0);
+		});
+	});
+	mailbox.setEndpoint(`http://${host}:${port}/mail`);
+	return { close: () => new Promise((resolve) => {
+		listener.close(() => resolve());
+	}) };
+}
+//#endregion
+//#region src/runtime/supervise/otel-spans.ts
+/**
+* Supervisor tree → OTLP spans. OPT-IN, off by default.
+*
+* WHY. A supervised tree is legible today only by parsing this package's own spawn journal, so
+* every other multi-agent shape on the machine (a coding-CLI's subagents, a pi fanout, ad-hoc tool
+* parallelism) needs its own bespoke reader. A span carrying `parent_span_id` IS a tree, and any
+* system can emit one — so emitting spans makes the supervisor readable by the same viewer as
+* everything else, with no per-system reader.
+*
+* WHAT IT IS NOT. This is telemetry, never the record of truth. The spawn journal remains the sole
+* durable ledger for replay/resume and for cost; nothing here is read back, and a run whose export
+* fails is unaffected in every observable way. The two data models are deliberately separate.
+*
+* HOW IT ATTACHES. This is a pure `RuntimeHooks` observer over the lifecycle events `Scope` ALREADY
+* emits — `agent.spawn` (a node opened), `agent.child` (a node settled), `agent.turn` (a driver
+* inference turn was metered). It adds no event, mutates no journal, and changes no result. Because
+* `Scope` re-seeds the same hooks into every nested scope (`makeNestedScopeSeam`), one observer sees
+* the WHOLE recursion at arbitrary depth.
+*
+* SPAN SHAPE. One span per supervised node, opened at spawn and closed at settle, parented to its
+* parent node's span; the run root is the trace. Driver inference rides as an `LLM` child span under
+* the node that metered it. Attributes reuse the vocabulary the rest of the stack already reads
+* (`openinference.span.kind`, `agent.name`, `llm.token_count.*`, `llm.cost_usd`, `tangle.cost.usd`)
+* — see `@tangle-network/agent-eval`'s `src/trace/attribute-vocabulary.ts`, which is the consumer.
+*
+* UNKNOWN IS NEVER ZERO. `Spend.tokensKnown === false` / `usdKnown === false` mark work that
+* HAPPENED with an unreported count. Those spans OMIT the token/cost attribute entirely and set
+* `tangle.supervise.tokens_known` / `tangle.supervise.cost_known` to `false`, so a reader can never
+* mistake an unmeasured turn for a free one.
+*/
+/** OTEL status codes (`UNSET` / `OK` / `ERROR`) — the numeric wire values `OtelSpan.status` carries. */
+const STATUS_UNSET = 0;
+const STATUS_OK = 1;
+const STATUS_ERROR = 2;
+/** Longest string attribute value written from free-form detail, so an oversized turn payload
+*  cannot inflate a span. Identity/label attributes we control are never truncated. */
+const MAX_DETAIL_CHARS = 256;
+/**
+* Build the span recorder for one supervised run, or `undefined` when no exporter resolves — the
+* off-by-default path. A run that passes no `exporter` and no `exportConfig` never reaches this
+* function at all; one that passes an `exportConfig` with no endpoint (and no env endpoint) gets
+* `undefined` here, so "configured but unreachable" also costs nothing.
+*/
+function createSupervisorSpanRecorder(opts) {
+	const exporter = opts.exporter ?? createOtelExporter(opts.exportConfig);
+	if (!exporter) return void 0;
+	const ownsExporter = opts.exporter === void 0;
+	const now = opts.now ?? Date.now;
+	const traceId = normalizeTraceId(opts.traceId, opts.runId);
+	const rootSpanId = generateSpanId();
+	const rootStartMs = now();
+	const base = {
+		"tangle.run.id": opts.runId,
+		"tangle.sessionId": opts.runId,
+		...opts.attributes ?? {}
+	};
+	/** Node id → its open span. Seeded with the run id ⇒ the root span, because a depth-0 spawn's
+	*  `parentId` is the run id itself and every deeper spawn's is a real node id. */
+	const open = /* @__PURE__ */ new Map();
+	const spanIdOf = /* @__PURE__ */ new Map([[opts.runId, rootSpanId]]);
+	let finished = false;
+	/** Every export is best-effort: a throwing exporter must never reach the run. */
+	const emit = (span) => {
+		try {
+			exporter.exportSpan(span);
+		} catch {}
+	};
+	const span = (spanId, parentSpanId, name, startMs, endMs, attrs, status, message) => ({
+		traceId,
+		spanId,
+		...parentSpanId ? { parentSpanId } : {},
+		name,
+		kind: 1,
+		startTimeUnixNano: msToNano(startMs),
+		endTimeUnixNano: msToNano(Math.max(startMs, endMs)),
+		attributes: toOtelAttributes(attrs),
+		status: {
+			code: status,
+			...message ? { message } : {}
+		}
+	});
+	function onSpawn(event) {
+		const p = record(event.payload);
+		const childId = str(p.childId);
+		if (!childId) return;
+		const label = str(p.label) ?? "node";
+		const runtime = str(p.runtime);
+		const isWait = runtime === "wait";
+		const attrs = {
+			...base,
+			"openinference.span.kind": isWait ? "CHAIN" : "AGENT",
+			"agent.name": label,
+			"tangle.supervise.node.id": childId,
+			"tangle.supervise.node.label": label,
+			"tangle.supervise.node.kind": isWait ? "wait" : "agent",
+			"tangle.supervise.tree.root": event.runId
+		};
+		if (event.parentId) attrs["tangle.supervise.node.parent_id"] = event.parentId;
+		if (runtime) attrs["tangle.supervise.node.runtime"] = runtime;
+		if (typeof p.depth === "number") attrs["tangle.supervise.node.depth"] = p.depth;
+		if (typeof event.stepIndex === "number") attrs["tangle.supervise.node.ordinal"] = event.stepIndex;
+		if (p.resumed === true) attrs["tangle.supervise.node.resumed"] = true;
+		assignBudget(attrs, p.budget);
+		const spanId = generateSpanId();
+		spanIdOf.set(childId, spanId);
+		open.set(childId, {
+			spanId,
+			parentSpanId: event.parentId && spanIdOf.get(event.parentId) || rootSpanId,
+			name: label,
+			startMs: event.timestamp,
+			attrs
+		});
+	}
+	function onSettled(event) {
+		const p = record(event.payload);
+		const childId = str(p.childId);
+		if (!childId) return;
+		const node = open.get(childId);
+		if (!node) return;
+		open.delete(childId);
+		const status = str(p.status);
+		const down = status === "down";
+		const attrs = {
+			...node.attrs,
+			"tangle.supervise.node.status": status ?? "done"
+		};
+		if (typeof event.stepIndex === "number") attrs["tangle.supervise.node.seq"] = event.stepIndex;
+		if (typeof p.outRef === "string") attrs["tangle.supervise.node.out_ref"] = p.outRef;
+		if (typeof p.valid === "boolean") attrs["tangle.supervise.verdict.valid"] = p.valid;
+		if (typeof p.score === "number") attrs["tangle.supervise.verdict.score"] = p.score;
+		if (down) {
+			attrs["error.type"] = p.infra === true ? "infra" : "child-down";
+			const reason = str(p.reason);
+			if (reason) attrs["error.message"] = truncate(reason);
+			if (typeof p.infra === "boolean") attrs["tangle.supervise.node.infra"] = p.infra;
+		}
+		const wokeBy = str(record(p.wait).settled);
+		if (wokeBy) attrs["tangle.supervise.wait.settled"] = wokeBy;
+		assignSpend(attrs, p.spent);
+		emit(span(node.spanId, node.parentSpanId, node.name, node.startMs, event.timestamp, attrs, down ? STATUS_ERROR : STATUS_OK, down ? str(p.reason) ?? "child down" : void 0));
+	}
+	function onTurn(event) {
+		const p = record(event.payload);
+		const parentId = event.parentId;
+		const parentSpanId = parentId && spanIdOf.get(parentId) || rootSpanId;
+		const attrs = {
+			...base,
+			"openinference.span.kind": "LLM",
+			"inference.observation_kind": "LLM",
+			"tangle.supervise.node.kind": "inference"
+		};
+		if (parentId) attrs["tangle.supervise.node.id"] = parentId;
+		for (const [key, value] of Object.entries(p)) {
+			if (key === "spend") continue;
+			if (key === "driver" && typeof value === "string") {
+				attrs["agent.name"] = value;
+				attrs["inference.agent_name"] = value;
+				continue;
+			}
+			if (key === "model" && typeof value === "string") {
+				attrs["llm.model_name"] = value;
+				continue;
+			}
+			if (Array.isArray(value)) {
+				const scalars = value.filter((v) => typeof v === "string" || typeof v === "number");
+				if (scalars.length > 0) attrs[`tangle.supervise.turn.${key}`] = truncate(scalars.join(","));
+				continue;
+			}
+			if (typeof value === "string") attrs[`tangle.supervise.turn.${key}`] = truncate(value);
+			else if (typeof value === "number" || typeof value === "boolean") attrs[`tangle.supervise.turn.${key}`] = value;
+		}
+		const spend = assignSpend(attrs, p.spend);
+		const endMs = event.timestamp + (spend?.ms ?? 0);
+		emit(span(generateSpanId(), parentSpanId, "gen_ai.client.inference", event.timestamp, endMs, attrs, STATUS_OK));
+	}
 	return {
-		url,
-		port,
-		get headers() {
-			return headers;
-		},
-		get credentialExpiresAt() {
-			return credentialExpiresAt;
+		hooks: { onEvent(event) {
+			if (finished) return;
+			try {
+				if (event.phase !== "after") return;
+				if (event.target === "agent.spawn") onSpawn(event);
+				else if (event.target === "agent.child") onSettled(event);
+				else if (event.target === "agent.turn") onTurn(event);
+			} catch {}
+		} },
+		traceId,
+		rootSpanId,
+		workerTrace(spawningNodeId) {
+			return {
+				traceId,
+				parentSpanId: spanIdOf.get(spawningNodeId) ?? rootSpanId
+			};
 		},
-		rotateCredential,
-		settled: () => coord.settled(),
-		submittedResult: () => coord.submittedResult(),
-		drainResolved: () => coord.drainResolved(),
-		isStopped: () => coord.isStopped(),
-		history: () => coord.history(),
-		stats: () => coord.stats(),
-		raiseFinding: (finding) => coord.raiseFinding(finding),
-		mailHistory: () => mailbox?.history() ?? [],
-		stopMailThread: (threadId) => mailbox?.stopThread(threadId) ?? false,
-		close: async () => {
-			closed = true;
-			await new Promise((resolve) => {
-				server.close(() => resolve());
-			});
-			await mailListener?.close();
+		async finish(outcome) {
+			if (finished) return;
+			finished = true;
+			const endMs = now();
+			try {
+				for (const [nodeId, node] of open) emit(span(node.spanId, node.parentSpanId, node.name, node.startMs, endMs, {
+					...node.attrs,
+					"tangle.supervise.node.status": "unsettled",
+					"tangle.supervise.node.settled": false,
+					"tangle.supervise.node.id": nodeId
+				}, STATUS_UNSET));
+				open.clear();
+				emit(span(rootSpanId, opts.parentSpanId, "supervisor.run", rootStartMs, endMs, rootAttrs(base, opts.agentName ?? "supervisor", outcome), rootStatus(outcome), rootMessage(outcome)));
+				await exporter.flush();
+				if (ownsExporter) await exporter.shutdown();
+			} catch {}
 		}
 	};
 }
-/**
-* Stand up the peer-mail capability listener: one HTTP server, one secret path per worker, and on
-* each path a tool server carrying ONLY `send_mail` / `read_mail` with that worker's identity
-* closed over. An unknown path is a flat 404 — the path is the credential, so a request that does
-* not present a minted one is not a client to reason with.
-*
-* The host is the coordination host, which the caller has already had to justify: the loopback gate
-* above governs both listeners, and there is deliberately no way to bind mail somewhere else.
-*/
-async function servePeerMail(mailbox, host) {
-	const servers = /* @__PURE__ */ new Map();
-	const forCapability = (capabilityId) => {
-		const existing = servers.get(capabilityId);
-		if (existing) return existing;
-		const created = createStdioToolServer({
-			serverName: "peer-mail",
-			serverVersion: "1",
-			tools: mailbox.tools(capabilityId)
-		});
-		servers.set(capabilityId, created);
-		return created;
+function rootAttrs(base, agentName, outcome) {
+	const attrs = {
+		...base,
+		"openinference.span.kind": "AGENT",
+		"inference.observation_kind": "AGENT",
+		"agent.name": agentName,
+		"inference.agent_name": agentName,
+		"tangle.supervise.node.kind": "root"
 	};
-	const listener = createServer((req, res) => {
-		const capabilityId = /^\/mail\/([0-9a-f]{32})$/.exec(req.url ?? "")?.[1];
-		if (req.method !== "POST" || capabilityId === void 0 || !mailbox.hasCapability(capabilityId)) {
-			res.writeHead(404).end();
-			return;
+	const result = outcome?.result;
+	if (result) {
+		attrs["tangle.supervise.result"] = result.kind;
+		if (result.kind === "no-winner") {
+			attrs["tangle.supervise.reason"] = result.reason;
+			attrs["tangle.supervise.down_count"] = result.downCount;
+			if (result.reason === "driver-failed") {
+				attrs["error.type"] = result.error.name;
+				attrs["error.message"] = truncate(result.error.message);
+			}
 		}
-		let body = "";
-		req.on("data", (chunk) => {
-			body += chunk;
-		});
-		req.on("end", () => {
-			(async () => {
-				try {
-					const message = JSON.parse(body);
-					const response = await forCapability(capabilityId).handle(message);
-					if (response === null) {
-						res.writeHead(202).end();
-						return;
-					}
-					res.writeHead(200, { "content-type": "application/json" });
-					res.end(JSON.stringify(response));
-				} catch (e) {
-					res.writeHead(200, { "content-type": "application/json" });
-					res.end(JSON.stringify({
-						jsonrpc: "2.0",
-						id: null,
-						error: {
-							code: -32700,
-							message: e instanceof Error ? e.message : "parse error"
-						}
-					}));
-				}
-			})();
-		});
-	});
-	const port = await new Promise((resolve, reject) => {
-		listener.once("error", reject);
-		listener.listen(0, host, () => {
-			const addr = listener.address();
-			resolve(typeof addr === "object" && addr ? addr.port : 0);
-		});
-	});
-	mailbox.setEndpoint(`http://${host}:${port}/mail`);
-	return { close: () => new Promise((resolve) => {
-		listener.close(() => resolve());
-	}) };
+		assignSpend(attrs, result.spentTotal);
+	}
+	if (outcome?.error !== void 0) {
+		attrs["tangle.supervise.result"] = "error";
+		const err = outcome.error;
+		attrs["error.type"] = err instanceof Error ? err.name : typeof err;
+		attrs["error.message"] = truncate(err instanceof Error ? err.message : String(err));
+	}
+	return attrs;
+}
+function rootStatus(outcome) {
+	if (outcome?.error !== void 0) return STATUS_ERROR;
+	if (!outcome?.result) return STATUS_UNSET;
+	return outcome.result.kind === "winner" ? STATUS_OK : STATUS_ERROR;
+}
+function rootMessage(outcome) {
+	if (outcome?.error !== void 0) return truncate(outcome.error instanceof Error ? outcome.error.message : String(outcome.error));
+	const result = outcome?.result;
+	return result && result.kind === "no-winner" ? result.reason : void 0;
+}
+/**
+* Write a `Spend` onto a span, honouring the "a missing measurement is never zero" invariant: a
+* channel marked NOT known contributes no number at all and instead flags itself, so nothing
+* downstream can sum an unmeasured turn as free. Returns the spend it read (for the duration).
+*/
+function assignSpend(attrs, value) {
+	if (!isRecord(value)) return void 0;
+	const spend = value;
+	const tokens = isRecord(spend.tokens) ? spend.tokens : void 0;
+	if (spend.tokensKnown === false) attrs["tangle.supervise.tokens_known"] = false;
+	else if (tokens) {
+		if (typeof tokens.input === "number") attrs["llm.token_count.prompt"] = tokens.input;
+		if (typeof tokens.output === "number") attrs["llm.token_count.completion"] = tokens.output;
+	}
+	if (spend.usdKnown === false) attrs["tangle.supervise.cost_known"] = false;
+	else if (typeof spend.usd === "number" && Number.isFinite(spend.usd)) {
+		attrs["llm.cost_usd"] = spend.usd;
+		attrs["tangle.cost.usd"] = spend.usd;
+	}
+	if (typeof spend.iterations === "number") attrs["tangle.supervise.iterations"] = spend.iterations;
+	if (typeof spend.ms === "number" && spend.ms > 0) attrs["tangle.supervise.duration_ms"] = spend.ms;
+	if (typeof spend.boxMinutes === "number" && Number.isFinite(spend.boxMinutes)) attrs["tangle.platform.box_minutes"] = spend.boxMinutes;
+	if (spend.boxMinutesProvenance !== void 0) {
+		attrs["tangle.platform.box_minutes_provenance"] = spend.boxMinutesProvenance;
+		attrs["tangle.platform.box_minutes_known"] = spend.boxMinutesKnown === true;
+	}
+	if (spend.tokensProvenance !== void 0) attrs["tangle.supervise.tokens_provenance"] = spend.tokensProvenance;
+	return spend;
+}
+function assignBudget(attrs, value) {
+	if (!isRecord(value)) return;
+	const budget = value;
+	if (typeof budget.maxTokens === "number") attrs["tangle.supervise.budget.max_tokens"] = budget.maxTokens;
+	if (typeof budget.maxIterations === "number") attrs["tangle.supervise.budget.max_iterations"] = budget.maxIterations;
+	if (typeof budget.maxUsd === "number") attrs["tangle.supervise.budget.max_usd"] = budget.maxUsd;
+}
+/**
+* A trace id must be 32 hex characters. A caller-supplied one is used verbatim when it already is;
+* anything else (and the default) is DERIVED from the run id by content address — deterministic, so
+* a resumed run rejoins the trace its first process opened rather than forking a new one.
+*/
+function normalizeTraceId(traceId, runId) {
+	if (traceId && /^[0-9a-f]{32}$/i.test(traceId)) return traceId.toLowerCase();
+	return contentAddress(traceId ?? runId).slice(7, 39);
+}
+function msToNano(ms) {
+	return (BigInt(Number.isFinite(ms) ? Math.floor(ms) : 0) * 1000000n).toString();
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function record(value) {
+	return isRecord(value) ? value : {};
+}
+function str(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function truncate(value) {
+	return value.length > MAX_DETAIL_CHARS ? `${value.slice(0, MAX_DETAIL_CHARS)}…` : value;
 }
 //#endregion
 //#region src/runtime/supervise/driver-retry.ts
@@ -1621,6 +1622,7 @@ function buildSupervisorAgent(profile, deps, testBrain) {
 			...deps.continuityByProfile ? { continuityByProfile: deps.continuityByProfile } : {},
 			...deps.preflightSpawn ? { preflightSpawn: deps.preflightSpawn } : {},
 			...deps.resolveSpawnProfile ? { resolveSpawnProfile: deps.resolveSpawnProfile } : {},
+			...deps.spawnResourceRoot ? { spawnResourceRoot: deps.spawnResourceRoot } : {},
 			...deps.stopRule ? { stopRule: deps.stopRule } : {},
 			...deps.onProgressStop ? { onProgressStop: deps.onProgressStop } : {},
 			...deps.maxTurns !== void 0 ? { maxTurns: deps.maxTurns } : {},
@@ -1708,6 +1710,7 @@ function buildSupervisorAgent(profile, deps, testBrain) {
 				...deps.replaySettlements ? { replaySettlements: true } : {},
 				...deps.preflightSpawn ? { preflightSpawn: deps.preflightSpawn } : {},
 				...deps.resolveSpawnProfile ? { resolveSpawnProfile: deps.resolveSpawnProfile } : {},
+				...deps.spawnResourceRoot ? { spawnResourceRoot: deps.spawnResourceRoot } : {},
 				...deps.peerMail ? { peerMail: deps.peerMail } : {},
 				...priorCoordination?.questions.length ? { priorQuestions: priorCoordination.questions } : {},
 				...priorCoordination?.escalations?.length ? { priorEscalations: priorCoordination.escalations } : {},
@@ -2984,6 +2987,19 @@ function assertNoUncapturedExecutableOption(decisionData) {
 * detached and frozen; executable ports are copied as the exact references selected at intake.
 * Service internals intentionally remain live, while replacing a callback/service on the caller's
 * mutable options object can no longer change an in-flight run. */
+/** The directory a root manager's spawn may resolve an inline resource `path` under. Only a
+*  loopback bridge driver has one this process can read: its `cwd` is a directory on this host.
+*  A remote bridge, a provider sandbox, or an in-process driver with no cwd yields `undefined`. */
+function rootSpawnResourceRoot(backend) {
+	if (backend === void 0 || backend.backend !== "bridge" || backend.cwd === void 0) return void 0;
+	let host;
+	try {
+		host = new URL(backend.bridgeUrl).hostname;
+	} catch {
+		return;
+	}
+	return isLoopbackHost(host) ? resolve(backend.cwd) : void 0;
+}
 function captureSuperviseOptions(opts) {
 	assertSuperviseOptionKeys(opts, "supervise");
 	const { backend, coordination, driverBackend, deliverable, resolveDeliverable, router, compaction, watchWorkers, analysts, makeWorkerAgent, makeLeafAgent, resolveSpawnProfile, blobs, journal, probes, registry, hooks, otel, authorizeSpawn, authorizeMessage, driveHarness, resolveDriveHarness, resolveSupervisorTools, escalateQuestion, onCoordinationEvent, executeExtraTool, stopRule, onProgressStop, onDriverAttempt, onUnmetContract, workerRetry, onWorkerRetry, finalizer, now, signal, rootHandle, ...decisionData } = opts;
@@ -3301,6 +3317,7 @@ function superviseInternal(profile, task, opts, testBrain) {
 	const managerBackend = options.driverBackend ?? (options.rootDriverFromBackend === false ? void 0 : options.backend);
 	if (options.driveHarness && options.resolveDriveHarness) throw new ValidationError("supervise: provide driveHarness or resolveDriveHarness, not both");
 	const hasCustomDriveHarness = Boolean(options.driveHarness || options.resolveDriveHarness);
+	const spawnResourceRoot = hasCustomDriveHarness ? void 0 : rootSpawnResourceRoot(managerBackend);
 	const spawnPreflight = composeSpawnPreflights(profileToolSpawnPreflight(options.makeWorkerAgent === void 0, options.resolveSupervisorTools !== void 0), coordinationChannelSpawnPreflight(options.makeWorkerAgent === void 0, hasCustomDriveHarness, managerBackend, options.coordination), options.backend?.backend === "bridge" ? bridgeSpawnPreflight(options.backend) : void 0);
 	const driverMaterialization = hasCustomDriveHarness ? options.driveHarnessMaterialization ?? fullProfileMaterialization : managerBackend && automaticDriverBackendSupported(managerBackend, options.coordination) ? backendProfileMaterialization(managerBackend) : void 0;
 	if (isExternalSupervisor(canonicalProfile) && !options.driveHarness && !options.resolveDriveHarness && (!managerBackend || !automaticDriverBackendSupported(managerBackend, options.coordination))) throw new ValidationError(`supervise: external supervisor profile.harness=${JSON.stringify(canonicalProfile.harness)} requires a local bridge, a provider with authenticated coordination.publicUrl and runtime MCP attachments, or an explicit driveHarness with reachable coordination transport`);
@@ -3529,6 +3546,7 @@ function superviseInternal(profile, task, opts, testBrain) {
 			...options.coordination && isExternalSupervisor(canonicalProfile) ? { coordination: options.coordination } : {},
 			...spawnPreflight ? { preflightSpawn: spawnPreflight } : {},
 			...options.resolveSpawnProfile ? { resolveSpawnProfile: options.resolveSpawnProfile } : {},
+			...spawnResourceRoot === void 0 ? {} : { spawnResourceRoot },
 			...options.peerMail ? { peerMail: options.peerMail } : {},
 			...options.maxLiveWorkers !== void 0 ? { maxLiveWorkers: options.maxLiveWorkers } : {},
 			...options.router ? { router: options.router } : {},
@@ -3657,6 +3675,6 @@ function rootProviderModelEvidenceFromExecution(evidence) {
 	return evidence ?? rootProviderModelEvidence([]);
 }
 //#endregion
-export { serveCoordinationMcp as _, isPreSpawnExecutorFailure as a, mapExecutorResult as b, withWorkerSpawnRetry as c, resolveSupervisorProfile as d, supervisorAgent as f, defaultUnmetContractSteer as g, classifyDriverFailure as h, workerFromBackend as i, assertCoordinationBinding as l, DriverAttemptsExhaustedError as m, supervise as n, resolveWorkerSpawnRetry as o, supervisorAgentWithTestBrain as p, superviseWithTestBrain as r, retryPreSpawnRefusals as s, DEFAULT_AUTHORED_PROFILE_SECURITY_POLICY as t, coordinationProfileToolPrefix as u, createSupervisorSpanRecorder as v, gateOnDeliverable as y };
+export { createSupervisorSpanRecorder as _, isPreSpawnExecutorFailure as a, mapExecutorResult as b, withWorkerSpawnRetry as c, resolveSupervisorProfile as d, supervisorAgent as f, defaultUnmetContractSteer as g, classifyDriverFailure as h, workerFromBackend as i, assertCoordinationBinding as l, DriverAttemptsExhaustedError as m, supervise as n, resolveWorkerSpawnRetry as o, supervisorAgentWithTestBrain as p, superviseWithTestBrain as r, retryPreSpawnRefusals as s, DEFAULT_AUTHORED_PROFILE_SECURITY_POLICY as t, coordinationProfileToolPrefix as u, serveCoordinationMcp as v, gateOnDeliverable as y };
 
-//# sourceMappingURL=supervise-W_mtzswa.js.map
+//# sourceMappingURL=supervise-DRDPNM81.js.map