pi-openai-toolkit 0.23.1 → 0.23.2

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

@@ -1,905 +1,912 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-import { randomUUID } from "node:crypto";
-import { isDeepStrictEqual } from "node:util";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { ProviderHeaders } from "@earendil-works/pi-ai";
-import {
-	buildSessionProjection,
-	calculateContextTokens,
-	estimateTokens,
-	type CompactionResult,
-	type ExtensionAPI,
-	type ExtensionContext,
-	type SessionBeforeCompactEvent,
-	type SessionEntry,
-} from "@earendil-works/pi-coding-agent";
-import { ContextWindowBudget, type ContextRemaining } from "./window-budget";
-import {
-	rewriteEncryptedToolOutputs,
-	rewriteWindowHeaders,
-	rewriteWindowPayload,
-} from "./window-request";
-import {
-	CONTEXT_WINDOW_COMPACTION_STRATEGY,
-	CONTEXT_WINDOW_COMPACTION_SUMMARY,
-	isContextWindowBoundary,
-	preserveSystemHead,
-	renderContextWindowMessage,
-	sendContextWindowMessage,
-} from "./messages";
-import {
-	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
-	CONTEXT_MANAGEMENT_PROTOCOL,
-	type CodexContextManagementMessageDetails,
-	type ContextWindowCompactionDetails,
-	type ContextWindowIdentity,
-	isCodexContextManagementMessageDetails,
-	isNonEmptyString,
-	isRecord,
-	isContextWindowCompactionDetails,
-	type NotesCheckpointReceipt,
-} from "./types";
-import {
-	encodeEncryptedOutputForContext,
-	isSuccessfulHistoryNotesToolResult,
-	loadHistoryNotesThreadHint,
-} from "./history-notes";
-import { rewriteContextNamespaceTools } from "./namespace-tools";
-import { hasInvalidatedCompactionContext } from "../payload-rewrite";
-
-interface StartContextWindowOptions {
-	triggerTurn: boolean;
-	signal?: AbortSignal;
-	trimPreviousWindow: boolean;
-	/** Captured with the tool activation policy, before any awaited backend work. */
-	gatewayModels?: readonly string[];
-	/** Persist an owned handoff's exact target before the marker can be queued. */
-	beforeSchedule?: (identity: ContextWindowIdentity) => void;
-}
-
-type ThreadHintLoader = (
-	ctx: ExtensionContext,
-	signal?: AbortSignal,
-	gatewayModels?: readonly string[],
-) => Promise<string | undefined>;
-
-type WindowBoundaryEntry = Extract<SessionEntry, { type: "custom_message" }> & {
-	details: CodexContextManagementMessageDetails;
-};
-
-/** Canonical input and real source anchors for one read-only manual compression. */
-export type RemoteWindowCompactionInput = {
-	messages: AgentMessage[];
-	firstKeptEntryId: string;
-	/** Only a newer compaction can own this window; pre-window checkpoints are retired. */
-	owningCompaction?: Extract<SessionEntry, { type: "compaction" }>;
-	/** Entries whose visible contributions Pi will retain alongside the new checkpoint. */
-	retainedMessages: AgentMessage[];
-	windowBoundaryIndex: number;
-};
-
-/**
- * In-process duplicate guard for one scheduled rollover. It is anchored to the
- * session that scheduled it and to the exact target window id, so it can never
- * be satisfied by an older or foreign marker. It is not checkpoint evidence:
- * only a persisted notes result unlocks the gate.
- */
-type PendingRollover = {
-	sessionId?: string;
-	targetWindowId: string;
-	/** The current request already contains this marker; never persistence proof. */
-	projected?: boolean;
-};
-
-export class CodexContextWindowManager {
-	private identity: ContextWindowIdentity | undefined;
-	private sessionId: string | undefined;
-	private restoredMarkerId: string | undefined;
-	private restoredCompactionId: string | undefined;
-	private boundary: WindowBoundaryResolution = { kind: "none" };
-	private readonly budget = new ContextWindowBudget();
-	private pendingRollover: PendingRollover | undefined;
-	private readonly projectionDiagnostics = new Set<string>();
-	private lastKnownSystemHead: AgentMessage | undefined;
-	private readonly compactionProjection = new AsyncLocalStorage<boolean>();
-
-	get isPreparingCompaction(): boolean { return this.compactionProjection.getStore() === true; }
-
-	/** Keep read-only preparation scoped across awaits without affecting other live requests. */
-	withCompactionProjection<T>(prepare: () => Promise<T>): Promise<T> {
-		return this.compactionProjection.run(true, prepare);
-	}
-	/**
-	 * Pi's getContextUsage() measures the durable transcript. Remote windows are
-	 * projected only by this extension, so remember the last provider-visible
-	 * estimate for budget decisions and get_context_remaining.
-	 */
-	private projectedContextTokens: number | undefined;
-	private readonly loadThreadHint: ThreadHintLoader;
-
-	constructor(loadThreadHint?: ThreadHintLoader) {
-		this.loadThreadHint = loadThreadHint ?? ((ctx, signal, gatewayModels) => loadHistoryNotesThreadHint(ctx, signal, gatewayModels));
-	}
-
-	reset(): void {
-		this.resetWindowState();
-		this.pendingRollover = undefined;
-		this.projectionDiagnostics.clear();
-		this.lastKnownSystemHead = undefined;
-	}
-
-	currentIdentity(): ContextWindowIdentity | undefined {
-		return this.identity ? { ...this.identity } : undefined;
-	}
-	/** Derived eligibility, never a replayed marker command. */
-	hasPendingTrim(): boolean {
-		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 {
-		this.identity = undefined;
-		this.sessionId = undefined;
-		this.restoredMarkerId = undefined;
-		this.restoredCompactionId = undefined;
-		this.boundary = { kind: "none" };
-		this.budget.reset();
-		this.projectedContextTokens = undefined;
-	}
-
-	restore(entries: readonly SessionEntry[], sessionId?: string): void {
-		// A rebuild of derived state must not drop an outstanding rollover guard;
-		// only a changed session or an observed target marker retires it below.
-		this.resetWindowState();
-		this.sessionId = sessionId;
-		for (const entry of entries) {
-			if (entry.type === "compaction") {
-				this.restoredCompactionId = entry.id;
-				continue;
-			}
-			if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
-			if (!couldBelongToSession(entry.details, sessionId)) continue;
-			if (!isCodexContextManagementMessageDetails(entry.details)) {
-				throw new Error("Malformed persisted Codex context-window message");
-			}
-			if (!matchesSession(entry.details.sessionId, sessionId)) continue;
-			const details = entry.details.contextManagement;
-			this.restoredMarkerId = entry.id;
-			if (details.kind === "window") {
-				this.identity = identityFromDetails(entry.details);
-			}
-			this.budget.restore(details.kind, details.currentWindowId);
-		}
-		this.boundary = resolveWindowBoundary(entries, sessionId);
-		this.retireSatisfiedOrStalePending(entries, sessionId);
-	}
-
-	/** Rebuild state when Pi navigates to a different session/branch. */
-	synchronize(ctx: Pick<ExtensionContext, "sessionManager">): void {
-		const entries = ctx.sessionManager.getBranch();
-		const sessionId = ctx.sessionManager.getSessionId();
-		this.retireSatisfiedOrStalePending(entries, sessionId);
-		const latestMarkerId = findLatestContextMarkerId(entries, sessionId);
-		let latestCompactionId: string | undefined;
-		for (let index = entries.length - 1; index >= 0; index--) {
-			if (entries[index]!.type === "compaction") {
-				latestCompactionId = entries[index]!.id;
-				break;
-			}
-		}
-		// Hook-provided compactions may have no success callback. The persisted
-		// branch also detects navigation before/after a commit with the same marker.
-		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);
-	}
-
-	/**
-	 * Drop a pending rollover only for durable reasons: the target window marker
-	 * is now persisted in this session, or the session changed. A queued marker
-	 * visible in an in-memory message list is not durable evidence.
-	 */
-	private retireSatisfiedOrStalePending(
-		entries: readonly SessionEntry[],
-		sessionId: string | undefined,
-	): void {
-		const pending = this.pendingRollover;
-		if (!pending) return;
-		if (pending.sessionId !== undefined && pending.sessionId !== sessionId) {
-			this.pendingRollover = undefined;
-			return;
-		}
-		if (hasPersistedWindowBoundary(entries, sessionId, pending.targetWindowId)) {
-			this.pendingRollover = undefined;
-		}
-	}
-
-	ensureInitialized(pi: ExtensionAPI, ctx: ExtensionContext, active: boolean): void {
-		if (!active) return;
-		this.synchronize(ctx);
-		if (this.identity) return;
-		const windowId = randomUUID();
-		this.sendWindowMessage(
-			pi,
-			ctx,
-			{ firstWindowId: windowId, currentWindowId: windowId, windowNumber: 0 },
-			{ triggerTurn: false, trimPreviousWindow: false },
-		);
-	}
-
-	project(
-		messages: readonly AgentMessage[],
-		mode: "off" | "local" | "remote",
-		/** Delay encoding until verified retained copies have been removed. */
-		encodeEncryptedOutputs = true,
-	): AgentMessage[] {
-		if (this.isPreparingCompaction) return this.projectCompactionContext(messages);
-		// 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]!;
-			if (
-				message.role === "custom" &&
-				message.customType === CODEX_CONTEXT_WINDOW_MESSAGE_TYPE
-			) {
-				if (!couldBelongToSession(message.details, this.sessionId)) continue;
-				if (!isCodexContextManagementMessageDetails(message.details)) {
-					throw new Error("Malformed persisted Codex context-window message");
-				}
-				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 (this.pendingRollover) this.pendingRollover.projected = queuedRollover;
-			}
-		}
-		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" ? (encodeEncryptedOutputs ? projectEncryptedToolResults(trimmed) : trimmed) : trimmed.filter(
-			(message) => message.role !== "custom" || message.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
-		);
-		this.projectedContextTokens = mode === "remote" && this.identity
-			? estimateProjectedWindowTokens(projected)
-			: undefined;
-		return projected;
-	}
-
-	/**
-	 * Strict, read-only projection. Unlike live Remote projection, an unsafe head
-	 * never falls back to the full transcript, updates identity, or records budget.
-	 */
-	projectCompactionContext(messages: readonly AgentMessage[], encodeEncryptedOutputs = false): AgentMessage[] {
-		if (this.pendingRollover || (this.boundary.kind !== "effective" && this.boundary.kind !== "superseded")) {
-			throw new Error("unsafe-compaction-window-boundary");
-		}
-		let boundaryIndex = 0;
-		if (this.boundary.kind === "effective") {
-			const boundary = this.boundary.entry;
-			boundaryIndex = messages.findIndex((message) => isContextWindowBoundary(message)
-				&& isDeepStrictEqual(message.details, boundary.details)
-				&& isDeepStrictEqual(message.content, boundary.content));
-			if (boundaryIndex < 0) throw new Error("compaction-window-boundary-missing");
-		}
-		const repair = preserveSystemHead({ messages, boundaryIndex });
-		if (!repair.head || repair.shrinkRejected) throw new Error("compaction-system-tool-head-lost");
-		return encodeEncryptedOutputs ? projectEncryptedToolResults(repair.messages) : [...repair.messages];
-	}
-
-	prepareRemoteCompaction(event: SessionBeforeCompactEvent, ctx: ExtensionContext): RemoteWindowCompactionInput {
-		this.synchronize(ctx);
-		if (this.hasPendingRollover(ctx) || (this.boundary.kind !== "effective" && this.boundary.kind !== "superseded")) {
-			throw new Error("unsafe-compaction-window-boundary");
-		}
-		const branch = ctx.sessionManager.getBranch();
-		if (!isDeepStrictEqual(event.branchEntries, branch)) throw new Error("compaction-branch-changed");
-		const projection = ctx.sessionManager.buildSessionProjection();
-		// Never manufacture source IDs or substitute a raw-history reconstruction.
-		if (!projection || !Array.isArray(projection.entries) || !Array.isArray(projection.messages)
-			|| !isDeepStrictEqual(projection.messages, projection.entries.flatMap((entry) => entry.messages))
-			|| new Set(projection.entries.map((entry) => entry.sourceEntry.id)).size !== projection.entries.length
-			|| projection.entries.some((entry) => !branch.some((raw) => raw.id === entry.sourceEntry.id && isDeepStrictEqual(raw, entry.sourceEntry)))) {
-			throw new Error("compaction-source-projection-unavailable");
-		}
-		const windowBoundaryIndex = branch.findIndex((entry) => entry.id === this.boundaryEntryId());
-		if (windowBoundaryIndex < 0) throw new Error("compaction-window-boundary-missing");
-		const latest = [...branch].reverse().find((entry) => entry.type === "compaction");
-		if (this.boundary.kind === "effective" && this.boundary.cleaned) {
-			// Details alone do not turn an arbitrary summary into Toolkit cleanup.
-			if (!latest || latest.type !== "compaction" || latest.fromHook !== true
-				|| latest.summary !== CONTEXT_WINDOW_COMPACTION_SUMMARY
-				|| !isContextWindowCompactionDetails(latest.details)
-				|| latest.details.windowId !== this.boundary.entry.details.contextManagement.currentWindowId
-				|| latest.firstKeptEntryId !== this.boundary.entry.id) throw new Error("unverified-window-cleanup");
-		}
-		const owningCompaction = this.boundary.kind === "superseded" && latest?.type === "compaction" ? latest : undefined;
-		if (this.boundary.kind === "superseded" && !owningCompaction) throw new Error("compaction-owner-missing");
-		const lowerId = owningCompaction?.id ?? this.boundary.entry.id;
-		const lowerIndex = branch.findIndex((entry) => entry.id === lowerId);
-		const requestedIndex = branch.findIndex((entry) => entry.id === event.preparation.firstKeptEntryId);
-		if (requestedIndex < 0 || lowerIndex < windowBoundaryIndex) throw new Error("unsafe-compaction-retained-start");
-		const firstKeptEntryId = requestedIndex < lowerIndex ? lowerId : event.preparation.firstKeptEntryId;
-		const keptIndex = Math.max(requestedIndex, lowerIndex);
-		const safeSources = new Set(projection.entries.filter((entry) => entry.messages.length > 0).map((entry) => entry.sourceEntry.id));
-		if (!safeSources.has(firstKeptEntryId)) throw new Error("unsafe-compaction-retained-start");
-		const retainedIds = new Set(branch.slice(keptIndex).map((entry) => entry.id));
-		return {
-			messages: this.projectCompactionContext(structuredClone(projection.messages)),
-			firstKeptEntryId,
-			owningCompaction,
-			retainedMessages: structuredClone(projection.entries.filter((entry) => retainedIds.has(entry.sourceEntry.id)
-				&& entry.sourceEntry.type !== "compaction").flatMap((entry) => entry.messages)),
-			windowBoundaryIndex,
-		};
-	}
-
-	private boundaryEntryId(): string | undefined {
-		return this.boundary.kind === "effective" || this.boundary.kind === "superseded" ? this.boundary.entry.id : undefined;
-	}
-
-	/**
-	 * Trim everything before the window boundary while keeping Pi's prompt/tool head.
-	 *
-	 * When the head cannot be preserved the trim is refused and the full message list is
-	 * sent, because a window without tools silently degrades into a chat the model can
-	 * only narrate. Each refusal is reported once per window and reason.
-	 */
-	private trimToWindow(messages: readonly AgentMessage[], boundaryIndex: number, local = false): AgentMessage[] {
-		const repair = preserveSystemHead({ messages, boundaryIndex, fallbackHead: this.lastKnownSystemHead });
-		if (repair.head) this.lastKnownSystemHead = repair.head;
-		if (repair.shrinkRejected) {
-			// Remote requests retain the existing tool-preservation fallback. A
-			// local request must never recover tools by leaking retired windows.
-			if (local) throw new Error("Cannot preserve the system/tool head in local context-window projection");
-			this.recordProjectionDiagnostic(repair.lostToolNames);
-		}
-		return [...repair.messages];
-	}
-
-	private recordProjectionDiagnostic(lostToolNames: readonly string[]): void {
-		const key = `${this.identity?.currentWindowId ?? "unknown"}|${[...lostToolNames].sort().join(",")}`;
-		this.projectionDiagnostics.add(key);
-	}
-
-	/**
-	 * Drain the pending `tool-loadout-shrink` reports. Returns one entry per window and
-	 * lost-tool set, so a caller can surface the incident without flooding the UI.
-	 */
-	takeProjectionDiagnostics(): string[] {
-		if (this.projectionDiagnostics.size === 0) return [];
-		const pending = [...this.projectionDiagnostics];
-		this.projectionDiagnostics.clear();
-		return pending;
-	}
-
-	async startNewWindow(
-		pi: ExtensionAPI,
-		ctx: ExtensionContext,
-		options: StartContextWindowOptions,
-	): Promise<boolean> {
-		this.synchronize(ctx);
-		// A same-session rollover whose target marker is not persisted yet is
-		// still in flight: report it instead of scheduling a second window.
-		if (this.hasPendingRollover(ctx)) return false;
-		if (options.signal?.aborted) throw new Error("Remote context rollover was aborted");
-		const current = this.identity;
-		const liveSessionId = ctx.sessionManager.getSessionId();
-		const currentWindowId = randomUUID();
-		const next: ContextWindowIdentity = current
-			? {
-				firstWindowId: current.firstWindowId,
-				currentWindowId,
-				previousWindowId: current.currentWindowId,
-				windowNumber: current.windowNumber + 1,
-			}
-			: { firstWindowId: currentWindowId, currentWindowId, windowNumber: 0 };
-		this.pendingRollover = { sessionId: liveSessionId, targetWindowId: currentWindowId };
-		try {
-			const checkpoint = current
-				? findLatestNotesCheckpointSinceBoundary(ctx.sessionManager.getBranch(), liveSessionId)
-				: undefined;
-			let threadHint: string | undefined;
-			if (current) {
-				try {
-					threadHint = await this.loadThreadHint(ctx, options.signal, options.gatewayModels);
-				} catch (error) {
-					if (options.signal?.aborted) throw error;
-				}
-			}
-			if (options.signal?.aborted) throw new Error("Remote context rollover was aborted");
-			options.beforeSchedule?.(next);
-			this.sendWindowMessage(pi, ctx, next, options, threadHint, checkpoint);
-			return true;
-		} catch (error) {
-			this.pendingRollover = undefined;
-			throw error;
-		}
-	}
-
-	recordBudget(
-		pi: ExtensionAPI,
-		ctx: ExtensionContext,
-		active: boolean,
-		contextReminderThresholdPercent: number,
-		contextTokens?: number,
-	): void {
-		if (!active || !this.identity || contextReminderThresholdPercent <= 0) return;
-		// Right after a rollover, Pi's usage anchor still reports the previous
-		// window's last request until the new window's first request completes.
-		// Budget decisions taken in that gap act on stale numbers: they burn the
-		// once-per-window reminder on a false alarm seconds after a successful
-		// rollover, leaving the window silent for the rest of its life.
-		if (!hasAssistantUsageSinceWindowBoundary(ctx.sessionManager.getBranch(), this.sessionId)) return;
-		const reminder = this.budget.record(
-			ctx,
-			this.identity,
-			contextTokens ?? this.projectedContextTokens,
-			contextReminderThresholdPercent,
-		);
-		if (!reminder) return;
-		sendContextWindowMessage(
-			pi,
-			reminder.content,
-			reminder.kind,
-			this.identity,
-			{ triggerTurn: reminder.kind === "fallback", sessionId: ctx.sessionManager.getSessionId() },
-		);
-	}
-
-	remaining(ctx: ExtensionContext, contextTokens?: number): ContextRemaining {
-		return this.budget.remaining(ctx, this.identity, contextTokens ?? this.projectedContextTokens);
-	}
-
-	/**
-	 * True when a notes checkpoint succeeded in the current window (after the
-	 * latest boundary). The scan always uses the live session id: a cached id can
-	 * belong to a session Pi already navigated away from, which would filter the
-	 * current window's marker and result out as foreign.
-	 */
-	hasNotesCheckpointSinceBoundary(
-		ctx: Pick<ExtensionContext, "sessionManager">,
-	): boolean {
-		return findNotesCheckpointSinceBoundary(
-			ctx.sessionManager.getBranch(),
-			ctx.sessionManager.getSessionId(),
-		);
-	}
-
-	/**
-	 * True while a rollover scheduled for the current session is awaiting its
-	 * persisted target marker. Call `synchronize()` first so a marker that has
-	 * already been persisted or a session switch retires the guard.
-	 */
-	hasPendingRollover(ctx: Pick<ExtensionContext, "sessionManager">): boolean {
-		const pending = this.pendingRollover;
-		if (!pending) return false;
-		return pending.sessionId === undefined || pending.sessionId === ctx.sessionManager.getSessionId();
-	}
-
-	/**
-	 * Whether a rollover may be scheduled from the current window.
-	 *
-	 * A window that was entered by a context switch has to do real work before it switches
-	 * again: without this guard a model can checkpoint and roll over on its very first turn,
-	 * which is how long sessions start looping between notes and new_context.
-	 */
-	canRolloverFromCurrentWindow(ctx: ExtensionContext): boolean {
-		if (!this.identity || this.identity.windowNumber === 0) return true;
-		// An exhausted window must always be able to escape: the budget fallback tells the
-		// model to checkpoint and switch, and refusing that would strand the session. An
-		// unmeasurable window keeps the guard, since nothing there is pushing for a switch.
-		const { remainingTokens } = this.remaining(ctx);
-		if (remainingTokens !== undefined && remainingTokens <= 0) return true;
-		return hasSubstantiveToolResultSinceBoundary(ctx.sessionManager.getBranch(), this.sessionId);
-	}
-
-	prepareCompaction(
-		event: SessionBeforeCompactEvent,
-	): { cancel: true } | { compaction: CompactionResult<ContextWindowCompactionDetails> } {
-		const boundary = resolveWindowBoundary(event.branchEntries, this.sessionId);
-		if (boundary.kind !== "effective" || boundary.cleaned || !boundary.entry.details.contextManagement.trimPreviousWindow) {
-			return { cancel: true };
-		}
-		// An unpersisted/cancelled proposal changes no eligibility.
-		return { compaction: this.createCompaction(event, boundary.entry) };
-	}
-
-	/**
-	 * Detach a local consumer at the durable Remote boundary, without summarizing
-	 * any Remote-managed history. Unlike a scheduled rollover trim, this needs
-	 * no pending trim and remains retryable until Pi persists the result.
-	 *
-	 * A consumed boundary is not an error. Once Pi has persisted the no-summary
-	 * boundary, `buildSessionProjection()` already starts at that marker, so
-	 * retired Remote history is outside every producer's input and the ordinary
-	 * compaction chain may summarize the remaining local window. Returning
-	 * `undefined` hands the event back to that chain; returning `{ cancel: true }`
-	 * would strand the session with no working compaction path at all.
-	 */
-	prepareDetachedCompaction(
-		event: SessionBeforeCompactEvent,
-	): { 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;
-		// A matching no-summary boundary is already the effective compaction anchor.
-		// Nothing is left to detach, and writing a second boundary for the same window
-		// would move the retained start backwards.
-		if (boundary.cleaned) return undefined;
-		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.
-		return {
-			compaction: {
-				...compaction,
-				tokensBefore: this.estimateLocalContextTokens(event.branchEntries),
-			},
-		};
-	}
-
-	private estimateLocalContextTokens(entries: readonly SessionEntry[]): number {
-		const messages = buildSessionProjection([...entries]).messages;
-		return this.project(messages, "local").reduce((total, message) => total + estimateTokens(message as never), 0);
-	}
-
-	private createCompaction(event: SessionBeforeCompactEvent, boundary: WindowBoundaryEntry): CompactionResult<ContextWindowCompactionDetails> {
-		return {
-			summary: CONTEXT_WINDOW_COMPACTION_SUMMARY,
-			firstKeptEntryId: boundary.id,
-			tokensBefore: event.preparation.tokensBefore,
-			details: {
-				protocol: CONTEXT_MANAGEMENT_PROTOCOL,
-				strategy: CONTEXT_WINDOW_COMPACTION_STRATEGY,
-				windowId: boundary.details.contextManagement.currentWindowId,
-			},
-		};
-	}
-
-	rewritePayload(payload: unknown, ctx: ExtensionContext): unknown {
-		const withMetadata = rewriteWindowPayload(payload, ctx, this.identity);
-		return rewriteContextNamespaceTools(withMetadata, { encrypted: true });
-	}
-
-	rewriteHeaders(headers: ProviderHeaders, ctx: ExtensionContext): void {
-		rewriteWindowHeaders(headers, ctx, this.identity);
-	}
-
-	private sendWindowMessage(
-		pi: ExtensionAPI,
-		ctx: ExtensionContext,
-		identity: ContextWindowIdentity,
-		options: StartContextWindowOptions,
-		threadHint?: string,
-		checkpoint?: NotesCheckpointReceipt,
-	): void {
-		sendContextWindowMessage(
-			pi,
-			renderContextWindowMessage(identity, threadHint, checkpoint),
-			"window",
-			identity,
-			{ triggerTurn: options.triggerTurn, sessionId: ctx.sessionManager.getSessionId() },
-			options.trimPreviousWindow,
-		);
-		this.identity = identity;
-		this.sessionId = ctx.sessionManager.getSessionId();
-		this.restoredMarkerId = 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 {
-		firstWindowId: context.firstWindowId,
-		currentWindowId: context.currentWindowId,
-		...(context.previousWindowId ? { previousWindowId: context.previousWindowId } : {}),
-		windowNumber: context.windowNumber,
-	};
-}
-
-const NOTES_CHECKPOINT_ACTIONS: ReadonlySet<string> = new Set(["append_to_file", "write_file"]);
-
-/** Tools that only move context around; they never count as work done in a window. */
-const CONTEXT_MANAGEMENT_TOOL_NAMES: ReadonlySet<string> = new Set([
-	"new_context",
-	"get_context_remaining",
-	"history",
-	"notes",
-]);
-
-/**
- * Whether the current window produced a tool result from anything other than the
- * context-handoff tools. Derived from persisted entries so it survives restarts.
- */
-export function hasSubstantiveToolResultSinceBoundary(
-	entries: readonly SessionEntry[],
-	sessionId?: string,
-): boolean {
-	const boundaryIndex = findLatestWindowBoundaryIndex(entries, sessionId);
-	if (boundaryIndex < 0) return true;
-	for (let index = boundaryIndex + 1; index < entries.length; index += 1) {
-		const entry = entries[index]!;
-		if (entry.type !== "message") continue;
-		const message = entry.message as unknown as { role?: string; toolName?: string };
-		if (message.role !== "toolResult" || typeof message.toolName !== "string") continue;
-		if (!CONTEXT_MANAGEMENT_TOOL_NAMES.has(message.toolName)) return true;
-	}
-	return false;
-}
-
-/**
- * Whether the branch contains a successful assistant usage after the latest
- * window boundary. Before that first usage lands, any context measurement is
- * still anchored to the previous window's last request.
- */
-export function hasAssistantUsageSinceWindowBoundary(
-	entries: readonly SessionEntry[],
-	sessionId?: string,
-): boolean {
-	const boundaryIndex = findLatestWindowBoundaryIndex(entries, sessionId);
-	if (boundaryIndex < 0) return false;
-	for (let index = boundaryIndex + 1; index < entries.length; index += 1) {
-		const entry = entries[index]!;
-		if (entry.type !== "message") continue;
-		const message = entry.message;
-		if (message.role !== "assistant") continue;
-		const candidate = message as unknown as {
-			stopReason?: string;
-			usage?: { totalTokens?: number; input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
-		};
-		if (candidate.stopReason === "aborted" || candidate.stopReason === "error") continue;
-		const usage = candidate.usage;
-		if (!usage) continue;
-		const tokens = usage.totalTokens ?? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
-		if (tokens > 0) return true;
-	}
-	return false;
-}
-
-/**
- * Return the most recent successful notes write after the latest window
- * boundary. The receipt is derived from persisted session entries so it
- * survives restarts and can be used for an explicit rollover handoff.
- */
-export function findLatestNotesCheckpointSinceBoundary(
-	entries: readonly SessionEntry[],
-	sessionId?: string,
-	afterEntryId?: string,
-): NotesCheckpointReceipt | undefined {
-	const windowBoundaryIndex = findLatestWindowBoundaryIndex(entries, sessionId);
-	const afterIndex = afterEntryId === undefined ? -1 : entries.findIndex((entry) => entry.id === afterEntryId);
-	if (windowBoundaryIndex < 0 || (afterEntryId !== undefined && afterIndex < 0)) return undefined;
-	const boundaryIndex = Math.max(windowBoundaryIndex, afterIndex);
-	const checkpointCalls = new Map<string, NotesCheckpointReceipt>();
-	let latest: NotesCheckpointReceipt | undefined;
-	for (let index = boundaryIndex + 1; index < entries.length; index += 1) {
-		const entry = entries[index]!;
-		if (entry.type !== "message") continue;
-		const message = entry.message;
-		if (message.role === "assistant") {
-			const parts = Array.isArray(message.content) ? message.content : [];
-			for (const part of parts) {
-				if (!isRecord(part) || part.type !== "toolCall" || part.name !== "notes") continue;
-				const args = isRecord(part.arguments) ? part.arguments : undefined;
-				const action = typeof args?.action === "string" ? args.action : "";
-				const path = isNonEmptyString(args?.path) ? args.path : undefined;
-				if (isNonEmptyString(part.id) && path !== undefined && NOTES_CHECKPOINT_ACTIONS.has(action)) {
-					checkpointCalls.set(part.id, { path, toolCallId: part.id });
-				}
-			}
-			continue;
-		}
-		if (message.role !== "toolResult" || message.toolName !== "notes") continue;
-		const receipt = checkpointCalls.get(message.toolCallId);
-		if (!receipt) continue;
-		checkpointCalls.delete(message.toolCallId);
-		if (message.isError !== false || !isSuccessfulHistoryNotesToolResult(message.details)) continue;
-		latest = receipt;
-	}
-	return latest;
-}
-
-/**
- * Whether the branch contains a successful notes append/write result after the
- * latest window boundary. Reads and failed writes never count as checkpoints.
- */
-export function findNotesCheckpointSinceBoundary(
-	entries: readonly SessionEntry[],
-	sessionId?: string,
-): boolean {
-	return findLatestNotesCheckpointSinceBoundary(entries, sessionId) !== undefined;
-}
-
-function findLatestWindowBoundaryIndex(
-	entries: readonly SessionEntry[],
-	sessionId?: string,
-): number {
-	for (let index = entries.length - 1; index >= 0; index -= 1) {
-		const entry = entries[index]!;
-		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
-		if (!couldBelongToSession(entry.details, sessionId)) continue;
-		if (!isCodexContextManagementMessageDetails(entry.details)) {
-			throw new Error("Malformed persisted Codex context-window message");
-		}
-		if (!matchesSession(entry.details.sessionId, sessionId)) continue;
-		if (entry.details.contextManagement.kind === "window") return index;
-	}
-	return -1;
-}
-
-export function findLatestWindowBoundaryEntry(
-	entries: readonly SessionEntry[],
-	sessionId?: string,
-): WindowBoundaryEntry | undefined {
-	for (let index = entries.length - 1; index >= 0; index -= 1) {
-		const entry = entries[index]!;
-		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
-		if (!couldBelongToSession(entry.details, sessionId)) continue;
-		if (!isCodexContextManagementMessageDetails(entry.details)) {
-			throw new Error("Malformed persisted Codex context-window message");
-		}
-		if (!matchesSession(entry.details.sessionId, sessionId)) continue;
-		if (entry.details.contextManagement.kind === "window") return entry as WindowBoundaryEntry;
-	}
-	return undefined;
-}
-
-/**
- * Whether this exact window boundary is already persisted for the session.
- * Only durable entries count; a queued/visible marker does not.
- */
-function hasPersistedWindowBoundary(
-	entries: readonly SessionEntry[],
-	sessionId: string | undefined,
-	windowId: string,
-): boolean {
-	for (const entry of entries) {
-		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
-		if (!couldBelongToSession(entry.details, sessionId)) continue;
-		if (!isCodexContextManagementMessageDetails(entry.details)) continue;
-		if (!matchesSession(entry.details.sessionId, sessionId)) continue;
-		const details = entry.details.contextManagement;
-		if (details.kind === "window" && details.currentWindowId === windowId) return true;
-	}
-	return false;
-}
-
-function findLatestContextMarkerId(
-	entries: readonly SessionEntry[],
-	sessionId?: string,
-): string | undefined {
-	for (let index = entries.length - 1; index >= 0; index -= 1) {
-		const entry = entries[index]!;
-		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
-		if (!couldBelongToSession(entry.details, sessionId)) continue;
-		if (!isCodexContextManagementMessageDetails(entry.details)) {
-			throw new Error("Malformed persisted Codex context-window message");
-		}
-		if (matchesSession(entry.details.sessionId, sessionId)) return entry.id;
-	}
-	return undefined;
-}
-
-function couldBelongToSession(details: unknown, sessionId: string | undefined): boolean {
-	if (sessionId === undefined || !isRecord(details)) return true;
-	const markerSessionId = details.sessionId;
-	return !isNonEmptyString(markerSessionId) || markerSessionId === sessionId;
-}
-
-function matchesSession(markerSessionId: string | undefined, sessionId: string | undefined): boolean {
-	return sessionId === undefined || markerSessionId === sessionId;
-}
-
-function estimateProjectedWindowTokens(messages: readonly AgentMessage[]): number {
-	let lastUsageIndex = -1;
-	let usageTokens = 0;
-	for (let index = messages.length - 1; index >= 0; index -= 1) {
-		const message = messages[index]!;
-		if (message.role !== "assistant" || message.stopReason === "aborted" || message.stopReason === "error" || !message.usage) continue;
-		const tokens = calculateContextTokens(message.usage);
-		if (tokens <= 0) continue;
-		lastUsageIndex = index;
-		usageTokens = tokens;
-		break;
-	}
-	if (lastUsageIndex < 0) return messages.reduce((total, message) => total + estimateProjectedMessageTokens(message), 0);
-	return usageTokens + messages
-		.slice(lastUsageIndex + 1)
-		.reduce((total, message) => total + estimateProjectedMessageTokens(message), 0);
-}
-
-function estimateProjectedMessageTokens(message: AgentMessage): number {
-	// A synthetic custom marker may be represented without content in a test or
-	// by an older host. It contributes no measurable text; it must not make the
-	// context hook fail closed merely because the diagnostic estimate is missing.
-	if (
-		!("content" in message) ||
-		(typeof message.content !== "string" && !Array.isArray(message.content))
-	) return 0;
-	return estimateTokens(message);
-}
-
-function projectEncryptedToolResults(messages: readonly AgentMessage[]): AgentMessage[] {
-	let changed = false;
-	const projected = messages.map((message) => {
-		if (message.role !== "toolResult" || !isRecord(message.details)) return message;
-		const historyNotes = message.details.codexHistoryNotes;
-		if (!isRecord(historyNotes) || typeof historyNotes.encrypted_output !== "string") return message;
-		changed = true;
-		return {
-			...message,
-			content: [
-				{ type: "text" as const, text: encodeEncryptedOutputForContext(historyNotes.encrypted_output) },
-				...message.content.filter((item) => item.type === "image"),
-			],
-		};
-	});
-	return changed ? projected : [...messages];
-}
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ProviderHeaders } from "@earendil-works/pi-ai";
+import {
+	buildSessionProjection,
+	calculateContextTokens,
+	estimateTokens,
+	type CompactionResult,
+	type ExtensionAPI,
+	type ExtensionContext,
+	type SessionBeforeCompactEvent,
+	type SessionEntry,
+	type ProjectedSessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { ContextWindowBudget, type ContextRemaining } from "./window-budget";
+import {
+	rewriteEncryptedToolOutputs,
+	rewriteWindowHeaders,
+	rewriteWindowPayload,
+} from "./window-request";
+import {
+	CONTEXT_WINDOW_COMPACTION_STRATEGY,
+	CONTEXT_WINDOW_COMPACTION_SUMMARY,
+	isContextWindowBoundary,
+	preserveSystemHead,
+	renderContextWindowMessage,
+	sendContextWindowMessage,
+} from "./messages";
+import {
+	CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+	CONTEXT_MANAGEMENT_PROTOCOL,
+	type CodexContextManagementMessageDetails,
+	type ContextWindowCompactionDetails,
+	type ContextWindowIdentity,
+	isCodexContextManagementMessageDetails,
+	isNonEmptyString,
+	isRecord,
+	isContextWindowCompactionDetails,
+	type NotesCheckpointReceipt,
+} from "./types";
+import {
+	encodeEncryptedOutputForContext,
+	isSuccessfulHistoryNotesToolResult,
+	loadHistoryNotesThreadHint,
+} from "./history-notes";
+import { rewriteContextNamespaceTools } from "./namespace-tools";
+import { hasInvalidatedCompactionContext } from "../payload-rewrite";
+
+interface StartContextWindowOptions {
+	triggerTurn: boolean;
+	signal?: AbortSignal;
+	trimPreviousWindow: boolean;
+	/** Captured with the tool activation policy, before any awaited backend work. */
+	gatewayModels?: readonly string[];
+	/** Persist an owned handoff's exact target before the marker can be queued. */
+	beforeSchedule?: (identity: ContextWindowIdentity) => void;
+}
+
+type ThreadHintLoader = (
+	ctx: ExtensionContext,
+	signal?: AbortSignal,
+	gatewayModels?: readonly string[],
+) => Promise<string | undefined>;
+
+type WindowBoundaryEntry = Extract<SessionEntry, { type: "custom_message" }> & {
+	details: CodexContextManagementMessageDetails;
+};
+
+/** Canonical input and real source anchors for one read-only manual compression. */
+export type RemoteWindowCompactionInput = {
+	messages: AgentMessage[];
+	/** Verified canonical source contributions within this window, including edits. */
+	entries: ProjectedSessionEntry[];
+	firstKeptEntryId: string;
+	/** Only a newer compaction can own this window; pre-window checkpoints are retired. */
+	owningCompaction?: Extract<SessionEntry, { type: "compaction" }>;
+	/** Entries whose visible contributions Pi will retain alongside the new checkpoint. */
+	retainedMessages: AgentMessage[];
+	windowBoundaryIndex: number;
+};
+
+/**
+ * In-process duplicate guard for one scheduled rollover. It is anchored to the
+ * session that scheduled it and to the exact target window id, so it can never
+ * be satisfied by an older or foreign marker. It is not checkpoint evidence:
+ * only a persisted notes result unlocks the gate.
+ */
+type PendingRollover = {
+	sessionId?: string;
+	targetWindowId: string;
+	/** The current request already contains this marker; never persistence proof. */
+	projected?: boolean;
+};
+
+export class CodexContextWindowManager {
+	private identity: ContextWindowIdentity | undefined;
+	private sessionId: string | undefined;
+	private restoredMarkerId: string | undefined;
+	private restoredCompactionId: string | undefined;
+	private boundary: WindowBoundaryResolution = { kind: "none" };
+	private readonly budget = new ContextWindowBudget();
+	private pendingRollover: PendingRollover | undefined;
+	private readonly projectionDiagnostics = new Set<string>();
+	private lastKnownSystemHead: AgentMessage | undefined;
+	private readonly compactionProjection = new AsyncLocalStorage<boolean>();
+
+	get isPreparingCompaction(): boolean { return this.compactionProjection.getStore() === true; }
+
+	/** Keep read-only preparation scoped across awaits without affecting other live requests. */
+	withCompactionProjection<T>(prepare: () => Promise<T>): Promise<T> {
+		return this.compactionProjection.run(true, prepare);
+	}
+	/**
+	 * Pi's getContextUsage() measures the durable transcript. Remote windows are
+	 * projected only by this extension, so remember the last provider-visible
+	 * estimate for budget decisions and get_context_remaining.
+	 */
+	private projectedContextTokens: number | undefined;
+	private readonly loadThreadHint: ThreadHintLoader;
+
+	constructor(loadThreadHint?: ThreadHintLoader) {
+		this.loadThreadHint = loadThreadHint ?? ((ctx, signal, gatewayModels) => loadHistoryNotesThreadHint(ctx, signal, gatewayModels));
+	}
+
+	reset(): void {
+		this.resetWindowState();
+		this.pendingRollover = undefined;
+		this.projectionDiagnostics.clear();
+		this.lastKnownSystemHead = undefined;
+	}
+
+	currentIdentity(): ContextWindowIdentity | undefined {
+		return this.identity ? { ...this.identity } : undefined;
+	}
+	/** Derived eligibility, never a replayed marker command. */
+	hasPendingTrim(): boolean {
+		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 {
+		this.identity = undefined;
+		this.sessionId = undefined;
+		this.restoredMarkerId = undefined;
+		this.restoredCompactionId = undefined;
+		this.boundary = { kind: "none" };
+		this.budget.reset();
+		this.projectedContextTokens = undefined;
+	}
+
+	restore(entries: readonly SessionEntry[], sessionId?: string): void {
+		// A rebuild of derived state must not drop an outstanding rollover guard;
+		// only a changed session or an observed target marker retires it below.
+		this.resetWindowState();
+		this.sessionId = sessionId;
+		for (const entry of entries) {
+			if (entry.type === "compaction") {
+				this.restoredCompactionId = entry.id;
+				continue;
+			}
+			if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
+			if (!couldBelongToSession(entry.details, sessionId)) continue;
+			if (!isCodexContextManagementMessageDetails(entry.details)) {
+				throw new Error("Malformed persisted Codex context-window message");
+			}
+			if (!matchesSession(entry.details.sessionId, sessionId)) continue;
+			const details = entry.details.contextManagement;
+			this.restoredMarkerId = entry.id;
+			if (details.kind === "window") {
+				this.identity = identityFromDetails(entry.details);
+			}
+			this.budget.restore(details.kind, details.currentWindowId);
+		}
+		this.boundary = resolveWindowBoundary(entries, sessionId);
+		this.retireSatisfiedOrStalePending(entries, sessionId);
+	}
+
+	/** Rebuild state when Pi navigates to a different session/branch. */
+	synchronize(ctx: Pick<ExtensionContext, "sessionManager">): void {
+		const entries = ctx.sessionManager.getBranch();
+		const sessionId = ctx.sessionManager.getSessionId();
+		this.retireSatisfiedOrStalePending(entries, sessionId);
+		const latestMarkerId = findLatestContextMarkerId(entries, sessionId);
+		let latestCompactionId: string | undefined;
+		for (let index = entries.length - 1; index >= 0; index--) {
+			if (entries[index]!.type === "compaction") {
+				latestCompactionId = entries[index]!.id;
+				break;
+			}
+		}
+		// Hook-provided compactions may have no success callback. The persisted
+		// branch also detects navigation before/after a commit with the same marker.
+		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);
+	}
+
+	/**
+	 * Drop a pending rollover only for durable reasons: the target window marker
+	 * is now persisted in this session, or the session changed. A queued marker
+	 * visible in an in-memory message list is not durable evidence.
+	 */
+	private retireSatisfiedOrStalePending(
+		entries: readonly SessionEntry[],
+		sessionId: string | undefined,
+	): void {
+		const pending = this.pendingRollover;
+		if (!pending) return;
+		if (pending.sessionId !== undefined && pending.sessionId !== sessionId) {
+			this.pendingRollover = undefined;
+			return;
+		}
+		if (hasPersistedWindowBoundary(entries, sessionId, pending.targetWindowId)) {
+			this.pendingRollover = undefined;
+		}
+	}
+
+	ensureInitialized(pi: ExtensionAPI, ctx: ExtensionContext, active: boolean): void {
+		if (!active) return;
+		this.synchronize(ctx);
+		if (this.identity) return;
+		const windowId = randomUUID();
+		this.sendWindowMessage(
+			pi,
+			ctx,
+			{ firstWindowId: windowId, currentWindowId: windowId, windowNumber: 0 },
+			{ triggerTurn: false, trimPreviousWindow: false },
+		);
+	}
+
+	project(
+		messages: readonly AgentMessage[],
+		mode: "off" | "local" | "remote",
+		/** Delay encoding until verified retained copies have been removed. */
+		encodeEncryptedOutputs = true,
+	): AgentMessage[] {
+		if (this.isPreparingCompaction) return this.projectCompactionContext(messages);
+		// 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]!;
+			if (
+				message.role === "custom" &&
+				message.customType === CODEX_CONTEXT_WINDOW_MESSAGE_TYPE
+			) {
+				if (!couldBelongToSession(message.details, this.sessionId)) continue;
+				if (!isCodexContextManagementMessageDetails(message.details)) {
+					throw new Error("Malformed persisted Codex context-window message");
+				}
+				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 (this.pendingRollover) this.pendingRollover.projected = queuedRollover;
+			}
+		}
+		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" ? (encodeEncryptedOutputs ? projectEncryptedToolResults(trimmed) : trimmed) : trimmed.filter(
+			(message) => message.role !== "custom" || message.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE,
+		);
+		this.projectedContextTokens = mode === "remote" && this.identity
+			? estimateProjectedWindowTokens(projected)
+			: undefined;
+		return projected;
+	}
+
+	/**
+	 * Strict, read-only projection. Unlike live Remote projection, an unsafe head
+	 * never falls back to the full transcript, updates identity, or records budget.
+	 */
+	projectCompactionContext(messages: readonly AgentMessage[], encodeEncryptedOutputs = false): AgentMessage[] {
+		if (this.pendingRollover || (this.boundary.kind !== "effective" && this.boundary.kind !== "superseded")) {
+			throw new Error("unsafe-compaction-window-boundary");
+		}
+		let boundaryIndex = 0;
+		if (this.boundary.kind === "effective") {
+			const boundary = this.boundary.entry;
+			boundaryIndex = messages.findIndex((message) => isContextWindowBoundary(message)
+				&& isDeepStrictEqual(message.details, boundary.details)
+				&& isDeepStrictEqual(message.content, boundary.content));
+			if (boundaryIndex < 0) throw new Error("compaction-window-boundary-missing");
+		}
+		const repair = preserveSystemHead({ messages, boundaryIndex });
+		if (!repair.head || repair.shrinkRejected) throw new Error("compaction-system-tool-head-lost");
+		return encodeEncryptedOutputs ? projectEncryptedToolResults(repair.messages) : [...repair.messages];
+	}
+
+	prepareRemoteCompaction(event: SessionBeforeCompactEvent, ctx: ExtensionContext): RemoteWindowCompactionInput {
+		this.synchronize(ctx);
+		if (this.hasPendingRollover(ctx) || (this.boundary.kind !== "effective" && this.boundary.kind !== "superseded")) {
+			throw new Error("unsafe-compaction-window-boundary");
+		}
+		const branch = ctx.sessionManager.getBranch();
+		if (!isDeepStrictEqual(event.branchEntries, branch)) throw new Error("compaction-branch-changed");
+		const projection = ctx.sessionManager.buildSessionProjection();
+		// Never manufacture source IDs or substitute a raw-history reconstruction.
+		if (!projection || !Array.isArray(projection.entries) || !Array.isArray(projection.messages)
+			|| !isDeepStrictEqual(projection.messages, projection.entries.flatMap((entry) => entry.messages))
+			|| new Set(projection.entries.map((entry) => entry.sourceEntry.id)).size !== projection.entries.length
+			|| projection.entries.some((entry) => !branch.some((raw) => raw.id === entry.sourceEntry.id && isDeepStrictEqual(raw, entry.sourceEntry)))) {
+			throw new Error("compaction-source-projection-unavailable");
+		}
+		const windowBoundaryIndex = branch.findIndex((entry) => entry.id === this.boundaryEntryId());
+		if (windowBoundaryIndex < 0) throw new Error("compaction-window-boundary-missing");
+		const latest = [...branch].reverse().find((entry) => entry.type === "compaction");
+		if (latest?.type === "compaction" && branch.findIndex((entry) => entry.id === latest.id) > windowBoundaryIndex
+			&& (isContextWindowCompactionDetails(latest.details) || latest.summary === CONTEXT_WINDOW_COMPACTION_SUMMARY)) {
+			// A malformed cleanup cannot masquerade as a new native/text owner.
+			// Details alone do not turn an arbitrary summary into Toolkit cleanup.
+			if (!latest || latest.type !== "compaction" || latest.fromHook !== true
+				|| latest.summary !== CONTEXT_WINDOW_COMPACTION_SUMMARY
+				|| !isContextWindowCompactionDetails(latest.details)
+				|| latest.details.windowId !== this.boundary.entry.details.contextManagement.currentWindowId
+				|| latest.firstKeptEntryId !== this.boundary.entry.id) throw new Error("unverified-window-cleanup");
+		}
+		const owningCompaction = this.boundary.kind === "superseded" && latest?.type === "compaction" ? latest : undefined;
+		if (this.boundary.kind === "superseded" && !owningCompaction) throw new Error("compaction-owner-missing");
+		const lowerId = owningCompaction?.id ?? this.boundary.entry.id;
+		const lowerIndex = branch.findIndex((entry) => entry.id === lowerId);
+		const requestedIndex = branch.findIndex((entry) => entry.id === event.preparation.firstKeptEntryId);
+		if (requestedIndex < 0 || lowerIndex < windowBoundaryIndex) throw new Error("unsafe-compaction-retained-start");
+		const firstKeptEntryId = requestedIndex < lowerIndex ? lowerId : event.preparation.firstKeptEntryId;
+		const keptIndex = Math.max(requestedIndex, lowerIndex);
+		const safeSources = new Set(projection.entries.filter((entry) => entry.messages.length > 0).map((entry) => entry.sourceEntry.id));
+		if (!safeSources.has(firstKeptEntryId)) throw new Error("unsafe-compaction-retained-start");
+		const retainedIds = new Set(branch.slice(keptIndex).map((entry) => entry.id));
+		return {
+			messages: this.projectCompactionContext(structuredClone(projection.messages)),
+			entries: structuredClone(projection.entries.filter((entry) =>
+				branch.findIndex((raw) => raw.id === entry.sourceEntry.id) >= windowBoundaryIndex)),
+			firstKeptEntryId,
+			owningCompaction,
+			retainedMessages: structuredClone(projection.entries.filter((entry) => retainedIds.has(entry.sourceEntry.id)
+				&& entry.sourceEntry.type !== "compaction").flatMap((entry) => entry.messages)),
+			windowBoundaryIndex,
+		};
+	}
+
+	private boundaryEntryId(): string | undefined {
+		return this.boundary.kind === "effective" || this.boundary.kind === "superseded" ? this.boundary.entry.id : undefined;
+	}
+
+	/**
+	 * Trim everything before the window boundary while keeping Pi's prompt/tool head.
+	 *
+	 * When the head cannot be preserved the trim is refused and the full message list is
+	 * sent, because a window without tools silently degrades into a chat the model can
+	 * only narrate. Each refusal is reported once per window and reason.
+	 */
+	private trimToWindow(messages: readonly AgentMessage[], boundaryIndex: number, local = false): AgentMessage[] {
+		const repair = preserveSystemHead({ messages, boundaryIndex, fallbackHead: this.lastKnownSystemHead });
+		if (repair.head) this.lastKnownSystemHead = repair.head;
+		if (repair.shrinkRejected) {
+			// Remote requests retain the existing tool-preservation fallback. A
+			// local request must never recover tools by leaking retired windows.
+			if (local) throw new Error("Cannot preserve the system/tool head in local context-window projection");
+			this.recordProjectionDiagnostic(repair.lostToolNames);
+		}
+		return [...repair.messages];
+	}
+
+	private recordProjectionDiagnostic(lostToolNames: readonly string[]): void {
+		const key = `${this.identity?.currentWindowId ?? "unknown"}|${[...lostToolNames].sort().join(",")}`;
+		this.projectionDiagnostics.add(key);
+	}
+
+	/**
+	 * Drain the pending `tool-loadout-shrink` reports. Returns one entry per window and
+	 * lost-tool set, so a caller can surface the incident without flooding the UI.
+	 */
+	takeProjectionDiagnostics(): string[] {
+		if (this.projectionDiagnostics.size === 0) return [];
+		const pending = [...this.projectionDiagnostics];
+		this.projectionDiagnostics.clear();
+		return pending;
+	}
+
+	async startNewWindow(
+		pi: ExtensionAPI,
+		ctx: ExtensionContext,
+		options: StartContextWindowOptions,
+	): Promise<boolean> {
+		this.synchronize(ctx);
+		// A same-session rollover whose target marker is not persisted yet is
+		// still in flight: report it instead of scheduling a second window.
+		if (this.hasPendingRollover(ctx)) return false;
+		if (options.signal?.aborted) throw new Error("Remote context rollover was aborted");
+		const current = this.identity;
+		const liveSessionId = ctx.sessionManager.getSessionId();
+		const currentWindowId = randomUUID();
+		const next: ContextWindowIdentity = current
+			? {
+				firstWindowId: current.firstWindowId,
+				currentWindowId,
+				previousWindowId: current.currentWindowId,
+				windowNumber: current.windowNumber + 1,
+			}
+			: { firstWindowId: currentWindowId, currentWindowId, windowNumber: 0 };
+		this.pendingRollover = { sessionId: liveSessionId, targetWindowId: currentWindowId };
+		try {
+			const checkpoint = current
+				? findLatestNotesCheckpointSinceBoundary(ctx.sessionManager.getBranch(), liveSessionId)
+				: undefined;
+			let threadHint: string | undefined;
+			if (current) {
+				try {
+					threadHint = await this.loadThreadHint(ctx, options.signal, options.gatewayModels);
+				} catch (error) {
+					if (options.signal?.aborted) throw error;
+				}
+			}
+			if (options.signal?.aborted) throw new Error("Remote context rollover was aborted");
+			options.beforeSchedule?.(next);
+			this.sendWindowMessage(pi, ctx, next, options, threadHint, checkpoint);
+			return true;
+		} catch (error) {
+			this.pendingRollover = undefined;
+			throw error;
+		}
+	}
+
+	recordBudget(
+		pi: ExtensionAPI,
+		ctx: ExtensionContext,
+		active: boolean,
+		contextReminderThresholdPercent: number,
+		contextTokens?: number,
+	): void {
+		if (!active || !this.identity || contextReminderThresholdPercent <= 0) return;
+		// Right after a rollover, Pi's usage anchor still reports the previous
+		// window's last request until the new window's first request completes.
+		// Budget decisions taken in that gap act on stale numbers: they burn the
+		// once-per-window reminder on a false alarm seconds after a successful
+		// rollover, leaving the window silent for the rest of its life.
+		if (!hasAssistantUsageSinceWindowBoundary(ctx.sessionManager.getBranch(), this.sessionId)) return;
+		const reminder = this.budget.record(
+			ctx,
+			this.identity,
+			contextTokens ?? this.projectedContextTokens,
+			contextReminderThresholdPercent,
+		);
+		if (!reminder) return;
+		sendContextWindowMessage(
+			pi,
+			reminder.content,
+			reminder.kind,
+			this.identity,
+			{ triggerTurn: reminder.kind === "fallback", sessionId: ctx.sessionManager.getSessionId() },
+		);
+	}
+
+	remaining(ctx: ExtensionContext, contextTokens?: number): ContextRemaining {
+		return this.budget.remaining(ctx, this.identity, contextTokens ?? this.projectedContextTokens);
+	}
+
+	/**
+	 * True when a notes checkpoint succeeded in the current window (after the
+	 * latest boundary). The scan always uses the live session id: a cached id can
+	 * belong to a session Pi already navigated away from, which would filter the
+	 * current window's marker and result out as foreign.
+	 */
+	hasNotesCheckpointSinceBoundary(
+		ctx: Pick<ExtensionContext, "sessionManager">,
+	): boolean {
+		return findNotesCheckpointSinceBoundary(
+			ctx.sessionManager.getBranch(),
+			ctx.sessionManager.getSessionId(),
+		);
+	}
+
+	/**
+	 * True while a rollover scheduled for the current session is awaiting its
+	 * persisted target marker. Call `synchronize()` first so a marker that has
+	 * already been persisted or a session switch retires the guard.
+	 */
+	hasPendingRollover(ctx: Pick<ExtensionContext, "sessionManager">): boolean {
+		const pending = this.pendingRollover;
+		if (!pending) return false;
+		return pending.sessionId === undefined || pending.sessionId === ctx.sessionManager.getSessionId();
+	}
+
+	/**
+	 * Whether a rollover may be scheduled from the current window.
+	 *
+	 * A window that was entered by a context switch has to do real work before it switches
+	 * again: without this guard a model can checkpoint and roll over on its very first turn,
+	 * which is how long sessions start looping between notes and new_context.
+	 */
+	canRolloverFromCurrentWindow(ctx: ExtensionContext): boolean {
+		if (!this.identity || this.identity.windowNumber === 0) return true;
+		// An exhausted window must always be able to escape: the budget fallback tells the
+		// model to checkpoint and switch, and refusing that would strand the session. An
+		// unmeasurable window keeps the guard, since nothing there is pushing for a switch.
+		const { remainingTokens } = this.remaining(ctx);
+		if (remainingTokens !== undefined && remainingTokens <= 0) return true;
+		return hasSubstantiveToolResultSinceBoundary(ctx.sessionManager.getBranch(), this.sessionId);
+	}
+
+	prepareCompaction(
+		event: SessionBeforeCompactEvent,
+	): { cancel: true } | { compaction: CompactionResult<ContextWindowCompactionDetails> } {
+		const boundary = resolveWindowBoundary(event.branchEntries, this.sessionId);
+		if (boundary.kind !== "effective" || boundary.cleaned || !boundary.entry.details.contextManagement.trimPreviousWindow) {
+			return { cancel: true };
+		}
+		// An unpersisted/cancelled proposal changes no eligibility.
+		return { compaction: this.createCompaction(event, boundary.entry) };
+	}
+
+	/**
+	 * Detach a local consumer at the durable Remote boundary, without summarizing
+	 * any Remote-managed history. Unlike a scheduled rollover trim, this needs
+	 * no pending trim and remains retryable until Pi persists the result.
+	 *
+	 * A consumed boundary is not an error. Once Pi has persisted the no-summary
+	 * boundary, `buildSessionProjection()` already starts at that marker, so
+	 * retired Remote history is outside every producer's input and the ordinary
+	 * compaction chain may summarize the remaining local window. Returning
+	 * `undefined` hands the event back to that chain; returning `{ cancel: true }`
+	 * would strand the session with no working compaction path at all.
+	 */
+	prepareDetachedCompaction(
+		event: SessionBeforeCompactEvent,
+	): { 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;
+		// A matching no-summary boundary is already the effective compaction anchor.
+		// Nothing is left to detach, and writing a second boundary for the same window
+		// would move the retained start backwards.
+		if (boundary.cleaned) return undefined;
+		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.
+		return {
+			compaction: {
+				...compaction,
+				tokensBefore: this.estimateLocalContextTokens(event.branchEntries),
+			},
+		};
+	}
+
+	private estimateLocalContextTokens(entries: readonly SessionEntry[]): number {
+		const messages = buildSessionProjection([...entries]).messages;
+		return this.project(messages, "local").reduce((total, message) => total + estimateTokens(message as never), 0);
+	}
+
+	private createCompaction(event: SessionBeforeCompactEvent, boundary: WindowBoundaryEntry): CompactionResult<ContextWindowCompactionDetails> {
+		return {
+			summary: CONTEXT_WINDOW_COMPACTION_SUMMARY,
+			firstKeptEntryId: boundary.id,
+			tokensBefore: event.preparation.tokensBefore,
+			details: {
+				protocol: CONTEXT_MANAGEMENT_PROTOCOL,
+				strategy: CONTEXT_WINDOW_COMPACTION_STRATEGY,
+				windowId: boundary.details.contextManagement.currentWindowId,
+			},
+		};
+	}
+
+	rewritePayload(payload: unknown, ctx: ExtensionContext): unknown {
+		const withMetadata = rewriteWindowPayload(payload, ctx, this.identity);
+		return rewriteContextNamespaceTools(withMetadata, { encrypted: true });
+	}
+
+	rewriteHeaders(headers: ProviderHeaders, ctx: ExtensionContext): void {
+		rewriteWindowHeaders(headers, ctx, this.identity);
+	}
+
+	private sendWindowMessage(
+		pi: ExtensionAPI,
+		ctx: ExtensionContext,
+		identity: ContextWindowIdentity,
+		options: StartContextWindowOptions,
+		threadHint?: string,
+		checkpoint?: NotesCheckpointReceipt,
+	): void {
+		sendContextWindowMessage(
+			pi,
+			renderContextWindowMessage(identity, threadHint, checkpoint),
+			"window",
+			identity,
+			{ triggerTurn: options.triggerTurn, sessionId: ctx.sessionManager.getSessionId() },
+			options.trimPreviousWindow,
+		);
+		this.identity = identity;
+		this.sessionId = ctx.sessionManager.getSessionId();
+		this.restoredMarkerId = 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 {
+		firstWindowId: context.firstWindowId,
+		currentWindowId: context.currentWindowId,
+		...(context.previousWindowId ? { previousWindowId: context.previousWindowId } : {}),
+		windowNumber: context.windowNumber,
+	};
+}
+
+const NOTES_CHECKPOINT_ACTIONS: ReadonlySet<string> = new Set(["append_to_file", "write_file"]);
+
+/** Tools that only move context around; they never count as work done in a window. */
+const CONTEXT_MANAGEMENT_TOOL_NAMES: ReadonlySet<string> = new Set([
+	"new_context",
+	"get_context_remaining",
+	"history",
+	"notes",
+]);
+
+/**
+ * Whether the current window produced a tool result from anything other than the
+ * context-handoff tools. Derived from persisted entries so it survives restarts.
+ */
+export function hasSubstantiveToolResultSinceBoundary(
+	entries: readonly SessionEntry[],
+	sessionId?: string,
+): boolean {
+	const boundaryIndex = findLatestWindowBoundaryIndex(entries, sessionId);
+	if (boundaryIndex < 0) return true;
+	for (let index = boundaryIndex + 1; index < entries.length; index += 1) {
+		const entry = entries[index]!;
+		if (entry.type !== "message") continue;
+		const message = entry.message as unknown as { role?: string; toolName?: string };
+		if (message.role !== "toolResult" || typeof message.toolName !== "string") continue;
+		if (!CONTEXT_MANAGEMENT_TOOL_NAMES.has(message.toolName)) return true;
+	}
+	return false;
+}
+
+/**
+ * Whether the branch contains a successful assistant usage after the latest
+ * window boundary. Before that first usage lands, any context measurement is
+ * still anchored to the previous window's last request.
+ */
+export function hasAssistantUsageSinceWindowBoundary(
+	entries: readonly SessionEntry[],
+	sessionId?: string,
+): boolean {
+	const boundaryIndex = findLatestWindowBoundaryIndex(entries, sessionId);
+	if (boundaryIndex < 0) return false;
+	for (let index = boundaryIndex + 1; index < entries.length; index += 1) {
+		const entry = entries[index]!;
+		if (entry.type !== "message") continue;
+		const message = entry.message;
+		if (message.role !== "assistant") continue;
+		const candidate = message as unknown as {
+			stopReason?: string;
+			usage?: { totalTokens?: number; input?: number; output?: number; cacheRead?: number; cacheWrite?: number };
+		};
+		if (candidate.stopReason === "aborted" || candidate.stopReason === "error") continue;
+		const usage = candidate.usage;
+		if (!usage) continue;
+		const tokens = usage.totalTokens ?? (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+		if (tokens > 0) return true;
+	}
+	return false;
+}
+
+/**
+ * Return the most recent successful notes write after the latest window
+ * boundary. The receipt is derived from persisted session entries so it
+ * survives restarts and can be used for an explicit rollover handoff.
+ */
+export function findLatestNotesCheckpointSinceBoundary(
+	entries: readonly SessionEntry[],
+	sessionId?: string,
+	afterEntryId?: string,
+): NotesCheckpointReceipt | undefined {
+	const windowBoundaryIndex = findLatestWindowBoundaryIndex(entries, sessionId);
+	const afterIndex = afterEntryId === undefined ? -1 : entries.findIndex((entry) => entry.id === afterEntryId);
+	if (windowBoundaryIndex < 0 || (afterEntryId !== undefined && afterIndex < 0)) return undefined;
+	const boundaryIndex = Math.max(windowBoundaryIndex, afterIndex);
+	const checkpointCalls = new Map<string, NotesCheckpointReceipt>();
+	let latest: NotesCheckpointReceipt | undefined;
+	for (let index = boundaryIndex + 1; index < entries.length; index += 1) {
+		const entry = entries[index]!;
+		if (entry.type !== "message") continue;
+		const message = entry.message;
+		if (message.role === "assistant") {
+			const parts = Array.isArray(message.content) ? message.content : [];
+			for (const part of parts) {
+				if (!isRecord(part) || part.type !== "toolCall" || part.name !== "notes") continue;
+				const args = isRecord(part.arguments) ? part.arguments : undefined;
+				const action = typeof args?.action === "string" ? args.action : "";
+				const path = isNonEmptyString(args?.path) ? args.path : undefined;
+				if (isNonEmptyString(part.id) && path !== undefined && NOTES_CHECKPOINT_ACTIONS.has(action)) {
+					checkpointCalls.set(part.id, { path, toolCallId: part.id });
+				}
+			}
+			continue;
+		}
+		if (message.role !== "toolResult" || message.toolName !== "notes") continue;
+		const receipt = checkpointCalls.get(message.toolCallId);
+		if (!receipt) continue;
+		checkpointCalls.delete(message.toolCallId);
+		if (message.isError !== false || !isSuccessfulHistoryNotesToolResult(message.details)) continue;
+		latest = receipt;
+	}
+	return latest;
+}
+
+/**
+ * Whether the branch contains a successful notes append/write result after the
+ * latest window boundary. Reads and failed writes never count as checkpoints.
+ */
+export function findNotesCheckpointSinceBoundary(
+	entries: readonly SessionEntry[],
+	sessionId?: string,
+): boolean {
+	return findLatestNotesCheckpointSinceBoundary(entries, sessionId) !== undefined;
+}
+
+function findLatestWindowBoundaryIndex(
+	entries: readonly SessionEntry[],
+	sessionId?: string,
+): number {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index]!;
+		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
+		if (!couldBelongToSession(entry.details, sessionId)) continue;
+		if (!isCodexContextManagementMessageDetails(entry.details)) {
+			throw new Error("Malformed persisted Codex context-window message");
+		}
+		if (!matchesSession(entry.details.sessionId, sessionId)) continue;
+		if (entry.details.contextManagement.kind === "window") return index;
+	}
+	return -1;
+}
+
+export function findLatestWindowBoundaryEntry(
+	entries: readonly SessionEntry[],
+	sessionId?: string,
+): WindowBoundaryEntry | undefined {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index]!;
+		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
+		if (!couldBelongToSession(entry.details, sessionId)) continue;
+		if (!isCodexContextManagementMessageDetails(entry.details)) {
+			throw new Error("Malformed persisted Codex context-window message");
+		}
+		if (!matchesSession(entry.details.sessionId, sessionId)) continue;
+		if (entry.details.contextManagement.kind === "window") return entry as WindowBoundaryEntry;
+	}
+	return undefined;
+}
+
+/**
+ * Whether this exact window boundary is already persisted for the session.
+ * Only durable entries count; a queued/visible marker does not.
+ */
+function hasPersistedWindowBoundary(
+	entries: readonly SessionEntry[],
+	sessionId: string | undefined,
+	windowId: string,
+): boolean {
+	for (const entry of entries) {
+		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
+		if (!couldBelongToSession(entry.details, sessionId)) continue;
+		if (!isCodexContextManagementMessageDetails(entry.details)) continue;
+		if (!matchesSession(entry.details.sessionId, sessionId)) continue;
+		const details = entry.details.contextManagement;
+		if (details.kind === "window" && details.currentWindowId === windowId) return true;
+	}
+	return false;
+}
+
+function findLatestContextMarkerId(
+	entries: readonly SessionEntry[],
+	sessionId?: string,
+): string | undefined {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index]!;
+		if (entry.type !== "custom_message" || entry.customType !== CODEX_CONTEXT_WINDOW_MESSAGE_TYPE) continue;
+		if (!couldBelongToSession(entry.details, sessionId)) continue;
+		if (!isCodexContextManagementMessageDetails(entry.details)) {
+			throw new Error("Malformed persisted Codex context-window message");
+		}
+		if (matchesSession(entry.details.sessionId, sessionId)) return entry.id;
+	}
+	return undefined;
+}
+
+function couldBelongToSession(details: unknown, sessionId: string | undefined): boolean {
+	if (sessionId === undefined || !isRecord(details)) return true;
+	const markerSessionId = details.sessionId;
+	return !isNonEmptyString(markerSessionId) || markerSessionId === sessionId;
+}
+
+function matchesSession(markerSessionId: string | undefined, sessionId: string | undefined): boolean {
+	return sessionId === undefined || markerSessionId === sessionId;
+}
+
+function estimateProjectedWindowTokens(messages: readonly AgentMessage[]): number {
+	let lastUsageIndex = -1;
+	let usageTokens = 0;
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index]!;
+		if (message.role !== "assistant" || message.stopReason === "aborted" || message.stopReason === "error" || !message.usage) continue;
+		const tokens = calculateContextTokens(message.usage);
+		if (tokens <= 0) continue;
+		lastUsageIndex = index;
+		usageTokens = tokens;
+		break;
+	}
+	if (lastUsageIndex < 0) return messages.reduce((total, message) => total + estimateProjectedMessageTokens(message), 0);
+	return usageTokens + messages
+		.slice(lastUsageIndex + 1)
+		.reduce((total, message) => total + estimateProjectedMessageTokens(message), 0);
+}
+
+function estimateProjectedMessageTokens(message: AgentMessage): number {
+	// A synthetic custom marker may be represented without content in a test or
+	// by an older host. It contributes no measurable text; it must not make the
+	// context hook fail closed merely because the diagnostic estimate is missing.
+	if (
+		!("content" in message) ||
+		(typeof message.content !== "string" && !Array.isArray(message.content))
+	) return 0;
+	return estimateTokens(message);
+}
+
+function projectEncryptedToolResults(messages: readonly AgentMessage[]): AgentMessage[] {
+	let changed = false;
+	const projected = messages.map((message) => {
+		if (message.role !== "toolResult" || !isRecord(message.details)) return message;
+		const historyNotes = message.details.codexHistoryNotes;
+		if (!isRecord(historyNotes) || typeof historyNotes.encrypted_output !== "string") return message;
+		changed = true;
+		return {
+			...message,
+			content: [
+				{ type: "text" as const, text: encodeEncryptedOutputForContext(historyNotes.encrypted_output) },
+				...message.content.filter((item) => item.type === "image"),
+			],
+		};
+	});
+	return changed ? projected : [...messages];
+}