pi-openai-toolkit 0.22.2 → 0.23.0

package/README.md

@@ -52,11 +52,13 @@ Set `defaults.context.mode` or an individual model's `context.mode`:
 
 **Remote compaction** accepts `openai-responses`, `openai-codex-responses`, and `azure-openai-responses`. It tries V2 first. On the official OpenAI API-key route, a qualifying protocol failure can trigger one standalone `/v1/responses/compact` request; its complete encrypted replacement window is preserved for replay. OpenAI OAuth, native Codex, Azure, and gateways keep their existing V2 route. OpenAI subscription-sharing OAuth and native Codex login are separate grants, not interchangeable credentials. Backend/model access is still required.
 
-Set `context.remoteCompaction.model` to use a separate producer on the same effective base URL without changing the active model. Exhausted remote attempts warn before continuing with a native text summary. `nativeFallback.enabled: false` disables only Toolkit's configured-model tier, not Pi's default summary. Aborts, incompatible provenance, and edits to sealed history still cancel rather than bypassing checkpoint safety. See [context settings](docs/configuration.md#context) and [checkpoint rules](docs/internals.md#remote-compaction-v2-wire-contract).
+Set `context.remoteCompaction.model` to use a separate producer on the same effective base URL without changing the active model. For ordinary remote compaction, exhausted remote attempts warn before continuing with a native text summary. `nativeFallback.enabled: false` disables only Toolkit's configured-model tier, not Pi's default summary. Aborts, incompatible provenance, and edits to sealed history still cancel rather than bypassing checkpoint safety. See [context settings](docs/configuration.md#context) and [checkpoint rules](docs/internals.md#remote-compaction-v2-wire-contract).
 
 **Remote windows** require the native `openai-codex` provider with `openai-codex-responses`, or an `openai-responses` gateway implementing the protocol. Gateways require `compatibility.transport: "codex-gateway"` on the exact model entry. This setting does not add the capability to an ordinary compatible endpoint.
 
-Change `mode` in the example above to `remote-windows`. Eligible sessions expose `new_context`, `get_context_remaining`, `history`, and `notes`. Manual `/compact [instructions]` starts a checkpoint handoff: write notes successfully, then switch windows. An existing effective window boundary survives model changes and switches to `remote-compaction` or `pi`: only the current local window is used, and retired Remote Context history is not sent to the model or a compaction producer. A no-summary local boundary preserves the persisted Remote Window / Context Session, so switching back to a supported model reuses the same window instead of opening a duplicate one. The legacy `leaveManagedMode` setting is retained for config compatibility but no longer triggers bulk close-out compaction.
+Change `mode` in the example above to `remote-windows`. Eligible sessions expose `new_context`, `get_context_remaining`, `history`, and `notes`. Manual `/compact [instructions]` remotely compresses the current window without switching the active model or opening another window. After the checkpoint is saved, the original model continues; failure stops with the existing context preserved, without a text-summary fallback. It uses the same `context.remoteCompaction.model` setting; `null` keeps the current model.
+
+An existing effective window boundary survives model changes and switches to `remote-compaction` or `pi`: only the current local window is used, and retired Remote Context history is not sent to the model or a compaction producer. A no-summary local boundary preserves the persisted Remote Window / Context Session, so switching back to a supported model reuses the same window instead of opening a duplicate one. That boundary is written once: later compactions under a non-window model continue through the ordinary producer, native-fallback or Pi-default chain instead of being cancelled. The legacy `leaveManagedMode` setting is retained for config compatibility but no longer triggers bulk close-out compaction.
 
 Remote windows use alpha endpoints that may change upstream. When switching models, the remote window remains persisted and reusable; see the [window lifecycle](docs/internals.md#rollover-lifecycle).
 

package/README.zh.md

@@ -52,11 +52,13 @@ Toolkit 只读取一个全局配置文件，即使扩展安装在项目内也一
 
 **远程压缩**支持 `openai-responses`、`openai-codex-responses` 和 `azure-openai-responses`，先尝试 V2。官方 OpenAI API-key 路由遇到符合条件的协议失败时，可再尝试一次独立的 `/v1/responses/compact`，并完整保存返回的加密替换窗口用于重放。OpenAI OAuth、原生 Codex、Azure 和网关保持原有 V2 路由。OpenAI subscription-sharing OAuth 与原生 Codex 登录是两种独立授权，凭据不能互换；模型和后端仍须具备相应权限。
 
-可用 `context.remoteCompaction.model` 指定同一有效 base URL 下的独立压缩模型，不改变当前模型。远程尝试全部失败后，会明确提示并继续普通文本摘要。`nativeFallback.enabled: false` 只关闭 Toolkit 的指定模型回退层，不关闭 Pi 默认摘要。取消操作、来源不匹配或已封存历史被修改时，仍会取消，不能绕过检查点安全检查。详见[上下文配置](docs/configuration.md#context)和[检查点规则](docs/internals.md#remote-compaction-v2-wire-contract)。
+可用 `context.remoteCompaction.model` 指定同一有效 base URL 下的独立压缩模型，不改变当前模型。普通远程压缩的远程尝试全部失败后，会明确提示并继续文本摘要。`nativeFallback.enabled: false` 只关闭 Toolkit 的指定模型回退层，不关闭 Pi 默认摘要。取消操作、来源不匹配或已封存历史被修改时，仍会取消，不能绕过检查点安全检查。详见[上下文配置](docs/configuration.md#context)和[检查点规则](docs/internals.md#remote-compaction-v2-wire-contract)。
 
 **远程窗口**需要原生 `openai-codex` 提供商的 `openai-codex-responses` API，或支持相应协议的 `openai-responses` 网关。网关必须在精确模型下设置 `compatibility.transport: "codex-gateway"`；这一设置不会让普通兼容端点自动获得该能力。
 
-将上例的 `mode` 改为 `remote-windows` 后，符合条件的会话会提供 `new_context`、`get_context_remaining`、`history` 和 `notes`。手动 `/compact [instructions]` 会发起检查点交接：先成功写入 notes，再切换窗口。切换模型或改用 `remote-compaction`、`pi` 模式后，已有的有效窗口边界仍然生效：只使用当前本地窗口，旧窗口历史不会发送给新模型或 compaction 模型。扩展会用一个不生成摘要的本地边界保留已持久化的 Remote Window / Context Session；切回支持窗口的模型时会复用同一个窗口，不会重复创建。旧配置中的 `leaveManagedMode` 仍会解析，但不再触发批量 close-out 压缩。
+将上例的 `mode` 改为 `remote-windows` 后，符合条件的会话会提供 `new_context`、`get_context_remaining`、`history` 和 `notes`。手动 `/compact [instructions]` 会远程压缩当前窗口，不切换当前模型，也不打开新窗口。检查点保存成功后由原模型继续；失败则停止并保留现有上下文，不回退到文本摘要。它沿用 `context.remoteCompaction.model` 设置；`null` 仍使用当前模型。
+
+切换模型或改用 `remote-compaction`、`pi` 模式后，已有的有效窗口边界仍然生效：只使用当前本地窗口，旧窗口历史不会发送给新模型或 compaction 模型。扩展会用一个不生成摘要的本地边界保留已持久化的 Remote Window / Context Session；切回支持窗口的模型时会复用同一个窗口，不会重复创建。该边界只写一次：之后在非窗口模型下的压缩会继续走普通 producer、native fallback 或 Pi 默认链路，而不再被取消。旧配置中的 `leaveManagedMode` 仍会解析，但不再触发批量 close-out 压缩。
 
 远程窗口依赖 alpha 接口，上游可能随时调整。切换模型时远程窗口状态仍会持久化并可复用，详见[窗口生命周期](docs/internals.md#rollover-lifecycle)。
 

package/docs/configuration.md

@@ -57,8 +57,8 @@ Place `context` under `defaults` or an exact `models` entry.
 | Relative field | Default | Contract |
 | --- | --- | --- |
 | `mode` | `"remote-compaction"` | `"pi"` delegates ordinary context management to Pi; `"remote-compaction"` uses the eligible Responses checkpoint path; `"remote-windows"` selects Codex windows where supported. |
-| `remoteCompaction.model` | `null` | Exact producer reference; `null` uses the active model. In `remote-compaction`, it selects the synthetic checkpoint producer on the same effective base URL. In active `remote-windows`, manual `/compact` temporarily selects it for notes checkpoint duty on the same backend/account. |
-| `remoteCompaction.inputSource` | `"legacy"` | `"legacy"` preserves session/raw-branch input; `"pi-context-hook"` opts into Pi's ordered context projection. Checkpoint provenance must match. |
+| `remoteCompaction.model` | `null` | Exact synthetic producer reference for `remote-compaction` and active `remote-windows` manual `/compact`, on the same effective base URL. `null` uses the active model; a separate producer never changes the active model. |
+| `remoteCompaction.inputSource` | `"legacy"` | `"legacy"` keeps the existing session/branch input path without request-time context hooks; `"pi-context-hook"` opts into Pi's ordered context projection. Active Remote manual compression uses the canonical effective current window in either mode. Checkpoint provenance must match. |
 | `remoteCompaction.allowContinuityBreak` | `false` | Allow restarting from Pi context after a foreign compaction entry. It does not make malformed opaque checkpoints replayable. |
 | `remoteCompaction.apis` | `["openai-responses", "openai-codex-responses", "azure-openai-responses"]` | May narrow this set; `[]` permits no remote-compaction API. Azure uses Pi's resolved `AZURE_OPENAI_*` environment values for the `/openai/v1` Responses path, deployment mapping, and `api-version`; unsupported entries are errors. |
 | `nativeFallback.enabled` | `true` | Enable the existing native-method fallback tier. |
@@ -71,13 +71,13 @@ Ordinary remote compaction tries V2 first. One automatic standalone `/v1/respons
 
 Standalone success preserves the full canonical output window, including retained items, rather than treating retained assistant text as a summary. When actual remote attempts are exhausted, Toolkit warns that no encrypted checkpoint was produced and starts the existing native text-summary chain: the configured remote producer after a remote attempt, or `nativeFallback.model` when remote compaction is unavailable. `nativeFallback.enabled: false` disables only the configured-model tier; disabled/unset/same-model selections still permit Pi's default summary. Explicit summary-model failures and checkpoint-integrity failures cancel. OpenAI subscription-sharing OAuth can reject compaction; separately authenticating native Codex is a different route, not a way to reuse that grant. See the [wire contract](internals.md#remote-compaction-v2-wire-contract).
 
-Native Codex eligibility derives from the actual Pi provider/API. Gateways additionally need the exact transport opt-in below. An existing effective Remote Window boundary survives model and context-mode changes, including `remote-compaction`, `pi`, and legacy disabled/off settings. A non-window consumer receives only the current local window; retired Remote Context history is excluded from live requests and compaction producers. This local safety check does not activate Remote tools or protocol support. A no-summary boundary preserves the marker for later reuse. A configured window model whose activation fails does not silently receive a summary fallback. Normal `new_context` keeps its persisted-notes, duplicate and cooldown gates. Synthetic Remote V2 producer/consumer identity and checkpoint provenance are unchanged. See [Toolkit internals](internals.md).
+Native Codex eligibility derives from the actual Pi provider/API. Gateways additionally need the exact transport opt-in below. An existing effective Remote Window boundary survives model and context-mode changes, including `remote-compaction`, `pi`, and legacy disabled/off settings. A non-window consumer receives only the current local window; retired Remote Context history is excluded from live requests and compaction producers. This local safety check does not activate Remote tools or protocol support. A no-summary boundary preserves the marker for later reuse and is written once; later compaction under a non-window model continues through the ordinary producer/native/Pi-default chain. A configured window model whose activation fails does not silently receive a summary fallback. Normal `new_context` keeps its persisted-notes, duplicate and cooldown gates. Synthetic Remote V2 producer/consumer identity and checkpoint provenance are unchanged. See [Toolkit internals](internals.md).
 
-In active `remote-windows`, `/compact [instructions]` starts checkpoint duty rather than producing a summary. The selected model must authenticate to the same native backend/account or gateway credential/affinity domain, fit the projected window plus its output reserve, and retain the required permitted context tools. Invalid or unsuitable explicit targets are refused without switching to a fallback model. The entire handoff uses the initiating context-policy snapshot; no config or global Pi defaults are rewritten.
+In active `remote-windows`, `/compact [instructions]` produces a Remote V2 encrypted checkpoint for only the effective current window. It excludes retired windows and checkpoints belonging to earlier boundaries, preserves the current prompt/tools and context edits, and uses the initiating policy snapshot. It does not select another active model, run a notes-writing agent, require a new notes checkpoint, or call `new_context`. The producer still needs the same effective base URL and supported runtime. Leaving `remoteCompaction.model` null does not move long-input compression to a cheaper model.
 
-Only a new persisted successful notes write/append after the handoff and the latest delivered user message authorizes its rollover. After the exact target marker is durable, Toolkit restores the original model/thinking before new-window inference and asks it to read the receipt first. Failure or cancellation restores an owned selection; a later user selection takes priority. Failed restoration blocks further handoff requests until selection/auth is repaired. Reload can recover selection, but does not automatically restart inference.
+After the exact new checkpoint is persisted and Pi has finished manual compaction, the unchanged original model automatically continues in the same session/window. New user work, model/thinking selection, navigation or cancellation supersedes pending continuation; host queues are not cleared or reordered. If safe continuation cannot be established, the saved checkpoint remains available for manual resumption. Reload never restarts inference. Ordinary `notes`, `history` and `new_context` remain usable.
 
-The SDK native compact call reports its intentional cancellation; the visible handoff is a separate agent operation. Pi's pre-hook “nothing to compact” and “already compacted” outcomes remain. Automatic threshold/overflow compaction and internal pending-trim maintenance do not initiate checkpoint duty. `nativeFallback.model` keeps its existing summary-model meaning.
+Any failure in this active-manual path stops and preserves the existing context. It does not try standalone compaction, native text summary or Pi's active-model fallback, regardless of `nativeFallback.enabled`. Successful manual compact now returns a real compaction result; Pi's pre-hook “nothing to compact” and “already compacted” outcomes remain. Automatic threshold/overflow and internal pending-trim maintenance keep their existing behavior. Old persisted notes-handoff records remain readable for owned selection recovery only, without retrying inference. `nativeFallback.model` retains its existing meaning outside this active-manual scope.
 
 ---
 

package/docs/internals.md

@@ -21,7 +21,7 @@ Developer-facing reference for [pi-openai-toolkit](../README.md). The README kee
 
 The single global document is loaded through [src/config.ts](../src/config.ts). [src/config/legacy.ts](../src/config/legacy.ts) owns unversioned compatibility; [src/config/v2.ts](../src/config/v2.ts) validates v2 scopes, resolves exact policy, and records leaf origins. [src/config/policy.ts](../src/config/policy.ts) defines effective values independently of persisted session data. See the [configuration reference](configuration.md) for supported fields and migration limits.
 
-Feature entrypoints resolve once per public operation and pass that immutable snapshot through awaited helpers. A separately named compaction producer is resolved from the same decoded document for its own identity. Subsequent independent callbacks reload; a managed manual handoff retains its initiating context-policy snapshot until selection is restored. There is no general cross-event provider transaction, project lookup, singleton cache, or config state writer. Internal legacy-shaped engine adapters preserve compaction/search algorithms without exposing v2 parsing to consumers. Cross-feature gateway policy belongs to the resolver, not the context enable switch.
+Feature entrypoints resolve once per public operation and pass that immutable snapshot through awaited helpers. A separately named compaction producer is resolved from the same decoded document for its own identity. Subsequent independent callbacks reload; active Remote manual compression retains its initiating context-policy snapshot through the owned operation, while legacy handoffs retain theirs through owned selection recovery. There is no general cross-event provider transaction, project lookup, singleton cache, or config state writer. Internal legacy-shaped engine adapters preserve compaction/search algorithms without exposing v2 parsing to consumers. Cross-feature gateway policy belongs to the resolver, not the context enable switch.
 
 Selected invalid policy blocks dependent operations; unrelated model errors remain reportable without replacing the selected model. Retired `autoMode` sections are ignored with a warning; they never create effective policy or invalidate other features. Image choices are checked before auth, uploads, or paid requests. The human `/toolkit-config` command inspects effective values, validation, or a migration candidate without action APIs or network access. Migration is preview-only; source bytes and unknown/dormant content stay untouched.
 
@@ -109,31 +109,31 @@ State invariants the lifecycle code must keep honest:
 - Budget checks are skipped until the current window has produced its own assistant usage. Acting on the previous window's usage anchor would burn the once-per-window reminder on a false alarm.
 - Pi's canonical session projection is the source of effective history. Toolkit may further restrict that projection, but never reconstruct omitted or summarized messages from the raw branch. Boundary resolution uses projected source entries and the active branch's latest compaction; an older marker retained inside a newer compaction does not authorize dropping that compaction's summary.
 - Window identity and cleanup eligibility are separate. A persisted `codex-context-window` message restores identity after reload/fork, but its historical `trimPreviousWindow` flag is not an outstanding command. A newer native summary or opaque checkpoint supersedes old cleanup without erasing window identity. Missing or edited boundary evidence is never repaired by loading raw history.
-- Maintenance compaction and local-consumer detachment use the same effective-boundary rules. Only a safe current boundary can produce a no-summary compaction; obsolete cleanup must not move the retained start backwards or replace a newer summary/checkpoint. Preparation alone changes no durable state, and cancellation, retry and branch navigation are resolved from current evidence rather than callback acknowledgments. User manual `/compact` still follows the managed handoff below.
-- An effective persisted window boundary belongs to the session, not the selected model or context mode. `context_with_system`, `before_provider_request`, and `session_before_compact` synchronize it before mode-specific exits, including `remote-compaction`, `pi`, and legacy disabled/off selections. A non-window consumer receives only the effective current context, with the current system/tool head preserved and internal markers removed; no Remote tools, metadata or affinity headers are activated by the local safety check. A pre-window opaque checkpoint cannot rehydrate retired history after local projection. When detachment is needed, the existing no-summary boundary runs before any configured, remote, native or Pi-default compaction producer. Once a later ordinary compaction owns effective context, the historical window does not suppress its summary or valid opaque replay. A genuinely new window can retire that checkpoint. Disabling opaque checkpoint generation through `responsesApis` does not disable required replay of an inherited checkpoint; an unsupported transport, authentication failure, or endpoint mismatch aborts the request instead of exposing its placeholder. The legacy `leaveManagedMode` setting remains compatible but does not start a bulk close-out from `model_select` or `agent_settled`.
+- Maintenance compaction and local-consumer detachment use the same effective-boundary rules. Only a safe current boundary can produce a no-summary compaction; obsolete cleanup must not move the retained start backwards or replace a newer summary/checkpoint. Preparation alone changes no durable state, and cancellation, retry and branch navigation are resolved from current evidence rather than callback acknowledgments. A boundary already consumed by its own no-summary compaction is not a dead end: the scheduled-trim path still refuses a second boundary, but a local consumer falls through to the ordinary compaction chain, because Pi's canonical projection already starts at that boundary and retired Remote history is outside every producer's input. User manual `/compact` still follows the managed handoff below.
+- An effective persisted window boundary belongs to the session, not the selected model or context mode. `context_with_system`, `before_provider_request`, and `session_before_compact` synchronize it before mode-specific exits, including `remote-compaction`, `pi`, and legacy disabled/off selections. A non-window consumer receives only the effective current context, with the current system/tool head preserved and internal markers removed; no Remote tools, metadata or affinity headers are activated by the local safety check. A pre-window opaque checkpoint cannot rehydrate retired history after local projection. When detachment is needed, the existing no-summary boundary runs before any configured, remote, native or Pi-default compaction producer. A boundary that a previous detach already persisted yields to that same producer chain instead of cancelling the operation. Once a later ordinary compaction owns effective context, the historical window does not suppress its summary or valid opaque replay. A genuinely new window can retire that checkpoint. Disabling opaque checkpoint generation through `responsesApis` does not disable required replay of an inherited checkpoint; an unsupported transport, authentication failure, or endpoint mismatch aborts the request instead of exposing its placeholder. The legacy `leaveManagedMode` setting remains compatible but does not start a bulk close-out from `model_select` or `agent_settled`.
 - Native text summarization delegates prompt construction, tool-result truncation, split-turn requests and output limits to Pi's `compact()`. Toolkit does not use character-count estimates to reject the configured summary model. If its resolution, authentication or summary generation fails, compaction is cancelled with the error and context is preserved; the active model is not an implicit retry target. Disabled/unset/same-model selections retain Pi's default path. Remote-window projection still excludes retired managed history before any producer call.
 
 ---
 
 ### Managed manual compact
 
-[src/context-management/manual-compact.ts](../src/context-management/manual-compact.ts) owns manual checkpoint duty. It uses public Pi lifecycle and selection APIs; it does not replace the built-in command or patch the scheduler. [src/context-management/window-manager.ts](../src/context-management/window-manager.ts) remains the sole owner of notes pairing, window identity, projection and trim.
+Active Remote Window manual `/compact` uses the shared Remote V2 client, not a notes-writing agent. [src/context-management/manual-compact.ts](../src/context-management/manual-compact.ts) owns its narrow cancellation/continuation lifecycle; [src/context-management/window-manager.ts](../src/context-management/window-manager.ts) remains the owner of window identity, canonical projection, notes pairing and trim. The built-in command and Pi scheduler are unchanged.
 
-1. An active managed `session_before_compact` with reason `manual` validates the source/target policies from one snapshot, actual permitted tools, remaining capacity and backend/account scope. It records the original model/thinking and cancels the native compact attempt. Internal window-bulk maintenance has a separate in-process owner even though Pi also labels it `manual`.
-2. The matching `session_compact_failed` callback launches duty only after Pi is idle. Public `setModel` changes the session selection, and a visible `sendUserMessage` rebuilds the target's normal prompt/tools. Delivery is observed through `message_start`; return from the fire-and-forget send API is not proof. A delivery timeout restores an abandoned idle selection.
-3. The existing `new_context` gate additionally requires a successful paired notes result after this operation and any later delivered user message. It records the exact target window before queueing a context-only marker, and returns a terminating result. Ordinary tools are blocked during checkpoint duty. Normal `new_context` outside this operation is unchanged.
-4. A terminating result alone does not stop mixed batches or queued messages. At `turn_end`, Toolkit requests abort without awaiting idle; context/request guards also refuse an unsafe continuation. The standard Responses and native Codex transports must not send an already-aborted continuation. Pi can deliver queued user content during that stop; it remains persisted and ordered for the original model.
-5. At `agent_settled`, after Pi has flushed custom messages, the controller verifies the exact durable marker and fresh checkpoint, restores original model/thinking, and sends one visible receipt-reading continuation. Pi 0.87 defers that continuation until every settled handler has returned, so later observers still see an idle session. Restoration finishes before the next provider request; marker `message_end` alone is not proof of persistence.
+1. `session_before_compact` distinguishes user-manual requests from Toolkit-owned maintenance even though both have reason `manual`. Resolve the producer and original consumer from one policy snapshot without invoking model/thinking setters.
+2. Prepare only the canonical effective current window. A later window retires an older opaque checkpoint; a newer checkpoint supersedes historical window markers. Preserve the prompt/tool head, context edits, complete tool pairs, native encrypted notes/history output and current deferred schemas. Hook-source preparation runs the ordered context phases once without triggering a budget reminder or maintenance. Unsafe projection cancels instead of recovering raw history.
+3. Send one synthetic Remote V2 request, validate it and recheck operation ownership, then return a real compaction result for Pi to persist. Select a genuine retained start within the submitted window. Resolution, protocol, network, validation and cancellation failures stop with no standalone/text-summary fallback, notes duty or continuation.
+4. `session_compact` synchronizes and verifies the latest exact persisted checkpoint. Repeated checkpoints share a summary string, so an event entry ID or summary match alone is insufficient proof. The callback returns without awaiting idle or sending a prompt: Pi emits it before clearing manual-compaction state.
+5. A cancellable bounded deferred check uses public `ctx.isIdle()` and exact session/branch/window/checkpoint/selection evidence before one normal `sendUserMessage` continuation. New user work, selection, navigation, queued work, another compact or shutdown invalidates stale continuation. Host queues stay untouched. If safe continuation is unavailable, keep the successful checkpoint and stop without inference.
 
-Versioned `pi-openai-toolkit:manual-compact` custom entries record operation/session/branch/window identities, exact model keys, original thinking and phase. They contain no credentials, transcript copy or note contents. Reload/navigation reads the current branch and only recovers still-owned selection; it never retries notes, rollover or paid inference. A newer user model/thinking selection ends ownership. Failed restoration stays durable and blocks further provider requests until recovery or an explicit user selection.
+Compression preserves the same session/window identity and does not call `new_context`. Ordinary notes/history and explicit rollover remain available; a later queued or persisted window must exclude the retired opaque checkpoint. The original working model consumes the checkpoint only after it is durable and manual compression is idle. Pi's pre-hook empty/already-compacted outcomes remain unchanged.
 
-The underlying native compact promise still rejects its intentional cancellation. Empty/already-compacted sessions can fail before the extension hook. This is a separate handoff operation, not a fabricated successful native compaction. An observed user cancellation before the owned checkpoint stop restores selection without automatically resuming. Tests use the official Pi runtime, disk-backed sessions, isolated HOME/settings and synthetic Responses/native Codex traffic in [test/pi-managed-compact.test.ts](../test/pi-managed-compact.test.ts); they assert every request's model/thinking, marker/note order, retained tool head and queue preservation.
+Old version-1 `pi-openai-toolkit:manual-compact` records remain decodable for owned selection recovery. Reload/navigation never retries their notes, rollover or inference; a newer user selection wins. New direct compression does not create notes-duty records or change the current model. Tests in [test/pi-managed-compact.test.ts](../test/pi-managed-compact.test.ts) use the official SDK, disk-backed sessions, isolated HOME/settings and mocked native/gateway traffic to verify input, persistence, continuation and failure ordering.
 
 ---
 
 ### Remote Compaction v2 wire contract
 
-v2 is what an uncovered session gets. Any model that Remote Context declines, such as a gateway without an exact transport opt-in, can still compact through v2 when its API appears in `context.remoteCompaction.apis`. Compaction generation follows the active strategy. Across mode changes, an already-persisted checkpoint remains authoritative until a safe newer window or compaction replaces it; a historical window identity alone must not suppress checkpoint replay.
+V2 serves ordinary eligible compaction and active Remote Window user-manual compaction. A model that Remote Context declines, such as a gateway without an exact transport opt-in, can still use the ordinary V2 path when its API appears in `context.remoteCompaction.apis`. Active Remote manual compression uses the stricter current-window and stop-on-failure contract above. Compaction generation follows the active strategy. Across mode changes, an already-persisted checkpoint remains authoritative until a safe newer window or compaction replaces it; a historical window identity alone must not suppress checkpoint replay.
 
 A `compaction_trigger` item appended to the live streaming request yields one output item of `type: "compaction"` with non-empty `encrypted_content`, stored in `CompactionEntry.details.compactedWindow`. On later requests the opaque checkpoint is replayed ahead of live turns, with no text summary. Replay fails closed: if the summary anchor cannot be located, the request is aborted with a notification and a content-free failure artifact. The sentinel-only payload is never sent.
 
@@ -143,7 +143,7 @@ A missing, empty, or invalid V2 checkpoint is never stored. Ordinary compaction
 
 #### Official API-key standalone fallback
 
-The ordinary path reuses one resolved physical producer, auth snapshot, and prepared full input. After a qualifying V2 failure, it makes at most one POST to `https://api.openai.com/v1/responses/compact`. Eligibility requires `openai-responses`, no Codex gateway affinity, public `ModelRegistry.hasConfiguredAuth(model) === true` and `isUsingOAuth(model) === false`, and the final Authorization header matching the resolved Bearer key. Missing/throwing/nonboolean metadata is unknown, not API-key evidence. Provider aliases may qualify at the official endpoint; OAuth, native Codex, Azure, custom gateways, managed handoff and inactive Remote Context recovery retain their previous routing. No token-shape inspection, extra auth resolution, model/account switch, redirect, capability cache, or generated version/beta header is introduced.
+The ordinary path reuses one resolved physical producer, auth snapshot, and prepared full input. After a qualifying V2 failure, it makes at most one POST to `https://api.openai.com/v1/responses/compact`. Eligibility requires `openai-responses`, no Codex gateway affinity, public `ModelRegistry.hasConfiguredAuth(model) === true` and `isUsingOAuth(model) === false`, and the final Authorization header matching the resolved Bearer key. Missing/throwing/nonboolean metadata is unknown, not API-key evidence. Provider aliases may qualify at the official endpoint; OAuth, native Codex, Azure, custom gateways, active Remote Window manual compression and inactive Remote Context recovery do not opt into this standalone fallback. No token-shape inspection, extra auth resolution, model/account switch, redirect, capability cache, or generated version/beta header is introduced.
 
 Qualifying failures are HTTP 400/404/405/422/501 without auth/quota exclusions, invalid/empty successful V2 checkpoint responses, or streamed errors with a recognized unsupported-protocol code. HTTP 401/403/429, known subscription/auth/billing/rate-limit restrictions, network failures, aborts, and generic server outages never trigger another protocol probe. OpenAI subscription-sharing OAuth and native Codex OAuth are distinct grants; selecting a separately authenticated Codex route does not authorize copying its credential to OpenAI.
 

package/package.json

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

package/src/context-management/manual-compact.ts

@@ -1,9 +1,10 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import { buildSessionContext, estimateTokens, type ExtensionAPI, type ExtensionContext, type SessionBeforeCompactEvent, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { buildSessionContext, estimateTokens, type CompactionResult, type ExtensionAPI, type ExtensionContext, type SessionBeforeCompactEvent, type SessionEntry } from "@earendil-works/pi-coding-agent";
 import { resolveToolkitConfig, type ResolvedToolkitConfig } from "../config";
 import { parseModelSpec } from "../runtime";
-import { THINKING_LEVELS } from "../types";
+import { THINKING_LEVELS, type NativeCompactionDetails } from "../types";
 import { resolveCodexContextProvider } from "./codex-provider";
 import { findLatestNotesCheckpointSinceBoundary, findLatestWindowBoundaryEntry, type CodexContextWindowManager } from "./window-manager";
 import { isNonEmptyString, isRecord, type CodexContextProvider, type ContextWindowIdentity } from "./types";
@@ -79,7 +80,183 @@ function freshCheckpoint(entries: readonly SessionEntry[], record: ManualCompact
 	return findLatestNotesCheckpointSinceBoundary(entries, record.sessionId, afterId);
 }
 
-/** Owns only manual managed handoffs, not normal window rollovers or Remote V2. */
+function branchFingerprint(entries: readonly SessionEntry[]): string {
+	return createHash("sha256").update(JSON.stringify(entries)).digest("hex");
+}
+
+export type RemoteManualCompactOperation = {
+	generation: number;
+	sessionId: string;
+	sessionFile: string | undefined;
+	anchorId: string;
+	branchLength: number;
+	branchFingerprint: string;
+	windowId: string;
+	model: string;
+	api: string;
+	baseUrl: string;
+	thinking: ThinkingLevel;
+	controller: AbortController;
+	signal: AbortSignal;
+	removeAbortListeners: () => void;
+	policy: ResolvedToolkitConfig;
+	candidate?: CompactionResult<NativeCompactionDetails>;
+	persistedId?: string;
+	deadline?: number;
+};
+
+/**
+ * One transient Remote V2 operation. It never selects a model, writes recovery
+ * records, takes host queues, or resumes from reload. Legacy duty recovery below
+ * remains independent.
+ */
+export class RemoteManualCompact {
+	private generation = 0;
+	private operation: RemoteManualCompactOperation | undefined;
+	private timer: ReturnType<typeof setTimeout> | undefined;
+
+	constructor(private readonly pi: ExtensionAPI, private readonly windows: CodexContextWindowManager,
+		private readonly idleTimeoutMs = 10_000) {}
+
+	get snapshot() { return this.operation?.policy.snapshot; }
+
+	invalidate(): void {
+		++this.generation;
+		clearTimeout(this.timer);
+		this.timer = undefined;
+		const operation = this.operation;
+		this.operation = undefined;
+		operation?.removeAbortListeners();
+		operation?.controller.abort();
+	}
+
+	cancel(operation: RemoteManualCompactOperation | undefined): void {
+		if (operation && this.operation === operation) this.invalidate();
+	}
+
+	begin(event: SessionBeforeCompactEvent, ctx: ExtensionContext, policy: ResolvedToolkitConfig): RemoteManualCompactOperation | undefined {
+		this.invalidate();
+		const model = ctx.model;
+		const anchorId = ctx.sessionManager.getLeafId();
+		const windowId = this.windows.currentIdentity()?.currentWindowId;
+		if (!model || !anchorId || !windowId || event.signal.aborted) return undefined;
+		const branch = ctx.sessionManager.getBranch();
+		if (!isDeepStrictEqual(event.branchEntries, branch)) return undefined;
+		const controller = new AbortController();
+		const onAbort = () => { if (this.operation === operation) this.invalidate(); };
+		// Manual compact has already aborted the preceding agent run. Its old,
+		// aborted ctx.signal is not cancellation of this newly initiated operation.
+		const signals = [event.signal, ...(ctx.signal && !ctx.signal.aborted && ctx.signal !== event.signal ? [ctx.signal] : [])];
+		const operation: RemoteManualCompactOperation = {
+			generation: this.generation, sessionId: ctx.sessionManager.getSessionId(),
+			sessionFile: ctx.sessionManager.getSessionFile(), anchorId,
+			branchLength: branch.length, branchFingerprint: branchFingerprint(branch), windowId,
+			model: modelKey(model)!, api: model.api, baseUrl: model.baseUrl, thinking: this.pi.getThinkingLevel(),
+			controller, signal: controller.signal, policy,
+			removeAbortListeners: () => { for (const signal of signals) signal.removeEventListener("abort", onAbort); },
+		};
+		this.operation = operation;
+		for (const signal of signals) signal.addEventListener("abort", onAbort, { once: true });
+		return operation;
+	}
+
+	private owns(operation: RemoteManualCompactOperation, ctx: ExtensionContext): boolean {
+		if (this.operation !== operation || operation.generation !== this.generation || operation.signal.aborted
+			|| ctx.sessionManager.getSessionId() !== operation.sessionId || ctx.sessionManager.getSessionFile() !== operation.sessionFile
+			|| modelKey(ctx.model) !== operation.model || ctx.model?.api !== operation.api || ctx.model?.baseUrl !== operation.baseUrl
+			|| this.pi.getThinkingLevel() !== operation.thinking || ctx.hasPendingMessages()) return false;
+		this.windows.synchronize(ctx);
+		return this.windows.currentIdentity()?.currentWindowId === operation.windowId && !this.windows.hasPendingRollover(ctx);
+	}
+
+	current(operation: RemoteManualCompactOperation, ctx: ExtensionContext): boolean {
+		try {
+			const branch = ctx.sessionManager.getBranch();
+			return this.owns(operation, ctx) && ctx.sessionManager.getLeafId() === operation.anchorId
+				&& branch.length === operation.branchLength && branchFingerprint(branch) === operation.branchFingerprint;
+		} catch { return false; }
+	}
+
+	arm(
+		operation: RemoteManualCompactOperation,
+		ctx: ExtensionContext,
+		candidate: CompactionResult<NativeCompactionDetails>,
+	): { readonly cancel: boolean; compaction: CompactionResult<NativeCompactionDetails> } | undefined {
+		if (!this.current(operation, ctx)) return undefined;
+		operation.candidate = structuredClone(candidate);
+		const owner = this;
+		return {
+			compaction: candidate,
+			// Pi reads this public result again after later before-compact observers.
+			// Revalidate at consumption, not just at return: newer work must revoke
+			// the candidate before persistence, without ctx.abort() draining TUI queues.
+			get cancel() { return !owner.current(operation, ctx); },
+		};
+	}
+
+	private durableCandidate(operation: RemoteManualCompactOperation, ctx: ExtensionContext): string | undefined {
+		if (!this.owns(operation, ctx) || !operation.candidate) return undefined;
+		const branch = ctx.sessionManager.getBranch();
+		// The event's ID can refer to an OLD equal-summary checkpoint in Pi 1.0.
+		// Only the new actual branch child and its complete candidate are proof.
+		if (branch.length !== operation.branchLength + 1
+			|| branchFingerprint(branch.slice(0, operation.branchLength)) !== operation.branchFingerprint) return undefined;
+		const entry = branch[operation.branchLength];
+		const candidate = operation.candidate;
+		if (!entry || entry.type !== "compaction" || entry.parentId !== operation.anchorId
+			|| entry.id === operation.anchorId || ctx.sessionManager.getLeafId() !== entry.id || entry.fromHook !== true
+			|| entry.summary !== candidate.summary || entry.firstKeptEntryId !== candidate.firstKeptEntryId
+			|| entry.tokensBefore !== candidate.tokensBefore
+			// Persistence omits undefined optional fields; compare the actual JSON
+			// data, not object identity, summary text, or provider response ID alone.
+			|| !isDeepStrictEqual(JSON.parse(JSON.stringify(entry.details)), JSON.parse(JSON.stringify(candidate.details)))) return undefined;
+		return entry.id;
+	}
+
+	private requestManualResume(ctx: ExtensionContext, message = "Remote /compact saved its checkpoint; resume manually."): void {
+		try { if (ctx.hasUI) ctx.ui.notify(message, "warning"); } catch { /* stale UI must not escape a deferred callback */ }
+	}
+
+	/** Observer only: never await idle or submit a prompt inside session_compact. */
+	persisted(ctx: ExtensionContext): void {
+		const operation = this.operation;
+		if (!operation?.candidate || operation.persistedId) return;
+		try { operation.persistedId = this.durableCandidate(operation, ctx); } catch { /* fail closed */ }
+		if (!operation.persistedId) {
+			this.invalidate();
+			this.requestManualResume(ctx, "Remote /compact could not verify its exact saved checkpoint; resume manually.");
+			return;
+		}
+		operation.deadline = Date.now() + this.idleTimeoutMs;
+		this.schedule(operation, ctx, 0);
+	}
+
+	private schedule(operation: RemoteManualCompactOperation, ctx: ExtensionContext, delay: number): void {
+		this.timer = setTimeout(() => {
+			this.timer = undefined;
+			if (this.operation !== operation) return;
+			try {
+				if (this.durableCandidate(operation, ctx) !== operation.persistedId) { this.invalidate(); return; }
+				if (Date.now() >= operation.deadline!) {
+					this.invalidate();
+					this.requestManualResume(ctx, "Remote /compact saved its checkpoint; automatic continuation could not safely reach idle. Resume manually.");
+					return;
+				}
+				if (!ctx.isIdle()) { this.schedule(operation, ctx, 25); return; }
+				// No await between final public ownership/queue/idle proof and send.
+				// Disarm first, so our own input/run events cannot invalidate a newer operation.
+				this.invalidate();
+				this.pi.sendUserMessage("Context compressed. Resume the active user task.");
+			} catch {
+				this.invalidate();
+				this.requestManualResume(ctx);
+			}
+		}, delay);
+		this.timer.unref?.();
+	}
+}
+
+/** Owns only legacy managed handoffs, not normal window rollovers or Remote V2. */
 export class ManagedManualCompact implements ContextRolloverHandoff {
 	private record: ManualCompactRecord | undefined;
 	private generation = 0;

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

@@ -1,4 +1,6 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ProviderHeaders } from "@earendil-works/pi-ai";
 import {
@@ -65,6 +67,17 @@ type WindowBoundaryEntry = Extract<SessionEntry, { type: "custom_message" }> & {
 	details: CodexContextManagementMessageDetails;
 };
 
+/** Canonical input and real source anchors for one read-only manual compression. */
+export type RemoteWindowCompactionInput = {
+	messages: AgentMessage[];
+	firstKeptEntryId: string;
+	/** Only a newer compaction can own this window; pre-window checkpoints are retired. */
+	owningCompaction?: Extract<SessionEntry, { type: "compaction" }>;
+	/** Entries whose visible contributions Pi will retain alongside the new checkpoint. */
+	retainedMessages: AgentMessage[];
+	windowBoundaryIndex: number;
+};
+
 /**
  * In-process duplicate guard for one scheduled rollover. It is anchored to the
  * session that scheduled it and to the exact target window id, so it can never
@@ -88,6 +101,14 @@ export class CodexContextWindowManager {
 	private pendingRollover: PendingRollover | undefined;
 	private readonly projectionDiagnostics = new Set<string>();
 	private lastKnownSystemHead: AgentMessage | undefined;
+	private readonly compactionProjection = new AsyncLocalStorage<boolean>();
+
+	get isPreparingCompaction(): boolean { return this.compactionProjection.getStore() === true; }
+
+	/** Keep read-only preparation scoped across awaits without affecting other live requests. */
+	withCompactionProjection<T>(prepare: () => Promise<T>): Promise<T> {
+		return this.compactionProjection.run(true, prepare);
+	}
 	/**
 	 * Pi's getContextUsage() measures the durable transcript. Remote windows are
 	 * projected only by this extension, so remember the last provider-visible
@@ -225,6 +246,7 @@ export class CodexContextWindowManager {
 		/** Delay encoding until verified retained copies have been removed. */
 		encodeEncryptedOutputs = true,
 	): AgentMessage[] {
+		if (this.isPreparingCompaction) return this.projectCompactionContext(messages);
 		// Recompute the request-only preview on every projection. Observing a
 		// queued marker must not authorize maintenance or retire the duplicate guard.
 		if (this.pendingRollover) this.pendingRollover.projected = false;
@@ -278,6 +300,78 @@ export class CodexContextWindowManager {
 		return projected;
 	}
 
+	/**
+	 * Strict, read-only projection. Unlike live Remote projection, an unsafe head
+	 * never falls back to the full transcript, updates identity, or records budget.
+	 */
+	projectCompactionContext(messages: readonly AgentMessage[], encodeEncryptedOutputs = false): AgentMessage[] {
+		if (this.pendingRollover || (this.boundary.kind !== "effective" && this.boundary.kind !== "superseded")) {
+			throw new Error("unsafe-compaction-window-boundary");
+		}
+		let boundaryIndex = 0;
+		if (this.boundary.kind === "effective") {
+			const boundary = this.boundary.entry;
+			boundaryIndex = messages.findIndex((message) => isContextWindowBoundary(message)
+				&& isDeepStrictEqual(message.details, boundary.details)
+				&& isDeepStrictEqual(message.content, boundary.content));
+			if (boundaryIndex < 0) throw new Error("compaction-window-boundary-missing");
+		}
+		const repair = preserveSystemHead({ messages, boundaryIndex });
+		if (!repair.head || repair.shrinkRejected) throw new Error("compaction-system-tool-head-lost");
+		return encodeEncryptedOutputs ? projectEncryptedToolResults(repair.messages) : [...repair.messages];
+	}
+
+	prepareRemoteCompaction(event: SessionBeforeCompactEvent, ctx: ExtensionContext): RemoteWindowCompactionInput {
+		this.synchronize(ctx);
+		if (this.hasPendingRollover(ctx) || (this.boundary.kind !== "effective" && this.boundary.kind !== "superseded")) {
+			throw new Error("unsafe-compaction-window-boundary");
+		}
+		const branch = ctx.sessionManager.getBranch();
+		if (!isDeepStrictEqual(event.branchEntries, branch)) throw new Error("compaction-branch-changed");
+		const projection = ctx.sessionManager.buildSessionProjection();
+		// Never manufacture source IDs or substitute a raw-history reconstruction.
+		if (!projection || !Array.isArray(projection.entries) || !Array.isArray(projection.messages)
+			|| !isDeepStrictEqual(projection.messages, projection.entries.flatMap((entry) => entry.messages))
+			|| new Set(projection.entries.map((entry) => entry.sourceEntry.id)).size !== projection.entries.length
+			|| projection.entries.some((entry) => !branch.some((raw) => raw.id === entry.sourceEntry.id && isDeepStrictEqual(raw, entry.sourceEntry)))) {
+			throw new Error("compaction-source-projection-unavailable");
+		}
+		const windowBoundaryIndex = branch.findIndex((entry) => entry.id === this.boundaryEntryId());
+		if (windowBoundaryIndex < 0) throw new Error("compaction-window-boundary-missing");
+		const latest = [...branch].reverse().find((entry) => entry.type === "compaction");
+		if (this.boundary.kind === "effective" && this.boundary.cleaned) {
+			// Details alone do not turn an arbitrary summary into Toolkit cleanup.
+			if (!latest || latest.type !== "compaction" || latest.fromHook !== true
+				|| latest.summary !== CONTEXT_WINDOW_COMPACTION_SUMMARY
+				|| !isContextWindowCompactionDetails(latest.details)
+				|| latest.details.windowId !== this.boundary.entry.details.contextManagement.currentWindowId
+				|| latest.firstKeptEntryId !== this.boundary.entry.id) throw new Error("unverified-window-cleanup");
+		}
+		const owningCompaction = this.boundary.kind === "superseded" && latest?.type === "compaction" ? latest : undefined;
+		if (this.boundary.kind === "superseded" && !owningCompaction) throw new Error("compaction-owner-missing");
+		const lowerId = owningCompaction?.id ?? this.boundary.entry.id;
+		const lowerIndex = branch.findIndex((entry) => entry.id === lowerId);
+		const requestedIndex = branch.findIndex((entry) => entry.id === event.preparation.firstKeptEntryId);
+		if (requestedIndex < 0 || lowerIndex < windowBoundaryIndex) throw new Error("unsafe-compaction-retained-start");
+		const firstKeptEntryId = requestedIndex < lowerIndex ? lowerId : event.preparation.firstKeptEntryId;
+		const keptIndex = Math.max(requestedIndex, lowerIndex);
+		const safeSources = new Set(projection.entries.filter((entry) => entry.messages.length > 0).map((entry) => entry.sourceEntry.id));
+		if (!safeSources.has(firstKeptEntryId)) throw new Error("unsafe-compaction-retained-start");
+		const retainedIds = new Set(branch.slice(keptIndex).map((entry) => entry.id));
+		return {
+			messages: this.projectCompactionContext(structuredClone(projection.messages)),
+			firstKeptEntryId,
+			owningCompaction,
+			retainedMessages: structuredClone(projection.entries.filter((entry) => retainedIds.has(entry.sourceEntry.id)
+				&& entry.sourceEntry.type !== "compaction").flatMap((entry) => entry.messages)),
+			windowBoundaryIndex,
+		};
+	}
+
+	private boundaryEntryId(): string | undefined {
+		return this.boundary.kind === "effective" || this.boundary.kind === "superseded" ? this.boundary.entry.id : undefined;
+	}
+
 	/**
 	 * Trim everything before the window boundary while keeping Pi's prompt/tool head.
 	 *
@@ -449,14 +543,24 @@ export class CodexContextWindowManager {
 	 * Detach a local consumer at the durable Remote boundary, without summarizing
 	 * any Remote-managed history. Unlike a scheduled rollover trim, this needs
 	 * no pending trim and remains retryable until Pi persists the result.
+	 *
+	 * A consumed boundary is not an error. Once Pi has persisted the no-summary
+	 * boundary, `buildSessionProjection()` already starts at that marker, so
+	 * retired Remote history is outside every producer's input and the ordinary
+	 * compaction chain may summarize the remaining local window. Returning
+	 * `undefined` hands the event back to that chain; returning `{ cancel: true }`
+	 * would strand the session with no working compaction path at all.
 	 */
 	prepareDetachedCompaction(
 		event: SessionBeforeCompactEvent,
-	): { cancel: true } | { compaction: CompactionResult<ContextWindowCompactionDetails> } | undefined {
+	): { compaction: CompactionResult<ContextWindowCompactionDetails> } | undefined {
 		const boundary = resolveWindowBoundary(event.branchEntries, this.sessionId);
 		if (boundary.kind === "ambiguous") throw new Error("Persisted Codex context-window boundary missing or edited");
 		if (boundary.kind !== "effective") return undefined;
-		if (boundary.cleaned) return { cancel: true };
+		// A matching no-summary boundary is already the effective compaction anchor.
+		// Nothing is left to detach, and writing a second boundary for the same window
+		// would move the retained start backwards.
+		if (boundary.cleaned) return undefined;
 		const compaction = this.createCompaction(event, boundary.entry);
 		// Pi's preparation/tokensBefore describes the durable branch, which includes
 		// Remote-managed history. Detached local accounting must use the same current

package/src/extension-runtime.ts

@@ -1,4 +1,7 @@
+import { isDeepStrictEqual } from "node:util";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { declarationsEqual, getCurrentSystemMessage, getCurrentTools } from "@earendil-works/pi-ai";
+import { convertResponsesTools } from "@earendil-works/pi-ai/api/openai-responses-shared";
 import type {
 	BeforeProviderRequestEvent,
 	ContextWithSystemEvent,
@@ -16,10 +19,13 @@ import {
 	isCodexGatewayModel,
 	isNativeCodexModel,
 } from "./context-management/codex-provider";
-import { routeContextNamespaceToolMessage } from "./context-management/namespace-tools";
+import { rewriteContextNamespaceCalls, rewriteContextNamespaceTools, routeContextNamespaceToolMessage } from "./context-management/namespace-tools";
+import { rewriteEncryptedToolOutputs } from "./context-management/window-request";
 import { loadHistoryNotesThreadHint } from "./context-management/history-notes";
 import { CodexContextWindowManager } from "./context-management/window-manager";
-import { ManagedManualCompact } from "./context-management/manual-compact";
+import { ManagedManualCompact, RemoteManualCompact, type RemoteManualCompactOperation } from "./context-management/manual-compact";
+import { isSystemTranscriptMessage } from "./context-management/messages";
+import { isRecord } from "./context-management/types";
 import {
 	registerContextManagementTools,
 	type ContextToolRegistrationState,
@@ -79,7 +85,9 @@ import {
 	getRemoteV2InputProvenance,
 	isNativeCompactionDetails,
 	type CompactionConfig,
+	type DeferredToolCarryoverV1,
 	type NativeCompactionDetails,
+	type NativeCompactionEntry,
 	type NativeCompactionRequestMeta,
 } from "./types";
 
@@ -116,6 +124,7 @@ type CompactionDependencies = {
 	nativeFallback: typeof runNativeFallbackCompaction;
 	contextWindows: CodexContextWindowManager;
 	manualCompact?: ManagedManualCompact;
+	remoteManualCompact: RemoteManualCompact;
 	/** Test seam for the same ordered projection exposed by the Pi host patch. */
 	projectCompactionContext?: CompactionContextProjection;
 	piContextHookPatch: PiContextHookPatchResult;
@@ -311,8 +320,9 @@ type CompactionProjectionResult =
 async function projectSessionContextForCompaction(
 	ctx: ExtensionContext,
 	projectCompactionContext: CompactionContextProjection | undefined,
+	canonicalMessages?: readonly AgentMessage[],
 ): Promise<CompactionProjectionResult> {
-	const messages = readSessionContextMessages(ctx);
+	const messages = canonicalMessages ? structuredClone([...canonicalMessages]) : readSessionContextMessages(ctx);
 	if (!messages) {
 		return { ok: false, reason: COMPACTION_SESSION_CONTEXT_UNAVAILABLE };
 	}
@@ -342,6 +352,187 @@ function getLegacySessionContextMessages(
 	];
 }
 
+type ScopedResponsesCompactInput = {
+	request: NativeCompactionRequestBody;
+	firstKeptEntryId: string;
+	deferredToolCarryover?: DeferredToolCarryoverV1;
+	requestSource: "session-context" | "non-native-session-context" | "latest-native-replay";
+	isCurrent: () => boolean;
+};
+
+/** Reject incomplete/ambiguous tool batches rather than let serialization invent results. */
+function requireCompleteCompactionToolPairs(messages: readonly AgentMessage[]): ReadonlyMap<string, string | undefined> {
+	const calls = new Map<string, string | undefined>();
+	const pending = new Set<string>();
+	for (const message of messages) {
+		if (message.role === "assistant") {
+			if (pending.size) throw new Error("compaction-tool-pair-mismatch");
+			for (const block of message.content) {
+				if (block.type !== "toolCall") continue;
+				const callId = block.id.split("|")[0];
+				if (!callId || calls.has(callId)) throw new Error("compaction-tool-pair-mismatch");
+				calls.set(callId, block.namespace);
+				pending.add(block.id);
+			}
+		} else if (message.role === "toolResult") {
+			if (!pending.delete(message.toolCallId)) throw new Error("compaction-tool-pair-mismatch");
+		} else if (pending.size && !isSystemTranscriptMessage(message)) {
+			throw new Error("compaction-tool-pair-mismatch");
+		}
+	}
+	if (pending.size) throw new Error("compaction-tool-pair-mismatch");
+	return calls;
+}
+
+/** Serialization must preserve every verified pair, with unique provider call IDs. */
+function requireCompactionWireToolPairs(input: readonly unknown[], namespaces: ReadonlyMap<string, string | undefined>): void {
+	const calls = new Set<string>();
+	const pending = new Set<string>();
+	for (const item of input) {
+		if (!isRecord(item)) throw new Error("compaction-tool-pair-mismatch");
+		if (item.type === "function_call") {
+			if (typeof item.call_id !== "string" || !namespaces.has(item.call_id) || calls.has(item.call_id)) {
+				throw new Error("compaction-tool-pair-mismatch");
+			}
+			calls.add(item.call_id);
+			pending.add(item.call_id);
+		} else if (item.type === "function_call_output") {
+			if (typeof item.call_id !== "string" || !pending.delete(item.call_id)) throw new Error("compaction-tool-pair-mismatch");
+		}
+	}
+	if (pending.size || calls.size !== namespaces.size) throw new Error("compaction-tool-pair-mismatch");
+}
+
+function requireCompactionHeadAndRetention(
+	canonical: readonly AgentMessage[],
+	projected: readonly AgentMessage[],
+	retained: readonly AgentMessage[],
+): void {
+	const before = getCurrentTools(canonical);
+	const after = getCurrentTools(projected);
+	if (!getCurrentSystemMessage(projected) || before.length !== after.length
+		|| before.some((tool, index) => !after[index] || !declarationsEqual(tool, after[index]!))) {
+		throw new Error("compaction-system-tool-head-lost");
+	}
+	// These exact source contributions will accompany the new summary in Pi.
+	// If a hook rewrites/omits one, future strict retained-copy removal cannot be proven.
+	let cursor = 0;
+	for (const message of retained) {
+		if (message.role === "custom" || message.role === "compactionSummary" || isSystemTranscriptMessage(message)) continue;
+		const index = projected.findIndex((candidate, index) => index >= cursor && isDeepStrictEqual(candidate, message));
+		if (index < 0) throw new Error("compaction-retained-context-mismatch");
+		cursor = index + 1;
+	}
+}
+
+/** Apply only pure wire adapters, never ordinary turn/history-ingest hooks. */
+function adaptCompactionWireInput(input: ResponsesInputItem[], namespaces: ReadonlyMap<string, string | undefined>): ResponsesInputItem[] {
+	// The shared legacy serializer omits namespace. Restore it from the verified
+	// canonical call before applying the existing context-router wire adapter.
+	const namespaced = input.map((item: unknown) => {
+		if (!isRecord(item) || item.type !== "function_call" || typeof item.call_id !== "string") return item;
+		const namespace = namespaces.get(item.call_id);
+		return namespace ? { ...item, namespace } : item;
+	});
+	const adapted = rewriteEncryptedToolOutputs(rewriteContextNamespaceCalls({ input: namespaced }));
+	if (!isRecord(adapted) || !Array.isArray(adapted.input)) throw new Error("compaction-wire-adaptation-failed");
+	// The adapters preserve the validated array shape, with native encrypted outputs.
+	return adapted.input as ResponsesInputItem[];
+}
+
+async function prepareActiveRemoteCompaction(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+	config: CompactionConfig,
+	execution: RemoteCompactionExecution,
+	dependencies: CompactionDependencies,
+	isCurrent: () => boolean,
+): Promise<ScopedResponsesCompactInput> {
+	const windows = dependencies.contextWindows;
+	const prepared = windows.prepareRemoteCompaction(event, ctx);
+	const branch = ctx.sessionManager.getBranch();
+	const provenance = getRemoteV2InputProvenance(config.remoteV2ContextSource);
+	let checkpoint: NativeCompactionEntry | undefined;
+	let requestSource: ScopedResponsesCompactInput["requestSource"] = "session-context";
+	if (prepared.owningCompaction) {
+		const latest = resolveLatestNativeCompactionEntry(branch, { baseUrl: execution.consumer.baseUrl });
+		if (latest.ok) {
+			if (latest.entry.id !== prepared.owningCompaction.id) throw new Error("compaction-owner-mismatch");
+			if (hasInvalidatedCompactionContext(branch, latest.entry.id)) throw new Error(COMPACTION_CHECKPOINT_CONTEXT_EDITED);
+			if (!hasVerifiedCompactionInputProvenance(latest.entry.details, provenance)) throw new Error(COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE);
+			checkpoint = latest.entry;
+			requestSource = "latest-native-replay";
+		} else {
+			if (latest.reason !== "latest-compaction-not-native" || !config.allowCompactionContinuityBreak) throw new Error("compaction-continuity-unavailable");
+			requestSource = "non-native-session-context";
+		}
+	}
+	let messages = prepared.messages;
+	if (config.remoteV2ContextSource === "pi-context-hook") {
+		const projection = await windows.withCompactionProjection(() => projectSessionContextForCompaction(
+			ctx, dependencies.projectCompactionContext, messages,
+		));
+		if (!isCurrent()) throw new Error("compaction-operation-superseded");
+		if (!projection.ok) throw new Error(projection.reason);
+		messages = windows.projectCompactionContext(projection.messages);
+	}
+	if (!isCurrent()) throw new Error("compaction-operation-superseded");
+	requireCompactionHeadAndRetention(prepared.messages, messages, prepared.retainedMessages);
+	if (checkpoint) {
+		// The synthetic Toolkit hook deliberately leaves these copies alone. Match
+		// exactly once, BEFORE encrypted-output markers change the canonical values.
+		const pruned = removeNativeCompactionRetainedMessages({
+			messages, branchEntries: branch, compactionEntry: checkpoint, expectedInputProvenance: provenance,
+		});
+		if (!pruned.ok) throw new Error(pruned.reason);
+		messages = pruned.messages;
+	}
+	const namespaces = requireCompleteCompactionToolPairs(messages);
+	const tools = getCurrentTools(messages);
+	const model = execution.compactor.currentModel;
+	const compat = isRecord(model.compat) ? model.compat : {};
+	const nativeCodex = model.api === "openai-codex-responses";
+	const encoded = windows.projectCompactionContext(messages, true);
+	let input: ResponsesInputItem[];
+	if (checkpoint) {
+		const summaryIndex = findLatestProjectedCompactionSummaryIndex(encoded, checkpoint.summary);
+		if (summaryIndex < 0 || encoded.filter((message) => message.role === "compactionSummary").length !== 1) {
+			throw new Error(COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE);
+		}
+		const leading = await serializeMessagesToResponsesInputWithLimits(model, encoded.slice(0, summaryIndex));
+		if (!isCurrent()) throw new Error("compaction-operation-superseded");
+		const tail = await serializeMessagesToResponsesInputWithLimits(model, encoded.slice(summaryIndex + 1), { firstSystemMessageIsUpdate: true });
+		requireCompactionWireToolPairs([...leading, ...tail], namespaces);
+		const details = checkpoint.details;
+		if (!details) throw new Error("compaction-owner-mismatch");
+		input = [...adaptCompactionWireInput(leading, namespaces), ...(cloneOpaqueWindow(details.compactedWindow) as ResponsesInputItem[]), ...adaptCompactionWireInput(tail, namespaces)];
+	} else {
+		const serialized = await serializeMessagesToResponsesInputWithLimits(model, encoded);
+		requireCompactionWireToolPairs(serialized, namespaces);
+		input = adaptCompactionWireInput(serialized, namespaces);
+	}
+	if (!isCurrent()) throw new Error("compaction-operation-superseded");
+	const toolPayload = rewriteContextNamespaceTools({ tools: convertResponsesTools(tools, {
+		...(nativeCodex ? { strict: null } : {}),
+		supportsStrictMode: typeof compat.supportsStrictMode === "boolean" ? compat.supportsStrictMode : nativeCodex,
+		supportsOpenAIGrammarTools: compat.supportsOpenAIGrammarTools === true,
+	}) }, { encrypted: true });
+	if (!isRecord(toolPayload) || !Array.isArray(toolPayload.tools)) throw new Error("compaction-wire-adaptation-failed");
+	// Current cache-stack state is authoritative; never borrow deferred metadata
+	// from an unrelated pre-window checkpoint. The canonical head proves which
+	// of those schemas are still live, including tools activated before rollover.
+	const activation = getLatestDeferredToolCarryover(branch) ?? checkpoint?.details?.deferredToolCarryover;
+	const names = new Set(tools.map((tool) => tool.name));
+	const deferredToolCarryover = activation ? { ...activation, toolNames: activation.toolNames.filter((name) => names.has(name)) } : undefined;
+	return {
+		request: { model: execution.compactor.requestModel ?? execution.compactor.model, input,
+			instructions: buildCompactionInstructions(ctx.getSystemPrompt(), event.customInstructions), tools: toolPayload.tools },
+		firstKeptEntryId: prepared.firstKeptEntryId,
+		deferredToolCarryover: deferredToolCarryover?.toolNames.length ? deferredToolCarryover : undefined,
+		requestSource, isCurrent,
+	};
+}
+
 async function runResponsesNativeCompact(
 	event: SessionBeforeCompactEvent,
 	ctx: ExtensionContext,
@@ -351,11 +542,13 @@ async function runResponsesNativeCompact(
 	projectCompactionContext: CompactionContextProjection | undefined,
 	/** Only ordinary compaction supplies this; managed recovery remains V2-only. */
 	standaloneCompact?: typeof executeNativeCompaction,
+	/** Active Remote manual input is strict/current-window-only and has no fallback. */
+	scopedInput?: ScopedResponsesCompactInput,
 ): 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 deferredToolCarryover = scopedInput ? scopedInput.deferredToolCarryover : getLatestDeferredToolCarryover(branchEntries);
 	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
 		baseUrl: consumer.baseUrl,
 	});
@@ -363,7 +556,10 @@ async function runResponsesNativeCompact(
 	const inputProvenance = getRemoteV2InputProvenance(config.remoteV2ContextSource);
 	let requestSource: "session-context" | "non-native-session-context" | "latest-native-replay";
 	let request: NativeCompactionRequestBody;
-	if (latestNativeCompaction.ok) {
+	if (scopedInput) {
+		request = scopedInput.request;
+		requestSource = scopedInput.requestSource;
+	} else if (latestNativeCompaction.ok) {
 		if (hasInvalidatedCompactionContext(branchEntries, latestNativeCompaction.entry.id)) {
 			return { outcome: "unprojected-input", reason: COMPACTION_CHECKPOINT_CONTEXT_EDITED };
 		}
@@ -482,10 +678,10 @@ async function runResponsesNativeCompact(
 		sessionId: getSessionId(ctx),
 	}, compactor.currentModel);
 	if (extras) {
-		request = { ...request, ...extras };
+		request = { ...request, ...extras, ...(scopedInput ? { tools: scopedInput.request.tools } : {}) };
 	}
 
-	if (event.signal?.aborted) return { outcome: "aborted" };
+	if (event.signal?.aborted || (scopedInput && !scopedInput.isCurrent())) return { outcome: "aborted" };
 	let protocol: "remote-v2" | "standalone-compact" = "remote-v2";
 	let compactResult: Awaited<ReturnType<typeof executeRemoteV2Compaction>> | NativeCompactionClientResult = await remoteCompact({
 		runtime: compactor,
@@ -495,6 +691,7 @@ async function runResponsesNativeCompact(
 		context: ctx,
 	});
 
+	if (scopedInput && !scopedInput.isCurrent()) return { outcome: "aborted" };
 	if (!compactResult.ok) {
 		if (compactResult.reason === "aborted" || event.signal?.aborted) return { outcome: "aborted" };
 		const tryStandalone = !!standaloneCompact && isStandaloneCompactionEligible(compactor) && qualifiesForStandaloneCompaction(compactResult);
@@ -507,7 +704,7 @@ async function runResponsesNativeCompact(
 			errorType: compactResult.errorType,
 			errorParam: compactResult.errorParam,
 			errorMessage: compactResult.errorMessage,
-			nextStep: tryStandalone ? "standalone-compact" : "native-summary",
+			nextStep: tryStandalone ? "standalone-compact" : scopedInput ? "stop-and-preserve" : "native-summary",
 		}, config, ctx);
 		if (tryStandalone && standaloneCompact) {
 			if (event.signal?.aborted) return { outcome: "aborted" };
@@ -578,7 +775,7 @@ async function runResponsesNativeCompact(
 	}
 
 	const compaction = createNativeCompactionResult({
-		firstKeptEntryId: event.preparation.firstKeptEntryId,
+		firstKeptEntryId: scopedInput?.firstKeptEntryId ?? event.preparation.firstKeptEntryId,
 		tokensBefore: event.preparation.tokensBefore,
 		details,
 	});
@@ -607,12 +804,13 @@ async function runResponsesNativeCompact(
 			requestExtras: extras ? Object.keys(extras) : [],
 			compactResponseId: compactResult.compactResponseId,
 			compactedItems: compactResult.compactedWindow.length,
-			firstKeptEntryId: event.preparation.firstKeptEntryId,
+			firstKeptEntryId: compaction.firstKeptEntryId,
 		},
 		config,
 		ctx,
 	);
 
+	if (scopedInput && !scopedInput.isCurrent()) return { outcome: "aborted" };
 	return { outcome: "success", compaction };
 }
 
@@ -744,6 +942,68 @@ async function runUnavailableContextCompaction(
 	return { cancel: true };
 }
 
+const ACTIVE_REMOTE_PREPARATION_REASONS = new Set([
+	"unsafe-compaction-window-boundary", "compaction-window-boundary-missing", "compaction-system-tool-head-lost",
+	"compaction-branch-changed", "compaction-source-projection-unavailable", "unverified-window-cleanup",
+	"compaction-owner-missing", "unsafe-compaction-retained-start", "compaction-owner-mismatch",
+	"compaction-continuity-unavailable", "compaction-operation-superseded", "compaction-tool-pair-mismatch",
+	"compaction-retained-context-mismatch", "compaction-wire-adaptation-failed", "compaction-boundary-not-found",
+	"first-kept-entry-not-found", "compaction-summary-not-found", "retained-context-mismatch", "unverified-compaction-input",
+	COMPACTION_CHECKPOINT_CONTEXT_EDITED, COMPACTION_CHECKPOINT_PROVENANCE_UNAVAILABLE,
+	COMPACTION_PROJECTED_CONTEXT_UNAVAILABLE, COMPACTION_PROJECTION_UNAVAILABLE, COMPACTION_SESSION_CONTEXT_UNAVAILABLE,
+]);
+
+async function runActiveRemoteManualCompact(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+	dependencies: CompactionDependencies,
+	resolved: ResolvedToolkitConfig,
+	operation: RemoteManualCompactOperation | undefined,
+): Promise<{ cancel: true } | { compaction: CompactionResult<NativeCompactionDetails> }> {
+	const lifecycle = dependencies.remoteManualCompact;
+	const config = resolved.config.compaction;
+	const stop = (reason: string): { cancel: true } => {
+		// No exception text, provider body, auth or opaque content crosses this boundary.
+		lifecycle.cancel(operation);
+		writeDebugArtifact("compaction-event", {
+			event: "session_before_compact.remote-window-manual-stopped", reason, nextStep: "stop-and-preserve",
+		}, config, ctx);
+		notifyWarning(ctx, `Remote /compact stopped (${reason}); existing context preserved. No summary fallback or automatic continuation was started.`);
+		return { cancel: true };
+	};
+	const isCurrent = () => !!operation && lifecycle.current(operation, ctx);
+	try {
+		if (!operation || dependencies.manualCompact?.busy || !isCurrent()) return stop("compaction-operation-superseded");
+		// Producer policy and auth are resolved once from the initiating document.
+		if (resolved.format === "v2" && config.remoteCompactModel) {
+			const spec = parseModelSpec(config.remoteCompactModel);
+			if (spec) {
+				const producerPolicy = resolveToolkitConfig(resolved.snapshot, { provider: spec.provider, id: spec.modelId });
+				notifyConfigIssues(ctx, producerPolicy);
+				if (producerPolicy.invalidFeatures.includes("compatibility")) return stop("invalid-producer-compatibility");
+			}
+		}
+		const resolution = await resolveRemoteCompactionExecution(ctx, {
+			enabled: config.enabled, responsesApis: config.responsesApis, codexGatewayModels: compactGatewayModels(resolved),
+		}, config.remoteCompactModel);
+		if (!isCurrent()) return stop("compaction-operation-superseded");
+		if (!resolution.ok) return stop(resolution.reason);
+		const scopedEvent = { ...event, signal: operation.signal };
+		const input = await prepareActiveRemoteCompaction(scopedEvent, ctx, config, resolution.execution, dependencies, isCurrent);
+		if (!isCurrent()) return stop("compaction-operation-superseded");
+		const outcome = await runResponsesNativeCompact(scopedEvent, ctx, config, resolution.execution,
+			dependencies.remoteCompact, dependencies.projectCompactionContext, undefined, input);
+		if (!isCurrent()) return stop("compaction-operation-superseded");
+		if (outcome.outcome !== "success") return stop(outcome.outcome === "unprojected-input" ? outcome.reason
+			: outcome.outcome === "failed" ? outcome.remoteFailure?.reason ?? "remote-compaction-failed" : "aborted");
+		const result = lifecycle.arm(operation, ctx, outcome.compaction);
+		return result ?? stop("compaction-operation-superseded");
+	} catch (error) {
+		return stop(error instanceof Error && ACTIVE_REMOTE_PREPARATION_REASONS.has(error.message)
+			? error.message : "remote-compaction-failed");
+	}
+}
+
 async function handleSessionBeforeCompact(
 	event: SessionBeforeCompactEvent,
 	ctx: ExtensionContext,
@@ -786,16 +1046,33 @@ async function handleSessionBeforeCompact(
 		return { cancel: true };
 	}
 
+	// Capture intent BEFORE capability/auth awaits so selection/navigation/work
+	// during resolution cannot silently become the owner of an older /compact.
+	let manualOperation: RemoteManualCompactOperation | undefined;
+	if (event.reason === "manual" && !dependencies.manualCompact?.isMaintenance && config.enabled && config.contextManagement === "remote") {
+		try { manualOperation = dependencies.remoteManualCompact.begin(event, ctx, resolved); } catch { /* active route stops below */ }
+	}
+
 	// Active and inactive covered Codex consumers retain their existing routing.
 	const contextModel = config.enabled && config.contextManagement === "remote"
 		? await resolveContextCapabilityModel(ctx)
 		: undefined;
+	if (manualOperation && !dependencies.remoteManualCompact.current(manualOperation, ctx)) {
+		dependencies.remoteManualCompact.cancel(manualOperation);
+		return { cancel: true };
+	}
 	if (isCodexContextModel(contextModel, config)) {
-		if (await remoteContextActive(ctx, config, contextModel)) {
+		const active = await remoteContextActive(ctx, config, contextModel);
+		// New work may make a formerly active runtime look unavailable. That is
+		// supersession, not permission to start the inactive-runtime fallback.
+		if (manualOperation && !dependencies.remoteManualCompact.current(manualOperation, ctx)) {
+			dependencies.remoteManualCompact.cancel(manualOperation);
+			return { cancel: true };
+		}
+		if (active) {
 			try {
-				if (event.reason === "manual" && dependencies.manualCompact && !dependencies.manualCompact.isMaintenance) {
-					await dependencies.manualCompact.request(event, ctx, resolved);
-					return { cancel: true };
+				if (event.reason === "manual" && !dependencies.manualCompact?.isMaintenance) {
+					return await runActiveRemoteManualCompact(event, ctx, dependencies, resolved, manualOperation);
 				}
 				return dependencies.contextWindows.prepareCompaction(event);
 			} catch {
@@ -804,6 +1081,7 @@ async function handleSessionBeforeCompact(
 			}
 		}
 
+		dependencies.remoteManualCompact.cancel(manualOperation);
 		const registrationState = getContextToolRegistrationState();
 		const failureReason = contextManagementFailureReason(registrationState);
 		if (failureReason !== "context-tools-excluded") {
@@ -819,11 +1097,28 @@ async function handleSessionBeforeCompact(
 		);
 	}
 
+	dependencies.remoteManualCompact.cancel(manualOperation);
 	try {
 		const detached = dependencies.contextWindows.prepareDetachedCompaction(event);
 		// A local consumer cannot summarize history owned by a Remote window,
 		// even after switching modes or disabling Toolkit compaction.
 		if (detached) return detached;
+		// A boundary already persisted by an earlier detach still owns this session.
+		// Retired Remote history is outside Pi's effective projection at that point, so
+		// ordinary compaction may continue; record why it no longer detaches.
+		const ownedIdentity = dependencies.contextWindows.currentIdentity();
+		if (ownedIdentity) {
+			writeDebugArtifact(
+				"compaction-event",
+				{
+					event: "session_before_compact.detached-already-owned",
+					windowId: ownedIdentity.currentWindowId,
+					superseded: dependencies.contextWindows.hasSupersededWindow(),
+				},
+				config,
+				ctx,
+			);
+		}
 	} catch {
 		notifyRemoteContextFailure(ctx, "malformed-window-state");
 		return { cancel: true };
@@ -1040,6 +1335,11 @@ async function handleContextInternal(
 				// The latter still contains retired remote windows and can be inflated by
 				// an upstream error even though this request only carries the live window.
 				let projected = contextWindows.project(event.messages, "remote", false);
+				if (contextWindows.isPreparingCompaction) {
+					// Synthetic preparation is read-only. The caller owns the one strict
+					// retained-copy match, then encrypted wire adaptation after all hooks.
+					return { messages: projected };
+				}
 				// Projection may observe the exact queued rollover before Pi persists
 				// it. Decide replay ownership from this request, not the old branch.
 				const ownsWindow = contextWindows.hasEffectiveWindow() || !contextWindows.currentIdentity();
@@ -1200,10 +1500,11 @@ async function handleBeforeProviderRequest(
 		: undefined;
 	const remoteActive = config.contextManagement === "remote" && await remoteContextActive(ctx, config, contextModel);
 	let remotePayload: unknown;
+	let activeWindowPayload = false;
 	if (remoteActive) {
 		try {
 			remotePayload = contextWindows.rewritePayload(event.payload, ctx);
-			if (contextWindows.hasEffectiveWindow() || !contextWindows.currentIdentity()) return remotePayload;
+			activeWindowPayload = contextWindows.hasEffectiveWindow() || !contextWindows.currentIdentity();
 			event = { ...event, payload: remotePayload };
 		} catch {
 			notifyRemoteContextFailure(ctx, "malformed-request-state");
@@ -1230,10 +1531,10 @@ async function handleBeforeProviderRequest(
 
 	// Do not reintroduce a pre-window opaque checkpoint after local projection.
 	// Request affinity/encrypted-output rewriting is reserved for active Remote.
-	if (contextWindows.hasEffectiveWindow()) return undefined;
+	if (contextWindows.hasEffectiveWindow() && !activeWindowPayload) return undefined;
 
 	const branchEntries = ctx.sessionManager.getBranch();
-	const inherited = config.contextManagement === "remote" && contextWindows.hasSupersededWindow()
+	const inherited = !activeWindowPayload && config.contextManagement === "remote" && contextWindows.hasSupersededWindow()
 		? resolveLatestNativeCompactionEntry(branchEntries) : undefined;
 	const inheritedCheckpoint = inherited?.ok ? inherited.entry : undefined;
 	const resolution = await resolveNativeCompactionEnvironment(
@@ -1291,6 +1592,10 @@ async function handleBeforeProviderRequest(
 		},
 	);
 
+	// Capture is pre-Web-Search metadata only. An effective Remote window still
+	// owns this live payload and must NEVER enter ordinary opaque replay below.
+	if (activeWindowPayload) return remotePayload;
+
 	const latestNativeCompaction = resolveLatestNativeCompactionEntry(branchEntries, {
 		baseUrl: runtime.baseUrl,
 	});
@@ -1406,6 +1711,7 @@ export default function registerCompactionExtension(
 		loadHistoryNotesThreadHint(ctx, signal, gatewayModels)
 	);
 	const manualCompact = new ManagedManualCompact(pi, contextWindows);
+	const remoteManualCompact = new RemoteManualCompact(pi, contextWindows);
 	const dependencies: CompactionDependencies = {
 		remoteCompact: executeRemoteV2Compaction,
 		standaloneCompact: executeNativeCompaction,
@@ -1413,7 +1719,8 @@ export default function registerCompactionExtension(
 		contextWindows,
 		...overrides,
 		manualCompact,
-		loadConfig: () => manualCompact.snapshot ?? loadConfig(),
+		remoteManualCompact,
+		loadConfig: () => remoteManualCompact.snapshot ?? manualCompact.snapshot ?? loadConfig(),
 		piContextHookPatch: overrides.piContextHookPatch ?? piContextHookPatch,
 	};
 	let tools!: ReturnType<typeof registerContextManagementTools>;
@@ -1472,6 +1779,7 @@ export default function registerCompactionExtension(
 		}
 	};
 	pi.on("session_start", async (_event, ctx) => {
+		remoteManualCompact.invalidate();
 		const resolved = contextOperation(dependencies.loadConfig, ctx);
 		const syncOutcome = await syncTools(ctx, ctx.model, { notifyWindowFailure: true }, resolved);
 		await manualCompact.recover(ctx);
@@ -1541,12 +1849,28 @@ export default function registerCompactionExtension(
 		manualCompact.guardRequest(ctx);
 		return handleContext(event, ctx, pi, dependencies.loadConfig, contextWindows, remoteContextActive, getContextToolRegistrationState);
 	});
-	pi.on("session_before_compact", (event, ctx) => handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive, getContextToolRegistrationState));
-	pi.on("session_compact", (_event, ctx) => contextWindows.synchronize(ctx));
+	pi.on("session_before_compact", async (event, ctx) => {
+		remoteManualCompact.invalidate();
+		try {
+			return await handleSessionBeforeCompact(event, ctx, dependencies, remoteContextActive, getContextToolRegistrationState);
+		} catch {
+			// Pi treats a rejected hook as absent and can invoke its implicit summary.
+			// Unexpected preparation/service failures must never authorize that work.
+			try { notifyWarning(ctx, "Compaction stopped; existing context preserved. Resume manually."); } catch { /* stale UI */ }
+			return { cancel: true };
+		}
+	});
+	pi.on("session_compact", (event, ctx) => {
+		contextWindows.synchronize(ctx);
+		if (event.reason === "manual" && event.fromExtension) remoteManualCompact.persisted(ctx);
+		else remoteManualCompact.invalidate();
+	});
 	pi.on("session_compact_failed", async (event, ctx) => {
+		remoteManualCompact.invalidate();
 		if (event.reason === "manual" && !manualCompact.isMaintenance) await manualCompact.compactFailed(ctx);
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
+		remoteManualCompact.invalidate();
 		await manualCompact.shutdown(ctx);
 		contextWindowReady = false;
 		contextWindows.reset();
@@ -1558,6 +1882,7 @@ export default function registerCompactionExtension(
 		await manualCompact.settled(ctx);
 	});
 	pi.on("model_select", async (event, ctx) => {
+		remoteManualCompact.invalidate();
 		manualCompact.modelSelected(event.model, ctx);
 		// Switching into a covered model mid-session must open the window
 		// lifecycle immediately: without an identity the request rewrite skips
@@ -1568,13 +1893,29 @@ export default function registerCompactionExtension(
 		await syncTools(ctx, event.model, { notifyWindowFailure: true }, resolved);
 	});
 	pi.on("before_agent_start", async (_event, ctx) => {
+		remoteManualCompact.invalidate();
 		await syncTools(ctx, ctx.model, { notifyWindowFailure: true });
 	});
-	pi.on("thinking_level_select", (event, ctx) => manualCompact.thinkingSelected(event.level, ctx));
-	pi.on("message_start", (event) => manualCompact.messageStarted(event.message));
+	pi.on("agent_start", () => remoteManualCompact.invalidate());
+	pi.on("input", () => { remoteManualCompact.invalidate(); });
+	pi.on("thinking_level_select", (event, ctx) => {
+		remoteManualCompact.invalidate();
+		manualCompact.thinkingSelected(event.level, ctx);
+	});
+	pi.on("message_start", (event) => {
+		remoteManualCompact.invalidate();
+		manualCompact.messageStarted(event.message);
+	});
 	pi.on("turn_end", (_event, ctx) => manualCompact.turnEnded(ctx));
-	pi.on("tool_call", (event) => manualCompact.guardTool(event.toolName));
+	pi.on("tool_call", (event) => {
+		remoteManualCompact.invalidate();
+		return manualCompact.guardTool(event.toolName);
+	});
+	pi.on("session_before_switch", () => remoteManualCompact.invalidate());
+	pi.on("session_before_fork", () => remoteManualCompact.invalidate());
+	pi.on("session_before_tree", () => remoteManualCompact.invalidate());
 	pi.on("session_tree", async (_event, ctx) => {
+		remoteManualCompact.invalidate();
 		contextWindows.synchronize(ctx);
 		await manualCompact.recover(ctx);
 		await syncTools(ctx);