OpenCodex 会话回滚根因剖析：Codex App 重启后历史丢失的定位与非破坏性修复

OpenCodex 会话回滚根因剖析Codex App 重启后历史丢失的定位与非破坏性修复【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodex导读本文基于 OpenCodexUniversal provider proxy for OpenAI Codex Claude Code开发日志中的一次真实事故复盘00_investigation.md 与 10_fix-and-verification.md完整还原Codex 桌面端重启后会话/线程列表回滚到最后一次ocx start快照这一数据丢失类 Bug 的定位过程、根因机制与修复方案。读完本文你将掌握OpenCodex 与原生 Codex 之间历史文件rollout JSONL 与state_5.sqlite的竞争写入原理、inode 交换如何杀死App 的缓存写句柄、以及一套追加 原位等长改写的非破坏性历史恢复协议。一、问题现象会话列表回到过去1.1 用户观察到的行为用户在终端前台运行ocx start启动 OpenCodex 代理通过Ctrl-C停止后再次启动。关闭并重新打开 Codex 桌面端时会话/线程列表回退到了最后一次ocx start时的状态——此时间点之后产生的对话凭空消失。用用户自己的记号描述期望循环a a b - b - b标签在opencodex - openai之间翻转内容始终向前推进实际循环a a b - a - a新产生的轮次b丢失列表被吸回旧状态。1.2 触发条件代理以前台进程方式运行bun src/cli/index.ts start而非安装为系统服务进程通过SIGINTCtrl-C/SIGTERM/SIGHUP/exit正常终止终止路径会触发syncCleanup见 src/cli/index.ts进而调用restoreNativeCodex()并执行syncCodexHistoryProvider(openai)的原生方向历史还原。二、根因还原行为正确但实现毁掉了实时数据2.1 还原本身是有意的OpenCodex 在注入路由后会把会话线程打上opencodex标签而原生 Codex 只能恢复openai标签的线程。因此代理在退出时把标签翻回openai是有意设计revert 行为让用户下次以纯原生 Codex 打开时仍能继续会话。问题出在这一还原动作的底层文件实现它破坏了 App 正在写入的实时数据。2.2 罪魁祸首一updateSessionMeta的 atomicWriteFile 交换 inode对照 codex-rs~/Developer/codex/121_openai-codex/codex-rs源码可确认问题链路旧实现updateSessionMeta对每个 rollout JSONL 使用atomicWriteFile先写临时文件再 rename重写文件rename 会替换文件的 inodeCodex App 缓存了当前活动会话的追加写句柄只有当句柄消失时才重新打开文件codex-rsrollout/src/recorder.rs的RolloutWriterState::ensure_writer_openrename 之后 App 的缓存句柄仍指向被孤立orphaned的旧 inode而路径上只剩 OpenCodex 写入的快照内容App 后续产生的新对话都写进了孤儿 inode路径上的文件永远停留在快照状态 →下次重启时新内容丢失。这正是列表回滚到最后一个ocx start快照的直接原因。2.3 罪魁祸首二对state_5.sqlite的双写竞争代理还以第二个写连接打开了 App 正在使用的state_5.sqliteWAL 模式且没有设置busy_timeout与 App 自己的连接池直接竞争写锁可能导致数据库层面出现半应用half-applied的 checkpoint 或锁失败。2.4 证据链lsof显示codex app-server持有state_5.sqliteps显示前台运行的bun src/cli/index.ts start代理没有OCX_SERVICE环境变量ocx status输出Service: not installedcodex-rsstate/src/runtime.rs以WAL synchronousNORMAL busy_timeout5s打开并池化数据库列表视图以数据库为单一事实来源use_state_db_onlycodex-rs 对线程 provider 有两条读取路径详见下节旧实现只覆盖了其中一条。三、两条读取路径为什么只改第一行不够codex-rs 读取一个线程的 provider 有两条独立路径读取路径机制对应 codex-rs 代码SQLite 回放按文件顺序折叠fold每一条session_meta最后写入者胜出last-writer-winsstate/src/extract.rs的apply_session_meta_from_item首行读取 克隆只读 rollout 的第一行并在后续写入 git/memory-mode 元数据时克隆它rollout/src/list.rs的read_session_meta_line与thread-store/src/local/update_thread_metadata.rs真实 rollout 文件里本来就可能存在多条session_meta行例如分叉/续写场景。任何修复若只处理一条路径另一条路径仍会把过期的 provider 标签复活。四、两次被否决的修复尝试gpt-5.5 评审在最终方案之前有两个候选被明确 BLOCKv1就地截断重写第一行先读取一个过期快照再ftruncate截断重写。这会与 App 的并发追加竞争裁剪掉新产生的轮次→ BLOCKv2追加一条尾部session_meta修复了截断竞争但第一行仍保留openai/过期内容且缺少对尾部行 thread id 的校验无法保证追加的是本线程的元数据 → BLOCK。这两次否决直接塑造了最终方案的形态既不能截断、不能 rename也不能不校验线程身份。五、最终方案保留还原行为但让每一次写入都非破坏性所有改动集中在 src/codex/history-provider.ts核心原则是保持 revert 语义停止时仍把线程标签翻回openai但对 App 实时文件的一切写入都不得破坏数据。共四项改动5.1openStateDb()以 App 的连接参数打开 SQLite以PRAGMA busy_timeout 5000打开state_5.sqlite与 App 自身连接参数codex-rsstate::runtime::base_sqlite_optionsbusy_timeout 5s对齐——并发写入时等待 WAL 锁而非立即失败取代原先三处裸new Database(stateDbPath)打开src/codex/history-provider.ts。实现细节超时值保存在模块级变量historyDbBusyTimeoutMs默认 5000并提供setHistoryDbBusyTimeoutForTests/adoptHistoryDbBusyTimeout供测试与跨 realmWorker场景传递PRAGMA执行失败仅降级旧版 sqlite 无此指令不会阻断写入。5.2appendRolloutLine()O_APPEND 追加绝无 rename / truncate对 rollout 追加一条session_meta行时使用O_RDWR | O_APPEND句柄与 codex-rsappend_rollout_item_to_path的写法一致并显式说明三个理由见 src/codex/history-provider.ts 注释inode 不变App 的缓存追加句柄保持有效不会写入孤儿 inode无截断竞争不与 App 的并发追加互相裁剪last-writer-wins 兼容App 按顺序折叠所有session_meta追加的尾部行覆盖更早的行正好覆盖 SQLite 回放路径。同时不重置 mtimeApp 以 mtime 作为 rollout 的updated_at强制回拨会隐藏真实编辑、打乱列表排序且不携带O_CREAT——目标文件消失时不重建历史。追加后执行fsync尽力保证持久性。5.3readLatestSessionMeta() thread-id 守卫补丁基于最新一条session_meta镜像 App 的 last-writer-wins 折叠并校验其payload.id必须等于规范线程 id见 readLatestSessionMetaForId 与 updateSessionMeta分叉forked/branchedrollout 会把源线程的session_meta追加在自己之后App 会丢弃 payload id 与规范线程 id 不符的记录codex-rsapply_session_meta_from_item因此必须按 id 解析本线程的最新元数据否则会克隆出错误线程的元数据或跳过本可分叉线程的路由/还原。5.4patchFirstLineProviderInPlace()长度保持的原位改写针对首行读取 克隆路径在 provider 变更长度不变的前提下例如opencodex→openai两个词等长只重写第一行里的model_provider:...token并用 JSON 无关紧要的空白空格填充释放的字节保证该行字节长度完全一致src/codex/history-provider.ts、planFirstLineProvider。等长 ⇒ 定偏移写入无 truncate、无 inode 交换与 App 的缓存句柄安全共存填充的空格落在 token 槽内后续把openai精确还原回opencodex时可直接复用这些字节grow 无需移动数据首行通过逐块扩大探针读取直到换行符硬上限 16 MiBMAX_FIRST_LINE 1 24见 readFirstRolloutLine因此超大base_instructions不会静默禁用补丁写前/写后都做assertHistoryDescriptorIdentitydevino 校验任何并发 rename/替换都抛history_rollout_identity_changed拒绝继续。updateSessionMeta的返回值durableProvider用于判断首行是否已持久化为目标 providerrequireDurableProvider: true的严格还原路径manifest 还原在首行不可修补时回滚已追加的尾部行并保留 manifest保证可安全重试。5.5 opencodex 方向为什么保持只追加openai→opencodex属于长度增长的变更刻意保持追加式line 1 保持原始 provider 在该方向上无害且本次数据丢失 Bug 只发生在还原revert方向。在 src/codex/history-provider.ts 的注释中明确前向路由保持 best-effort严格 manifest 还原才要求持久化首行。六、修复的覆盖范围所有入口统一收敛文档确认所有原生还原入口都经由restoreNativeCodex/syncCodexHistoryProvider/restoreLegacyOpenaiHistory因此自动继承该修复src/cli/index.ts 的信号关闭路径SIGINT/SIGTERM/SIGHUP/exit上的syncCleanup含ocx stop/restore/recover-history子命令服务管理ocx stop、restore、recover-history管理 API 的/stop端点src/server/management/native-integration-routes.ts 等服务停止/卸载src/service/cli.ts注入方向opencodexsrc/codex/inject.ts行为不变仅继承了更安全的追加与 DB 打开。另外在同步关闭路径中src/cli/index.tsOCX_SERVICE 1或存在外部 Codex provider 时会跳过还原避免不必要的写入扰动。七、验证回归测试 隔离环境实测文档记录的验证结果bun x tsc --noEmit无类型错误bun test ./tests/890 项通过、0 失败新增回归测试位于 tests/codex-integration/codex-history-provider.test.ts文档写作时为tests/codex-history-provider.test.ts覆盖追加而非重写第一行保留 inode 与既有字节对应测试appends a new session_meta instead of rewriting line 1, preserving inode and prior content最新session_meta为外部线程 id 时跳过追加appends this threads own session_meta when the latest one belongs to a different thread idopencodex 源还原时原位等长改写第一行且后续的首行克隆不再复活opencodexrewrites line 1 in place (length-preserving)...第一行超过 64 KiB 读取块时仍能修补patches line 1 even when the first session_meta line is larger than the read chunk (big base_instructions)以及严格的并发竞争场景还原读回后被外部写者篡改、manifest 在 CAS 窗口被替换、分叉 rollout 尾随父线程session_meta等见同文件第 935–1136 行附近的竞争测试组。隔离CODEX_HOME中的活体复现inode_preservedtrueb/b存活DB 翻转为openai最新与首行session_meta均为openai且之后 App 的克隆追加仍解析为openai。八、工程启示与操作建议8.1 从本事故可以提炼的三条经验语义正确不等于实现安全把线程标签翻回openai是有意的但用 rename/truncate 实现就摧毁了另一方Codex App持有的缓存写句柄——多进程共享文件时inode 身份devino必须被视为共享协议的一部分双路径读取要求双路径修补只补 SQLite 回放路径而忽略首行克隆路径Bug 会以复活形式复发任何历史改写都要枚举下游所有读取者等长改写 JSON 空白填充是一种克制而优雅的技巧既达成数据面目标又不触碰文件身份是非破坏性补丁的典型范式。8.2 运维建议用服务模式避开还原扰动如果你从不打算在两次启动之间退回原生 Codex可以安装服务模式运行代理ocx service install后以OCX_SERVICE1运行src/cli/index.ts 会因此跳过关闭时的restoreNativeCodex好处完全跳过退出时的历史还原避免 DB/rollout 的写入抖动注意服务模式下线程保持opencodex标签无法直接用原生codex恢复这些会话这是有意的取舍。诊断时可用ocx status确认Service: not installed状态用ocx doctor检查历史/备份清单backup manifest 位于配置目录的codex-history-backup-id.json见 src/codex/history-provider.ts 的historyBackupPathFor。结语这次事故的完整闭环——从lsof/ps取证、到 codex-rs 双读取路径对照、再到两版失败方案的评审否决、最终以O_APPEND 追加 等长原位改写落地——展示了多进程共享会话存储时非破坏性写入的全部要义。相关实现可继续在 src/codex/history-provider.ts 与 src/codex/inject/restore.ts 中深入阅读回归测试集则在 tests/codex-integration/codex-history-provider.test.ts。【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址: https://gitcode.com/gh_mirrors/ope/opencodex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考