@criogaid/pi-codex-compaction 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## 未发布
 
+## 0.5.0
+
+- 检查点的普通重放和再次压缩遵守当前图片读取设置，关闭时过滤保留的原始图片。
+- 保持 V2 的工具声明与历史加载记录；符合快照条件时复用普通请求的完整序列化前缀，包括中途隐藏工具的投影和 provider 钩子改写的历史，再追加新增内容，避免重新生成旧前缀破坏缓存。
+- 修复本轮临时提示词在对话结束后使请求快照失效的问题；真正的提示词、工具、思考等级或界面以外的配置变化仍会阻止复用。
+- 切换界面主题后直接压缩仍复用普通请求的工具声明和历史前缀，避免主题变化导致隐藏工具声明重新出现。
+- 手动压缩或下一轮开始前的自动压缩不再因 Pi 在本轮结束后回到基础系统提示词而丢弃请求快照；扩展按轮调整系统提示词时，压缩仍复用普通请求的完整前缀和缓存参数。其他输入变化仍会使快照失效。
+- 切换思考块显示、终端图片、编辑器边距、全屏和 Markdown 渲染等只影响 Pi 界面的设置后，压缩继续复用请求快照。
+- 补齐 `parallel_tool_calls`、完整 `text` 输出设置和 `prompt_cache_options` 缓存模式/TTL 的复用，不复制预热操作或诊断响应 ID。服务端会话引用不被照搬，相关请求保留本地重建的完整历史。补充重复检查点、隐藏上下文保留和重试请求一致性的回归测试。
+- 兼容 Codex provider 的成功 `response.done` 事件，继续拒绝失败和未完成的响应。
+- 使用跨进程文件锁保护配置版本检查和原子替换，防止多个 Pi 进程保存同一旧版本时静默覆盖。
+- 补充上述路径的真实 Pi 会话、provider 和跨进程回归测试，以及与 Codex V2 源码的对照记录。
+- V2 重试覆盖整次 SSE 请求与响应收集，额外次数取 Pi provider 设置与 2 的较小值，关闭 provider 内层重试，避免次数相乘。只凭暂时 HTTP、网络或流错误的明确证据重试；永久错误、协议校验失败和取消不会重试。每次尝试保持请求内容和后端不变，重新认证并校验会话归属。
+- V2 压缩前按 Pi 实际准备请求的模型窗口裁剪末尾工具输出；保留原生文字回退、普通请求和模型切换行为，HTTP 重定向沿用 provider 与 fetch。
+- 压缩期间切换模型后仍保存原模型生成的结果；新检查点无法在当前后端重放时，在安装后按检查点提示一次。配置文字回退同样不因切换对话模型而取消，会话变化或主动取消仍丢弃结果。
+- 补充整次重试及兼容性回归测试，覆盖已有检查点的文字回退、跨后端继续请求、普通模型路由和被动模型切换。
+- 开发与测试依赖更新至 Pi 1.0.4 并通过完整测试；Pi 最低支持版本仍为 0.99.1。
+
+## 0.4.1
+
+- V2 模型识别改为显式 `compat.remoteCompaction` 配置优先；未配置时，`openai-responses` 或 `openai-codex-responses` 模型的 ID 包含 `gpt`（不区分大小写）即尝试 V2，不再限制服务商或官方地址；其他 API 的 GPT 模型未配置时直接使用 Pi 原生压缩，不显示失败警告。无效配置不会退回名称匹配。检查点支持保存和恢复自定义 API 标识，继续校验后端身份。
+
 ## 0.4.0
 
 - 更新压缩历史的恢复提示，明确使用当前包 `@criogaid/pi-codex-compaction`。保留旧会话摘要的精确识别与消息编辑保护，无需迁移会话文件。

package/README.md

@@ -5,7 +5,7 @@
 让 [Pi](https://github.com/earendil-works/pi) 在 Codex 模型上使用 Codex Remote Compaction V2 压缩聊天记录，失败时自动退回 Pi 原生压缩，并且可以为原生压缩单独指定一个摘要模型。
 
 - **装上即用：** 对 Codex 模型默认启用 V2 远程压缩，无需任何配置。
-- **失败自动退回：** 当前模型不支持 V2，或 V2 请求失败时，改用 Pi 原生的文字摘要压缩，对话不会中断。
+- **失败自动退回：** 当前模型不支持 V2，或 V2 请求失败时，改用 Pi 原生的文字摘要压缩。
 - **独立摘要模型（可选）：** 退回 Pi 原生压缩时，可以使用你指定的模型和思考等级生成摘要。它只接管这一步，不影响 V2 远程压缩，也不改变当前对话模型。
 
 [安装](#安装) · [工作方式](#工作方式) · [独立摘要模型](#独立摘要模型) · [配置](#配置) · [自定义网关](#自定义网关) · [注意事项](#注意事项)
@@ -31,26 +31,7 @@ pi install git:github.com/Criogaid/pi-codex-compaction
 
 ## 工作方式
 
-```text
-触发压缩（/compact、自动压缩、超出上下文）
-  |
-  v
-V2 开启，且当前模型支持 V2？ -- 否 ------------------+
-  | 是                                               |
-  v                                                  |
-用当前对话模型请求 V2 远程压缩                       |
-  |                                                  |
-  v                                                  |
-成功？ -- 是 --> 完成                                |
-  | 否                                               |
-  v                                                  |
-Pi 原生压缩（文字摘要） <----------------------------+
-  |
-  +-- 已启用独立摘要模型 --> 用指定模型和思考等级生成摘要
-  |                          失败则停止本次压缩
-  |
-  +-- 未启用 -------------> 用当前对话模型生成摘要
-```
+手动、自动或上下文溢出触发压缩时，扩展先按设置尝试 V2。V2 关闭、不支持或请求失败时，按配置使用 Pi 原生文字摘要。
 
 | 情况 | 压缩方式 | 使用的模型 |
 | --- | --- | --- |
@@ -60,8 +41,16 @@ Pi 原生压缩（文字摘要） <----------------------------+
 
 压缩完成后继续原来的对话，当前对话模型和思考等级保持不变。V2 失败、改用独立摘要模型时，Pi 会显示提示及实际使用的模型。
 
+已有 V2 检查点也允许文字摘要回退。Pi 的文字摘要只能使用可读取的摘要和近期消息，无法解读检查点的加密历史；回退成功后，新的文字摘要成为后续对话上下文。
+
 `/compact` 后附加的要求（例如“重点保留尚未完成的任务”）只对 Pi 原生压缩生效。V2 不接受这些要求，扩展会提示它们被忽略。
 
+### 请求失败与重试
+
+V2 对一次完整的 SSE 请求及其响应收集进行有限重试，覆盖可确认的暂时 HTTP 错误、网络错误和有响应进展后提前结束的流。额外重试次数取 Pi 的 provider 重试设置与 2 的较小值；未设置时最多额外重试 2 次，总共最多 3 次请求，设置为 0 时不重试。每次重试使用同一份已准备的请求内容和同一后端，并重新通过 Pi 认证。
+
+无效压缩结果、重复输出、权限或额度等永久错误、取消操作，以及无法确认属于暂时故障的错误，不会重试。服务端要求等待的时间超过允许上限时也会停止重试。重试耗尽后按上表转为 Pi 文字摘要。HTTP 重定向沿用 provider 和 fetch 的处理方式。
+
 ## 独立摘要模型
 
 假设你平时用 `gpt-6-astra` 聊天，希望退回原生压缩时改用 `gpt-6.1-sol` 生成摘要：
@@ -135,15 +124,15 @@ Pi 原生压缩（文字摘要） <----------------------------+
 - 文件无法读取、JSON 格式错误或 V2 设置无效时，停止压缩。
 - `fallback` 部分只在需要原生压缩时校验，因此它填错不会影响成功的 V2 压缩。
 - `fallback` 无效时菜单显示 `Invalid`。你仍可切换 V2，已填写的内容会原样保留；重新选择模型即可修复，之后需要打开 `Use separate summary model` 才会使用它。
-- 打开菜单后配置文件被其他程序修改时，保存会失败；重新打开菜单再操作即可。
+- 多个 Pi 进程保存同一个配置时会互斥；同一旧版本只能有一个修改成功，其他菜单须重新打开。直接编辑文件时仍会在保存前检查版本；外部编辑器不参与 Pi 的保存锁。
 
 </details>
 
 ## 自定义网关
 
-默认只有 Pi 自带的 `openai-codex` 服务商（官方地址）会尝试 V2。其他网关须本身支持 Codex Remote Compaction V2，仅兼容普通 Responses API 不够；模型的 API 类型须为 `openai-responses` 或 `openai-codex-responses`。
+模型是否尝试 V2 由 `compat.remoteCompaction` 决定：有配置时按配置判断；没有配置时，API 类型为 `openai-responses` 或 `openai-codex-responses` 且模型 ID 包含 `gpt`（不区分大小写）即尝试 V2。其他 API 的请求格式无法携带 V2 压缩，未配置时直接使用 Pi 原生压缩。服务商名称和是否使用官方地址不参与启用判断。显示名称不参与匹配。
 
-在 Pi 的 `models.json` 中为模型添加 `compat.remoteCompaction`：
+显式配置须指定 `protocol: "v2"`，可同时指定 `endpoint`。协议或端点配置无效时不尝试 V2，也不会退回名称匹配。非 GPT 模型或需要覆盖端点时，可以在 Pi 的 `models.json` 中添加：
 
 ```json
 {
@@ -154,7 +143,7 @@ Pi 原生压缩（文字摘要） <----------------------------+
       "apiKey": "$CUSTOM_CODEX_API_KEY",
       "models": [
         {
-          "id": "gpt-example",
+          "id": "custom-model",
           "compat": {
             "remoteCompaction": {
               "protocol": "v2"
@@ -171,13 +160,19 @@ Pi 原生压缩（文字摘要） <----------------------------+
 
 网关的压缩请求使用其他路径时，可以在 `remoteCompaction` 内增加 `endpoint`。它的协议、主机和端口须与 Pi 认证后实际使用的 `baseUrl` 一致，且不能包含用户名、密码、查询参数（`?`）或片段（`#`）。
 
+V2 总开关仍决定是否发送新的远程压缩请求。模型名匹配只决定是否尝试；Pi 的适配器和网关仍须实际支持 V2，请求失败时退回 Pi 原生压缩。默认端点按 API 推导：`openai-codex-responses` 使用 Codex 路径，其他 API 使用 `/responses`。检查点继续绑定实际 provider、API 和端点，防止跨后端重放。
+
 ## 注意事项
 
-- **V2 压缩结果绑定服务商。** V2 压缩后的旧记录以加密数据保存，只有原服务能读取，扩展无法还原成文字。重新打开会话或创建分支时可以继续使用，但须保持服务商、API 类型和请求地址不变。换到其他服务后，原生压缩只能根据 Pi 仍可读取的摘要和消息生成，无法包含这部分加密记录。
-- **同一服务内切换模型。** 扩展会继续发送已压缩的记录；如果新模型不接受，需要切回原模型。V2 协议仍属实验性质。
-- **关闭 V2 不影响已有记录。** 已经用 V2 压缩的记录仍会照常发送。
-- **加载顺序。** 压缩后 Pi 会保留一部分近期消息。如果它们被其他扩展改写，本扩展可能无法确认其与已压缩记录对应，从而停止使用那部分记录。搭配会改写聊天内容的扩展时，请把本包放在 Pi 的 `packages` 列表靠前的位置。
-- **缓存。** 会话、模型、历史前缀、工具和设置未变时，压缩请求会复用最近一次普通请求中观察到的系统指令、工具定义、缓存标识和思考等选项。关闭或隐藏的工具不会因为压缩重新出现在这份工具声明中。记录只覆盖本扩展收到的请求内容，之后执行的扩展仍可能改写它；服务端也自行决定是否使用缓存，因此不保证缓存命中或费用下降。
+- **V2 压缩结果绑定服务商。** V2 压缩后的旧记录以加密数据保存，扩展无法还原成文字。重新打开会话或创建分支时可以继续使用，但须保持服务商、API 类型和请求地址不变。换到其他后端后，扩展跳过加密历史，继续使用 Pi 可读取的摘要和近期消息。
+- **同一服务内切换模型。** 扩展继续重放检查点，服务端决定新模型是否接受。模型切换本身不会触发压缩；后续 V2 使用当前对话模型，窗口容量由 Pi 和 provider 处理。普通请求的模型路由沿用 Pi 及其他扩展的处理结果。压缩进行中切换模型不会取消压缩，结果仍由开始时的模型生成并保存，与 Pi 原生压缩一致；如果新模型属于其他后端，扩展会提示新结果无法在当前后端重放。
+- **关闭 V2 不影响已有记录的重放。** 已压缩记录仍可在原后端照常发送；下一次压缩按配置使用文字摘要。
+- **关闭图片读取。** Pi 的 `images.blockImages` 设置也适用于检查点中保留的原始图片；普通重放和再次压缩都会用文字占位替换这些图片。已有保存记录不被修改，但关闭期间生成的新检查点会保留本次发送的占位符，之后重新开启读取不保证能恢复更早的原始图片。该设置不能删除已经包含在加密压缩结果中的图像信息。
+- **加载顺序。** 压缩后 Pi 会保留一部分近期消息。如果它们被其他扩展改写，本扩展可能无法确认其与已压缩记录对应，便跳过加密历史并继续普通请求。搭配会改写聊天内容的扩展时，请把本包放在 Pi 的 `packages` 列表靠前的位置。
+- **工具声明。** V2 保留工具声明、历史中的工具加载记录及实际调用与结果。符合快照条件时复用最近一次普通请求的声明；没有可用快照时，由 Pi 序列化会话中的工具元数据。Pi 未公开工具隐藏状态的修订号；只改变隐藏状态而其他公开设置未变时，旧快照仍可能被复用。
+- **缓存复用。** 会话、模型、后端、历史前缀、工具和设置匹配时，压缩请求复用最近一次普通请求中观察到的完整前缀，包括中途工具加载和历史改写，再追加新增内容。本轮结束后 Pi 回到基础提示词、本轮临时提示词结束，或只修改主题、思考块显示、终端和编辑器外观等界面设置，都不会使匹配的快照失效；真正的提示词或其他配置变化仍会失效。系统指令、思考、服务等级、并行工具调用、输出格式、verbosity、缓存键及缓存模式/TTL 随快照复用，诊断响应 ID 和预热操作不被复制。普通请求依赖服务端会话引用时，仅复用独立参数，历史由 Pi 从本地上下文重建。记录只覆盖本扩展收到的请求内容，之后执行的扩展仍可能改写它；服务端自行决定是否使用缓存，因此不保证命中或费用下降。
+
+与 Codex 客户端的源码对照、已还原部分和差异见 [V2 实现对照](docs/verification/codex-v2-parity.md)。
 
 ## 开发
 
@@ -197,7 +192,7 @@ npm run pack:check
 <details>
 <summary><strong>发布流程</strong></summary>
 
-[Publish](.github/workflows/publish.yml) 在推送 `v*` 标签时运行。标签须与 `package.json` 的版本一致，例如版本 `0.4.0` 对应标签 `v0.4.0`。目前只发布正式版本，不接受 `-beta`、`-rc` 等预发布后缀。
+[Publish](.github/workflows/publish.yml) 在推送 `v*` 标签时运行。标签须与 `package.json` 的版本一致，例如版本 `0.5.0` 对应标签 `v0.5.0`。目前只发布正式版本，不接受 `-beta`、`-rc` 等预发布后缀。
 
 首次发布前，在仓库的 **Settings → Secrets and variables → Actions** 中添加 `NPM_TOKEN`。按 [npm 文档](https://docs.npmjs.com/creating-and-viewing-access-tokens)创建 granular access token，授予 `@criogaid` 作用域的发布权限（Read and write / publish and stage），并启用 Bypass two-factor authentication。包创建后，可以将 token 权限缩小到该包。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@criogaid/pi-codex-compaction",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Provider-aware Codex Remote Compaction V2 for Pi.",
   "type": "module",
   "repository": {
@@ -41,14 +41,16 @@
     "@earendil-works/pi-tui": ">=0.99.1"
   },
   "dependencies": {
+    "proper-lockfile": "4.1.2",
     "saxes": "6.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.99.1",
-    "@earendil-works/pi-ai": "0.99.1",
-    "@earendil-works/pi-coding-agent": "0.99.1",
-    "@earendil-works/pi-tui": "0.99.1",
+    "@earendil-works/pi-agent-core": "1.0.4",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
     "@types/node": "26.1.1",
+    "@types/proper-lockfile": "4.1.4",
     "typescript": "7.0.2"
   },
   "pi": {

package/src/capability.ts

@@ -1,23 +1,20 @@
 // Own model eligibility and endpoint identity; authentication supplies the effective base URL.
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { hasApi } from "@earendil-works/pi-ai";
 import { isObject } from "./protocol.js";
 
 export const CODEX_API = "openai-codex-responses" as const;
-export const OPENAI_RESPONSES_API = "openai-responses" as const;
-export type RemoteCompactionApi = typeof CODEX_API | typeof OPENAI_RESPONSES_API;
-const OFFICIAL_PROVIDER = "openai-codex";
-const OFFICIAL_BASE_URL = "https://chatgpt.com/backend-api";
+// Name-matched models need a Responses payload with an input array and a query-free request URL.
+const NAME_MATCH_APIS: readonly Api[] = ["openai-responses", CODEX_API];
 
 export interface ProviderIdentity {
   readonly provider: string;
-  readonly api: RemoteCompactionApi;
+  readonly api: Api;
   readonly modelId: string;
   readonly baseUrl: string;
   readonly endpoint: string;
 }
 export interface CapableModel {
-  readonly model: Model<RemoteCompactionApi>;
+  readonly model: Model<Api>;
   readonly identity: ProviderIdentity;
 }
 
@@ -30,18 +27,15 @@ export function normalizeUrl(value: string): string {
   url.pathname = url.pathname.replace(/\/+$/, "") || "/";
   return url.toString().replace(/\/$/, "");
 }
-/** Mirror Pi 0.99's resolveCodexUrl and the OpenAI SDK's `/responses` route for a normalized base URL. */
-export function deriveEndpoint(baseUrl: string, api: RemoteCompactionApi): string {
-  if (api === OPENAI_RESPONSES_API) return `${baseUrl}/responses`;
+/** Use Pi's Codex route for that adapter and the Responses route for other APIs. */
+export function deriveEndpoint(baseUrl: string, api: Api): string {
+  if (api !== CODEX_API) return `${baseUrl}/responses`;
   if (baseUrl.endsWith("/codex/responses")) return baseUrl;
   if (baseUrl.endsWith("/codex")) return `${baseUrl}/responses`;
   return `${baseUrl}/codex/responses`;
 }
 
-function configuredEndpoint(model: Model<RemoteCompactionApi>, baseUrl: string): string | undefined {
-  // Pi preserves extension metadata but its built-in compatibility type does not declare it.
-  const compat: unknown = model.compat;
-  const value = isObject(compat) ? compat.remoteCompaction : undefined;
+function configuredEndpoint(value: unknown, model: Model<Api>, baseUrl: string): string | undefined {
   if (!isObject(value) || value.protocol !== "v2" ||
       (value.endpoint !== undefined && typeof value.endpoint !== "string")) return undefined;
   try {
@@ -54,7 +48,12 @@ function configuredEndpoint(model: Model<RemoteCompactionApi>, baseUrl: string):
 }
 
 export function capableModel(model: Model<Api> | undefined, effectiveBaseUrl?: string): CapableModel | undefined {
-  if (!model || (!hasApi(model, CODEX_API) && !hasApi(model, OPENAI_RESPONSES_API))) return undefined;
+  if (!model) return undefined;
+  // Pi preserves extension metadata but its built-in compatibility type does not declare it.
+  const compat: unknown = model.compat;
+  const configured = isObject(compat) ? compat.remoteCompaction : undefined;
+  if (configured === undefined &&
+      (!NAME_MATCH_APIS.includes(model.api) || !model.id.toLowerCase().includes("gpt"))) return undefined;
   let configuredBaseUrl: string;
   let baseUrl: string;
   try {
@@ -63,8 +62,8 @@ export function capableModel(model: Model<Api> | undefined, effectiveBaseUrl?: s
   } catch {
     return undefined;
   }
-  const endpoint = model.provider === OFFICIAL_PROVIDER && hasApi(model, CODEX_API) && configuredBaseUrl === OFFICIAL_BASE_URL
-    ? deriveEndpoint(baseUrl, CODEX_API) : configuredEndpoint(model, baseUrl);
+  const endpoint = configured === undefined
+    ? deriveEndpoint(baseUrl, model.api) : configuredEndpoint(configured, model, baseUrl);
   return endpoint ? {
     model,
     identity: { provider: model.provider, api: model.api, modelId: model.id, baseUrl, endpoint },

package/src/checkpoint.ts

@@ -12,8 +12,6 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { isObject, type JsonObject, REMOTE_COMPACTION_PROTOCOL, validateCompactionItem } from "./protocol.js";
 import {
-  CODEX_API,
-  OPENAI_RESPONSES_API,
   normalizeUrl,
   type ProviderIdentity,
 } from "./capability.js";
@@ -102,7 +100,8 @@ export function parseCheckpointDetails(value: unknown): CodexCheckpointDetails |
     value.checkpointId.length < 8 ||
     typeof value.provider !== "string" ||
     !value.provider ||
-    (value.api !== CODEX_API && value.api !== OPENAI_RESPONSES_API) ||
+    typeof value.api !== "string" ||
+    !value.api ||
     typeof value.modelId !== "string" ||
     !value.modelId ||
     typeof value.baseUrl !== "string" ||

package/src/fallback-settings.ts

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { lstat, mkdir, open, rename, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
 import { isObject } from "./protocol.js";
 
 export const COMPACTION_SETTINGS_RELATIVE_PATH = "extensions/pi-codex-compaction/config.json";
@@ -28,6 +29,35 @@ interface SettingsFile {
   readonly mode: number;
 }
 
+async function withSettingsLock(path: string, save: (assertOwned: () => void) => Promise<void>): Promise<void> {
+  let compromised: Error | undefined;
+  const release = await lockfile.lock(path, {
+    // The target can be absent on its first save; the adjacent lock still serializes its creation.
+    realpath: false,
+    retries: { retries: 10, factor: 1.5, minTimeout: 20, maxTimeout: 100 },
+    onCompromised: (error) => { compromised = error; },
+  }).catch((error: unknown) => {
+    throw new Error(isObject(error) && error.code === "ELOCKED"
+      ? `Compaction settings at ${path} are being edited by another Pi process; reopen /codex-compaction and try again`
+      : `Could not lock compaction settings at ${path}`, { cause: error });
+  });
+  const assertOwned = () => {
+    if (compromised) throw new Error(`Compaction settings lock was lost at ${path}; reopen /codex-compaction and try again`, { cause: compromised });
+  };
+  try {
+    assertOwned();
+    await save(assertOwned);
+  } finally {
+    try {
+      await release();
+    } catch (error) {
+      // A compromised lock is already released by proper-lockfile; surface that cause below.
+      if (!compromised) throw new Error(`Could not release compaction settings lock at ${path}`, { cause: error });
+    }
+    assertOwned();
+  }
+}
+
 async function readSettingsFile(path: string): Promise<SettingsFile> {
   let file;
   try {
@@ -133,7 +163,8 @@ function parseFallback(fallback: unknown): FallbackConfiguration {
 
 /**
  * Capture one revision; reading configuration.fallback validates it on demand and can throw.
- * Saving detects edits before atomic replacement; a selection without a fallback field keeps the file's fallback as written.
+ * Saving locks across Pi processes before checking the revision and atomically replacing the file.
+ * A selection without a fallback field keeps the file's fallback as written.
  */
 export async function loadCompactionSettings(path: string) {
   const original = await readSettingsFile(path);
@@ -150,31 +181,34 @@ export async function loadCompactionSettings(path: string) {
       const fallback = "fallback" in selection ? selection.fallback : rawFallback?.value;
       await withFileMutationQueue(path, async () => {
         await mkdir(dirname(path), { recursive: true });
-        const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
-        const bytes = Buffer.from(`${JSON.stringify({
-          version: SETTINGS_VERSION,
-          remoteCompaction: { enabled: selection.remoteCompactionEnabled },
-          ...(fallback === undefined ? {} : { fallback }),
-        }, null, 2)}\n`);
-        if (bytes.length > MAX_SETTINGS_BYTES) throw new Error(`Compaction settings must not exceed ${MAX_SETTINGS_BYTES} bytes`);
-        try {
-          await writeFile(temporary, bytes, { flag: "wx", mode: original.mode });
-          const current = await readSettingsFile(path);
-          if (original.bytes === undefined ? current.bytes !== undefined : !current.bytes?.equals(original.bytes)) {
-            throw new Error("Compaction settings changed while the menu was open; reopen /codex-compaction and try again");
+        await withSettingsLock(path, async (assertOwned) => {
+          const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+          const bytes = Buffer.from(`${JSON.stringify({
+            version: SETTINGS_VERSION,
+            remoteCompaction: { enabled: selection.remoteCompactionEnabled },
+            ...(fallback === undefined ? {} : { fallback }),
+          }, null, 2)}\n`);
+          if (bytes.length > MAX_SETTINGS_BYTES) throw new Error(`Compaction settings must not exceed ${MAX_SETTINGS_BYTES} bytes`);
+          try {
+            await writeFile(temporary, bytes, { flag: "wx", mode: original.mode });
+            const current = await readSettingsFile(path);
+            if (original.bytes === undefined ? current.bytes !== undefined : !current.bytes?.equals(original.bytes)) {
+              throw new Error("Compaction settings changed while the menu was open; reopen /codex-compaction and try again");
+            }
+            // Reading follows existing symlinks; an atomic replacement would remove the link itself.
+            const entry = await lstat(path).catch((error: unknown) => {
+              if (isObject(error) && error.code === "ENOENT") return undefined;
+              throw error;
+            });
+            if (entry?.isSymbolicLink()) {
+              throw new Error(`Compaction settings are a symbolic link; edit its target directly at ${path}`);
+            }
+            assertOwned();
+            await rename(temporary, path);
+          } finally {
+            await rm(temporary, { force: true });
           }
-          // Reading follows existing symlinks; an atomic replacement would remove the link itself.
-          const entry = await lstat(path).catch((error: unknown) => {
-            if (isObject(error) && error.code === "ENOENT") return undefined;
-            throw error;
-          });
-          if (entry?.isSymbolicLink()) {
-            throw new Error(`Compaction settings are a symbolic link; edit its target directly at ${path}`);
-          }
-          await rename(temporary, path);
-        } finally {
-          await rm(temporary, { force: true });
-        }
+        });
       });
     },
   };

package/src/index.ts

@@ -30,7 +30,7 @@ import {
   projectCheckpointContext,
   projectCheckpointRequest,
 } from "./checkpoint.js";
-import { hasCheckpointMarker, type JsonObject, REMOTE_COMPACTION_PROTOCOL, rewriteCheckpointMarker } from "./protocol.js";
+import { hasCheckpointMarker, type JsonObject, REMOTE_COMPACTION_PROTOCOL, rewriteCheckpointMarker, withoutInputImages } from "./protocol.js";
 import { requestRemoteCompaction } from "./remote.js";
 import { requestFallbackCompaction } from "./fallback.js";
 import { COMPACTION_SETTINGS_RELATIVE_PATH, loadCompactionSettings, type CompactionConfiguration } from "./fallback-settings.js";
@@ -39,6 +39,8 @@ import { compactionRequest, providerRequestFor, RequestSnapshotTracker, type Pro
 
 const STATUS_KEY = "codex-compaction";
 const COMPLETION_ENTRY_TYPE = "pi-codex-compaction-completed";
+const INCOMPATIBLE_BACKEND_WARNING =
+  "The active Codex checkpoint cannot replay on this provider backend; only its fallback marker and retained recent messages remain available.";
 
 interface CompletionEntryData {
   message: string;
@@ -103,7 +105,7 @@ function projectedCurrentMessages(
   return { messages: projected, prior };
 }
 
-async function replayCheckpoint(payload: unknown, ctx: ExtensionContext): Promise<JsonObject | undefined> {
+async function replayCheckpoint(payload: unknown, ctx: ExtensionContext, blockImages: boolean): Promise<JsonObject | undefined> {
   const checkpoint = activeCheckpoint(ctx);
   if (!checkpoint) return undefined;
   const marker = checkpointMarker(checkpoint.details.checkpointId);
@@ -111,7 +113,8 @@ async function replayCheckpoint(payload: unknown, ctx: ExtensionContext): Promis
   if (!await compatibleIdentity(checkpoint.details, ctx)) {
     throw new Error("The active opaque checkpoint no longer matches the resolved provider endpoint");
   }
-  return rewriteCheckpointMarker(payload, marker, checkpoint.details.replacementHistory);
+  const history = checkpoint.details.replacementHistory;
+  return rewriteCheckpointMarker(payload, marker, blockImages ? withoutInputImages(history) : history);
 }
 
 function errorMessage(error: unknown): string {
@@ -123,6 +126,7 @@ function notifyFailure(ctx: ExtensionContext, error: unknown): void {
   ctx.ui.notify(`Codex remote compaction failed; using Pi compaction. ${errorMessage(error)}`, "warning");
 }
 
+/** A model switch never cancels compaction; it finishes with the model selected when it started, as Pi's does. */
 function sessionStillOwned(ctx: ExtensionContext, sessionId: string, signal: AbortSignal): boolean {
   return !signal.aborted && ctx.sessionManager.getSessionId() === sessionId;
 }
@@ -133,7 +137,7 @@ async function compactFallback(
   ctx: ExtensionContext,
   sessionId: string,
   configuration: CompactionConfiguration,
-  remoteError?: unknown,
+  remoteError: unknown,
 ) {
   let announced = false;
   try {
@@ -147,7 +151,7 @@ async function compactFallback(
       signal: event.signal,
       sessionId,
       onPrepared: ({ model, thinkingLevel }) => {
-        if (!sessionStillOwned(ctx, sessionId, event.signal)) throw new Error("Compaction session ownership changed");
+        if (!sessionStillOwned(ctx, sessionId, event.signal)) throw new Error("Compaction session changed");
         if (announced) return;
         announced = true;
         ctx.ui.setStatus(STATUS_KEY, "Pi fallback compaction...");
@@ -183,48 +187,51 @@ async function compactRemotely(
 ) {
   const supported = capableModel(ctx.model);
   const sessionId = ctx.sessionManager.getSessionId();
-  if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+  const owned = () => sessionStillOwned(ctx, sessionId, event.signal);
+  if (!owned()) return { cancel: true };
   let configuration: CompactionConfiguration;
   try {
     configuration = (await loadCompactionSettings(compactionSettingsPath)).configuration;
   } catch (error) {
-    if (sessionStillOwned(ctx, sessionId, event.signal) && ctx.hasUI) {
+    if (owned() && ctx.hasUI) {
       ctx.ui.notify(`Could not read compaction settings; compaction stopped. ${errorMessage(error)}`, "error");
     }
     return { cancel: true };
   }
-  if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
-  if (!configuration.remoteCompactionEnabled || !supported) return compactFallback(pi, event, ctx, sessionId, configuration);
+  if (!owned()) return { cancel: true };
+  if (!configuration.remoteCompactionEnabled || !supported) return compactFallback(pi, event, ctx, sessionId, configuration, undefined);
   const reasoning = pi.getThinkingLevel();
   const settings = pi.getSettings();
   let announced = false;
   ctx.ui.setStatus(STATUS_KEY, "Codex remote compaction...");
   try {
-    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    if (!owned()) return { cancel: true };
     if (event.customInstructions?.trim() && ctx.hasUI) {
       ctx.ui.notify("Codex Remote Compaction V2 does not accept custom instructions; they are ignored.", "warning");
     }
     const current = projectedCurrentMessages(event, supported.identity);
     const inputs = providerRequestInputs(pi, ctx);
+    const providerRequest = providerRequestFor(snapshots, sessionId, supported, current.messages, inputs);
     const request = compactionRequest(snapshots, sessionId, supported, current.messages, {
       blockImages: settings.images?.blockImages ?? false,
       systemPrompt: () => ctx.getSystemPrompt(),
       tools: () => activeTools(pi),
-    });
+    }, providerRequest);
     const response = await requestRemoteCompaction({
       modelRegistry: ctx.modelRegistry,
       model: supported.model,
       context: request.context,
       userItemOrigins: userItemOrigins(request.messages),
-      providerRequest: providerRequestFor(snapshots, sessionId, supported, current.messages, inputs),
+      providerRequest,
       reasoning,
       sessionId,
       thinkingBudgets: settings.thinkingBudgets,
+      blockImages: settings.images?.blockImages ?? false,
       maxRetries: settings.retry?.provider?.maxRetries,
       maxRetryDelayMs: settings.retry?.provider?.maxRetryDelayMs,
       signal: event.signal,
       onPrepared: () => {
-        if (!sessionStillOwned(ctx, sessionId, event.signal)) throw new Error("Compaction session ownership changed");
+        if (!owned()) throw new Error("Compaction session changed");
         // Provider retries prepare the payload again; announce the compaction once.
         if (announced) return;
         announced = true;
@@ -242,12 +249,12 @@ async function compactRemotely(
         : undefined,
       fetch,
     });
-    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    if (!owned()) return { cancel: true };
     const retention = await prepareRetention(response.promptInput, event.signal, {
       images: response.images,
       contextual: response.contextual,
     });
-    if (!sessionStillOwned(ctx, sessionId, event.signal)) return { cancel: true };
+    if (!owned()) return { cancel: true };
     const replacementHistory = buildReplacementHistory(retention, response.item);
     const details = createCheckpointDetails({
       identity: response.identity,
@@ -264,7 +271,7 @@ async function compactRemotely(
       },
     };
   } catch (error) {
-    if (event.signal.aborted || ctx.sessionManager.getSessionId() !== sessionId) {
+    if (!owned()) {
       return { cancel: true };
     }
     return await compactFallback(pi, event, ctx, sessionId, configuration, error);
@@ -283,6 +290,12 @@ export function createCodexCompactionExtension(
     registerCompactionCommand(pi, compactionSettingsPath);
     const warnings = new Set<string>();
     const snapshots = new RequestSnapshotTracker();
+    const warnOnce = (ctx: ExtensionContext, key: string, message: string) => {
+      const scoped = `${ctx.sessionManager.getSessionId()}:${key}`;
+      if (warnings.has(scoped)) return;
+      warnings.add(scoped);
+      if (ctx.hasUI) ctx.ui.notify(message, "warning");
+    };
 
     pi.registerEntryRenderer<CompletionEntryData>(
       COMPLETION_ENTRY_TYPE,
@@ -303,7 +316,7 @@ export function createCodexCompactionExtension(
       compactRemotely(pi, event, ctx, compactionSettingsPath, options.fetch, snapshots.current()),
     );
 
-    pi.on("session_compact", (event) => {
+    pi.on("session_compact", async (event, ctx) => {
       if (!event.fromExtension) return;
       const details = parseCheckpointDetails(event.compactionEntry.details);
       if (!details) return;
@@ -312,6 +325,9 @@ export function createCodexCompactionExtension(
         protocol: REMOTE_COMPACTION_PROTOCOL,
         checkpointId: details.checkpointId,
       });
+      // The model may have switched to another backend while compaction ran.
+      if (await compatibleIdentity(details, ctx)) return;
+      warnOnce(ctx, `${details.checkpointId}:backend`, INCOMPATIBLE_BACKEND_WARNING);
     });
 
     pi.on("context", async (event, ctx) => {
@@ -320,16 +336,8 @@ export function createCodexCompactionExtension(
       if (!checkpoint || !await compatibleIdentity(checkpoint.details, ctx)) return undefined;
       const messages = projectCheckpointContext(event.messages, checkpoint.details);
       if (messages) return { messages };
-      const key = `${ctx.sessionManager.getSessionId()}:${checkpoint.details.checkpointId}:projection`;
-      if (!warnings.has(key)) {
-        warnings.add(key);
-        if (ctx.hasUI) {
-          ctx.ui.notify(
-            "The active Codex checkpoint no longer matches the retained messages, so its opaque history is not replayed.",
-            "warning",
-          );
-        }
-      }
+      warnOnce(ctx, `${checkpoint.details.checkpointId}:projection`,
+        "The active Codex checkpoint no longer matches the retained messages, so its opaque history is not replayed.");
       return undefined;
     });
 
@@ -344,29 +352,26 @@ export function createCodexCompactionExtension(
     });
 
     pi.on("before_provider_request", async (event, ctx) => {
-      const payload = await replayCheckpoint(event.payload, ctx);
+      const payload = await replayCheckpoint(event.payload, ctx, pi.getSettings().images?.blockImages ?? false);
       snapshots.recordProviderRequest(
         ctx.sessionManager.getSessionId(),
         capableModel(ctx.model),
         () => canonicalMessages(ctx),
         () => ctx.getSystemPrompt(),
-        () => ({ payload: payload ?? event.payload, inputs: providerRequestInputs(pi, ctx) }),
+        // Keep the wire marker in the snapshot; ordinary requests and V2 each replay it exactly once.
+        () => ({ payload: event.payload, inputs: providerRequestInputs(pi, ctx) }),
       );
       return payload;
     });
 
+    pi.on("agent_settled", (_event, ctx) => {
+      snapshots.recordSettledRun(ctx.sessionManager.getSessionId(), capableModel(ctx.model), () => providerRequestInputs(pi, ctx));
+    });
+
     pi.on("model_select", async (event, ctx) => {
       const checkpoint = activeCheckpoint(ctx);
       if (!checkpoint || await compatibleIdentity(checkpoint.details, ctx, event.model)) return;
-      const key = `${ctx.sessionManager.getSessionId()}:${event.model.provider}:${event.model.id}`;
-      if (warnings.has(key)) return;
-      warnings.add(key);
-      if (ctx.hasUI) {
-        ctx.ui.notify(
-          "The active Codex checkpoint cannot replay on this provider backend; only its fallback marker and retained recent messages remain available.",
-          "warning",
-        );
-      }
+      warnOnce(ctx, `${event.model.provider}:${event.model.id}`, INCOMPATIBLE_BACKEND_WARNING);
     });
 
     pi.on("session_shutdown", (_event, ctx) => {