Codex IO Bridge
Codex IO Bridge 为 VS Code 扩展提供一套共享的 Codex 会话接口：读取会话与本地历史、发送输入、接收事件，以及管理桥接状态。它是供其他扩展使用的本机基础层；安装后不会自动连接飞书，也不会自动发送消息。
Codex IO Bridge provides a shared Codex session API for VS Code extensions: read conversations and local history, send input, receive events, and manage bridge health. It is a local integration layer for other extensions. Installing it does not connect to Feishu or send messages automatically.
What it connects / 它连接什么
Bridge 在当前 VS Code 窗口中运行，通过经用户明确安装的桥接文件与官方 OpenAI Codex 扩展通信。Remote 等扩展调用公开 API；Bridge 复用官方 Codex 的连接，不创建自己的模型服务或飞书连接。
Bridge runs in the current VS Code window and communicates with the official OpenAI Codex extension through bridge files installed at the user's request. Extensions such as Remote call its public API. Bridge reuses Codex's connection; it does not run a separate model service or connect to Feishu.
Consumer extensions IO Bridge (local API v1) Official Codex
------------------- ------------------------ --------------
Codex Remote ---------+----------> Control panel + compatibility --------> Codex host
Codex Voice ----------+ Session API + request protection Renderer + app-server
Other consumers -------+ Events + JSONL history observer <----> Local CODEX_HOME
Patch install / update / restore Session state + JSONL
左侧是接入方，中间是 Bridge 的控制、健康检查、请求防重、事件及历史模块，右侧是官方 Codex 与本地会话数据。补丁只由 Bridge 管理，依赖扩展不应分别修改官方文件。
The left side shows consumers; the center shows Bridge's controls, health checks, replay protection, events, and history modules; the right side shows official Codex and local session data. Bridge alone manages the patch. Consumer extensions should not modify Codex files independently.
Message relay / 消息中转链路
使用 Codex Remote 接入飞书时，飞书机器人和群聊由 Remote 配置及维护。Remote 将群消息映射到 Codex 会话，经 Bridge 提交给官方 Codex；回复、状态和历史再经 Bridge 返回 Remote，由 Remote 负责转发到飞书。Voice 等其他接入方使用同一 Bridge API，但各自负责自己的输入输出体验。
When Codex Remote connects Feishu, Remote owns the bot configuration and chats. Remote maps a chat message to a Codex conversation and submits it through Bridge to official Codex. Replies, state, and history return through Bridge, while Remote delivers them to Feishu. Other consumers, including Voice, use the same Bridge API and own their respective user experiences.
Input / 输入
[Feishu chat] -> [Remote: bot + chat routing] -> [Bridge: API + replay guard]
-> [Official Codex: native turn] -> [Model]
Result / 回复
[Model] -> [Official Codex: events + local JSONL] -> [Bridge: event + history]
-> [Remote: deduplicate + deliver] -> [Feishu chat]
实时事件与本地 JSONL 历史共同支持状态更新和缺失消息补齐；sendMessage 的接受回执只表示 Codex 已接受输入，不表示模型已经回复。飞书网络、机器人权限和转发策略均不属于 Bridge 的配置。
Live events and local JSONL history support status updates and recovery of missed messages. An accepted sendMessage receipt means Codex accepted the input; it does not mean the model has replied. Feishu networking, bot permissions, and forwarding policy are configured outside Bridge.
Install and use / 安装与使用
本扩展需要 VS Code 1.96.2 或更新版本、受信任的本机桌面工作区，以及已经安装并登录的官方 openai.chatgpt Codex 扩展。Bridge 复用该扩展的 app-server 连接；自身不需要填写令牌或服务地址。Codex CLI 和 ChatGPT Desktop 采用独立的接入产品，不由本扩展适配。
This extension requires VS Code 1.96.2 or later, a trusted local desktop workspace, and the installed, signed-in official openai.chatgpt Codex extension. Bridge reuses that extension's app-server connection and requires no token or server address of its own. Codex CLI and ChatGPT Desktop use separate connectors.
安装官方 Codex 和 Codex IO Bridge，打开活动栏中的 Codex IO Bridge。
Install official Codex and Codex IO Bridge, then open Codex IO Bridge in the Activity Bar.
查看“代码兼容”“补丁文件”“当前窗口”三项状态。默认自动安装兼容的新目录；关闭自动安装或更新已有补丁时，点击 安装会话桥接。
Inspect code compatibility, patch files, and current-window status. Compatible clean installations are patched automatically by default; use 安装会话桥接 (Install session bridge) when automatic installation is disabled or an existing patch needs updating.
安装或更新补丁后，等正在运行的 Codex 任务结束再重载相关窗口。
After installing or updating the patch, wait for running Codex tasks to finish before reloading the relevant windows.
面板显示 会话桥接已就绪 后，再在 Remote 或适配版 Voice 中设置相应功能。
Once the panel shows 会话桥接已就绪 (Session bridge ready), configure Remote or a compatible Voice extension for its own features.
默认开启 自动为兼容的新版 Codex 安装桥接，可在本面板或全局设置 codexIo.automaticInstallation 中关闭。启动及官方扩展注册变化会触发检查，通过后为干净的新目录备份并安装；已明确恢复的目录、冲突和未完成事务保持原样。健康检查与刷新本身只读，自动安装不会重启扩展或中断任务。需要启用时，在任务结束后点击扩展页的“重启扩展”。已验证构建不是版本白名单；Remote SSH、Dev Container、浏览器版 VS Code 和自定义 Codex CLI 不在当前支持范围内。
Automatic installation for compatible clean Codex directories is enabled by default. Disable it in the panel or through codexIo.automaticInstallation. Startup and official-extension registration changes trigger verification and installation with backups; explicitly restored directories, conflicts, and incomplete transactions remain untouched. Health checks and refreshes stay read-only. Automatic installation never restarts extensions or interrupts tasks: use Restart Extensions once tasks finish when activation is pending. Verified builds are not a version allowlist. Remote SSH, Dev Containers, browser-based VS Code, and custom Codex CLI remain outside the supported scope.
Bridge 0.12.5（补丁 1.17.4）保留对 Codex 26.928.40906 的适配，并修复原生发送成功后旧队列快照使消息再次排队、重复执行的问题。已确认送达的输入按原生消息身份清理；内容相同但身份不同的消息、编辑后的输入和结果未知的输入继续保留。旧版已验证适配继续保留；后续版本仍按实际入口与依赖结构检查兼容性。
Bridge 0.12.5 (patch 1.17.4) retains support for Codex 26.928.40906 and fixes stale queue snapshots that could requeue and repeat an already accepted native input. Confirmed inputs are consumed by their native message identity; independent messages with identical text, edited inputs, and uncertain deliveries are preserved. Previously verified adapters remain available; future versions are still checked against their actual integration points and dependencies.
Bridge 0.12.6 补充异步问答工具记录的历史识别及实时变更通知，并与后到的原生问题记录按调用身份去重。接入方仍须通过 getPendingQuestions() 确认问题当前可回答，再调用 answerQuestion()；历史中存在问题记录本身不代表仍在等待回答。本次沿用运行时补丁 1.17.4。
Bridge 0.12.6 recognizes asynchronous question tool records in history and emits live updates, deduplicating later native question records by their call identity. Consumers must still confirm the current state with getPendingQuestions() before invoking answerQuestion(); a historical question alone does not prove that an answer is still pending. This release retains runtime patch 1.17.4.
Bridge 0.12.7（补丁 1.17.5）合并自定义 provider 的 Ultra 档位显示修复：模型声明支持且用户未关闭时可显示 Ultra；官方 provider 的原有功能开关、个人偏好和 Copilot 限制保持生效。同时保留 0.12.5 的原生队列去重及 0.12.6 的异步问答识别修复。升级后需要安装或更新会话桥接，再重新加载插件，以启用新的运行时补丁。
Bridge 0.12.7 (patch 1.17.5) includes the custom-provider Ultra visibility fix: Ultra is available when the model advertises support and the user has not excluded it. First-party feature gates, user preferences, and Copilot restrictions remain in effect. This release also retains the native queue deduplication from 0.12.5 and asynchronous question recognition from 0.12.6. After upgrading, install or update the session bridge and reload extensions to activate the new runtime patch.
Bridge 0.12.8（补丁 1.17.6）增加 Codex 26.930.21537 的宿主和会话界面适配，保留原生发送与排队去重、调整方向、问答表单以及自定义 provider Ultra 档位修复。升级后请安装或更新会话桥接，再通过 VS Code 的“重启扩展”启用。兼容性仍按实际代码入口和依赖结构验证，不依赖版本白名单。
Bridge 0.12.8 (patch 1.17.6) adds host and conversation UI adapters for Codex 26.930.21537 while retaining native input and queue deduplication, steering, question forms, and the custom-provider Ultra fix. After upgrading, install or update the session bridge, then use VS Code's Restart Extensions action. Compatibility continues to be verified against actual entry points and dependency structure rather than a version allowlist.
已验证的构建包括 26.908.40401、26.917.62051、26.928.31416、26.928.40906、26.930.21537、26.930.31428、26.930.31730 和 26.930.41038，各自的适配独立保留。上方的“最新版本”只表示最近完成验证的构建；其他版本仍可通过结构检查复用兼容适配。
Verified builds include 26.908.40401, 26.917.62051, 26.928.31416, 26.928.40906, 26.930.21537, 26.930.31428, 26.930.31730, and 26.930.41038, each retaining its own adapter. The latest version identifies the most recently verified build; other versions can still reuse an adapter when structural checks pass.
Bridge 0.12.27（补丁 1.17.17）加入完整模块语法树、词法作用域及导入/导出关系的自适应识别。已审查代码只有编译改名、格式或静态资源改名时，可以为未知版本生成补丁；安装记录保存绑定与摘要，重启、更新和恢复会核验原始备份。首次分析使用独立工作线程，结果按内容缓存，空闲线程释放。第一版家族基于 26.930.41038；模块结构或行为变化仍需精准适配，全部旧版适配保留。详见自适应说明。
Bridge 0.12.27 (patch 1.17.17) adds adaptation based on complete module ASTs, lexical scopes, and actual imports/exports. Reviewed code with compiler binding renames, formatting changes, or static asset renames can produce patches for unknown versions. Binding and digest evidence survives restart, updates, and restoration. Initial parsing runs in a worker; content-addressed results are cached and idle workers released. The first family is based on 26.930.41038. Changed module structures or behavior still require a precise adapter; all older adapters remain available. See the adaptive guide.
手动修复适配只保留两个主要按钮：复制修复提示词、安装 Codex 修复包。自动适配失败时，Bridge 在本地自动准备说明与源码快照，显示准备进度；用户复制提示词到新的 Codex 会话执行，在原生界面查看模型输出并处理授权。生成的修复包会自动检查，按钮未满足前置条件时不可点击，并明确说明原因；详细报告提供失败项与验证范围。修正后的包会自动重新检查，安装仍需确认，并在安装前核对实际源码。安装包自带 4 个适配层、15 个接口契约、完整 API 声明和独立校验器；备份和恢复沿用原来的完整性校验。具体操作和验证边界见手动修复说明。
Manual adaptation presents two main controls: Copy repair prompt and Install Codex repair package. When automatic adaptation fails, Bridge prepares local instructions and a source snapshot with visible file progress. Run the copied prompt in a new Codex conversation, where model output and approvals remain accessible. Generated output is checked automatically. Buttons remain disabled until their prerequisites are met and explain why; detailed reports expose failures and validation scope. Modified output is automatically rechecked, and installation still requires confirmation and a fresh live-source check. The extension ships four adapter layers, fifteen hook contracts, the full public API declaration and bundled validators. Installation and restoration retain backup and integrity checks. See the manual repair guide.
Bridge 0.12.26（补丁 1.17.16）增加 Codex 26.930.41038 的原生输入框、问答表单和消息总线绑定；保留旧版适配及原生队列去重、调整方向、审批和在线历史整理。
Bridge 0.12.26 (patch 1.17.16) adds native composer, question-form, and transport bindings for Codex 26.930.41038, retaining older adapters, queue deduplication, steering, approvals, and online history maintenance. Structural detection already handles unknown versions, changed hashes, and renamed assets; changed compiled bindings or interface contracts require additional validation. See the compatibility study for evidence and the proposed detection improvements.
Bridge 0.12.9 修复真实会话中的异步提问识别：将不带 ID 的原生问题展示记录与相邻工具记录合并，使用实际 Codex 回合身份匹配问答框；明确标记的最终回复等待回合完成确认，不再临时作为进度公开。运行时补丁沿用 1.17.6，各旧版适配保留。
Bridge 0.12.9 merges identity-less native question display records with their adjacent tool records and uses the actual Codex turn identity for pending forms. Explicit final replies wait for turn completion instead of temporarily appearing as progress. Runtime patch 1.17.6 and all existing version adapters are retained.
Bridge 0.12.10（补丁 1.17.7）新增 Codex 26.930.31428 的独立适配，更新输入框、消息总线、队列和问答表单的原生绑定。全部旧版适配继续保留；未知版本仍可在入口、依赖和实际加载资源的结构检查通过后复用适配。原生队列去重、调整方向和自定义 provider Ultra 档位修复继续生效。升级后安装或更新会话桥接，并在任务结束后通过 VS Code 的“重启扩展”启用。
Bridge 0.12.10 (patch 1.17.7) adds a separate adapter for Codex 26.930.31428 with updated native composer, transport, queue, and question-form bindings. All previous adapters remain available; unknown versions can still reuse an adapter when integration points, dependencies, and loaded resources pass structural checks. Native queue deduplication, steering, and custom-provider Ultra support are retained. After upgrading, install or update the session bridge and use VS Code's Restart Extensions action when running tasks finish.
Bridge 0.12.11（补丁 1.17.8）新增 Codex 26.930.31730 的独立适配，保留全部旧版适配及原生发送、队列去重、调整方向和问答链路。侧栏刷新改为只读检查：按钮保持可用，检查期间点击的操作在检查结束后按最新状态执行；重复刷新合并，安装和恢复等文件操作仍互斥。升级后需要安装或更新会话桥接，再在任务结束后重启扩展。
Bridge 0.12.11 (patch 1.17.8) adds a separate adapter for Codex 26.930.31730 and retains every previous adapter, native input, queue deduplication, steering, and question handling. Sidebar refresh is now a read-only check that keeps buttons usable; actions clicked during the check run against the updated state afterward. Repeated refreshes are coalesced, while installation and restoration remain mutually exclusive. Install or update the session bridge after upgrading, then restart extensions when running tasks finish.
Bridge 0.12.12（补丁 1.17.9）增加按需归档容量查询与原生永久删除接口，并优化包含大图片的 JSONL 读取，避免重复复制不断增长的记录。普通历史查找不再扫描归档目录，活跃分支明确引用的归档祖先仍按限定前缀读取。归档删除会验证原生状态、文件身份及分支依赖；旧版 Codex 缺少原生删除接口时明确提示不支持，已有适配继续保留。
Bridge 0.12.12 (patch 1.17.9) adds on-demand archive storage inspection and native permanent deletion. Large JSONL records are assembled without repeatedly copying their growing prefixes. Normal history discovery excludes archives; active branches retain access to explicitly referenced ancestor prefixes. Archive deletion verifies native state, file identity, and branch dependencies. Older Codex builds without native deletion report it as unsupported, while existing adapters remain available.
Bridge 0.12.13（补丁 1.17.10）增加归档删除预览、按确认清单批量删除及原生恢复。预览区分共享历史、派生子会话与普通 fork 来源，展示实际依赖及阻止原因；关联删除仅包含已归档依赖，按子会话先于父会话的顺序执行。恢复使用 thread/unarchive，不修改历史正文、不发送模型请求。
Bridge 0.12.13 (patch 1.17.10) adds archive deletion previews, confirmed batch execution, and native restoration. Previews distinguish shared history and spawned descendants from ordinary fork provenance, and report dependencies and blockers. Cascading deletion includes archived dependents only and processes children before parents. Restoration uses thread/unarchive, without rewriting history bodies or sending model requests.
Bridge 0.12.14（补丁 1.17.11）增加普通会话父级查询及受保护的永久删除预览/执行。普通列表删除明确保护所有具父级关联的会话（包括 fork 来源），不会级联；原有归档删除依然按真实共享历史及派生依赖判断。新操作仅在已验证安全下限 app-server 0.159.2 或更新版本开放；当前窗口已加载的会话拒绝执行，其他进程的占用由 Codex 原生归档期间持有的排它写锁保护。不会强行关闭或绕过占用拒绝。
Bridge 0.12.14 (patch 1.17.11) adds parent inspection and protected permanent-deletion previews/execution for ordinary conversations. This operation protects every parent-linked conversation, including fork provenance, and never cascades. Existing archive deletion still follows actual shared-history and spawn dependencies. The new operation requires the verified safety floor of app-server 0.159.2 or later. Threads loaded in the current host are rejected; foreign processes are protected by Codex's exclusive writer lock throughout native archival. Occupancy refusals are never forced or bypassed.
Complete capability list / 完整能力清单
下表覆盖当前公开的全部 29 个能力标识。接入方应读取 getHealth().capabilities，按能力启用功能，而不要从扩展版本号推断功能可用。
The table covers all 29 public capability identifiers. Consumers should inspect getHealth().capabilities and enable features by capability, instead of inferring availability from an extension version.
| 模块 / Module |
能力标识 / Capability IDs |
功能 / Function |
| 状态与可靠性 / Health and reliability |
health, request-replay-protection |
只读就绪状态、结构化错误、持久请求防重 / Read-only readiness, structured errors, durable replay protection |
| 会话管理 / Conversations |
thread-list, thread-summary, thread-create, thread-runtime, running-threads, thread-models, thread-name |
列表与按 ID 查询、创建、运行状态、按需列出运行中会话、模型与名称 / List and look up by ID, create, inspect runtime, list running conversations on demand, set model and name |
| 归档管理 / Archives |
archived-thread-delete, archived-thread-batch-delete, archived-thread-restore |
查看归档占用及依赖、按确认清单批量物理删除或恢复正常会话 / Inspect archive sizes and dependencies, execute confirmed batch deletion, or restore conversations |
| 普通会话删除 / Ordinary conversation deletion |
thread-delete |
父级关系及占用保护，确认后使用原生归档与删除，不级联 / Protect parent relationships and active ownership; native archive/delete after confirmation without cascading |
| 历史与资源 / History and files |
thread-history, history-images, history-files |
本地可见历史、图片及受限文件读取 / Local visible history, images, and scoped file reads |
| 输入与控制 / Input and controls |
background-input, input-images, native-queue, turn-steering, interrupt |
后台输入、图片、VS Code 原生排队、调整方向、中断 / Background input, images, native VS Code queue, steering, interrupt |
| 用户交互 / User interaction |
interactions, async-question-replies, pending-questions |
审批、异步问题回答及待答状态 / Approvals, asynchronous answers, live pending-question state |
| 事件与观察 / Events and observation |
thread-events, owned-thread-observation |
多播事件、可释放的独立会话观察 / Multicast events and independently disposable observations |
| 输入框与语音适配 / Composer and voice integration |
draft-input, continuous-input, recording-controls |
草稿插入、提交与录音控件协议 / Draft insertion, submission, and recording-control protocol |
Public API / 公开接口
公开 API 为 v1，完整类型见随扩展提供的 api/index.d.ts。每个 VS Code 扩展宿主有自己的 API 实例；backendId + threadId 标识后端会话，hostEpoch 等运行时身份在窗口重载后应重新取得。
The public API is v1; see the bundled api/index.d.ts for complete types. Each VS Code extension host has its own API instance. backendId + threadId identifies a backend conversation, while runtime identities such as hostEpoch must be reacquired after a window reload.
| API |
用途 / Purpose |
getHealth, getStatus |
读取桥接就绪、兼容及运行状态；getStatus 为兼容接口 / Read readiness, compatibility, and runtime; getStatus is retained for compatibility |
listThreads, getThreadSummary |
分页列出会话、按 ID 读取会话及分支摘要；可显式请求历史容量 / Page through conversations or read a summary; optionally request storage metadata |
inspectThreadMetadata |
按需批量读取工作目录、更新时间及历史文件容量 / Read directories, update times, and history storage sizes in an on-demand batch |
listArchivedThreads, deleteArchivedThread |
按需查看归档容量、经确认后使用 Codex 原生接口物理删除 / Inspect archived storage on demand and permanently delete through Codex after confirmation |
prepareArchivedThreadDeletion, deleteArchivedThreads, restoreArchivedThread |
预览批量及关联删除清单、确认后执行、恢复归档 / Preview batch and dependency deletion, execute after confirmation, and restore archives |
inspectThreadRelations, prepareThreadDeletion, deleteThreads |
普通会话父级查询、单条或批量永久删除预览及执行 / Inspect parents and preview/execute single or batch permanent deletion of ordinary conversations |
getThreadRuntime |
读取当前窗口的加载、忙碌和活动回合状态 / Read this window's loaded, busy, and active-turn state |
listRunningThreads |
按需读取当前窗口全部运行中、等待授权或等待回答的会话，包括未被 Remote 管理的会话 / Inspect all running conversations and pending approvals or answers in this window on demand, including conversations not managed by Remote |
listModels, setThreadModel |
查看可用模型与推理强度、设置后续回合模型 / List available models and reasoning efforts; set a model for later turns |
renameThread |
经 Codex 原生接口修改会话名称 / Rename a conversation through Codex's native interface |
createThread, openThread |
创建会话、在官方侧栏打开会话 / Create a conversation or open it in the official sidebar |
subscribeThread, observeThread |
观察事件及 JSONL 补偿；后者返回可释放句柄 / Observe events and JSONL recovery; the latter returns a disposable handle |
getHistory |
读取可见用户与助手消息、时间及来源 / Read visible user and assistant messages, timestamps, and sources |
readHistoryImage, readHistoryFile |
按历史中的资源 ID 读取图片或可见本地文件 / Read an image or visible local file by its history resource ID |
sendMessage, queueMessage, steerMessage |
立即提交、显式加入 Codex 可见的原生队列、向指定活动回合调整方向 / Submit immediately, queue in Codex’s visible native queue, or steer an identified active turn |
getPendingQuestions, answerQuestion |
只读原生待答状态、回答仍有效的结构化问题 / Read live pending state and answer a still-valid structured question |
interrupt, respond |
中断指定回合、响应仍有效的审批或阻塞式问题 / Interrupt a turn or respond to a live approval or blocking question |
getTargets, composer |
获取可见输入框、插入或提交草稿并同步录音 UI 状态 / Get visible composers, edit or submit drafts, and sync recording UI state |
onEvent |
订阅可多播的原生通知、完成事件与就绪变化 / Subscribe to multicast native notifications, completion events, and readiness changes |
接入扩展通过 VS Code 的 extensions.getExtension('koupualen.codex-io-bridge').activate() 获取 API，并在调用前检查 apiVersion === 1、getHealth().ready 及所需能力。推荐在自己的 package.json 中声明 extensionDependencies: ["koupualen.codex-io-bridge"] 和 extensionKind: ["ui"]。示例的 ./types/codex-io-bridge 是接入方复制 api/index.d.ts 后的本地路径，仅供类型检查；不要通过 Node require() 启动第二份 Bridge。
A consumer obtains the API through VS Code's extensions.getExtension('koupualen.codex-io-bridge').activate(), then checks apiVersion === 1, getHealth().ready, and required capabilities. Declare extensionDependencies: ["koupualen.codex-io-bridge"] and extensionKind: ["ui"] in the consumer's package.json. The example's ./types/codex-io-bridge is a consumer-owned copy of api/index.d.ts for type checking only; do not use Node require() to create a second Bridge instance.
可选接口 listRunningThreads() 依赖 running-threads 能力，只在用户打开或刷新运行列表时调用。它分页读取当前窗口原生后端的已加载清单，再以最多 4 个并发读取会话元数据；原生检查最多 8 秒、1000 个会话，不恢复会话、不扫描历史正文，也不为查询新增轮询。返回 RunningThreadSnapshot：data 是已确认运行的会话，附带 windowId、backendId、hostEpoch、capturedAt、inspected、complete 和 failures。名称可由缓存的侧栏名称索引补齐。单个 API 实例只覆盖自己的 VS Code 窗口，调用方须分别向各窗口查询，并按 backendId + threadId 合并去重；即使窗口共享同一个 backendId，也不能因此只查询其中一个窗口。
The optional listRunningThreads() method requires running-threads. Invoke it when the user opens or refreshes the running list. It pages through the current window's native loaded-thread inventory and reads metadata with at most four concurrent requests. Native inspection is bounded to eight seconds and 1,000 conversations; it does not resume threads, scan history bodies, or add background polling. Its RunningThreadSnapshot contains confirmed running conversations in data, plus windowId, backendId, hostEpoch, capturedAt, inspected, complete, and failures. Names may be supplemented from the cached sidebar name index. Each API instance covers only its own VS Code window: consumers must query every window, then deduplicate by backendId + threadId. A shared backendId is not a reason to skip another window.
state 区分 running、waiting-approval、waiting-input；activeFlags 保留原生等待标记。waitingOnApproval 与 waitingOnUserInput 可以同时存在，此时 state 为 waiting-approval，界面仍应展示两个等待标记。本次原生状态优先于旧的回合或问题缓存：缺失状态不会猜成运行，明确运行但缺少等待标记时会说明无法核实等待详情。读取失败、状态缺失或检查达到上限时，complete 为 false，应保留已查到的结果并展示 failures；空 data 的不完整结果不能解释成“全部空闲”，更不能据此自动重载窗口。连接身份在查询期间变化时接口拒绝该次结果，请重新查询。旧桥接缺少这个可选能力只影响运行列表，不影响既有会话功能。
state distinguishes running, waiting-approval, and waiting-input; activeFlags preserves native waiting indicators. waitingOnApproval and waitingOnUserInput can coexist: state then selects waiting-approval, while the UI should still display both indicators. Current native state takes precedence over old turn or question caches. Missing state is not guessed as running; confirmed activity without waiting flags is reported with an explanation that waiting details could not be verified. Read failures, missing state, or inspection limits set complete to false: retain confirmed entries and show failures. An incomplete empty data array does not mean every conversation is idle and must never justify an automatic window reload. A connection identity change during inspection rejects the result; query again. Older bridges lacking this optional capability lose only the running-list feature, not their existing conversation features.
从 0.12.19 起，运行快照增加可选 hierarchyVersion: 1。每条活动记录的 sourceKind 区分 conversation、subagent 与 unknown；已确认的自动子代理附带 subagent.parentThreadId，祖先链完整时提供 subagent.rootThread 元数据与 ancestryComplete: true。查询按需补读必要祖先的元数据，复用本次已读结果，并共享总读取数、并发和时间预算。只有原生来源及明确父关系可证明子代理归属；forkedFromId、相同目录及缺少名称均不是证据。
From 0.12.19, running snapshots include optional hierarchyVersion: 1. Active rows expose sourceKind as conversation, subagent, or unknown. Confirmed automatic agents provide subagent.parentThreadId; fully resolved ancestry adds subagent.rootThread metadata and ancestryComplete: true. Necessary ancestor metadata is read on demand, cached within the inspection, and shares its total read, concurrency, and time budgets. Only native origins and explicit parent relationships establish ancestry; forkedFromId, shared directories, and missing names do not.
data 仍保留每个真实活动子代理，根会话元数据不代表根会话本身正在运行。展示端可先按后端与活动线程 ID 去重，再将子代理归到根会话；仅有子代理活动时也应保留该会话，并明确说明活动来自子代理。关系未知、读取失败或环形父链均保留原活动记录并报告不完整，不能因折叠而丢失运行证据。旧版未提供关系信息时，接入方应说明无法核实归属。
data retains every genuinely active subagent; root metadata alone does not mean the root is active. Consumers can deduplicate by backend and active thread ID, then group agents under their root. Keep the conversation visible when only its agents are active and label that distinction. Unknown ancestry, read failures, and cycles preserve original activity with an incomplete result, so grouping cannot erase evidence of work. Explain unverified ancestry when using older snapshots without relationship information.
从 0.12.15 起，普通会话列表可显式传入 listThreads({includeStorage:true}) 或 getThreadSummary({...ref,includeStorage:true}) 读取 sizeBytes、fileCount。不传时保持原来的轻量查询。可选方法 inspectThreadMetadata({threadIds,refresh?}) 一次查询最多 100 条会话，返回 {data: ThreadSummary[]}；接入前检查方法是否存在。元数据请求限制并发、合并进行中的同 ID 查询并短暂缓存；refresh:true 请求更新摘要。文件信息只统计该会话自身的 sessions 历史分片和压缩副本，不包含继承父文件、工作区附件或归档目录，不读取消息或图片正文、不恢复会话。失败项返回 storageError，容量未知时不得用零替代。请只在显示列表或用户刷新时调用，不放入周期性的发现或同步任务。
From 0.12.15, explicitly request listThreads({includeStorage:true}) or getThreadSummary({...ref,includeStorage:true}) to obtain sizeBytes and fileCount; omitting the flag preserves the lightweight query. The optional inspectThreadMetadata({threadIds,refresh?}) method reads up to 100 conversations and returns {data: ThreadSummary[]}; check for its presence before calling. Metadata requests have bounded concurrency, coalesce in-flight requests for the same ID, and use a short cache; refresh:true refreshes summaries. Storage covers only the conversation's own history partitions and compressed copies under sessions, excluding inherited parent files, workspace attachments, and archives. It does not read message/image bodies or resume conversations. Failed entries carry storageError; never display unknown sizes as zero. Invoke these reads only for visible lists or explicit refreshes, not recurring discovery or synchronization.
归档管理接口从 0.12.12 起可选提供。listArchivedThreads({cursor?, limit?}) 只在用户打开归档管理时调用，容量使用本机会话 JSONL 文件的 stat 元数据，包含会话自身分片，不包括继承的父会话或外部附件；不会为了显示容量解析图片正文。将 nextCursor 原样传回同一窗口的 API。删除前展示名称、容量与不可恢复提示，取得确认后调用 deleteArchivedThread({threadId, deleteToken, requestId})；deleteToken 来自当前列表、15 分钟有效，不可跨窗口使用。删除依赖 archived-thread-delete 能力和官方原生 thread/delete；旧 Codex 不支持时明确拒绝，不直接改数据库或强删。目标身份、文件大小或时间有变动，以及仍有其他会话引用归档时，均拒绝删除。RESULT_UNKNOWN 时先刷新列表核对，绝不自动重复删除。
Archive management is optional from 0.12.12. Call listArchivedThreads({cursor?, limit?}) only when the user opens archive management. Sizes come from local JSONL stat metadata, including the thread's own partitions but excluding inherited parent histories and external attachments; image bodies are not parsed for sizing. Return nextCursor unchanged to the same window's API. Show the exact conversation, size, and irreversible effect before obtaining confirmation, then call deleteArchivedThread({threadId, deleteToken, requestId}). The list's deleteToken lasts 15 minutes and cannot move between windows. Deletion requires archived-thread-delete and native thread/delete; unsupported Codex versions are rejected without direct database edits or forced file removal. Changed targets and archives referenced by another conversation are protected. On RESULT_UNKNOWN, refresh and reconcile before taking further action; never automatically retry deletion.
原生删除会递归处理派生子会话，因此 Bridge 同时检查本地父级元数据及原生状态库中的派生关系，有子会话时拒绝删除。.jsonl.zst 压缩副本计入容量，但目前不解压检查依赖：压缩目标不会返回 deleteToken；删除其他归档时若发现压缩会话，也会以明确错误停止，避免遗漏依赖后误删。
Native deletion recursively removes spawned children, so Bridge checks both local parent metadata and native state-database ancestry, rejecting parents with descendants. Compressed .jsonl.zst copies count toward storage but are not yet decompressed for dependency checks: compressed targets receive no deleteToken, and deletion of another archive stops with an explicit error if compressed sessions prevent a complete dependency check.
批量接入从 prepareArchivedThreadDeletion({threadIds, includeDependents}) 开始。这是只读预览，返回 members、dependencies、blockedReasons、容量及 canDelete；includeDependents 默认关闭，开启时只允许纳入已归档依赖。将完整清单及不可恢复提示交给用户确认后，原样提交 deleteArchivedThreads({planToken, requestId})。计划只属于当前 API 实例和原生后端，15 分钟后过期；成员状态、文件或依赖变化时必须重新预览。逐项 results 的 deleted/failed/unknown/skipped 是实际结果，批次不能视作原子事务；partial 或 unknown 后先核对，不自动重试整个批次。
Start batch integration with the read-only prepareArchivedThreadDeletion({threadIds, includeDependents}). It returns members, dependencies, blockedReasons, storage totals, and canDelete. Dependency inclusion defaults to off and only admits archived dependents. Show the entire scope and irreversible effect, obtain confirmation, then pass the unchanged token to deleteArchivedThreads({planToken, requestId}). Plans belong to one API instance and native backend, expire after 15 minutes, and require a new preview if members, files, or dependencies change. Per-item deleted/failed/unknown/skipped results are authoritative; batches are not atomic transactions. Reconcile partial or unknown outcomes instead of automatically retrying the batch.
恢复使用列表中独立的 restoreToken：restoreArchivedThread({threadId, backendId?, restoreToken, requestId})。它不依赖 deleteToken，因此不能安全删除的压缩归档仍可尝试原生恢复。恢复只处理指定会话，不自动恢复或加载其子会话。接入方如有“自动同步新会话”功能，应在恢复前持久化排除该会话，避免将恢复事件或重新出现的旧记录误判为新建会话。
Restore with the list's separate restoreToken: restoreArchivedThread({threadId, backendId?, restoreToken, requestId}). It does not require a deleteToken, so compressed archives that cannot be safely deleted can still use native restoration. Restoration affects only the selected conversation and does not load or restore its descendants. Consumers that automatically synchronize newly created sessions should persist an exclusion before restoration, so a restore event or reappearing historical record cannot be mistaken for a new conversation.
普通列表删除使用 inspectThreadRelations({threadIds}) 批量读取当前页父级信息，再以 prepareThreadDeletion({threadIds}) 取得不可篡改的确认计划。展示 members 的父级与阻止原因、实际可删除项及容量，用户确认后调用 deleteThreads({planToken, requestId})。有父级的条目即使随父会话一起选择也会跳过；真正存在依赖的父会话也不会隐式级联。确认计划 15 分钟有效，属于原 API 实例与后端。按项处理结果：deleted 已物理删除，archived 仅完成归档，failed 未完成，unknown 需人工核对，skipped 未执行。不要把整个批次的失败当成“完全没发生”，也不要在未知结果后自动重放。
For ordinary lists, batch-read parent metadata with inspectThreadRelations({threadIds}), then obtain an immutable confirmation plan with prepareThreadDeletion({threadIds}). Show parent links, blockers, the eligible subset, and storage totals before calling deleteThreads({planToken, requestId}) after confirmation. Parent-linked entries remain protected even when selected alongside their parents; dependency-bearing parents never cascade implicitly. Plans last 15 minutes and belong to the original API instance and backend. Handle each result: deleted is permanent deletion, archived is archival only, failed is incomplete, unknown requires reconciliation, and skipped was not executed. A failed batch is not proof that nothing happened; never automatically replay uncertain outcomes.
import * as vscode from 'vscode';
import type { CodexIoBridgeApi } from './types/codex-io-bridge';
export async function sendToCodex(threadId: string, text: string, requestId: string) {
const extension = vscode.extensions.getExtension<CodexIoBridgeApi>('koupualen.codex-io-bridge');
if (!extension) throw new Error('Codex IO Bridge is not installed');
const io = await extension.activate();
if (io.apiVersion !== 1) throw new Error('Incompatible Bridge API');
const health = await io.getHealth();
if (!health.ready || !health.capabilities.includes('background-input')) {
throw new Error(health.error?.message || 'Codex IO Bridge is not ready');
}
// Generate and retain requestId for the user action before calling this function.
const receipt = await io.sendMessage({ threadId, backendId: health.backendId, text, requestId });
// receipt.state === 'accepted' does not mean the turn has completed.
return receipt;
}
readHistoryImage 从 0.12.16 起接受可选 maxBytes。省略时仍按原先的 10 MiB 上限读取；需要在本机压缩原图的接入方，可以显式请求不超过 40 * 1024 * 1024 的正整数上限。返回的 byteLength、sha256 仍描述未压缩原图，Bridge 不改变图片内容。超过请求上限返回 IMAGE_TOO_LARGE，非法参数返回 INVALID_REQUEST。此选项只扩大可见历史图片的有界读取，不放宽输入图片限制，也不允许任意路径读取。
From 0.12.16, readHistoryImage accepts optional maxBytes. Omitting it preserves the 10 MiB read limit. Consumers that locally compress originals may explicitly request a positive integer limit of up to 40 * 1024 * 1024. Returned byteLength and sha256 still describe the original bytes; Bridge does not transform images. Exceeding the requested limit returns IMAGE_TOO_LARGE; invalid limits return INVALID_REQUEST. This is a bounded read of images already visible in the conversation, with no change to input-image limits or arbitrary-path access.
写入操作须使用稳定的 requestId。RESULT_UNKNOWN 表示操作可能已经执行，应先在原 Codex 会话核对，不能换 ID 自动重发；THREAD_BUSY 等明确未投递错误才可依原请求规则重试。原生排队返回 queued 只表示入队，图片文件应保留到 Codex 实际消费。
Mutations need a stable requestId. RESULT_UNKNOWN means the operation may already have happened: inspect the original Codex conversation before retrying, and do not automatically submit under a new ID. Explicit non-delivery errors such as THREAD_BUSY can be retried according to the request contract. A native queued receipt means enqueued, not executed; retain local image files until Codex consumes them.
respond 复用原请求的 requestId、hostEpoch 及所属窗口，可转交 MCP 工具审批的原生 action、content、_meta.persist 响应。消费者必须按本次请求允许的范围展示选择，不能自行补充长期授权。成功仅表示响应已交给 Codex 连接，不代表工具已执行；发送期间同步断连、重启或桥接销毁会返回 RESULT_UNKNOWN，不得自动重试。已解决请求或旧宿主请求会明确拒绝。
respond uses the original requestId, hostEpoch, and owning window to forward native MCP approval responses containing action, content, and _meta.persist. Consumers must offer only scopes permitted by that request and never add persistent authorization themselves. Success means the response was handed to the Codex connection, not that the tool executed. A synchronous disconnect, restart, or bridge disposal during sending returns RESULT_UNKNOWN and must not trigger an automatic retry. Resolved requests and requests from earlier hosts are rejected.
Data and safety / 数据与安全
Bridge 在本机读取 Codex 可见会话历史，并可按该会话历史中的 ID 读取图片或普通本地文件；它不提供任意路径读取接口。补丁原文件备份默认位于 ~/.codex-io-bridge/backups/，请求防重记录位于 ~/.codex-io-bridge/request-receipts/，防重记录不保存提示词正文。诊断可能包含本机路径，分享前请自行检查。
Bridge reads locally visible Codex history and can read images or ordinary local files by IDs found in that conversation's history; it does not expose arbitrary-path reads. Original-file backups default to ~/.codex-io-bridge/backups/, and replay-protection records to ~/.codex-io-bridge/request-receipts/; the latter do not store prompt bodies. Diagnostics may contain local paths, so review them before sharing.
维护与诊断 提供查看日志、检查待核对的队列消息，以及二次确认后的 恢复官方 Codex 文件。恢复仅处理 Bridge 能验证归属及哈希的文件；若发现文件冲突会停止覆盖。恢复后需重载相关窗口，依赖 Bridge 的扩展会暂时无法收发，历史不会被删除。
维护与诊断 (Maintenance and diagnostics) offers logs, queue messages requiring review, and 恢复官方 Codex 文件 (Restore official Codex files) behind a confirmation step. Restore only touches files whose ownership and hashes Bridge can verify, and stops on conflicts. Reload affected windows afterward; dependent extensions cannot send or receive until the bridge is reinstalled, but conversation history is retained.
旧版 Voice 若自行管理同一份官方补丁，需先在旧 Voice 中恢复其补丁、停用旧版并重载，再由 IO Bridge 安装共享补丁。legacy-conflict、unsupported、conflict、partial 等状态会在面板中说明下一步；这些状态下接入方应暂停新输入并保留用户内容。
If an older Voice extension manages its own patch of the same official files, restore that patch from the older Voice extension, disable it, and reload before installing the shared IO Bridge patch. The panel explains next steps for legacy-conflict, unsupported, conflict, and partial states. Consumers should pause new input and preserve user content in those states.
Support scope / 支持范围
公开 API 保持 v1。官方 Codex 版本变化后是否可用由代码兼容检查决定；关键结构不匹配时，Bridge 会停止安装并展示失败项。Bridge 是本机 VS Code 扩展间接口，不是独立 HTTP 服务或飞书机器人。
The public API remains v1. After an official Codex update, code compatibility checks determine whether the bridge can be used. Bridge refuses installation and reports failed checks when required structures no longer match. It is a local interface among VS Code extensions, not a standalone HTTP service or Feishu bot.
需要排查时，先打开桥接控制面板查看代码兼容、补丁文件和当前窗口，再使用 维护与诊断 → 查看诊断 / 查看日志。接入扩展的飞书连接、群聊路由和语音设置应在各自扩展中排查。
For troubleshooting, start with code compatibility, patch files, and current-window state in the Bridge control panel, then use Maintenance and diagnostics → Diagnostics / Logs. Investigate Feishu connections, chat routing, and voice settings in the respective consumer extensions.
Installation packages / 安装包
仓库中的各版本 VSIX 安装包统一保存在 release/，由 Git 管理。开发者执行 npm run package 时，脚本先通过 VSCE 的发布前步骤编译，再根据 package.json 中的名称与版本生成 release/codex-io-bridge-<version>.vsix。同版本安装包已存在时会拒绝覆盖，请升级版本号后再打包。release/ 不会被嵌套进安装包。
All versioned VSIX installation packages are kept in release/ and tracked in Git. npm run package compiles through VSCE's prepublish step and writes release/codex-io-bridge-<version>.vsix using the name and version in package.json. Packaging refuses to overwrite an existing version; increase the version before packaging again. The release/ directory is excluded from the VSIX contents.
历史图片整理 / History image maintenance
Remote 可通过 Bridge 为已管理会话预览内嵌图片的压缩或移除。此能力当前支持 macOS，沿父级历史查找文件，并维护共享分支的位置引用。“一键减脂”保护各处理会话最新一轮的图片，只压缩更早的内嵌图片；“极致瘦身”移除选中会话及计划所列祖先历史中的全部内嵌图片，包括最新一轮。仅更新引用的范围外分支保留自己的图片。压缩设置按 Base64 体积计算，默认 4～64 KiB，不以画面清晰度作为保留大图的理由。
Remote can use Bridge to preview compression or removal of embedded images in managed conversations on macOS. Compression preserves each processed conversation’s latest-round images and shrinks earlier ones. Extreme removal deletes all embedded images in the selected conversation and listed ancestor scope, including the latest round. Shared branches needing reference updates only retain their own images. The default Base64-size budget is 4–64 KiB. Low visual quality does not cause oversized images to be retained.
分页历史分别核验当前会话 ID、根会话 ID 和物理分片 ID。子会话的根会话 ID 可以不同于自身 ID；缺省根会话 ID 时遵循原生格式回退到当前 ID。显式继承引用按物理分片及完整记录边界解析，不用根会话 ID 拼接历史，也不把父会话的运行中任务当作子会话任务。
Paginated history validates the current conversation, root session, and physical rollout as separate identities. A child can have a different root session; an omitted root session follows the native fallback to its current ID. Explicit inherited references use physical rollouts and complete record boundaries. The root session does not concatenate histories or transfer a parent's active task to its child.
新计划默认在线执行：预览副本、用户确认范围、为所列会话建立持久化保护、卸载原生会话并取得独占锁、协调提交历史文件与缓存，最后核对同步记录并解除保护。通常原生卸载可能需要约 1 分钟，大文件另需处理时间，不要求退出全部 Codex 窗口。只有所列目标、父级来源和共享关联范围暂停，其他会话继续使用。运行中、待回答、待授权和原生队列中的消息须先正常结束或处理；整理不会中断、删除或重新投递这些内容。实际 Codex 程序和缓存格式须通过隔离能力检查；不能验证时拒绝修改。成功完成后不永久保留原始图片备份。
New plans run online: stage copies, confirm the exact scope, establish durable conversation protection, unload native state and obtain writer locks, commit history and cache updates together, then reconcile synchronization before releasing protection. Native unloading may take about a minute, with extra processing time for large files, without requiring all Codex windows to exit. Only the listed target, ancestors, and shared dependencies pause; unrelated conversations remain usable. Running tasks, pending answers or approvals, and native queued messages must finish normally first. Maintenance does not interrupt, delete, or resubmit them. The executable and cache schema must pass isolated capability checks; unverifiable formats are refused. Completed operations do not retain permanent original-image backups.
同一数据目录中未接入保护的 CLI、Desktop 或未知原生进程会阻止在线整理；错误会标明需要关闭的 PID。其他数据目录不受影响。旧 Bridge 若没有 history-image-online-maintenance 能力需先升级；不会静默绕过独占校验。旧计划的 executionMode 缺失或为 offline 时，继续按原方式等待所有 Codex 正常退出；等待中的旧任务可取消并重新预览。旧极致瘦身计划也保留当时的最新轮次保护规则，不会在升级时暗中扩大范围。
Unguarded CLI, Desktop, or unknown native processes using the same data directory block online maintenance; the error identifies the PID to close. Other data directories are unaffected. Older Bridge hosts without history-image-online-maintenance must be updated; ownership checks are never silently bypassed. Legacy plans with absent or offline executionMode retain their original requirement that all Codex processes exit. Cancel a waiting legacy job and prepare a new plan to use online mode. Legacy removal plans also retain their captured latest-round policy rather than expanding their scope during upgrades.
维护中断后，如果 Codex 已重新连接或重启，优先在 Remote → 会话管理 → 历史图片整理任务 → 恢复到处理前 操作，让 Remote 重新核对当前所有窗口的会话保护。如果 Codex 因本次存储保护暂时无法启动，在 VS Code 命令面板运行 Codex IO: 恢复中断的历史图片整理，选择对应任务并确认恢复到处理前。这个本地入口不要求 Codex 已连接或飞书网络可用；发现仍在运行的连接不属于原保护范围时会停止恢复，不会绕过检查。不要手动删除存储保护标记；只能在备份及恢复校验通过后移除。
If Codex has reconnected or restarted since the interruption, prefer Remote → 会话管理 → 历史图片整理任务 → 恢复到处理前 so Remote can recheck protection in every current window. If the storage guard prevents Codex from starting, run Codex IO: 恢复中断的历史图片整理 from the command palette, select the job, and confirm rollback. This local entry requires neither a ready Codex connection nor Feishu network access. It stops when a running connection does not belong to the original protected scope instead of bypassing ownership checks. Do not remove storage guards manually; they are released only after validated completion or rollback.
接口约定 / API contract
| Optional API |
用途 / Purpose |
prepareThreadImageMaintenance |
检查当前会话及父级，冻结压缩设置，生成有时效的副本预览。Prepare an expiring staged plan with captured settings. |
scheduleThreadImageMaintenance |
确认计划后传入唯一 requestId；在线计划还需传入完整 onlineLease，重复调用同一 ID 不重复执行。Schedule a confirmed plan with a stable idempotency key and verified lease for online execution. |
getThreadImageMaintenanceJob |
读取状态与完整位置映射，仅用于同步状态恢复。Read a job and its full reconciliation receipt. |
listThreadImageMaintenanceJobs |
读取轻量摘要，不向界面发送历史逐记录映射。List lightweight summaries. |
cancelThreadImageMaintenance |
取消等待独占权或旧离线等待退出的任务。Cancel a job waiting for ownership or legacy offline exit. |
recoverThreadImageMaintenance |
为中断任务请求恢复到处理前；宿主重启后可传重新核验的 onlineLease，原生被存储保护阻止启动时可用原记录校验本地恢复。Request rollback; pass a reverified lease after host changes, or use the stored proof for local recovery when the native process cannot start. |
在线所有权接口按顺序调用，并保留同一个任务 ID、窗口身份及冻结范围：createHistoryMaintenanceScope 创建保护范围，installHistoryMaintenanceGuard 在每个相关窗口安装输入保护，quiesceHistoryMaintenance 校验任务与原生队列后卸载会话。getHistoryMaintenanceScope 和 inspectHistoryMaintenanceGuard 用于只读核对丢失的回执；不能把未知结果当作未执行而重投。完成并迁移同步游标后，先逐窗口 finishHistoryMaintenanceGuard 清理旧缓存，再 releaseHistoryMaintenanceScope 解除范围保护。
The online ownership APIs share the same job ID, frozen scope, and window identities: create the scope with createHistoryMaintenanceScope, install guards in every participating window with installHistoryMaintenanceGuard, then validate work and the native queue and unload through quiesceHistoryMaintenance. getHistoryMaintenanceScope and inspectHistoryMaintenanceGuard provide read-only evidence for lost acknowledgements; unknown outcomes never authorize blind replay. After completion and cursor reconciliation, clear stale caches through each window’s finishHistoryMaintenanceGuard, then release the scope with releaseHistoryMaintenanceScope.
接入方必须先展示确切范围并取得用户确认，协调所有受影响会话的输入、发送与历史同步，持久保存暂停状态，再安排任务。收到完成回执后，更新所有使用旧位置引用的同步状态，成功后才解除暂停。不要仅按图片文字内容去重，不要修改已经接受的消息投递 ID。状态、取消和恢复接口只访问本机维护记录，不依赖原生健康检查。
Consumers must present the exact scope for confirmation, quiesce affected inputs and deliveries, and durably pause synchronization before scheduling. Rebase every stored reference using the completed receipt before resuming. Do not deduplicate by visible image text or change accepted delivery IDs. Status, cancellation, and recovery access local maintenance records without native-health requirements.
