@sayknow-cli/agent-core 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-07-06
+### Added
+
+- Agent queues now expose ordered move helpers for steering and follow-up messages so callers can reorder pending work without removing and re-adding messages.
+
+### Fixed
+
+- Preserved inherited fork-context seed messages when a compacted child rebase receives only child-local normalized messages, avoiding seed loss after task-child compaction (#1567).
+
 ## [0.7.7] - 2026-06-28
 
 ### Fixed

package/dist/types/agent.d.ts

@@ -349,11 +349,15 @@ export declare class Agent {
      * Used by dequeue keybinding.
      */
     popLastSteer(): AgentMessage | undefined;
+    removeSteerAt(index: number): AgentMessage | undefined;
+    moveSteer(fromIndex: number, toIndex: number): boolean;
     /**
      * Remove and return the last follow-up message from the queue (LIFO).
      * Used by dequeue keybinding.
      */
     popLastFollowUp(): AgentMessage | undefined;
+    removeFollowUpAt(index: number): AgentMessage | undefined;
+    moveFollowUp(fromIndex: number, toIndex: number): boolean;
     /** Remove queued steering+follow-up messages matching `predicate`, preserving order of the rest. */
     removeQueuedMessages(predicate: (message: AgentMessage) => boolean): {
         steering: number;

package/dist/types/append-only-context.d.ts

@@ -92,10 +92,23 @@ export declare class AppendOnlyLog {
  * ctx = mgr.build(context);        // subsequent calls use cache
  * ```
  */
+export interface AppendOnlyContextManagerOptions {
+    /**
+     * Invoked whenever the stable prefix fingerprint changes on `build()` (a
+     * provider prompt-cache prefix reset). Used for per-session diagnostics; must
+     * not throw. `from` is `<unbuilt>` on the first build.
+     */
+    readonly onPrefixChange?: (info: {
+        from: string;
+        to: string;
+        version: number;
+    }) => void;
+}
 export declare class AppendOnlyContextManager {
     #private;
     readonly prefix: StablePrefix;
     readonly log: AppendOnlyLog;
+    constructor(options?: AppendOnlyContextManagerOptions);
     static forkFromSeed(args: {
         prefixSnapshot?: StablePrefixSnapshot;
         messages?: readonly Message[];

package/dist/types/compaction/compaction.d.ts

@@ -98,6 +98,11 @@ export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLim
  */
 export declare function emergencyCompactionReason(sample: EmergencyCompactionSample, limits?: EmergencyCompactionLimits): CompactionTriggerReason | null;
 export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): number;
+/**
+ * Image content has no tokenizer representation; charge a fixed estimate
+ * matching what providers typically bill for inline images.
+ */
+export declare const IMAGE_TOKEN_ESTIMATE = 1200;
 /**
  * Native-free chars/4 token estimate for a message. This is the only message
  * token estimator: provider usage (see {@link calculatePromptTokens}) anchors
@@ -176,6 +181,25 @@ export interface SummaryOptions {
     /** Hint that websocket transport should be preferred when supported by the provider implementation. */
     preferWebsockets?: boolean;
 }
+/**
+ * Cap the serialized conversation fed to a summarization request so the request
+ * itself fits inside the model's context window.
+ *
+ * Without this, summarizing a near-full context serializes (nearly) the entire
+ * history back into a single summary request; on strict backends (e.g.
+ * OpenAI-code/Codex `context_length_exceeded`) that request itself overflows and
+ * throws, so context-overflow recovery cannot produce a summary and the agent
+ * fails to compact-and-continue — a non-interactive `skc -p` run then terminates
+ * on the very overflow the recovery was meant to absorb.
+ *
+ * The budget reserves the summary's own output tokens plus prompt/system/template
+ * overhead, and applies a conservative safety factor because the chars/4 heuristic
+ * undercounts dense or CJK text (the reason the original overflow was missed).
+ * Truncation keeps the head (origin/goals) and the tail (most recent state) and
+ * elides the middle; it is a last resort that only triggers when the input would
+ * otherwise not fit.
+ */
+export declare function boundConversationTextForSummary(conversationText: string, model: Model, outputMaxTokens: number): string;
 export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
 export interface HandoffOptions {
     /** Live agent system prompt — passed verbatim so providers hit the cached prefix. */
@@ -224,8 +248,32 @@ export interface CompactionPreparation {
     fileOps: FileOperations;
     /** Compaction settions from settings.jsonl	*/
     settings: CompactionSettings;
+    /**
+     * Diagnostics for the keep-window token correction (Finding 7). `ratio` is the
+     * clamped heuristic→actual correction that was applied (1 when none supplied);
+     * `keepRecentTokensCorrected` is the heuristic budget findCutPoint actually used.
+     */
+    tokenCorrection: {
+        ratio: number;
+        keepRecentTokensCorrected: number;
+    };
+}
+/** Bounds for the keep-window token correction (Finding 7): never trust a ratio
+ * beyond 2x in either direction so a bad estimate cannot balloon or collapse the
+ * kept window. */
+export declare const TOKEN_CORRECTION_MIN_RATIO = 0.5;
+export declare const TOKEN_CORRECTION_MAX_RATIO = 2;
+export interface PrepareCompactionOptions {
+    /**
+     * Observed heuristic→actual token correction for the post-boundary keep window
+     * (actualTokens / chars-4-heuristicTokens), supplied by the caller from per-turn
+     * Usage deltas or a stable-prefix-subtracted comparison. Clamped to
+     * [0.5, 2] and applied bidirectionally. When omitted, no correction is applied
+     * (the confounded raw promptTokens/estimatedTokens quotient is never used).
+     */
+    tokenCorrectionRatio?: number;
 }
-export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings, options?: PrepareCompactionOptions): CompactionPreparation | undefined;
 /**
  * Generate summaries for compaction using prepared data.
  * Returns CompactionResult - SessionManager adds id/parentId when saving.

package/dist/types/compaction/pruning.d.ts

@@ -44,4 +44,26 @@ export interface AssistantArgumentPruneResult {
     prunedEntries: SessionMessageEntry[];
 }
 export declare function pruneAssistantToolArguments(entries: SessionEntry[], config?: PruneConfig): AssistantArgumentPruneResult;
+/**
+ * Estimate the token savings {@link pruneToolOutputs} would achieve, without
+ * mutating any entry. Returns 0 savings when below the configured minimum so the
+ * caller sees the same gate the real prune enforces.
+ */
+export declare function estimateToolOutputPruneSavings(entries: SessionEntry[], config?: PruneConfig): {
+    prunableCount: number;
+    tokensSaved: number;
+};
+/**
+ * Evidence gate for below-threshold maintenance pruning (Finding 13). Pruning
+ * forces a prompt-cache-epoch reset, so it only runs when opted in AND the
+ * estimated stale savings clear a high minimum AND exceed the one-time reset
+ * cost (so the reclaim pays the reset back). Default-off/blocked until live
+ * evidence justifies enabling.
+ */
+export declare function shouldRunMaintenancePrune(args: {
+    enabled: boolean;
+    estimatedSavings: number;
+    minSavings: number;
+    cacheEpochResetCost: number;
+}): boolean;
 export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;

package/package.json

@@ -1,9 +1,9 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/agent-core",
-	"version": "0.3.7",
+	"version": "0.3.9",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
-	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
+	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
 	"contributors": [
 		"Mario Zechner"
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/ai": "0.3.7",
-		"@sayknow-cli/natives": "0.3.7",
-		"@sayknow-cli/utils": "0.3.7",
+		"@sayknow-cli/ai": "0.3.9",
+		"@sayknow-cli/natives": "0.3.9",
+		"@sayknow-cli/utils": "0.3.9",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -342,9 +342,136 @@ export function normalizeMessagesForProvider(
 	return changed ? normalized : messages;
 }
 
+interface ConvertedContextCacheEntry {
+	messageHashes: string[];
+	modelKey: string;
+	toolKey: string;
+	intentTracing: boolean;
+	convertToLlm: AgentLoopConfig["convertToLlm"];
+	transformContext: AgentLoopConfig["transformContext"];
+	llmMessages: Context["messages"];
+	normalizedMessages: Context["messages"];
+}
+
+const convertedContextCache = new WeakMap<AgentLoopConfig, ConvertedContextCacheEntry>();
+
+function stableCacheString(value: unknown): string | undefined {
+	try {
+		return JSON.stringify(value, (_key, item) =>
+			typeof item === "function" ? `[Function:${item.name || "anonymous"}]` : item,
+		);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Hash a message by full content serialization.
+ *
+ * Deliberately NOT memoized by object identity: callers mutate messages in
+ * place (compaction rewrites, obfuscation, abort markers) and the cache's
+ * correctness contract requires detecting those mutations. The per-turn
+ * serialization cost is the price of that contract; the win is skipping
+ * convertToLlm + normalize on stable contexts, which dominates for
+ * image-heavy histories.
+ */
+function hashMessageContent(message: AgentMessage): string | undefined {
+	return stableCacheString(message);
+}
+
+function buildConvertedContextCacheKeys(
+	messages: AgentMessage[],
+	context: AgentContext,
+	config: AgentLoopConfig,
+): Pick<ConvertedContextCacheEntry, "messageHashes" | "modelKey" | "toolKey" | "intentTracing"> | undefined {
+	const intentTracing = !!config.intentTracing;
+	const messageHashes = messages.map(hashMessageContent);
+	const modelKey = stableCacheString(config.model);
+	const toolKey = stableCacheString(normalizeTools(context.tools, intentTracing) ?? []);
+	if (messageHashes.some(hash => hash === undefined) || modelKey === undefined || toolKey === undefined) {
+		return undefined;
+	}
+	return {
+		messageHashes: messageHashes as string[],
+		modelKey,
+		toolKey,
+		intentTracing,
+	};
+}
+
+function findStablePrefixLength(previous: string[], next: string[]): number {
+	const max = Math.min(previous.length, next.length);
+	let index = 0;
+	while (index < max && previous[index] === next[index]) index++;
+	return index;
+}
+
+async function convertAndNormalizeMessages(
+	messages: AgentMessage[],
+	context: AgentContext,
+	config: AgentLoopConfig,
+): Promise<Context["messages"]> {
+	const keys = buildConvertedContextCacheKeys(messages, context, config);
+	if (!keys) {
+		return normalizeMessagesForProvider(await config.convertToLlm(messages), config.model);
+	}
+	const previous = convertedContextCache.get(config);
+	const canReuse =
+		previous &&
+		previous.convertToLlm === config.convertToLlm &&
+		previous.transformContext === config.transformContext &&
+		previous.modelKey === keys.modelKey &&
+		previous.toolKey === keys.toolKey &&
+		previous.intentTracing === keys.intentTracing;
+
+	if (canReuse) {
+		const stablePrefixLength = findStablePrefixLength(previous.messageHashes, keys.messageHashes);
+		if (stablePrefixLength === keys.messageHashes.length && stablePrefixLength === previous.messageHashes.length) {
+			return previous.normalizedMessages;
+		}
+		// Append-only fast path: convert only the new suffix and concatenate.
+		// CONTRACT: `convertToLlm` must be per-message (each output message
+		// derived solely from its input message). The bundled converters
+		// satisfy this — they map/filter message-by-message. A converter that
+		// merges adjacent messages or pairs across the suffix boundary would
+		// diverge from a full rebuild; such converters must not be combined
+		// with appendOnlyContext. Covered by the suffix-equivalence test in
+		// agent-loop-context-cache.test.ts.
+		if (
+			config.appendOnlyContext &&
+			stablePrefixLength === previous.messageHashes.length &&
+			keys.messageHashes.length > previous.messageHashes.length
+		) {
+			const suffix = messages.slice(stablePrefixLength);
+			const convertedSuffix = await config.convertToLlm(suffix);
+			const llmMessages = [...previous.llmMessages, ...convertedSuffix];
+			const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
+			convertedContextCache.set(config, {
+				...keys,
+				convertToLlm: config.convertToLlm,
+				transformContext: config.transformContext,
+				llmMessages,
+				normalizedMessages,
+			});
+			return normalizedMessages;
+		}
+	}
+
+	const llmMessages = await config.convertToLlm(messages);
+	const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
+	convertedContextCache.set(config, {
+		...keys,
+		convertToLlm: config.convertToLlm,
+		transformContext: config.transformContext,
+		llmMessages,
+		normalizedMessages,
+	});
+	return normalizedMessages;
+}
+
 export const INTENT_FIELD = "_i";
 
-function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" = "require"): unknown {
+function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" = "optional"): unknown {
 	if (!schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
 	const schemaRecord = schema as Record<string, unknown>;
 	const propertiesValue = schemaRecord.properties;
@@ -400,7 +527,7 @@ export function normalizeTools(tools: AgentContext["tools"], injectIntent: boole
 function resolveIntentMode(intent: AgentTool["intent"]): "require" | "optional" | "omit" {
 	if (typeof intent === "function") return "omit";
 	if (intent === "optional" || intent === "omit") return intent;
-	return "require";
+	return intent === "require" ? "require" : "optional";
 }
 
 function extractIntent(args: Record<string, unknown>): { intent?: string; strippedArgs: Record<string, unknown> } {
@@ -711,9 +838,9 @@ async function streamAssistantResponse(
 		messages = await config.transformContext(messages, signal);
 	}
 
-	// Convert to LLM-compatible messages (AgentMessage[] → Message[])
-	const llmMessages = await config.convertToLlm(messages);
-	const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
+	// Convert to LLM-compatible messages (AgentMessage[] → Message[]) and normalize at the LLM boundary.
+	// Cache hits are keyed by provider-visible content hashes, never message object identity.
+	const normalizedMessages = await convertAndNormalizeMessages(messages, context, config);
 
 	// Build LLM context — append-only mode caches system prompt + tools
 	// AND keeps an append-only message log so prior-turn bytes are stable.

package/src/agent.ts

@@ -954,6 +954,15 @@ export class Agent {
 	popLastSteer(): AgentMessage | undefined {
 		return this.#steeringQueue.pop();
 	}
+	removeSteerAt(index: number): AgentMessage | undefined {
+		if (index < 0 || index >= this.#steeringQueue.length) return undefined;
+		const [removed] = this.#steeringQueue.splice(index, 1);
+		return removed;
+	}
+
+	moveSteer(fromIndex: number, toIndex: number): boolean {
+		return this.#moveQueuedMessage(this.#steeringQueue, fromIndex, toIndex);
+	}
 
 	/**
 	 * Remove and return the last follow-up message from the queue (LIFO).
@@ -962,6 +971,25 @@ export class Agent {
 	popLastFollowUp(): AgentMessage | undefined {
 		return this.#followUpQueue.pop();
 	}
+	removeFollowUpAt(index: number): AgentMessage | undefined {
+		if (index < 0 || index >= this.#followUpQueue.length) return undefined;
+		const [removed] = this.#followUpQueue.splice(index, 1);
+		return removed;
+	}
+
+	moveFollowUp(fromIndex: number, toIndex: number): boolean {
+		return this.#moveQueuedMessage(this.#followUpQueue, fromIndex, toIndex);
+	}
+
+	#moveQueuedMessage<T>(queue: T[], fromIndex: number, toIndex: number): boolean {
+		if (fromIndex < 0 || fromIndex >= queue.length) return false;
+		if (toIndex < 0 || toIndex >= queue.length) return false;
+		if (fromIndex === toIndex) return true;
+		const [item] = queue.splice(fromIndex, 1);
+		if (item === undefined) return false;
+		queue.splice(toIndex, 0, item);
+		return true;
+	}
 
 	/** Remove queued steering+follow-up messages matching `predicate`, preserving order of the rest. */
 	removeQueuedMessages(predicate: (message: AgentMessage) => boolean): {

package/src/append-only-context.ts

@@ -194,6 +194,15 @@ export class AppendOnlyLog {
  * ctx = mgr.build(context);        // subsequent calls use cache
  * ```
  */
+export interface AppendOnlyContextManagerOptions {
+	/**
+	 * Invoked whenever the stable prefix fingerprint changes on `build()` (a
+	 * provider prompt-cache prefix reset). Used for per-session diagnostics; must
+	 * not throw. `from` is `<unbuilt>` on the first build.
+	 */
+	readonly onPrefixChange?: (info: { from: string; to: string; version: number }) => void;
+}
+
 export class AppendOnlyContextManager {
 	readonly prefix = new StablePrefix();
 	readonly log = new AppendOnlyLog();
@@ -203,6 +212,11 @@ export class AppendOnlyContextManager {
 	#syncedHashes: (number | bigint)[] = [];
 	/** Number of provider-normalized messages that were seeded before child-local messages. */
 	#seededPrefixCount = 0;
+	readonly #onPrefixChange: AppendOnlyContextManagerOptions["onPrefixChange"];
+
+	constructor(options: AppendOnlyContextManagerOptions = {}) {
+		this.#onPrefixChange = options.onPrefixChange;
+	}
 
 	static forkFromSeed(args: {
 		prefixSnapshot?: StablePrefixSnapshot;
@@ -220,7 +234,15 @@ export class AppendOnlyContextManager {
 	}
 
 	build(context: AgentContext, options: BuildOptions): Context {
-		this.prefix.build(context, options);
+		const previousFingerprint = this.prefix.fingerprint;
+		const changed = this.prefix.build(context, options);
+		if (changed && this.#onPrefixChange) {
+			this.#onPrefixChange({
+				from: previousFingerprint,
+				to: this.prefix.fingerprint,
+				version: this.prefix.version,
+			});
+		}
 		const { systemPrompt, tools } = this.prefix.toContext();
 		return { systemPrompt, messages: this.log.toMessages(), tools };
 	}
@@ -252,7 +274,7 @@ export class AppendOnlyContextManager {
 			if (this.#seededPrefixCount > 0) {
 				// F9: a seeded fork whose inherited prefix changed (e.g. after compaction)
 				// rebases onto the new provider context instead of throwing.
-				this.#rebaseToBaseline(normalizedMessages);
+				this.#rebaseToBaseline(messagesToSync, seededPrefixLength);
 				return;
 			}
 			this.log.clear();
@@ -265,7 +287,7 @@ export class AppendOnlyContextManager {
 		// while a seed prefix is active; a genuine seeded compaction rebases (F9).
 		if (messagesToSync.length < this.#lastSyncCount) {
 			if (this.#seededPrefixCount > 0) {
-				this.#rebaseToBaseline(normalizedMessages);
+				this.#rebaseToBaseline(messagesToSync, seededPrefixLength);
 				return;
 			}
 			this.log.clear();
@@ -359,12 +381,12 @@ export class AppendOnlyContextManager {
 		return false;
 	}
 
-	/** F9: reset the seeded log to a new provider-visible baseline (seeded compaction/rebase). */
-	#rebaseToBaseline(messages: readonly unknown[]): void {
+	/** F9: reset the log to a new provider-visible baseline after seeded compaction/rebase. */
+	#rebaseToBaseline(messages: readonly unknown[], seededPrefixCount = 0): void {
 		this.log.clear();
 		this.log.extend([...messages]);
 		this.#lastSyncCount = messages.length;
-		this.#seededPrefixCount = 0;
+		this.#seededPrefixCount = seededPrefixCount;
 		this.#syncedHashes = this.#hashRange(messages, 0, messages.length);
 	}
 }

package/src/compaction/compaction.ts

@@ -315,7 +315,7 @@ export function resolveThresholdTokens(
  * Image content has no tokenizer representation; charge a fixed estimate
  * matching what providers typically bill for inline images.
  */
-const IMAGE_TOKEN_ESTIMATE = 1200;
+export const IMAGE_TOKEN_ESTIMATE = 1200;
 /**
  * Estimate tokens for collected message fragments using the native-free
  * heuristic. Provider usage is the authoritative anchor for context-changing
@@ -679,6 +679,49 @@ export interface SummaryOptions {
 	preferWebsockets?: boolean;
 }
 
+/**
+ * Cap the serialized conversation fed to a summarization request so the request
+ * itself fits inside the model's context window.
+ *
+ * Without this, summarizing a near-full context serializes (nearly) the entire
+ * history back into a single summary request; on strict backends (e.g.
+ * OpenAI-code/Codex `context_length_exceeded`) that request itself overflows and
+ * throws, so context-overflow recovery cannot produce a summary and the agent
+ * fails to compact-and-continue — a non-interactive `skc -p` run then terminates
+ * on the very overflow the recovery was meant to absorb.
+ *
+ * The budget reserves the summary's own output tokens plus prompt/system/template
+ * overhead, and applies a conservative safety factor because the chars/4 heuristic
+ * undercounts dense or CJK text (the reason the original overflow was missed).
+ * Truncation keeps the head (origin/goals) and the tail (most recent state) and
+ * elides the middle; it is a last resort that only triggers when the input would
+ * otherwise not fit.
+ */
+export function boundConversationTextForSummary(
+	conversationText: string,
+	model: Model,
+	outputMaxTokens: number,
+): string {
+	const contextWindow = model.contextWindow;
+	if (!Number.isFinite(contextWindow) || contextWindow <= 0) return conversationText;
+
+	const OVERHEAD_TOKENS = 4096;
+	const SAFETY_FACTOR = 0.6;
+	const inputBudgetTokens = Math.floor(
+		(contextWindow - Math.max(0, outputMaxTokens) - OVERHEAD_TOKENS) * SAFETY_FACTOR,
+	);
+	if (inputBudgetTokens <= 0) return conversationText;
+	if (estimateTextTokensHeuristic(conversationText) <= inputBudgetTokens) return conversationText;
+
+	const budgetChars = inputBudgetTokens * HEURISTIC_BYTES_PER_TOKEN;
+	const headChars = Math.floor(budgetChars * 0.35);
+	const tailChars = Math.max(0, budgetChars - headChars);
+	const head = conversationText.slice(0, headChars);
+	const tail = tailChars > 0 ? conversationText.slice(conversationText.length - tailChars) : "";
+	const elided = conversationText.length - head.length - tail.length;
+	return `${head}\n\n[... ${elided} characters of older conversation elided so this summarization request fits within the model context window ...]\n\n${tail}`;
+}
+
 export async function generateSummary(
 	currentMessages: AgentMessage[],
 	model: Model,
@@ -703,7 +746,7 @@ export async function generateSummary(
 	// Serialize conversation to text so model doesn't try to continue it
 	// Convert to LLM messages first (handles custom app messages when caller provides a transformer).
 	const llmMessages = (options?.convertToLlm ?? convertToLlm)(currentMessages);
-	const conversationText = serializeConversation(llmMessages);
+	const conversationText = boundConversationTextForSummary(serializeConversation(llmMessages), model, maxTokens);
 
 	// Build the prompt with conversation wrapped in tags
 	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
@@ -859,7 +902,7 @@ async function generateShortSummary(
 ): Promise<string> {
 	const maxTokens = Math.min(512, Math.floor(0.2 * reserveTokens));
 	const llmMessages = (options?.convertToLlm ?? convertToLlm)(recentMessages);
-	const conversationText = serializeConversation(llmMessages);
+	const conversationText = boundConversationTextForSummary(serializeConversation(llmMessages), model, maxTokens);
 
 	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
 	if (historySummary) {
@@ -934,11 +977,35 @@ export interface CompactionPreparation {
 	fileOps: FileOperations;
 	/** Compaction settions from settings.jsonl	*/
 	settings: CompactionSettings;
+	/**
+	 * Diagnostics for the keep-window token correction (Finding 7). `ratio` is the
+	 * clamped heuristic→actual correction that was applied (1 when none supplied);
+	 * `keepRecentTokensCorrected` is the heuristic budget findCutPoint actually used.
+	 */
+	tokenCorrection: { ratio: number; keepRecentTokensCorrected: number };
+}
+
+/** Bounds for the keep-window token correction (Finding 7): never trust a ratio
+ * beyond 2x in either direction so a bad estimate cannot balloon or collapse the
+ * kept window. */
+export const TOKEN_CORRECTION_MIN_RATIO = 0.5;
+export const TOKEN_CORRECTION_MAX_RATIO = 2;
+
+export interface PrepareCompactionOptions {
+	/**
+	 * Observed heuristic→actual token correction for the post-boundary keep window
+	 * (actualTokens / chars-4-heuristicTokens), supplied by the caller from per-turn
+	 * Usage deltas or a stable-prefix-subtracted comparison. Clamped to
+	 * [0.5, 2] and applied bidirectionally. When omitted, no correction is applied
+	 * (the confounded raw promptTokens/estimatedTokens quotient is never used).
+	 */
+	tokenCorrectionRatio?: number;
 }
 
 export function prepareCompaction(
 	pathEntries: SessionEntry[],
 	settings: CompactionSettings,
+	options: PrepareCompactionOptions = {},
 ): CompactionPreparation | undefined {
 	if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
 		return undefined;
@@ -956,17 +1023,22 @@ export function prepareCompaction(
 
 	const lastUsage = getLastAssistantUsage(pathEntries);
 	const tokensBefore = lastUsage ? calculateContextTokens(lastUsage) : 0;
-	let keepRecentTokens = settings.keepRecentTokens;
-	if (lastUsage) {
-		const estimatedTokens = estimateEntriesTokens(pathEntries, boundaryStart, boundaryEnd);
-		const promptTokens = calculatePromptTokens(lastUsage);
-		const ratio = estimatedTokens > 0 ? promptTokens / estimatedTokens : 0;
-		if (Number.isFinite(ratio) && ratio > 1) {
-			keepRecentTokens = Math.max(1, Math.floor(keepRecentTokens / ratio));
-		}
-	}
 
-	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, keepRecentTokens);
+	// Correct the keep-window budget for the chars/4 heuristic error using the
+	// caller-supplied observed ratio (actual/heuristic). The legacy raw
+	// promptTokens/estimatedTokens quotient is intentionally NOT used: promptTokens
+	// counts system+tools+full history while estimatedTokens counted only the
+	// post-boundary slice, so it was confounded and only ever shrank the window.
+	// Here the correction is bidirectional and clamped to [0.5, 2].
+	const keepRecentTokens = settings.keepRecentTokens;
+	const rawRatio = options.tokenCorrectionRatio;
+	const appliedRatio =
+		rawRatio !== undefined && Number.isFinite(rawRatio) && rawRatio > 0
+			? Math.min(TOKEN_CORRECTION_MAX_RATIO, Math.max(TOKEN_CORRECTION_MIN_RATIO, rawRatio))
+			: 1;
+	const keepRecentTokensCorrected = Math.max(1, Math.round(keepRecentTokens / appliedRatio));
+
+	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, keepRecentTokensCorrected);
 
 	// Get ID of first kept entry
 	const firstKeptEntry = pathEntries[cutPoint.firstKeptEntryIndex];
@@ -1034,6 +1106,7 @@ export function prepareCompaction(
 		previousPreserveData,
 		fileOps,
 		settings,
+		tokenCorrection: { ratio: appliedRatio, keepRecentTokensCorrected },
 	};
 }
 
@@ -1235,7 +1308,7 @@ async function generateTurnPrefixSummary(
 	const maxTokens = Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix
 
 	const llmMessages = (options?.convertToLlm ?? convertToLlm)(messages);
-	const conversationText = serializeConversation(llmMessages);
+	const conversationText = boundConversationTextForSummary(serializeConversation(llmMessages), model, maxTokens);
 	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
 	const summarizationMessages = [
 		{

package/src/compaction/pruning.ts

@@ -527,14 +527,29 @@ export function pruneAssistantToolArguments(
 	return { argumentPrunedCount: candidates.length, argumentTokensSaved, prunedEntries };
 }
 
-export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+interface ToolOutputPruneCandidate {
+	entry: SessionMessageEntry;
+	tokens: number;
+	notice: string;
+	savings: number;
+}
+
+/**
+ * Read-only pass that collects the tool-result entries that {@link pruneToolOutputs}
+ * would prune, plus the total estimated token savings. Shared by the mutating
+ * prune and the non-mutating {@link estimateToolOutputPruneSavings} so the
+ * maintenance gate (Finding 13) can decide whether pruning is worth a cache-epoch
+ * reset without rewriting history.
+ */
+function collectToolOutputPruneCandidates(
+	entries: SessionEntry[],
+	config: PruneConfig,
+): { candidates: ToolOutputPruneCandidate[]; tokensSaved: number } {
 	let accumulatedTokens = 0;
-	let tokensSaved = 0;
-	let prunedCount = 0;
 
 	const { staleResultIndices } = buildStalenessIndex(entries);
 	const staleOverridable = new Set(config.staleOverridableTools ?? []);
-	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; notice: string; savings: number }> = [];
+	const candidates: ToolOutputPruneCandidate[] = [];
 
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
@@ -574,14 +589,56 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 		accumulatedTokens += tokens;
 	}
 
+	let tokensSaved = 0;
 	for (const candidate of candidates) {
 		tokensSaved += candidate.savings;
 	}
+	return { candidates, tokensSaved };
+}
+
+/**
+ * Estimate the token savings {@link pruneToolOutputs} would achieve, without
+ * mutating any entry. Returns 0 savings when below the configured minimum so the
+ * caller sees the same gate the real prune enforces.
+ */
+export function estimateToolOutputPruneSavings(
+	entries: SessionEntry[],
+	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+): { prunableCount: number; tokensSaved: number } {
+	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
+	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+		return { prunableCount: 0, tokensSaved: 0 };
+	}
+	return { prunableCount: candidates.length, tokensSaved };
+}
+
+/**
+ * Evidence gate for below-threshold maintenance pruning (Finding 13). Pruning
+ * forces a prompt-cache-epoch reset, so it only runs when opted in AND the
+ * estimated stale savings clear a high minimum AND exceed the one-time reset
+ * cost (so the reclaim pays the reset back). Default-off/blocked until live
+ * evidence justifies enabling.
+ */
+export function shouldRunMaintenancePrune(args: {
+	enabled: boolean;
+	estimatedSavings: number;
+	minSavings: number;
+	cacheEpochResetCost: number;
+}): boolean {
+	if (!args.enabled) return false;
+	if (args.estimatedSavings < args.minSavings) return false;
+	return args.estimatedSavings > args.cacheEpochResetCost;
+}
+
+export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
 
 	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
 		return { prunedCount: 0, tokensSaved: 0, prunedEntries: [] };
 	}
 
+	let prunedCount = 0;
+
 	const prunedAt = Date.now();
 	const prunedEntries: SessionMessageEntry[] = [];
 	for (const candidate of candidates) {