@iowarp/clio-coder 0.3.3 → 0.3.6

package/src/domains/dispatch/budget-envelope.ts

@@ -0,0 +1,396 @@
+import type { WorkerBudget } from "../../worker/spec-contract.js";
+import type { AgentBudget, AgentBudgetPhase } from "../agents/recipe.js";
+
+/** Invocation-level phase requested by dispatch. */
+export interface DispatchBudgetPhase {
+	toolCalls: number;
+	readReserve: number;
+}
+
+/** Typed invocation request. The ceiling preauthorizes growth on a later phase. */
+export interface DispatchBudgetRequest extends DispatchBudgetPhase {
+	retryRevision?: DispatchBudgetPhase;
+}
+
+export type BudgetEnvelopeReasonCode =
+	| "global-cap-clamp"
+	| "read-reserve-unavailable-clamp"
+	| "read-reserve-cap-clamp"
+	| "retry-growth-authorized"
+	| "retry-growth-denied"
+	| "revision-growth-authorized"
+	| "revision-growth-denied";
+
+export interface BudgetEnvelopeReason {
+	code: BudgetEnvelopeReasonCode;
+	detail: string;
+}
+
+export interface RunToolBudgetEnvelope {
+	version: 1;
+	policy: {
+		recipeId: string;
+		default: AgentBudgetPhase & { synthesis: boolean };
+		maximum: AgentBudgetPhase;
+		exact: boolean;
+	};
+	request: DispatchBudgetRequest | null;
+	effective: WorkerBudget;
+	reasons: ReadonlyArray<BudgetEnvelopeReason>;
+}
+
+export type BudgetAdmissionDenialCode =
+	| "exact-recipe-policy"
+	| "recipe-maximum"
+	| "global-cap"
+	| "ceiling-below-request";
+
+export class BudgetAdmissionError extends Error {
+	readonly code: BudgetAdmissionDenialCode;
+
+	constructor(code: BudgetAdmissionDenialCode, message: string) {
+		super(`dispatch: budget admission denied (${code}): ${message}`);
+		this.name = "BudgetAdmissionError";
+		this.code = code;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function clonePhase(value: unknown, prefix: string): DispatchBudgetPhase {
+	if (!isRecord(value)) throw new Error(`${prefix} must be an object`);
+	for (const key of Object.keys(value)) {
+		if (key !== "toolCalls" && key !== "readReserve") throw new Error(`${prefix}.${key} is unknown`);
+	}
+	for (const key of ["toolCalls", "readReserve"] as const) {
+		if (!Object.hasOwn(value, key)) throw new Error(`${prefix}.${key} is required`);
+	}
+	const toolCalls = value.toolCalls;
+	if (typeof toolCalls !== "number" || !Number.isSafeInteger(toolCalls) || toolCalls <= 0) {
+		throw new Error(`${prefix}.toolCalls must be a positive safe integer`);
+	}
+	const readReserve = value.readReserve;
+	if (typeof readReserve !== "number" || !Number.isSafeInteger(readReserve) || readReserve < 0) {
+		throw new Error(`${prefix}.readReserve must be a non-negative safe integer`);
+	}
+	if (readReserve >= toolCalls) throw new Error(`${prefix}.readReserve must be less than ${prefix}.toolCalls`);
+	return { toolCalls, readReserve };
+}
+
+/** Strict validation and cloning for model, CLI, and persisted request inputs. */
+export function cloneDispatchBudgetRequest(value: unknown, prefix = "budget"): DispatchBudgetRequest {
+	if (!isRecord(value)) throw new Error(`${prefix} must be an object`);
+	for (const key of Object.keys(value)) {
+		if (key !== "toolCalls" && key !== "readReserve" && key !== "retryRevision") {
+			throw new Error(`${prefix}.${key} is unknown`);
+		}
+	}
+	const phase = clonePhase({ toolCalls: value.toolCalls, readReserve: value.readReserve }, prefix);
+	const retryRevision =
+		value.retryRevision === undefined ? undefined : clonePhase(value.retryRevision, `${prefix}.retryRevision`);
+	return { ...phase, ...(retryRevision === undefined ? {} : { retryRevision }) };
+}
+
+function freezeEnvelope(envelope: RunToolBudgetEnvelope): RunToolBudgetEnvelope {
+	Object.freeze(envelope.policy.default);
+	Object.freeze(envelope.policy.maximum);
+	Object.freeze(envelope.policy);
+	if (envelope.request !== null) {
+		if (envelope.request.retryRevision !== undefined) Object.freeze(envelope.request.retryRevision);
+		Object.freeze(envelope.request);
+	}
+	Object.freeze(envelope.effective);
+	for (const reason of envelope.reasons) Object.freeze(reason);
+	Object.freeze(envelope.reasons);
+	return Object.freeze(envelope);
+}
+
+function phaseWithin(candidate: DispatchBudgetPhase, maximum: AgentBudgetPhase): boolean {
+	return candidate.toolCalls <= maximum.toolCalls && candidate.readReserve <= maximum.readReserve;
+}
+
+function samePhase(left: DispatchBudgetPhase, right: AgentBudgetPhase): boolean {
+	return left.toolCalls === right.toolCalls && left.readReserve === right.readReserve;
+}
+
+function assertRequestAdmitted(input: { request: DispatchBudgetRequest; policy: AgentBudget; hardCap: number }): void {
+	const { request, policy, hardCap } = input;
+	const authoredMaximum = policy.maximum ?? policy;
+	if (policy.maximum === undefined && !samePhase(request, policy)) {
+		throw new BudgetAdmissionError(
+			"exact-recipe-policy",
+			`the recipe pins ${policy.toolCalls} tool calls with a read reserve of ${policy.readReserve}`,
+		);
+	}
+	if (!phaseWithin(request, authoredMaximum)) {
+		throw new BudgetAdmissionError(
+			"recipe-maximum",
+			`the requested phase ${request.toolCalls}/${request.readReserve} exceeds recipe maximum ${authoredMaximum.toolCalls}/${authoredMaximum.readReserve}`,
+		);
+	}
+	if (request.toolCalls > hardCap) {
+		throw new BudgetAdmissionError(
+			"global-cap",
+			`the requested ${request.toolCalls} tool calls exceed the operator cap of ${hardCap}`,
+		);
+	}
+	const ceiling = request.retryRevision;
+	if (ceiling === undefined) return;
+	if (ceiling.toolCalls < request.toolCalls || ceiling.readReserve < request.readReserve) {
+		throw new BudgetAdmissionError(
+			"ceiling-below-request",
+			`retryRevision ${ceiling.toolCalls}/${ceiling.readReserve} must not be smaller than the requested phase ${request.toolCalls}/${request.readReserve}`,
+		);
+	}
+	if (policy.maximum === undefined && !samePhase(ceiling, policy)) {
+		throw new BudgetAdmissionError(
+			"exact-recipe-policy",
+			`the recipe pins ${policy.toolCalls} tool calls with a read reserve of ${policy.readReserve}`,
+		);
+	}
+	if (!phaseWithin(ceiling, authoredMaximum)) {
+		throw new BudgetAdmissionError(
+			"recipe-maximum",
+			`retryRevision ${ceiling.toolCalls}/${ceiling.readReserve} exceeds recipe maximum ${authoredMaximum.toolCalls}/${authoredMaximum.readReserve}`,
+		);
+	}
+	if (ceiling.toolCalls > hardCap) {
+		throw new BudgetAdmissionError(
+			"global-cap",
+			`retryRevision ${ceiling.toolCalls} exceeds the operator cap of ${hardCap}`,
+		);
+	}
+}
+
+export interface ResolveToolBudgetEnvelopeInput {
+	recipeId: string;
+	policy: AgentBudget;
+	request?: DispatchBudgetRequest;
+	hardCap: number;
+	hasReadTool: boolean;
+	retry: boolean;
+	revision: boolean;
+}
+
+/** Resolve the one immutable envelope used by admission, enforcement, and evidence. */
+export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput): RunToolBudgetEnvelope {
+	if (!Number.isSafeInteger(input.hardCap) || input.hardCap <= 0) {
+		throw new Error("dispatch: worker tool-call cap must be a positive safe integer");
+	}
+	if (input.request !== undefined)
+		assertRequestAdmitted({ request: input.request, policy: input.policy, hardCap: input.hardCap });
+
+	const request = input.request === undefined ? null : cloneDispatchBudgetRequest(input.request);
+	const base = request ?? input.policy;
+	const reasons: BudgetEnvelopeReason[] = [];
+	let selected: DispatchBudgetPhase = base;
+	const phaseKind = input.retry ? "retry" : input.revision ? "revision" : null;
+	if (phaseKind !== null) {
+		const ceiling = request?.retryRevision;
+		if (ceiling !== undefined && !samePhase(ceiling, base)) {
+			selected = ceiling;
+			reasons.push({
+				code: phaseKind === "retry" ? "retry-growth-authorized" : "revision-growth-authorized",
+				detail: `${phaseKind} phase grew from ${base.toolCalls}/${base.readReserve} to the preauthorized ceiling ${ceiling.toolCalls}/${ceiling.readReserve}`,
+			});
+		} else {
+			reasons.push({
+				code: phaseKind === "retry" ? "retry-growth-denied" : "revision-growth-denied",
+				detail:
+					ceiling === undefined
+						? `${phaseKind} phase retained ${base.toolCalls}/${base.readReserve} because the original request declared no ceiling`
+						: `${phaseKind} phase retained ${base.toolCalls}/${base.readReserve} because the declared ceiling did not authorize growth`,
+			});
+		}
+	}
+	const revisionCeiling = phaseKind === null ? request?.retryRevision : undefined;
+	if (revisionCeiling !== undefined && !samePhase(revisionCeiling, selected)) {
+		reasons.push({
+			code: "revision-growth-authorized",
+			detail: `a result-contract revision may grow from ${selected.toolCalls}/${selected.readReserve} to the preauthorized ceiling ${revisionCeiling.toolCalls}/${revisionCeiling.readReserve}`,
+		});
+	}
+
+	let toolCalls = selected.toolCalls;
+	if (toolCalls > input.hardCap) {
+		reasons.push({
+			code: "global-cap-clamp",
+			detail: `tool calls were clamped from ${toolCalls} to the operator cap of ${input.hardCap}`,
+		});
+		toolCalls = input.hardCap;
+	}
+	let readReserve = selected.readReserve;
+	if (!input.hasReadTool && readReserve > 0) {
+		reasons.push({
+			code: "read-reserve-unavailable-clamp",
+			detail: `read reserve was clamped from ${readReserve} to 0 because the read tool is unavailable`,
+		});
+		readReserve = 0;
+	}
+	const maximumEffectiveReserve = Math.max(0, toolCalls - 1);
+	if (readReserve > maximumEffectiveReserve) {
+		reasons.push({
+			code: "read-reserve-cap-clamp",
+			detail: `read reserve was clamped from ${readReserve} to ${maximumEffectiveReserve} after the tool-call cap`,
+		});
+		readReserve = maximumEffectiveReserve;
+	}
+	let effectiveRevision: DispatchBudgetPhase | undefined;
+	if (revisionCeiling !== undefined && !samePhase(revisionCeiling, selected)) {
+		let revisionReadReserve = revisionCeiling.readReserve;
+		if (!input.hasReadTool && revisionReadReserve > 0) {
+			reasons.push({
+				code: "read-reserve-unavailable-clamp",
+				detail: `result-contract revision read reserve was clamped from ${revisionReadReserve} to 0 because the read tool is unavailable`,
+			});
+			revisionReadReserve = 0;
+		}
+		effectiveRevision = { toolCalls: revisionCeiling.toolCalls, readReserve: revisionReadReserve };
+	}
+
+	const authoredMaximum = input.policy.maximum ?? input.policy;
+	return freezeEnvelope({
+		version: 1,
+		policy: {
+			recipeId: input.recipeId,
+			default: {
+				toolCalls: input.policy.toolCalls,
+				readReserve: input.policy.readReserve,
+				synthesis: input.policy.synthesis,
+			},
+			maximum: { toolCalls: authoredMaximum.toolCalls, readReserve: authoredMaximum.readReserve },
+			exact: input.policy.maximum === undefined,
+		},
+		request,
+		effective: {
+			toolCalls,
+			readReserve,
+			synthesis: input.policy.synthesis,
+			hardCap: input.hardCap,
+			...(effectiveRevision === undefined ? {} : { revision: effectiveRevision }),
+		},
+		reasons,
+	});
+}
+
+export function formatBudgetPolicy(envelope: RunToolBudgetEnvelope): string {
+	const policy = envelope.policy;
+	const range = policy.exact
+		? `exact ${policy.default.toolCalls}/${policy.default.readReserve}`
+		: `default ${policy.default.toolCalls}/${policy.default.readReserve}, max ${policy.maximum.toolCalls}/${policy.maximum.readReserve}`;
+	return `${policy.recipeId} ${range}, synthesis=${policy.default.synthesis ? "on" : "off"}`;
+}
+
+export function formatBudgetRequest(envelope: RunToolBudgetEnvelope): string {
+	const request = envelope.request;
+	if (request === null) return "recipe default";
+	const ceiling = request.retryRevision;
+	return ceiling === undefined
+		? `${request.toolCalls}/${request.readReserve}, no retry/revision growth`
+		: `${request.toolCalls}/${request.readReserve}, retry/revision ceiling ${ceiling.toolCalls}/${ceiling.readReserve}`;
+}
+
+export function formatEffectiveBudget(envelope: RunToolBudgetEnvelope): string {
+	const budget = envelope.effective;
+	const revision = budget.revision
+		? `, result revision ${budget.revision.toolCalls}/${budget.revision.readReserve}`
+		: "";
+	return `${budget.toolCalls}/${budget.readReserve}${revision}, lifetime cap ${budget.hardCap}, synthesis=${budget.synthesis ? "on" : "off"}`;
+}
+
+export function formatBudgetReasons(envelope: RunToolBudgetEnvelope): string {
+	return envelope.reasons.length === 0 ? "none" : envelope.reasons.map((reason) => reason.code).join(",");
+}
+
+const BUDGET_REASON_CODES: ReadonlySet<string> = new Set<BudgetEnvelopeReasonCode>([
+	"global-cap-clamp",
+	"read-reserve-unavailable-clamp",
+	"read-reserve-cap-clamp",
+	"retry-growth-authorized",
+	"retry-growth-denied",
+	"revision-growth-authorized",
+	"revision-growth-denied",
+]);
+
+/** Safely project an envelope that crossed a persistence or event boundary. */
+export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelope | undefined {
+	try {
+		if (!isRecord(value) || value.version !== 1 || !isRecord(value.policy) || !isRecord(value.effective)) {
+			return undefined;
+		}
+		const recipeId = value.policy.recipeId;
+		if (typeof recipeId !== "string" || recipeId.length === 0 || typeof value.policy.exact !== "boolean") {
+			return undefined;
+		}
+		if (!isRecord(value.policy.default) || typeof value.policy.default.synthesis !== "boolean") return undefined;
+		const defaultPhase = clonePhase(
+			{ toolCalls: value.policy.default.toolCalls, readReserve: value.policy.default.readReserve },
+			"budget.policy.default",
+		);
+		const maximum = clonePhase(value.policy.maximum, "budget.policy.maximum");
+		const request = value.request === null ? null : cloneDispatchBudgetRequest(value.request);
+		const effectivePhase = clonePhase(
+			{ toolCalls: value.effective.toolCalls, readReserve: value.effective.readReserve },
+			"budget.effective",
+		);
+		const revision =
+			value.effective.revision === undefined
+				? undefined
+				: clonePhase(value.effective.revision, "budget.effective.revision");
+		if (
+			typeof value.effective.synthesis !== "boolean" ||
+			typeof value.effective.hardCap !== "number" ||
+			!Number.isSafeInteger(value.effective.hardCap) ||
+			value.effective.hardCap <= 0 ||
+			!Array.isArray(value.reasons)
+		) {
+			return undefined;
+		}
+		if (
+			maximum.toolCalls < defaultPhase.toolCalls ||
+			maximum.readReserve < defaultPhase.readReserve ||
+			(value.policy.exact && !samePhase(maximum, defaultPhase)) ||
+			effectivePhase.toolCalls > value.effective.hardCap ||
+			value.effective.synthesis !== value.policy.default.synthesis ||
+			(revision !== undefined &&
+				(revision.toolCalls < effectivePhase.toolCalls ||
+					revision.toolCalls > value.effective.hardCap ||
+					(revision.toolCalls === effectivePhase.toolCalls && revision.readReserve <= effectivePhase.readReserve)))
+		) {
+			return undefined;
+		}
+		const reasons: BudgetEnvelopeReason[] = [];
+		for (const reason of value.reasons) {
+			if (
+				!isRecord(reason) ||
+				typeof reason.code !== "string" ||
+				!BUDGET_REASON_CODES.has(reason.code) ||
+				typeof reason.detail !== "string"
+			) {
+				return undefined;
+			}
+			reasons.push({ code: reason.code as BudgetEnvelopeReasonCode, detail: reason.detail });
+		}
+		return freezeEnvelope({
+			version: 1,
+			policy: {
+				recipeId,
+				default: { ...defaultPhase, synthesis: value.policy.default.synthesis },
+				maximum,
+				exact: value.policy.exact,
+			},
+			request,
+			effective: {
+				...effectivePhase,
+				synthesis: value.effective.synthesis,
+				hardCap: value.effective.hardCap,
+				...(revision === undefined ? {} : { revision }),
+			},
+			reasons,
+		});
+	} catch {
+		return undefined;
+	}
+}

package/src/domains/dispatch/contract.ts

@@ -6,6 +6,7 @@ import type { ProtectedArtifactState } from "../safety/protected-artifacts.js";
 import type { AssignmentId, DispatchAssignment } from "./assignment.js";
 import type { DurableAssignmentRecord } from "./assignment-store.js";
 import type { DetachedBatchRecord, RegisterDetachedBatchInput } from "./batch-store.js";
+import type { RunToolBudgetEnvelope } from "./budget-envelope.js";
 import type { ExecutionRole } from "./execution-role.js";
 import type { DispatchReservationRecord, ReservationTopology } from "./reservation-store.js";
 import type { ApprovedAssignmentRoute } from "./route-approval.js";
@@ -111,6 +112,7 @@ export interface DispatchSnapshot {
 		outcomePhase: string;
 		heartbeat: "alive" | "stale" | "dead" | "n/a";
 		lineage: RunLineage;
+		budget?: RunToolBudgetEnvelope;
 		startedAt: string;
 		/** Execution-only elapsed time retained for runtime monitoring. */
 		elapsedMs: number;

package/src/domains/dispatch/extension.ts

@@ -19,6 +19,7 @@ import { GUARDRAIL_DEFAULTS } 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";
+import { responseModelIdObservationFromRecord } from "../../core/response-model-id.js";
 import {
 	responseSchemaConflictsWithTools,
 	runtimeSpeaksResponseSchemaDialect,
@@ -134,6 +135,7 @@ import {
 	registerDetachedBatch,
 } from "./batch-store.js";
 import { type BatchState, createBatch, onRunComplete, snapshotBatch } from "./batch-tracker.js";
+import { type RunToolBudgetEnvelope, resolveToolBudgetEnvelope } from "./budget-envelope.js";
 import { assessCapabilityMismatch, type CapabilityMismatch } from "./capability-match.js";
 import { capacityLeaseUsage, createNodeLeaseUsageReader } from "./capacity-lease.js";
 import type {
@@ -307,6 +309,7 @@ interface ActiveRun {
 	requestOrigin?: DispatchRequestOrigin;
 	agentId: string;
 	task: string;
+	budget?: RunToolBudgetEnvelope;
 	cwd: string;
 	/** Fleet node this run was placed on; null when no placement resolved it. */
 	node: RunNodeIdentity | null;
@@ -1287,6 +1290,7 @@ interface DispatchLifecycleStage {
 	capabilityMismatch: CapabilityMismatch | null;
 	effectiveAutonomy: AutonomyLevel;
 	budget: WorkerBudget;
+	budgetEnvelope: RunToolBudgetEnvelope;
 	settings?: Readonly<ReturnType<ConfigContract["get"]>>;
 }
 
@@ -1411,7 +1415,7 @@ function assertWriteRootsEnforceable(runtime: RuntimeDescriptor, writeRoots: Rea
 function assertWorkerBudgetEnforceable(runtime: RuntimeDescriptor, hasDeclaredBudget: boolean): void {
 	if (!hasDeclaredBudget || runtime.kind !== "subprocess") return;
 	throw new Error(
-		`dispatch: runtime '${runtime.id}' cannot enforce an explicit agent budget because subprocess workers do not expose per-tool mediation; choose a native or claude-sdk worker`,
+		`dispatch: runtime '${runtime.id}' cannot enforce an explicit dispatch budget because subprocess workers do not expose per-tool mediation; choose a native or claude-sdk worker`,
 	);
 }
 
@@ -1543,26 +1547,36 @@ function assertPostRuntimeToolCompatibility(
 	);
 }
 
+function workerToolCallHardCap(settings: EffectiveSettings): number {
+	const rawEnvCap = process.env.CLIO_CODER_WORKER_TOOL_CALL_CAP?.trim();
+	const parsedEnvCap = rawEnvCap && /^[1-9]\d*$/.test(rawEnvCap) ? Number(rawEnvCap) : Number.NaN;
+	return Number.isSafeInteger(parsedEnvCap)
+		? parsedEnvCap
+		: (settings?.guardrails.workerToolCallCap ?? GUARDRAIL_DEFAULTS.workerToolCallCap);
+}
+
 function resolveEffectiveWorkerBudget(input: {
+	req: DispatchRequest;
+	recipeId: string;
 	declared: ReturnType<typeof normalizeAgentSpec>["budget"];
 	allowedTools: ReadonlyArray<ToolName>;
 	settings: EffectiveSettings;
-}): WorkerBudget {
-	const rawEnvCap = process.env.CLIO_CODER_WORKER_TOOL_CALL_CAP?.trim();
-	const parsedEnvCap = rawEnvCap && /^[1-9]\d*$/.test(rawEnvCap) ? Number(rawEnvCap) : Number.NaN;
-	const hardCap = Number.isSafeInteger(parsedEnvCap)
-		? parsedEnvCap
-		: (input.settings?.guardrails.workerToolCallCap ?? GUARDRAIL_DEFAULTS.workerToolCallCap);
+}): RunToolBudgetEnvelope {
+	const hardCap = workerToolCallHardCap(input.settings);
 	const declared = input.declared ?? {
 		toolCalls: hardCap,
 		readReserve: Math.min(5, Math.max(0, hardCap - 1)),
 		synthesis: true,
 	};
-	const toolCalls = Math.min(declared.toolCalls, hardCap);
-	const readReserve = input.allowedTools.includes(ToolNames.Read)
-		? Math.min(declared.readReserve, Math.max(0, toolCalls - 1))
-		: 0;
-	return { toolCalls, readReserve, synthesis: declared.synthesis, hardCap };
+	return resolveToolBudgetEnvelope({
+		recipeId: input.recipeId,
+		policy: declared,
+		...(input.req.budget === undefined ? {} : { request: input.req.budget }),
+		hardCap,
+		hasReadTool: input.allowedTools.includes(ToolNames.Read),
+		retry: (input.req.lineage?.attempt ?? 0) > 0,
+		revision: input.req.gate?.role === "builder" && input.req.gate.cycle > 1 && input.req.gate.verdict === "revise",
+	});
 }
 
 function frozenProtectedArtifactState(state: ProtectedArtifactState | undefined): ProtectedArtifactState {
@@ -3193,7 +3207,7 @@ export function createDispatchBundle(
 		);
 		enforceCapabilityGate(target.target.id, target.modelCapabilities, req.requiredCapabilities);
 		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.workers.onPermission ?? "deny");
-		assertWorkerBudgetEnforceable(target.runtime, spec.budget !== null);
+		assertWorkerBudgetEnforceable(target.runtime, spec.budget !== null || req.budget !== undefined);
 
 		const cwd = req.cwd ?? process.cwd();
 		const sessionAutonomy = settings?.autonomy ?? "auto-edit";
@@ -3231,7 +3245,13 @@ export function createDispatchBundle(
 			workingContextPaths: workerWorkingContextPaths(req),
 		});
 		const systemPrompt = compiledWorkerPrompt.systemPrompt;
-		const budget = resolveEffectiveWorkerBudget({ declared: spec.budget, allowedTools: effectiveTools, settings });
+		const budgetEnvelope = resolveEffectiveWorkerBudget({
+			req,
+			recipeId: recipe.id,
+			declared: spec.budget,
+			allowedTools: effectiveTools,
+			settings,
+		});
 		// Fetch structured project context only for tiers that receive it, so
 		// read-only scouts never pay the CLIO-CODER.md read. The tier is spec policy
 		// (capability-class default, recipe frontmatter override).
@@ -3291,7 +3311,8 @@ export function createDispatchBundle(
 			operatorProfileApplied: compiledWorkerPrompt.operatorProfileApplied ?? false,
 			capabilityMismatch,
 			effectiveAutonomy,
-			budget,
+			budget: budgetEnvelope.effective,
+			budgetEnvelope,
 			...(settings ? { settings } : {}),
 		};
 	}
@@ -3473,6 +3494,7 @@ export function createDispatchBundle(
 					role?: string;
 					usage?: unknown;
 					model?: unknown;
+					responseModelIdObservation?: unknown;
 					responseModel?: unknown;
 					responseId?: unknown;
 					stopReason?: unknown;
@@ -3522,12 +3544,16 @@ export function createDispatchBundle(
 				tokenMeter.cacheReadTokens += typeof u.cacheRead === "number" ? u.cacheRead : 0;
 				tokenMeter.cacheWriteTokens += typeof u.cacheWrite === "number" ? u.cacheWrite : 0;
 				tokenMeter.reasoningTokens += extractReasoningTokenCount(u);
-				const model = readStringOrNull(event.message.model);
-				const responseModel = readStringOrNull(event.message.responseModel);
-				const responseId = readStringOrNull(event.message.responseId);
-				if (model !== null || responseModel !== null || responseId !== null) {
-					upstreamResponses.push({ model, responseModel, responseId });
-				}
+				const requestedModelId = readStringOrNull(event.message.model);
+				const responseModelIdObservation = responseModelIdObservationFromRecord(event.message, "not-observed");
+				const differingResponseModelId = readStringOrNull(event.message.responseModel);
+				const providerResponseId = readStringOrNull(event.message.responseId);
+				upstreamResponses.push({
+					requestedModelId,
+					responseModelIdObservation,
+					differingResponseModelId,
+					providerResponseId,
+				});
 				if (event.message.stopReason === "error") {
 					const message = readStringOrNull(event.message.errorMessage);
 					if (message !== null) failureMessage = message;
@@ -4142,6 +4168,11 @@ export function createDispatchBundle(
 			return handle;
 		};
 		if (req.delegationAgentId) {
+			if (req.budget !== undefined) {
+				throw new Error(
+					"dispatch: budget envelopes cannot be enforced on an ACP delegation target; dispatch to a native or claude-sdk worker",
+				);
+			}
 			assertPlannedNodeIdentity(req, { id: "local", kind: "local" });
 			assertProtectedArtifactsEnforceable("acp-delegation", false, protectedArtifactState);
 			if (req.responseSchema !== undefined) {
@@ -4372,6 +4403,7 @@ export function createDispatchBundle(
 					role?: string;
 					usage?: unknown;
 					model?: unknown;
+					responseModelIdObservation?: unknown;
 					responseModel?: unknown;
 					responseId?: unknown;
 					stopReason?: unknown;
@@ -4477,12 +4509,16 @@ export function createDispatchBundle(
 				tokenMeter.cacheReadTokens += typeof u.cacheRead === "number" ? u.cacheRead : 0;
 				tokenMeter.cacheWriteTokens += typeof u.cacheWrite === "number" ? u.cacheWrite : 0;
 				tokenMeter.reasoningTokens += extractReasoningTokenCount(u);
-				const model = readStringOrNull(event.message.model);
-				const responseModel = readStringOrNull(event.message.responseModel);
-				const responseId = readStringOrNull(event.message.responseId);
-				if (model !== null || responseModel !== null || responseId !== null) {
-					upstreamResponses.push({ model, responseModel, responseId });
-				}
+				const requestedModelId = readStringOrNull(event.message.model);
+				const responseModelIdObservation = responseModelIdObservationFromRecord(event.message, "not-observed");
+				const differingResponseModelId = readStringOrNull(event.message.responseModel);
+				const providerResponseId = readStringOrNull(event.message.responseId);
+				upstreamResponses.push({
+					requestedModelId,
+					responseModelIdObservation,
+					differingResponseModelId,
+					providerResponseId,
+				});
 				if (event.message.stopReason === "error") {
 					const message = readStringOrNull(event.message.errorMessage);
 					if (message !== null) failureMessage = message;
@@ -4573,6 +4609,7 @@ export function createDispatchBundle(
 				agentAudience: lifecycle.agentAudience,
 				requestOrigin: lifecycle.requestOrigin,
 				task: req.task,
+				budget: lifecycle.budgetEnvelope,
 				targetId: lifecycle.target.target.id,
 				wireModelId: lifecycle.target.wireModelId,
 				runtimeId: lifecycle.target.runtime.id,
@@ -4638,6 +4675,7 @@ export function createDispatchBundle(
 			// reroute lineage depth, and the model context window for the
 			// per-worker meter. All optional so consumers degrade to local/plain.
 			const fleetIdentity = {
+				budget: lifecycle.budgetEnvelope,
 				...(placement !== undefined && placement !== null ? { node: placement.node.id } : {}),
 				...(req.gate !== undefined ? { gate: { role: req.gate.role, cycle: req.gate.cycle } } : {}),
 				...(req.reroutes !== undefined && req.reroutes.length > 0 ? { rerouteCount: req.reroutes.length } : {}),
@@ -4743,6 +4781,7 @@ export function createDispatchBundle(
 			requestOrigin: lifecycle.requestOrigin,
 			agentId: req.agentId,
 			task: req.task,
+			budget: lifecycle.budgetEnvelope,
 			cwd: lifecycle.cwd,
 			node: placement?.node ?? null,
 			aborted: false,
@@ -4817,6 +4856,7 @@ export function createDispatchBundle(
 				agentAudience: lifecycle.agentAudience,
 				requestOrigin: lifecycle.requestOrigin,
 				task: req.task,
+				budget: lifecycle.budgetEnvelope,
 				targetId: lifecycle.target.target.id,
 				wireModelId: lifecycle.target.wireModelId,
 				runtimeId: lifecycle.target.runtime.id,
@@ -5306,6 +5346,11 @@ export function createDispatchBundle(
 		req = validation.restore(validated.spec);
 
 		if (req.delegationAgentId) {
+			if (req.budget !== undefined) {
+				throw new Error(
+					"dispatch: budget envelopes cannot be enforced on an ACP delegation target; dispatch to a native or claude-sdk worker",
+				);
+			}
 			const protectedArtifactState = getProtectedArtifactState();
 			assertProtectedArtifactsEnforceable("acp-delegation", false, protectedArtifactState);
 			if (req.responseSchema !== undefined) {
@@ -5369,6 +5414,7 @@ export function createDispatchBundle(
 		);
 		assertPostRuntimeToolCompatibility(req.agentId, agentSpec, effectiveTools, target);
 		assertRuntimeCanHonorWorkerPermissionMode(target.runtime, settings?.workers.onPermission ?? "deny");
+		assertWorkerBudgetEnforceable(target.runtime, agentSpec.budget !== null || req.budget !== undefined);
 		assertResponseSchemaEnforceable(target.runtime, target.modelCapabilities, req.responseSchema, effectiveTools.length);
 		assertWriteRootsEnforceable(target.runtime, req.writeRoots);
 		assertProtectedArtifactsEnforceable(
@@ -5376,6 +5422,13 @@ export function createDispatchBundle(
 			target.runtime.kind !== "subprocess",
 			getProtectedArtifactState(),
 		);
+		resolveEffectiveWorkerBudget({
+			req,
+			recipeId: recipe.id,
+			declared: agentSpec.budget,
+			allowedTools: effectiveTools,
+			settings,
+		});
 		return {
 			agentId: req.agentId,
 			specFingerprint: agentSpecFingerprint(agentSpec),
@@ -5773,6 +5826,7 @@ export function createDispatchBundle(
 				runId: run.runId,
 				agentId: run.agentId,
 				task: run.task,
+				...(run.budget !== undefined ? { budget: run.budget } : {}),
 				runtimeKind: run.runtimeKind,
 				outcomePhase: run.stallKilled ? "terminating" : run.aborted ? "aborting" : "running",
 				heartbeat,

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

@@ -55,6 +55,7 @@ function envelopeFromReceipt(receipt: RunReceipt, status: RunStatus, receiptPath
 		...(receipt.agentAudience !== undefined ? { agentAudience: receipt.agentAudience } : {}),
 		...(receipt.requestOrigin !== undefined ? { requestOrigin: receipt.requestOrigin } : {}),
 		task: receipt.task,
+		...(receipt.budget !== undefined ? { budget: receipt.budget } : {}),
 		...(receipt.briefing !== undefined ? { briefing: receipt.briefing } : {}),
 		...(receipt.steering !== undefined ? { steering: receipt.steering } : {}),
 		targetId: receipt.targetId,