pi-openai-toolkit 0.20.7 → 0.21.0

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

@@ -1,801 +1,801 @@
-import { randomUUID } from "node:crypto";
-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;
-};
-
-/**
- * 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;
-	/**
-	 * 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[] {
-		// 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;
-	}
-
-	/**
-	 * 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.
-	 */
-	prepareDetachedCompaction(
-		event: SessionBeforeCompactEvent,
-	): { 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.
-		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 { randomUUID } from "node:crypto";
+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;
+};
+
+/**
+ * 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;
+	/**
+	 * 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[] {
+		// 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;
+	}
+
+	/**
+	 * 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.
+	 */
+	prepareDetachedCompaction(
+		event: SessionBeforeCompactEvent,
+	): { 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.
+		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];
+}