@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/domains/dispatch/extension.ts

@@ -1,3 +1,7 @@
+import { parseWorkerContextSeed } from "../../worker/context-seed.js";
+import { WORKER_STDIN_FRAME_MAX_BYTES } from "../../worker/protocol.js";
+import { WORKER_CONTEXT_PREAMBLE } from "../context/worker/select.js";
+import { persistWorkerContextSeed } from "../context/worker/store.js";
 /**
  * Dispatch domain wire-up (post-W5).
  *
@@ -17,7 +21,7 @@ import { BusChannels, type DispatchCompletedPayload, type DispatchRunIdentity }
 import { DEFAULT_SETTINGS, type DelegationToolGovernance } from "../../core/defaults.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
 import { gatewayRoutingObservationFromRecord } from "../../core/gateway-routing.js";
-import { GUARDRAIL_DEFAULTS } from "../../core/guardrails.js";
+import { GUARDRAIL_DEFAULTS, resolveGuardrail } from "../../core/guardrails.js";
 import { readClioVersion, readPiMonoVersion } from "../../core/package-root.js";
 import { canonicalizeExistingPath } from "../../core/path-canonical.js";
 import { protectedResidencyModels } from "../../core/residency-protection.js";
@@ -29,7 +33,7 @@ import {
 } from "../../core/response-schema.js";
 import { isSkillActivation, type SkillActivation } from "../../core/skill-activation.js";
 import { rawDurationMs } from "../../core/timers.js";
-import { isBuiltinToolName, type ToolName, ToolNames } from "../../core/tool-names.js";
+import { isBuiltinToolName, isHarnessExtensionToolName, type ToolName, ToolNames } from "../../core/tool-names.js";
 import {
 	type AcpDelegationRunHandle,
 	type AcpDelegationRunInput,
@@ -72,6 +76,7 @@ import {
 } from "../agents/spec.js";
 import type { ConfigContract } from "../config/contract.js";
 import type { ContextContract, ProjectPromptContext, ProjectStructuredContext } from "../context/contract.js";
+import { enabledHarnessExtensionToolNames } from "../extensions/command-tools.js";
 import type { MiddlewareContract } from "../middleware/contract.js";
 import { workerSafetyOneLiner } from "../prompts/compiler.js";
 import type { PromptsContract } from "../prompts/contract.js";
@@ -320,7 +325,10 @@ interface RunTokenMeter {
 	outputTokens: number;
 	cacheReadTokens: number;
 	cacheWriteTokens: number;
+	cacheWrite1hTokens?: number;
 	reasoningTokens: number;
+	/** Native calls are priced individually by the SDK, including cache TTLs and context tiers. */
+	costUsd?: number;
 }
 
 interface ActiveRun {
@@ -453,6 +461,7 @@ function sealRouteDecision(draft: RunReceiptDraft, decision: RouteDecisionV1): R
 export const UNKNOWN_PRICING_ADMISSION_ESTIMATE_USD = 1;
 
 function calculateUsageCostUsd(meter: RunTokenMeter, pricing: EffectivePricing["rates"]): number {
+	if (meter.costUsd !== undefined) return meter.costUsd;
 	if (pricing === null) return 0;
 	return (
 		(meter.inputTokens * pricing.input +
@@ -463,6 +472,39 @@ function calculateUsageCostUsd(meter: RunTokenMeter, pricing: EffectivePricing["
 	);
 }
 
+function accumulateNativeUsage(
+	meter: RunTokenMeter,
+	usage: Record<string, unknown>,
+	pricing: EffectivePricing["rates"],
+): void {
+	const count = (value: unknown): number =>
+		typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+	const call: RunTokenMeter = {
+		inputTokens: count(usage.input),
+		outputTokens: count(usage.output),
+		cacheReadTokens: count(usage.cacheRead),
+		cacheWriteTokens: count(usage.cacheWrite),
+		reasoningTokens: extractReasoningTokenCount(usage),
+	};
+	const reported = isRecord(usage.cost) ? usage.cost.total : undefined;
+	// An SDK total is already priced with per-call tiers, service tier
+	// and cache-write lifetime. Never reprice it from an aggregate token count.
+	// Retain the target-rate fallback only for workers that omit calculated
+	// cost. Zero remains zero; its provenance still comes from the target.
+	const callCost =
+		typeof reported === "number" && Number.isFinite(reported) && reported >= 0
+			? reported
+			: calculateUsageCostUsd(call, pricing);
+	meter.costUsd = (meter.costUsd ?? 0) + callCost;
+	meter.inputTokens += call.inputTokens;
+	meter.outputTokens += call.outputTokens;
+	meter.cacheReadTokens += call.cacheReadTokens;
+	meter.cacheWriteTokens += call.cacheWriteTokens;
+	if (typeof usage.cacheWrite1h === "number" && usage.cacheWrite1h >= 0 && usage.cacheWrite1h <= call.cacheWriteTokens)
+		meter.cacheWrite1hTokens = (meter.cacheWrite1hTokens ?? 0) + usage.cacheWrite1h;
+	meter.reasoningTokens += call.reasoningTokens;
+}
+
 /**
  * Output-token figure the admission estimate prices a route against. Settings
  * always carry `defaults.maxTokens`; the fallback covers the callers that
@@ -706,6 +748,7 @@ function reportDispatchDiagnostic(scope: string, error: unknown): void {
 }
 
 const OUTCOME_CODE_SPECIFICITY: ReadonlyArray<RunOutcomeCode> = [
+	"worker_context_exhausted",
 	"result_contract_exhausted",
 	"loop_guard_tools_disabled_exhausted",
 	"worker_tool_call_cap_exhausted",
@@ -1181,6 +1224,24 @@ export function buildDynamicPromptMessages(
 	dynamicContext: WorkerDynamicContext = {},
 ): WorkerPromptMessage[] {
 	const messages: WorkerPromptMessage[] = [];
+	if (req.contextSeed) {
+		const seed = parseWorkerContextSeed(req.contextSeed);
+		const body =
+			seed.provenance.mode === "fork"
+				? WORKER_CONTEXT_PREAMBLE
+				: seed.messages
+						.map((message) => {
+							if (message.role !== "user") throw new Error("worker context: invalid portable packet");
+							return typeof message.content === "string"
+								? message.content
+								: message.content
+										.filter((block) => block.type === "text")
+										.map((block) => block.text)
+										.join("\n");
+						})
+						.join("\n\n");
+		messages.push({ id: "dispatch-worker-context", body, contentHash: sha256(body) });
+	}
 	if (dynamicContext.workspace) {
 		const body = renderWorkerWorkspaceContext(dynamicContext.workspace);
 		messages.push({ id: "dispatch-workspace", body, contentHash: sha256(body) });
@@ -1259,6 +1320,19 @@ export function buildDynamicPromptMessages(
 	return messages;
 }
 
+function assertWorkerContextRequest(req: DispatchRequest, native: boolean): void {
+	const mode = req.context?.mode ?? "isolated";
+	if (mode === "isolated") {
+		if (req.contextSeed !== undefined) throw new Error("worker context: isolated request cannot inherit a seed");
+		return;
+	}
+	if (!req.contextSeed) throw new Error("worker context: inheritance requires a host-captured seed");
+	const seed = parseWorkerContextSeed(req.contextSeed);
+	if (seed.provenance.mode !== mode) throw new Error("worker context: seed mode differs from admitted request");
+	if (mode === "fork" && !native)
+		throw new Error("worker context: fork requires a native Pi runtime; use splice for external agents");
+}
+
 interface ResolvedTarget {
 	target: TargetDescriptor;
 	runtime: RuntimeDescriptor;
@@ -1601,6 +1675,7 @@ function effectiveToolNames(
 	 * here rather than leaving the model to spend budget finding that out.
 	 */
 	denied: ReadonlySet<string> = new Set(),
+	cwd = process.cwd(),
 ): ReadonlyArray<ToolName> {
 	if (!targetToolCapability(target)) return [];
 	// A hermetic process registers no network plane, so the worker's registry
@@ -1609,9 +1684,13 @@ function effectiveToolNames(
 	// attests; otherwise the run is refused for a mismatch instead of simply
 	// running without network.
 	const networkStripped = networkToolsDisabled();
+	const harnessTools =
+		target.runtime.kind === "http" && !writeConfined && allowedTools.some(isHarnessExtensionToolName)
+			? enabledHarnessExtensionToolNames(cwd)
+			: new Set<string>();
 	const names = allowedTools.filter(
 		(tool): tool is ToolName =>
-			isBuiltinToolName(tool) &&
+			(isBuiltinToolName(tool) || harnessTools.has(tool)) &&
 			tool !== ToolNames.AskUser &&
 			!(networkStripped && tool === ToolNames.WebFetch) &&
 			!denied.has(tool) &&
@@ -1995,6 +2074,10 @@ function buildDispatchWorkerSpec(input: DispatchWorkerSpecInput, config?: Config
 	// autonomy can only narrow (reviewer/judge runs pin read-only); a worker
 	// never exceeds the orchestrator's authority.
 	spec.autonomy = input.effectiveAutonomy;
+	if (input.req.contextSeed && input.target.runtime.kind === "http")
+		spec.contextSeed = parseWorkerContextSeed(input.req.contextSeed);
+	if (Buffer.byteLength(JSON.stringify(spec), "utf8") + 1 > WORKER_STDIN_FRAME_MAX_BYTES)
+		throw new Error("worker context: complete WorkerSpec exceeds the stdin frame budget; use a smaller splice");
 	return spec;
 }
 
@@ -3572,6 +3655,7 @@ export function createDispatchBundle(
 				providers,
 			);
 		let target = resolveTarget();
+		assertWorkerContextRequest(req, target.runtime.kind === "http");
 		const identity = (resolved: ResolvedTarget): string =>
 			JSON.stringify([
 				resolved.target.id,
@@ -3591,7 +3675,13 @@ export function createDispatchBundle(
 		const sessionAutonomy = settings?.safety.autonomy ?? "auto-edit";
 		const effectiveAutonomy = effectiveWorkerAutonomy(sessionAutonomy, req.autonomy, spec.capabilityClass);
 		const effectiveTools = withLedgerToolNarrowing(
-			effectiveToolNames(admission.allowedTools, target, pathScope.writeBoundaries.length > 0, deniedToolNames(req)),
+			effectiveToolNames(
+				admission.allowedTools,
+				target,
+				pathScope.writeBoundaries.length > 0,
+				deniedToolNames(req),
+				req.cwd ?? process.cwd(),
+			),
 			req,
 		);
 		assertPostRuntimeToolCompatibility(req.agentId, spec, effectiveTools, target);
@@ -3652,7 +3742,11 @@ export function createDispatchBundle(
 		});
 		const projectContextProvenance = projectContextProvenanceFor(tier, dynamicPromptMessages);
 		const dynamicText = dynamicPromptMessages.map((message) => message.body).join("\n\n");
-		const compiledPromptHash = promptCompositionHash([systemPrompt, dynamicText]);
+		const compiledPromptHash = promptCompositionHash([
+			systemPrompt,
+			dynamicText,
+			...(req.contextSeed ? [req.contextSeed.provenance.contentHash] : []),
+		]);
 		const staticCompositionHash = promptHash(systemPrompt);
 		const sessionShellHash = staticCompositionHash;
 		const dynamicHash = dynamicPromptMessages.length > 0 ? sha256(dynamicText) : sha256("");
@@ -3724,6 +3818,7 @@ export function createDispatchBundle(
 			// before the external agent is started.
 			dispatchResultContract(req, spec);
 		}
+		assertWorkerContextRequest(req, false);
 		if (!settings) throw new Error("dispatch: effective settings required for ACP delegation");
 		const configured = settings.integrations.externalAgents.entries.find((entry) => entry.id === agentId);
 		if (!configured) throw new Error(`dispatch: ACP delegation agent '${agentId}' not configured`);
@@ -3765,7 +3860,11 @@ export function createDispatchBundle(
 		});
 		const projectContextProvenance = projectContextProvenanceFor(tier, dynamicPromptMessages);
 		const dynamicText = dynamicPromptMessages.map((message) => message.body).join("\n\n");
-		const compiledPromptHash = promptCompositionHash([systemPrompt, dynamicText]);
+		const compiledPromptHash = promptCompositionHash([
+			systemPrompt,
+			dynamicText,
+			...(req.contextSeed ? [req.contextSeed.provenance.contentHash] : []),
+		]);
 		const staticCompositionHash = promptHash(systemPrompt);
 		const sessionShellHash = staticCompositionHash;
 		const dynamicHash = dynamicPromptMessages.length > 0 ? sha256(dynamicText) : sha256("");
@@ -3829,6 +3928,7 @@ export function createDispatchBundle(
 		const wireModelId = lifecycle.agentConfig.id;
 		assertTargetNotCoolingDown(req, targetId, runtimeId, wireModelId);
 
+		if (req.contextSeed) persistWorkerContextSeed(req.contextSeed);
 		assertBudgetAdmitsRoute(req, { rates: null, provenance: "unknown" }, settings);
 
 		const queuedIdentity =
@@ -3889,7 +3989,13 @@ export function createDispatchBundle(
 		}
 		timing.workerSpawnedAt = new Date(now()).toISOString();
 
-		const tokenMeter = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+		const tokenMeter: RunTokenMeter = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			reasoningTokens: 0,
+		};
 		const safetyDecisionCounts = { allowed: 0, blocked: 0, permissionRequested: 0 };
 		const blockedAttempts: SafetyBlockedAttempt[] = [];
 		const toolStats = new Map<string, ToolCallStat>();
@@ -4084,6 +4190,7 @@ export function createDispatchBundle(
 				node: LOCAL_RUN_NODE,
 				...(lifecycle.pipeline ? { pipeline: lifecycle.pipeline } : {}),
 				...(lifecycle.briefing ? { briefing: lifecycle.briefing } : {}),
+				...(req.contextSeed ? { workerContext: structuredClone(req.contextSeed.provenance) } : {}),
 				...(req.gate !== undefined ? { gate: req.gate } : {}),
 				...(req.council !== undefined ? { council: req.council } : {}),
 				...(req.plan !== undefined ? { plan: req.plan } : {}),
@@ -4255,6 +4362,7 @@ export function createDispatchBundle(
 				node: LOCAL_RUN_NODE,
 				...(lifecycle.pipeline ? { pipeline: lifecycle.pipeline } : {}),
 				...(lifecycle.briefing ? { briefing: lifecycle.briefing } : {}),
+				...(req.contextSeed ? { workerContext: structuredClone(req.contextSeed.provenance) } : {}),
 				...(req.gate !== undefined ? { gate: req.gate } : {}),
 				...(req.council !== undefined ? { council: req.council } : {}),
 				...(req.plan !== undefined ? { plan: req.plan } : {}),
@@ -4276,6 +4384,7 @@ export function createDispatchBundle(
 				outputTokenCount: tokenMeter.outputTokens,
 				cacheReadTokenCount: tokenMeter.cacheReadTokens,
 				cacheWriteTokenCount: tokenMeter.cacheWriteTokens,
+				...(tokenMeter.cacheWrite1hTokens === undefined ? {} : { cacheWrite1hTokenCount: tokenMeter.cacheWrite1hTokens }),
 				reasoningTokenCount: tokenMeter.reasoningTokens,
 				...(upstreamResponses.length > 0 ? { upstreamResponses: [...upstreamResponses] } : {}),
 				...(capturedOutput !== undefined ? { output: capturedOutput } : {}),
@@ -4362,6 +4471,7 @@ export function createDispatchBundle(
 				outputTokenCount: receipt.outputTokenCount ?? 0,
 				cacheReadTokenCount: receipt.cacheReadTokenCount ?? 0,
 				cacheWriteTokenCount: receipt.cacheWriteTokenCount ?? 0,
+				...(receipt.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1hTokenCount: receipt.cacheWrite1hTokenCount }),
 				reasoningTokenCount: receipt.reasoningTokenCount ?? 0,
 				staticShellHash: receipt.staticShellHash ?? null,
 				sessionShellHash: receipt.sessionShellHash ?? null,
@@ -4487,6 +4597,9 @@ export function createDispatchBundle(
 					dynamicHash: receiptDraft.dynamicHash ?? null,
 					cacheReadTokenCount: receiptDraft.cacheReadTokenCount ?? 0,
 					cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount ?? 0,
+					...(receiptDraft.cacheWrite1hTokenCount === undefined
+						? {}
+						: { cacheWrite1hTokenCount: receiptDraft.cacheWrite1hTokenCount }),
 					reasoningTokenCount: receiptDraft.reasoningTokenCount ?? 0,
 					heartbeatAt: heartbeatIso(acp.heartbeatAt),
 				};
@@ -4720,6 +4833,7 @@ export function createDispatchBundle(
 			shadow: () => observeShadowRoute(req, placed, settings),
 		});
 
+		if (req.contextSeed) persistWorkerContextSeed(req.contextSeed);
 		const queuedIdentity =
 			req.lineage === undefined && req.runIdHint !== undefined
 				? {
@@ -4772,31 +4886,44 @@ export function createDispatchBundle(
 				throw error;
 			}
 		})();
-		const tokenMeter = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, reasoningTokens: 0 };
+		const tokenMeter: RunTokenMeter = {
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			reasoningTokens: 0,
+		};
 		const safetyDecisionCounts = { allowed: 0, blocked: 0, permissionRequested: 0 };
 		const escalationCounts = { requested: 0, approved: 0, denied: 0, timedOut: 0 };
 		const blockedAttempts: SafetyBlockedAttempt[] = [];
-		const spec = buildDispatchWorkerSpec(
-			{
-				req,
-				pathScope: lifecycle.pathScope,
-				target: lifecycle.target,
-				admission: lifecycle.admission,
-				recipe: lifecycle.recipe,
-				systemPrompt: lifecycle.systemPrompt,
-				dynamicPromptMessages: lifecycle.dynamicPromptMessages,
-				promptSignature: lifecycle.promptSignature,
-				toolSignature: lifecycle.toolSignature,
-				dynamicHash: lifecycle.dynamicHash,
-				middlewareSnapshot: middleware.snapshot(),
-				protectedArtifactState,
-				apiKey: lifecycle.apiKey,
-				effectiveAutonomy: lifecycle.effectiveAutonomy,
-				budget: lifecycle.budget,
-				...(lifecycle.settings ? { settings: lifecycle.settings } : {}),
-			},
-			config ?? undefined,
-		);
+		let spec: WorkerSpec;
+		try {
+			spec = buildDispatchWorkerSpec(
+				{
+					req,
+					pathScope: lifecycle.pathScope,
+					target: lifecycle.target,
+					admission: lifecycle.admission,
+					recipe: lifecycle.recipe,
+					systemPrompt: lifecycle.systemPrompt,
+					dynamicPromptMessages: lifecycle.dynamicPromptMessages,
+					promptSignature: lifecycle.promptSignature,
+					toolSignature: lifecycle.toolSignature,
+					dynamicHash: lifecycle.dynamicHash,
+					middlewareSnapshot: middleware.snapshot(),
+					protectedArtifactState,
+					apiKey: lifecycle.apiKey,
+					effectiveAutonomy: lifecycle.effectiveAutonomy,
+					budget: lifecycle.budget,
+					...(lifecycle.settings ? { settings: lifecycle.settings } : {}),
+				},
+				config ?? undefined,
+			);
+		} catch (error) {
+			leaseSlot.release();
+			if (req.lineage === undefined) await failQueuedAssignment(capacityLease.assignmentId);
+			throw error;
+		}
 		// The agent ledger is orchestrator-owned. The worker sends a body and
 		// nothing else; every attribution field below is stamped from this
 		// process's own admission record, so no worker-supplied value can reach
@@ -5045,11 +5172,7 @@ export function createDispatchBundle(
 			}
 			if (event.type === "message_end" && event.message?.role === "assistant" && isRecord(event.message.usage)) {
 				const u = event.message.usage;
-				tokenMeter.inputTokens += typeof u.input === "number" ? u.input : 0;
-				tokenMeter.outputTokens += typeof u.output === "number" ? u.output : 0;
-				tokenMeter.cacheReadTokens += typeof u.cacheRead === "number" ? u.cacheRead : 0;
-				tokenMeter.cacheWriteTokens += typeof u.cacheWrite === "number" ? u.cacheWrite : 0;
-				tokenMeter.reasoningTokens += extractReasoningTokenCount(u);
+				accumulateNativeUsage(tokenMeter, u, lifecycle.target.effectivePricing.rates);
 				const requestedModelId = readStringOrNull(event.message.model);
 				const responseModelIdObservation = responseModelIdObservationFromRecord(event.message, "not-observed");
 				const differingResponseModelId = readStringOrNull(event.message.responseModel);
@@ -5205,6 +5328,7 @@ export function createDispatchBundle(
 					: {}),
 				...(lifecycle.pipeline ? { pipeline: lifecycle.pipeline } : {}),
 				...(lifecycle.briefing ? { briefing: lifecycle.briefing } : {}),
+				...(req.contextSeed ? { workerContext: structuredClone(req.contextSeed.provenance) } : {}),
 				...(req.gate !== undefined ? { gate: req.gate } : {}),
 				...(req.council !== undefined ? { council: req.council } : {}),
 				...(req.plan !== undefined ? { plan: req.plan } : {}),
@@ -5445,6 +5569,7 @@ export function createDispatchBundle(
 					: {}),
 				...(lifecycle.pipeline ? { pipeline: lifecycle.pipeline } : {}),
 				...(lifecycle.briefing ? { briefing: lifecycle.briefing } : {}),
+				...(req.contextSeed ? { workerContext: structuredClone(req.contextSeed.provenance) } : {}),
 				...(steering.length > 0 ? { steering: steering.map((entry) => ({ ...entry })) } : {}),
 				...(req.gate !== undefined ? { gate: req.gate } : {}),
 				...(req.council !== undefined ? { council: req.council } : {}),
@@ -5477,11 +5602,15 @@ export function createDispatchBundle(
 				outputTokenCount: tokenMeter.outputTokens,
 				cacheReadTokenCount: tokenMeter.cacheReadTokens,
 				cacheWriteTokenCount: tokenMeter.cacheWriteTokens,
+				...(tokenMeter.cacheWrite1hTokens === undefined ? {} : { cacheWrite1hTokenCount: tokenMeter.cacheWrite1hTokens }),
 				reasoningTokenCount: tokenMeter.reasoningTokens,
 				...(upstreamResponses.length > 0 ? { upstreamResponses: [...upstreamResponses] } : {}),
 				...(capturedOutput !== undefined ? { output: capturedOutput } : {}),
 				costUsd,
-				costProvenance: lifecycle.target.effectivePricing.provenance,
+				costProvenance:
+					lifecycle.target.effectivePricing.provenance === "unknown" && costUsd > 0
+						? "estimated"
+						: lifecycle.target.effectivePricing.provenance,
 				compiledPromptHash: lifecycle.compiledPromptHash,
 				staticCompositionHash: lifecycle.staticCompositionHash,
 				staticShellHash: lifecycle.staticCompositionHash,
@@ -5571,6 +5700,7 @@ export function createDispatchBundle(
 				outputTokenCount: receipt.outputTokenCount ?? 0,
 				cacheReadTokenCount: receipt.cacheReadTokenCount ?? 0,
 				cacheWriteTokenCount: receipt.cacheWriteTokenCount ?? 0,
+				...(receipt.cacheWrite1hTokenCount === undefined ? {} : { cacheWrite1hTokenCount: receipt.cacheWrite1hTokenCount }),
 				reasoningTokenCount: receipt.reasoningTokenCount ?? 0,
 				staticShellHash: receipt.staticShellHash ?? null,
 				sessionShellHash: receipt.sessionShellHash ?? null,
@@ -5816,6 +5946,9 @@ export function createDispatchBundle(
 					...(receiptDraft.cacheReadTokenCount !== undefined
 						? { cacheReadTokenCount: receiptDraft.cacheReadTokenCount }
 						: {}),
+					...(receiptDraft.cacheWrite1hTokenCount === undefined
+						? {}
+						: { cacheWrite1hTokenCount: receiptDraft.cacheWrite1hTokenCount }),
 					...(receiptDraft.cacheWriteTokenCount !== undefined
 						? { cacheWriteTokenCount: receiptDraft.cacheWriteTokenCount }
 						: {}),
@@ -6125,9 +6258,16 @@ export function createDispatchBundle(
 			targets.targetOrder,
 			providers,
 		);
+		assertWorkerContextRequest(req, target.runtime.kind === "http");
 		enforceCapabilityGate(target.target.id, target.modelCapabilities, req.requiredCapabilities);
 		const effectiveTools = withLedgerToolNarrowing(
-			effectiveToolNames(admission.allowedTools, target, pathScope.writeBoundaries.length > 0, deniedToolNames(req)),
+			effectiveToolNames(
+				admission.allowedTools,
+				target,
+				pathScope.writeBoundaries.length > 0,
+				deniedToolNames(req),
+				req.cwd ?? process.cwd(),
+			),
 			req,
 		);
 		assertPostRuntimeToolCompatibility(req.agentId, agentSpec, effectiveTools, target);
@@ -6590,7 +6730,11 @@ export function createDispatchBundle(
 			// No in-memory executor survives a process restart, so every active
 			// side-store lease from an earlier bundle is orphaned and must expire.
 			cleanupDispatchReservations({ startup: true, nowMs: now() });
-			ledger = openLedger();
+			ledger = openLedger({
+				get maxRuns() {
+					return getEffectiveSettings()?.fleet?.history?.maxRuns ?? resolveGuardrail("maxDispatchRuns");
+				},
+			});
 			// Symphony P10: restart recovery from durable artifacts. Adopt
 			// receipts whose ledger rows were lost to a crash between
 			// recordReceipt() and persist(); quarantine tampered ones.
@@ -6720,6 +6864,7 @@ export function createDispatchBundle(
 			const meter = run.meter;
 			const totalTokens = meter.inputTokens + meter.outputTokens + meter.cacheReadTokens + meter.cacheWriteTokens;
 			const costUsd = calculateUsageCostUsd(meter, run.pricing);
+			const costProvenance = run.costProvenance === "unknown" && costUsd > 0 ? "estimated" : run.costProvenance;
 			const startedMs = Date.parse(run.startedAt);
 			const elapsedMs = Number.isFinite(startedMs) ? Math.max(0, tickNow - startedMs) : 0;
 			const timing = deriveRunPhaseDurations(run.timing, run.startedAt, new Date(tickNow).toISOString());
@@ -6737,14 +6882,14 @@ export function createDispatchBundle(
 				timing,
 				tokens: { input: meter.inputTokens, output: meter.outputTokens, total: totalTokens },
 				costUsd,
-				costProvenance: run.costProvenance,
+				costProvenance,
 				node: run.node !== null ? { ...run.node } : null,
 			});
 			totals.inputTokens += meter.inputTokens;
 			totals.outputTokens += meter.outputTokens;
 			totals.totalTokens += totalTokens;
 			totals.costUsd += costUsd;
-			costAmounts.push({ usd: costUsd, provenance: run.costProvenance });
+			costAmounts.push({ usd: costUsd, provenance: costProvenance });
 			totals.runtimeSeconds += elapsedMs / 1000;
 		}
 		const retrying = [...retryQueue.values()].map((entry) => ({

package/src/domains/dispatch/fleet-plan.ts

@@ -1,3 +1,4 @@
+import { type FleetCommandRegistry, resolveFleetCommandArgs } from "../agents/fleet-commands.js";
 /**
  * Fleet contract to execution plan.
  *
@@ -19,9 +20,11 @@ import {
 	type FleetContract,
 	type FleetContractStep,
 	type FleetStepScope,
+	fleetCodeSteps,
 	fleetLoopCheckStepId,
 	fleetLoopRepairStepId,
 	fleetStepWriteBoundary,
+	validateFleetCommands,
 } from "../agents/fleet-contract.js";
 import type { ResultContract } from "../agents/result-contract.js";
 import type { AgentAutomationAuthority } from "../agents/spec.js";
@@ -58,6 +61,8 @@ export interface FleetPlanAgentResolution {
 }
 
 export interface CompileFleetPlanInput {
+	commands?: FleetCommandRegistry | null;
+	vars?: Readonly<Record<string, string>>;
 	contract: FleetContract;
 	/**
 	 * Rendered prompt body. It describes the whole chain, so every agent node
@@ -117,6 +122,9 @@ function declaredLoops(steps: ReadonlyArray<FleetContractStep>): Map<string, Exe
 
 export function compileFleetExecutionPlan(input: CompileFleetPlanInput): ExecutionPlan {
 	const { contract, task, resolveAgent } = input;
+	if (input.commands !== undefined) validateFleetCommands(contract, input.commands, input.vars ?? {});
+	else if (fleetCodeSteps(contract).some((step) => (step.args?.length ?? 0) > 0))
+		throw new Error("fleet code args: admission requires the operator command registry");
 	const loops = declaredLoops(contract.steps);
 	const steps: ExecutionPlanStepInput[] = [];
 
@@ -206,6 +214,7 @@ export function compileFleetExecutionPlan(input: CompileFleetPlanInput): Executi
 				kind: "code",
 				id: step.id,
 				commandId: step.command,
+				...(step.args ? { args: resolveFleetCommandArgs(step.args, input.vars) } : {}),
 				scope: step.scope,
 				dependencies,
 				...boundary(step.scope, step.writes),
@@ -225,6 +234,7 @@ export function compileFleetExecutionPlan(input: CompileFleetPlanInput): Executi
 					kind: "code",
 					id: checkId,
 					commandId: step.check.command,
+					...(step.check.args ? { args: resolveFleetCommandArgs(step.check.args, input.vars) } : {}),
 					scope: step.check.scope,
 					dependencies: checkDependencies,
 					...boundary(step.check.scope, step.check.writes),

package/src/domains/dispatch/fleet-run.ts

@@ -689,6 +689,7 @@ export async function executeFleetRun(input: ExecuteFleetRunInput): Promise<Flee
 				}
 				const originalMessage = isCommit ? commitMessageFor(step, priorResults) : null;
 				const outcome = await runCodeStep({
+					...(step.args ? { args: step.args } : {}),
 					stepId: step.id,
 					command,
 					workspaceRoot,

package/src/domains/dispatch/index.ts

@@ -22,6 +22,7 @@ export type {
 	DispatchAssignment,
 } from "./assignment.js";
 export type { AssignmentVerdictOwner, DurableAssignmentRecord } from "./assignment-store.js";
+export { endpointCapacityUsage } from "./capacity-lease.js";
 export type { CodeStepOutcome, CodeStepRecord, CodeStepRunInput } from "./code-step.js";
 export {
 	canonicalCodeReport,

package/src/domains/dispatch/orphan-recovery.ts

@@ -58,6 +58,7 @@ function envelopeFromReceipt(receipt: RunReceipt, status: RunStatus, receiptPath
 		task: receipt.task,
 		...(receipt.budget !== undefined ? { budget: receipt.budget } : {}),
 		...(receipt.briefing !== undefined ? { briefing: receipt.briefing } : {}),
+		...(receipt.workerContext !== undefined ? { workerContext: receipt.workerContext } : {}),
 		...(receipt.steering !== undefined ? { steering: receipt.steering } : {}),
 		targetId: receipt.targetId,
 		wireModelId: receipt.wireModelId,
@@ -77,6 +78,7 @@ function envelopeFromReceipt(receipt: RunReceipt, status: RunStatus, receiptPath
 	};
 	if (receipt.cacheReadTokenCount !== undefined) envelope.cacheReadTokenCount = receipt.cacheReadTokenCount;
 	if (receipt.cacheWriteTokenCount !== undefined) envelope.cacheWriteTokenCount = receipt.cacheWriteTokenCount;
+	if (receipt.cacheWrite1hTokenCount !== undefined) envelope.cacheWrite1hTokenCount = receipt.cacheWrite1hTokenCount;
 	if (receipt.reasoningTokenCount !== undefined) envelope.reasoningTokenCount = receipt.reasoningTokenCount;
 	if (receipt.inputTokenCount !== undefined) envelope.inputTokenCount = receipt.inputTokenCount;
 	if (receipt.outputTokenCount !== undefined) envelope.outputTokenCount = receipt.outputTokenCount;

package/src/domains/dispatch/receipt-integrity.ts

@@ -114,6 +114,7 @@ export const RECEIPT_INTEGRITY_FIELD_COVERAGE = {
 	outputTokenCount: true,
 	cacheReadTokenCount: true,
 	cacheWriteTokenCount: true,
+	cacheWrite1hTokenCount: true,
 	reasoningTokenCount: true,
 	upstreamResponses: true,
 	output: true,
@@ -155,6 +156,7 @@ export const RECEIPT_INTEGRITY_FIELD_COVERAGE = {
 	ledgerContribution: true,
 	sessionId: true,
 	briefing: true,
+	workerContext: true,
 	outcomeCode: true,
 	steering: true,
 	routeDecision: true,
@@ -210,6 +212,7 @@ function ledgerDigestFields(envelope: RunEnvelope): Record<string, unknown> {
 		tokenCount: envelope.tokenCount,
 		cacheReadTokenCount: envelope.cacheReadTokenCount,
 		cacheWriteTokenCount: envelope.cacheWriteTokenCount,
+		cacheWrite1hTokenCount: envelope.cacheWrite1hTokenCount,
 		reasoningTokenCount: envelope.reasoningTokenCount,
 		staticShellHash: envelope.staticShellHash,
 		sessionShellHash: envelope.sessionShellHash,
@@ -232,6 +235,7 @@ function ledgerDigestFields(envelope: RunEnvelope): Record<string, unknown> {
 		promptSignature: envelope.promptSignature ?? null,
 		toolSignature: envelope.toolSignature ?? null,
 		briefing: envelope.briefing ?? null,
+		...(envelope.workerContext !== undefined ? { workerContext: envelope.workerContext } : {}),
 		outcomeCode: envelope.outcomeCode ?? null,
 		steering: envelope.steering ?? null,
 	};
@@ -364,6 +368,7 @@ function firstLedgerMismatch(receipt: RunReceipt, envelope: RunEnvelope): string
 		["tokenCount", receipt.tokenCount, envelope.tokenCount],
 		["cacheReadTokenCount", receipt.cacheReadTokenCount ?? 0, envelope.cacheReadTokenCount ?? 0],
 		["cacheWriteTokenCount", receipt.cacheWriteTokenCount ?? 0, envelope.cacheWriteTokenCount ?? 0],
+		["cacheWrite1hTokenCount", receipt.cacheWrite1hTokenCount ?? 0, envelope.cacheWrite1hTokenCount ?? 0],
 		["reasoningTokenCount", receipt.reasoningTokenCount ?? 0, envelope.reasoningTokenCount ?? 0],
 		["staticShellHash", receipt.staticShellHash ?? null, envelope.staticShellHash ?? null],
 		["sessionShellHash", receipt.sessionShellHash ?? null, envelope.sessionShellHash ?? null],
@@ -379,6 +384,8 @@ function firstLedgerMismatch(receipt: RunReceipt, envelope: RunEnvelope): string
 		if (!Object.is(receiptValue, ledgerValue)) return field;
 	}
 	if (canonicalJson(receipt.briefing ?? null) !== canonicalJson(envelope.briefing ?? null)) return "briefing";
+	if (canonicalJson(receipt.workerContext ?? null) !== canonicalJson(envelope.workerContext ?? null))
+		return "workerContext";
 	if (canonicalJson(receipt.budget ?? null) !== canonicalJson(envelope.budget ?? null)) return "budget";
 	if (canonicalJson(receipt.steering ?? null) !== canonicalJson(envelope.steering ?? null)) return "steering";
 	return null;

package/src/domains/dispatch/state.ts

@@ -239,7 +239,6 @@ function capRuns(all: RunEnvelope[], maxRuns: number): RunEnvelope[] {
 }
 
 export function openLedger(opts?: LedgerOptions): Ledger {
-	const maxRuns = resolveMaxRuns(opts?.maxRuns);
 	let runs: RunEnvelope[] = readRuns();
 	// Ids this process has written since the last successful persist. See
 	// mergeRunsById: this is what separates our writes from a sibling's rows we
@@ -262,6 +261,7 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 				task: input.task,
 				...(input.budget !== undefined ? { budget: structuredClone(input.budget) } : {}),
 				...(input.briefing !== undefined ? { briefing: structuredClone(input.briefing) } : {}),
+				...(input.workerContext !== undefined ? { workerContext: structuredClone(input.workerContext) } : {}),
 				...(input.steering !== undefined ? { steering: structuredClone(input.steering) } : {}),
 				targetId: input.targetId,
 				wireModelId: input.wireModelId,
@@ -368,7 +368,7 @@ export function openLedger(opts?: LedgerOptions): Ledger {
 				if (stateRootRemoved()) return;
 				const diskRuns = readRuns();
 				const merged = mergeRunsById(diskRuns, runs, dirty);
-				const capped = capRuns(merged, maxRuns);
+				const capped = capRuns(merged, resolveMaxRuns(opts?.maxRuns));
 				runs = capped;
 				atomicWrite(target, JSON.stringify(capped, null, 2));
 				// A run that left the ring has no ledger row to view any more, so its