@iowarp/clio-coder 0.4.4 → 0.4.6

package/src/domains/context/working-set/recall.ts

@@ -1,19 +1,6 @@
-/**
- * Exact recall by ref.
- *
- * A `contextEviction` entry removes a tool-result body from the projection
- * and leaves a marker naming the ref. Recall is the reverse move: given a ref
- * on the active path whose key the fold still lists as evicted, hand back the
- * original body byte-exact and describe the `contextRecall` entry the caller
- * appends. The ref stays evicted in the fold: the body rides the recall tool
- * result at the tail of the working set, so the marker and the prefix cache
- * are untouched and a repeat recall is the churn signal. Pure over entries:
- * nothing here reads the session, writes the ledger, or calls a model.
- *
- * The body is read through the same `payload.ts` readers the projection and
- * the marker use, so what recall returns is exactly what the model saw before
- * eviction. No truncation happens here; the observation envelope applies the
- * per-turn caps.
+/** Exact persisted tool-result recall and bounded discovery on the active path.
+ * Bodies return at the tail through the caller's observation envelope; the raw
+ * ledger, summary cut, and existing eviction markers remain unchanged.
  */
 
 import { ceilChars } from "../../session/context-accounting.js";
@@ -29,7 +16,14 @@ import {
 } from "./contract.js";
 import { parseRefKey, refKey } from "./fold.js";
 import { callPathsByToolCallId } from "./path-index.js";
-import { offloadPathOf, primaryPathOf, toolResultPayload, toolResultText } from "./payload.js";
+import {
+	hasLegacyCompactionMarker,
+	offloadPathOf,
+	primaryPathOf,
+	toolResultPayload,
+	toolResultText,
+} from "./payload.js";
+import { compactionCut } from "./visible.js";
 
 export type RecallOutcome = { ok: true; result: RecallResult } | { ok: false; error: RecallError };
 
@@ -47,7 +41,7 @@ export function resolveRecall(
 	ref: string,
 	activeLeafTurnId?: string,
 ): RecallOutcome {
-	const parsed = parseRefKey(ref);
+	const parsed = parseRefKey(ref, view);
 	if (parsed === null) return { ok: false, error: { kind: "invalid_ref", ref } };
 	const key = refKey(parsed);
 	const active = filterEntriesToActivePath(entries, activeLeafTurnId);
@@ -55,11 +49,15 @@ export function resolveRecall(
 	if (entry === undefined) {
 		return { ok: false, error: { kind: "not_on_active_path", ref: key } };
 	}
-	// Thinking leaves the working set without a marker and is not recallable
-	// in this slice; `recallErrorMessage` names that case from the entry.
-	if (isThinkingEntry(entry) || !view.evicted.has(key) || !isToolResultEntry(entry)) {
-		return { ok: false, error: { kind: "not_evicted", ref: key } };
+	if (!isToolResultEntry(entry) || hasLegacyCompactionMarker(entry.payload)) {
+		return { ok: false, error: { kind: "unavailable", ref: key } };
 	}
+	const state = view.evicted.has(key)
+		? "evicted"
+		: compactionCut(active).visible.some((candidate) => candidate.turnId === key)
+			? "visible"
+			: "summarized";
+	if (state === "visible") return { ok: false, error: { kind: "visible", ref: key } };
 	const payload = toolResultPayload(entry.payload);
 	const body = toolResultText(payload.result);
 	const offloadPath = offloadPathOf(payload);
@@ -67,6 +65,7 @@ export function resolveRecall(
 		ok: true,
 		result: {
 			ref: parsed,
+			state,
 			entry,
 			body,
 			tokens: ceilChars(body.length),
@@ -103,50 +102,73 @@ export function buildRecallFields(
 	};
 }
 
-/** Refs listed in a recall failure before the list is cut with an ellipsis. */
-const MAX_LISTED_REFS = 8;
+export interface RecallDiscoveryOptions {
+	/** Case-insensitive terms matched against ref, tool name, and path. */
+	query?: string;
+	/** Default 8, maximum 12. */
+	limit?: number;
+	/** Zero-based position in matching active-path ledger order. */
+	offset?: number;
+	activeLeafTurnId?: string;
+}
 
 export interface RecallableRefListing {
-	/** Already-rendered `ref (tool path)` rows, bounded for prompt use. */
+	/** Bounded metadata rows; never result bodies or assistant thinking. */
 	refs: string[];
-	/** Recallable refs omitted after the bounded prefix. */
 	remaining: number;
+	total: number;
+	offset: number;
+	nextOffset?: number;
 }
 
-/**
- * The refs a recall can actually bring back, so the next call can name one of
- * them. Thinking refs are evicted too but are not recallable, so listing them
- * would hand the caller a ref that fails for a different reason. A guessed
- * "nearest" ref was tried first and dropped: over time-ordered ids a prefix
- * match names an unrelated result, and the listing is what helps.
- */
-export function recallableRefListing(entries: ReadonlyArray<SessionEntry>, view: WorkingSetView): RecallableRefListing {
-	const byTurnId = new Map<string, SessionEntry>();
-	for (const entry of entries) byTurnId.set(entry.turnId, entry);
-	const callPaths = callPathsByToolCallId(entries);
+/** Stable ledger-order pages for the same active path and query. */
+export function recallableRefListing(
+	entries: ReadonlyArray<SessionEntry>,
+	view: WorkingSetView,
+	options: RecallDiscoveryOptions = {},
+): RecallableRefListing {
+	const active = filterEntriesToActivePath(entries, options.activeLeafTurnId);
+	const visible = new Set(compactionCut(active).visible.map((entry) => entry.turnId));
+	const callPaths = callPathsByToolCallId(active);
+	const terms = (options.query ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+	const limit =
+		typeof options.limit === "number" && Number.isFinite(options.limit)
+			? Math.max(1, Math.min(12, Math.floor(options.limit)))
+			: 8;
+	const offset =
+		typeof options.offset === "number" && Number.isSafeInteger(options.offset) ? Math.max(0, options.offset) : 0;
 	const refs: string[] = [];
-	for (const key of view.evicted.keys()) {
-		const entry = byTurnId.get(key);
-		if (entry === undefined || !isToolResultEntry(entry)) continue;
-		// After a summary compaction the markers before the cut are gone from
-		// the working set, so the listing is the only place the caller learns
-		// what a ref was. Tool and path are what it needs to pick one.
+	let total = 0;
+	for (const entry of active) {
+		if (!isToolResultEntry(entry) || hasLegacyCompactionMarker(entry.payload)) continue;
+		const state = view.evicted.has(entry.turnId) ? "evicted" : visible.has(entry.turnId) ? "visible" : "summarized";
+		if (state === "visible") continue;
 		const payload = toolResultPayload(entry.payload);
 		const toolCallId = typeof payload.obj.toolCallId === "string" ? payload.obj.toolCallId : undefined;
 		const path = primaryPathOf(payload) ?? (toolCallId === undefined ? undefined : callPaths.get(toolCallId));
-		refs.push(`${key} (${payload.toolName}${path === undefined ? "" : ` ${path}`})`);
+		const alias = view.evicted.get(entry.turnId)?.alias;
+		const metadata = `${alias ?? ""} ${entry.turnId} ${payload.toolName} ${path ?? ""}`.toLowerCase();
+		if (!terms.every((term) => metadata.includes(term))) continue;
+		if (total >= offset && refs.length < limit) {
+			// Keep each row bounded even for unusual tool/path metadata.
+			const label = `${payload.toolName}${path === undefined ? "" : ` ${path}`}`.replace(/\s+/g, " ").slice(0, 240);
+			refs.push(`${alias ?? entry.turnId} (${label}) [${state}; ${entry.timestamp}]`);
+		}
+		total += 1;
 	}
-	return {
-		refs: refs.slice(0, MAX_LISTED_REFS),
-		remaining: Math.max(0, refs.length - MAX_LISTED_REFS),
-	};
+	const remaining = Math.max(0, total - offset - refs.length);
+	return { refs, remaining, total, offset, ...(remaining > 0 ? { nextOffset: offset + refs.length } : {}) };
 }
 
-function recallableRefMessage(entries: ReadonlyArray<SessionEntry>, view: WorkingSetView): string {
-	const listing = recallableRefListing(entries, view);
+function recallableRefMessage(
+	entries: ReadonlyArray<SessionEntry>,
+	view: WorkingSetView,
+	activeLeafTurnId?: string,
+): string {
+	const listing = recallableRefListing(entries, view, activeLeafTurnId === undefined ? {} : { activeLeafTurnId });
 	if (listing.refs.length === 0) return "No recallable refs on the active path.";
 	const more = listing.remaining > 0 ? `, and ${listing.remaining} more` : "";
-	return `Recallable refs on the active path: ${listing.refs.join(", ")}${more}.`;
+	return `Recallable refs on the active path: ${listing.refs.join(", ")}${more}. Discover all matches with context(scope="recall", limit=8, offset=0), omitting ref; query filters path/tool/ref terms. Follow nextOffset.`;
 }
 
 /**
@@ -159,19 +181,23 @@ export function recallErrorMessage(
 	error: RecallError,
 	entries: ReadonlyArray<SessionEntry> = [],
 	view: WorkingSetView = EMPTY_WORKING_SET_VIEW,
+	activeLeafTurnId?: string,
 ): string {
-	const listing = ` ${recallableRefMessage(entries, view)}`;
+	const active = filterEntriesToActivePath(entries, activeLeafTurnId);
+	const listing = ` ${recallableRefMessage(active, view, activeLeafTurnId)}`;
 	switch (error.kind) {
 		case "invalid_ref":
-			return `recall ref must be a single turnId without whitespace; got '${error.ref}'.`;
+			return `recall ref must be a single recall alias or turnId without whitespace; got '${error.ref}'.`;
 		case "not_on_active_path":
 			return `ref ${error.ref} is not on the active path of this session (unknown or on an abandoned branch).${listing}`;
-		case "not_evicted": {
-			const entry = entries.find((candidate) => candidate.turnId === error.ref);
+		case "visible":
+			return `ref ${error.ref} is visible; its content is already in context.${listing}`;
+		case "unavailable": {
+			const entry = active.find((candidate) => candidate.turnId === error.ref);
 			if (entry !== undefined && isThinkingEntry(entry)) {
 				return `ref ${error.ref} is an assistant turn; thinking is not recallable.${listing}`;
 			}
-			return `ref ${error.ref} is not evicted; its content is already in context.${listing}`;
+			return `ref ${error.ref} has no recallable original tool result (unsupported entry or legacy destructive compaction).${listing}`;
 		}
 	}
 }

package/src/domains/dispatch/active-route-planner.ts

@@ -42,6 +42,7 @@ export function routeValidationProjection(
 		decisionRefs,
 		resolvedVerification,
 		resultContractOverride,
+		resultSummary,
 		fleetGateReceipt,
 		taskWorktree,
 		runIdHint,
@@ -68,6 +69,7 @@ export function routeValidationProjection(
 				? { resolvedVerification: resolvedVerification.map((check) => ({ ...check, argv: [...check.argv] })) }
 				: {}),
 			...(resultContractOverride !== undefined ? { resultContractOverride } : {}),
+			...(resultSummary !== undefined ? { resultSummary: { ...resultSummary } } : {}),
 			...(fleetGateReceipt !== undefined ? { fleetGateReceipt: { ...fleetGateReceipt } } : {}),
 			...(taskWorktree !== undefined ? { taskWorktree } : {}),
 			...(runIdHint !== undefined ? { runIdHint } : {}),
@@ -132,7 +134,7 @@ export function planActiveRoute(
 		version: 1,
 		decision,
 		totalCostUpperBoundUsd: perAttemptUpperBoundUsd * input.maxAttempts,
-		deadlineMs: input.request.routingIntent?.deadlineMs ?? 60_000,
+		deadlineMs: input.request.routingIntent?.deadlineMs ?? null,
 		maxAttempts: input.maxAttempts,
 	};
 	assertApprovedAssignmentRoute(approval);
@@ -163,8 +165,9 @@ export function consumeActiveRouteApproval<T>(
 		throw new Error("dispatch: active recovery requires a resolver-authenticated attempt decision");
 	}
 	const request = applyActiveRouteSelection(input.request, decision);
-	if (input.request.lineage === undefined) {
-		request.assignmentDeadlineAt = Date.parse(input.requestedAt) + approval.deadlineMs;
+	if (input.request.lineage === undefined && approval.deadlineMs !== null) {
+		const deadline = Date.parse(input.requestedAt) + approval.deadlineMs;
+		request.assignmentDeadlineAt = Math.min(request.assignmentDeadlineAt ?? deadline, deadline);
 	}
 	return { request, observation: input.observe(request, decision) };
 }

package/src/domains/dispatch/admission-queue.ts

@@ -5,7 +5,8 @@ export interface AdmissionQueueRequest<T> {
 	assignmentId: string;
 	priority: number;
 	queuedAt: number;
-	deadlineAt: number;
+	/** Explicit caller deadline; absent means wait until capacity, cancellation, or a fault. */
+	deadlineAt?: number;
 	planId: string | null;
 	planOrder: number | null;
 	value: T;
@@ -47,6 +48,7 @@ export interface AdmissionQueue<T> {
 }
 export function createAdmissionQueue<T>(options: {
 	maxSize: number;
+	/** Legacy planning estimate; never shortens an explicit deadline or stops a healthy wait. */
 	finiteCeilingMs: number;
 	/** Reserved concurrent peak for a plan, resolved when the plan is seen. */
 	reservedPlanPeak?: (planId: string) => number | undefined;
@@ -67,7 +69,7 @@ export function createAdmissionQueue<T>(options: {
 			request: AdmissionQueueRequest<T>;
 			resolve: (outcome: AdmissionQueueOutcome<T>) => void;
 			reject: (error: Error) => void;
-			timer: ReturnType<typeof setTimeout>;
+			timer: ReturnType<typeof setTimeout> | undefined;
 		}
 	>();
 	const remove = (requestId: string, state: "canceled" | "timed_out"): boolean => {
@@ -85,12 +87,22 @@ export function createAdmissionQueue<T>(options: {
 				return Promise.reject(new Error(`dispatch: admission queue full (${entries.size}/${options.maxSize})`));
 			if (entries.has(request.requestId))
 				return Promise.reject(new Error(`dispatch: duplicate queued request '${request.requestId}'`));
-			const effectiveDeadline = Math.min(request.deadlineAt, request.queuedAt + options.finiteCeilingMs);
-			if (!Number.isFinite(effectiveDeadline))
+			const effectiveDeadline = request.deadlineAt;
+			if (effectiveDeadline !== undefined && !Number.isFinite(effectiveDeadline))
 				return Promise.reject(new Error("dispatch: queued request requires a finite deadline"));
 			return new Promise((resolve, reject) => {
-				const bounded = { ...request, deadlineAt: effectiveDeadline };
-				const timer = setTimeout(() => remove(request.requestId, "timed_out"), Math.max(0, effectiveDeadline - now()));
+				const bounded = { ...request };
+				const expire = (): void => {
+					const entry = entries.get(request.requestId);
+					if (!entry || effectiveDeadline === undefined) return;
+					const remaining = effectiveDeadline - now();
+					if (remaining <= 0) remove(request.requestId, "timed_out");
+					else entry.timer = setTimeout(expire, Math.min(2_147_483_647, remaining));
+				};
+				const timer =
+					effectiveDeadline === undefined
+						? undefined
+						: setTimeout(expire, Math.min(2_147_483_647, Math.max(0, effectiveDeadline - now())));
 				entries.set(request.requestId, { request: bounded, resolve, reject, timer });
 			});
 		},
@@ -107,7 +119,7 @@ export function createAdmissionQueue<T>(options: {
 		},
 		admitNext(nowMs = now(), canAdmit = () => true) {
 			for (const request of orderAdmissionRequests([...entries.values()].map((entry) => entry.request))) {
-				if (request.deadlineAt <= nowMs) {
+				if (request.deadlineAt !== undefined && request.deadlineAt <= nowMs) {
 					remove(request.requestId, "timed_out");
 					continue;
 				}

package/src/domains/dispatch/admission.ts

@@ -46,7 +46,7 @@ export interface CapacityAdmissionController {
 		assignmentId: string;
 		nodeId: string;
 		endpointKey?: string;
-		deadlineAt: number;
+		deadlineAt?: number;
 		priority?: number;
 		planId?: string;
 		planOrder?: number;
@@ -283,7 +283,7 @@ export function createCapacityAdmissionController(options: {
 					assignmentId: input.assignmentId,
 					priority: input.priority ?? 0,
 					queuedAt,
-					deadlineAt: input.deadlineAt,
+					...(input.deadlineAt === undefined ? {} : { deadlineAt: input.deadlineAt }),
 					planId: input.planId ?? null,
 					planOrder: input.planOrder ?? null,
 					value: () =>
@@ -313,7 +313,7 @@ export function createCapacityAdmissionController(options: {
 						nodeId: input.nodeId,
 						...(input.endpointKey !== undefined ? { endpointKey: input.endpointKey } : {}),
 						waitedMs: now() - queuedAt,
-						overdueAtQueueMs: queuedAt - input.deadlineAt,
+						overdueAtQueueMs: input.deadlineAt === undefined ? 0 : queuedAt - input.deadlineAt,
 						queueDepth: queue.size(),
 						limits: options.limits(),
 						usage: options.usage?.() ?? capacityLeaseUsage({ nowMs: now() }),

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

@@ -7,7 +7,7 @@ export interface DispatchBudgetPhase {
 	readReserve: number;
 }
 
-/** Typed invocation request. The ceiling preauthorizes growth on a later phase. */
+/** Typed advisory invocation estimate. A later phase may use a different estimate. */
 export interface DispatchBudgetRequest extends DispatchBudgetPhase {
 	retryRevision?: DispatchBudgetPhase;
 }
@@ -31,8 +31,10 @@ export interface RunToolBudgetEnvelope {
 	enforcement:
 		| {
 				classification: "native-per-tool";
-				perTool: "enforced";
-				clioControls: ReadonlyArray<"tool-calls" | "read-reserve" | "synthesis" | "attempt-cap">;
+				perTool: "enforced" | "advisory";
+				clioControls: ReadonlyArray<
+					"tool-calls" | "read-reserve" | "synthesis" | "attempt-cap" | "tool-observation" | "cancellation"
+				>;
 		  }
 		| {
 				classification: "external-one-shot";
@@ -50,6 +52,7 @@ export interface RunToolBudgetEnvelope {
 	reasons: ReadonlyArray<BudgetEnvelopeReason>;
 }
 
+const ADVISORY_CLIO_CONTROLS = ["tool-observation", "cancellation"] as const;
 const NATIVE_CLIO_CONTROLS = ["tool-calls", "read-reserve", "synthesis", "attempt-cap"] as const;
 const EXTERNAL_CLIO_CONTROLS = [
 	"single-launch",
@@ -129,63 +132,10 @@ function freezeEnvelope(envelope: RunToolBudgetEnvelope): RunToolBudgetEnvelope
 	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;
@@ -202,10 +152,14 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 	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);
+	if (
+		request?.retryRevision &&
+		(request.retryRevision.toolCalls < request.toolCalls || request.retryRevision.readReserve < request.readReserve)
+	) {
+		throw new BudgetAdmissionError("ceiling-below-request", "retryRevision must not be smaller than the requested phase");
+	}
 	const base = request ?? input.policy;
 	const reasons: BudgetEnvelopeReason[] = [];
 	let selected: DispatchBudgetPhase = base;
@@ -216,15 +170,7 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 			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`,
+				detail: `${phaseKind} phase grew from ${base.toolCalls}/${base.readReserve} to the advisory estimate ${ceiling.toolCalls}/${ceiling.readReserve}`,
 			});
 		}
 	}
@@ -232,18 +178,11 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 	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}`,
+			detail: `a result-contract revision may grow from ${selected.toolCalls}/${selected.readReserve} to the advisory estimate ${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;
-	}
+	const toolCalls = selected.toolCalls;
 	let readReserve = selected.readReserve;
 	if (!input.hasReadTool && readReserve > 0) {
 		reasons.push({
@@ -285,8 +224,8 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 					}
 				: {
 						classification: "native-per-tool",
-						perTool: "enforced",
-						clioControls: [...NATIVE_CLIO_CONTROLS],
+						perTool: "advisory",
+						clioControls: [...ADVISORY_CLIO_CONTROLS],
 					},
 		policy: {
 			recipeId: input.recipeId,
@@ -300,6 +239,7 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 		},
 		request,
 		effective: {
+			mode: "advisory",
 			toolCalls,
 			readReserve,
 			synthesis: input.policy.synthesis,
@@ -312,6 +252,8 @@ export function resolveToolBudgetEnvelope(input: ResolveToolBudgetEnvelopeInput)
 
 export function formatBudgetPolicy(envelope: RunToolBudgetEnvelope): string {
 	const policy = envelope.policy;
+	if (envelope.effective.mode === "advisory")
+		return `${policy.recipeId} advisory default ${policy.default.toolCalls}/${policy.default.readReserve}, recommended max ${policy.maximum.toolCalls}/${policy.maximum.readReserve}`;
 	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}`;
@@ -322,6 +264,8 @@ export function formatBudgetRequest(envelope: RunToolBudgetEnvelope): string {
 	const request = envelope.request;
 	if (request === null) return "recipe default";
 	const ceiling = request.retryRevision;
+	if (envelope.effective.mode === "advisory")
+		return `${request.toolCalls}/${request.readReserve} advisory${ceiling ? `, retry/revision estimate ${ceiling.toolCalls}/${ceiling.readReserve}` : ""}`;
 	return ceiling === undefined
 		? `${request.toolCalls}/${request.readReserve}, no retry/revision growth`
 		: `${request.toolCalls}/${request.readReserve}, retry/revision ceiling ${ceiling.toolCalls}/${ceiling.readReserve}`;
@@ -335,8 +279,10 @@ export function formatEffectiveBudget(envelope: RunToolBudgetEnvelope): string {
 	const enforcement =
 		envelope.enforcement.classification === "external-one-shot"
 			? "external one-shot; per-tool unobserved/not enforced"
-			: "native per-tool enforced";
-	return `${budget.toolCalls}/${budget.readReserve}${revision}, lifetime cap ${budget.hardCap}, synthesis=${budget.synthesis ? "on" : "off"}; ${enforcement}`;
+			: envelope.enforcement.perTool === "advisory"
+				? "native per-tool observed/advisory"
+				: "native per-tool enforced";
+	return `${budget.toolCalls}/${budget.readReserve}${revision}, ${budget.mode === "advisory" ? "advisory baseline" : "lifetime cap"} ${budget.hardCap}, synthesis=${budget.synthesis ? "on" : "off"}; ${enforcement}`;
 }
 
 export function formatBudgetReasons(envelope: RunToolBudgetEnvelope): string {
@@ -391,15 +337,17 @@ export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelop
 		) {
 			return undefined;
 		}
+		if (value.effective.mode !== undefined && value.effective.mode !== "advisory" && value.effective.mode !== "enforced")
+			return undefined;
 		if (
 			maximum.toolCalls < defaultPhase.toolCalls ||
 			maximum.readReserve < defaultPhase.readReserve ||
 			(value.policy.exact && !samePhase(maximum, defaultPhase)) ||
-			effectivePhase.toolCalls > value.effective.hardCap ||
+			(value.effective.mode !== "advisory" && effectivePhase.toolCalls > value.effective.hardCap) ||
 			value.effective.synthesis !== value.policy.default.synthesis ||
 			(revision !== undefined &&
 				(revision.toolCalls < effectivePhase.toolCalls ||
-					revision.toolCalls > value.effective.hardCap ||
+					(value.effective.mode !== "advisory" && revision.toolCalls > value.effective.hardCap) ||
 					(revision.toolCalls === effectivePhase.toolCalls && revision.readReserve <= effectivePhase.readReserve)))
 		) {
 			return undefined;
@@ -443,6 +391,17 @@ export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelop
 					clioControls: [...EXTERNAL_CLIO_CONTROLS],
 				};
 			}
+			if (
+				value.enforcement.classification === "native-per-tool" &&
+				value.enforcement.perTool === "advisory" &&
+				value.effective.mode === "advisory" &&
+				isExactStringArray(value.enforcement.clioControls, ADVISORY_CLIO_CONTROLS)
+			)
+				return {
+					classification: "native-per-tool" as const,
+					perTool: "advisory" as const,
+					clioControls: [...ADVISORY_CLIO_CONTROLS],
+				};
 			if (
 				value.enforcement.classification === "native-per-tool" &&
 				value.enforcement.perTool === "enforced" &&
@@ -457,6 +416,11 @@ export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelop
 			return null;
 		})();
 		if (enforcement === null) return undefined;
+		if (
+			enforcement.classification === "native-per-tool" &&
+			(enforcement.perTool === "advisory") !== (value.effective.mode === "advisory")
+		)
+			return undefined;
 		return freezeEnvelope({
 			version: 1,
 			enforcement,
@@ -468,6 +432,7 @@ export function cloneRunToolBudgetEnvelope(value: unknown): RunToolBudgetEnvelop
 			},
 			request,
 			effective: {
+				...(value.effective.mode === undefined ? {} : { mode: value.effective.mode as "advisory" | "enforced" }),
 				...effectivePhase,
 				synthesis: value.effective.synthesis,
 				hardCap: value.effective.hardCap,