@iowarp/clio-coder 0.4.1 → 0.4.2

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
@@ -280,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,
@@ -775,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}.
+ * 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 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.
- */
-export function residencyManagedFor(
-	lifecycle: "user-managed" | "clio-coder-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/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
@@ -360,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 };
 }
 
@@ -416,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
@@ -467,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 =
@@ -516,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
@@ -594,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;
@@ -748,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,
@@ -766,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);
@@ -773,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",
@@ -792,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",
@@ -1084,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;

package/src/engine/worker-runtime.ts

@@ -73,8 +73,10 @@ import { startClaudeSdkWorkerRun } from "./claude/sdk-runtime.js";
 import { startClaudeCodeWorkerRun } from "./claude/subprocess-runtime.js";
 import {
 	createLoopGuardRegistration,
+	isLockedSynthesisFallbackOnly,
 	isLoopGuardSynthesisBackstopReason,
 	lockedSynthesisFallbackText,
+	lockedSynthesisRepromptMessages,
 	resolveDeliveryTools,
 	sanitizeLockedSynthesisMessage,
 	workerLoopBlockBudget,
@@ -378,9 +380,8 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 	// already surfaced.
 	const workerSettings = validateSettingsFile().settings;
 	setGlobalDefaultMaxOutputTokens(workerSettings.chat.maxOutputTokens);
-	// Same mirroring for guardrail policy: the worker's loop-guard cap and tool
-	// byte caps resolve settings-first, so the fresh process needs the section
-	// installed before any registry or tool construction reads it.
+	// Same mirroring for guardrail policy: the fresh process needs its settings
+	// projection installed before any registry or tool construction reads it.
 	configureGuardrails(guardrailValuesFromSettings(workerSettings));
 	const fauxModel = registerFauxFromEnv();
 	// Workers are bounded runs against an admission-verified recipe surface.
@@ -412,8 +413,10 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 			: {}),
 	});
 	// Flipped by the loop guard's lockout callback; read by onPayload below to
-	// force the remaining model rounds text-only via tool_choice none.
+	// force the remaining model rounds text-only by removing the tool surface
+	// (tool_choice none on Anthropic; see patchToolSurfaceLockedPayload).
 	let synthesisToolLock = false;
+	let lockedSynthesisReprompts = 0;
 	let workerBoundFailure: string | null = null;
 	let workerBoundAborted = false;
 	let abortWorkerForBound: (() => void) | null = null;
@@ -596,6 +599,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		includeInteractiveTools: false,
 		invokeOptions: () => ({
 			correlationId: `worker-model-round-${workerModelRound}`,
+			toolResultMaxBytes: workerSettings.context.toolResultMaxBytes,
 			...(agentSkillPolicy ? { pendingSkillPolicy: agentSkillPolicy } : {}),
 		}),
 	});
@@ -661,13 +665,38 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 			pendingReadCitations.delete(event.toolCallId);
 			if (request !== undefined && event.isError !== true) recordObservedRead(request, event.result);
 		}
-		// Synthesis-locked run: a model that ignores tool_choice none emits its
-		// chat template's tool-call syntax as plain text. Sanitize the finished
-		// message in place before it hits stdout; pi stores this same object in
-		// agent state, so the NDJSON event, the dispatch consumer's answer
-		// reconstruction, and any later provider round all see the same text.
+		// Synthesis-locked run: the round ships no tool surface, so a model that
+		// calls a tool anyway lands its chat template's tool-call syntax in the
+		// reply as plain text. Sanitize the finished message in place before it
+		// hits stdout; pi stores this same object in agent state, so the NDJSON
+		// event, the dispatch consumer's answer reconstruction, and any later
+		// provider round all see the same text.
+		// A markup-only locked reply re-prompted this round; the result-contract
+		// check below stands aside so the round costs the one re-prompt, not one
+		// of the contract's bounded repair slots (on ornith both were queued for
+		// the same message and the run then ran out of repairs on a later
+		// grounding violation).
+		let repromptedThisMessage = false;
 		if (synthesisToolLock && event.type === "message_end") {
-			sanitizeLockedSynthesisMessage(event.message);
+			const stripped = sanitizeLockedSynthesisMessage(event.message);
+			// A model that calls a tool anyway hands its markup back as text and
+			// the sanitizer leaves only the fallback notice: the training habit
+			// survives the strip (Qwen3.8 did it in 1 of 5 stripped runs). One
+			// re-prompt, delivered as a tool exchange like the result-contract
+			// repair, asks for the answer in prose; a second markup-only reply
+			// keeps the notice.
+			if (stripped && lockedSynthesisReprompts < 1 && isLockedSynthesisFallbackOnly(event.message)) {
+				lockedSynthesisReprompts += 1;
+				repromptedThisMessage = true;
+				process.stderr.write("[worker] synthesis lock: reply was tool-call markup only; re-prompting once for prose\n");
+				for (const message of lockedSynthesisRepromptMessages(lockedSynthesisReprompts, {
+					provider: model.provider,
+					api: model.api,
+					model: model.id,
+				})) {
+					agent.followUp(message as unknown as AgentMessage);
+				}
+			}
 		}
 		// Bounded terminal-contract repair, on whichever message ends the run.
 		// A worker that finishes inside its budget never trips the synthesis
@@ -676,7 +705,7 @@ export function startWorkerRun(input: WorkerRunInput, emit: WorkerEventEmit): Wo
 		// same contract against the sealed receipt; this is the only point at
 		// which the model can still act on the validator's reason.
 		const contract = input.resultContract;
-		if (contract && event.type === "message_end" && isTerminalAssistantMessage(event.message)) {
+		if (contract && !repromptedThisMessage && event.type === "message_end" && isTerminalAssistantMessage(event.message)) {
 			const violation = terminalContractViolation(
 				contract,
 				event.message,

package/src/engine/worker-tools.ts

@@ -155,8 +155,10 @@ export function createWorkerToolRegistry(
 	// The ledger tool registers unconditionally. attestedToolSignature signs the
 	// names a bare registry produces, so a conditional registration would drift
 	// the signature and fail admission; only the injected port varies, and a run
-	// without one answers that it has no coordination ledger.
+	// without one answers that it has no coordination ledger. The explicit flag
+	// is what keeps that true now that the session registry omits the tool.
 	const registration = registerCoreTools(registry, {
+		includeLedgerTools: true,
 		...(agentLedger ? { agentLedger } : {}),
 		// A worker cannot install a skill or reach the operator who could, so
 		// its skill listing carries installed (or bound) skills only; the

package/src/entry/extension-hook-sources.ts

@@ -0,0 +1,28 @@
+import type { ExtensionSnapshot } from "../domains/extensions/index.js";
+import type { CapturedHookSourceSet } from "../domains/middleware/index.js";
+
+/**
+ * Adapt an extension snapshot's captured hook declarations to the
+ * middleware-native captured source set. This is the only place the two
+ * domains' shapes meet; middleware never imports extension types.
+ */
+export function capturedHookSourcesFor(
+	snapshot: Pick<ExtensionSnapshot, "generation" | "hookSources">,
+): CapturedHookSourceSet {
+	return {
+		generation: snapshot.generation,
+		sources: snapshot.hookSources.map((source) => ({
+			provenance: {
+				id: source.provenance.id,
+				scope: source.provenance.scope,
+				...(source.provenance.sourcePath !== undefined ? { sourcePath: source.provenance.sourcePath } : {}),
+				canonicalRoot: source.provenance.canonicalRoot,
+				manifestDigest: source.provenance.manifestDigest,
+				contentDigest: source.provenance.contentDigest,
+			},
+			declarationsDigest: source.declarationsDigest,
+			declarations: source.declarations,
+			...(source.parseError !== undefined ? { parseError: source.parseError } : {}),
+		})),
+	};
+}