@iowarp/clio-coder 0.4.4 → 0.4.5

package/src/interactive/turn-context.ts

@@ -6,6 +6,7 @@
  * all flow through it.
  */
 
+import { createHash } from "node:crypto";
 import {
 	BusChannels,
 	type ContextActivityStatus,
@@ -23,6 +24,7 @@ import {
 import type { ClioSettings } from "../core/config.js";
 import type { SafeEventBus } from "../core/event-bus.js";
 import { residencyTargetKey } from "../core/residency-target-key.js";
+import type { PendingSkillToolPolicy } from "../core/skill-activation.js";
 import type { ToolName } from "../core/tool-names.js";
 import { buildEvictionFields, planEviction } from "../domains/context/working-set/engine.js";
 import { foldWorkingSet } from "../domains/context/working-set/fold.js";
@@ -45,7 +47,8 @@ import {
 	DEFAULT_COMPACTION_THRESHOLD,
 	shouldCompact,
 } from "../domains/session/compaction/auto.js";
-import type { CompactResult } from "../domains/session/compaction/compact.js";
+import type { CompactInput, CompactResult } from "../domains/session/compaction/compact.js";
+import { DEFAULT_KEEP_RECENT_TOKENS } from "../domains/session/compaction/defaults.js";
 import { maskStaleObservations } from "../domains/session/compaction/mask-observations.js";
 import { estimateTokens } from "../domains/session/compaction/tokens.js";
 import {
@@ -73,13 +76,15 @@ import {
 	type PromptCacheStats,
 } from "../domains/session/context-ledger.js";
 import type { SessionContract } from "../domains/session/contract.js";
-import type { CompactionTrigger, SessionEntry } from "../domains/session/entries.js";
+import { type CompactionTrigger, mainSkillContextState, type SessionEntry } from "../domains/session/entries.js";
 import {
 	appendPromptCompileRecord,
 	PROMPT_MANIFEST_VERSION,
 	readPromptCompileRecords,
 	type SessionPromptCompileRecord,
 } from "../domains/session/prompt-manifest.js";
+import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
+import { resolveReservedOutputTokens } from "../engine/apis/output-budget.js";
 import type { AgentMessage, Usage } from "../engine/types.js";
 import { resolveToolPromptHint, type ToolRegistry } from "../tools/registry.js";
 import {
@@ -105,7 +110,13 @@ export interface TurnContextDeps {
 	observability?: ObservabilityContract | undefined;
 	bus?: SafeEventBus | undefined;
 	readSessionEntries?: (() => ReadonlyArray<SessionEntry>) | undefined;
-	autoCompact?: ((instructions?: string, trigger?: CompactionTrigger) => Promise<CompactResult | null>) | undefined;
+	autoCompact?:
+		| ((
+				instructions?: string,
+				trigger?: CompactionTrigger,
+				budget?: Pick<CompactInput, "keepRecentTokens" | "preserveUserTurnId" | "skillContextState" | "signal">,
+		  ) => Promise<CompactResult | null>)
+		| undefined;
 	/** Test seam for the eviction planner; production uses `planEviction` from the working-set engine. */
 	planEviction?: typeof planEviction;
 	getMemorySection?: (() => string) | undefined;
@@ -121,7 +132,7 @@ export interface LiveContextEstimate {
 	 * did not see.
 	 */
 	tokens: number;
-	/** Pure chars/4 projection, with the pre-existing provider-usage anchor. */
+	/** Structural projection; includes the legacy usage floor when no live anchor is trusted. */
 	estimatedTokens: number;
 	/**
 	 * Provider-attested prompt tokens for the messages up to the last reconciled
@@ -187,7 +198,10 @@ export interface TurnContext {
 		instructions?: string,
 		triggerOverride?: CompactionTrigger,
 		pendingUserText?: string,
+		pendingSkillPolicy?: PendingSkillToolPolicy,
+		signal?: AbortSignal,
 	): Promise<boolean>;
+	cancelCompaction(): void;
 	postToolContinuationGuard(
 		agentRuntime: AgentRuntime,
 		signal?: AbortSignal,
@@ -244,6 +258,7 @@ function evictionSkipMessage(
 export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	const { state, middleware } = deps;
 	const compactionTrigger = new AutoCompactionTrigger<CompactResult | null>();
+	let compactionController: AbortController | null = null;
 
 	let currentContextSnapshot: ContextSnapshot | null = null;
 	/**
@@ -252,14 +267,25 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	 *
 	 * `tokens` is the provider's own prompt count for that call plus the output
 	 * it produced, which together are what the next call's prompt carries for
-	 * the same messages. `anchoredMessageCount` is the length of the live
-	 * message list at that moment, so anything appended since is priced by
-	 * estimate and added on top. Unlike the per-message usage anchor inside
+	 * the same messages. The anchored message prefix identifies that history,
+	 * so anything appended since is priced by estimate and added on top.
+	 * Unlike the per-message usage anchor inside
 	 * `estimateAgentContextTokens`, this survives `contextUsageInvalidated`:
 	 * a working-set projection subtracts the tokens it removed rather than
 	 * throwing the attestation away.
 	 */
-	let reconciledAnchor: { tokens: number; anchoredMessageCount: number } | null = null;
+	let reconciledAnchor: {
+		tokens: number;
+		anchoredMessages: ReadonlyArray<AgentMessage>;
+		runtime: AgentRuntime;
+		model: AgentRuntime["agent"]["state"]["model"];
+		modelKey: string;
+		targetId: string;
+		runtimeId: string;
+		wireModelId: string;
+		systemPromptTokens: number;
+		toolSchemaTokens: number;
+	} | null = null;
 	let lastCompactionEvent: { stage: string; tokensBefore: number; tokensAfter: number; trigger: string } | null = null;
 	// Last settled run's provider cache usage plus whether the compiled system
 	// prompt was reused. Shown together in /context so "prompt reused" can
@@ -292,11 +318,10 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	let resumedPromptHash: string | null = null;
 	const sessionWorkingContextPaths = new Set<string>();
 	let pendingPromptLogEntry: SessionPromptCompileRecord | null = null;
-	// A post-tool guard can run after every tool result in one model turn. Once
-	// both automatic stages report that they have nothing to do, remember that
-	// stable user-turn id so the remaining results do not repeat the same plan
-	// and summary probes. A new submitted user turn gets a new id naturally.
-	let emptyAutoCompactTurnId: string | null = null;
+	// Reuse an empty automatic attempt only for identical ledger and provider
+	// context. Same-turn tool growth or same-length content replacement must
+	// get a fresh cut; ordinary below-threshold checks never fingerprint it.
+	let emptyAutoCompactContextKey: string | null = null;
 
 	// Cache-disturbance honesty (T3.3). Accumulate every known local-runtime
 	// disturbance and prefix-byte change since the last settled run. The next
@@ -549,27 +574,36 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		return { contextWindow: 0, contextWindowSource: null, contextWindowSlots: null };
 	};
 
-	/**
-	 * Carry the reconciled anchor onto the current message list: the attested
-	 * prompt for the messages it covered, plus a chars/4 estimate of everything
-	 * appended since, plus text that has not been submitted yet. The tool
-	 * schemas and the system prompt are inside the attested figure already, so
-	 * they are not added again. Null when there is no attestation, or when the
-	 * list is shorter than the anchor covered, which means the history it
-	 * described was rewritten beneath it.
-	 */
-	const reconciledAnchoredTokens = (agentRuntime: AgentRuntime, pendingUserTokens: number): number | null => {
+	const anchorModelKey = (agentRuntime: AgentRuntime): string => {
+		const model = agentRuntime.agent.state.model;
+		return JSON.stringify([model?.id, model?.provider, model?.api, model?.baseUrl]);
+	};
+
+	/** Price appended history separately so eviction can retain it without folding in static growth twice. */
+	const reconciledHistoryTokens = (agentRuntime: AgentRuntime): number | null => {
 		const anchor = reconciledAnchor;
 		if (!anchor) return null;
 		const messages = agentRuntime.agent.state.messages;
-		if (anchor.anchoredMessageCount > messages.length) return null;
+		if (
+			anchor.runtime !== agentRuntime ||
+			anchor.model !== agentRuntime.agent.state.model ||
+			anchor.modelKey !== anchorModelKey(agentRuntime) ||
+			anchor.targetId !== agentRuntime.targetId ||
+			anchor.runtimeId !== agentRuntime.runtimeId ||
+			anchor.wireModelId !== agentRuntime.wireModelId ||
+			anchor.anchoredMessages.length > messages.length ||
+			anchor.anchoredMessages.some((message, index) => message !== messages[index])
+		) {
+			reconciledAnchor = null;
+			return null;
+		}
 		let tail = 0;
-		for (let i = anchor.anchoredMessageCount; i < messages.length; i += 1) {
+		for (let i = anchor.anchoredMessages.length; i < messages.length; i += 1) {
 			const message = messages[i];
 			if (message === undefined) continue;
 			tail += estimateAgentMessageTokens(message);
 		}
-		return anchor.tokens + tail + pendingUserTokens;
+		return anchor.tokens + tail;
 	};
 
 	const liveContextEstimate = (agentRuntime: AgentRuntime, pendingUserText?: string): LiveContextEstimate => {
@@ -581,8 +615,22 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			...(pendingUserText !== undefined ? { pendingUserText } : {}),
 		};
 		const breakdown = estimateAgentContextBreakdown(estimateInput);
-		const estimatedTokens = estimateAgentContextTokens(estimateInput);
-		const reconciledTokens = reconciledAnchoredTokens(agentRuntime, breakdown.pendingUserTokens);
+		const historyTokens = reconciledHistoryTokens(agentRuntime);
+		const anchor = reconciledAnchor;
+		// Provider usage already includes the old system prompt and schemas.
+		// Price only positive growth, separately: shrinking one must not hide
+		// growth in the other when the measured prompt exceeds chars/4.
+		const reconciledTokens =
+			historyTokens !== null && anchor
+				? historyTokens +
+					breakdown.pendingUserTokens +
+					Math.max(0, breakdown.systemPromptTokens - anchor.systemPromptTokens) +
+					Math.max(0, breakdown.toolSchemaTokens - anchor.toolSchemaTokens)
+				: null;
+		const estimatedTokens =
+			reconciledTokens === null
+				? estimateAgentContextTokens(estimateInput)
+				: breakdown.systemPromptTokens + breakdown.messageTokens + breakdown.pendingUserTokens + breakdown.toolSchemaTokens;
 		return {
 			// The estimate is a floor, not a competing verdict: it prices material
 			// the attested call never saw, so a provider count below it would be
@@ -601,13 +649,20 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 	 * what the planner priced out against the same projection and re-anchor on
 	 * the refreshed list, instead of discarding the figure and falling back to
 	 * pure chars/4 exactly when the accounting matters most (issue #227).
-	 * Call after the message list has been rebuilt.
+	 * Materialize history before rebuilding the list; otherwise advancing the
+	 * anchor would lose tool results appended since the last measured call.
+	 * Static baselines stay tied to that call until the next reconciliation.
 	 */
-	const carryReconciledAnchorThroughProjection = (agentRuntime: AgentRuntime, tokensRemoved: number): void => {
-		if (!reconciledAnchor) return;
+	const carryReconciledAnchorThroughProjection = (
+		agentRuntime: AgentRuntime,
+		historyTokens: number | null,
+		tokensRemoved: number,
+	): void => {
+		if (!reconciledAnchor || historyTokens === null) return;
 		reconciledAnchor = {
-			tokens: Math.max(0, reconciledAnchor.tokens - Math.max(0, tokensRemoved)),
-			anchoredMessageCount: agentRuntime.agent.state.messages.length,
+			...reconciledAnchor,
+			tokens: Math.max(0, historyTokens - Math.max(0, tokensRemoved)),
+			anchoredMessages: [...agentRuntime.agent.state.messages],
 		};
 	};
 
@@ -679,14 +734,57 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		instructions?: string,
 		triggerOverride?: CompactionTrigger,
 		pendingUserText?: string,
+		pendingSkillPolicy?: PendingSkillToolPolicy,
+		signal?: AbortSignal,
 	): Promise<boolean> => {
 		if (!deps.readSessionEntries) return false;
-		const activeAutoTurnId = force ? null : state.activeUserTurnId;
-		if (activeAutoTurnId && emptyAutoCompactTurnId === activeAutoTurnId) return false;
+		// Overflow forces a fit attempt even below the automatic threshold, but
+		// still needs the request budget and active task. Manual force keeps its defaults.
+		const useRequestBudget = !force || triggerOverride === "overflow";
+		const activeAutoTurnId = useRequestBudget ? state.activeUserTurnId : null;
+		const skillContextState = mainSkillContextState(
+			filterEntriesToActivePath(deps.readSessionEntries(), state.lastTurnId ?? undefined),
+			pendingSkillPolicy ?? state.currentPendingSkillPolicy ?? state.activeSkillSurface,
+		);
 		const settings = deps.getSettings();
 		const cfg = settings.context.compaction;
 		const autoEnabled = cfg?.auto !== false;
 		if (!force && !autoEnabled) return false;
+		const compactionThreshold = cfg?.threshold ?? DEFAULT_COMPACTION_THRESHOLD;
+		const pressureEstimate = force ? null : liveContextEstimate(agentRuntime, pendingUserText);
+		if (
+			pressureEstimate &&
+			!shouldCompact(pressureEstimate.tokens, compactionThreshold, pressureEstimate.contextWindow).shouldCompact
+		)
+			return false;
+		// Empty cuts are reusable only while their source and provider context
+		// remain unchanged. Tools can grow the same user turn into a useful cut.
+		const attemptKey =
+			!force && activeAutoTurnId
+				? createHash("sha256")
+						.update(
+							JSON.stringify({
+								turn: activeAutoTurnId,
+								leaf: state.lastTurnId,
+								entries: deps.readSessionEntries(),
+								context: {
+									systemPrompt: agentRuntime.agent.state.systemPrompt,
+									messages: agentRuntime.agent.state.messages,
+									tools: agentRuntime.agent.state.tools,
+									model: agentRuntime.agent.state.model,
+									thinkingLevel: agentRuntime.agent.state.thinkingLevel,
+								},
+								pendingUserText,
+								skillContextState,
+								estimate: pressureEstimate,
+								compaction: cfg,
+								workingSet: settings.context.workingSet,
+								output: settings.chat.maxOutputTokens,
+							}),
+						)
+						.digest("hex")
+				: null;
+		if (attemptKey && emptyAutoCompactContextKey === attemptKey) return false;
 		let preSummaryStageActed = false;
 		// G1 from smoke pass 2: a short session generates all its pressure inside
 		// the protection window, the non-destructive layer finds nothing, and the
@@ -695,16 +793,14 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		// actually follows.
 		let evictionSkipNotice: string | null = null;
 		const rememberEmptyAutomaticAttempt = (): void => {
-			if (!force && !preSummaryStageActed && activeAutoTurnId) emptyAutoCompactTurnId = activeAutoTurnId;
+			if (!force && !preSummaryStageActed && attemptKey) emptyAutoCompactContextKey = attemptKey;
 		};
 
-		const compactionThreshold = cfg?.threshold ?? DEFAULT_COMPACTION_THRESHOLD;
 		const trigger: CompactionTrigger = triggerOverride ?? (force ? "force" : "auto");
 
-		if (!force) {
-			const estimate = liveContextEstimate(agentRuntime, pendingUserText);
+		if (pressureEstimate) {
+			const estimate = pressureEstimate;
 			const verdict = shouldCompact(estimate.tokens, compactionThreshold, estimate.contextWindow);
-			if (!verdict.shouldCompact) return false;
 
 			// One-release compatibility escape hatch. This is the destructive
 			// pre-stage that working-set eviction replaces; keep it byte-for-byte
@@ -808,6 +904,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 						middleware.fireCompactionHook("working_set_evict", "pressure", estimate.tokens);
 						emitCompactionActivity("started", "compacting context (working-set eviction)");
 						try {
+							const historyTokens = reconciledHistoryTokens(agentRuntime);
 							deps.session.appendEntry({
 								...buildEvictionFields(planned, {
 									trigger: "pressure",
@@ -820,7 +917,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 							});
 							noteColdReason("working_set_evict");
 							refreshAgentMessagesFromSession(agentRuntime);
-							carryReconciledAnchorThroughProjection(agentRuntime, planned.tokensBefore - planned.tokensAfter);
+							carryReconciledAnchorThroughProjection(agentRuntime, historyTokens, planned.tokensBefore - planned.tokensAfter);
 
 							const postEvictionSnapshot = captureRuntimeContextSnapshot(
 								agentRuntime,
@@ -898,13 +995,69 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		// useful ahead of it.
 		if (evictionSkipNotice) deps.emitNotice(evictionSkipNotice);
 		let result: CompactResult | null = null;
-		const beforeSnapshotId = currentContextSnapshot?.snapshotId ?? null;
+		// Compare full runtime estimates on both sides. The current snapshot and
+		// result.tokensBefore may instead carry provider-calibrated history usage.
+		const snapshotMetadata =
+			currentContextSnapshot && currentContextSnapshot.systemPrompt === agentRuntime.agent.state.systemPrompt
+				? { promptSegments: currentContextSnapshot.promptSegments, promptHash: currentContextSnapshot.promptHash }
+				: {};
+		const preCompactSnapshot = captureRuntimeContextSnapshot(
+			agentRuntime,
+			state.activeUserTurnId || "compaction",
+			compactionThreshold,
+			snapshotMetadata,
+		);
+		let budget:
+			| Pick<CompactInput, "keepRecentTokens" | "preserveUserTurnId" | "skillContextState" | "signal">
+			| undefined = skillContextState !== undefined ? { skillContextState } : undefined;
+		if (useRequestBudget) {
+			const estimate = liveContextEstimate(agentRuntime, pendingUserText);
+			const output = Math.min(
+				resolveReservedOutputTokens(agentRuntime.agent.state.model?.maxTokens, {
+					api: agentRuntime.agent.state.model?.api ?? "",
+					contextWindow: estimate.contextWindow,
+					inputTokens: estimate.tokens,
+				}),
+				settings.chat.maxOutputTokens > 0 ? settings.chat.maxOutputTokens : Number.POSITIVE_INFINITY,
+			);
+			const inputTarget = Math.min(estimate.contextWindow * compactionThreshold, estimate.contextWindow - output);
+			const staticTokens = estimate.breakdown.systemPromptTokens + estimate.breakdown.toolSchemaTokens;
+			const calibration = Math.max(
+				0,
+				estimate.tokens - staticTokens - estimate.breakdown.messageTokens - estimate.breakdown.pendingUserTokens,
+			);
+			// Split available history space between the recent suffix and the
+			// checkpoint (including verbatim active instructions). The cut remains
+			// structural, so the unchanged continuation guard verifies the result.
+			const historyBudget = inputTarget - staticTokens - estimate.breakdown.pendingUserTokens - calibration;
+			budget = {
+				...budget,
+				keepRecentTokens: Math.min(DEFAULT_KEEP_RECENT_TOKENS, Math.max(1, Math.floor(historyBudget / 2))),
+				...(activeAutoTurnId ? { preserveUserTurnId: activeAutoTurnId } : {}),
+			};
+		}
+		let summarySignal = compactionController?.signal;
 		try {
-			result = await compactionTrigger.fire(() => (deps.autoCompact ?? (async () => null))(instructions, trigger));
+			result = await compactionTrigger.fire(async () => {
+				const controller = new AbortController();
+				compactionController = controller;
+				summarySignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+				try {
+					return (
+						(await deps.autoCompact?.(instructions, trigger, {
+							...budget,
+							signal: summarySignal,
+						})) ?? null
+					);
+				} finally {
+					if (compactionController === controller) compactionController = null;
+				}
+			});
 		} catch (error) {
 			if (!summaryLifecycleStarted) startSummaryLifecycle();
 			emitCompactionActivity("failed", compactionFailureMessage(error));
 			deps.bus?.emit(BusChannels.CompactionEnd, { trigger, at: Date.now() });
+			summarySignal?.throwIfAborted();
 			throw error;
 		}
 		if (!result || result.summary.length === 0) {
@@ -934,33 +1087,36 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			agentRuntime,
 			state.activeUserTurnId || "compaction",
 			compactionThreshold,
+			snapshotMetadata,
 		);
 		currentContextSnapshot = postCompactSnapshot;
+		persistContextSnapshot(preCompactSnapshot);
 		persistContextSnapshot(postCompactSnapshot);
 
+		const tokensBefore = snapshotInputTokens(preCompactSnapshot);
 		const tokensAfter = snapshotInputTokens(postCompactSnapshot);
 		lastCompactionEvent = {
 			stage: "llm_summary",
-			tokensBefore: result.tokensBefore,
+			tokensBefore,
 			tokensAfter,
 			trigger,
 		};
 		deps.bus?.emit(BusChannels.ContextPruned, {
 			stage: "llm_summary",
-			tokensBefore: result.tokensBefore,
+			tokensBefore,
 			tokensAfter,
 			trigger,
-			snapshotIdBefore: beforeSnapshotId,
+			snapshotIdBefore: preCompactSnapshot.snapshotId,
 			snapshotIdAfter: postCompactSnapshot.snapshotId,
 			at: Date.now(),
 		} satisfies ContextPrunedPayload);
-		emitCompactionActivity("completed", `compacted ~${result.tokensBefore} -> ~${tokensAfter} tokens`);
+		emitCompactionActivity("completed", `compacted ~${tokensBefore} -> ~${tokensAfter} tokens`);
 
 		deps.emitNotice(
 			renderCompactionSummaryLine({
 				messagesSummarized: result.messagesSummarized,
 				summaryChars: result.summary.length,
-				tokensBefore: result.tokensBefore,
+				tokensBefore,
 				isSplitTurn: result.isSplitTurn,
 			}),
 		);
@@ -990,6 +1146,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		rememberedLoadedContextWindow,
 		refreshAgentMessagesFromSession,
 		runAutoCompact,
+		cancelCompaction: () => compactionController?.abort(),
 
 		setCurrentSnapshot(snapshot: ContextSnapshot): void {
 			currentContextSnapshot = snapshot;
@@ -1004,13 +1161,22 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			// Cached prompt tokens still occupy the window; providers report them
 			// outside `input`, so the attested prompt is the three summed.
 			const promptTokens = (usage.input || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
-			const messages = state.runtime?.agent.state.messages;
-			if (promptTokens > 0 && messages) {
+			const runtime = state.runtime;
+			if (promptTokens > 0 && runtime) {
+				const breakdown = estimateAgentContextBreakdown({ ...runtime.agent.state, messages: [] });
 				// The output of this call is part of the next call's prompt for the
 				// same messages, which is why it is folded in here.
 				reconciledAnchor = {
 					tokens: promptTokens + (usage.output || 0),
-					anchoredMessageCount: messages.length,
+					anchoredMessages: [...runtime.agent.state.messages],
+					runtime,
+					model: runtime.agent.state.model,
+					modelKey: anchorModelKey(runtime),
+					targetId: runtime.targetId,
+					runtimeId: runtime.runtimeId,
+					wireModelId: runtime.wireModelId,
+					systemPromptTokens: breakdown.systemPromptTokens,
+					toolSchemaTokens: breakdown.toolSchemaTokens,
 				};
 			}
 			if (!currentContextSnapshot) return;
@@ -1199,7 +1365,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			let compacted = false;
 			if (verdict.shouldCompact) {
 				try {
-					compacted = await runAutoCompact(agentRuntime, false, undefined, "auto");
+					compacted = await runAutoCompact(agentRuntime, false, undefined, "auto", undefined, undefined, signal);
 				} catch (err) {
 					throw new Error(
 						`[Clio Coder] post-tool context guard could not compact before continuation: ${err instanceof Error ? err.message : String(err)}`,
@@ -1379,6 +1545,7 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		},
 
 		resetForSession(): void {
+			compactionController?.abort();
 			// An in-process switch replaces the whole prefix: the backend's slot
 			// still holds the outgoing session's prompt and history, so the first
 			// turn on the incoming one is expected-cold on every tier, exactly as
@@ -1397,13 +1564,14 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			resumedPromptHash = null;
 			sessionWorkingContextPaths.clear();
 			pendingPromptLogEntry = null;
-			emptyAutoCompactTurnId = null;
+			emptyAutoCompactContextKey = null;
 			reconciledAnchor = null;
 			const session = deps.session?.current();
 			currentContextSnapshot = session ? getLatestContextSnapshot(session) : null;
 		},
 
 		dispose(): void {
+			compactionController?.abort();
 			for (const unsubscribe of unsubscribeColdReasonSources) unsubscribe?.();
 		},
 	};

package/src/interactive/turn-middleware.ts

@@ -268,7 +268,9 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 
 		flushPendingReminders(): string {
 			if (pendingReminders.length === 0) return "";
-			const messages = pendingReminders.map((entry) => entry.message);
+			// Severity affects host actions, not the text delivered to the model.
+			// A paired continuation/info and reminder/warn still needs one copy.
+			const messages = [...new Set(pendingReminders.map((entry) => entry.message))];
 			pendingReminders.length = 0;
 			return `<system-reminder>\n${messages.join("\n\n")}\n</system-reminder>`;
 		},

package/src/interactive/turn-persistence.ts

@@ -17,6 +17,7 @@ import {
 	type AssistantCallTiming,
 	assistantSessionPayload,
 	estimatedUsageForInterruptedTurn,
+	explainInterruptedAssistant,
 	extractUserText,
 	hasPersistableAssistantContent,
 	hasStructuredToolCall,
@@ -220,10 +221,12 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 
 	const appendAssistantTurn = (message: AgentMessage, timing?: AssistantCallTiming | null): void => {
 		if (message?.role !== "assistant") return;
+		if (persistedAssistantMessages.has(message)) return;
 		// A loop-guard interrupt already persisted a durable closing turn with the
 		// stop reason; drop the empty aborted message the abort leaves behind so
 		// the operator does not see a hollow "request aborted" turn after it.
 		if (state.activeInterruptReason !== null && isEmptyAbortedAssistantMessage(message)) return;
+		if (explainInterruptedAssistant(message, state.activeInterruptReason)) state.interruptedAssistantMessage = message;
 		const failure = terminalFailureFromAssistantMessage(message);
 		const payload = assistantSessionPayload(message, failure);
 		if (timing) payload.timing = timing;

package/src/interactive/turn-runtime.ts

@@ -32,7 +32,7 @@ import {
 	patchToolChoiceNonePayload,
 } from "../engine/provider-payload.js";
 import type { AgentEvent, AgentMessage, EngineModel, Usage } from "../engine/types.js";
-import type { resolveAgentTools, ToolOutcome, ToolTelemetry } from "../tools/agent-tools.js";
+import type { resolveAgentTools, ToolFinishEvent, ToolTelemetry } from "../tools/agent-tools.js";
 import {
 	type AssistantCallTiming,
 	type BackendCacheVerdict,
@@ -162,7 +162,10 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 	 * a call whose end event never arrives leaves at most one stale entry, which
 	 * the next run with the same id would overwrite.
 	 */
-	const toolOutcomes = new Map<string, { outcome: ToolOutcome; reason?: string; durationMs: number }>();
+	const toolOutcomes = new Map<
+		string,
+		Pick<ToolFinishEvent, "outcome" | "reason" | "durationMs" | "ruleId" | "reasonCode" | "policySource">
+	>();
 	const toolTelemetry: ToolTelemetry = {
 		onFinish(event) {
 			if (event.toolCallId === undefined) return;
@@ -170,6 +173,9 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 				outcome: event.outcome,
 				...(event.reason === undefined ? {} : { reason: event.reason }),
 				durationMs: event.durationMs,
+				...(event.ruleId === undefined ? {} : { ruleId: event.ruleId }),
+				...(event.reasonCode === undefined ? {} : { reasonCode: event.reasonCode }),
+				...(event.policySource === undefined ? {} : { policySource: event.policySource }),
 			});
 		},
 	};
@@ -651,6 +657,9 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 						? {}
 						: {
 								outcome: admission.outcome,
+								...(admission.ruleId === undefined ? {} : { ruleId: admission.ruleId }),
+								...(admission.reasonCode === undefined ? {} : { reasonCode: admission.reasonCode }),
+								...(admission.policySource === undefined ? {} : { policySource: admission.policySource }),
 								...(admission.reason === undefined ? {} : { blockReason: admission.reason }),
 							}),
 				} as typeof event;

package/src/interactive/turn-state.ts

@@ -88,19 +88,19 @@ export interface ChatTurnState {
 	/** The user turn id of the in-flight submit; null between turns. */
 	activeUserTurnId: string | null;
 	/**
-	 * Set by a loop-guard interrupt (cancel with a reason). While set, the empty
-	 * aborted assistant messages the abort produces are suppressed in both the
-	 * ledger and the live transcript; the durable closing turn carrying the
-	 * reason is persisted when the run settles (submit's finally), after the
-	 * in-flight tool results have landed. Cleared there, and defensively at the
-	 * start of each submit.
+	 * Set by an operator or explained interrupt. A nonempty aborted assistant
+	 * carries this reason; hollow abort messages are suppressed and replaced
+	 * by one durable closing turn after in-flight tool results have landed.
+	 * Cleared at settlement and defensively at the start of each submit.
 	 */
 	activeInterruptReason: string | null;
+	/** The provider's nonempty aborted message closes this interrupt without a synthetic second assistant. */
+	interruptedAssistantMessage: AgentMessage | null;
 	/**
 	 * Estimated spend of the cancelled call whose hollow aborted message the
-	 * interrupt suppressed (thinking streamed, no text). The message never reaches
-	 * the ledger, so the closing turn persisted in submit's finally carries this
-	 * instead of an estimate derived from its own notice text. Cleared with
+	 * interrupt suppressed. The message never reaches the ledger, so the closing
+	 * turn persisted in submit's finally carries this instead of an estimate
+	 * derived from its own notice text. Cleared with
 	 * `activeInterruptReason`.
 	 */
 	interruptedUsage: Record<string, unknown> | null;
@@ -148,6 +148,7 @@ export function createTurnState(initialThinkingLevel: ThinkingLevel): ChatTurnSt
 		replayedContextMessages: [],
 		activeUserTurnId: null,
 		activeInterruptReason: null,
+		interruptedAssistantMessage: null,
 		interruptedUsage: null,
 		synthesisToolLock: false,
 		toolProseAbortReason: null,

package/src/interactive/watch-pane.ts

@@ -21,7 +21,7 @@
 import { mkdirSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { type ClioDirs, clioCacheDir, clioConfigDir, clioDataDir, clioStateDir } from "../core/xdg.js";
-import type { MuxContract, MuxPaneRef } from "../domains/mux/index.js";
+import type { MuxContract, MuxPaneOpenFailure, MuxPaneRef } from "../domains/mux/index.js";
 import type { PanesWatchController, PanesWatchResult } from "../domains/mux/operations.js";
 import { watchViewerCommand } from "../domains/mux/viewer-command.js";
 
@@ -115,8 +115,9 @@ export function createWatchPaneController(deps: WatchPaneDeps): PanesWatchContro
 	 * of Clio's pane at the configured share. On a host without the layout tier
 	 * the dock request degrades inside the contract to a plain right split.
 	 */
-	const openPane = (): Promise<MuxPaneRef | null> =>
+	const openPane = (onFailure?: (failure: MuxPaneOpenFailure) => void): Promise<MuxPaneRef | null> =>
 		deps.mux.openUtilityPane({
+			...(onFailure ? { onFailure } : {}),
 			argv: command(selectionPath, dirs),
 			cwd: deps.getCwd(),
 			label: "watch",
@@ -152,9 +153,22 @@ export function createWatchPaneController(deps: WatchPaneDeps): PanesWatchContro
 			const scanned = await adoptExistingPane();
 			if (!scanned) await adoptExistingPane();
 			if (paneId !== null) return { status: "watching", runId, paneId, opened: false };
-			const opened = await openPane();
+			let reason =
+				"cannot open the watch pane: no failure reason was supplied by the pane host; check /panes before trying again";
+			const opened = await openPane((failure) => {
+				if (failure.source === "local") {
+					reason = `cannot open the watch pane locally: ${failure.message}`;
+				} else {
+					const details = [
+						`kind=${failure.kind}`,
+						...(failure.wireCode === null ? [] : [`code=${failure.wireCode}`]),
+						...(failure.method === null ? [] : [`method=${failure.method}`]),
+					];
+					reason = `cannot open the watch pane (${details.join(", ")}): ${failure.message || "no failure message was supplied by the pane host"}`;
+				}
+			});
 			if (opened === null) {
-				return { status: "unavailable", reason: "the pane host refused to open the watch pane" };
+				return { status: "unavailable", reason };
 			}
 			paneId = opened.paneId;
 			return { status: "watching", runId, paneId, opened: true };