@iowarp/clio-coder 0.4.0 → 0.4.2

package/src/engine/apis/openai-completions.ts

@@ -28,12 +28,12 @@ import { lmStudioReasoningEffort } from "../../domains/providers/runtimes/common
 import type { ThinkingLevel } from "../../domains/providers/types/capability-flags.js";
 import type { LocalModelQuirks, SamplingProfile } from "../../domains/providers/types/local-model-quirks.js";
 import type { LmStudioTargetSettings } from "../../domains/providers/types/target-descriptor.js";
-import { filterGemmaChannelStream } from "../gemma-channel-filter.js";
+import { filterGemmaChannelStream, usesGemmaChannelMarkers } from "../gemma-channel-filter.js";
 import { HarmonyResponseParser } from "../harmony-response.js";
 import { createSentinelStripper, stripTokenizerSentinels } from "../strip-tokenizer-sentinels.js";
 import { ensureLlamaCppResidency } from "./llamacpp-residency.js";
 import { ensureLmStudioResidency } from "./lmstudio.js";
-import { LOCAL_TOOL_TURN_MAX_OUTPUT_TOKENS, remainingContextMaxTokens } from "./output-budget.js";
+import { remainingContextMaxTokens } from "./output-budget.js";
 import { residencyManagedFor } from "./residency.js";
 import { mergeSamplingOverride } from "./sampling-overrides.js";
 import type { EngineApiProvider } from "./types.js";
@@ -60,11 +60,11 @@ const REASONING_CHARS_PER_TOKEN = 4;
 export { estimateInputTokensFromContext, remainingContextMaxTokens } from "./output-budget.js";
 
 interface ClioRuntimeMetadata {
-	clio?: {
+	clioCoder?: {
 		targetId: string;
 		runtimeId: string;
 		/** Present only when settings set the target lifecycle explicitly. */
-		lifecycle?: "user-managed" | "clio-managed";
+		lifecycle?: "user-managed" | "clio-coder-managed";
 		gateway?: boolean;
 		quirks?: LocalModelQuirks;
 		chatTemplateKwargsUnsupported?: boolean;
@@ -75,11 +75,11 @@ interface ClioRuntimeMetadata {
 }
 
 function chatTemplateKwargsUnsupported(model: Model<Api>): boolean {
-	return (model as Model<Api> & ClioRuntimeMetadata).clio?.chatTemplateKwargsUnsupported === true;
+	return (model as Model<Api> & ClioRuntimeMetadata).clioCoder?.chatTemplateKwargsUnsupported === true;
 }
 
 function clioQuirks(model: Model<"openai-completions">): LocalModelQuirks | undefined {
-	return (model as Model<"openai-completions"> & ClioRuntimeMetadata).clio?.quirks;
+	return (model as Model<"openai-completions"> & ClioRuntimeMetadata).clioCoder?.quirks;
 }
 
 function pickSamplingProfile(
@@ -138,7 +138,7 @@ function backendCompletionTimings(value: unknown, source: BackendTimingsSource):
 }
 
 function backendTimingsSourceForModel(model: Model<Api>): BackendTimingsSource | null {
-	const metadata = (model as Model<Api> & ClioRuntimeMetadata).clio;
+	const metadata = (model as Model<Api> & ClioRuntimeMetadata).clioCoder;
 	if (model.provider === "llamacpp" && metadata?.runtimeId === "llamacpp") return "llamacpp-timings";
 	if (model.provider === "lmstudio" && metadata?.runtimeId === "lmstudio") return "lmstudio-timings";
 	return null;
@@ -371,8 +371,23 @@ function applyThinkingPayload(
 	resolved: ResolvedModelRuntimeCapabilities,
 	model: Model<Api>,
 ): Record<string, unknown> {
-	if (applied.mechanism === "none") return stripThinkingRequestFields(payload);
-	if (applied.mechanism === "always-on") return payload;
+	if (applied.mechanism === "none") {
+		const next = stripThinkingRequestFields(payload);
+		if (resolved.request.chatTemplateKwargs && !chatTemplateKwargsUnsupported(model)) {
+			const existing = isPlainRecord(next.chat_template_kwargs) ? next.chat_template_kwargs : {};
+			next.chat_template_kwargs = { ...existing, ...resolved.request.chatTemplateKwargs };
+		}
+		return next;
+	}
+	if (applied.mechanism === "always-on") {
+		if (resolved.request.chatTemplateKwargs && !chatTemplateKwargsUnsupported(model)) {
+			const next: Record<string, unknown> = { ...payload };
+			const existing = isPlainRecord(next.chat_template_kwargs) ? next.chat_template_kwargs : {};
+			next.chat_template_kwargs = { ...existing, ...resolved.request.chatTemplateKwargs };
+			return next;
+		}
+		return payload;
+	}
 	const next: Record<string, unknown> = { ...payload };
 	if (
 		resolved.request.reasoningEffort &&
@@ -563,21 +578,9 @@ function withRemainingContextBudget<TOptions extends StreamOptions>(
 	context: Context,
 	options: TOptions | undefined,
 ): TOptions {
-	const metadata = runtimeMetadata(model);
-	const localToolOutputLimit =
-		options?.maxTokens === undefined &&
-		(context.tools?.length ?? 0) > 0 &&
-		(model.provider === "llamacpp" || metadata?.runtimeId === "llamacpp")
-			? LOCAL_TOOL_TURN_MAX_OUTPUT_TOKENS
-			: undefined;
 	return {
 		...(options ?? {}),
-		maxTokens: remainingContextMaxTokens(
-			model,
-			context,
-			options,
-			localToolOutputLimit === undefined ? undefined : { maxOutputTokens: localToolOutputLimit },
-		),
+		maxTokens: remainingContextMaxTokens(model, context, options),
 	} as TOptions;
 }
 
@@ -593,8 +596,8 @@ function hasEmptyArguments(args: Record<string, unknown>): boolean {
 	return Object.keys(args).length === 0;
 }
 
-function runtimeMetadata(model: Model<Api>): NonNullable<ClioRuntimeMetadata["clio"]> | undefined {
-	return (model as Model<Api> & ClioRuntimeMetadata).clio;
+function runtimeMetadata(model: Model<Api>): NonNullable<ClioRuntimeMetadata["clioCoder"]> | undefined {
+	return (model as Model<Api> & ClioRuntimeMetadata).clioCoder;
 }
 
 function emptyErrorMessage(model: Model<"openai-completions">, message: string): AssistantMessage {
@@ -679,7 +682,7 @@ function hasReportedReasoningUsage(usage: Usage): boolean {
  * upstream already reported reasoning usage, because ACP consumers accept all
  * three field spellings for cross-agent compatibility.
  */
-export function applyOpenAICompatReasoningEstimate(message: AssistantMessage): void {
+function applyOpenAICompatReasoningEstimate(message: AssistantMessage): void {
 	if (hasReportedReasoningUsage(message.usage)) return;
 	const estimated = estimateReasoningTokens(message.content);
 	const reportedOutput = message.usage.output;
@@ -936,7 +939,7 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 										(requestModel) => piOpenAICompletions.stream(requestModel, effectiveContext, capturedOptions),
 									),
 							),
-							resolved.family === "gemma-4",
+							usesGemmaChannelMarkers(resolved.modelId),
 						),
 						resolved,
 					),
@@ -969,7 +972,7 @@ export const openAICompletionsApiProvider: EngineApiProvider<"openai-completions
 										(requestModel) => piOpenAICompletions.streamSimple(requestModel, effectiveContext, capturedOptions),
 									),
 							),
-							resolved.family === "gemma-4",
+							usesGemmaChannelMarkers(resolved.modelId),
 						),
 						resolved,
 					),

package/src/engine/apis/output-budget.ts

@@ -13,7 +13,7 @@ const DEFAULT_MAX_OUTPUT_TOKENS = CLIO_MIN_MAX_OUTPUT_TOKENS;
 
 /**
  * Process-wide default output budget requested per turn, sourced from
- * settings.defaults.maxTokens at session start (see
+ * chat.maxOutputTokens at session start (see
  * {@link setGlobalDefaultMaxOutputTokens}). 0 means unset: callers fall back to
  * the model's advertised cap as before.
  */
@@ -30,19 +30,6 @@ export function setGlobalDefaultMaxOutputTokens(value: number): void {
 	globalDefaultMaxOutputTokens = Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
 }
 
-/**
- * Output ceiling applied to a llama.cpp tool-bearing turn when the caller did
- * not request an explicit limit. It bounds a genuinely runaway local
- * generation without muzzling real work: a single tool call that writes a
- * sizable file (a full HTML page, a multi-function source module) needs far
- * more than a few thousand tokens of argument, and the tool-call argument
- * counts against this same response budget. Narration loops where a local
- * model keeps saying it will call a tool without emitting one are caught
- * separately by assessToolProseLoop, so this number only has to be large
- * enough to let legitimate large outputs through.
- */
-export const LOCAL_TOOL_TURN_MAX_OUTPUT_TOKENS = CLIO_MIN_MAX_OUTPUT_TOKENS;
-
 /**
  * Tokens a preflight context check should hold back for the response: the
  * smaller of the model's advertised output limit and the default output
@@ -84,15 +71,18 @@ export function remainingContextMaxTokens(
 	const modelLimit = model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY;
 	// Precedence for the requested ceiling when the caller gave no explicit
 	// maxTokens: a more-specific tool-turn limit, then the global default, then
-	// the model's advertised cap. Math.min below clamps the result down to the
-	// model cap and the remaining context budget regardless, so the global
-	// default never lets a small model overshoot what it supports.
+	// the model's advertised cap. A model that advertises no cap uses the product
+	// floor instead of requesting its entire remaining context window. Math.min
+	// below clamps the result down to every known boundary, so frontier providers
+	// with a known cap never receive a larger max_tokens value.
 	const defaultLimit =
 		limits?.maxOutputTokens !== undefined && limits.maxOutputTokens > 0
 			? limits.maxOutputTokens
 			: globalDefaultMaxOutputTokens > 0
 				? globalDefaultMaxOutputTokens
-				: modelLimit;
+				: model.maxTokens > 0
+					? modelLimit
+					: DEFAULT_MAX_OUTPUT_TOKENS;
 	const requested = options?.maxTokens ?? defaultLimit;
 	const resolved = Math.min(requested, modelLimit, budget);
 	return Number.isFinite(resolved) ? resolved : DEFAULT_MAX_OUTPUT_TOKENS;

package/src/engine/apis/residency.ts

@@ -26,8 +26,8 @@
  *
  * The reconciler is best-effort and non-blocking. A slow or unreachable
  * server, or a malformed resident listing, degrades to observe-only and never
- * crashes a turn. `CLIO_CODER_RESIDENCY=observe` and an explicit target
- * `lifecycle: user-managed` both force observe-only on every runtime path.
+ * crashes a turn. An explicit target `lifecycle: user-managed` forces
+ * observe-only on every runtime path.
  * Every collision or stress case emits a notice over the event bus instead of
  * a thrown error. One reconcile decision holds per (target, model) within a
  * TTL, and mutations for a target are serialized across processes through a
@@ -130,7 +130,7 @@ export function residentTagProtected(tags: ReadonlyArray<string> | undefined): b
 const clioLoaded = new Map<string, Set<string>>();
 
 /** Record that Clio loaded `modelId` on the target identified by `targetKey`. */
-export function markClioLoaded(targetKey: string, modelId: string): void {
+function markClioLoaded(targetKey: string, modelId: string): void {
 	let set = clioLoaded.get(targetKey);
 	if (!set) {
 		set = new Set();
@@ -156,12 +156,6 @@ function isClioLoaded(targetKey: string, entry: ResidentModelInfo): boolean {
 export const RECONCILE_TTL_MS = 60_000;
 const reconcileCache = new Map<string, { modelId: string; decision: "reconcile" | "observe"; at: number }>();
 
-/** Test-only: clear the cross-call Clio-loaded registry and TTL cache. */
-export function resetResidencyState(): void {
-	clioLoaded.clear();
-	reconcileCache.clear();
-}
-
 // --- residency decision (pure) ----------------------------------------------
 
 /**
@@ -286,7 +280,7 @@ function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): Resid
 		facts,
 		"swap",
 		"warning",
-		`swapping resident '${entry.modelId}' for requested '${facts.keepModelId}' on '${facts.targetId}' (Clio did not load it; recorded transition instead of a silent unload; set CLIO_CODER_RESIDENCY=observe or lifecycle: user-managed to forbid swaps).`,
+		`swapping resident '${entry.modelId}' for requested '${facts.keepModelId}' on '${facts.targetId}' (Clio did not load it; recorded transition instead of a silent unload; set lifecycle: user-managed to forbid swaps).`,
 		{
 			...(entry.sizeVramBytes !== undefined ? { freedVramBytes: entry.sizeVramBytes } : {}),
 			swappedOut: entry.modelId,
@@ -301,7 +295,7 @@ function evictionNotice(facts: ResidencyFacts, entry: ResidentClassified): Resid
  * tiers, eviction order, and every notice case directly testable without a
  * server.
  */
-export function decideResidency(facts: ResidencyFacts): ResidencyPlan {
+function decideResidency(facts: ResidencyFacts): ResidencyPlan {
 	const notices: ResidencyNotice[] = [];
 	const keepResident = facts.resident.some((entry) => residentMatchesKeep(entry, facts.keepModelId));
 	const others = facts.resident.filter((entry) => !residentMatchesKeep(entry, facts.keepModelId));
@@ -781,29 +775,10 @@ export async function reconcileResidency(adapter: ResidencyAdapter): Promise<Rec
 }
 
 /**
- * The env-level residency opt-out. Clio manages residency for every
- * manageable runtime by default; `CLIO_CODER_RESIDENCY=observe` (or off/0/false/
- * user) flips the whole process to observe-only. Per-target opt-out goes
- * through {@link residencyManagedFor}.
- */
-export function residencyManaged(env: NodeJS.ProcessEnv = process.env): boolean {
-	const opt = (env.CLIO_CODER_RESIDENCY ?? "").trim().toLowerCase();
-	if (opt === "observe" || opt === "off" || opt === "0" || opt === "false" || opt === "user" || opt === "user-managed") {
-		return false;
-	}
-	return true;
-}
-
-/**
- * Combined residency opt-out for one target: the process-wide env switch plus
- * the target's explicit `lifecycle: user-managed`. An absent lifecycle means
- * the operator made no choice, and Clio manages by default; runtime synthesis
- * only sets the metadata field when settings carry an explicit value.
+ * Residency policy for one target. An absent lifecycle means the operator made
+ * no choice and Clio manages by default; runtime synthesis only sets the
+ * metadata field when settings carry an explicit value.
  */
-export function residencyManagedFor(
-	lifecycle: "user-managed" | "clio-managed" | undefined,
-	env: NodeJS.ProcessEnv = process.env,
-): boolean {
-	if (lifecycle === "user-managed") return false;
-	return residencyManaged(env);
+export function residencyManagedFor(lifecycle: "user-managed" | "clio-coder-managed" | undefined): boolean {
+	return lifecycle !== "user-managed";
 }

package/src/engine/claude/sdk-module.ts

@@ -66,20 +66,9 @@ export type ClaudeAgentSdkLoader = () => Promise<ClaudeAgentSdkModule>;
 // runtime `import()`.
 const realLoader: ClaudeAgentSdkLoader = async () => await import("@anthropic-ai/claude-agent-sdk");
 
-let loader: ClaudeAgentSdkLoader = realLoader;
+const loader: ClaudeAgentSdkLoader = realLoader;
 let cached: ClaudeAgentSdkModule | null = null;
 
-/**
- * Swap the import used by {@link loadClaudeAgentSdk}. The absence of a 224MB
- * optional package cannot be staged inside a normal test process, so the
- * contract test intercepts the import here; passing `null` restores the real
- * one and clears the cache.
- */
-export function setClaudeAgentSdkLoader(next: ClaudeAgentSdkLoader | null): void {
-	loader = next ?? realLoader;
-	cached = null;
-}
-
 /**
  * Resolve the SDK, or fail with {@link ClaudeAgentSdkUnavailableError}. A load
  * error that is not a resolution failure (a broken install, a throwing module

package/src/engine/claude/sdk-runtime.ts

@@ -53,11 +53,11 @@ async function* oneSdkUserMessage(message: SDKUserMessage): AsyncIterable<SDKUse
 	yield message;
 }
 
-export function claudeSdkPermissionModeForAutonomy(_level: AutonomyLevel | undefined): PermissionMode {
+function claudeSdkPermissionModeForAutonomy(_level: AutonomyLevel | undefined): PermissionMode {
 	return "default";
 }
 
-export function claudeSdkToolsForAutonomy(_level: AutonomyLevel | undefined): NonNullable<Options["tools"]> {
+function claudeSdkToolsForAutonomy(_level: AutonomyLevel | undefined): NonNullable<Options["tools"]> {
 	return DEFAULT_CLAUDE_TOOLS;
 }
 
@@ -314,7 +314,7 @@ export interface ClaudeWorkerBudgetGate {
 }
 
 /** Canonical call counter shared by the SDK's PreToolUse/canUseTool mediation seam. */
-export function createClaudeWorkerBudgetGate(
+function createClaudeWorkerBudgetGate(
 	budget: WorkerBudget,
 	onBoundary: () => void,
 	onHardCap: () => void,
@@ -438,7 +438,7 @@ function decideToolUse(
 }
 
 /** Share one logical permission decision across the SDK hook/callback pair. */
-export function decideClaudeSdkToolUseOnce(
+function decideClaudeSdkToolUseOnce(
 	handled: Map<string, ClaudeToolPermissionDecision>,
 	toolUseID: string | undefined,
 	decide: () => ClaudeToolPermissionDecision,
@@ -536,7 +536,7 @@ export function startClaudeSdkWorkerRun(input: WorkerRunInput, emit: WorkerEvent
 				() => {},
 				() => {
 					budgetFailure = true;
-					emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+					emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
 					abort();
 				},
 				resolveDeliveryTools(allowedToolSet, input.product),
@@ -563,7 +563,7 @@ export function startClaudeSdkWorkerRun(input: WorkerRunInput, emit: WorkerEvent
 		if (hookInput.hook_event_name !== "PostToolBatch" || !budgetGate?.phaseReached()) return { continue: true };
 		if (input.budget?.synthesis === false) {
 			budgetFailure = true;
-			emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+			emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
 			return { continue: false, stopReason: `worker agent budget reached (${input.budget.toolCalls})` };
 		}
 		return {

package/src/engine/claude/subprocess-runtime.ts

@@ -54,7 +54,7 @@ function buildClaudeCodePrompt(input: WorkerRunInput): string {
 	return parts.join("\n\n");
 }
 
-export function buildClaudeCodeArgs(input: WorkerRunInput): string[] {
+function buildClaudeCodeArgs(input: WorkerRunInput): string[] {
 	assertToolProfileEnforceable(input.toolProfile, "claude-code");
 	const permission = claudeSubprocessPermissionConfigForAutonomy(input.autonomy);
 	const args = [

package/src/engine/claude/tool-safety.ts

@@ -227,7 +227,7 @@ function budgetDenial(
 	};
 }
 
-export function evaluateClaudeToolPermission(input: EvaluateClaudeToolPermissionInput): ClaudeToolPermissionDecision {
+function evaluateClaudeToolPermission(input: EvaluateClaudeToolPermissionInput): ClaudeToolPermissionDecision {
 	const mapped = mapClaudeToolCall(input.toolName, input.input, input.cwd);
 	const call: ClassifierCall = { tool: mapped.clioToolName, args: mapped.args };
 	const attempt = input.budgetGate?.attempt(mapped.clioToolName);
@@ -346,7 +346,7 @@ function emitToolFinish(
 	const finalReasonCode = reasonCode ?? decision.policy?.reasonCode;
 	if (finalReasonCode !== undefined) event.reasonCode = finalReasonCode;
 	if (decision.policy?.policySource !== undefined) event.policySource = decision.policy.policySource;
-	emit({ type: "clio_tool_finish", payload: event });
+	emit({ type: "clio_coder_tool_finish", payload: event });
 }
 
 export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermissionInput): ClaudeToolPermissionDecision {
@@ -366,7 +366,7 @@ export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermission
 		startedAt,
 		...(action !== null ? { action } : {}),
 	};
-	input.emit({ type: "clio_tool_start", payload: start });
+	input.emit({ type: "clio_coder_tool_start", payload: start });
 	if (decision.kind === "allow") {
 		emitToolFinish(
 			input.emit,
@@ -383,7 +383,7 @@ export function emitClaudeToolPermissionDecision(input: EmitClaudeToolPermission
 	if (decision.permissionRequired) {
 		const mode = input.onPermission ?? "deny";
 		input.emit({
-			type: "clio_permission_resolved",
+			type: "clio_coder_permission_resolved",
 			payload: {
 				tool: decision.mapped.clioToolName,
 				actionClass: decision.decision.classification.actionClass,

package/src/engine/gemma-channel-filter.ts

@@ -6,6 +6,25 @@ import type {
 	ThinkingContent,
 } from "@earendil-works/pi-ai";
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import { inferLocalModelFamily } from "../domains/providers/model-family.js";
+
+/**
+ * Whether a model id names a Gemma 4 checkpoint, whose chat template writes its
+ * private channel with the markers below when llama-server leaves the thought
+ * inline in `content` instead of extracting it to `reasoning_content`.
+ *
+ * Keyed on the wire model id rather than on the resolved family, because
+ * `capabilityFamily` returns the knowledge-base family whenever the catalog
+ * matches an id and every Gemma entry there names a build (`gemma4-26b-a4b`,
+ * `gemma-4-31b-it-qat-mtp`, `gemopus-4-31b-it`), never the literal `gemma-4`
+ * that `inferLocalModelFamily` produces for an id the catalog does not match.
+ * Gating on the family therefore ran the filter only for Gemma ids the catalog
+ * did not know, so naming `gemma4-26b-moe` and `gemma4-31b-dense` in it (issue
+ * #263) turned the filter off for the two ids the router actually serves.
+ */
+export function usesGemmaChannelMarkers(modelId: string): boolean {
+	return inferLocalModelFamily(modelId) === "gemma-4";
+}
 
 const THOUGHT_START = /<\|channel>[^\n]*\n/;
 const BARE_THOUGHT_START = /^\s*(?:thought|own[- ]?(?:thought|think))\s*\n/i;

package/src/engine/loop-guard.ts

@@ -87,9 +87,9 @@ export const LOOP_SYNTHESIS_BACKSTOP_DENIALS = 2;
 export const WIDE_BATCH_DENIAL_FLOOR = 32;
 
 /**
- * Default lifetime tool-call cap for a worker run. Value and env override live
- * in core/guardrails.ts (`CLIO_CODER_WORKER_TOOL_CALL_CAP`); re-exported here for
- * tests and callers that reason about the guard's tuning in one place.
+ * Default lifetime tool-call cap for a worker run. The configurable value lives
+ * at `fleet.limits.toolCallsPerRun`; this default is re-exported for tests and
+ * callers that reason about the guard's tuning in one place.
  */
 export const DEFAULT_WORKER_TOOL_CALL_CAP = GUARDRAIL_DEFAULTS.workerToolCallCap;
 
@@ -105,7 +105,7 @@ export const DEFAULT_WORKER_TOOL_CALL_CAP = GUARDRAIL_DEFAULTS.workerToolCallCap
  * DISTINCT unproductive calls. Legitimate deep work (a repo-wide audit runs
  * 25+ productive calls in one turn) must not be decapitated by it; mainstream
  * harnesses run 100+ calls per turn with no ceiling at all. Value and env
- * override (`CLIO_CODER_TURN_TOOL_CALL_BUDGET`) live in core/guardrails.ts.
+ * live at `safety.limits.chatToolCallsPerTurn`.
  */
 export const DEFAULT_ORCH_TURN_TOOL_CALL_BUDGET = GUARDRAIL_DEFAULTS.turnToolCallBudget;
 /**
@@ -185,6 +185,70 @@ function loopBlockBaseReason(tool: string, repeatCount: number, priorSuccesses:
 	);
 }
 
+/** True when a sanitized locked reply holds nothing but the fallback notice. */
+export function isLockedSynthesisFallbackOnly(message: AgentMessage | undefined): boolean {
+	if (!message || typeof message !== "object" || (message as { role?: unknown }).role !== "assistant") return false;
+	const content = (message as { content?: unknown }).content;
+	if (!Array.isArray(content)) return false;
+	const text = content
+		.filter((block): block is { type: "text"; text: string } => block?.type === "text" && typeof block.text === "string")
+		.map((block) => block.text)
+		.join("")
+		.trim();
+	return text === lockedSynthesisFallbackText();
+}
+
+export const LOCKED_SYNTHESIS_REPROMPT_TOOL = "clio_synthesis_reprompt";
+
+/**
+ * One bounded re-prompt after a locked round came back as tool-call markup
+ * only. Delivered as a paired synthetic tool exchange, never a user turn, for
+ * the same reason the result-contract repair is (#55: a late user message
+ * re-renders every earlier assistant turn on templates keyed off the last
+ * user message and invalidates the whole prompt cache).
+ */
+export function lockedSynthesisRepromptMessages(
+	attempt: number,
+	origin: { provider: string; api: string; model: string },
+): ReadonlyArray<AgentMessage> {
+	const id = `clio-synthesis-reprompt-${attempt}`;
+	const timestamp = Date.now();
+	return [
+		{
+			role: "assistant",
+			content: [{ type: "toolCall", id, name: LOCKED_SYNTHESIS_REPROMPT_TOOL, arguments: {} }],
+			stopReason: "toolUse",
+			usage: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			...origin,
+			timestamp,
+		},
+		{
+			role: "toolResult",
+			toolCallId: id,
+			toolName: LOCKED_SYNTHESIS_REPROMPT_TOOL,
+			content: [
+				{
+					type: "text",
+					text:
+						"Your previous reply contained only tool-call markup, which cannot run: tool calls are disabled for " +
+						"the rest of this run. Everything you gathered is already in the conversation above. Write the " +
+						"final answer now as plain prose (or the exact result format the task asked for), with no tool-call " +
+						"markup of any kind.",
+				},
+			],
+			isError: true,
+			timestamp,
+		},
+	] as unknown as ReadonlyArray<AgentMessage>;
+}
+
 /**
  * Directive returned when a turn is locked to synthesis: tool use is over, so
  * the model must answer from what it already gathered. Fed back to the model as
@@ -352,11 +416,6 @@ export function isLoopGuardSynthesisBackstopReason(reason: string): boolean {
 	return /^loop guard: tool calls stayed disabled and .+ was called again instead of answering/.test(reason);
 }
 
-/** Worker lifetime tool-call cap: env > settings guardrails > default. */
-export function readWorkerToolCallCap(env: NodeJS.ProcessEnv = process.env): number {
-	return resolveGuardrail("workerToolCallCap", env);
-}
-
 /** Soft/hard per-turn tool-call budget for the interactive orchestrator. */
 export interface OrchTurnToolCallBudget {
 	/** Distinct calls in a turn that trigger the re-plan nudge. */
@@ -365,8 +424,8 @@ export interface OrchTurnToolCallBudget {
 	hard: number;
 }
 
-export function readOrchTurnToolCallBudget(env: NodeJS.ProcessEnv = process.env): OrchTurnToolCallBudget {
-	const soft = resolveGuardrail("turnToolCallBudget", env);
+export function readOrchTurnToolCallBudget(): OrchTurnToolCallBudget {
+	const soft = resolveGuardrail("turnToolCallBudget");
 	return { soft, hard: soft + ORCH_TURN_TOOL_CALL_HARD_MARGIN };
 }
 
@@ -421,7 +480,7 @@ export interface CreateLoopGuardRegistrationOptions {
 	 * the turn over the bus. Absent for workers, which rely on the lifetime
 	 * {@link toolCallCap} instead.
 	 */
-	turnToolCallBudget?: OrchTurnToolCallBudget;
+	turnToolCallBudget?: OrchTurnToolCallBudget | (() => OrchTurnToolCallBudget);
 	/**
 	 * When the per-turn loop-block budget is exhausted, lock tool use for the
 	 * rest of the turn instead of cancelling it outright. Every further call is
@@ -472,7 +531,6 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 		(cap === undefined || options.toolCallSoftLimit <= cap)
 			? options.toolCallSoftLimit
 			: undefined;
-	const turnBudget = options.turnToolCallBudget;
 	const synthesisLockout = options.turnSynthesisLockout === true;
 	let softReadReserve = options.toolCallSoftReadReserve ?? 0;
 	let softReadReserveThreshold =
@@ -521,6 +579,12 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 	let reserveDirectiveEmitted = false;
 	const blocksByTurn = new Map<string, number>();
 	const callsByTurn = new Map<string, number>();
+	/**
+	 * Per-turn count of successful write or edit calls. The identical-call key
+	 * carries it, so a check rerun after a change (fix-verify) is a fresh call
+	 * while a verbatim repeat with nothing changed in between still counts.
+	 */
+	const mutationEpochByTurn = new Map<string, number>();
 	/**
 	 * Turns whose tool use is locked to synthesis after reaching the block
 	 * budget. Key present means locked; the value carries the block that tripped
@@ -599,6 +663,9 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 	// (admission returns before execution), so only real results anchor.
 	const recordSuccessfulResult = (input: MiddlewareHookInput): void => {
 		if (input.metadata?.resultKind !== "ok") return;
+		if (input.toolName === ToolNames.Write || input.toolName === ToolNames.Edit) {
+			bumpBoundedCounter(mutationEpochByTurn, input.turnId ?? NO_TURN_BUCKET);
+		}
 		if (!resultCarriesEvidence(input.toolResultDetails)) return;
 		const tool = input.toolName;
 		if (typeof tool !== "string" || tool.length === 0) return;
@@ -753,11 +820,11 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 
 	const emitBudgetEvent = (
 		input: MiddlewareHookInput,
+		turnBudget: OrchTurnToolCallBudget,
 		callsThisTurn: number,
 		interrupted: boolean,
 		at: number,
 	): void => {
-		if (turnBudget === undefined) return;
 		const payload: ToolBudgetExceededPayload = {
 			tool: input.toolName ?? "unknown",
 			callsThisTurn,
@@ -771,6 +838,8 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 	};
 
 	const evaluateTurnBudget = (input: MiddlewareHookInput, now: number): ReadonlyArray<MiddlewareEffect> | null => {
+		const budgetSource = options.turnToolCallBudget;
+		const turnBudget = typeof budgetSource === "function" ? budgetSource() : budgetSource;
 		if (turnBudget === undefined) return null;
 		const turnKey = input.turnId ?? NO_TURN_BUCKET;
 		const callsThisTurn = bumpBoundedCounter(callsByTurn, turnKey);
@@ -778,7 +847,7 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 			// Hard ceiling: interrupt the turn the same way the block budget does.
 			// The bus event drives chat.cancel() in the interactive layer; the
 			// block effect makes the in-flight attempt fail with the same reason.
-			if (callsThisTurn === turnBudget.hard) emitBudgetEvent(input, callsThisTurn, true, now);
+			if (callsThisTurn === turnBudget.hard) emitBudgetEvent(input, turnBudget, callsThisTurn, true, now);
 			return [
 				{
 					kind: "block_tool",
@@ -797,7 +866,7 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 			// ever run. The operator sees one warn notice per turn (the first
 			// crossing); the model keeps getting the directive on every further
 			// over-budget attempt so it cannot quietly resume spraying calls.
-			if (callsThisTurn === turnBudget.soft) emitBudgetEvent(input, callsThisTurn, false, now);
+			if (callsThisTurn === turnBudget.soft) emitBudgetEvent(input, turnBudget, callsThisTurn, false, now);
 			return [
 				{
 					kind: "block_tool",
@@ -1089,7 +1158,13 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 				// regardless of age, so an unscoped key would let one identical call
 				// per user turn (rerunning a build across turns) accumulate into a
 				// false loop.
-				const verdict = options.safety.observeLoop(`${turnKey}|${fingerprint}`, now);
+				// The epoch scopes repeats to "since the last successful write or
+				// edit": a live session repeated a batch of eleven read-only bash
+				// calls five times, every one admitted, because the detector kept
+				// only a 30 s window or the last four attempts and no batch ever
+				// showed a third repeat inside either.
+				const epoch = mutationEpochByTurn.get(turnKey) ?? 0;
+				const verdict = options.safety.observeLoop(`${turnKey}|${epoch}|${fingerprint}`, now);
 				if (verdict.looping) {
 					const tool = input.toolName ?? "unknown";
 					const priorSuccesses = succeededFingerprints.get(fingerprint) ?? 0;