@iowarp/clio-coder 0.4.9 → 0.5.0

package/src/engine/apis/sampling-overrides.ts

@@ -1,5 +1,26 @@
 import { runOverrides } from "../../core/run-overrides.js";
-import type { SamplingProfile } from "../../domains/providers/types/local-model-quirks.js";
+import type { LocalModelQuirks, SamplingProfile } from "../../domains/providers/types/local-model-quirks.js";
+
+export function pickSamplingProfile(
+	quirks: LocalModelQuirks | undefined,
+	thinkingActive: boolean,
+): SamplingProfile | undefined {
+	const sampling = quirks?.sampling;
+	return mergeSamplingOverride(thinkingActive ? (sampling?.thinking ?? sampling?.instruct) : sampling?.instruct);
+}
+
+/** Pi passes these keys through; native Ollama uses the same sampler names as llama.cpp. */
+export function samplingParamsFromProfile(profile: SamplingProfile, runtimeId: string): Record<string, number> {
+	const repeatPenaltyKey = runtimeId === "vllm" || runtimeId === "sglang" ? "repetition_penalty" : "repeat_penalty";
+	return {
+		...(profile.topP !== undefined ? { top_p: profile.topP } : {}),
+		...(profile.topK !== undefined ? { top_k: profile.topK } : {}),
+		...(profile.minP !== undefined ? { min_p: profile.minP } : {}),
+		...(profile.repeatPenalty !== undefined ? { [repeatPenaltyKey]: profile.repeatPenalty } : {}),
+		...(profile.presencePenalty !== undefined ? { presence_penalty: profile.presencePenalty } : {}),
+		...(profile.frequencyPenalty !== undefined ? { frequency_penalty: profile.frequencyPenalty } : {}),
+	};
+}
 
 function numberField(record: Record<string, number | undefined>, key: keyof SamplingProfile): number | undefined {
 	const value = record[key];
@@ -29,7 +50,7 @@ function runSamplingOverrides(env: NodeJS.ProcessEnv = process.env): SamplingPro
 	return Object.keys(out).length > 0 ? out : undefined;
 }
 
-export function mergeSamplingOverride(
+function mergeSamplingOverride(
 	profile: SamplingProfile | undefined,
 	override: SamplingProfile | undefined = runSamplingOverrides(),
 ): SamplingProfile | undefined {

package/src/engine/apis/types.ts

@@ -4,13 +4,12 @@ import type {
 	Context,
 	Model,
 	SimpleStreamOptions,
-	StreamFunction,
 	StreamOptions,
 } from "@earendil-works/pi-ai";
 
 /** Engine-owned API implementation shape; avoids the deprecated compat registry type. */
 export interface EngineApiProvider<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> {
 	api: TApi;
-	stream: StreamFunction<TApi, TOptions>;
+	stream(model: Model<TApi>, context: Context, options?: TOptions): AssistantMessageEventStream;
 	streamSimple(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
 }

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

@@ -1,3 +1,4 @@
+import nodePath from "node:path";
 import { performance } from "node:perf_hooks";
 import { ToolNames } from "../../core/tool-names.js";
 import type { ClassifierCall } from "../../domains/safety/action-classifier.js";
@@ -90,6 +91,25 @@ function pathArgs(input: Record<string, unknown>): Record<string, unknown> {
 	return path ? { ...input, path } : { ...input };
 }
 
+/**
+ * Arguments for the SDK's search tools. They search `path`, so that key wins
+ * over the file keys a model may add. Their glob can also leave the search
+ * directory, by an absolute pattern or a `..` segment, and then the literal
+ * directory prefix of the glob is where the search reaches and the path the
+ * policy judges.
+ */
+function searchArgs(input: Record<string, unknown>, globKey: "pattern" | "glob" | null): Record<string, unknown> {
+	const base = stringField(input, "path", "file_path", "filePath");
+	const glob = globKey === null ? undefined : stringField(input, globKey);
+	if (glob !== undefined && (nodePath.isAbsolute(glob) || glob.split("/").includes(".."))) {
+		const literal = glob.split("/");
+		const firstMagic = literal.findIndex((segment) => /[*?[\]{}]/u.test(segment));
+		const prefix = (firstMagic === -1 ? literal.slice(0, -1) : literal.slice(0, firstMagic)).join("/") || "/";
+		return { ...input, path: base === undefined || nodePath.isAbsolute(prefix) ? prefix : nodePath.join(base, prefix) };
+	}
+	return base === undefined ? { ...input } : { ...input, path: base };
+}
+
 function commandArgs(input: Record<string, unknown>, cwd: string): Record<string, unknown> {
 	const command = stringField(input, "command", "cmd", "shell", "input", "description") ?? JSON.stringify(input);
 	return { ...input, command, cwd: stringField(input, "cwd") ?? cwd };
@@ -157,12 +177,12 @@ function mapClaudeToolCall(toolName: string, input: Record<string, unknown>, cwd
 		case "Write":
 			return { claudeToolName: toolName, clioToolName: ToolNames.Write, args: pathArgs(input), known: true };
 		case "Grep":
-			return { claudeToolName: toolName, clioToolName: ToolNames.Grep, args: pathArgs(input), known: true };
+			return { claudeToolName: toolName, clioToolName: ToolNames.Grep, args: searchArgs(input, "glob"), known: true };
 		case "Glob":
-			return { claudeToolName: toolName, clioToolName: ToolNames.Find, args: pathArgs(input), known: true };
+			return { claudeToolName: toolName, clioToolName: ToolNames.Find, args: searchArgs(input, "pattern"), known: true };
 		case "LS":
 		case "Ls":
-			return { claudeToolName: toolName, clioToolName: ToolNames.Ls, args: pathArgs(input), known: true };
+			return { claudeToolName: toolName, clioToolName: ToolNames.Ls, args: searchArgs(input, null), known: true };
 		case "WebFetch":
 		case "WebSearch":
 			return { claudeToolName: toolName, clioToolName: ToolNames.WebFetch, args: { ...input }, known: true };
@@ -175,12 +195,16 @@ function mapClaudeToolCall(toolName: string, input: Record<string, unknown>, cwd
 	}
 }
 
+function readsOutsideWorkspace(decision: SafetyDecision): boolean {
+	return decision.policy?.readScope === "outside-workspace";
+}
+
 function toAutonomyBlock(decision: SafetyDecision, level: AutonomyLevel, call: ClassifierCall): SafetyDecision {
 	const actionClass = decision.classification.actionClass;
 	return {
 		kind: "block",
 		classification: decision.classification,
-		rejection: autonomyDenyRejection(level, call.tool, actionClass),
+		rejection: autonomyDenyRejection(level, call.tool, actionClass, readsOutsideWorkspace(decision)),
 		...(decision.policy !== undefined ? { policy: decision.policy } : {}),
 	};
 }
@@ -190,7 +214,7 @@ function toAutonomyAsk(decision: SafetyDecision, level: AutonomyLevel, call: Cla
 	return {
 		kind: "ask",
 		classification: decision.classification,
-		rejection: autonomyAskRejection(level, call.tool, actionClass),
+		rejection: autonomyAskRejection(level, call.tool, actionClass, undefined, readsOutsideWorkspace(decision)),
 		...(decision.policy !== undefined ? { policy: decision.policy } : {}),
 	};
 }
@@ -285,6 +309,7 @@ function evaluateClaudeToolPermission(input: EvaluateClaudeToolPermissionInput):
 	const actionClass = decision.classification.actionClass;
 	const disposition = mapAutonomy(level, actionClass, {
 		executeRecognized: decision.policy?.execRecognition !== "unrecognized",
+		...(readsOutsideWorkspace(decision) ? { readOutsideWorkspace: true } : {}),
 	});
 	if (disposition === "allow") {
 		const admission = input.budgetGate?.admit(mapped.clioToolName);

package/src/engine/context.ts

@@ -0,0 +1,13 @@
+/** Pi owns transcript replay. Clio's local transports consume its resolved snapshot. */
+import { type Context, getCurrentSystemPrompt, getCurrentTools, normalizeContext } from "@earendil-works/pi-ai";
+
+export { normalizeContext };
+
+export function resolvedRequestContext(context: Context): Context {
+	const { messages } = normalizeContext(context);
+	return {
+		systemPrompt: getCurrentSystemPrompt(messages),
+		tools: getCurrentTools(messages),
+		messages: messages.filter((message) => message.role !== "system"),
+	};
+}

package/src/engine/env-api-keys.ts

@@ -14,6 +14,7 @@ const ENV_KEYS: Readonly<Record<string, string>> = {
 	"qwen-token-plan-cn": "QWEN_TOKEN_PLAN_CN_API_KEY",
 	"qwen-token-plan-individual": "QWEN_TOKEN_PLAN_API_KEY",
 	openai: "OPENAI_API_KEY",
+	meta: "META_API_KEY",
 	"azure-openai-responses": "AZURE_OPENAI_API_KEY",
 	nvidia: "NVIDIA_API_KEY",
 	deepseek: "DEEPSEEK_API_KEY",
@@ -60,7 +61,7 @@ function apiKeyEnvVars(provider: string): readonly string[] | undefined {
 	return name ? [name] : undefined;
 }
 
-/** Synchronous provider-key discovery pinned to pi-ai 0.85's public behavior. */
+/** Synchronous provider-key discovery pinned to pi-ai 0.86.1's public behavior. */
 export function findEngineEnvKeys(provider: string, env?: ProviderEnv): string[] | undefined {
 	const names = apiKeyEnvVars(provider);
 	if (!names) return undefined;

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

@@ -140,6 +140,7 @@ type ReplacementBlock = TextContent | ThinkingContent;
 export function filterGemmaChannelStream(
 	source: AssistantMessageEventStream,
 	enabled: boolean,
+	fail: (stream: AssistantMessageEventStream, error: unknown) => void,
 ): AssistantMessageEventStream {
 	if (!enabled) return source;
 	const filtered = createAssistantMessageEventStream();
@@ -234,8 +235,8 @@ export function filterGemmaChannelStream(
 				} else filtered.push(event as AssistantMessageEvent);
 			}
 			filtered.end();
-		} catch {
-			filtered.end();
+		} catch (error) {
+			fail(filtered, error);
 		}
 	})();
 	return filtered;

package/src/engine/instrumented-tui.ts

@@ -126,6 +126,30 @@ export class InstrumentedTuiMainScreen extends TuiMainScreen {
 }
 
 export class InstrumentedTuiAltScreen extends TuiAltScreen {
+	private terminalSelectionUsers = 0;
+	private readonly capturesMouse: boolean;
+
+	/** pi-tui selects transcript text, but capturing overlays consume its mouse path.
+	 * Let the terminal select the stable interview screen until it closes. */
+	useTerminalSelection(): () => void {
+		if (!this.capturesMouse) return () => {};
+		if (this.terminalSelectionUsers++ === 0) this.terminal.write("\x1b[?1006l\x1b[?1003l\x1b[?1002l\x1b[?1000l");
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			if (--this.terminalSelectionUsers !== 0) return;
+			// Match pi-tui's negotiated tracking mode; focus reporting was never disabled.
+			const term = process.env.TERM?.toLowerCase() ?? "";
+			const multiplexed =
+				process.env.TMUX !== undefined ||
+				process.env.ZELLIJ !== undefined ||
+				process.env.STY !== undefined ||
+				term.startsWith("tmux") ||
+				term.startsWith("screen");
+			this.terminal.write(`\x1b[?1000h\x1b[?1002h${multiplexed ? "" : "\x1b[?1003h"}\x1b[?1006h`);
+		};
+	}
 	private currentFrame: unknown | undefined;
 
 	constructor(
@@ -137,6 +161,7 @@ export class InstrumentedTuiAltScreen extends TuiAltScreen {
 		renderAdmission?: TuiRenderAdmission,
 	) {
 		super(terminal, showHardwareCursor, logDirectory, options);
+		this.capturesMouse = options?.mouse ?? true;
 		this.deferredAdmission = new DeferredRenderAdmission(renderAdmission, (force) => super.requestRender(force));
 	}
 

package/src/engine/loop-guard.ts

@@ -35,6 +35,7 @@ import type { MiddlewareHookRegistration } from "../domains/middleware/runtime.j
 import type { MiddlewareEffect, MiddlewareHookInput } from "../domains/middleware/types.js";
 import type { SafetyContract } from "../domains/safety/contract.js";
 import { hashToolCall } from "../domains/safety/loop-detector.js";
+import { resolveReadPath } from "../tools/path-utils.js";
 import type { AgentMessage } from "./types.js";
 
 export const LOOP_GUARD_REGISTRATION_ID = "guard.loop";
@@ -200,6 +201,16 @@ export function isLockedSynthesisFallbackOnly(message: AgentMessage | undefined)
 
 export const LOCKED_SYNTHESIS_REPROMPT_TOOL = "clio_synthesis_reprompt";
 
+/** Preserve the task and safety contract while retiring the earlier tool-use phase. */
+export function lockedSynthesisSystemPrompt(systemPrompt: string, requiredResult?: string): string {
+	return [
+		systemPrompt,
+		"# Current execution phase: final synthesis",
+		"Tools are disabled for the rest of this run. Earlier instructions to use tools apply only to the completed tool phase. Do not emit tool calls or tool-call markup. Return the final result now using the evidence already observed; preserve all safety rules and the required result format. Do not invent missing evidence.",
+		...(requiredResult ? [`Required terminal result: ${requiredResult}`] : []),
+	].join("\n\n");
+}
+
 /**
  * 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
@@ -210,6 +221,7 @@ export const LOCKED_SYNTHESIS_REPROMPT_TOOL = "clio_synthesis_reprompt";
 export function lockedSynthesisRepromptMessages(
 	attempt: number,
 	origin: { provider: string; api: string; model: string },
+	requiredResult?: string,
 ): ReadonlyArray<AgentMessage> {
 	const id = `clio-synthesis-reprompt-${attempt}`;
 	const timestamp = Date.now();
@@ -239,8 +251,9 @@ export function lockedSynthesisRepromptMessages(
 					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.",
+						"final answer now in the required result format (JSON when a result contract requires it; otherwise prose), with no tool-call " +
+						"markup of any kind." +
+						(requiredResult ? `\nRequired terminal result: ${requiredResult}` : ""),
 				},
 			],
 			isError: true,
@@ -259,7 +272,7 @@ function synthesisLockoutDirective(): string {
 	return (
 		"loop guard: this turn reached its tool-call limit after repeated identical calls, so tool calls are now " +
 		"disabled for the rest of this turn. Everything you retrieved is already in the conversation above. Answer " +
-		"the operator now, in plain prose, from what you have gathered. Do not write tool-call markup such as " +
+		"now from what you have gathered, preserving the required result format (JSON for a JSON result contract; otherwise prose). Do not write tool-call markup such as " +
 		"<tool_call> blocks; tool calls are disabled and will not run."
 	);
 }
@@ -276,7 +289,7 @@ function synthesisBackstopReason(tool: string): string {
 function workerExplorationSynthesisDirective(limit: number): string {
 	return (
 		`worker exploration budget reached (${limit}); exploration tools are now disabled for this run. ` +
-		"Answer in plain prose from the evidence already gathered, with live path:line citations. Do not retry or " +
+		"Return the required result format from the evidence already gathered: keep JSON when the result contract requires JSON, and keep citations grounded in actual reads. Do not retry or " +
 		"substitute another tool call."
 	);
 }
@@ -431,6 +444,8 @@ export function readOrchTurnToolCallBudget(): OrchTurnToolCallBudget {
 
 export interface CreateLoopGuardRegistrationOptions {
 	safety: SafetyContract;
+	/** Enables returned-read coverage only when the caller supplies its result-shaping cap. */
+	readResultMaxBytes?: number;
 	/** Orchestrator only: LoopBlocked events for the interactive layer. */
 	bus?: SafeEventBus;
 	/** Loop blocks tolerated per turn before the block reason announces a stop. */
@@ -626,6 +641,11 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 	 * differently answered call resets it.
 	 */
 	const stagnationByTurn = new Map<string, { reducedFingerprint: string; resultFingerprint: string; streak: number }>();
+	const eofByTurn = new Map<string, { identity: string; streak: number }>();
+	// Actual returned line coverage, not requested limits. File stamps retire old
+	// coverage after external changes; successful writes/edits clear it as well.
+	const readCoverage = new Map<string, { bytes: number; mtimeMs: number; ranges: Array<[number, number]> }>();
+	const redundantReadsByTurn = new Map<string, number>();
 	const crossArgumentResultsByTurn = new Map<
 		string,
 		{ tool: string; resultFingerprint: string; argumentFingerprints: Set<string>; warned: boolean }
@@ -670,6 +690,8 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 		if (input.metadata?.resultKind !== "ok") return;
 		if (input.toolName === ToolNames.Write || input.toolName === ToolNames.Edit) {
 			bumpBoundedCounter(mutationEpochByTurn, input.turnId ?? NO_TURN_BUCKET);
+			readCoverage.clear();
+			redundantReadsByTurn.clear();
 		}
 		if (!resultCarriesEvidence(input.toolResultDetails)) return;
 		const tool = input.toolName;
@@ -878,7 +900,7 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 					reason:
 						`tool-call budget: you have made ${callsThisTurn} tool calls in this turn (soft budget ${turnBudget.soft}). ` +
 						`Every further tool call this turn will be blocked, so do not retry this call and do not substitute ` +
-						`another one. Summarize what you have found so far in plain text, state the single next step you ` +
+						`another one. Summarize what you have found so far in the required result format, state the single next step you ` +
 						`propose, and wait for the operator.`,
 					severity: "hard-block",
 				},
@@ -920,6 +942,147 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 		return [{ kind: "block_tool", reason, severity: "hard-block" }];
 	};
 
+	const readCoverageEffects = (input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> => {
+		const turnKey = input.turnId ?? NO_TURN_BUCKET;
+		const reset = () => {
+			redundantReadsByTurn.delete(turnKey);
+			return [];
+		};
+		const details = input.toolResultDetails;
+		const file = details?.file as { bytes?: unknown; mtimeMs?: unknown } | undefined;
+		const observation = details?.observation as
+			| { tool?: unknown; unit?: unknown; format?: unknown; shownCount?: unknown; truncated?: unknown }
+			| undefined;
+		const path = input.toolArgs?.path;
+		const offset = input.toolArgs?.offset ?? 1;
+		const resultBytes = input.metadata?.resultBytes;
+		// after_tool precedes the registry's final shaping pass. If that pass
+		// could shorten the source, its pre-shaping line count is not evidence.
+		const deliveredCap = Math.min(options.readResultMaxBytes ?? 0, resolveGuardrail("readMaxBytes"));
+		if (
+			!Number.isFinite(deliveredCap) ||
+			deliveredCap <= 0 ||
+			typeof resultBytes !== "number" ||
+			!Number.isFinite(resultBytes) ||
+			resultBytes > deliveredCap ||
+			input.toolName !== ToolNames.Read ||
+			input.metadata?.resultKind !== "ok" ||
+			typeof path !== "string" ||
+			input.toolArgs?.tail !== undefined ||
+			typeof offset !== "number" ||
+			!Number.isSafeInteger(offset) ||
+			offset < 1 ||
+			typeof file?.bytes !== "number" ||
+			!Number.isFinite(file.bytes) ||
+			typeof file.mtimeMs !== "number" ||
+			!Number.isFinite(file.mtimeMs) ||
+			details?.fileChange !== undefined ||
+			observation?.tool !== ToolNames.Read ||
+			observation.unit !== "lines" ||
+			observation.format !== "text" ||
+			typeof observation.shownCount !== "number" ||
+			!Number.isSafeInteger(observation.shownCount) ||
+			observation.shownCount <= 0
+		)
+			return reset();
+		// A byte-truncated final line may only be a prefix. Conservatively exclude
+		// the last line of any truncated window from previously observed coverage.
+		const end = offset + observation.shownCount - 1;
+		const coveredEnd = end - (observation.truncated === true ? 1 : 0);
+		if (!Number.isSafeInteger(end)) return reset();
+		// Use the same path resolution as read (including symlinks and aliases).
+		// Numbered output is separate evidence: the first citation reread is useful.
+		let canonicalPath: string;
+		try {
+			canonicalPath = resolveReadPath(path);
+		} catch {
+			return reset();
+		}
+		const key = `${turnKey}\0${canonicalPath}\0${input.toolArgs?.line_numbers === true}`;
+		let entry = readCoverage.get(key);
+		if (!entry || entry.bytes !== file.bytes || entry.mtimeMs !== file.mtimeMs) {
+			entry = { bytes: file.bytes, mtimeMs: file.mtimeMs, ranges: [] };
+		}
+		const redundant = entry.ranges.some(([start, stop]) => start <= offset && stop >= end);
+		// Even a possibly partial one-line result is redundant when an earlier
+		// complete read already covered that line. It need not add new coverage.
+		const ranges: Array<[number, number]> = [...entry.ranges];
+		if (coveredEnd >= offset) ranges.push([offset, coveredEnd]);
+		ranges.sort((a, b) => a[0] - b[0]);
+		entry.ranges = [];
+		for (const range of ranges) {
+			const last = entry.ranges.at(-1);
+			if (last && range[0] <= last[1] + 1) last[1] = Math.max(last[1], range[1]);
+			else entry.ranges.push(range);
+		}
+		// Forget excess evidence conservatively instead of retaining unbounded state.
+		entry.ranges = entry.ranges.slice(-SUCCEEDED_FINGERPRINT_LIMIT);
+		readCoverage.delete(key);
+		if (readCoverage.size >= SUCCEEDED_FINGERPRINT_LIMIT) {
+			const oldest = readCoverage.keys().next().value;
+			if (oldest !== undefined) readCoverage.delete(oldest);
+		}
+		readCoverage.set(key, entry);
+		if (!redundant) return reset();
+		const streak = bumpBoundedCounter(redundantReadsByTurn, turnKey);
+		if (streak < RESULT_STAGNATION_THRESHOLD || lockoutByTurn.has(turnKey)) return [];
+		const reason = `loop detected: ${streak} consecutive read calls returned only source lines already observed from unchanged files. Reuse the evidence above and return the required result format; do not page through it again.`;
+		// The read already ran and remains successful. Reuse the existing loop
+		// budget/lock transition, delivering its reason as a result annotation.
+		return blockAsLoop(input, turnKey, ToolNames.Read, streak, reason, options.now?.() ?? Date.now()).map((effect) =>
+			effect.kind === "block_tool"
+				? { kind: "annotate_tool_result" as const, message: effect.reason, severity: "warn" as const }
+				: effect,
+		);
+	};
+
+	// Read's typed EOF result proves that changing offsets cannot reveal more
+	// content in this file version. Error strings contain offsets and therefore
+	// cannot use the byte-identical successful-result detector.
+	const readEofEffects = (input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> => {
+		const turnKey = input.turnId ?? NO_TURN_BUCKET;
+		const details = input.toolResultDetails;
+		const file = details?.file as { bytes?: unknown; mtimeMs?: unknown } | undefined;
+		if (
+			input.toolName !== ToolNames.Read ||
+			input.metadata?.resultKind !== "error" ||
+			details?.code !== "read_past_eof" ||
+			typeof input.toolArgs?.path !== "string" ||
+			typeof file?.bytes !== "number" ||
+			!Number.isFinite(file.bytes) ||
+			typeof file.mtimeMs !== "number" ||
+			!Number.isFinite(file.mtimeMs) ||
+			typeof details.totalLines !== "number" ||
+			!Number.isSafeInteger(details.totalLines) ||
+			details.totalLines < 0
+		) {
+			eofByTurn.delete(turnKey);
+			return [];
+		}
+		let path: string;
+		try {
+			path = resolveReadPath(input.toolArgs.path);
+		} catch {
+			eofByTurn.delete(turnKey);
+			return [];
+		}
+		const identity = JSON.stringify([path, file.bytes, file.mtimeMs, details.totalLines]);
+		const previous = eofByTurn.get(turnKey);
+		const streak = previous?.identity === identity ? previous.streak + 1 : 1;
+		if (!eofByTurn.has(turnKey) && eofByTurn.size >= LOOP_GUARD_TURN_LIMIT) {
+			const oldest = eofByTurn.keys().next().value;
+			if (oldest !== undefined) eofByTurn.delete(oldest);
+		}
+		eofByTurn.set(turnKey, { identity, streak });
+		if (streak < 2 || lockoutByTurn.has(turnKey)) return [];
+		const reason = `loop detected: ${streak} consecutive reads went past the end of the same unchanged file. Changing offset or limit cannot reveal more content. Reuse the evidence already returned and synthesize the answer.`;
+		return blockAsLoop(input, turnKey, ToolNames.Read, streak, reason, options.now?.() ?? Date.now()).map((effect) =>
+			effect.kind === "block_tool"
+				? { kind: "annotate_tool_result" as const, message: effect.reason, severity: "warn" as const }
+				: effect,
+		);
+	};
+
 	return {
 		id: LOOP_GUARD_REGISTRATION_ID,
 		description:
@@ -927,7 +1090,10 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 		hooks: ["before_tool", "after_tool"],
 		callCount: () => count,
 		extendWorkerToolCallPhase(phase): boolean {
+			// A repair may extend a soft work phase, never a sealed loop or hard-cap lock.
 			if (
+				lockoutByTurn.size > 0 ||
+				capLockout !== null ||
 				softLimit === undefined ||
 				!Number.isSafeInteger(phase.toolCalls) ||
 				!Number.isSafeInteger(phase.readReserve) ||
@@ -959,7 +1125,7 @@ export function createLoopGuardRegistration(options: CreateLoopGuardRegistration
 			if (input.hook === "after_tool") {
 				recordSuccessfulResult(input);
 				recordResultForStagnation(input);
-				const effects = [...crossArgumentResultEffects(input)];
+				const effects = [...crossArgumentResultEffects(input), ...readCoverageEffects(input), ...readEofEffects(input)];
 				if (
 					options.toolBudgetAdvisory &&
 					!advisoryEmitted &&

package/src/engine/pi-mono-names.ts

@@ -1,3 +1,7 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolvePackageRoot } from "../core/package-root.js";
+
 /**
  * Canonical pi-mono package names. The engine barrel is the sole place in
  * the codebase where the literal `@earendil-works/*` strings are allowed to
@@ -11,3 +15,15 @@ export const PI_MONO_PACKAGES = {
 } as const;
 
 export type PiMonoPackageName = (typeof PI_MONO_PACKAGES)[keyof typeof PI_MONO_PACKAGES];
+
+let cachedPiMonoVersion: string | null = null;
+
+/** Engine dependency metadata is outside the instant terminal's package/version path. */
+export function readPiMonoVersion(): string {
+	if (cachedPiMonoVersion) return cachedPiMonoVersion;
+	const pkg = JSON.parse(readFileSync(join(resolvePackageRoot(), "package.json"), "utf8")) as {
+		dependencies?: Record<string, string>;
+	};
+	cachedPiMonoVersion = pkg.dependencies?.[PI_MONO_PACKAGES.agentCore] ?? "unknown";
+	return cachedPiMonoVersion;
+}

package/src/engine/prewarm.ts

@@ -1,3 +1,10 @@
+import {
+	createInitialSystemMessage,
+	getCurrentTools,
+	getToolStateChanges,
+	toToolDeclaration,
+} from "@earendil-works/pi-ai";
+import { normalizeContext } from "./context.js";
 /**
  * One bounded-output warm through the eventual caller's engine request path.
  * Copies portable context, applies public Pi transforms and payload hooks,
@@ -38,7 +45,7 @@ export interface PrewarmContext {
  * filter so its message array is the one a turn would send, not the agent's
  * internal list.
  */
-const LLM_MESSAGE_ROLES: ReadonlySet<string> = new Set(["user", "assistant", "toolResult"]);
+const LLM_MESSAGE_ROLES: ReadonlySet<string> = new Set(["system", "user", "assistant", "toolResult"]);
 
 export interface PrewarmRoundInput {
 	model: EngineModel;
@@ -53,6 +60,8 @@ export interface PrewarmRoundInput {
 	signal?: AbortSignal;
 	/** Admission bound on the engine's input estimate, after context selection. */
 	maxInputTokens?: number;
+	/** Recheck foreground ownership after asynchronous context transforms. */
+	canSend?: () => boolean;
 	/** Public Pi preparation hooks of the eventual caller. No tools or agent loop are executed. */
 	agent?: Pick<
 		Agent,
@@ -156,6 +165,16 @@ export async function runPrewarmRound(input: PrewarmRoundInput): Promise<Prewarm
 		}
 	}
 
+	if (metadata?.runtimeId === "litellm") {
+		const onPayload = input.agent?.onPayload;
+		options.onPayload = async (payload: unknown, currentModel: EngineModel) => {
+			const patched = (await onPayload?.(payload, currentModel)) ?? payload;
+			// Warming is authorized for the verified local route only. A gateway
+			// must not turn an unavailable local model into a billed fallback.
+			return { ...(patched as Record<string, unknown>), num_retries: 0, disable_fallbacks: true };
+		};
+	}
+
 	const send = input.streamFn ?? input.agent?.streamFunction ?? streamSimple;
 	const startedAt = performance.now();
 	let firstDeltaAt: number | null = null;
@@ -164,28 +183,38 @@ export async function runPrewarmRound(input: PrewarmRoundInput): Promise<Prewarm
 
 	try {
 		input.signal?.throwIfAborted();
-		let messages: AgentMessage[] = [
-			...structuredClone([...input.state.messages]),
-			{ role: "user", content: [{ type: "text", text: PREWARM_USER_TEXT }], timestamp: Date.now() },
-		];
+		// Match Agent's initial baseline and pre-request tool reconciliation, using
+		// Pi's public declaration diff. Never clone executable AgentTool objects.
+		let messages: AgentMessage[] = structuredClone([...input.state.messages]);
+		if (messages[0]?.role !== "system") {
+			const initial = createInitialSystemMessage(input.state.systemPrompt, input.state.tools.map(toToolDeclaration));
+			if (initial) messages.unshift(initial);
+		}
+		const changes = getToolStateChanges(getCurrentTools(messages), input.state.tools.map(toToolDeclaration));
+		if (changes.toolsAdded.length || changes.toolsRemoved.length) {
+			messages.push({
+				role: "system",
+				content: "",
+				timestamp: Date.now(),
+				...(changes.toolsAdded.length ? { toolsAdded: changes.toolsAdded } : {}),
+				...(changes.toolsRemoved.length ? { toolsRemoved: changes.toolsRemoved } : {}),
+			});
+		}
+		messages.push({ role: "user", content: [{ type: "text", text: PREWARM_USER_TEXT }], timestamp: Date.now() });
 		if (input.agent?.transformContext) messages = await input.agent.transformContext(messages, input.signal);
 		const converted = input.agent
 			? await input.agent.convertToLlm(messages)
 			: messages.filter((message) => LLM_MESSAGE_ROLES.has(message.role));
 		input.signal?.throwIfAborted();
-		const context = {
-			systemPrompt: input.state.systemPrompt,
-			messages: converted,
-			tools: [...input.state.tools],
-		} as Parameters<typeof streamSimple>[1];
+		// Transforms own the final prompt and declarations, just as on a real turn.
+		const context = normalizeContext({ messages: converted as Parameters<typeof streamSimple>[1]["messages"] });
 		if (input.maxInputTokens !== undefined && estimateInputTokensFromContext(context) > input.maxInputTokens) {
 			throw new Error("pre-warm input estimate exceeds its token budget");
 		}
-		const events = await send(
-			model,
-			context as unknown as Parameters<typeof streamSimple>[1],
-			options as unknown as Parameters<typeof streamSimple>[2],
-		);
+		if (input.canSend?.() === false) {
+			return { aborted: true, usage: null, backend: null, timing: { ttftMs: null, apiMs: elapsed() }, errorMessage: null };
+		}
+		const events = await send(model, context, options as unknown as Parameters<typeof streamSimple>[2]);
 		for await (const event of events) {
 			const hasDelta =
 				event.type === "toolcall_start" ||