feat: harden enterprise control plane

docs/architecture/codex_server_progress_card_cn.md

@@ -1,10 +1,26 @@
 # Codex Server 协议与 Boss 执行进度卡接入记录
 
-更新时间：`2026-05-08`
+更新时间：`2026-05-16`
 
 ## 1. Codex 最新开放协议结论
 
-当前可作为 Boss 稳定集成入口的是 Codex CLI MCP server：
+2026-05-16 的最新架构判断：Boss 后续优先围绕 Codex App Server 做深度接入，但当前生产链路仍保留 `codex exec resume`，`codex mcp-server` 作为兼容 provider 候选。
+
+Codex App Server 是更适合 Boss 长期接入的协议层，因为它面向富客户端和产品级集成，覆盖：
+
+- authentication
+- conversation history
+- approvals
+- streamed agent events
+- Thread / Turn / Item
+- model/list、skills/list、plugin/list、app/list
+- command execution、file change、tool input、MCP tool-call approvals
+
+Boss 不能直接把 App Server 原始 Thread / Turn / Item 字段写进业务层。当前第一批已经新增 `local-agent/codex-app-server-runner.mjs`，把 App Server 的 `thread/resume | thread/start -> turn/start -> item/agentMessage/delta -> turn/completed` 映射成 Boss 的普通任务完成回写；下一批再继续把 Approval、Skill、file changes 和更细粒度 progress 归一化为 Boss 自有的 `execution_progress / approval_card / change_set / risk_event / skill_capability`。
+
+官方文档入口：`https://developers.openai.com/codex/app-server`
+
+当前仍可作为 Boss 兼容集成入口的是 Codex CLI MCP server：
 
 - 启动命令：`codex mcp-server`
 - Inspector 调试：`npx @modelcontextprotocol/inspector codex mcp-server`
@@ -16,10 +32,12 @@
 
 本机当前检测结果：
 
-- 本机 `codex --version`：`codex-cli 0.114.0`
-- npm 最新稳定包：`@openai/codex 0.129.0`
-- npm alpha：`0.130.0-alpha.5`
-- 本机 `0.114.0` 已支持 `codex mcp-server --help`，但落后于当前 `0.129.0` 的 app-server / protocol 拆分、ThreadStore、MCP turn metadata、plugin sharing 等新能力
+- 本机 `codex --version`：`codex-cli 0.131.0-alpha.9`
+- 本机 `codex app-server --help` 已可用；本机 help 当前显示 `--listen` 支持 `stdio://`、`unix://`、`unix://PATH` 和 `off`
+- 官方文档仍提到 WebSocket 传输，但标注 experimental / unsupported；Boss 当前只把 `stdio` 作为默认接入，后续如要接 WebSocket 必须先做协议快照和灰度开关
+- Boss 第一批只用 App Server 做任务级 provider，不直接复用 ChatGPT Mobile 到 Codex App 的官方 relay；官方移动控制链路仍属于 ChatGPT App 与 Codex App 同账号/工作区之间的产品能力，不是第三方 Boss 可以稳定依赖的私有通道
+
+下一轮再核对版本时，不要只看 npm 包版本号；必须同时读取 App Server schema / TypeScript 定义，并把 protocol snapshot 保存到 `docs/protocol-snapshots/codex-app-server/<version>/`。
 
 ## 2. Boss 当前采用的接入策略
 
@@ -76,8 +94,13 @@ APP 展示结构对齐截图：
 - Boss 消息账本新增 `execution_progress`
 - Android 原生聊天页新增结构化进度卡
 - local-agent 完成回写会补 Git diff、GitHub CLI 状态和产物名
+- `local-agent` 新增 `Codex App Server` runner，boss-agent 默认打开；`conversation_reply / dispatch_execution` 会先尝试 App Server，任务尚未真正启动 turn 时允许回退 CLI，turn 已启动后不再重复下发，避免双写同一线程
+- `local-agent` 新增 `Codex Computer Use -> CUA Driver` 桌面控制级 fallback：远程控制这台电脑时默认先通过 Codex Computer Use 执行，失败后再走 Boss 既有 CUA Driver runtime
+- `device-heartbeat` 设备能力新增 `codexAppServer`，用于前台和后台知道该设备是否具备 App Server provider
 
 后续建议按两步继续：
 
-1. 新增 `CodexMcpBackendAdapter`：让 `codex mcp-server` 成为 `ExecutionBackend` 的可选实现，先 feature flag 默认关闭，保留 `codex exec resume` 作为生产主链。
-2. 增加任务级 live progress API：`POST /api/v1/master-agent/tasks/[taskId]/progress`，让本地 agent 在执行中也能实时刷新进度卡，而不是只在 claim / complete 两个节点更新。
+1. 把当前 runner 提升为完整 `CodexAppServerBackendAdapter`：继续补 Approval / file change / skill / app / browser / computer-use 事件映射，但保持 feature flag 默认关闭。
+2. 新增 `CodexMcpBackendAdapter`：让 `codex mcp-server` 成为 `ExecutionBackend` 的兼容实现，用于 App Server 不可用或只需要轻量会话时。
+3. 增加任务级 live progress API：`POST /api/v1/master-agent/tasks/[taskId]/progress`，让本地 agent 在执行中也能实时刷新进度卡，而不是只在 claim / complete 两个节点更新。
+4. 建立协议快照目录和兼容测试：每次 Codex 协议升级时生成 schema、跑映射测试、灰度打开新 capability，避免把某个 Codex 版本写死到 APP 或后台。