pi-openai-toolkit 0.14.13 → 0.15.1

package/src/extension-runtime.ts

@@ -1,1329 +1,1375 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type {
-	BeforeProviderRequestEvent,
-	ContextEvent,
-	CompactionResult,
-	ExtensionAPI,
-	ExtensionContext,
-	SessionBeforeCompactEvent,
-} from "@earendil-works/pi-coding-agent";
-import { loadToolkitConfig } from "./config";
-import {
-	codexContextProviderHeaders,
-	resolveCodexContextProvider,
-	isCodexGatewayModel,
-	isNativeCodexModel,
-} from "./context-management/codex-provider";
-import { routeContextNamespaceToolMessage } from "./context-management/namespace-tools";
-import { loadHistoryNotesThreadHint } from "./context-management/history-notes";
-import { CodexContextWindowManager } from "./context-management/window-manager";
-import {
-	BULK_CLIFF_RATIO,
-	decideBulkCliffAction,
-	decideBulkCloseOut,
-	evaluateWindowBulk,
-} from "./context-management/window-bulk";
-import {
-	registerContextManagementTools,
-	type ContextToolRegistrationState,
-} from "./context-management/tools";
-import { writeDebugArtifact, writeReplayFailureArtifact } from "./debug";
-import {
-	COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
-	COMPACTION_PROJECTION_UNAVAILABLE,
-	COMPACTION_SESSION_CONTEXT_UNAVAILABLE,
-	COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE,
-	hasVerifiedCompactionInputProvenance,
-	type UnprojectedCompactionReason,
-} from "./compaction-projection";
-import { CODEX_GATEWAY_FORWARD_HEADERS } from "./responses-headers";
-import { resolveLatestNativeCompactionEntry } from "./details-store";
-import {
-	getPiContextHookProjector,
-	installPiContextHookPatch,
-	reportPiContextHookFailure,
-	type PiContextHookPatchResult,
-} from "./pi-context-hook";
-import { runNativeFallbackCompaction } from "./native-fallback";
-import {
-	rewriteResponsesPayloadWithNativeReplay,
-	removeNativeCompactionRetainedMessages,
-	serializeLiveTailToResponsesInput,
-} from "./payload-rewrite";
-import { getCompactionRequestExtras, rememberRequestContext } from "./request-context-cache";
-import { resolveWebSearchRoute } from "./web-search/types";
-import { executeRemoteV2Compaction } from "./remote-v2-client";
-import {
-	resolveNativeCompactionEnvironment,
-	resolveRemoteCompactionExecution,
-	type RemoteCompactionExecution,
-} from "./runtime";
-import {
-	serializeMessagesToCompactRequest,
-	serializeMessagesToResponsesInput,
-	type NativeCompactionRequestBody,
-	type ResponsesInputItem,
-} from "./serializer";
-import {
-	createNativeCompactionDetails,
-	createNativeCompactionResult,
-	COMPACTION_EXTENSION_ID,
-	getLatestDeferredToolCarryover,
-	getRemoteV2InputProvenance,
-	isNativeCompactionDetails,
-	type CompactionConfig,
-	type NativeCompactionDetails,
-	type NativeCompactionRequestMeta,
-} from "./types";
-
-type CompactionContextProjection = (
-	messages: readonly AgentMessage[],
-	ctx: ExtensionContext,
-) => readonly AgentMessage[] | undefined | Promise<readonly AgentMessage[] | undefined>;
-
-type CompactionDependencies = {
-	loadConfig: typeof loadToolkitConfig;
-	remoteCompact: typeof executeRemoteV2Compaction;
-	nativeFallback: typeof runNativeFallbackCompaction;
-	contextWindows: CodexContextWindowManager;
-	/** Test seam for the same ordered projection exposed by the Pi host patch. */
-	projectCompactionContext?: CompactionContextProjection;
-	piContextHookPatch: PiContextHookPatchResult;
-};
-
-type RemoteContextActive = (
-	ctx: ExtensionContext,
-	config: CompactionConfig,
-	model?: ExtensionContext["model"],
-) => Promise<boolean>;
-
-type ContextToolSyncOutcome = {
-	eligible: boolean;
-	toolsSynced: boolean;
-	registrationState: ContextToolRegistrationState;
-	windowInitialized: boolean;
-};
-
-type ResponsesCompactOutcome =
-	| { outcome: "success"; compaction: CompactionResult<NativeCompactionDetails> }
-	| { outcome: "aborted" }
-	| { outcome: "failed" }
-	| {
-			outcome: "unprojected-input";
-			reason: UnprojectedCompactionReason;
-	  };
-
-function buildCompactionRequestMeta(event: SessionBeforeCompactEvent): NativeCompactionRequestMeta {
-	return {
-		tokensBefore: event.preparation.tokensBefore,
-		previousSummaryPresent: Boolean(event.preparation.previousSummary),
-	};
-}
-
-function getCurrentModelDebugInfo(ctx: ExtensionContext) {
-	return ctx.model
-		? {
-			provider: ctx.model.provider,
-			id: ctx.model.id,
-		}
-		: undefined;
-}
-
-function getCompactionIdentityDebugInfo(entry: { details?: unknown } | undefined) {
-	return isNativeCompactionDetails(entry?.details)
-		? {
-			provider: entry.details.provider,
-			api: entry.details.api,
-			model: entry.details.model,
-			baseUrl: entry.details.baseUrl,
-			compactionModel: entry.details.compactionModel,
-		}
-		: undefined;
-}
-
-function getSessionId(ctx: ExtensionContext): string | undefined {
-	try {
-		return ctx.sessionManager.getSessionId();
-	} catch {
-		return undefined;
-	}
-}
-
-function notifyWarning(ctx: ExtensionContext, message: string): void {
-	if (ctx.hasUI) {
-		ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: ${message}`, "warning");
-	}
-}
-
-async function isRemoteContextActive(
-	ctx: ExtensionContext,
-	config: CompactionConfig,
-	model: ExtensionContext["model"] = ctx.model,
-): Promise<boolean> {
-	if (!config.enabled || config.contextManagement !== "remote") return false;
-	const resolution = await resolveCodexContextProvider(ctx, model, config.gatewayContextModels);
-	return resolution.ok;
-}
-
-function isCodexContextModel(
-	model: ExtensionContext["model"] | undefined,
-	config: CompactionConfig,
-): boolean {
-	return config.contextManagement === "remote"
-		&& (isNativeCodexModel(model) || isCodexGatewayModel(model, config.gatewayContextModels));
-}
-
-function notifyRemoteContextFailure(ctx: ExtensionContext, reason: string): void {
-	if (ctx.hasUI) {
-		ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: Remote Context management inactive (${reason})`, "warning");
-	}
-}
-
-/**
- * Surface every window trim that had to be refused to keep the tool loadout intact.
- *
- * The refusal itself is safe: the model keeps the previous turns instead of losing its
- * tools. It is still a continuity incident, so it is recorded once per window and reason
- * instead of being allowed to pass silently.
- */
-function reportProjectionDiagnostics(
-	contextWindows: CodexContextWindowManager,
-	config: CompactionConfig,
-	ctx: ExtensionContext,
-): void {
-	const diagnostics = contextWindows.takeProjectionDiagnostics();
-	if (diagnostics.length === 0) return;
-	writeDebugArtifact(
-		"compaction-event",
-		{ event: "context.projection.tool_loadout_shrink", diagnostics },
-		config,
-		ctx,
-	);
-	if (ctx.hasUI) {
-		ctx.ui.notify(
-			`${COMPACTION_EXTENSION_ID}: kept previous context to preserve tools (${diagnostics.join("; ")})`,
-			"warning",
-		);
-	}
-}
-
-function cloneOpaqueWindow(window: readonly unknown[]): unknown[] {
-	return window.map((item) => structuredClone(item));
-}
-
-function buildCompactionInstructions(systemPrompt: string, customInstructions?: string): string {
-	const guidance = customInstructions?.trim();
-	if (!guidance) {
-		return systemPrompt;
-	}
-
-	return `${systemPrompt}\n\nAdditional user guidance for this manual /compact request:\n${guidance}`;
-}
-
-function findLatestProjectedCompactionSummaryIndex(
-	messages: readonly AgentMessage[],
-	summary: string,
-): number {
-	for (let index = messages.length - 1; index >= 0; index -= 1) {
-		const message = messages[index];
-		if (message?.role === "compactionSummary" && message.summary === summary) {
-			return index;
-		}
-	}
-
-	return -1;
-}
-
-type SessionManagerWithOptionalContext = ExtensionContext["sessionManager"] & {
-	buildSessionContext?: () => { messages?: readonly AgentMessage[] };
-};
-
-function readSessionContextMessages(ctx: ExtensionContext): AgentMessage[] | undefined {
-	const sessionManager = ctx.sessionManager as SessionManagerWithOptionalContext;
-	if (typeof sessionManager.buildSessionContext !== "function") {
-		return undefined;
-	}
-
-	try {
-		const sessionContext = sessionManager.buildSessionContext();
-		if (!sessionContext || !Array.isArray(sessionContext.messages)) {
-			return undefined;
-		}
-		return structuredClone([...sessionContext.messages]);
-	} catch {
-		return undefined;
-	}
-}
-
-type CompactionProjectionResult =
-	| { ok: true; messages: readonly AgentMessage[] }
-	| { ok: false; reason: typeof COMPACTION_PROJECTION_UNAVAILABLE | typeof COMPACTION_SESSION_CONTEXT_UNAVAILABLE };
-
-async function projectSessionContextForCompaction(
-	ctx: ExtensionContext,
-	projectCompactionContext: CompactionContextProjection | undefined,
-): Promise<CompactionProjectionResult> {
-	const messages = readSessionContextMessages(ctx);
-	if (!messages) {
-		return { ok: false, reason: COMPACTION_SESSION_CONTEXT_UNAVAILABLE };
-	}
-
-	const projector = projectCompactionContext ?? getPiContextHookProjector(ctx);
-	if (!projector) {
-		return { ok: false, reason: COMPACTION_PROJECTION_UNAVAILABLE };
-	}
-
-	try {
-		const projected = await projector(messages, ctx);
-		return Array.isArray(projected)
-			? { ok: true, messages: projected }
-			: { ok: false, reason: COMPACTION_PROJECTION_UNAVAILABLE };
-	} catch {
-		return { ok: false, reason: COMPACTION_PROJECTION_UNAVAILABLE };
-	}
-}
-
-function getLegacySessionContextMessages(
-	event: SessionBeforeCompactEvent,
-	ctx: ExtensionContext,
-): AgentMessage[] {
-	return readSessionContextMessages(ctx) ?? [
-		...event.preparation.messagesToSummarize,
-		...event.preparation.turnPrefixMessages,
-	];
-}
-
-async function runResponsesNativeCompact(
-	event: SessionBeforeCompactEvent,
-	ctx: ExtensionContext,
-	config: CompactionConfig,
-	execution: RemoteCompactionExecution,
-	remoteCompact: typeof executeRemoteV2Compaction,
-	projectCompactionContext: CompactionContextProjection | undefined,
-): Promise<ResponsesCompactOutcome> {
-	const { consumer, compactor } = execution;
-	const instructions = buildCompactionInstructions(ctx.getSystemPrompt(), event.customInstructions);
-	const branchEntries = event.branchEntries ?? ctx.sessionManager.getBranch();
-	const deferredToolCarryover = getLatestDeferredToolCarryover(branchEntries);
-	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
-		baseUrl: consumer.baseUrl,
-	});
-
-	const inputProvenance = getRemoteV2InputProvenance(config.remoteV2ContextSource);
-	let requestSource: "session-context" | "non-native-session-context" | "latest-native-replay";
-	let request: NativeCompactionRequestBody;
-	if (latestNativeCompaction.ok) {
-		const details = latestNativeCompaction.entry.details;
-		if (!details) {
-			return { outcome: "failed" };
-		}
-		if (!hasVerifiedCompactionInputProvenance(details, inputProvenance)) {
-			return {
-				outcome: "unprojected-input",
-				reason: COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
-			};
-		}
-		requestSource = "latest-native-replay";
-
-		if (config.remoteV2ContextSource === "pi-context-hook") {
-			const projection = await projectSessionContextForCompaction(ctx, projectCompactionContext);
-			if (!projection.ok) {
-				return { outcome: "unprojected-input", reason: projection.reason };
-			}
-			const summaryIndex = findLatestProjectedCompactionSummaryIndex(
-				projection.messages,
-				latestNativeCompaction.entry.summary,
-			);
-			if (summaryIndex < 0) {
-				return {
-					outcome: "unprojected-input",
-					reason: COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE,
-				};
-			}
-			const input: ResponsesInputItem[] = [
-				...(cloneOpaqueWindow(details.compactedWindow) as ResponsesInputItem[]),
-				...serializeMessagesToResponsesInput(
-					compactor.currentModel,
-					[...projection.messages.slice(summaryIndex + 1)],
-					{ firstSystemMessageIsUpdate: true },
-				),
-			];
-			request = {
-				model: compactor.model,
-				input,
-				instructions,
-			};
-		} else {
-			const liveTailEntries = branchEntries.slice(latestNativeCompaction.index + 1);
-			const input: ResponsesInputItem[] = [
-				...(cloneOpaqueWindow(details.compactedWindow) as ResponsesInputItem[]),
-				...serializeLiveTailToResponsesInput({ model: compactor.currentModel, entries: liveTailEntries }),
-			];
-			request = {
-				model: compactor.model,
-				input,
-				instructions,
-			};
-		}
-	} else if (
-		latestNativeCompaction.reason === "no-compaction" ||
-		(latestNativeCompaction.reason === "latest-compaction-not-native" &&
-			config.allowCompactionContinuityBreak)
-	) {
-		requestSource =
-			latestNativeCompaction.reason === "no-compaction" ? "session-context" : "non-native-session-context";
-		if (config.remoteV2ContextSource === "pi-context-hook") {
-			const projection = await projectSessionContextForCompaction(ctx, projectCompactionContext);
-			if (!projection.ok) {
-				return { outcome: "unprojected-input", reason: projection.reason };
-			}
-			request = serializeMessagesToCompactRequest({
-				model: compactor.currentModel,
-				messages: [...projection.messages],
-				instructions,
-			});
-		} else {
-			request = serializeMessagesToCompactRequest({
-				model: compactor.currentModel,
-				messages: getLegacySessionContextMessages(event, ctx),
-				instructions,
-			});
-		}
-	} else {
-		writeDebugArtifact(
-			"compaction-event",
-			{
-				event: "session_before_compact.remote-v2-skip",
-				reason: latestNativeCompaction.reason,
-				consumer: {
-					provider: consumer.provider,
-					api: consumer.api,
-					model: consumer.model,
-					baseUrl: consumer.baseUrl,
-				},
-				compactor: {
-					provider: compactor.provider,
-					api: compactor.api,
-					model: compactor.model,
-					baseUrl: compactor.baseUrl,
-				},
-				latestCompactionIndex: latestNativeCompaction.latestCompactionIndex,
-				latestCompactionIdentity: getCompactionIdentityDebugInfo(latestNativeCompaction.latestCompaction),
-			},
-			config,
-			ctx,
-		);
-		return { outcome: "failed" };
-	}
-
-	// Mirror the latest codex_rs CompactionInput fields captured from the most
-	// recent live provider request for this model (tools, reasoning, etc.).
-	const extras = getCompactionRequestExtras({
-		provider: consumer.provider,
-		api: consumer.api,
-		model: consumer.model,
-		baseUrl: consumer.baseUrl,
-		sessionId: getSessionId(ctx),
-	}, compactor.currentModel);
-	if (extras) {
-		request = { ...request, ...extras };
-	}
-
-	const compactResult = await remoteCompact({
-		runtime: compactor,
-		request,
-		signal: event.signal,
-		settings: config,
-		context: ctx,
-	});
-
-	if (compactResult.ok === false) {
-		writeDebugArtifact(
-			"compaction-event",
-			{
-				event: "session_before_compact.remote-v2-failure",
-				reason: compactResult.reason,
-				status: compactResult.status,
-				errorMessage: compactResult.errorMessage,
-			},
-			config,
-			ctx,
-		);
-		return compactResult.reason === "aborted" ? { outcome: "aborted" } : { outcome: "failed" };
-	}
-
-	let details: NativeCompactionDetails;
-	try {
-		details = createNativeCompactionDetails({
-			provider: consumer.provider,
-			api: consumer.api,
-			model: consumer.model,
-			baseUrl: consumer.baseUrl,
-			compactionModel: {
-				provider: compactor.provider,
-				api: compactor.api,
-				model: compactor.model,
-				baseUrl: compactor.baseUrl,
-			},
-			deferredToolCarryover,
-			compactedWindow: compactResult.compactedWindow,
-			compactResponseId: compactResult.compactResponseId,
-			createdAt: compactResult.createdAt,
-			requestMeta: buildCompactionRequestMeta(event),
-			inputProvenance,
-		});
-	} catch (error) {
-		writeDebugArtifact(
-			"compaction-event",
-			{
-				event: "session_before_compact.invalid-native-details",
-				reason: error instanceof Error ? error.message : String(error),
-				consumer: {
-					provider: consumer.provider,
-					api: consumer.api,
-					model: consumer.model,
-					baseUrl: consumer.baseUrl,
-				},
-				compactor: {
-					provider: compactor.provider,
-					api: compactor.api,
-					model: compactor.model,
-					baseUrl: compactor.baseUrl,
-				},
-			},
-			config,
-			ctx,
-		);
-		return { outcome: "failed" };
-	}
-
-	const compaction = createNativeCompactionResult({
-		firstKeptEntryId: event.preparation.firstKeptEntryId,
-		tokensBefore: event.preparation.tokensBefore,
-		details,
-	});
-
-	writeDebugArtifact(
-		"compaction-event",
-		{
-			event: "session_before_compact.remote-v2-success",
-			consumer: {
-				provider: consumer.provider,
-				api: consumer.api,
-				model: consumer.model,
-				baseUrl: consumer.baseUrl,
-			},
-			compactor: {
-				provider: compactor.provider,
-				api: compactor.api,
-				model: compactor.model,
-				baseUrl: compactor.baseUrl,
-			},
-			requestSource,
-			remoteV2ContextSource: config.remoteV2ContextSource,
-			inputProvenance,
-			requestInputItems: request.input.length,
-			requestExtras: extras ? Object.keys(extras) : [],
-			compactResponseId: compactResult.compactResponseId,
-			compactedItems: compactResult.compactedWindow.length,
-			firstKeptEntryId: event.preparation.firstKeptEntryId,
-		},
-		config,
-		ctx,
-	);
-
-	return { outcome: "success", compaction };
-}
-
-async function handleSessionBeforeCompact(
-	event: SessionBeforeCompactEvent,
-	ctx: ExtensionContext,
-	dependencies: CompactionDependencies,
-	remoteContextActive: RemoteContextActive,
-) {
-	const { config: toolkitConfig } = dependencies.loadConfig();
-	const config = toolkitConfig.compaction;
-	if (!config.enabled) {
-		return undefined;
-	}
-
-	writeDebugArtifact(
-		"compaction-event",
-		{
-			event: "session_before_compact",
-			customInstructions: event.customInstructions,
-			preparation: {
-				tokensBefore: event.preparation.tokensBefore,
-				firstKeptEntryId: event.preparation.firstKeptEntryId,
-				previousSummaryPresent: Boolean(event.preparation.previousSummary),
-				messagesToSummarizeCount: event.preparation.messagesToSummarize.length,
-				turnPrefixMessagesCount: event.preparation.turnPrefixMessages.length,
-			},
-		},
-		config,
-		ctx,
-	);
-
-	if (event.signal.aborted) {
-		return { cancel: true };
-	}
-
-	// Remote Context management owns this eligible Codex session. It persists a
-	// no-summary boundary and deliberately never calls remote_compaction_v2.
-	if (isCodexContextModel(ctx.model, config)) {
-		if (await remoteContextActive(ctx, config)) {
-			try {
-				dependencies.contextWindows.synchronize(ctx);
-				return dependencies.contextWindows.prepareCompaction(event);
-			} catch {
-				notifyRemoteContextFailure(ctx, "malformed-window-state");
-				return { cancel: true };
-			}
-		}
-		// A configured native Codex Remote session must never re-enter this
-		// extension's Remote V2 compaction chain, and Pi's native compaction is
-		// deliberately disabled for Remote-managed models: cancelling here keeps
-		// the boundary the only rollover mechanism. The inactive reason is
-		// surfaced so the user can fix activation instead of losing context to a
-		// silent native summary.
-		notifyRemoteContextFailure(ctx, "native-codex-context-unavailable");
-		return { cancel: true };
-	}
-
-	// Branch 1: Responses-family APIs use remote_compaction_v2 on the normal Responses stream.
-	let remoteAttempted = false;
-	const resolution = await resolveRemoteCompactionExecution(
-		ctx,
-		{
-			enabled: config.enabled,
-			responsesApis: config.responsesApis,
-			codexGatewayModels: config.contextManagement === "remote" ? config.gatewayContextModels : [],
-		},
-		config.remoteCompactModel,
-	);
-	if (resolution.ok) {
-		remoteAttempted = true;
-		const responsesOutcome = await runResponsesNativeCompact(
-			event,
-			ctx,
-			config,
-			resolution.execution,
-			dependencies.remoteCompact,
-			dependencies.projectCompactionContext,
-		);
-		if (responsesOutcome.outcome === "success") {
-			return { compaction: responsesOutcome.compaction };
-		}
-		if (responsesOutcome.outcome === "aborted") {
-			return { cancel: true };
-		}
-		if (responsesOutcome.outcome === "unprojected-input") {
-			const message = responsesOutcome.reason === COMPACTION_PROJECTION_UNAVAILABLE
-				? "Pi's ordered context-hook projection is unavailable; Remote V2 was not sent raw session history."
-				: responsesOutcome.reason === COMPACTION_SESSION_CONTEXT_UNAVAILABLE
-					? "Pi did not provide the current session context required by its context-hook projection."
-					: responsesOutcome.reason === COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE
-						? "Pi's projected context did not include the current compaction summary anchor."
-						: "The latest opaque checkpoint has no marker for the configured Remote V2 context source, or was created in the other mode.";
-			writeDebugArtifact(
-				"compaction-event",
-				{
-					event: "session_before_compact.remote-v2-unprojected-input",
-					reason: responsesOutcome.reason,
-					contextSource: config.remoteV2ContextSource,
-					inputProvenance: getRemoteV2InputProvenance(config.remoteV2ContextSource),
-					piContextHookPatch: dependencies.piContextHookPatch,
-					message,
-				},
-				config,
-				ctx,
-			);
-			notifyWarning(
-				ctx,
-				`Remote V2 compaction cancelled (${responsesOutcome.reason}); ${message} Keep the context-source setting aligned with the checkpoint or choose legacy mode explicitly.`,
-			);
-			return { cancel: true };
-		}
-		// failed: fall through to the configured-model fallback below.
-	} else {
-		writeDebugArtifact(
-			"compaction-event",
-			{
-				event: "session_before_compact.remote-v2-unavailable",
-				reason: resolution.reason,
-				provider: resolution.provider,
-				api: resolution.api,
-				model: resolution.model,
-				baseUrl: resolution.baseUrl,
-				modelSpec: resolution.modelSpec,
-				errorMessage: resolution.errorMessage,
-			},
-			config,
-			ctx,
-		);
-		if (config.remoteCompactModel) {
-			notifyWarning(
-				ctx,
-				`remote compaction model "${config.remoteCompactModel}" unusable (${resolution.reason}); using the native fallback chain`,
-			);
-		}
-	}
-
-	// Branch 2: run pi's native compaction method. A failed remote request is compacted by the
-	// remote producer itself; a model that cannot use remote v2 at all uses nativeFallback.model.
-	const fallbackModelSpec = remoteAttempted ? config.remoteCompactModel : config.nativeFallback.model;
-	const fallback = await dependencies.nativeFallback({ ctx, event, config, modelSpec: fallbackModelSpec });
-	if (fallback.ok) {
-		if (ctx.hasUI) {
-			ctx.ui.notify(
-				`${COMPACTION_EXTENSION_ID}: compacted with ${fallback.model.provider}/${fallback.model.id} (native method)`,
-				"info",
-			);
-		}
-		writeDebugArtifact(
-			"compaction-event",
-			{
-				event: "session_before_compact.fallback-success",
-				model: fallback.model,
-			},
-			config,
-			ctx,
-		);
-		return { compaction: fallback.result };
-	}
-
-	if (fallback.reason === "aborted") {
-		return { cancel: true };
-	}
-
-	writeDebugArtifact(
-		"compaction-event",
-		{
-			event: "session_before_compact.fallback-skip",
-			reason: fallback.reason,
-			modelSpec: fallback.modelSpec,
-			errorMessage: fallback.errorMessage,
-			...(fallback.estimatedTokens === undefined ? {} : { estimatedTokens: fallback.estimatedTokens }),
-			...(fallback.contextWindow === undefined ? {} : { contextWindow: fallback.contextWindow }),
-		},
-		config,
-		ctx,
-	);
-
-	// Intentional pi-default paths: feature disabled, nothing configured, or it matches the current one.
-	const intentionalSkip =
-		fallback.reason === "disabled" ||
-		fallback.reason === "no-model-configured" ||
-		fallback.reason === "same-as-current-model";
-	if (fallback.reason === "model-window-too-small") {
-		// The configured summary model is narrower than the request Pi would send for it.
-		// Skipping is the success path here: pi's current model gets one chance instead of
-		// the provider terminating the oversized summary.
-		notifyWarning(
-			ctx,
-			`compaction summary model "${fallback.modelSpec}" cannot fit ~${fallback.estimatedTokens} tokens in its ${fallback.contextWindow} window; compacting with the current model instead`,
-		);
-	} else if (!intentionalSkip) {
-		notifyWarning(
-			ctx,
-			`compaction model "${fallback.modelSpec}" unusable (${fallback.reason}${fallback.errorMessage ? `: ${fallback.errorMessage}` : ""}); using pi's default compaction`,
-		);
-	}
-
-	// Branch 3: pi's default native compaction with the current model.
-	return undefined;
-}
-
-/**
- * Surface (and optionally close) the gap between the durable transcript and the remote window.
- *
- * Remote context management retires previous windows in the request projection, so a covered
- * model never notices that the branch still carries every one of them. Switching to a model
- * without remote context - or resuming such a session - hands that whole pile to the provider
- * at once, and the first manual `/compact` then has to summarize it. Runs once per agent turn,
- * never per request, and only once per window and model so the notice cannot become a nag.
- */
-async function handleWindowBulk(
-	ctx: ExtensionContext,
-	contextWindows: CodexContextWindowManager,
-	loadConfig: typeof loadToolkitConfig,
-	trigger: "model-switch" | "turn-end",
-): Promise<void> {
-	const { config: config } = loadConfig();
-	const compaction = config.compaction;
-	if (!compaction.enabled || compaction.contextManagement !== "remote") return;
-	if (!ctx.model) return;
-
-	const modelKey = `${ctx.model.provider}/${ctx.model.id}`;
-	const report = evaluateWindowBulk(ctx);
-	if (!report) return;
-	contextWindows.noteWindowBulk(report, modelKey);
-	const cliff = contextWindows.takeBulkCliff(modelKey);
-	if (!cliff) return;
-	const action = decideBulkCloseOut({
-		action: decideBulkCliffAction(cliff, compaction.leaveManagedMode),
-		mode: ctx.mode,
-		trigger,
-		hasPendingTrim: contextWindows.hasPendingTrim(),
-	});
-	if (action === "ignore") return;
-
-	writeDebugArtifact(
-		"compaction-event",
-		{
-			event: `window-bulk.${action}`,
-			trigger,
-			policy: compaction.leaveManagedMode,
-			model: modelKey,
-			unmanagedTokens: cliff.unmanagedTokens,
-			managedTokens: cliff.managedTokens,
-			targetContextWindow: cliff.targetContextWindow,
-			overBudget: cliff.overBudget,
-		},
-		compaction,
-		ctx,
-	);
-
-	const gap = `${cliff.unmanagedTokens.toLocaleString()} tokens of retired windows are still in this session's transcript, while remote context management has been sending ${cliff.managedTokens.toLocaleString()}`;
-	if (action === "warn") {
-		notifyWarning(
-			ctx,
-			`${gap} to ${modelKey}${cliff.overBudget ? `, past ${Math.round(BULK_CLIFF_RATIO * 100)}% of its window` : ""}. Checkpoint with notes and run /compact (or new_context) before continuing on a model without remote context, or set compaction.leaveManagedMode="compact" to do it automatically.`,
-		);
-		return;
-	}
-
-	notifyWarning(ctx, `${gap} to ${modelKey}, past ${Math.round(BULK_CLIFF_RATIO * 100)}% of its window; compacting the retired windows first.`);
-	if (typeof ctx.compact !== "function") return;
-	ctx.compact({
-		onError: (error: Error) => {
-			notifyWarning(ctx, `automatic boundary compaction failed: ${error.message}`);
-		},
-	});
-}
-
-async function handleContextInternal(
-	event: ContextEvent,
-	ctx: ExtensionContext,
-	pi: ExtensionAPI,
-	loadConfig: typeof loadToolkitConfig,
-	contextWindows: CodexContextWindowManager,
-	remoteContextActive: RemoteContextActive,
-) {
-	const { config: { compaction: config } } = loadConfig();
-	if (!config.enabled) {
-		const visibleMessages = contextWindows.project(event.messages, "off");
-		return visibleMessages.length === event.messages.length && visibleMessages.every((message, index) => message === event.messages[index])
-			? undefined
-			: { messages: visibleMessages };
-	}
-
-	if (config.contextManagement === "remote") {
-		try {
-			contextWindows.synchronize(ctx);
-		} catch {
-			notifyRemoteContextFailure(ctx, "malformed-window-state");
-			reportPiContextHookFailure(ctx, "malformed-window-state");
-			ctx.abort();
-			return undefined;
-		}
-
-		const remoteActive = await remoteContextActive(ctx, config);
-		if (remoteActive) {
-			try {
-				contextWindows.recordBudget(
-					pi,
-					ctx,
-					true,
-					config.contextReminderThresholdPercent,
-				);
-				const projected = contextWindows.project(event.messages, "remote");
-				reportProjectionDiagnostics(contextWindows, config, ctx);
-				return projected.length === event.messages.length && projected.every((message, index) => message === event.messages[index])
-					? undefined
-					: { messages: projected };
-			} catch (error) {
-				notifyRemoteContextFailure(ctx, "malformed-window-state");
-				reportPiContextHookFailure(ctx, "malformed-window-state");
-				ctx.abort();
-				return undefined;
-			}
-		}
-
-		// An eligible Codex Remote session is never allowed to fall through to the
-		// older compaction-replay path. Gateway traffic must also fail closed when
-		// its transport capability is unavailable; otherwise Pi could send an
-		// ordinary unscoped request and lose CPA OAuth/session affinity.
-		if (isCodexContextModel(ctx.model, config)) {
-			if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
-				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
-				reportPiContextHookFailure(ctx, "codex-context-unavailable");
-				ctx.abort();
-				return undefined;
-			}
-			const visibleMessages = contextWindows.project(event.messages, "off");
-			return visibleMessages.length === event.messages.length && visibleMessages.every((message, index) => message === event.messages[index])
-				? undefined
-				: { messages: visibleMessages };
-		}
-	}
-
-	// Inactive/ineligible Remote mode must not expose internal window markers to a
-	// gateway or another provider. The existing compaction replay path remains the
-	// owner for this safe fallback.
-	const visibleMessages = contextWindows.project(event.messages, "off");
-	const replayEvent = visibleMessages === event.messages ? event : { ...event, messages: visibleMessages };
-	const resolution = await resolveNativeCompactionEnvironment(ctx, {
-		enabled: config.enabled,
-		responsesApis: config.responsesApis,
-		codexGatewayModels: config.contextManagement === "remote" ? config.gatewayContextModels : [],
-	});
-	if (!resolution.ok) return undefined;
-	const branchEntries = ctx.sessionManager.getBranch();
-	const latest = resolveLatestNativeCompactionEntry(branchEntries, { baseUrl: resolution.runtime.baseUrl });
-	if (!latest.ok) return undefined;
-	const result = removeNativeCompactionRetainedMessages({
-		messages: replayEvent.messages,
-		branchEntries,
-		compactionEntry: latest.entry,
-		expectedInputProvenance: getRemoteV2InputProvenance(config.remoteV2ContextSource),
-	});
-	if (!result.ok) {
-		writeReplayFailureArtifact({ reason: result.reason, compactionEntryId: latest.entry.id }, config, ctx);
-		if (ctx.hasUI) ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: replay failed (${result.reason}); request aborted`, "error");
-		reportPiContextHookFailure(ctx, `replay-failed:${result.reason}`);
-		ctx.abort();
-		return undefined;
-	}
-	return result.messages === replayEvent.messages ? undefined : { messages: result.messages };
-}
-
-/**
- * Pi's emitContext() catches handler exceptions. Re-throw as usual for Pi, but
- * also report the failure so the compaction projector cannot mistake the
- * caught exception for a successful projection.
- */
-async function handleContext(
-	event: ContextEvent,
-	ctx: ExtensionContext,
-	pi: ExtensionAPI,
-	loadConfig: typeof loadToolkitConfig,
-	contextWindows: CodexContextWindowManager,
-	remoteContextActive: RemoteContextActive,
-) {
-	try {
-		return await handleContextInternal(event, ctx, pi, loadConfig, contextWindows, remoteContextActive);
-	} catch (error) {
-		reportPiContextHookFailure(ctx, error instanceof Error ? error.message : String(error));
-		throw error;
-	}
-}
-
-async function handleBeforeProviderRequest(
-	event: BeforeProviderRequestEvent,
-	ctx: ExtensionContext,
-	loadConfig: typeof loadToolkitConfig,
-	contextWindows: CodexContextWindowManager,
-	remoteContextActive: RemoteContextActive,
-) {
-	const { config: toolkitConfig } = loadConfig();
-	const config = toolkitConfig.compaction;
-	if (!config.enabled) {
-		return undefined;
-	}
-
-	if (config.contextManagement === "remote") {
-		try {
-			contextWindows.synchronize(ctx);
-		} catch {
-			notifyRemoteContextFailure(ctx, "malformed-window-state");
-			ctx.abort();
-			return undefined;
-		}
-	}
-	if (config.contextManagement === "remote" && await remoteContextActive(ctx, config)) {
-		try {
-			return contextWindows.rewritePayload(event.payload, ctx);
-		} catch {
-			notifyRemoteContextFailure(ctx, "malformed-request-state");
-			ctx.abort();
-			return undefined;
-		}
-	}
-	if (isCodexContextModel(ctx.model, config)) {
-		// Keep Codex Remote mutually exclusive with the legacy replay pipeline
-		// when authentication or tool ownership is unavailable. Gateway traffic
-		// cannot continue as an ordinary Responses request because that would
-		// silently lose the required CPA session/account selection.
-		if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
-			notifyRemoteContextFailure(ctx, "codex-context-unavailable");
-			ctx.abort();
-		}
-		return undefined;
-	}
-
-	const resolution = await resolveNativeCompactionEnvironment(
-		ctx,
-		{
-			enabled: config.enabled,
-			responsesApis: config.responsesApis,
-			codexGatewayModels: config.contextManagement === "remote" ? config.gatewayContextModels : [],
-		},
-		event.payload,
-	);
-	if (resolution.ok === false) {
-		writeDebugArtifact(
-			"provider-request",
-			{
-				event: "before_provider_request.skip",
-				reason: resolution.reason,
-				provider: resolution.provider,
-				api: resolution.api,
-				model: resolution.model,
-				baseUrl: resolution.baseUrl,
-				errorMessage: resolution.errorMessage,
-				currentModel: getCurrentModelDebugInfo(ctx),
-				payload: event.payload,
-			},
-			config,
-			ctx,
-		);
-		return undefined;
-	}
-
-	const runtime = resolution.runtime;
-	const payload = runtime.payload;
-	if (!payload) {
-		return undefined;
-	}
-
-	// Capture compact-relevant request fields (tools, reasoning, ...) for the next
-	// synthetic compact request using the active consumer's effective runtime identity.
-	// This hook runs before the separate Web Search transform, so injected native search
-	// tools are not copied into remote_compaction_v2.
-	const webSearchRoute = resolveWebSearchRoute({ model: ctx.model, config: toolkitConfig.webSearch });
-	rememberRequestContext(
-		payload,
-		{
-			provider: runtime.provider,
-			api: runtime.api,
-			model: runtime.model,
-			baseUrl: runtime.baseUrl,
-			sessionId: getSessionId(ctx),
-		},
-		{
-			excludeWebSearchTools: webSearchRoute.route === "standalone-alpha",
-		},
-	);
-
-	const branchEntries = ctx.sessionManager.getBranch();
-	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
-		baseUrl: runtime.baseUrl,
-	});
-	if (!latestNativeCompaction.ok) {
-		writeDebugArtifact(
-			"provider-request",
-			{
-				event: "before_provider_request.no-native-compaction",
-				reason: latestNativeCompaction.reason,
-				provider: runtime.provider,
-				api: runtime.api,
-				model: runtime.model,
-				baseUrl: runtime.baseUrl,
-				branchEntries: branchEntries.length,
-				latestCompactionIndex: latestNativeCompaction.latestCompactionIndex,
-				latestCompactionIdentity: getCompactionIdentityDebugInfo(latestNativeCompaction.latestCompaction),
-				payload,
-			},
-			config,
-			ctx,
-		);
-		return undefined;
-	}
-
-	const latestNativeCompactionEntry = latestNativeCompaction.entry;
-	const rewrite = rewriteResponsesPayloadWithNativeReplay({
-		model: runtime.currentModel,
-		payload,
-		branchEntries,
-		compactionEntry: latestNativeCompactionEntry,
-		expectedInputProvenance: getRemoteV2InputProvenance(config.remoteV2ContextSource),
-	});
-	if (!rewrite.ok) {
-		writeDebugArtifact(
-			"provider-request",
-			{
-				event: "before_provider_request.rewrite-failed",
-				reason: rewrite.reason,
-				provider: runtime.provider,
-				api: runtime.api,
-				model: runtime.model,
-				baseUrl: runtime.baseUrl,
-				compactionEntryId: latestNativeCompactionEntry.id,
-				parity: rewrite.parity,
-				payload,
-			},
-			config,
-			ctx,
-		);
-
-		// Fail loud instead of letting Pi send the sentinel-only payload: the
-		// compacted history would be silently lost while the request still succeeds.
-		// A forced redacted failure record is written even when logProviderPayloads
-		// is disabled so the incident is diagnosable without leaking content.
-		writeReplayFailureArtifact(
-			{
-				reason: rewrite.reason,
-				parity: rewrite.parity,
-				compactionEntryId: latestNativeCompactionEntry.id,
-				provider: runtime.provider,
-				api: runtime.api,
-				model: runtime.model,
-			},
-			config,
-			ctx,
-		);
-		if (ctx.hasUI) {
-			ctx.ui.notify(
-				`${COMPACTION_EXTENSION_ID}: native compaction replay failed (${rewrite.reason}); provider request aborted`,
-				"error",
-			);
-		}
-		ctx.abort();
-		return undefined;
-	}
-
-	writeDebugArtifact(
-		"provider-request",
-		{
-			event: "before_provider_request.native-rewrite",
-			provider: runtime.provider,
-			api: runtime.api,
-			model: runtime.model,
-			baseUrl: runtime.baseUrl,
-			compactionEntryId: latestNativeCompactionEntry.id,
-			boundaryIndex: rewrite.segments.boundaryIndex,
-			firstKeptEntryIndex: rewrite.segments.firstKeptEntryIndex,
-			originalInputItems: payload.input.length,
-			rewrittenInputItems: rewrite.rewrittenPayload.input.length,
-			leadingItems: rewrite.segments.leading.length,
-			compactionSummaryItems: rewrite.segments.compactionSummary.length,
-			compactedItems: rewrite.segments.compactedWindow.length,
-			postItems: rewrite.segments.post.length,
-			payload: rewrite.rewrittenPayload,
-			originalPayload: payload,
-		},
-		config,
-		ctx,
-	);
-
-	return rewrite.rewrittenPayload;
-}
-
-export default function registerCompactionExtension(
-	pi: ExtensionAPI,
-	overrides: Partial<CompactionDependencies> = {},
-) {
-	const loadConfig = overrides.loadConfig ?? loadToolkitConfig;
-	const piContextHookPatch = installPiContextHookPatch();
-	const contextWindows = overrides.contextWindows ?? new CodexContextWindowManager((ctx, signal) =>
-		loadHistoryNotesThreadHint(ctx, signal, loadConfig().config.compaction.gatewayContextModels)
-	);
-	const dependencies: CompactionDependencies = {
-		loadConfig,
-		remoteCompact: executeRemoteV2Compaction,
-		nativeFallback: runNativeFallbackCompaction,
-		contextWindows,
-		...overrides,
-		piContextHookPatch: overrides.piContextHookPatch ?? piContextHookPatch,
-	};
-	let tools!: ReturnType<typeof registerContextManagementTools>;
-	let contextWindowReady = false;
-	const isContextRuntimeActive = async (
-		ctx: ExtensionContext,
-		config: CompactionConfig,
-		model = ctx.model,
-	): Promise<boolean> =>
-		contextWindowReady && tools.isRegistered && await isRemoteContextActive(ctx, config, model);
-	tools = registerContextManagementTools(
-		pi,
-		contextWindows,
-		async (ctx) => {
-			const config = dependencies.loadConfig().config.compaction;
-			return isContextRuntimeActive(ctx, config);
-		},
-		() => dependencies.loadConfig().config.compaction.gatewayContextModels,
-	);
-	const remoteContextActive: RemoteContextActive = isContextRuntimeActive;
-	const syncTools = async (
-		ctx: ExtensionContext,
-		model = ctx.model,
-		options: { notifyWindowFailure?: boolean } = {},
-	): Promise<ContextToolSyncOutcome> => {
-		// Until this call proves otherwise, do not let a previous session/window
-		// identity make a failed activation look usable.
-		contextWindowReady = false;
-		const config = dependencies.loadConfig().config.compaction;
-		const eligible = await isRemoteContextActive(ctx, config, model);
-		const toolSync = tools.sync(eligible);
-		const outcome: ContextToolSyncOutcome = {
-			eligible,
-			toolsSynced: toolSync.synced,
-			registrationState: toolSync.registrationState,
-			windowInitialized: false,
-		};
-		if (!eligible || !toolSync.synced) return outcome;
-		// Activation can succeed after `session_start` missed it, because Pi 0.86 may
-		// reject the registration read while a session replacement is still binding.
-		// The window lifecycle has to open on that later activation too, or requests
-		// carry no window metadata and the backend never ingests the turns.
-		try {
-			contextWindows.ensureInitialized(pi, ctx, true);
-			contextWindowReady = true;
-			return { ...outcome, windowInitialized: true };
-		} catch {
-			// Do not leave tools exposed while the request path has no valid window
-			// identity. The next lifecycle hook may retry once Pi is usable again.
-			tools.sync(false);
-			if (options.notifyWindowFailure) notifyRemoteContextFailure(ctx, "malformed-window-state");
-			return outcome;
-		}
-	};
-	pi.on("session_start", async (_event, ctx) => {
-		const syncOutcome = await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
-		const active = syncOutcome.eligible && syncOutcome.toolsSynced && syncOutcome.windowInitialized;
-		const { config: toolkitConfig, source, warnings } = dependencies.loadConfig();
-		const config = toolkitConfig.compaction;
-		if (!config.enabled) return;
-
-		let activationReason: string | undefined;
-		// Only models the built-in Remote Context coverage targets may activate or
-		// warn; everything else silently runs Pi's normal compaction path.
-		if (config.contextManagement === "remote" && isCodexContextModel(ctx.model, config) && !active) {
-			if (syncOutcome.registrationState === "conflict") {
-				activationReason = "tool-name-conflict";
-				notifyRemoteContextFailure(ctx, activationReason);
-			} else if (syncOutcome.registrationState === "unverified" || !syncOutcome.toolsSynced) {
-				// Transient: the runtime has not published or accepted our tools yet. A
-				// later before_agent_start re-verifies, so do not report provider failure.
-				activationReason = "tool-registration-pending";
-			} else if (syncOutcome.eligible && !syncOutcome.windowInitialized) {
-				activationReason = "malformed-window-state";
-			} else {
-				const remoteResolution = await resolveCodexContextProvider(ctx, ctx.model, config.gatewayContextModels);
-				activationReason = remoteResolution.ok ? "codex-context-unavailable" : remoteResolution.reason;
-				notifyRemoteContextFailure(ctx, activationReason);
-			}
-		}
-
-		if (warnings.length > 0 && ctx.hasUI && config.debug) {
-			ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: ${warnings[0]}`, "warning");
-		}
-
-		const artifactPath = writeDebugArtifact(
-			"lifecycle",
-			{
-				event: "session_start",
-				config,
-				configSource: source,
-				warnings,
-				activation: {
-					active,
-					contextManagement: config.contextManagement,
-					remoteV2ContextSource: config.remoteV2ContextSource,
-					model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
-					...(activationReason ? { reason: activationReason } : {}),
-				},
-				piContextHookPatch: dependencies.piContextHookPatch,
-			},
-			config,
-			ctx,
-		);
-
-		if (ctx.hasUI && (config.notifyOnLoad || config.debug)) {
-			ctx.ui.notify(
-				artifactPath
-					? `${COMPACTION_EXTENSION_ID} loaded • debug artifacts → ${artifactPath}`
-					: `${COMPACTION_EXTENSION_ID} loaded`,
-				"info",
-			);
-		}
-	});
-
-	pi.on("context", (event, ctx) => handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive));
-	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive));
-	pi.on("session_compact", (event, _ctx) => contextWindows.recordCompaction(event.compactionEntry.details));
-	pi.on("session_shutdown", () => {
-		contextWindowReady = false;
-		contextWindows.reset();
-		tools.reset();
-	});
-	pi.on("agent_settled", async (_event, ctx) => {
-		// Idle: no retry, compaction, or queued continuation is left running, so this is the
-		// only safe place to spend a model call on the user's behalf.
-		await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "turn-end");
-	});
-	pi.on("model_select", async (event, ctx) => {
-		// Switching into a covered model mid-session must open the window
-		// lifecycle immediately: without an identity the request rewrite skips
-		// window metadata, the backend never ingests those turns, and the first
-		// new_context would trim pre-switch history that no history can recover.
-		// syncTools() activates and initializes the window when the model is covered.
-		await syncTools(ctx, event.model, { notifyWindowFailure: true });
-		// The switch itself is the moment the durable transcript changes consumer, and the
-		// session is idle here, so the close-out must happen now rather than mid-turn.
-		await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "model-switch");
-	});
-	pi.on("before_agent_start", async (_event, ctx) => {
-		await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
-	});
-	pi.on("before_provider_request", (event, ctx) => handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive));
-	pi.on("before_provider_headers", async (event, ctx) => {
-		const config = dependencies.loadConfig().config.compaction;
-		if (!isCodexContextModel(ctx.model, config)) return;
-		const active = await remoteContextActive(ctx, config);
-		if (!active) {
-			if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
-				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
-				ctx.abort();
-			}
-			return;
-		}
-		const provider = await resolveCodexContextProvider(ctx, ctx.model, config.gatewayContextModels);
-		if (provider.ok && provider.provider.kind === "codex-gateway") {
-			const sessionId = getSessionId(ctx);
-			const gatewayHeaders = codexContextProviderHeaders(provider.provider, {
-				sessionId,
-				clientRequestId: sessionId,
-			});
-			const allowedGatewayHeaders = new Set<string>(CODEX_GATEWAY_FORWARD_HEADERS);
-			for (const existing of Object.keys(event.headers)) {
-				if (!allowedGatewayHeaders.has(existing.toLowerCase())) delete event.headers[existing];
-			}
-			for (const name of [
-				"authorization",
-				"originator",
-				"user-agent",
-				"version",
-				"session-id",
-				"x-client-request-id",
-				"x-codex-affinity-scope",
-				"x-codex-model",
-			]) {
-				for (const existing of Object.keys(event.headers)) {
-					if (existing.toLowerCase() === name) delete event.headers[existing];
-				}
-				const value = gatewayHeaders.get(name);
-				if (value) event.headers[name] = value;
-			}
-		}
-		contextWindows.rewriteHeaders(event.headers, ctx);
-	});
-	pi.on("message_end", async (event, ctx) => {
-		const config = dependencies.loadConfig().config.compaction;
-		if (!isCodexContextModel(ctx.model, config) || !tools.isRegistered) return undefined;
-		if (!(await remoteContextActive(ctx, config))) return undefined;
-		const message = routeContextNamespaceToolMessage(event.message);
-		return message === event.message ? undefined : { message };
-	});
-}
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type {
+	BeforeProviderRequestEvent,
+	ContextEvent,
+	CompactionResult,
+	ExtensionAPI,
+	ExtensionContext,
+	SessionBeforeCompactEvent,
+} from "@earendil-works/pi-coding-agent";
+import { assertConfigValid, loadToolkitConfig, resolveToolkitConfig, type ResolvedToolkitConfig } from "./config";
+import { notifyConfigIssues } from "./config/notifications";
+import { registerToolkitConfigCommand } from "./config-command";
+import {
+	codexContextProviderHeaders,
+	resolveCodexContextProvider,
+	isCodexGatewayModel,
+	isNativeCodexModel,
+} from "./context-management/codex-provider";
+import { routeContextNamespaceToolMessage } from "./context-management/namespace-tools";
+import { loadHistoryNotesThreadHint } from "./context-management/history-notes";
+import { CodexContextWindowManager } from "./context-management/window-manager";
+import {
+	BULK_CLIFF_RATIO,
+	decideBulkCliffAction,
+	decideBulkCloseOut,
+	evaluateWindowBulk,
+} from "./context-management/window-bulk";
+import {
+	registerContextManagementTools,
+	type ContextToolRegistrationState,
+} from "./context-management/tools";
+import { writeDebugArtifact, writeReplayFailureArtifact } from "./debug";
+import {
+	COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
+	COMPACTION_PROJECTION_UNAVAILABLE,
+	COMPACTION_SESSION_CONTEXT_UNAVAILABLE,
+	COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE,
+	hasVerifiedCompactionInputProvenance,
+	type UnprojectedCompactionReason,
+} from "./compaction-projection";
+import { CODEX_GATEWAY_FORWARD_HEADERS } from "./responses-headers";
+import { resolveLatestNativeCompactionEntry } from "./details-store";
+import {
+	getPiContextHookProjector,
+	installPiContextHookPatch,
+	reportPiContextHookFailure,
+	type PiContextHookPatchResult,
+} from "./pi-context-hook";
+import { runNativeFallbackCompaction } from "./native-fallback";
+import {
+	rewriteResponsesPayloadWithNativeReplay,
+	removeNativeCompactionRetainedMessages,
+	serializeLiveTailToResponsesInput,
+} from "./payload-rewrite";
+import { getCompactionRequestExtras, rememberRequestContext } from "./request-context-cache";
+import { resolveWebSearchRoute } from "./web-search/types";
+import { executeRemoteV2Compaction } from "./remote-v2-client";
+import {
+	resolveNativeCompactionEnvironment,
+	resolveRemoteCompactionExecution,
+	parseModelSpec,
+	type RemoteCompactionExecution,
+} from "./runtime";
+import {
+	serializeMessagesToCompactRequest,
+	serializeMessagesToResponsesInput,
+	type NativeCompactionRequestBody,
+	type ResponsesInputItem,
+} from "./serializer";
+import {
+	createNativeCompactionDetails,
+	createNativeCompactionResult,
+	COMPACTION_EXTENSION_ID,
+	getLatestDeferredToolCarryover,
+	getRemoteV2InputProvenance,
+	isNativeCompactionDetails,
+	type CompactionConfig,
+	type NativeCompactionDetails,
+	type NativeCompactionRequestMeta,
+} from "./types";
+
+type CompactionContextProjection = (
+	messages: readonly AgentMessage[],
+	ctx: ExtensionContext,
+) => readonly AgentMessage[] | undefined | Promise<readonly AgentMessage[] | undefined>;
+
+function contextOperation(loadConfig: typeof loadToolkitConfig, ctx: ExtensionContext, model = ctx.model): ResolvedToolkitConfig {
+	const loaded = loadConfig();
+	const resolved = resolveToolkitConfig(loaded, model);
+	notifyConfigIssues(ctx, resolved);
+	return resolved;
+}
+
+function requireContextPolicy(resolved: ResolvedToolkitConfig, ctx: ExtensionContext): void {
+	try {
+		assertConfigValid(resolved, "context", "compatibility", "diagnostics");
+	} catch (error) {
+		if (typeof ctx.abort === "function") ctx.abort();
+		throw error;
+	}
+}
+
+function compactGatewayModels(resolved: ResolvedToolkitConfig): readonly string[] {
+	return resolved.format === "v2" || resolved.config.compaction.contextManagement === "remote"
+		? resolved.gatewayModelKeys : [];
+}
+
+type CompactionDependencies = {
+	loadConfig: typeof loadToolkitConfig;
+	remoteCompact: typeof executeRemoteV2Compaction;
+	nativeFallback: typeof runNativeFallbackCompaction;
+	contextWindows: CodexContextWindowManager;
+	/** Test seam for the same ordered projection exposed by the Pi host patch. */
+	projectCompactionContext?: CompactionContextProjection;
+	piContextHookPatch: PiContextHookPatchResult;
+};
+
+type RemoteContextActive = (
+	ctx: ExtensionContext,
+	config: CompactionConfig,
+	model?: ExtensionContext["model"],
+) => Promise<boolean>;
+
+type ContextToolSyncOutcome = {
+	eligible: boolean;
+	toolsSynced: boolean;
+	registrationState: ContextToolRegistrationState;
+	windowInitialized: boolean;
+};
+
+type ResponsesCompactOutcome =
+	| { outcome: "success"; compaction: CompactionResult<NativeCompactionDetails> }
+	| { outcome: "aborted" }
+	| { outcome: "failed" }
+	| {
+			outcome: "unprojected-input";
+			reason: UnprojectedCompactionReason;
+	  };
+
+function buildCompactionRequestMeta(event: SessionBeforeCompactEvent): NativeCompactionRequestMeta {
+	return {
+		tokensBefore: event.preparation.tokensBefore,
+		previousSummaryPresent: Boolean(event.preparation.previousSummary),
+	};
+}
+
+function getCurrentModelDebugInfo(ctx: ExtensionContext) {
+	return ctx.model
+		? {
+			provider: ctx.model.provider,
+			id: ctx.model.id,
+		}
+		: undefined;
+}
+
+function getCompactionIdentityDebugInfo(entry: { details?: unknown } | undefined) {
+	return isNativeCompactionDetails(entry?.details)
+		? {
+			provider: entry.details.provider,
+			api: entry.details.api,
+			model: entry.details.model,
+			baseUrl: entry.details.baseUrl,
+			compactionModel: entry.details.compactionModel,
+		}
+		: undefined;
+}
+
+function getSessionId(ctx: ExtensionContext): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionId();
+	} catch {
+		return undefined;
+	}
+}
+
+function notifyWarning(ctx: ExtensionContext, message: string): void {
+	if (ctx.hasUI) {
+		ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: ${message}`, "warning");
+	}
+}
+
+async function isRemoteContextActive(
+	ctx: ExtensionContext,
+	config: CompactionConfig,
+	model: ExtensionContext["model"] = ctx.model,
+): Promise<boolean> {
+	if (!config.enabled || config.contextManagement !== "remote") return false;
+	const resolution = await resolveCodexContextProvider(ctx, model, config.gatewayContextModels);
+	return resolution.ok;
+}
+
+function isCodexContextModel(
+	model: ExtensionContext["model"] | undefined,
+	config: CompactionConfig,
+): boolean {
+	return config.contextManagement === "remote"
+		&& (isNativeCodexModel(model) || isCodexGatewayModel(model, config.gatewayContextModels));
+}
+
+function notifyRemoteContextFailure(ctx: ExtensionContext, reason: string): void {
+	if (ctx.hasUI) {
+		ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: Remote Context management inactive (${reason})`, "warning");
+	}
+}
+
+/**
+ * Surface every window trim that had to be refused to keep the tool loadout intact.
+ *
+ * The refusal itself is safe: the model keeps the previous turns instead of losing its
+ * tools. It is still a continuity incident, so it is recorded once per window and reason
+ * instead of being allowed to pass silently.
+ */
+function reportProjectionDiagnostics(
+	contextWindows: CodexContextWindowManager,
+	config: CompactionConfig,
+	ctx: ExtensionContext,
+): void {
+	const diagnostics = contextWindows.takeProjectionDiagnostics();
+	if (diagnostics.length === 0) return;
+	writeDebugArtifact(
+		"compaction-event",
+		{ event: "context.projection.tool_loadout_shrink", diagnostics },
+		config,
+		ctx,
+	);
+	if (ctx.hasUI) {
+		ctx.ui.notify(
+			`${COMPACTION_EXTENSION_ID}: kept previous context to preserve tools (${diagnostics.join("; ")})`,
+			"warning",
+		);
+	}
+}
+
+function cloneOpaqueWindow(window: readonly unknown[]): unknown[] {
+	return window.map((item) => structuredClone(item));
+}
+
+function buildCompactionInstructions(systemPrompt: string, customInstructions?: string): string {
+	const guidance = customInstructions?.trim();
+	if (!guidance) {
+		return systemPrompt;
+	}
+
+	return `${systemPrompt}\n\nAdditional user guidance for this manual /compact request:\n${guidance}`;
+}
+
+function findLatestProjectedCompactionSummaryIndex(
+	messages: readonly AgentMessage[],
+	summary: string,
+): number {
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index];
+		if (message?.role === "compactionSummary" && message.summary === summary) {
+			return index;
+		}
+	}
+
+	return -1;
+}
+
+type SessionManagerWithOptionalContext = ExtensionContext["sessionManager"] & {
+	buildSessionContext?: () => { messages?: readonly AgentMessage[] };
+};
+
+function readSessionContextMessages(ctx: ExtensionContext): AgentMessage[] | undefined {
+	const sessionManager = ctx.sessionManager as SessionManagerWithOptionalContext;
+	if (typeof sessionManager.buildSessionContext !== "function") {
+		return undefined;
+	}
+
+	try {
+		const sessionContext = sessionManager.buildSessionContext();
+		if (!sessionContext || !Array.isArray(sessionContext.messages)) {
+			return undefined;
+		}
+		return structuredClone([...sessionContext.messages]);
+	} catch {
+		return undefined;
+	}
+}
+
+type CompactionProjectionResult =
+	| { ok: true; messages: readonly AgentMessage[] }
+	| { ok: false; reason: typeof COMPACTION_PROJECTION_UNAVAILABLE | typeof COMPACTION_SESSION_CONTEXT_UNAVAILABLE };
+
+async function projectSessionContextForCompaction(
+	ctx: ExtensionContext,
+	projectCompactionContext: CompactionContextProjection | undefined,
+): Promise<CompactionProjectionResult> {
+	const messages = readSessionContextMessages(ctx);
+	if (!messages) {
+		return { ok: false, reason: COMPACTION_SESSION_CONTEXT_UNAVAILABLE };
+	}
+
+	const projector = projectCompactionContext ?? getPiContextHookProjector(ctx);
+	if (!projector) {
+		return { ok: false, reason: COMPACTION_PROJECTION_UNAVAILABLE };
+	}
+
+	try {
+		const projected = await projector(messages, ctx);
+		return Array.isArray(projected)
+			? { ok: true, messages: projected }
+			: { ok: false, reason: COMPACTION_PROJECTION_UNAVAILABLE };
+	} catch {
+		return { ok: false, reason: COMPACTION_PROJECTION_UNAVAILABLE };
+	}
+}
+
+function getLegacySessionContextMessages(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+): AgentMessage[] {
+	return readSessionContextMessages(ctx) ?? [
+		...event.preparation.messagesToSummarize,
+		...event.preparation.turnPrefixMessages,
+	];
+}
+
+async function runResponsesNativeCompact(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+	config: CompactionConfig,
+	execution: RemoteCompactionExecution,
+	remoteCompact: typeof executeRemoteV2Compaction,
+	projectCompactionContext: CompactionContextProjection | undefined,
+): Promise<ResponsesCompactOutcome> {
+	const { consumer, compactor } = execution;
+	const instructions = buildCompactionInstructions(ctx.getSystemPrompt(), event.customInstructions);
+	const branchEntries = event.branchEntries ?? ctx.sessionManager.getBranch();
+	const deferredToolCarryover = getLatestDeferredToolCarryover(branchEntries);
+	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
+		baseUrl: consumer.baseUrl,
+	});
+
+	const inputProvenance = getRemoteV2InputProvenance(config.remoteV2ContextSource);
+	let requestSource: "session-context" | "non-native-session-context" | "latest-native-replay";
+	let request: NativeCompactionRequestBody;
+	if (latestNativeCompaction.ok) {
+		const details = latestNativeCompaction.entry.details;
+		if (!details) {
+			return { outcome: "failed" };
+		}
+		if (!hasVerifiedCompactionInputProvenance(details, inputProvenance)) {
+			return {
+				outcome: "unprojected-input",
+				reason: COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
+			};
+		}
+		requestSource = "latest-native-replay";
+
+		if (config.remoteV2ContextSource === "pi-context-hook") {
+			const projection = await projectSessionContextForCompaction(ctx, projectCompactionContext);
+			if (!projection.ok) {
+				return { outcome: "unprojected-input", reason: projection.reason };
+			}
+			const summaryIndex = findLatestProjectedCompactionSummaryIndex(
+				projection.messages,
+				latestNativeCompaction.entry.summary,
+			);
+			if (summaryIndex < 0) {
+				return {
+					outcome: "unprojected-input",
+					reason: COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE,
+				};
+			}
+			const input: ResponsesInputItem[] = [
+				...(cloneOpaqueWindow(details.compactedWindow) as ResponsesInputItem[]),
+				...serializeMessagesToResponsesInput(
+					compactor.currentModel,
+					[...projection.messages.slice(summaryIndex + 1)],
+					{ firstSystemMessageIsUpdate: true },
+				),
+			];
+			request = {
+				model: compactor.model,
+				input,
+				instructions,
+			};
+		} else {
+			const liveTailEntries = branchEntries.slice(latestNativeCompaction.index + 1);
+			const input: ResponsesInputItem[] = [
+				...(cloneOpaqueWindow(details.compactedWindow) as ResponsesInputItem[]),
+				...serializeLiveTailToResponsesInput({ model: compactor.currentModel, entries: liveTailEntries }),
+			];
+			request = {
+				model: compactor.model,
+				input,
+				instructions,
+			};
+		}
+	} else if (
+		latestNativeCompaction.reason === "no-compaction" ||
+		(latestNativeCompaction.reason === "latest-compaction-not-native" &&
+			config.allowCompactionContinuityBreak)
+	) {
+		requestSource =
+			latestNativeCompaction.reason === "no-compaction" ? "session-context" : "non-native-session-context";
+		if (config.remoteV2ContextSource === "pi-context-hook") {
+			const projection = await projectSessionContextForCompaction(ctx, projectCompactionContext);
+			if (!projection.ok) {
+				return { outcome: "unprojected-input", reason: projection.reason };
+			}
+			request = serializeMessagesToCompactRequest({
+				model: compactor.currentModel,
+				messages: [...projection.messages],
+				instructions,
+			});
+		} else {
+			request = serializeMessagesToCompactRequest({
+				model: compactor.currentModel,
+				messages: getLegacySessionContextMessages(event, ctx),
+				instructions,
+			});
+		}
+	} else {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.remote-v2-skip",
+				reason: latestNativeCompaction.reason,
+				consumer: {
+					provider: consumer.provider,
+					api: consumer.api,
+					model: consumer.model,
+					baseUrl: consumer.baseUrl,
+				},
+				compactor: {
+					provider: compactor.provider,
+					api: compactor.api,
+					model: compactor.model,
+					baseUrl: compactor.baseUrl,
+				},
+				latestCompactionIndex: latestNativeCompaction.latestCompactionIndex,
+				latestCompactionIdentity: getCompactionIdentityDebugInfo(latestNativeCompaction.latestCompaction),
+			},
+			config,
+			ctx,
+		);
+		return { outcome: "failed" };
+	}
+
+	// Mirror the latest codex_rs CompactionInput fields captured from the most
+	// recent live provider request for this model (tools, reasoning, etc.).
+	const extras = getCompactionRequestExtras({
+		provider: consumer.provider,
+		api: consumer.api,
+		model: consumer.model,
+		baseUrl: consumer.baseUrl,
+		sessionId: getSessionId(ctx),
+	}, compactor.currentModel);
+	if (extras) {
+		request = { ...request, ...extras };
+	}
+
+	const compactResult = await remoteCompact({
+		runtime: compactor,
+		request,
+		signal: event.signal,
+		settings: config,
+		context: ctx,
+	});
+
+	if (compactResult.ok === false) {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.remote-v2-failure",
+				reason: compactResult.reason,
+				status: compactResult.status,
+				errorMessage: compactResult.errorMessage,
+			},
+			config,
+			ctx,
+		);
+		return compactResult.reason === "aborted" ? { outcome: "aborted" } : { outcome: "failed" };
+	}
+
+	let details: NativeCompactionDetails;
+	try {
+		details = createNativeCompactionDetails({
+			provider: consumer.provider,
+			api: consumer.api,
+			model: consumer.model,
+			baseUrl: consumer.baseUrl,
+			compactionModel: {
+				provider: compactor.provider,
+				api: compactor.api,
+				model: compactor.model,
+				baseUrl: compactor.baseUrl,
+			},
+			deferredToolCarryover,
+			compactedWindow: compactResult.compactedWindow,
+			compactResponseId: compactResult.compactResponseId,
+			createdAt: compactResult.createdAt,
+			requestMeta: buildCompactionRequestMeta(event),
+			inputProvenance,
+		});
+	} catch (error) {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.invalid-native-details",
+				reason: error instanceof Error ? error.message : String(error),
+				consumer: {
+					provider: consumer.provider,
+					api: consumer.api,
+					model: consumer.model,
+					baseUrl: consumer.baseUrl,
+				},
+				compactor: {
+					provider: compactor.provider,
+					api: compactor.api,
+					model: compactor.model,
+					baseUrl: compactor.baseUrl,
+				},
+			},
+			config,
+			ctx,
+		);
+		return { outcome: "failed" };
+	}
+
+	const compaction = createNativeCompactionResult({
+		firstKeptEntryId: event.preparation.firstKeptEntryId,
+		tokensBefore: event.preparation.tokensBefore,
+		details,
+	});
+
+	writeDebugArtifact(
+		"compaction-event",
+		{
+			event: "session_before_compact.remote-v2-success",
+			consumer: {
+				provider: consumer.provider,
+				api: consumer.api,
+				model: consumer.model,
+				baseUrl: consumer.baseUrl,
+			},
+			compactor: {
+				provider: compactor.provider,
+				api: compactor.api,
+				model: compactor.model,
+				baseUrl: compactor.baseUrl,
+			},
+			requestSource,
+			remoteV2ContextSource: config.remoteV2ContextSource,
+			inputProvenance,
+			requestInputItems: request.input.length,
+			requestExtras: extras ? Object.keys(extras) : [],
+			compactResponseId: compactResult.compactResponseId,
+			compactedItems: compactResult.compactedWindow.length,
+			firstKeptEntryId: event.preparation.firstKeptEntryId,
+		},
+		config,
+		ctx,
+	);
+
+	return { outcome: "success", compaction };
+}
+
+async function handleSessionBeforeCompact(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+	dependencies: CompactionDependencies,
+	remoteContextActive: RemoteContextActive,
+) {
+	const resolved = contextOperation(dependencies.loadConfig, ctx);
+	if (resolved.invalidFeatures.some((feature) => ["context", "compatibility", "diagnostics"].includes(feature))) return { cancel: true };
+	const config = resolved.config.compaction;
+	if (!config.enabled) {
+		return undefined;
+	}
+
+	writeDebugArtifact(
+		"compaction-event",
+		{
+			event: "session_before_compact",
+			customInstructions: event.customInstructions,
+			preparation: {
+				tokensBefore: event.preparation.tokensBefore,
+				firstKeptEntryId: event.preparation.firstKeptEntryId,
+				previousSummaryPresent: Boolean(event.preparation.previousSummary),
+				messagesToSummarizeCount: event.preparation.messagesToSummarize.length,
+				turnPrefixMessagesCount: event.preparation.turnPrefixMessages.length,
+			},
+		},
+		config,
+		ctx,
+	);
+
+	if (event.signal.aborted) {
+		return { cancel: true };
+	}
+
+	// Remote Context management owns this eligible Codex session. It persists a
+	// no-summary boundary and deliberately never calls remote_compaction_v2.
+	if (isCodexContextModel(ctx.model, config)) {
+		if (await remoteContextActive(ctx, config)) {
+			try {
+				dependencies.contextWindows.synchronize(ctx);
+				return dependencies.contextWindows.prepareCompaction(event);
+			} catch {
+				notifyRemoteContextFailure(ctx, "malformed-window-state");
+				return { cancel: true };
+			}
+		}
+		// A configured native Codex Remote session must never re-enter this
+		// extension's Remote V2 compaction chain, and Pi's native compaction is
+		// deliberately disabled for Remote-managed models: cancelling here keeps
+		// the boundary the only rollover mechanism. The inactive reason is
+		// surfaced so the user can fix activation instead of losing context to a
+		// silent native summary.
+		notifyRemoteContextFailure(ctx, "native-codex-context-unavailable");
+		return { cancel: true };
+	}
+
+	// Resolve producer protocol policy from this operation's document, not a later disk read.
+	if (resolved.format === "v2" && config.remoteCompactModel) {
+		const producer = parseModelSpec(config.remoteCompactModel);
+		if (producer) {
+			const producerPolicy = resolveToolkitConfig(resolved.snapshot, { provider: producer.provider, id: producer.modelId });
+			notifyConfigIssues(ctx, producerPolicy);
+			if (producerPolicy.invalidFeatures.includes("compatibility")) return { cancel: true };
+		}
+	}
+	// Branch 1: Responses-family APIs use remote_compaction_v2 on the normal Responses stream.
+	let remoteAttempted = false;
+	const resolution = await resolveRemoteCompactionExecution(
+		ctx,
+		{
+			enabled: config.enabled,
+			responsesApis: config.responsesApis,
+			codexGatewayModels: compactGatewayModels(resolved),
+		},
+		config.remoteCompactModel,
+	);
+	if (resolution.ok) {
+		remoteAttempted = true;
+		const responsesOutcome = await runResponsesNativeCompact(
+			event,
+			ctx,
+			config,
+			resolution.execution,
+			dependencies.remoteCompact,
+			dependencies.projectCompactionContext,
+		);
+		if (responsesOutcome.outcome === "success") {
+			return { compaction: responsesOutcome.compaction };
+		}
+		if (responsesOutcome.outcome === "aborted") {
+			return { cancel: true };
+		}
+		if (responsesOutcome.outcome === "unprojected-input") {
+			const message = responsesOutcome.reason === COMPACTION_PROJECTION_UNAVAILABLE
+				? "Pi's ordered context-hook projection is unavailable; Remote V2 was not sent raw session history."
+				: responsesOutcome.reason === COMPACTION_SESSION_CONTEXT_UNAVAILABLE
+					? "Pi did not provide the current session context required by its context-hook projection."
+					: responsesOutcome.reason === COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE
+						? "Pi's projected context did not include the current compaction summary anchor."
+						: "The latest opaque checkpoint has no marker for the configured Remote V2 context source, or was created in the other mode.";
+			writeDebugArtifact(
+				"compaction-event",
+				{
+					event: "session_before_compact.remote-v2-unprojected-input",
+					reason: responsesOutcome.reason,
+					contextSource: config.remoteV2ContextSource,
+					inputProvenance: getRemoteV2InputProvenance(config.remoteV2ContextSource),
+					piContextHookPatch: dependencies.piContextHookPatch,
+					message,
+				},
+				config,
+				ctx,
+			);
+			notifyWarning(
+				ctx,
+				`Remote V2 compaction cancelled (${responsesOutcome.reason}); ${message} Keep the context-source setting aligned with the checkpoint or choose legacy mode explicitly.`,
+			);
+			return { cancel: true };
+		}
+		// failed: fall through to the configured-model fallback below.
+	} else {
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.remote-v2-unavailable",
+				reason: resolution.reason,
+				provider: resolution.provider,
+				api: resolution.api,
+				model: resolution.model,
+				baseUrl: resolution.baseUrl,
+				modelSpec: resolution.modelSpec,
+				errorMessage: resolution.errorMessage,
+			},
+			config,
+			ctx,
+		);
+		if (config.remoteCompactModel) {
+			notifyWarning(
+				ctx,
+				`remote compaction model "${config.remoteCompactModel}" unusable (${resolution.reason}); using the native fallback chain`,
+			);
+		}
+	}
+
+	// Branch 2: run pi's native compaction method. A failed remote request is compacted by the
+	// remote producer itself; a model that cannot use remote v2 at all uses nativeFallback.model.
+	const fallbackModelSpec = remoteAttempted ? config.remoteCompactModel : config.nativeFallback.model;
+	const fallback = await dependencies.nativeFallback({ ctx, event, config, modelSpec: fallbackModelSpec });
+	if (fallback.ok) {
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`${COMPACTION_EXTENSION_ID}: compacted with ${fallback.model.provider}/${fallback.model.id} (native method)`,
+				"info",
+			);
+		}
+		writeDebugArtifact(
+			"compaction-event",
+			{
+				event: "session_before_compact.fallback-success",
+				model: fallback.model,
+			},
+			config,
+			ctx,
+		);
+		return { compaction: fallback.result };
+	}
+
+	if (fallback.reason === "aborted") {
+		return { cancel: true };
+	}
+
+	writeDebugArtifact(
+		"compaction-event",
+		{
+			event: "session_before_compact.fallback-skip",
+			reason: fallback.reason,
+			modelSpec: fallback.modelSpec,
+			errorMessage: fallback.errorMessage,
+			...(fallback.estimatedTokens === undefined ? {} : { estimatedTokens: fallback.estimatedTokens }),
+			...(fallback.contextWindow === undefined ? {} : { contextWindow: fallback.contextWindow }),
+		},
+		config,
+		ctx,
+	);
+
+	// Intentional pi-default paths: feature disabled, nothing configured, or it matches the current one.
+	const intentionalSkip =
+		fallback.reason === "disabled" ||
+		fallback.reason === "no-model-configured" ||
+		fallback.reason === "same-as-current-model";
+	if (fallback.reason === "model-window-too-small") {
+		// The configured summary model is narrower than the request Pi would send for it.
+		// Skipping is the success path here: pi's current model gets one chance instead of
+		// the provider terminating the oversized summary.
+		notifyWarning(
+			ctx,
+			`compaction summary model "${fallback.modelSpec}" cannot fit ~${fallback.estimatedTokens} tokens in its ${fallback.contextWindow} window; compacting with the current model instead`,
+		);
+	} else if (!intentionalSkip) {
+		notifyWarning(
+			ctx,
+			`compaction model "${fallback.modelSpec}" unusable (${fallback.reason}${fallback.errorMessage ? `: ${fallback.errorMessage}` : ""}); using pi's default compaction`,
+		);
+	}
+
+	// Branch 3: pi's default native compaction with the current model.
+	return undefined;
+}
+
+/**
+ * Surface (and optionally close) the gap between the durable transcript and the remote window.
+ *
+ * Remote context management retires previous windows in the request projection, so a covered
+ * model never notices that the branch still carries every one of them. Switching to a model
+ * without remote context - or resuming such a session - hands that whole pile to the provider
+ * at once, and the first manual `/compact` then has to summarize it. Runs once per agent turn,
+ * never per request, and only once per window and model so the notice cannot become a nag.
+ */
+async function handleWindowBulk(
+	ctx: ExtensionContext,
+	contextWindows: CodexContextWindowManager,
+	loadConfig: typeof loadToolkitConfig,
+	trigger: "model-switch" | "turn-end",
+	resolved = contextOperation(loadConfig, ctx),
+): Promise<void> {
+	requireContextPolicy(resolved, ctx);
+	const compaction = resolved.config.compaction;
+	if (!compaction.enabled || compaction.contextManagement !== "remote") return;
+	if (!ctx.model) return;
+
+	const modelKey = `${ctx.model.provider}/${ctx.model.id}`;
+	const report = evaluateWindowBulk(ctx);
+	if (!report) return;
+	contextWindows.noteWindowBulk(report, modelKey);
+	const cliff = contextWindows.takeBulkCliff(modelKey);
+	if (!cliff) return;
+	const action = decideBulkCloseOut({
+		action: decideBulkCliffAction(cliff, compaction.leaveManagedMode),
+		mode: ctx.mode,
+		trigger,
+		hasPendingTrim: contextWindows.hasPendingTrim(),
+	});
+	if (action === "ignore") return;
+
+	writeDebugArtifact(
+		"compaction-event",
+		{
+			event: `window-bulk.${action}`,
+			trigger,
+			policy: compaction.leaveManagedMode,
+			model: modelKey,
+			unmanagedTokens: cliff.unmanagedTokens,
+			managedTokens: cliff.managedTokens,
+			targetContextWindow: cliff.targetContextWindow,
+			overBudget: cliff.overBudget,
+		},
+		compaction,
+		ctx,
+	);
+
+	const gap = `${cliff.unmanagedTokens.toLocaleString()} tokens of retired windows are still in this session's transcript, while remote context management has been sending ${cliff.managedTokens.toLocaleString()}`;
+	if (action === "warn") {
+		notifyWarning(
+			ctx,
+			`${gap} to ${modelKey}${cliff.overBudget ? `, past ${Math.round(BULK_CLIFF_RATIO * 100)}% of its window` : ""}. Checkpoint with notes and run /compact (or new_context) before continuing on a model without remote context, or set compaction.leaveManagedMode="compact" to do it automatically.`,
+		);
+		return;
+	}
+
+	notifyWarning(ctx, `${gap} to ${modelKey}, past ${Math.round(BULK_CLIFF_RATIO * 100)}% of its window; compacting the retired windows first.`);
+	if (typeof ctx.compact !== "function") return;
+	ctx.compact({
+		onError: (error: Error) => {
+			notifyWarning(ctx, `automatic boundary compaction failed: ${error.message}`);
+		},
+	});
+}
+
+async function handleContextInternal(
+	event: ContextEvent,
+	ctx: ExtensionContext,
+	pi: ExtensionAPI,
+	loadConfig: typeof loadToolkitConfig,
+	contextWindows: CodexContextWindowManager,
+	remoteContextActive: RemoteContextActive,
+) {
+	const resolved = contextOperation(loadConfig, ctx);
+	requireContextPolicy(resolved, ctx);
+	const config = resolved.config.compaction;
+	if (!config.enabled) {
+		const visibleMessages = contextWindows.project(event.messages, "off");
+		return visibleMessages.length === event.messages.length && visibleMessages.every((message, index) => message === event.messages[index])
+			? undefined
+			: { messages: visibleMessages };
+	}
+
+	if (config.contextManagement === "remote") {
+		try {
+			contextWindows.synchronize(ctx);
+		} catch {
+			notifyRemoteContextFailure(ctx, "malformed-window-state");
+			reportPiContextHookFailure(ctx, "malformed-window-state");
+			ctx.abort();
+			return undefined;
+		}
+
+		const remoteActive = await remoteContextActive(ctx, config);
+		if (remoteActive) {
+			try {
+				contextWindows.recordBudget(
+					pi,
+					ctx,
+					true,
+					config.contextReminderThresholdPercent,
+				);
+				const projected = contextWindows.project(event.messages, "remote");
+				reportProjectionDiagnostics(contextWindows, config, ctx);
+				return projected.length === event.messages.length && projected.every((message, index) => message === event.messages[index])
+					? undefined
+					: { messages: projected };
+			} catch (error) {
+				notifyRemoteContextFailure(ctx, "malformed-window-state");
+				reportPiContextHookFailure(ctx, "malformed-window-state");
+				ctx.abort();
+				return undefined;
+			}
+		}
+
+		// An eligible Codex Remote session is never allowed to fall through to the
+		// older compaction-replay path. Gateway traffic must also fail closed when
+		// its transport capability is unavailable; otherwise Pi could send an
+		// ordinary unscoped request and lose CPA OAuth/session affinity.
+		if (isCodexContextModel(ctx.model, config)) {
+			if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
+				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
+				reportPiContextHookFailure(ctx, "codex-context-unavailable");
+				ctx.abort();
+				return undefined;
+			}
+			const visibleMessages = contextWindows.project(event.messages, "off");
+			return visibleMessages.length === event.messages.length && visibleMessages.every((message, index) => message === event.messages[index])
+				? undefined
+				: { messages: visibleMessages };
+		}
+	}
+
+	// Inactive/ineligible Remote mode must not expose internal window markers to a
+	// gateway or another provider. The existing compaction replay path remains the
+	// owner for this safe fallback.
+	const visibleMessages = contextWindows.project(event.messages, "off");
+	const replayEvent = visibleMessages === event.messages ? event : { ...event, messages: visibleMessages };
+	const resolution = await resolveNativeCompactionEnvironment(ctx, {
+		enabled: config.enabled,
+		responsesApis: config.responsesApis,
+		codexGatewayModels: compactGatewayModels(resolved),
+	});
+	if (!resolution.ok) return undefined;
+	const branchEntries = ctx.sessionManager.getBranch();
+	const latest = resolveLatestNativeCompactionEntry(branchEntries, { baseUrl: resolution.runtime.baseUrl });
+	if (!latest.ok) return undefined;
+	const result = removeNativeCompactionRetainedMessages({
+		messages: replayEvent.messages,
+		branchEntries,
+		compactionEntry: latest.entry,
+		expectedInputProvenance: getRemoteV2InputProvenance(config.remoteV2ContextSource),
+	});
+	if (!result.ok) {
+		writeReplayFailureArtifact({ reason: result.reason, compactionEntryId: latest.entry.id }, config, ctx);
+		if (ctx.hasUI) ctx.ui.notify(`${COMPACTION_EXTENSION_ID}: replay failed (${result.reason}); request aborted`, "error");
+		reportPiContextHookFailure(ctx, `replay-failed:${result.reason}`);
+		ctx.abort();
+		return undefined;
+	}
+	return result.messages === replayEvent.messages ? undefined : { messages: result.messages };
+}
+
+/**
+ * Pi's emitContext() catches handler exceptions. Re-throw as usual for Pi, but
+ * also report the failure so the compaction projector cannot mistake the
+ * caught exception for a successful projection.
+ */
+async function handleContext(
+	event: ContextEvent,
+	ctx: ExtensionContext,
+	pi: ExtensionAPI,
+	loadConfig: typeof loadToolkitConfig,
+	contextWindows: CodexContextWindowManager,
+	remoteContextActive: RemoteContextActive,
+) {
+	try {
+		return await handleContextInternal(event, ctx, pi, loadConfig, contextWindows, remoteContextActive);
+	} catch (error) {
+		reportPiContextHookFailure(ctx, error instanceof Error ? error.message : String(error));
+		throw error;
+	}
+}
+
+async function handleBeforeProviderRequest(
+	event: BeforeProviderRequestEvent,
+	ctx: ExtensionContext,
+	loadConfig: typeof loadToolkitConfig,
+	contextWindows: CodexContextWindowManager,
+	remoteContextActive: RemoteContextActive,
+) {
+	const resolved = contextOperation(loadConfig, ctx);
+	requireContextPolicy(resolved, ctx);
+	const toolkitConfig = resolved.config;
+	const config = toolkitConfig.compaction;
+	if (!config.enabled) {
+		return undefined;
+	}
+
+	if (config.contextManagement === "remote") {
+		try {
+			contextWindows.synchronize(ctx);
+		} catch {
+			notifyRemoteContextFailure(ctx, "malformed-window-state");
+			ctx.abort();
+			return undefined;
+		}
+	}
+	if (config.contextManagement === "remote" && await remoteContextActive(ctx, config)) {
+		try {
+			return contextWindows.rewritePayload(event.payload, ctx);
+		} catch {
+			notifyRemoteContextFailure(ctx, "malformed-request-state");
+			ctx.abort();
+			return undefined;
+		}
+	}
+	if (isCodexContextModel(ctx.model, config)) {
+		// Keep Codex Remote mutually exclusive with the legacy replay pipeline
+		// when authentication or tool ownership is unavailable. Gateway traffic
+		// cannot continue as an ordinary Responses request because that would
+		// silently lose the required CPA session/account selection.
+		if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
+			notifyRemoteContextFailure(ctx, "codex-context-unavailable");
+			ctx.abort();
+		}
+		return undefined;
+	}
+
+	const resolution = await resolveNativeCompactionEnvironment(
+		ctx,
+		{
+			enabled: config.enabled,
+			responsesApis: config.responsesApis,
+			codexGatewayModels: compactGatewayModels(resolved),
+		},
+		event.payload,
+	);
+	if (resolution.ok === false) {
+		writeDebugArtifact(
+			"provider-request",
+			{
+				event: "before_provider_request.skip",
+				reason: resolution.reason,
+				provider: resolution.provider,
+				api: resolution.api,
+				model: resolution.model,
+				baseUrl: resolution.baseUrl,
+				errorMessage: resolution.errorMessage,
+				currentModel: getCurrentModelDebugInfo(ctx),
+				payload: event.payload,
+			},
+			config,
+			ctx,
+		);
+		return undefined;
+	}
+
+	const runtime = resolution.runtime;
+	const payload = runtime.payload;
+	if (!payload) {
+		return undefined;
+	}
+
+	// Capture compact-relevant request fields (tools, reasoning, ...) for the next
+	// synthetic compact request using the active consumer's effective runtime identity.
+	// This hook runs before the separate Web Search transform, so injected native search
+	// tools are not copied into remote_compaction_v2.
+	const webSearchRoute = resolveWebSearchRoute({ model: ctx.model, config: toolkitConfig.webSearch });
+	rememberRequestContext(
+		payload,
+		{
+			provider: runtime.provider,
+			api: runtime.api,
+			model: runtime.model,
+			baseUrl: runtime.baseUrl,
+			sessionId: getSessionId(ctx),
+		},
+		{
+			excludeWebSearchTools: webSearchRoute.route === "standalone-alpha",
+		},
+	);
+
+	const branchEntries = ctx.sessionManager.getBranch();
+	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
+		baseUrl: runtime.baseUrl,
+	});
+	if (!latestNativeCompaction.ok) {
+		writeDebugArtifact(
+			"provider-request",
+			{
+				event: "before_provider_request.no-native-compaction",
+				reason: latestNativeCompaction.reason,
+				provider: runtime.provider,
+				api: runtime.api,
+				model: runtime.model,
+				baseUrl: runtime.baseUrl,
+				branchEntries: branchEntries.length,
+				latestCompactionIndex: latestNativeCompaction.latestCompactionIndex,
+				latestCompactionIdentity: getCompactionIdentityDebugInfo(latestNativeCompaction.latestCompaction),
+				payload,
+			},
+			config,
+			ctx,
+		);
+		return undefined;
+	}
+
+	const latestNativeCompactionEntry = latestNativeCompaction.entry;
+	const rewrite = rewriteResponsesPayloadWithNativeReplay({
+		model: runtime.currentModel,
+		payload,
+		branchEntries,
+		compactionEntry: latestNativeCompactionEntry,
+		expectedInputProvenance: getRemoteV2InputProvenance(config.remoteV2ContextSource),
+	});
+	if (!rewrite.ok) {
+		writeDebugArtifact(
+			"provider-request",
+			{
+				event: "before_provider_request.rewrite-failed",
+				reason: rewrite.reason,
+				provider: runtime.provider,
+				api: runtime.api,
+				model: runtime.model,
+				baseUrl: runtime.baseUrl,
+				compactionEntryId: latestNativeCompactionEntry.id,
+				parity: rewrite.parity,
+				payload,
+			},
+			config,
+			ctx,
+		);
+
+		// Fail loud instead of letting Pi send the sentinel-only payload: the
+		// compacted history would be silently lost while the request still succeeds.
+		// A forced redacted failure record is written even when logProviderPayloads
+		// is disabled so the incident is diagnosable without leaking content.
+		writeReplayFailureArtifact(
+			{
+				reason: rewrite.reason,
+				parity: rewrite.parity,
+				compactionEntryId: latestNativeCompactionEntry.id,
+				provider: runtime.provider,
+				api: runtime.api,
+				model: runtime.model,
+			},
+			config,
+			ctx,
+		);
+		if (ctx.hasUI) {
+			ctx.ui.notify(
+				`${COMPACTION_EXTENSION_ID}: native compaction replay failed (${rewrite.reason}); provider request aborted`,
+				"error",
+			);
+		}
+		ctx.abort();
+		return undefined;
+	}
+
+	writeDebugArtifact(
+		"provider-request",
+		{
+			event: "before_provider_request.native-rewrite",
+			provider: runtime.provider,
+			api: runtime.api,
+			model: runtime.model,
+			baseUrl: runtime.baseUrl,
+			compactionEntryId: latestNativeCompactionEntry.id,
+			boundaryIndex: rewrite.segments.boundaryIndex,
+			firstKeptEntryIndex: rewrite.segments.firstKeptEntryIndex,
+			originalInputItems: payload.input.length,
+			rewrittenInputItems: rewrite.rewrittenPayload.input.length,
+			leadingItems: rewrite.segments.leading.length,
+			compactionSummaryItems: rewrite.segments.compactionSummary.length,
+			compactedItems: rewrite.segments.compactedWindow.length,
+			postItems: rewrite.segments.post.length,
+			payload: rewrite.rewrittenPayload,
+			originalPayload: payload,
+		},
+		config,
+		ctx,
+	);
+
+	return rewrite.rewrittenPayload;
+}
+
+export default function registerCompactionExtension(
+	pi: ExtensionAPI,
+	overrides: Partial<CompactionDependencies> = {},
+) {
+	const loadConfig = overrides.loadConfig ?? loadToolkitConfig;
+	registerToolkitConfigCommand(pi, loadConfig);
+	const piContextHookPatch = installPiContextHookPatch();
+	const contextWindows = overrides.contextWindows ?? new CodexContextWindowManager((ctx, signal, gatewayModels) =>
+		loadHistoryNotesThreadHint(ctx, signal, gatewayModels)
+	);
+	const dependencies: CompactionDependencies = {
+		loadConfig,
+		remoteCompact: executeRemoteV2Compaction,
+		nativeFallback: runNativeFallbackCompaction,
+		contextWindows,
+		...overrides,
+		piContextHookPatch: overrides.piContextHookPatch ?? piContextHookPatch,
+	};
+	let tools!: ReturnType<typeof registerContextManagementTools>;
+	let contextWindowReady = false;
+	const isContextRuntimeActive = async (
+		ctx: ExtensionContext,
+		config: CompactionConfig,
+		model = ctx.model,
+	): Promise<boolean> =>
+		contextWindowReady && tools.isRegistered && await isRemoteContextActive(ctx, config, model);
+	tools = registerContextManagementTools(
+		pi,
+		contextWindows,
+		async (ctx) => {
+			const resolved = contextOperation(dependencies.loadConfig, ctx);
+			assertConfigValid(resolved, "context", "compatibility");
+			return { active: await isContextRuntimeActive(ctx, resolved.config.compaction), gatewayModels: resolved.gatewayModelKeys };
+		},
+	);
+	const remoteContextActive: RemoteContextActive = isContextRuntimeActive;
+	const syncTools = async (
+		ctx: ExtensionContext,
+		model = ctx.model,
+		options: { notifyWindowFailure?: boolean } = {},
+		resolved = contextOperation(dependencies.loadConfig, ctx, model),
+	): Promise<ContextToolSyncOutcome> => {
+		// Until this call proves otherwise, do not let a previous session/window
+		// identity make a failed activation look usable.
+		contextWindowReady = false;
+		const config = resolved.config.compaction;
+		const eligible = !resolved.invalidFeatures.some((feature) => ["context", "compatibility"].includes(feature)) && await isRemoteContextActive(ctx, config, model);
+		const toolSync = tools.sync(eligible);
+		const outcome: ContextToolSyncOutcome = {
+			eligible,
+			toolsSynced: toolSync.synced,
+			registrationState: toolSync.registrationState,
+			windowInitialized: false,
+		};
+		if (!eligible || !toolSync.synced) return outcome;
+		// Activation can succeed after `session_start` missed it, because Pi 0.86 may
+		// reject the registration read while a session replacement is still binding.
+		// The window lifecycle has to open on that later activation too, or requests
+		// carry no window metadata and the backend never ingests the turns.
+		try {
+			contextWindows.ensureInitialized(pi, ctx, true);
+			contextWindowReady = true;
+			return { ...outcome, windowInitialized: true };
+		} catch {
+			// Do not leave tools exposed while the request path has no valid window
+			// identity. The next lifecycle hook may retry once Pi is usable again.
+			tools.sync(false);
+			if (options.notifyWindowFailure) notifyRemoteContextFailure(ctx, "malformed-window-state");
+			return outcome;
+		}
+	};
+	pi.on("session_start", async (_event, ctx) => {
+		const resolved = contextOperation(dependencies.loadConfig, ctx);
+		const syncOutcome = await syncTools(ctx, ctx.model, { notifyWindowFailure: true }, resolved);
+		const active = syncOutcome.eligible && syncOutcome.toolsSynced && syncOutcome.windowInitialized;
+		const { source } = resolved;
+		const warnings = resolved.issues.map((issue) => `${issue.path}: ${issue.code}`);
+		const config = resolved.config.compaction;
+		if (resolved.invalidFeatures.length > 0) return;
+		if (!config.enabled) return;
+
+		let activationReason: string | undefined;
+		// Only models the built-in Remote Context coverage targets may activate or
+		// warn; everything else silently runs Pi's normal compaction path.
+		if (config.contextManagement === "remote" && isCodexContextModel(ctx.model, config) && !active) {
+			if (syncOutcome.registrationState === "conflict") {
+				activationReason = "tool-name-conflict";
+				notifyRemoteContextFailure(ctx, activationReason);
+			} else if (syncOutcome.registrationState === "unverified" || !syncOutcome.toolsSynced) {
+				// Transient: the runtime has not published or accepted our tools yet. A
+				// later before_agent_start re-verifies, so do not report provider failure.
+				activationReason = "tool-registration-pending";
+			} else if (syncOutcome.eligible && !syncOutcome.windowInitialized) {
+				activationReason = "malformed-window-state";
+			} else {
+				const remoteResolution = await resolveCodexContextProvider(ctx, ctx.model, config.gatewayContextModels);
+				activationReason = remoteResolution.ok ? "codex-context-unavailable" : remoteResolution.reason;
+				notifyRemoteContextFailure(ctx, activationReason);
+			}
+		}
+
+
+		const artifactPath = writeDebugArtifact(
+			"lifecycle",
+			{
+				event: "session_start",
+				config,
+				configSource: source,
+				warnings,
+				activation: {
+					active,
+					contextManagement: config.contextManagement,
+					remoteV2ContextSource: config.remoteV2ContextSource,
+					model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined,
+					...(activationReason ? { reason: activationReason } : {}),
+				},
+				piContextHookPatch: dependencies.piContextHookPatch,
+			},
+			config,
+			ctx,
+		);
+
+		if (ctx.hasUI && ["info", "debug"].includes(resolved.policy.diagnostics.level) && (config.notifyOnLoad || config.debug)) {
+			ctx.ui.notify(
+				artifactPath
+					? `${COMPACTION_EXTENSION_ID} loaded • debug artifacts → ${artifactPath}`
+					: `${COMPACTION_EXTENSION_ID} loaded`,
+				"info",
+			);
+		}
+	});
+
+	pi.on("context", (event, ctx) => handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive));
+	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive));
+	pi.on("session_compact", (event, _ctx) => contextWindows.recordCompaction(event.compactionEntry.details));
+	pi.on("session_shutdown", () => {
+		contextWindowReady = false;
+		contextWindows.reset();
+		tools.reset();
+	});
+	pi.on("agent_settled", async (_event, ctx) => {
+		// Idle: no retry, compaction, or queued continuation is left running, so this is the
+		// only safe place to spend a model call on the user's behalf.
+		await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "turn-end");
+	});
+	pi.on("model_select", async (event, ctx) => {
+		// Switching into a covered model mid-session must open the window
+		// lifecycle immediately: without an identity the request rewrite skips
+		// window metadata, the backend never ingests those turns, and the first
+		// new_context would trim pre-switch history that no history can recover.
+		// syncTools() activates and initializes the window when the model is covered.
+		const resolved = contextOperation(dependencies.loadConfig, ctx, event.model);
+		await syncTools(ctx, event.model, { notifyWindowFailure: true }, resolved);
+		// The switch itself is the moment the durable transcript changes consumer, and the
+		// session is idle here, so the close-out must happen now rather than mid-turn.
+		await handleWindowBulk(ctx, contextWindows, dependencies.loadConfig, "model-switch", resolved);
+	});
+	pi.on("before_agent_start", async (_event, ctx) => {
+		await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
+	});
+	pi.on("before_provider_request", (event, ctx) => handleBeforeProviderRequest(event, ctx, dependencies.loadConfig, contextWindows, remoteContextActive));
+	pi.on("before_provider_headers", async (event, ctx) => {
+		const resolved = contextOperation(dependencies.loadConfig, ctx);
+		requireContextPolicy(resolved, ctx);
+		const config = resolved.config.compaction;
+		if (!isCodexContextModel(ctx.model, config)) return;
+		const active = await remoteContextActive(ctx, config);
+		if (!active) {
+			if (isCodexGatewayModel(ctx.model, config.gatewayContextModels)) {
+				notifyRemoteContextFailure(ctx, "codex-context-unavailable");
+				ctx.abort();
+			}
+			return;
+		}
+		const provider = await resolveCodexContextProvider(ctx, ctx.model, config.gatewayContextModels);
+		if (provider.ok && provider.provider.kind === "codex-gateway") {
+			const sessionId = getSessionId(ctx);
+			const gatewayHeaders = codexContextProviderHeaders(provider.provider, {
+				sessionId,
+				clientRequestId: sessionId,
+			});
+			const allowedGatewayHeaders = new Set<string>(CODEX_GATEWAY_FORWARD_HEADERS);
+			for (const existing of Object.keys(event.headers)) {
+				if (!allowedGatewayHeaders.has(existing.toLowerCase())) delete event.headers[existing];
+			}
+			for (const name of [
+				"authorization",
+				"originator",
+				"user-agent",
+				"version",
+				"session-id",
+				"x-client-request-id",
+				"x-codex-affinity-scope",
+				"x-codex-model",
+			]) {
+				for (const existing of Object.keys(event.headers)) {
+					if (existing.toLowerCase() === name) delete event.headers[existing];
+				}
+				const value = gatewayHeaders.get(name);
+				if (value) event.headers[name] = value;
+			}
+		}
+		contextWindows.rewriteHeaders(event.headers, ctx);
+	});
+	pi.on("message_end", async (event, ctx) => {
+		const resolved = contextOperation(dependencies.loadConfig, ctx);
+		requireContextPolicy(resolved, ctx);
+		const config = resolved.config.compaction;
+		if (!isCodexContextModel(ctx.model, config) || !tools.isRegistered) return undefined;
+		if (!(await remoteContextActive(ctx, config))) return undefined;
+		const message = routeContextNamespaceToolMessage(event.message);
+		return message === event.message ? undefined : { message };
+	});
+}