合并主分支

解决合并冲突

docs/project-memory/shared-memory/pitfalls.md

@@ -135,6 +135,23 @@
 - 验证：用 deferred graph Promise 断言终态前 Tauri layout read/update 调用均为 0；图就绪后首次坐标直接按最终深度生成，旧 scope 迟到结果无效，手动坐标不变且相同自动布局不增加 revision。
 - 关联：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/src/view/project-development/useProjectResourceCanvasLayout.ts`、`apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs`。
 
+## 等价 Runtime 投影刷新不能清空资源依赖图（2026-08-10）
+
+- 现象：专业 Agent 运行期间，资源画布中的卡片按轮询节奏整批消失并立即恢复；停止产生新的 Runtime 时间戳后闪烁减弱或消失。
+- 原因：专业 Agent 轮询会重建结果数组；资源内容虽然相同，前端图读取 effect 仍因数组引用变化重新执行，并先把图和布局置空。布局位置暂时缺失时，所有资源卡都会返回 `null`。
+- 处理：用包含项目与资源输入的语义 scope key 稳定图请求参数，等价输入不重复读取；同一项目的资源集合确实变化时，异步刷新期间保留上一个已解析图和布局，只有首次加载或切换项目才启用空图屏障。刷新失败继续展示旧快照，不能用瞬态失败清空画布。
+- 验证：AppSurface 先用全新但内容相同的 Agent 结果数组 rerender，断言图读取仍只有一次且原卡片 DOM 保持连接；再增加真实资源并延迟第二次图响应，断言旧卡片在刷新窗口持续挂载，新图返回后新增卡片正常出现。
+- 关联：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
+
+## Supervisor steer 不能只有内部排队事件（2026-08-10）
+
+- 现象：自主制作期间继续向项目总控发消息，用户消息已进入同一 Run，当前 Provider 也被中断并重新规划，但普通工作台短暂的提交状态消失后一直没有回复，直到整轮制作最终收束。
+- 原因：steer 只持久化用户消息与内部 `steer.queued` 事件；公开事件投影又明确排除 `steer.*`。普通工作台提交后会用后端 conversation 覆盖本地消息，因此仅追加临时前端气泡也无法稳定跨刷新显示。
+- 处理：根 Project Supervisor 的 steer 进入 durable `queued` 后，先写“正在判断、当前任务继续”的公开确认，再由独立 `steer-decision` LLM turn 返回自然语言回复和 `interruptCurrentProvider`。状态询问、解释和不冲突补充默认不中断；明确停止、改向或会使在途方案过期时才允许请求中断。判定和回复按 `run + steer` 持久幂等，刷新后仍可见；判定失败时继续当前任务，并在下一安全边界应用 steer。
+- 并发边界：steer 入队、Runner `runtime.steer` 通知都不得直接触发 Provider interrupt。Codex app-server 的判定使用独立节点，不能等待主节点 turn 锁；判定为 true 后也只能中断 `appliedSteerCursor < steer.sequence` 的旧 Provider 请求，已经消费该 steer 后启动的新请求不可被误杀。已经开始的工具和外部动作不强杀，完成 observation 后再消费 steer。
+- 验证：真实 mock LLM 回归必须覆盖状态询问回复且 `interruptCurrentProvider=false`；持久重放只保留一条语义回复；steer 入队后旧 Provider 继续运行，判定为 true 后才中断；新规划 Provider 的 cursor 已包含该 steer 时即使旧判定为 true 也不能中断。前端同秒多条消息保持“用户补充 → 判断提示/语义回复”的关联顺序。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/interaction.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/steering.rs`、`apps/ai-game-creator-shell/src-tauri/src/runner/dispatch.rs`、`apps/ai-game-creator-shell/src/features/agent-runtime/model.ts`。
+
 ## Jenkins 异步备份不能用 nohup 脱离作业
 
 - 现象：Stdb Publish 成功，上传日志只留下“已获取进程锁 / 上传已有备份 / 目标对象”，没有成功或可捕获错误；本地 tar.gz 和 `uploadStatus=deferred` manifest 每次发布后继续增长。
@@ -4131,6 +4148,7 @@
 
 - 现象：延迟重试携带比既有行更旧的调用方时间，回填图片序列字段时若无条件写入，会使 `updated_at` 倒退，导致基于时间戳的同步看不到更新或排序错误。
 - 处理：同源图片序列字段只允许 `None → Some`，非空冲突失败关闭；发生回填时 `updated_at = max(existing.updated_at, request_timestamp)`。legacy 音频 repair 不派生资源级图片序列或通用时长，重放继续精确匹配。
+
 ## 历史钱包消费不能从最近流水或通用订单快照推算
 
 - 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。
@@ -4198,7 +4216,9 @@
 - 原因：不是业务递归。debug 构建中 pending action continuation、后台 task queue 和 Agent 主循环各自形成大型 async poll frame；恢复路径在同一次 poll 调用链直接进入下一层状态机，累计超过 worker 默认栈。
 - 处理：整个 pending continuation、它进入的后台主循环，以及完成、取消或失败后 drain 同 Agent 后续队列时，都必须跨越独立 Tokio task 轮询边界，使上层 poll 先退栈后再轮询下一层状态机。传入边界的 future 必须先装箱；若泛型 helper 直接持有大型 future，即使随后 `spawn`，调用方 async frame 仍会把它保留在默认 worker 栈上。边界必须保留结构化取消语义；当前使用 boxed future 与 `JoinSet`，父 continuation 被丢弃时同步 abort 子任务。不得只增大 CI 的 `RUST_MIN_STACK`，否则生产默认栈仍可能崩溃。
 - 验证：失败用例必须在未设置 `RUST_MIN_STACK` 时通过；同时覆盖 policy batch 全组、拒绝 pending 后重规划并 drain 下一任务，以及 pending/cancellation 回归，证明恢复不重复生成 isolated spawn、队列继续推进且父任务取消不遗留后台子任务。
-- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs`。
+- 2026-08-10 补充：Provider、Codex CLI 与 Codex app-server 合并到同一个模式分发后，即使本轮实际选择普通 Provider，未装箱的组合 future 仍携带最大分支状态；委派子任务完成后回流父 Agent 的既有回归会在默认 Tokio worker 栈稳定溢出，单独运行同样失败，扩大 `RUST_MIN_STACK` 才通过。持久重试 helper 与非持久压缩路径都必须在构造完整物理 Provider request 后、进入下层泛型 control/lifecycle helper 前装箱；不要逐个扩大 queue worker 栈，也不要等到底层 helper 内部再装箱已经进入调用方 frame 的泛型 future。
+- 2026-08-10 验证：未设置 `RUST_MIN_STACK` 时运行 `background_agent_runtime_can_delegate_task_to_other_agent`，并追加 `provider_retry_`、`provider_handoff_`、`response_stream_` 与 Native shell 完整门禁；测试只能以默认 worker 栈通过，不能把 CI 环境变量当修复。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/pending_execution.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/provider_retry.rs`。
 
 ## Provider 可扩展不能用一个全局 protocol 枚举代替实例隔离
 
@@ -4451,6 +4471,7 @@
 - 原因：正式 SFX handler 把计费、翻译、provider、持久化和写回内联在一个 future 中；分层测试只能证明单个 helper，不能证明组合顺序和“失败后不继续”。同时若把 mock 流程另写一遍，它本身又可能与生产逻辑漂移。
 - 处理：抽出单一 Worker 编排函数和计费 / stage adapter。生产 adapter 代理现有正式实现：OSS 后只准备 asset object / binding 候选，项目资源、账号素材、画布和 job 终态通过同一原子提交落库；测试 adapter 逐段记录调用与注入失败。组合矩阵同时断言 charge / refund、LLM / provider / OSS / writeback 计数、稳定 reason code 和权威值等值。ElevenLabs 二进制、MIME、大小、timeout 和 MP3 仍由 loopback adapter 测试负责，组合 mock 不替代协议测试。
 - 验证：自动 / 手动时长 × Loop 四组合成功；余额不足；翻译、HTTP、无效音频、时长探测、OSS PUT / HEAD、asset confirm / bind、项目资源、账号素材和画布写回逐点失败；所有 job provider POST `<= 1`，预扣后失败 refund `= 1`。
+
 ## 生成结果的稳定 ID 和 job 终态都不能代替 durable receipt（2026-08-06）
 
 - 现象：Provider / OSS 已成功，但项目资源、账号素材、binding、画布和 job 只完成一部分；不确定结果重放时，有时又复制一批素材或重复推进 canvas revision。inline 路径在进程重启后尤其无法判断前一次提交是否整笔完成。
@@ -4478,3 +4499,31 @@
 - 原因：`normalize_generated_asset_folder_id` 只处理 `project`、旧 `folder-*` 和默认目录 ID 的兼容映射，不读取 SpacetimeDB；真正的 `require_owned_asset_folder` 位于生成结果持久化末端。把“失败会退款”误当成副作用补偿，漏掉退款不能撤销 provider 请求与 OSS PUT。
 - 处理：所有付费编辑器生成在队列 enqueue 前和 worker / inline 执行前复用只读 `preflight_editor_generation_target_and_return`，按认证 owner 校验可选项目及归一化目录；读取失败和归属不匹配一律失败关闭。helper 返回 canonical 项目与目录并覆写后续入队 / worker / 原子准备使用的 payload，不能校验 trim 后的项目却持久化原始空白值。角色图片、角色动作、图标 spritesheet 与 UI 提取省略目录时按实际默认目录预检；默认目录允许尚未创建，自定义目录必须存在且 owned。预检不替代最终 procedure 复验，也不保证跨外部调用的目录锁定。
 - 验证：源码顺序回归必须覆盖图片生成、图片修改、图标 spritesheet、UI 设计图提取、视频、角色动作、SFX 与 BGM 的 enqueue / direct 两层，证明纯本地格式和 `data:` / `blob:` 稳定引用门禁先执行，canonical target 在预检后写回 payload，远端引用解析、generation input rebuild、扣费、入队、provider 与 OSS 均留在预检之后；模块侧扫描证明预检只调用 runtime identity、项目、目录只读校验且不含 insert / update / delete，并覆盖带空白项目、`project`、旧 `folder-*`、默认目录 ID、自定义目录与 `None` 归一化。
+
+## Codex CLI 节点不能把进程终态当成 Runtime 提交证据（2026-08-10）
+
+- 现象：`codex exec` 已启动或退出码为 `0`，但 JSONL 没有 `turn.completed`；或者已出现 `thread.started`，Runner 随后退出，重启时误以为节点已完成。GUI 进程的 PATH、安装或登录状态与交互终端不同时，还可能在默认模式下静默落回 HTTP Provider。
+- 原因：CLI 进程、Provider lifecycle、retry/handoff 和 Runtime finalization 是连续但不同的 durable owner；本地进程退出不能代替现有账本的原子提交与回读。模式切换若不进入配置指纹，还会把另一执行模式的 retry/handoff 当成当前结果。
+- 处理：Codex CLI 必须只作为新的节点推理适配器，继续经过原 Runtime 的 lifecycle、retry、handoff、receipt、revision、verification 和 reconciliation。只接受完整 JSONL `turn.completed` 与可验证的最终消息；`started` 无 `completed`、超时、异常退出或输出破损都继续走原失败/核对边界。`agentMode`、CLI 版本和影响输出的固定参数必须纳入配置指纹；CLI 不可用时显式报错，不得静默切回 Provider。
+- 验证：确定性回归覆盖 stdin prompt、空临时 cwd、read-only/no-shell/ephemeral 参数、structured tool call 转换、缺失终态、超时进程组回收和 stderr 不泄漏；真实 smoke 必须显式 opt-in，并分开报告 CLI 协议成功与本机认证/网络结果。
+
+## 空 MCP 覆盖不会清除 Codex 用户配置中的 MCP（2026-08-10）
+
+- 现象：以 `codex app-server -c 'mcp_servers={}'` 启动后，`thread/start` 仍发出用户配置中各 MCP server 的 startup 事件；若直接把这种进程当 AGC 节点 Agent，会出现 Codex 与 AGC 两套 ToolHost、副作用和审批边界。
+- 原因：Codex `-c` 对 table 做配置合并，空 table 不是“删除已有所有条目”。长期 app-server 与一次性 `codex exec --ignore-user-config` 的配置隔离能力不同，不能照搬参数后假设用户配置已清空。
+- 处理：为 AGC app-server 创建权限受限的临时 `CODEX_HOME`，只桥接已有 `auth.json`，不带入用户 `config.toml`、MCP、skills、hooks 或项目 rules；model/provider/effort 全部由 AGC 显式传入。server→client 请求一律拒绝，原生工具 item 一律协议失败。临时 HOME 和认证桥接不得写入项目、日志或持久账本。
+- 验证：协议 smoke 必须观察 `thread/start` 后没有 MCP startup 事件；fake server 还要断言 API Key 不在 argv、初始化只一次、结构化输出回到 AGC ToolHost。只看到 `initialize` 成功不能证明安全隔离成立。
+
+## 只隔离 CODEX_HOME 仍会加载用户 Skill，且 Codex 原生工具默认不全关闭（2026-08-10）
+
+- 现象：app-server 虽然使用临时 `CODEX_HOME` 和 read-only turn，仍可能发现 `$HOME/.agents/skills`，并默认提供 cached web search、multi-agent 及其它稳定原生能力；等 `item/completed` 后再拒绝已经太晚，工具调用和额外模型成本可能已发生。
+- 原因：Codex 的用户 Skill 发现根是 OS HOME，不是 `CODEX_HOME`；`dynamicTools=[]` 也只清空宿主动态工具，不会移除 Codex 内建工具。read-only/network off 是副作用防线，不等于从模型工具目录删除能力。
+- 处理：同时隔离 `HOME / USERPROFILE / APPDATA / LOCALAPPDATA`，并在临时 workspace 创建空 `.git` 作为仓库发现边界，防止继续向父目录（例如 `/tmp`）发现 `.codex/.agents`；启动前设置 `web_search="disabled"`、`agents.enabled=false`，并关闭 shell/unified exec/browser/plugin/image/workspace dependency 等原生 feature；接收 `item/started` 时只允许消息、计划、推理和压缩等被动 item，其余立即 interrupt。配置中的 `webSearchEnabled=true` 必须失败关闭并提示切 `provider`。
+- 验证：fake app-server 检查 argv 不含 Key、专用 Key 只在环境、继承 `CODEX_API_KEY` 被移除、HOME 指向临时目录、web/multi-agent/shell 关闭；另覆盖 turn-start 回包前 drop 最终只发一次对应 interrupt。
+
+## 多 Agent 共享一个 Codex app-server 会放大单点终态丢失（2026-08-10）
+
+- 现象：多个节点最初已有 `started -> completed`，随后一个 app-server stdio 连接关闭，同一秒多个仍在途节点一起进入 `needs-reconciliation`；单看 threadId 不同会误以为节点已经进程隔离。
+- 原因：pool 只按 LLM 凭据和路由复用进程，节点身份只用于进程内 thread map。任一 stdout framing、子进程退出或连接故障都会 drain 整个进程的 pending/turn router，使所有共享节点同时失去可信终态。
+- 处理：pool key 必须包含 `projectId + agentId + sessionId + runId`，每个权威节点直接持有独立 app-server 子进程；同节点 turn 还要串行，不能向同一 thread 并发 `turn/start`。只发送当前 CLI schema 定义的字段；stderr 使用有界内存尾部并先脱敏再进入 Runner 诊断。
+- 验证：至少两个节点并发各跑多轮，确认存在两个 app-server PID；终止其中一个后只有对应节点进入 reconciliation，另一个仍能收到 `turn/completed`。旧 AppData 缺 `agentMode` 且含非 Responses 路由时必须保留 `provider`，不能在项目自动恢复时批量失败。