pi-openai-toolkit 0.20.5 → 0.20.7

package/docs/internals.md

@@ -73,11 +73,12 @@ sequenceDiagram
   Model->>Toolkit: new_context
   Toolkit->>Toolkit: verify successful notes write in this window
   Toolkit-->>Model: checkpoint receipt with the successful note path
-  Toolkit-->>Pi: window marker appended, previous window trim scheduled
+  Toolkit-->>Pi: new window marker persisted
   Note over Model: Context switch is complete; read the receipt once, then resume the active task
   Model->>Backend: next request with the new x-codex-window-id
   Pi->>Toolkit: session_before_compact
-  Toolkit-->>Pi: no-summary boundary consuming the scheduled trim
+  Toolkit->>Toolkit: resolve boundary against Pi's effective context
+  Toolkit-->>Pi: safe no-summary boundary, or cancel obsolete cleanup
 ```
 
 State invariants the lifecycle code must keep honest:
@@ -90,12 +91,12 @@ State invariants the lifecycle code must keep honest:
 - When even that rebuild would lose declared tools, the trim is refused and the full message list is sent: a window that still carries the previous turns is usable, a window with no tools silently degrades into a chat the model can only narrate. Each refusal is reported once per window and lost-tool set through `takeProjectionDiagnostics()`, which writes a `context.projection.tool_loadout_shrink` compaction artifact and warns in the UI.
 - The manager also remembers the head it last anchored. When a boundary compaction retires the transcript entry that declared the tools, the branch itself no longer contains a system message, and the remembered head is re-anchored instead of sending a tool-less window. The cache is request-time only, refreshed by every projection, and cleared by `reset()`.
 - `new_context` has no force escape hatch: a persisted successful notes checkpoint in the current window is always required before rollover. The model must wait for the notes result to be persisted before retrying.
-- After a marker is accepted for sending, the manager keeps a session/window-anchored pending guard until that exact target marker is persisted or the session changes. A duplicate `new_context` during this persistence gap returns `started: false` and sends no second marker; projected/in-memory messages do not retire the guard.
+- After a marker is accepted for sending, the manager keeps a session/window-anchored pending guard until that exact target marker is persisted or the session changes. A duplicate `new_context` during this persistence gap returns `started: false` and sends no second marker; projected/in-memory messages do not retire the guard. The exact queued target can already trim the current Remote request and select its metadata, but this preview is recomputed per request and never authorizes maintenance compaction before persistence.
 - Budget checks are skipped until the current window has produced its own assistant usage. Acting on the previous window's usage anchor would burn the once-per-window reminder on a false alarm.
-- Preparing a boundary never consumes its scheduled trim. The manager reconciles the latest persisted compaction and branch state, so only a durable matching boundary consumes it. Missing/late callbacks, aborted preparation and navigation across branches sharing a marker remain retryable. Automatic threshold/overflow and toolkit-owned manual maintenance only trim a matching scheduled window; a user manual `/compact` follows the managed handoff below.
-- A window boundary is persisted as a `codex-context-window` custom message. `session_start` replays boundaries from the branch and rebuilds identity after forks.
-- Retiring windows remains a projection-level operation in the persisted branch, but a non-window consumer never receives that retired history. `context_with_system` trims to the latest persisted Remote Context boundary, preserves the current system/tool head, and removes the internal window marker before the local provider request. The legacy `leaveManagedMode` setting is retained only so old config files remain valid; it no longer warns or starts a bulk close-out from `model_select` or `agent_settled`.
-- If a non-window consumer reaches `session_before_compact` while a Remote Context boundary exists, the extension returns a no-summary compaction anchored at that boundary. No Remote V2/native compaction producer receives the Remote window, Pi retains the marker and current-window tail, and switching back to a supported model reuses the persisted window identity. A session with no Remote boundary keeps the ordinary compaction path.
+- Pi's canonical session projection is the source of effective history. Toolkit may further restrict that projection, but never reconstruct omitted or summarized messages from the raw branch. Boundary resolution uses projected source entries and the active branch's latest compaction; an older marker retained inside a newer compaction does not authorize dropping that compaction's summary.
+- Window identity and cleanup eligibility are separate. A persisted `codex-context-window` message restores identity after reload/fork, but its historical `trimPreviousWindow` flag is not an outstanding command. A newer native summary or opaque checkpoint supersedes old cleanup without erasing window identity. Missing or edited boundary evidence is never repaired by loading raw history.
+- Maintenance compaction and local-consumer detachment use the same effective-boundary rules. Only a safe current boundary can produce a no-summary compaction; obsolete cleanup must not move the retained start backwards or replace a newer summary/checkpoint. Preparation alone changes no durable state, and cancellation, retry and branch navigation are resolved from current evidence rather than callback acknowledgments. User manual `/compact` still follows the managed handoff below.
+- A non-window consumer receives only the effective current context, with the system/tool head preserved and internal window markers removed. When detachment is needed, no compaction producer receives retired Remote history. Once a later ordinary compaction owns effective context, the historical window does not suppress its summary or valid opaque replay. A genuinely new window can retire that checkpoint. Disabling opaque checkpoint generation through `responsesApis` does not disable required replay of an inherited checkpoint; an unsupported transport, authentication failure, or endpoint mismatch aborts the request instead of exposing its placeholder. The legacy `leaveManagedMode` setting remains compatible but does not start a bulk close-out from `model_select` or `agent_settled`.
 - The configured native-fallback summary model is still checked against the physical request size (`estimateSummarizationRequest`). The guard remains a provider-safety invariant; the Remote-window fix avoids the oversized request by excluding managed history before any compaction producer can be called, rather than removing the guard or chunking the request.
 
 ---
@@ -120,7 +121,7 @@ The underlying native compact promise still rejects its intentional cancellation
 
 ### Remote Compaction v2 wire contract
 
-v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway without an exact transport opt-in, can still compact through v2 when its API appears in `context.remoteCompaction.apis`. The two strategies never compete for one session.
+v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway without an exact transport opt-in, can still compact through v2 when its API appears in `context.remoteCompaction.apis`. Compaction generation follows the active strategy. Across mode changes, an already-persisted checkpoint remains authoritative until a safe newer window or compaction replaces it; a historical window identity alone must not suppress checkpoint replay.
 
 A `compaction_trigger` item appended to the live streaming request yields one output item of `type: "compaction"` with non-empty `encrypted_content`, stored in `CompactionEntry.details.compactedWindow`. On later requests the opaque checkpoint is replayed ahead of live turns, with no text summary. Replay fails closed: if the summary anchor cannot be located, the request is aborted with a notification and a content-free failure artifact. The sentinel-only payload is never sent.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openai-toolkit",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "private": false,
   "type": "module",
   "engines": {

package/src/context-management/window-manager.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ProviderHeaders } from "@earendil-works/pi-ai";
 import {
-	buildSessionContext,
+	buildSessionProjection,
 	calculateContextTokens,
 	estimateTokens,
 	type CompactionResult,
@@ -43,6 +43,7 @@ import {
 	loadHistoryNotesThreadHint,
 } from "./history-notes";
 import { rewriteContextNamespaceTools } from "./namespace-tools";
+import { hasInvalidatedCompactionContext } from "../payload-rewrite";
 
 interface StartContextWindowOptions {
 	triggerTurn: boolean;
@@ -73,6 +74,8 @@ type WindowBoundaryEntry = Extract<SessionEntry, { type: "custom_message" }> & {
 type PendingRollover = {
 	sessionId?: string;
 	targetWindowId: string;
+	/** The current request already contains this marker; never persistence proof. */
+	projected?: boolean;
 };
 
 export class CodexContextWindowManager {
@@ -80,10 +83,9 @@ export class CodexContextWindowManager {
 	private sessionId: string | undefined;
 	private restoredMarkerId: string | undefined;
 	private restoredCompactionId: string | undefined;
-	private branchStateInvalidated = false;
+	private boundary: WindowBoundaryResolution = { kind: "none" };
 	private readonly budget = new ContextWindowBudget();
 	private pendingRollover: PendingRollover | undefined;
-	private trimPendingWindowId: string | undefined;
 	private readonly projectionDiagnostics = new Set<string>();
 	private lastKnownSystemHead: AgentMessage | undefined;
 	/**
@@ -108,9 +110,21 @@ export class CodexContextWindowManager {
 	currentIdentity(): ContextWindowIdentity | undefined {
 		return this.identity ? { ...this.identity } : undefined;
 	}
-	/** Whether a rollover trim awaits a matching persisted compaction. */
+	/** Derived eligibility, never a replayed marker command. */
 	hasPendingTrim(): boolean {
-		return this.trimPendingWindowId !== undefined;
+		return this.boundary.kind === "effective" && !this.boundary.cleaned &&
+			this.boundary.entry.details.contextManagement.trimPreviousWindow === true;
+	}
+
+	/** Historical identity does not own a newer native/opaque checkpoint. */
+	hasEffectiveWindow(): boolean {
+		if (!this.identity || this.boundary.kind === "ambiguous") return false;
+		return this.boundary.kind !== "superseded" ||
+			(this.pendingRollover?.projected === true && this.pendingRollover.targetWindowId === this.identity.currentWindowId);
+	}
+
+	hasSupersededWindow(): boolean {
+		return this.boundary.kind === "superseded";
 	}
 
 	private resetWindowState(): void {
@@ -118,9 +132,8 @@ export class CodexContextWindowManager {
 		this.sessionId = undefined;
 		this.restoredMarkerId = undefined;
 		this.restoredCompactionId = undefined;
-		this.branchStateInvalidated = false;
+		this.boundary = { kind: "none" };
 		this.budget.reset();
-		this.trimPendingWindowId = undefined;
 		this.projectedContextTokens = undefined;
 	}
 
@@ -132,7 +145,6 @@ export class CodexContextWindowManager {
 		for (const entry of entries) {
 			if (entry.type === "compaction") {
 				this.restoredCompactionId = entry.id;
-				this.recordCompaction(entry.details);
 				continue;
 			}
 			if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
@@ -145,13 +157,10 @@ export class CodexContextWindowManager {
 			this.restoredMarkerId = entry.id;
 			if (details.kind === "window") {
 				this.identity = identityFromDetails(entry.details);
-				this.trimPendingWindowId = details.trimPreviousWindow ? details.currentWindowId : undefined;
 			}
 			this.budget.restore(details.kind, details.currentWindowId);
 		}
-		// recordCompaction may invalidate the cache while replaying entries; the
-		// completed replay already reconciled those acknowledgments with this branch.
-		this.branchStateInvalidated = false;
+		this.boundary = resolveWindowBoundary(entries, sessionId);
 		this.retireSatisfiedOrStalePending(entries, sessionId);
 	}
 
@@ -170,9 +179,11 @@ export class CodexContextWindowManager {
 		}
 		// Hook-provided compactions may have no success callback. The persisted
 		// branch also detects navigation before/after a commit with the same marker.
-		if (this.branchStateInvalidated || this.sessionId !== sessionId || this.restoredMarkerId !== latestMarkerId || this.restoredCompactionId !== latestCompactionId) {
+		if (this.sessionId !== sessionId || this.restoredMarkerId !== latestMarkerId || this.restoredCompactionId !== latestCompactionId) {
 			this.restore(entries, sessionId);
 		}
+		// Edits and sibling navigation may leave marker/compaction IDs unchanged.
+		this.boundary = resolveWindowBoundary(entries, sessionId);
 	}
 
 	/**
@@ -211,13 +222,22 @@ export class CodexContextWindowManager {
 	project(
 		messages: readonly AgentMessage[],
 		mode: "off" | "local" | "remote",
+		/** Delay encoding until verified retained copies have been removed. */
+		encodeEncryptedOutputs = true,
 	): AgentMessage[] {
+		// Recompute the request-only preview on every projection. Observing a
+		// queued marker must not authorize maintenance or retire the duplicate guard.
+		if (this.pendingRollover) this.pendingRollover.projected = false;
 		if (mode === "off") {
 			this.projectedContextTokens = undefined;
 			return messages.filter(
 				(message) => message.role !== "custom" || message.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
 			);
 		}
+		if (this.boundary.kind === "ambiguous") {
+			throw new Error("Persisted Codex context-window boundary missing or edited in canonical projection");
+		}
+		if (this.boundary.kind === "superseded") this.identity = identityFromDetails(this.boundary.entry.details);
 		let boundaryIndex = -1;
 		for (let index = 0; index < messages.length; index += 1) {
 			const message = messages[index]!;
@@ -232,28 +252,24 @@ export class CodexContextWindowManager {
 				if (!matchesSession(message.details.sessionId, this.sessionId)) continue;
 			}
 			if (!isContextWindowBoundary(message)) continue;
+			const queuedRollover = mode === "remote" && this.pendingRollover?.targetWindowId === message.details.contextManagement.currentWindowId;
+			if (this.boundary.kind === "superseded" && !queuedRollover) continue;
 			// Local consumers follow the synchronized persisted identity, not a
 			// queued marker from the request view. They never own the Remote session.
 			if (mode === "local" && message.details.contextManagement.currentWindowId !== this.identity?.currentWindowId) continue;
 			boundaryIndex = index;
-			if (mode === "remote") this.identity = identityFromDetails(message.details);
-		}
-		if (boundaryIndex < 0) {
-			if (mode === "local" && this.identity) {
-				throw new Error("Persisted Codex context-window boundary missing from local projection");
-			}
 			if (mode === "remote") {
-				this.identity = undefined;
-				this.restoredMarkerId = undefined;
-				this.budget.reset();
-				this.trimPendingWindowId = undefined;
+				this.identity = identityFromDetails(message.details);
+				if (this.pendingRollover) this.pendingRollover.projected = queuedRollover;
 			}
-			this.projectedContextTokens = undefined;
+		}
+		if (boundaryIndex < 0 && this.boundary.kind === "effective") {
+			throw new Error("Persisted Codex context-window boundary missing from effective projection");
 		}
 		// Projection observes the request view, never durable session state. A
 		// queued rollover marker must not clear the duplicate guard here.
 		const trimmed = boundaryIndex < 0 ? [...messages] : this.trimToWindow(messages, boundaryIndex, mode === "local");
-		const projected = mode === "remote" ? projectEncryptedToolResults(trimmed) : trimmed.filter(
+		const projected = mode === "remote" ? (encodeEncryptedOutputs ? projectEncryptedToolResults(trimmed) : trimmed) : trimmed.filter(
 			(message) => message.role !== "custom" || message.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
 		);
 		this.projectedContextTokens = mode === "remote" && this.identity
@@ -421,21 +437,12 @@ export class CodexContextWindowManager {
 	prepareCompaction(
 		event: SessionBeforeCompactEvent,
 	): { cancel: true } | { compaction: CompactionResult<ContextWindowCompactionDetails> } {
-		// Only the compaction that consumes a scheduled rollover may write a
-		// boundary. Every other path — threshold, manual /compact, overflow —
-		// stays cancelled: a boundary written without a pending trim does not
-		// shrink anything, becomes Pi's latest-compaction anchor, and blinds
-		// getContextUsage (null tokens) until the next assistant usage lands —
-		// which is exactly how the exhausted-window fallback can go silent.
-		const boundary = findLatestWindowBoundaryEntry(event.branchEntries, this.sessionId);
-		if (!boundary || boundary.details.contextManagement.currentWindowId !== this.trimPendingWindowId) {
+		const boundary = resolveWindowBoundary(event.branchEntries, this.sessionId);
+		if (boundary.kind !== "effective" || boundary.cleaned || !boundary.entry.details.contextManagement.trimPreviousWindow) {
 			return { cancel: true };
 		}
-		const compaction = this.createCompaction(event);
-		// Preparation is only a proposal: Pi may abort before appending it.
-		// synchronize() consumes the trim after observing a durable compaction;
-		// recordCompaction() also handles hosts that emit a success callback.
-		return { compaction };
+		// An unpersisted/cancelled proposal changes no eligibility.
+		return { compaction: this.createCompaction(event, boundary.entry) };
 	}
 
 	/**
@@ -445,10 +452,12 @@ export class CodexContextWindowManager {
 	 */
 	prepareDetachedCompaction(
 		event: SessionBeforeCompactEvent,
-	): { compaction: CompactionResult<ContextWindowCompactionDetails> } | undefined {
-		const boundary = findLatestWindowBoundaryEntry(event.branchEntries, this.sessionId);
-		if (!boundary) return undefined;
-		const compaction = this.createCompaction(event);
+	): { cancel: true } | { compaction: CompactionResult<ContextWindowCompactionDetails> } | undefined {
+		const boundary = resolveWindowBoundary(event.branchEntries, this.sessionId);
+		if (boundary.kind === "ambiguous") throw new Error("Persisted Codex context-window boundary missing or edited");
+		if (boundary.kind !== "effective") return undefined;
+		if (boundary.cleaned) return { cancel: true };
+		const compaction = this.createCompaction(event, boundary.entry);
 		// Pi's preparation/tokensBefore describes the durable branch, which includes
 		// Remote-managed history. Detached local accounting must use the same current
 		// window projection that the non-window provider sees instead.
@@ -461,30 +470,19 @@ export class CodexContextWindowManager {
 	}
 
 	private estimateLocalContextTokens(entries: readonly SessionEntry[]): number {
-		const messages = buildSessionContext(entries as never[]).messages as unknown as AgentMessage[];
+		const messages = buildSessionProjection([...entries]).messages;
 		return this.project(messages, "local").reduce((total, message) => total + estimateTokens(message as never), 0);
 	}
 
-	recordCompaction(details: unknown): void {
-		if (!isContextWindowCompactionDetails(details)) return;
-		if (this.trimPendingWindowId !== undefined && details.windowId === this.trimPendingWindowId) {
-			this.trimPendingWindowId = undefined;
-			// The callback supplies no branch identity. Force durable reconciliation
-			// even if navigation returns to the cached pre-commit branch before sync.
-			this.branchStateInvalidated = true;
-		}
-	}
-
-	createCompaction(event: SessionBeforeCompactEvent): CompactionResult<ContextWindowCompactionDetails> {
-		const boundary = findLatestWindowBoundaryEntry(event.branchEntries, this.sessionId);
+	private createCompaction(event: SessionBeforeCompactEvent, boundary: WindowBoundaryEntry): CompactionResult<ContextWindowCompactionDetails> {
 		return {
 			summary: CONTEXT_WINDOW_COMPACTION_SUMMARY,
-			firstKeptEntryId: boundary?.id ?? event.preparation.firstKeptEntryId,
+			firstKeptEntryId: boundary.id,
 			tokensBefore: event.preparation.tokensBefore,
 			details: {
 				protocol: CONTEXT_MANAGEMENT_PROTOCOL,
 				strategy: CONTEXT_WINDOW_COMPACTION_STRATEGY,
-				...(this.identity ? { windowId: this.identity.currentWindowId } : {}),
+				windowId: boundary.details.contextManagement.currentWindowId,
 			},
 		};
 	}
@@ -517,13 +515,41 @@ export class CodexContextWindowManager {
 		this.identity = identity;
 		this.sessionId = ctx.sessionManager.getSessionId();
 		this.restoredMarkerId = undefined;
-		this.trimPendingWindowId = options.trimPreviousWindow ? identity.currentWindowId : undefined;
 		// sendMessage() acceptance is not persistence. The pending rollover stays
 		// armed until synchronize() observes this target window in the persisted
 		// branch (or the session changes).
 	}
 }
 
+type WindowBoundaryResolution =
+	| { kind: "none" | "ambiguous" }
+	| { kind: "superseded"; entry: WindowBoundaryEntry }
+	| { kind: "effective"; entry: WindowBoundaryEntry; cleaned: boolean };
+
+/** Pi's projection owns context; raw chronology only establishes window ownership. */
+function resolveWindowBoundary(entries: readonly SessionEntry[], sessionId?: string): WindowBoundaryResolution {
+	const boundary = findLatestWindowBoundaryEntry(entries, sessionId);
+	if (!boundary) return { kind: "none" };
+	const projection = buildSessionProjection([...entries]);
+	const latest = projection.entries.find((entry) => entry.sourceEntry.type === "compaction")?.sourceEntry;
+	const boundaryIndex = entries.findIndex((entry) => entry.id === boundary.id);
+	const laterCompaction = latest?.type === "compaction" && entries.findIndex((entry) => entry.id === latest.id) > boundaryIndex
+		? latest : undefined;
+	if (laterCompaction && hasInvalidatedCompactionContext([...entries], laterCompaction.id)) return { kind: "ambiguous" };
+	const marker = projection.entries.find((entry) => entry.sourceEntry.id === boundary.id);
+	// A surviving edit can replace content without changing custom details.
+	const edited = entries.some((entry) => entry.type === "context_edit" && entry.targetId === boundary.id &&
+		projection.entries.some((projected) => projected.sourceEntry.id === entry.id));
+	if (edited) return { kind: "ambiguous" };
+	const cleaned = laterCompaction !== undefined &&
+		isContextWindowCompactionDetails(laterCompaction.details) &&
+		laterCompaction.details.windowId === boundary.details.contextManagement.currentWindowId &&
+		laterCompaction.firstKeptEntryId === boundary.id;
+	if (laterCompaction && !cleaned) return { kind: "superseded", entry: boundary };
+	if (!marker?.messages.some(isContextWindowBoundary)) return { kind: "ambiguous" };
+	return { kind: "effective", entry: boundary, cleaned };
+}
+
 function identityFromDetails(details: CodexContextManagementMessageDetails): ContextWindowIdentity {
 	const context = details.contextManagement;
 	return {

package/src/extension-runtime.ts

@@ -882,7 +882,9 @@ async function handleSessionBeforeCompact(
 			config,
 			ctx,
 		);
-		if (config.remoteCompactModel) {
+		const expectedConsumerCapabilityMiss =
+			resolution.reason === "unsupported-api" && resolution.modelSpec === undefined;
+		if (config.remoteCompactModel && !expectedConsumerCapabilityMiss) {
 			notifyWarning(
 				ctx,
 				`remote compaction model "${config.remoteCompactModel}" unusable (${resolution.reason}); using the native fallback chain`,
@@ -955,6 +957,19 @@ async function handleSessionBeforeCompact(
 	return undefined;
 }
 
+function rejectInheritedCheckpointReplay(
+	ctx: ExtensionContext,
+	config: CompactionConfig,
+	compactionEntryId: string,
+	reason: string,
+): undefined {
+	writeReplayFailureArtifact({ reason, compactionEntryId }, config, ctx);
+	reportPiContextHookFailure(ctx, `replay-failed:${reason}`);
+	if (ctx.hasUI) ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: inherited checkpoint replay failed (${reason}); request aborted`, "error");
+	ctx.abort();
+	return undefined;
+}
+
 async function handleContextInternal(
 	event: ContextWithSystemEvent,
 	ctx: ExtensionContext,
@@ -975,6 +990,7 @@ async function handleContextInternal(
 	}
 
 	let localMessages: AgentMessage[] | undefined;
+	let remoteReplayProjection = false;
 	if (config.contextManagement === "remote") {
 		const contextModel = await resolveContextCapabilityModel(ctx);
 		try {
@@ -992,7 +1008,11 @@ async function handleContextInternal(
 				// Measure the provider-visible current window, not Pi's durable transcript.
 				// The latter still contains retired remote windows and can be inflated by
 				// an upstream error even though this request only carries the live window.
-				const projected = contextWindows.project(event.messages, "remote");
+				let projected = contextWindows.project(event.messages, "remote", false);
+				// Projection may observe the exact queued rollover before Pi persists
+				// it. Decide replay ownership from this request, not the old branch.
+				const ownsWindow = contextWindows.hasEffectiveWindow() || !contextWindows.currentIdentity();
+				if (ownsWindow) projected = contextWindows.project(projected, "remote");
 				contextWindows.recordBudget(
 					pi,
 					ctx,
@@ -1000,9 +1020,13 @@ async function handleContextInternal(
 					config.contextReminderThresholdPercent,
 				);
 				reportProjectionDiagnostics(contextWindows, config, ctx);
-				return projected.length === event.messages.length && projected.every((message, index) => message === event.messages[index])
-					? undefined
-					: { messages: projected };
+				if (ownsWindow) {
+					return projected.length === event.messages.length && projected.every((message, index) => message === event.messages[index])
+						? undefined
+						: { messages: projected };
+				}
+				localMessages = projected;
+				remoteReplayProjection = true;
 			} catch (error) {
 				notifyRemoteContextFailure(ctx, "malformed-window-state");
 				reportPiContextHookFailure(ctx, "malformed-window-state");
@@ -1011,11 +1035,10 @@ async function handleContextInternal(
 			}
 		}
 
-		// An eligible Codex Remote session is never allowed to fall through to the
-		// older compaction-replay path. An explicit host exclusion is the one
-		// intentional downgrade: strip internal markers and let the ordinary request
-		// proceed without Remote Context affinity.
-		if (isCodexContextModel(contextModel, config)) {
+		// An unavailable covered runtime must not silently become an ordinary
+		// replay consumer. Explicit host exclusion remains the one intentional
+		// downgrade; active Remote can replay a newer inherited checkpoint.
+		if (!remoteActive && isCodexContextModel(contextModel, config)) {
 			const registrationState = getContextToolRegistrationState();
 			if (isExcludedGatewayContext(contextModel, config, registrationState)) {
 				const visibleMessages = contextWindows.project(event.messages, "off");
@@ -1036,39 +1059,58 @@ async function handleContextInternal(
 				: { messages: visibleMessages };
 		}
 
-		try {
-			const projected = contextWindows.project(event.messages, "local");
-			localMessages = projected;
-			if (contextWindows.currentIdentity()) {
-				// This boundary owns earlier history, including any older Remote V2
-				// checkpoint. A local request must not replay that history back in.
-				return projected.length === event.messages.length && projected.every((message, index) => message === event.messages[index])
-					? undefined
-					: { messages: projected };
+		if (!remoteActive) {
+			try {
+				const projected = contextWindows.project(event.messages, "local");
+				localMessages = projected;
+				if (contextWindows.hasEffectiveWindow()) {
+					// This boundary owns earlier history, including any older Remote V2
+					// checkpoint. A local request must not replay that history back in.
+					return projected.length === event.messages.length && projected.every((message, index) => message === event.messages[index])
+						? undefined
+						: { messages: projected };
+				}
+			} catch (error) {
+				notifyRemoteContextFailure(ctx, "malformed-window-state");
+				reportPiContextHookFailure(ctx, error instanceof Error ? error.message : String(error));
+				ctx.abort();
+				return undefined;
 			}
-		} catch (error) {
-			notifyRemoteContextFailure(ctx, "malformed-window-state");
-			reportPiContextHookFailure(ctx, error instanceof Error ? error.message : String(error));
-			ctx.abort();
-			return undefined;
 		}
 	}
 
-	// With no Remote boundary, the ordinary checkpoint replay path remains the
-	// owner. Inactive covered Codex consumers were handled separately above.
+	// Without an effective Remote boundary, the latest checkpoint owns replay.
+	// This also covers a newer checkpoint superseding a historical window.
 	const visibleMessages = localMessages ?? contextWindows.project(event.messages, "off");
-	const visibleResult = visibleMessages.length === event.messages.length && visibleMessages.every((message, index) => message === event.messages[index])
-		? undefined : { messages: visibleMessages };
+	const finishProjection = (messages: AgentMessage[]) => {
+		// Compare canonical retained copies before Remote encrypted-output encoding.
+		const projected = remoteReplayProjection ? contextWindows.project(messages, "remote") : messages;
+		return projected.length === event.messages.length && projected.every((message, index) => message === event.messages[index])
+			? undefined : { messages: projected };
+	};
 	const replayEvent = visibleMessages === event.messages ? event : { ...event, messages: visibleMessages };
+	const branchEntries = ctx.sessionManager.getBranch();
+	const inherited = config.contextManagement === "remote" && contextWindows.hasSupersededWindow()
+		? resolveLatestNativeCompactionEntry(branchEntries) : undefined;
+	const inheritedCheckpoint = inherited?.ok ? inherited.entry : undefined;
 	const resolution = await resolveNativeCompactionEnvironment(ctx, {
 		enabled: config.enabled,
-		responsesApis: config.responsesApis,
+		// Disabling checkpoint generation cannot turn an inherited opaque
+		// checkpoint into a usable text summary. Replay checks transport support.
+		responsesApis: inheritedCheckpoint ? undefined : config.responsesApis,
 		codexGatewayModels: compactGatewayModels(resolved),
 	});
-	if (!resolution.ok) return visibleResult;
-	const branchEntries = ctx.sessionManager.getBranch();
+	if (!resolution.ok) {
+		return inheritedCheckpoint
+			? rejectInheritedCheckpointReplay(ctx, config, inheritedCheckpoint.id, resolution.reason)
+			: finishProjection(visibleMessages);
+	}
 	const latest = resolveLatestNativeCompactionEntry(branchEntries, { baseUrl: resolution.runtime.baseUrl });
-	if (!latest.ok) return visibleResult;
+	if (!latest.ok) {
+		return inheritedCheckpoint
+			? rejectInheritedCheckpointReplay(ctx, config, inheritedCheckpoint.id, latest.reason)
+			: finishProjection(visibleMessages);
+	}
 	const result = removeNativeCompactionRetainedMessages({
 		messages: replayEvent.messages,
 		branchEntries,
@@ -1082,7 +1124,7 @@ async function handleContextInternal(
 		ctx.abort();
 		return undefined;
 	}
-	return result.messages === replayEvent.messages ? visibleResult : { messages: result.messages };
+	return finishProjection(result.messages);
 }
 
 /**
@@ -1135,16 +1177,20 @@ async function handleBeforeProviderRequest(
 			return undefined;
 		}
 	}
-	if (config.contextManagement === "remote" && await remoteContextActive(ctx, config, contextModel)) {
+	const remoteActive = config.contextManagement === "remote" && await remoteContextActive(ctx, config, contextModel);
+	let remotePayload: unknown;
+	if (remoteActive) {
 		try {
-			return contextWindows.rewritePayload(event.payload, ctx);
+			remotePayload = contextWindows.rewritePayload(event.payload, ctx);
+			if (contextWindows.hasEffectiveWindow() || !contextWindows.currentIdentity()) return remotePayload;
+			event = { ...event, payload: remotePayload };
 		} catch {
 			notifyRemoteContextFailure(ctx, "malformed-request-state");
 			ctx.abort();
 			return undefined;
 		}
 	}
-	if (isCodexContextModel(contextModel, config)) {
+	if (!remoteActive && isCodexContextModel(contextModel, config)) {
 		const registrationState = getContextToolRegistrationState();
 		// A readable empty registry is an intentional host exclusion. Do not
 		// rewrite gateway identity or abort an ordinary child-session request.
@@ -1163,18 +1209,23 @@ async function handleBeforeProviderRequest(
 
 	// Do not reintroduce a pre-window opaque checkpoint after local projection.
 	// Request affinity/encrypted-output rewriting is reserved for active Remote.
-	if (config.contextManagement === "remote" && contextWindows.currentIdentity()) return undefined;
+	if (config.contextManagement === "remote" && contextWindows.hasEffectiveWindow()) return undefined;
 
+	const branchEntries = ctx.sessionManager.getBranch();
+	const inherited = config.contextManagement === "remote" && contextWindows.hasSupersededWindow()
+		? resolveLatestNativeCompactionEntry(branchEntries) : undefined;
+	const inheritedCheckpoint = inherited?.ok ? inherited.entry : undefined;
 	const resolution = await resolveNativeCompactionEnvironment(
 		ctx,
 		{
 			enabled: config.enabled,
-			responsesApis: config.responsesApis,
+			responsesApis: inheritedCheckpoint ? undefined : config.responsesApis,
 			codexGatewayModels: compactGatewayModels(resolved),
 		},
 		event.payload,
 	);
 	if (resolution.ok === false) {
+		if (inheritedCheckpoint) return rejectInheritedCheckpointReplay(ctx, config, inheritedCheckpoint.id, resolution.reason);
 		writeDebugArtifact(
 			"provider-request",
 			{
@@ -1191,7 +1242,7 @@ async function handleBeforeProviderRequest(
 			config,
 			ctx,
 		);
-		return undefined;
+		return remotePayload;
 	}
 
 	const runtime = resolution.runtime;
@@ -1219,11 +1270,11 @@ async function handleBeforeProviderRequest(
 		},
 	);
 
-	const branchEntries = ctx.sessionManager.getBranch();
 	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
 		baseUrl: runtime.baseUrl,
 	});
 	if (!latestNativeCompaction.ok) {
+		if (inheritedCheckpoint) return rejectInheritedCheckpointReplay(ctx, config, inheritedCheckpoint.id, latestNativeCompaction.reason);
 		writeDebugArtifact(
 			"provider-request",
 			{
@@ -1241,7 +1292,7 @@ async function handleBeforeProviderRequest(
 			config,
 			ctx,
 		);
-		return undefined;
+		return remotePayload;
 	}
 
 	const latestNativeCompactionEntry = latestNativeCompaction.entry;
@@ -1469,7 +1520,7 @@ export default function registerCompactionExtension(
 		return handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive, getContextToolRegistrationState);
 	});
 	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive, getContextToolRegistrationState));
-	pi.on("session_compact", (event, _ctx) => contextWindows.recordCompaction(event.compactionEntry.details));
+	pi.on("session_compact", (_event, ctx) => contextWindows.synchronize(ctx));
 	pi.on("session_compact_failed", async (event, ctx) => {
 		if (event.reason === "manual" && !manualCompact.isMaintenance) await manualCompact.compactFailed(ctx);
 	});

package/src/native-fallback.ts

@@ -1,7 +1,8 @@
 import {
 	compact,
+	convertToLlm,
 	DEFAULT_COMPACTION_SETTINGS,
-	estimateTokens,
+	serializeConversation,
 	type CompactionResult,
 	type ExtensionContext,
 	type SessionBeforeCompactEvent,
@@ -59,16 +60,10 @@ function toErrorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
-/**
- * Output budget Pi gives the summary itself: `generateSummary` caps `maxTokens` at
- * `min(floor(0.8 * reserveTokens), model.maxTokens)`.
- */
-const SUMMARIZATION_OUTPUT_RESERVE_TOKENS = Math.floor(
-	DEFAULT_COMPACTION_SETTINGS.reserveTokens * 0.8,
-);
-
-/** Summarization instructions plus the `<conversation>` framing around the transcript. */
+/** Summarization instructions plus the framing around the serialized transcript. */
 const SUMMARIZATION_TEMPLATE_TOKENS = 1024;
+const HISTORY_OUTPUT_RESERVE_RATIO = 0.8;
+const TURN_PREFIX_OUTPUT_RESERVE_RATIO = 0.5;
 
 export type SummarizationRequestSize = {
 	inputTokens: number;
@@ -76,33 +71,93 @@ export type SummarizationRequestSize = {
 	totalTokens: number;
 };
 
+function estimateTextTokens(text: string | undefined): number {
+	return text ? Math.ceil(String(text).length / 4) : 0;
+}
+
+function estimateSerializedConversationTokens(
+	messages: SessionBeforeCompactEvent["preparation"]["messagesToSummarize"],
+): number {
+	const serialized = serializeConversation(convertToLlm(messages));
+	return estimateTextTokens(serialized);
+}
+
+function getEffectiveReserveTokens(preparation: SessionBeforeCompactEvent["preparation"]): number {
+	const reserveTokens = preparation.settings?.reserveTokens;
+	return typeof reserveTokens === "number" && Number.isFinite(reserveTokens) && reserveTokens >= 0
+		? reserveTokens
+		: DEFAULT_COMPACTION_SETTINGS.reserveTokens;
+}
+
+function getOutputReserveTokens(
+	reserveTokens: number,
+	model: { maxTokens?: number },
+	ratio: number,
+): number {
+	const outputTokens = Math.floor(ratio * reserveTokens);
+	return typeof model.maxTokens === "number" && model.maxTokens > 0
+		? Math.min(outputTokens, model.maxTokens)
+		: outputTokens;
+}
+
+function estimateSummaryRequest(
+	messages: SessionBeforeCompactEvent["preparation"]["messagesToSummarize"],
+	outputTokens: number,
+	previousSummary?: string,
+	customInstructions?: string,
+): SummarizationRequestSize {
+	const inputTokens =
+		SUMMARIZATION_TEMPLATE_TOKENS
+		+ estimateSerializedConversationTokens(messages)
+		+ estimateTextTokens(previousSummary)
+		+ estimateTextTokens(customInstructions);
+	return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+}
+
 /**
- * Size of the request Pi's `compact()` is about to send, measured the same way Pi
- * measures context (the exported `estimateTokens`, a conservative chars/4).
+ * Size of the individual request(s) Pi's `compact()` is about to send.
  *
- * A session driven by a wide-window model (400k) produces a preparation that a narrower
- * summary model (272k) cannot accept at all: the provider terminates the stream and the
- * first manual `/compact` fails. Callers must not attempt that request; the estimate is
- * deliberately an under-declaration of certainty, so a missing `contextWindow` skips the
- * check instead of guessing.
+ * Pi first converts messages with `convertToLlm()` and then applies
+ * `serializeConversation()`, which truncates tool results before they enter the
+ * summarization prompt. Split-turn compaction sends history and turn-prefix
+ * summaries as separate requests, so this returns the largest individual request
+ * rather than adding their inputs together. The fixed allowance remains
+ * deliberately conservative for Pi's system prompt, tags, and instructions.
+ *
+ * A session driven by a wide-window model (400k) can produce a preparation that a
+ * narrower summary model (272k) cannot accept. Callers must not attempt that request;
+ * a missing `contextWindow` skips the check instead of guessing.
  */
 export function estimateSummarizationRequest(
 	preparation: SessionBeforeCompactEvent["preparation"],
 	model: { contextWindow?: number; maxTokens?: number },
+	customInstructions?: string,
 ): SummarizationRequestSize {
-	const conversation = [
-		...(preparation.messagesToSummarize ?? []),
-		...(preparation.turnPrefixMessages ?? []),
-	];
-	let inputTokens = SUMMARIZATION_TEMPLATE_TOKENS;
-	for (const message of conversation) inputTokens += estimateTokens(message as never);
-	if (preparation.previousSummary) {
-		inputTokens += Math.ceil(String(preparation.previousSummary).length / 4);
+	const reserveTokens = getEffectiveReserveTokens(preparation);
+	const historyMessages = preparation.messagesToSummarize ?? [];
+	const turnPrefixMessages = preparation.turnPrefixMessages ?? [];
+	const historyOutputTokens = getOutputReserveTokens(reserveTokens, model, HISTORY_OUTPUT_RESERVE_RATIO);
+	const historyRequest = estimateSummaryRequest(
+		historyMessages,
+		historyOutputTokens,
+		preparation.previousSummary,
+		customInstructions,
+	);
+
+	if (!preparation.isSplitTurn || turnPrefixMessages.length === 0) {
+		return historyRequest;
 	}
-	const outputTokens = model.maxTokens && model.maxTokens > 0
-		? Math.min(SUMMARIZATION_OUTPUT_RESERVE_TOKENS, model.maxTokens)
-		: SUMMARIZATION_OUTPUT_RESERVE_TOKENS;
-	return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
+
+	const requests = [
+		...(historyMessages.length > 0 ? [historyRequest] : []),
+		estimateSummaryRequest(
+			turnPrefixMessages,
+			getOutputReserveTokens(reserveTokens, model, TURN_PREFIX_OUTPUT_RESERVE_RATIO),
+		),
+	];
+	return requests.reduce((largest, request) =>
+		request.totalTokens > largest.totalTokens ? request : largest,
+	);
 }
 
 /** Whether the summary model can accept this request at all; unknown windows always pass. */
@@ -163,7 +218,11 @@ export async function runNativeFallbackCompaction(args: {
 		return { ok: false, reason: "same-as-current-model", modelSpec: spec };
 	}
 
-	const size = estimateSummarizationRequest(event.preparation, model as { contextWindow?: number; maxTokens?: number });
+	const size = estimateSummarizationRequest(
+		event.preparation,
+		model as { contextWindow?: number; maxTokens?: number },
+		event.customInstructions,
+	);
 	if (!fitsSummarizationRequest(size, model as { contextWindow?: number })) {
 		return {
 			ok: false,