@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/engine/external-subprocess.ts

@@ -1,15 +1,117 @@
 import type { ChildProcessByStdio } from "node:child_process";
 import type { Readable } from "node:stream";
 
+import { boundedExternalDiagnostic } from "../core/external-diagnostic.js";
+
 export type SubprocessWithStdio = ChildProcessByStdio<null, Readable, Readable>;
 
+export type BoundedLine = { kind: "line"; line: string } | { kind: "oversized" };
+
+/**
+ * Split a byte stream without ever retaining more than one bounded line.
+ * Node has already allocated each incoming chunk, but an unterminated provider
+ * line cannot make this decoder accumulate without limit.
+ */
+export async function* readBoundedLines(
+	readable: Readable,
+	options: { maxLineBytes: number; maxTotalBytes: number },
+): AsyncGenerator<BoundedLine> {
+	let segments: Buffer[] = [];
+	let lineBytes = 0;
+	let totalBytes = 0;
+	let discarding = false;
+	const finishLine = (): BoundedLine | null => {
+		if (discarding) {
+			segments = [];
+			lineBytes = 0;
+			discarding = false;
+			return { kind: "oversized" };
+		}
+		if (lineBytes === 0) return { kind: "line", line: "" };
+		const joined = Buffer.concat(segments, lineBytes);
+		segments = [];
+		lineBytes = 0;
+		const end = joined.at(-1) === 0x0d ? joined.length - 1 : joined.length;
+		return { kind: "line", line: joined.subarray(0, end).toString("utf8") };
+	};
+
+	for await (const raw of readable) {
+		const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(String(raw));
+		totalBytes += chunk.byteLength;
+		if (totalBytes > options.maxTotalBytes) throw new Error("external stdout exceeded the cumulative output limit");
+		let offset = 0;
+		while (offset < chunk.length) {
+			const newline = chunk.indexOf(0x0a, offset);
+			const end = newline === -1 ? chunk.length : newline;
+			const piece = chunk.subarray(offset, end);
+			if (!discarding && piece.length > 0) {
+				if (lineBytes + piece.length > options.maxLineBytes) {
+					segments = [];
+					lineBytes = 0;
+					discarding = true;
+				} else {
+					segments.push(piece);
+					lineBytes += piece.length;
+				}
+			}
+			if (newline === -1) break;
+			const line = finishLine();
+			if (line) yield line;
+			offset = newline + 1;
+		}
+	}
+	if (discarding || lineBytes > 0) {
+		const line = finishLine();
+		if (line) yield line;
+	}
+}
+
 export async function readStderr(child: { stderr: Readable }): Promise<string> {
-	let stderr = "";
+	let tail = Buffer.alloc(0);
 	for await (const chunk of child.stderr) {
-		stderr += String(chunk);
-		if (stderr.length > 8192) stderr = stderr.slice(-8192);
+		const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+		tail = Buffer.concat([tail, bytes]);
+		if (tail.byteLength > 8192) tail = tail.subarray(tail.byteLength - 8192);
 	}
-	return stderr;
+	return boundedExternalDiagnostic(tail.toString("utf8"));
+}
+
+export interface ProcessTreeTerminator {
+	terminate(): void;
+	cleanup(): void;
+}
+
+/** POSIX process-group termination with a direct-child fallback; Windows is direct-child only. */
+export function createProcessTreeTerminator(
+	child: { pid?: number | undefined; exitCode: number | null; kill(signal?: NodeJS.Signals): boolean },
+	graceMs = 1500,
+): ProcessTreeTerminator {
+	let sent = false;
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	const signal = (name: NodeJS.Signals): void => {
+		if (child.exitCode !== null) return;
+		if (child.pid && process.platform !== "win32") {
+			try {
+				process.kill(-child.pid, name);
+				return;
+			} catch {
+				// The child may not have established its group yet.
+			}
+		}
+		child.kill(name);
+	};
+	return {
+		terminate() {
+			if (sent) return;
+			sent = true;
+			signal("SIGTERM");
+			timer = setTimeout(() => signal("SIGKILL"), graceMs);
+		},
+		cleanup() {
+			if (timer) clearTimeout(timer);
+			timer = null;
+		},
+	};
 }
 
 export function waitForClose(child: {
@@ -17,7 +119,13 @@ export function waitForClose(child: {
 	once(event: "close", listener: (code: number | null) => void): unknown;
 }): Promise<number> {
 	return new Promise((resolve) => {
-		child.once("error", () => resolve(1));
-		child.once("close", (code: number | null) => resolve(code ?? 1));
+		let settled = false;
+		const finish = (code: number): void => {
+			if (settled) return;
+			settled = true;
+			resolve(code);
+		};
+		child.once("error", () => finish(1));
+		child.once("close", (code: number | null) => finish(code ?? 1));
 	});
 }

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/background-model-metadata.ts

@@ -0,0 +1,18 @@
+import type { ProvidersContract } from "../domains/providers/contract.js";
+
+/** Cold gateway roles need their own declared model controls before synthesis.
+ * Read metadata only; an unknown/mixed successful probe remains authoritative.
+ * Memory supplies its existing deadline/generation signal, including auth.
+ */
+export async function prepareBackgroundModelMetadata(
+	providers: ProvidersContract,
+	targetId: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	signal?.throwIfAborted();
+	const status = providers.list().find((entry) => entry.target.id === targetId);
+	if (status?.target.runtime === "litellm" && status.health.lastCheckAt === null) {
+		await providers.probeTarget(targetId, { reasoning: false, ...(signal ? { signal } : {}) });
+	}
+	signal?.throwIfAborted();
+}

package/src/entry/compaction-prompt.ts

@@ -0,0 +1,57 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const MAX_PROMPT_BYTES = 64 * 1024;
+
+/** Absolute paths remain supported; relative paths are based on the current session workspace. */
+export async function readCompactionSystemPrompt(
+	path: string | null | undefined,
+	workspace: string,
+): Promise<string | undefined> {
+	if (path === undefined || path === null) return undefined;
+	// Quote the configured path, not file contents. Escape invisible directional
+	// formatting too, and bound diagnostics for an invalid oversized filename.
+	const quotedPath = JSON.stringify(path).replace(
+		/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu,
+		(character) => `\\u{${character.codePointAt(0)?.toString(16)}}`,
+	);
+	const displayPath = quotedPath.length <= 1024 ? quotedPath : `${quotedPath.slice(0, 1024)}...`;
+	const failure = (reason: string) =>
+		new Error(
+			`context.compaction.systemPrompt ${displayPath} ${reason}; set a readable, nonempty UTF-8 file of at most ${MAX_PROMPT_BYTES} bytes (relative to the session workspace), or unset the override`,
+		);
+	if (!path.trim()) throw failure("path is empty");
+	let file: Awaited<ReturnType<typeof open>>;
+	try {
+		// Nonblocking open prevents a named pipe from hanging compaction before stat.
+		file = await open(resolve(workspace, path), constants.O_RDONLY | constants.O_NONBLOCK);
+	} catch {
+		throw failure("cannot be opened");
+	}
+	try {
+		if (!(await file.stat()).isFile()) throw failure("must refer to a regular file");
+		// Read only limit + 1, even if the file grows after stat. No unbounded readFile.
+		const buffer = Buffer.alloc(MAX_PROMPT_BYTES + 1);
+		let length = 0;
+		while (length < buffer.length) {
+			const { bytesRead } = await file.read(buffer, length, buffer.length - length, null);
+			if (bytesRead === 0) break;
+			length += bytesRead;
+		}
+		if (length > MAX_PROMPT_BYTES) throw failure("file is oversized");
+		let text: string;
+		try {
+			text = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length));
+		} catch {
+			throw failure("file is not valid UTF-8");
+		}
+		if (!text.trim()) throw failure("file is empty");
+		return text;
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("context.compaction.systemPrompt ")) throw error;
+		throw failure("file cannot be read");
+	} finally {
+		await file.close();
+	}
+}

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 } : {}),
+		})),
+	};
+}