合并远端主线并解决游戏创作冲突

融合主线 Runtime、安全修复与提示词资源
保留可运行版本、资源替换和数值微调能力
修复资源画布布局、焦点与依赖关系融合
补齐 manifest 并发保护与 Tetris 场景兼容
同步前端测试、Rust 回归测试与权威文档

docs/project-memory/shared-memory/development-workflow.md

@@ -89,17 +89,35 @@ cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml real_
 
 修改 game-chat release flavor 后，至少执行壳配置门禁、AppSurface game-chat 定向测试、前端类型检查、AppData / 诊断日志 / release flavor 相关 Rust 定向测试、`npm run check:encoding` 和 `git diff --check`。打包 smoke 必须确认：安装信息和产物版本为 `0.1.1`；无参数启动直接进入且只能停留在 game-chat 页面；停止或断开 `api-server` 后本地工作台仍能打开；普通 dev / release 与 debug game-chat 仍走原认证入口；独立 AppData 生效。预览 smoke 应先让当前 run 成功验证 revision N，确认 Tauri registry 启动一个 server 且 iframe 自动出现；在 validate 后、start 取得锁前推进项目 revision，必须确认原子 `expectedRevision` 门禁拒绝启动且授权保留等待新证据；再验证 revision N+1，确认 server 进程和 loopback origin 不变、iframe 显示新版本且响应为 `no-store`。same-run steer 还要覆盖旧验证不消费新授权、旧异步 attempt 不清新 generation；Runner registry 单独 running、失败 / 相同 / 更低 revision 均不能触发用户预览或重复刷新，停止后顶部显示“预览未启动”。独立包退出时必须通过 `runner.shutdown_for_client_exit` 先进入 draining 再结束本 boot，保留 durable sidecar 供下次 reconciliation，不把中断任务写成 completed；Windows Runner 必须 `CREATE_SUSPENDED -> AssignProcessToJobObject -> ResumeThread`，分配或恢复失败时 kill + wait，客户端持有 kill-on-close Job 兜底，关闭主窗口后 Runner、MCP、command、ConPTY 及其后代都应消失。普通 dev / release 和 CLI 继续使用 `runner.shutdown_if_idle`。
 
-game-chat 迭代还必须确认以下行为：Supervisor ready 输出、`art-director / code-prototype / preview-readiness / preview-playtest` 四个专业 Agent 的 durable `final-reply`，以及 Rust 明确生成 `eventId + publicText` 的每条公开 Runtime 输出都作为独立 assistant 消息逐条固化在项目聊天；`art-asset-plan` 不进入进度、阶段记录或 final-reply 投影。消息通过顶层 `messageId` 幂等追加，事件 / 轮询 / hydration 重放不重复。前端禁止从原始 `summary / detail`、tool plan、Provider / Runner 元数据、命令输出或路径自行拼接持久消息；UI 把一个父 Run 统一显示为“本轮生成进度”，最新状态也不得暴露内部“第 N 轮”，完整 GUI / CLI 任务图可显示 `x/14`，首版快车道显示 `x/4`，终态不保留运行中进度卡；可信 `project-supervisor-game-chat` 一轮完成 `preview-playtest` 后直接收束，不请求下一次 Provider tool-plan；所有调度入口（包括 `agent.schedule_ready`、`task.list` 结果驱动的直接 `agent.delegate`）均不得暴露或启动 `publish-strategy` / `publish-package`。game-chat 必须配置可用的 External Editor API，由 `art-director` 通过一次平台 `images/generations` 生成并登记 `assets/art-spec.png`，`code-prototype` 必须把它显著用于用户可见的主要背景、玩家和目标；未配置 API 或缺少任一环节都必须失败关闭。普通 GUI / CLI autonomous 继续正式透明 `assets/art-spritesheet.png` 的完整 DAG。对应定向测试至少包括：
+game-chat 迭代还必须确认以下行为：Supervisor ready 输出、本轮实际启动的 `design-director / art-director / art-asset-plan / code-director / code-prototype / preview-readiness / preview-playtest` 专业 Agent 各自产生 durable `final-reply`，条件路由跳过的节点只要求 manifest 正确投影为 completed，不伪造 Agent 回复；Rust 明确生成 `eventId + publicText` 的每条公开 Runtime 输出都作为独立 assistant 消息逐条固化在项目聊天。消息通过顶层 `messageId` 幂等追加，事件 / 轮询 / hydration 重放不重复。前端禁止从原始 `summary / detail`、tool plan、Provider / Runner 元数据、命令输出或路径自行拼接持久消息；UI 把一个父 Run 统一显示为“本轮生成进度”，最新状态也不得暴露内部“第 N 轮”，完整 GUI / CLI 任务图可显示 `x/14`，首版快车道显示 `x/7`，终态不保留运行中进度卡；可信 `project-supervisor-game-chat` 一轮完成 `preview-playtest` 后直接收束，不请求下一次 Provider tool-plan；所有调度入口均不得暴露或启动 `publish-strategy` / `publish-package`。固定关键词与资产探测只进入 Supervisor 的 advisory context；没有持久 Supervisor 路由时不得启动任何 child。只有程序侧审计判定存在真实缺口或 Supervisor 明确选择整体重做时才要求可用 External Editor API，并按 `art-spec.png -> icon-spritesheet -> art-spritesheet.png + iconImageSrcs 本地切片 -> code-prototype Canvas 使用四类切片` 补齐；`use-existing-art` 不得重复生成或扣费，但仍须通过相同正式资产和代码可见使用门禁。
 
-game-chat 首版快车道采用独立四阶段口径：只显示 `art-director`、`code-prototype`、`preview-readiness`、`preview-playtest` 的 `x/4`，不把完整 DAG 或内部 loop 计入分母。父 Run 与全部 child Run 共用 240 秒软预算和 300 秒累计硬上限；首版最多一次 Provider 规划 / 写入请求，软预算后只能运行确定性的本地 fallback、`game.static_smoke`、`preview.validate`，硬上限内未通过完成门必须失败，证据在上限后到齐也不得写 `single_round_converged`。live10 实测正式透明 `icon-spritesheet` 后处理超过 300 秒，因此 game-chat 改为一次平台 `images/generations` 生成并登记 `assets/art-spec.png`；fallback 只有该图片有效登记且真实存在时才允许生成，并必须把它显著绘制为主要背景、玩家和目标。未配置 External Editor API、图片生成失败、缺少 Canvas / manifest 登记、文件、HTML 引用或用户可见绘制时必须在 300 秒内失败关闭，绝不误报 completed。普通 GUI / CLI 继续正式透明 `assets/art-spritesheet.png` 的完整 DAG。对应定向测试至少包括：
+Project Supervisor 根后台任务还必须验证公开消息硬门：任务先落为不可执行的 `preparing / public-status-pending`，项目 conversation 中存在且仅存在一条同 run 的 `runtime-public-status-* / accepted` 后才能转为 `pending / queued`；恢复 preflight 只验证并临时分类可恢复状态，不改写 task/conversation，真实 resume 持有 Agent 锁后才可把 accepted preparing 持久提升为 `pending / queued`；否则不得执行。若该消息无法持久化，task 必须进入 `failed / public-status-write-failed` 且 Provider、工具与 child 调度均为零。这类 Runtime 公开状态不得合入 Agent prompt。根 Supervisor 通过正式失败 / 预算耗尽收束或 game-chat 绝对硬期限进入 reconciliation 时，即使后续 task/event/state 写入失败，也必须已经存在一条脱敏终态失败消息；专业 Agent 命中全局硬期限时，项目 conversation 仍必须幂等保留根终态，但 child 终态只能写入与权威 task 的 agent/run/session、两个 parent 和 binding 全部一致的私有 Session；自称根 agent/run 却 session 或 parent 不符时失败关闭。只有根 Supervisor 的 `turn.started / turn.failed / turn.budget_exhausted` 不得再形成第二条聊天消息，专业 Agent 的公开启动事件仍应显示。非 Supervisor 专业 Agent 的失败状态留在对应 Agent Session，不得把私有诊断送进项目 conversation。定向复验至少运行：
 
-game-chat GUI 恢复还要覆盖两类竞态：root Runtime 先终态、manifest 四阶段后终态时，必须等到四任务最终状态后仅持久化一条 `【Supervisor 阶段记录】`；页面初始 hydration 直接读到真实终态时也要补写缺失记录，但不得把 `idle` 当作完成。同时，GUI 启动的 `agent.resume` 自动扫描必须先做只读恢复工作预检：新项目或无 task / retry / handoff / finalization / pending / reconciliation 工作的已终态项目不弹确认，存在任何 durable recovery artifact 则仍必须命中 `agent.resume` policy。
+提交前还要覆盖启动崩溃窗口：仅 `preparing` 时 preflight/resume 均不执行；用户消息已持久但 accepted 缺失时，preflight 只报可恢复且 task/conversation 不变，resume 才补写 accepted 并转为 `pending / queued`。还要验证用户消息或 accepted 已落盘但审计失败均继续入队、根终态首次公开写入瞬时失败会用同 ID 重试、receipt / isolated-join 失败只有一条公开结果，以及同秒连续任务通过共享的 run 关联摘要按 `user -> accepted -> terminal` 逐任务展示。
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml public_start_status -- --test-threads=1
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml structured_plan_state_write_failure_stops_before_context_and_audit -- --test-threads=1
+npm run test -- apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts apps/ai-game-creator-shell/tests/appSurface.test.ts
+```
+
+game-chat 条件快车道仍采用七任务口径，但执行顺序由持久合同控制。父 Run 与全部 child Run 共用 4200 秒软预算和 4500 秒累计硬上限；Supervisor 首轮先调用 `agent.route_manifest`，决策前零 child。`audit-existing-first` 的首波仅为 `design-director + code-director`，已登记但无效的旧派生视觉不得阻断这两项审计启动；code-director 必须先 `asset.list`，读取 Supervisor 已持久化的 authoritative 决策，再提交正式资产覆盖合同。覆盖完整时跳过图片生成，存在缺口时只开放缺口对应 owner，`regenerate-art` 才强制重新开放两个美术 owner；已登记但校验失败的固定资产只允许当前路由绑定的 canonical owner 原位替换。新生成仍按 `art-spec.png -> art-spritesheet.png + 独立切片` 推进，最后才允许 code-prototype 写入或局部修复入口。软预算后只允许使用已登记图集、当前 resourceId 对应切片清单的确定性本地 fallback、`game.static_smoke` 和 `preview.validate`；不得退回普通生图、猜测 atlas 网格或纯代码核心画面。完成门要求活动 Canvas 分别绘制 player、blocks-and-targets、obstacles-and-scene、feedback-effects 四类不同切片；整图 `<img>`、CSS background、完整图集直绘、单个猜测裁切和路径诱饵均失败。对应定向测试至少包括：决策前零 child、旧无效视觉不阻断首波、首波无美术 child、code-director 收到真实持久策略、完整覆盖零生成、仅缺图集只运行 `art-asset-plan`、无效已登记资产由 owner 原位替换、art spec 缺失导致引用合同失效时同时补齐两个槽位、显式重做原位替换两个正式资产、旧 root/fingerprint/缺口或重复路由失败关闭，以及补齐后恢复 code-prototype。
+
+失败续跑还必须覆盖同 Session 同 source 继承、跨 Session / 跨 source 不继承、首次与连续 successor 的 effective task / contract / scheduler 一致性，以及中英文纯继续短语使用同一识别函数。非占位入口的新 `code-prototype` 必须先产生本人 mutation 再 smoke；连续只读 smoke 不得收束。占位 fallback 只允许显式支持的真实玩法模板，俄罗斯方块必须验证棋盘、下落、旋转、锁定和消行语义，未知玩法必须失败关闭。
+
+game-chat GUI 恢复还要覆盖两类竞态：root Runtime 先终态、manifest 七任务 lane 后终态时，必须等到七个首版任务最终状态后仅持久化一条 `【Supervisor 阶段记录】`；页面初始 hydration 直接读到真实终态时也要补写缺失记录，但不得把 `idle` 当作完成。同时，GUI 启动的 `agent.resume` 自动扫描必须先做只读恢复工作预检：新项目或无 task / retry / handoff / finalization / pending / reconciliation 工作的已终态项目不弹确认，存在任何 durable recovery artifact 则仍必须命中 `agent.resume` policy。
 
 ```bash
 npm run test -- apps/ai-game-creator-shell/tests/agentRuntimeModel.test.ts --run
 cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml autonomous_completion_contract -- --nocapture --test-threads=1
 ```
 
+修改 manifest invalidation relay、GUI owner attach 或其测试夹具后，所有会读写进程全局事件 sink 的测试统一使用 `manifest_invalidation_sink_isolation_` 前缀，并至少以 2 个 test thread 重复运行该 filter。测试 fixture 的 accept 和 payload 读取都必须使用总 deadline，不能只在 accept 成功后给 `TcpStream` 设置 read timeout；全局 sink 只能在共享 test-only 串行锁内由 RAII guard 配置和清理。
+
+```bash
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml manifest_invalidation_sink_isolation_ -- --nocapture --test-threads=2
+```
+
 source allowlist、game-chat 单轮完成门和 Canvas spritesheet 引用门禁均须命中实际测试；若完整 Rust suite 受 Windows `os error 32` 既有文件锁竞态影响，应单独复跑新增 filter 并如实记录，不能把锁竞态失败改报为本次改动通过。
 
 Windows release 的非交互后台命令统一使用 `CREATE_NO_WINDOW`，包括 `command.exec / project.verify`、STDIO MCP、Repository Context Git、`git.inspect / project.git_commit` 和 `taskkill` 清理命令；需要进程组终止时再叠加 `CREATE_NEW_PROCESS_GROUP`，不要使用 `DETACHED_PROCESS`。smoke 时应在实际任务运行期间观察无额外控制台窗口，并在关闭客户端后核对整棵后台进程树为零，再重启确认 reconciliation 可继续。
@@ -654,7 +672,7 @@ npm run ai-game-creator-shell:agent-runtime:supervisor-swarm-tool-plan-handoff-r
 
 ## AI 游戏创作长耗时与退出恢复验证
 
-- 修改 autonomous 调度时，必须证明缺省 policy 不产生 manifest 之外的首波专业委派，Editor Key、已有/损坏视觉资产均不能改变该事实；显式项目 policy 只验证“原样尊重”，不能由 Runtime 隐式扩充。
+- 修改 autonomous 调度时，必须证明缺省 policy 不产生 manifest 之外的首波专业委派，Editor Key、已有/损坏视觉资产均不能改变该事实；game-chat 还必须证明持久 Supervisor 决策前零 child，决策后的首波只有 `design-director + code-director`，固定关键词不能直接改 Graph。显式项目 policy 只验证“原样尊重”，不能由 Runtime 隐式扩充。
 - 修改预览完成门时，分别覆盖 child `preview-readiness` 当前 revision smoke、child `preview-playtest` 到根 Supervisor 合同的 browser receipt，以及 WebSocket 启动前退出的稳定基础设施分类。基础设施错误必须在一次浏览器调用后让 run 失败，不能只做到后续调用快速失败而继续消耗 Provider 轮次。
 - 修改 game-chat Runner 生命周期时，至少覆盖 busy durable sidecar 拒绝 client-exit、拒绝后 `draining=false` 可继续执行、清空后 idle shutdown、重复 shutdown 幂等；Windows target check 继续保留，不能以删除 Job Object 或放任后台继续来规避 reconciliation。
 - LLM 配置回归必须穷举全部规范 Agent，校验无遗漏/重复、显式 patch 覆盖默认，并锁定 GUI 展示映射和 Rust resolver 一致；模板与 GUI 初始草稿不得把规范默认持久化成 `agentLlm` 显式覆盖。`--llm-status` 要输出逐 Agent 实际 reasoning/timing/retry 值。运行日志与当前配置冲突时，先区分 durable run snapshot 和后来修改的文件，不能按当前文件反推历史请求。

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

@@ -38,11 +38,92 @@
 - 验证：分别用 `lsof -a -p <pid> -d cwd -Fn` 核对两组监听进程 cwd；app-run 窗口标题必须为“AI 游戏创作 · App Run”，Vite marker API target 必须指向 app-run 的实际 API。
 - 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`、`apps/ai-game-creator-shell/src-tauri/tauri.app-run-dev.conf.json`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## Chat 生成预算字段不能按模型名猜测或失败后自动重放
+
+- 现象：同一个 OpenAI-compatible Chat endpoint 调用 reasoning 模型时返回 `Unsupported parameter: max_tokens`；直接把全局请求字段改成 `max_completion_tokens` 后，旧兼容网关又可能拒绝新字段。
+- 原因：内部生成预算语义与上游 wire dialect 被混在一起。Chat 当前字段是 `max_completion_tokens`，旧兼容层仍只接受 `max_tokens`；Responses 和 Anthropic 又分别使用自己的字段。模型名、base URL 和 `OpenAiCompatible` 标签都不能证明 endpoint 能力，收到 `400` 后重发还可能重复计费。
+- 处理：在 `LlmConfig` 上显式声明 Chat token budget field capability；通用兼容配置默认 legacy，已验证的 VectorEngine 专用 client opt-in `max_completion_tokens`，每次只发送一个字段。内部 `max_output_tokens` 与 AGC 持久指纹键 `maxOutputTokens` 保持不变。
+- 验证：序列化测试分别断言 modern / legacy Chat 只出现选定字段，请求级 model override 不改变字段；Responses 继续只发 `max_output_tokens`，Anthropic 继续只发 `max_tokens`；AppState 测试断言 VectorEngine client 已显式启用 modern capability。
+- 关联：`server-rs/crates/platform-llm/src/lib.rs`、`server-rs/crates/api-server/src/state.rs`、`scripts/test-ve-llm.mjs`、Issue #143。
+
+## Runtime 状态写失败不能发生在公开失败消息之前
+
+- 现象：用户提交长任务后只看到运行失败或任务直接消失，聊天里一条有用消息都没有；另一些失败又同时出现 Runtime event 和 conversation 两条近似提示。
+- 原因：启动确认依赖实际 `turn.started`，任务只入队或 Runner 在 start transition 前失败时没有公开回执；终态失败先写 task/event/state，最后才由各 main-loop 分支尽力追加 assistant。坏掉的若正是状态文件，流程会在公开消息前返回；散落的 `let _` 又无法提供幂等身份。
+- 处理：用户直接投递的 Project Supervisor 根任务先落为不可执行的 `preparing / public-status-pending`，持久化同 run 的 `runtime-public-status-* / accepted` 后才转为 `pending / queued`；恢复 preflight 只验证业务状态，不改写 task/conversation，仅 resume 持有 Agent 锁后才可持久提升。根 Supervisor 通过正式失败 / 预算耗尽收束或 game-chat 绝对硬期限进入 reconciliation 时，先写相同协议的终态消息，再处理 Runtime 其它投影。专业 Agent 命中全局硬期限时，应由权威根 task 在项目 conversation 中幂等写根终态，child 仅在身份完整匹配时写私有 Session；根 agent/run 的 session 或两个 parent 冲突时必须失败关闭。消息正文只能来自封闭脱敏映射，prompt 构建必须按稳定前缀排除；前端按前缀标记 Runtime-owned，只过滤根 Supervisor 的 `turn.started / turn.failed / turn.budget_exhausted`，不吞掉专业 Agent 启动进度。模型仍负责业务 commentary/final，Runtime 的两条硬门不扩展成业务判断器。
+- 恢复补充：不能把“accepted 还没写完”等同于“用户从未投递”。用户消息已持久时，真实 resume 必须补写 accepted 后才入队；用户消息或 accepted conversation 已存在时，后续审计失败不得留下“正在启动”但永不执行的假状态，但同 message ID 的 role/content 冲突必须把 task 明确收束为 `conversation-write-failed`。根终态首次公开写入的瞬时失败必须在终态投影后用相同 message ID 重试。带 parent 的 Supervisor continuation 不得同时产生 Session 终态和 Runtime 事件两条公开消息；秒级时间戳下必须以 task/status message ID 共享的 run 关联摘要排序，不能用不同消息类别的计数猜测顺序。
+- 验证：任务 journal 必须显示 `preparing -> pending`，仅有 accepted 时恢复才可提升；破坏项目 conversation 时断言任务为 `public-status-write-failed` 且无可运行 pending；破坏 Runtime state 路径时断言公开失败已经存在；重复写同一 run/status 只有一条 message ID；渲染实际 prompt 断言不包含 Runtime 公开状态；AppSurface 证明根启动/失败事件不重复，专业 Agent 启动仍可见。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_state.rs`、`agent/runtime_driver/task_start.rs`、`src/features/agent-runtime/model.ts`、`src/features/project-workspace/SupervisorChatOnlyView.tsx`。
+
+## manifest 被旧快照写回 Pending 时不能让父 Run 抛下真实运行中的 child
+
+- 现象：`code-prototype` 已有确定性 child run、running journal 和工具事件，父 Supervisor 却在几秒后以 fixed graph stalled 失败；child 随后完成代码与静态检查，但 completion gate 持续报告 `task=code-prototype status=pending`，最后 `loop-budget-exhausted`。
+- 原因：并发 hydration 或其它旧 manifest 快照把 scheduler 已写的 running 覆盖为 pending；父 Run 把“当前不宜调度新 child”错误等同于“没有 child 需要等待”，并只以 manifest 状态判断 DAG 活性。父先终态后，真实 child 也失去正常投影窗口。
+- 处理：调度与等待分离。新调度可以被派生视觉修复等门禁阻止，但当前最新活跃根 Run 下，只要 durable child 具有确定性 runId、scheduler source、正确父链接且 journal 仍处于 queued/running，父 Run 就继续等待；同一 child 的完成门可容忍 manifest pending，但仍执行正式产物、revision、静态检查与试玩证据门禁。更新根 Run、GUI/CLI、终态/确认/reconciliation child 或绑定冲突全部失败关闭。
+- 验证：人工把当前 child 的 manifest 状态回写 pending，断言父 DAG 仍 in progress、父上下文可持久化为 `waiting-for-manifest-tasks`、child 可投影 completed；随后创建更新根 Run，断言旧 child 不再保持 DAG 活性且 completion blocker 恢复 `status=pending`。不要靠增加 loop 次数或伪造 completed 掩盖竞态。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/autonomous_policy.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/main_loop.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`。
+
+## 固定关键词提示不能代替 Supervisor 选择条件任务图
+
+- 现象：用户只说“现在没有用到任何美术资源”，Graph 就在 Supervisor 输出任何计划前自动打开美术节点；或者用户想复用现有素材，Runtime 直接按关键词预完成节点。Supervisor 无固定计划时随即 `fixed-task-graph-stalled`，看起来像模型不理解意图，实际上模型根本没有获得决策机会。
+- 原因：同一套关键词函数同时承担 prompt hint、Graph reset、baseline 豁免和历史试玩类型继承，启发式信号越过 Supervisor 成为了控制面真相；main loop 又在 Provider 请求前优先调度 ready task。
+- 处理：启发式结果只序列化成 `advisoryOnly=true` 的 Supervisor context。Scheduler 以持久 `GameChatWorkflowDecision` 为首轮前置门；Supervisor 先选审计或整体重做，code-director 再用成功 `asset.list` 和 Runtime 复核的覆盖合同选择复用或精确补缺。Runtime 可以拒绝过期、伪造、遗漏或重复 route，但不得替 Supervisor 补写决定。
+- 验证：直接使用用户原句，断言 hint 命中但 manifest 全部保持 pending、决策前零 child、Provider request 包含路由工具；决策后首波只有 design/code，code-director 未完成 asset.list/route 时不能完成；再分别覆盖完整复用、真实缺口和显式重做。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`runtime_driver/main_loop.rs`、`runtime_driver/task_start.rs`、`runtime_protocol/autonomous_completion.rs`。
+
+## 既有正式产物不能同时被快车道视为已完成、被本轮 baseline 门视为未变化
+
+- 现象：增量任务已有完整美术图集，`art-asset-plan` 每轮都返回零 action 和“已验证交付”，但 completion gate 每轮都报告 `assets/manifest.art.json(unchanged-from-run-baseline)`；最终 child `loop-budget-exhausted`，随后 Graph 和父 Run 失败。日志中没有本轮 Provider request、tool plan 或 action receipt。
+- 原因：Graph reset 无差别重新打开稳定的美术 owner 节点；快车道按“当前产物有效”判断完成，owner 完成合同则按“本轮必须修改 baseline 产物”判断完成，两套语义互相冲突。增加 loop 预算、伪造版本号或机械改写 manifest 都不能消除冲突，还会引入 verification loop、字段丢失或错误复用旧主题。
+- 处理：关键词和资产探测只作为 Supervisor 的 advisory context，不能直接修改 Graph。根 Run 先持久化 `audit-existing-first / regenerate-art` 决策；前者只启动 `design-director + code-director`，由 code-director 在成功 `asset.list` 后提交权威覆盖合同和精确缺口。Runtime 验证合同后才把已有 owner 投影为 completed，或只打开缺口 owner；根完成门只对持久路由明确复用的 art manifest 忽略 baseline 相同，所有结构、Canvas、私有回执、切片和可见使用验收继续失败关闭。
+- 验证：先断言 Supervisor 决策前零 child、固定关键词不会预完成节点，再覆盖完整复用、仅缺图集和明确重做。还要直接经过父完成门，证明合法持久路由不再出现 art baseline gap，并证明删除切片后覆盖合同拒绝复用；旧 root、错误 fingerprint、虚构或遗漏缺口和重复改写路由都应失败关闭。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`。
+
+## 执行锁移交给未确认启动的异步 future 会制造永久 queued
+
+- 现象：父 Supervisor 与 Runner 一直显示运行中、heartbeat 正常，专业 Agent 已有 `background_task.queued` 和 `autonomous_ready_task.scheduled`，对应执行锁也被 Runner 持有，但该 child 永远没有 running journal、`turn.started` 或后续 Runtime event；其它同批 Agent 可能已经完成。
+- 原因：ready scheduler 把 per-Agent 执行锁直接 move 进 fire-and-forget Tokio future，并在 future 首次 poll 前返回成功。锁移交不是启动确认；future 未进入 start transition 时，常规 wake/recovery 又拿不到同一把锁，queued task 因而没有任何接管者。预先占用 child locks 的测试会绕过真实 spawn 路径，无法发现该缺口。
+- 处理：实际 Runner 必须在项目写锁外同步完成 pending -> running 与 started journal，成功且 execution worker 已开始轮询后才移交执行锁；启动/接管失败必须持锁完成 child failed 与 manifest Graph failed 投影，再释放锁并让 parent 收到错误。scheduled 诊断审计失败不能阻断 child 启动，external client 只负责 wake Runner。UI 另以 durable `startedAt` 和父/子最大活动时间显示运行态时长及疑似停滞；task-record fallback 不得把最新 record 时间写成 startedAt，父 Run terminal 后也不得被 child 晚到事件继续增加时长。
+- 验证：使用真实空闲 child lanes 一次调度 `design-director / art-director / code-director`，在有界时间内逐一断言 running/`turn.started`，并验证幂等重调度不新增逻辑 Run；禁止只断言 scheduled 记录、锁文件或 Runner heartbeat。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_start.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/task_queue.rs`、`apps/ai-game-creator-shell/src/features/project-workspace/SupervisorChatOnlyView.tsx`。
+
+## Canvas 视觉门不能在没有资产词法候选时运行整套 JavaScript 语义分析
+
+- 现象：Supervisor 已写入 `turn.started`，但第一条 planning 进度长期不出现；Runner 无 Provider 连接，单个 Tokio worker 持续占满一核。对项目现场复现时，15 KiB 的经典脚本在检查一个根本未被引用的切片文件时，超过 60 秒仍未返回。
+- 原因：视觉门先为每个候选切片无条件执行模块依赖分析和函数可达性分析，最后才判断图片 `.src` 或已绑定 DOM 元素是否能指向目标资产。没有 `import` 关键字、没有目标文件名且没有已绑定图片元素时，这些全程序分析不可能产生有效视觉证据，属于纯浪费；复杂闭包与 alias 图会把浪费放大成看似 Runtime 停滞。
+- 处理：仅做单向安全短路：JavaScript 原文同时没有大小写精确的 `import` 与 `export` 字节序列时，跳过模块依赖语义分析；纯 `export ... from` / `export * from` 仍是模块图依赖，不能误跳过。当前脚本不含目标文件名或任一已绑定 DOM 图片元素 ID 时，先低成本解码 `\\xNN`、`\\uNNNN`、`\\u{...}`、简单转义和续行；解码后仍无候选才直接判定没有绘制证据，解码不确定则保守进入 Oxc。这样必须保留 computed `s\\x72c`、转义资产 URL 与转义 `getElementById/querySelector`，同时不能因 HTML 中存在某个绑定元素让所有无关 JavaScript 单元进入重分析。
+- 验证：无候选现场的同一切片检查必须有界返回且保持 `missing-visible-art-slice-use` 结论；同时覆盖相对路径、转义 URL、computed/转义属性与 DOM 方法、绑定 DOM 图片元素、含无关正则转义的脚本单元、路径大小写、纯重导出模块图、动态 import namespace 写入、未调用函数、恒假分支和真实可达 `drawImage`，证明短路只拒绝不可能命中的输入，不扩大验收权限。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`。
+
+## ready-task 对账取消后不能让 successor 永久继承 failed Graph
+
+- 现象：未知工具结果按安全边界进入 `needs-reconciliation`，人工核对后取消原 child；manifest 随即把该节点投影为 failed，父 game-chat 固定任务图明确失败。随后重试父 Run 虽创建同源 successor，却原样继承 failed manifest，几秒内再次失败，原项目无法继续。
+- 原因：取消原 reconciliation Run 只负责安全释放 Agent 队列屏障，并不等于 manifest 任务完成；continuation 完成合同保留既有 Graph 进度，却没有区分“普通失败”和“已经人工核对、保留 cancel tombstone 的 reconciliation 取消”。
+- 处理：旧 action 继续禁止重放或伪造 observation；旧 child 与父 Run 先真实终态。新 Supervisor continuation 仅扫描同 Session、同 source、同有效任务合同的历史根 Run，并要求对应 ready-task 同时存在 `failed / needs-reconciliation` 记录、最终 `cancelled` 记录和 durable cancel tombstone，才把当前 manifest 的同一 failed 节点恢复为 pending，让 scheduler 创建新 child Run。manifest 的读取、筛选、child 证据重验和写回放在同一项目写锁内；每个 task journal 只读取一次并按 parent Run 建索引。较新的无 child Run 默认阻断旧凭证，只有其 root journal 精确证明为旧 failed Graph 在进入 scheduler 前即失败时才允许向前查找；scheduler 自身失败不得被当成该兼容场景。
+- 验证：构造 reconciliation child、人工 cancel tombstone、failed manifest 和终态父 Run，证明同源 continuation 只重排该节点；并列普通 failed 节点保持 failed，完成合同继续继承原任务 SHA 与项目 baseline，旧 pending action 不恢复。追加覆盖“旧 failed Graph 未调度”的中间 Run 可以跨过，而较新的 scheduler failure 即使没有 child journal 也会阻断更老 tombstone。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion_contract_tests.rs`。
+
+## `timeout_at` 不能替代显式的预算耗尽预检
+
+- 现象：给完美像素加端点级并发闸后，预算已经耗尽的请求仍然能拿到许可，白占一个名额继续去打几轮全账号 SpacetimeDB 扫描，直到下载那步才失败。
+- 原因：`tokio::time::timeout_at` 会先 poll 一次内层 future 再判超时。信号量有空闲许可时 `acquire_owned()` 首次 poll 就绪，于是即使 deadline 早已过去，返回的仍是 `Ok(Ok(permit))` 而不是超时。既有 `acquire_editor_pixel_art_cpu_permit` 里那句 `if Instant::now() >= processing_deadline` 正是为此存在，新写的许可函数漏掉后被单测抓出。
+- 处理：所有「先判预算、再等资源」的获取函数都必须在 `timeout_at` 之前显式判一次 `Instant::now() >= deadline` 并直接返回超时错误；这句不是冗余防御。同理，进入排队计数之前也要先做这个预检，避免为注定失败的请求占用队列名额。
+- 验证：在有空闲许可时用已过期的 deadline 调用获取函数，只断言返回 `504` 而不是许可；`504` 已足以证明显式预检没有被 `timeout_at` 的首次 poll 绕过。禁止在该用例里读取进程级队列 Atomic 的 before/after；相对断言同样会被并行测试插入。仅靠「信号量占满时超时」的用例发现不了这个问题。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`（`acquire_editor_pixel_art_snap_permit`、`acquire_editor_pixel_art_cpu_permit`）。
+
+## 有界等待队列的计数递减必须写在 Drop 里
+
+- 现象：给同步端点加「最多 N 个等待者」的保险丝时，若把计数递减写在正常返回路径上，客户端断连或超时触发会让等待中的 future 被丢弃而跳过递减；计数只增不减，最终队列永久判定为满，接口对所有人返回 `503` 且不会自愈。
+- 原因：Rust 的 async future 可以在任意 await 点被取消，取消时只保证 `Drop` 会跑，不保证后续代码会执行。有界队列的入场与离场天然不对称。
+- 处理：把递增封进一个 guard 结构体，递减放在它的 `Drop` 实现里；递增本身用 `fetch_update` 的 CAS，不能用「先读后加」——两个线程同时读到 `max - 1` 各自加一就会越界。拿到资源后立即 `drop(guard)` 让出队列名额，不要让它跟着许可一起活到请求结束。
+- 验证：单测覆盖 CAS 边界（满了返回失败且计数不越界、上限为 0 时任何进入都失败），并由独立用例覆盖 guard 离开作用域后的计数归还。预算耗尽路径只断言 `504`，不得通过另一个测试也会修改的进程级 static before/after 来推断“未入队”，也不得用串行锁或 `--test-threads=1` 掩盖隔离问题。
+- 关联：`server-rs/crates/api-server/src/editor_project.rs`（`try_enter_bounded_queue`、`EditorPixelArtSnapQueueGuard`）。
+
 ## Linux 生产脚本门禁不能假设本地也是 GNU userland
 
 - 现象：macOS 本地运行维护页、生产 API 部署和 Rust 产物门禁时，依次出现 `mv: illegal option -- T`、`mapfile: command not found`、`/usr/bin/cp` / `/usr/bin/chmod` 不存在，以及 `.rlib` 明明含有 `.o` 却报告“没有可扫描成员”；安全修复计划还会把 `/var/folders` 到 `/private/var/folders` 的系统别名误判为用户符号链接。
 - 原因：生产机是 Linux/GNU，而本地门禁运行在 BSD userland、Bash 3.2 和 BSD ar；测试桩硬编码 Linux 二进制路径与参数，归档解析器没有去掉 BSD 扩展成员名的尾随 NUL，路径校验也直接比较了未规范化字符串。
-- 处理：维护 marker 使用同目录临时文件加 POSIX `mv -f`；生产部署测试桩在 macOS 忠实模拟 GNU `mv/ln -T` 的“目标不是目录”语义，并按平台选择系统工具；脚本收集服务使用 Bash 3.2 可用的 `while read`；rlib 解析清理 BSD 成员名 NUL；计划文件只规范化系统临时目录别名，仍拒绝其下用户创建的符号链接组件。
+- 处理：维护 marker 使用同目录临时文件加 POSIX `mv -f`，并在替换前拒绝所有符号链接和目录目标，避免 `mv -f` 跟随目录链接把临时文件移入链接目标；生产部署测试桩在 macOS 忠实模拟 GNU `mv/ln -T` 的“目标不是目录”语义，并按平台选择系统工具；脚本收集服务使用 Bash 3.2 可用的 `while read`；rlib 解析清理 BSD 成员名 NUL；计划文件只规范化系统临时目录别名，仍拒绝其下用户创建的符号链接组件。
 - 验证：运行 `npm run check:maintenance-page`、`npm run check:production-api-deploy`、`npm run check:server-rs-ddd`、`npm run test -- scripts/spacetime-repair-editor-canvas-resources.test.ts`，并在 Linux CI 保留同一生产脚本语义。
 - 关联：`scripts/deploy/maintenance-on.sh`、`scripts/check-maintenance-page.mjs`、`scripts/check-production-api-deploy.mjs`、`scripts/deploy/production-api-deploy.sh`、`scripts/check-module-runtime-artifact.mjs`、`scripts/spacetime-repair-editor-canvas-resources.mjs`。
 
@@ -50,8 +131,8 @@
 
 - 现象：画布资产之间已有橙色精确引用线，但依赖任务之间没有灰色 task flow；测试用 `design-foundation` 之类字符串时正常，真实生成返回 `task-1` 后失败。
 - 原因：`GameCreationAppAssetSource.taskId` 保存的是 External Editor 生成任务身份，命名空间与本地 `.agent/manifest.json` 的 Agent/task 身份不同；前端用 `taskById.get(source.taskId)` 会让真实画布资产全部失去 producer。
-- 处理：资源依赖图的 Tauri Rust read model 从有界 `.agent/agent.db` 读取 `agent.runtime.canvas.asset_generate`，以 `assetId -> agentId` 映射 producer，并要求 `agentId` 存在于当前 manifest。记录缺失、多个不同有效 Agent 冲突或读取已截断时失败关闭该资产的 task flow，不回退 `source.taskId`。精确 `asset-reference` 仍只依赖 manifest 中外部 resourceId 的唯一匹配。
-- 验证：Rust fixture 把 `source.taskId` 固定为 `task-1 / task-2`，只有审计提供 `art-director / design-foundation` 后才生成 task flow；移除审计后橙色引用保留、灰色任务流消失。AppSurface 使用相同生产数据形状回归。
+- 处理：资源依赖图的 Tauri Rust read model 从有界 `.agent/agent.db` 读取 `agent.runtime.canvas.asset_generate`，以 `assetId -> agentId` 映射 producer，并要求 `agentId` 存在于当前 manifest。记录缺失、多个不同有效 Agent 冲突或读取已截断时失败关闭 producer assignment、task flow 与对应 `cyclicTaskIds`，不回退 `source.taskId`。精确 `asset-reference` 仍只依赖 manifest 中外部 resourceId 的唯一匹配；Rust 独立返回的 `dependencyDepths` 继续作为 manifest / reference read model 权威结果，前端只过滤未知资源、负数、非整数和非安全整数，不得因 producer 截断把它整体清空。
+- 验证：Rust fixture 把 `source.taskId` 固定为 `task-1 / task-2`，只有审计提供 `art-director / design-foundation` 后才生成 task flow；移除或截断审计后橙色引用保留、灰色任务流消失，合法深度仍为 `asset:spec=0 / asset:ui=1`。AppSurface 使用截断生产数据形状证明深度 `0 / 1 / 2` 真实到达卡片布局，并且不会把已有自动坐标持久化成扁平布局。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/project/resource_dependency_graph.rs`、`apps/ai-game-creator-shell/src/view/project-development/resourceDependencyGraphModel.ts`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。
 
 ## 依赖图未就绪时不能先初始化资源布局
@@ -365,10 +446,18 @@
 
 - 现象：产品要求画板 `生成角色动作` 返回后按透明序列帧播放和下载，但旧实现或旧测试可能继续把结果当作预览视频处理。
 - 原因：后端仍需要先生成 `previewVideoPath` 再抽帧、绿幕去背和落 OSS；如果前端把预览视频当主媒体，就会绕过已经扣绿幕的 PNG 帧，也无法按序列帧打包下载。
-- 处理：角色动作结果图层主 `src` 使用 `frames[0].imageSrc`，`mediaType` 固定为 `image-sequence`，`assetKind` 固定为 `character-animation`，完整帧列表写入 `imageSequenceFrames`，`previewVideoPath` 只作为来源信息保留。单图层下载必须生成序列帧 ZIP；画布素材 ZIP 中角色动作写入 `sequences/<编号-标题>/frames/`。不得移除后端原有视频生成、抽帧、绿幕去背和帧落盘流程。
-- 验证：`ImageCanvasGenerationLayerModel` 应断言动作结果 `src` 为首帧且 `mediaType="image-sequence"`；画布集成测试应出现 `画布序列帧：角色动作` 图片播放器，不应出现角色动作 `<video>`；导出测试应断言角色动作下载和画布素材导出都包含序列帧 ZIP / frames 目录。
+- 处理：角色动作结果图层主 `src` 使用 `frames[0].imageSrc`，`mediaType` 固定为 `image-sequence`，`assetKind` 固定为 `character-animation`，完整帧列表写入 `imageSequenceFrames`，`previewVideoPath` 只作为来源信息保留。生成端确认每帧对象后必须把该帧 `objectKey` 与 `assetObjectId` 一起写入正式 payload 和 `generation_inputs_json.characterAnimation.frames`。单图层下载必须生成序列帧 ZIP；画布素材 ZIP 中角色动作写入 `sequences/<编号-标题>/frames/`。不得移除后端原有视频生成、抽帧、绿幕去背和帧落盘流程。
+- 验证：`ImageCanvasGenerationLayerModel` 应断言动作结果 `src` 为首帧且 `mediaType="image-sequence"`；画布集成测试应出现 `画布序列帧：角色动作` 图片播放器，不应出现角色动作 `<video>`；导出测试应断言角色动作下载和画布素材导出都包含序列帧 ZIP / frames 目录；生成测试还应断言首帧与非首帧的稳定引用都被保留。
 - 关联：`src/components/image-editor/ImageCanvasGenerationLayerModel.ts`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasExportModel.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
 
+## OSS 导出兜底必须覆盖响应体读取阶段
+
+- 现象：浏览器控制台显示 OSS `206 Partial Content` 后紧跟 `net::ERR_FAILED`，画布预览或素材导出失败，但没有出现预期的 `/api/assets/read-bytes` 兜底请求。
+- 原因：`fetch(signedUrl)` 可能先返回一个 `ok` 的 `Response`，网络、浏览器 Range 缓存或传输错误随后才在 `arrayBuffer()` / `blob()` 消费响应体时暴露；如果直连保护边界只包住 `fetch` 和状态码，响应体失败会绕过 fallback。
+- 处理：私有素材字节读取必须在直连 OSS 分支内完整消费响应体并重新构造可重复读取的 `Response`；换签、请求、非成功状态或响应体读取任一阶段失败时统一回退同源 `/api/assets/read-bytes`。Abort 仍应直接上抛，不能转化为额外服务器读取。
+- 验证：前端服务测试模拟 OSS 返回 `206/ok`、但 `blob()` reject，断言随后请求 `/api/assets/read-bytes` 并返回 fallback 完整字节；同时保留直连成功、局部分片、直连非成功、请求 reject 和 Abort 边界。
+- 关联：`src/services/assetReadUrlService.ts`、`src/services/assetReadUrlService.test.ts`、`src/components/image-editor/ImageCanvasExportModel.ts`。
+
 ## 图片画布序列帧播放不要复用普通图片淡入样式
 
 - 现象：角色动作序列帧播放时看起来像每帧之间在渐变或闪烁。
@@ -505,6 +594,22 @@
 - 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx -- --runInBand` 应覆盖裁扩先上传再创建项目资源，以及去背景队列完成后对未完成占位进行二次项目读取。
 - 关联：`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
 
+## 图片画布不能用 `local-*` 前缀代替资源登记状态
+
+- 现象：刚加入画布、资源登记仍在途的图层被复制后，权威项目快照刷新与资源创建响应交错，副本可能刷新后消失；反过来，历史自包含角色动作序列虽然也使用 `local-*`，却会被永久禁用并持续提示“素材仍在保存”。
+- 原因：`local-*` 同时覆盖两种不同状态：新素材的临时 ID，以及没有项目资源行、但已凭完整持久化帧成为终态的历史兼容序列。ID 前缀不是状态机；把所有本地 ID 当 pending，或把多个布局调用压进一个临时 ID single-flight Promise，都无法表达每次请求的真实生命周期与恢复上下文。
+- 处理：新素材是否 pending 必须读资源登记在途集合；存在明确在途请求时，复制、剪切、创建副本和内部粘贴整体拒绝，正式 `resourceId` 回填后开放。历史序列按结构化持久化的严格自包含谓词识别，不能显示保存中；暂不支持复制时用准确原因失败关闭。既非 pending 又不满足历史谓词的 unresolved local 图层也拒绝，但提示“资源尚未登记”而非“仍在保存”。不要把普通 layout PATCH pending 当资源登记状态，也不要阻止系统剪贴板图片导入。资源创建不再按临时 ID single-flight 合并；布局保存的串行 latest-wins 队列仍保留。
+- 验证：`ImageCanvasLayerCommandModel.test.ts`、`useImageCanvasLayerCommands.test.tsx` 和 `ImageCanvasContextMenusView.test.tsx` 分别覆盖登记在途整体拒绝、正式 ID 回填后恢复、历史 self-contained local sequence 不误报保存中，以及 unsupported / unresolved 的准确提示；`useImageCanvasProjectPersistence.test.tsx` 继续覆盖单个资源响应与权威快照交错恢复。
+- 关联：`src/components/image-editor/ImageCanvasLayerCommandModel.ts`、`src/components/image-editor/useImageCanvasLayerCommands.ts`、`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`docs/【编辑器】图片画布结构化持久化与迁移回滚方案-2026-07-19.md`。
+
+## 图片画布修改图层标签不能通过创建资源和换绑实现
+
+- 现象：用户只修改一个图层的素材类型，项目资源数量却增加且该图层的 `resourceId` 改变；如果修改请求完成前复制，原图层会换绑到新资源，副本仍引用旧资源，刷新后副本类型回退。
+- 原因：把资源 `assetKind` 同时当作共享默认值和布局实例标签，只能通过按类型查找 / 创建资源来模拟局部修改。异步响应只知道原 `layerId`，无法自动追踪期间复制出的新布局实例；layout 又没有独立覆盖字段，最终形成资源身份漂移和类型错位。
+- 处理：固定双层模型：`editor_project_resource.asset_kind` 是资源默认类型，`editor_canvas_layer.asset_kind_override` 是可空布局覆盖，effective 值为 `override ?? resource default`。图层标签动作只写 / 清除 override，保持资源行数量和 `resourceId` 不变；复制复用 `resourceId` 并复制 override。`asset_kind_override` 必须是追加在表末尾、默认 `None` 的 typed 字段，不能塞入 `item_json`；schema 同步 migration、表目录、bindings、DTO 和 canonical hash。
+- 验证：覆盖“修改标签不新增资源且不换 ID”“同资源两个图层可有不同 override”“复制保留 override 后可独立修改”“清除 override 恢复资源默认值”“刷新与 structured round-trip 不丢覆盖”，并运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、定向 Rust / API / 前端测试。
+- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-module/src/migration.rs`、`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`src/services/image-editor/editorProjectClient.ts`。
+
 ## 图片画布项目封面上传失败要有本地展示兜底
 
 - 现象：画布项目已反复打开、保存或操作，但 `/project` 列表卡片仍只显示“项目”占位，没有封面图。
@@ -3244,9 +3349,9 @@
 
 - 现象：release 上 api-server 周期性出现全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 业务超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），`/healthz` 仍 200，只有重启能恢复，过若干小时复发。
 - 原因：旧 `PooledConnectionLease` 只能显式 `release_connection` 归还；HTTP 请求方在等待 StDB 回包期间断开时 handler future 被取消，permit 自动归还但槽位 `in_use` 永不复位。后续 acquire 在拿到 permit 后进入无界 `loop + yield_now` 扫描空闲槽位，泄漏积累到 pool_size 后整池挂死。
-- 处理：租约持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop` 统一复位槽位/归还连接；槽位改 `AtomicBool` CAS 抢占，删除自旋循环（持有 permit 必然命中空闲槽位）。任何新的"显式归还"资源在 async 取消语义下都要先想 Drop 兜底。
+- 处理：租约持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop` 统一复位槽位/归还连接；槽位改 `AtomicBool` CAS 抢占，删除自旋循环（持有 permit 必然命中空闲槽位）。任何新的"显式归还"资源在 async 取消语义下都要先想 Drop 兜底。该保证只覆盖本地 lease / slot / permit 回收；RPC 已发出后，handler timeout/drop 不会取消或回滚远端 procedure，结果仍须按 unknown 读取权威事实。
 - 验证：`cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（`dropped_lease_releases_slot_and_permit`、`acquire_times_out_at_pool_acquire_when_pool_is_busy`）。
-- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md`。
+- 关联：`server-rs/crates/spacetime-client/src/active.rs`、`docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md`。
 
 ## 后台灰度配置不能从 SpacetimeDB 本地表缓存读取
 
@@ -3805,6 +3910,7 @@
 - Provider action 安全持久化补充：pending / provider action 的泄密检测不能因裸自然语言短语 `api key` 直接拒绝，否则 `agent.delegate` 中“不要暴露 External Editor API Key”等安全约束会被误报并阻断首批协作。赋值形式只允许完整匹配受控的“未配置 / 不可用 / 禁止读取”等状态或固定无密钥降级说明，不能用 `starts_with` 放行 `none-but-secret`、`not configured; actual value ...` 等安全前缀后的凭据；`**API Key**:`、`` `API Key`: ``、`API Key（生产）:` 等装饰或限定标签也必须识别为赋值。结构化字段标记 `apiKey / api_key`、`Authorization / Cookie`、`token / Bearer` 以及已知 secret token 形状仍必须检测并失败关闭。
 - Windows retry 扫描补充：`Path::strip_prefix(root)` 在 Windows 上得到的相对 `Path` 转字符串后使用反斜杠，不能直接传给只接受 portable `/` 的 Runtime JSON sidecar 读取器；否则 Runner 重启或显式 `--agent-resume` 扫描已到期 retry 时会报“项目文件路径不能包含反斜杠”，任务持续停在 `waiting-for-provider-retry`。目录扫描应按路径组件重组成 `/` 分隔的 UTF-8 相对路径，不要放宽全局路径校验。
 - 恢复交互：`needs-reconciliation` 即使没有 `pendingToolAction`，也必须提供显式“已核对，结束旧任务”；它只取消旧 run，不直接 retry。若取消后仍有 pending task，由 Runner 自动继续；只有队列为空且旧 run 已取消时，才允许创建新的 retry run，避免重复执行同一用户输入。自主构建 Supervisor 的 retry 不能改写为普通 `agent-background-task` source，必须从已验证的原 Run Profile 绑定恢复 `project-supervisor-gui / project-supervisor-cli` 可信来源；不得只信可追加的 task journal。
+- Steer source：前端选择可 steer Runtime 时不能只比较 Agent、Session 和 Run Profile，还必须在调用方声明 source 时精确比较持久 `source`。例如 game-chat 只能 steer `project-supervisor-game-chat`，不能把同 Session/Profile 的 `project-supervisor-cli` run 当成目标；source 不一致时应按当前入口新建或排队自己的 run，不能先调用后端再把“steer source 与当前 Run 不一致”暴露给用户。
 - 验证：前端回归同时覆盖零历史、无 Session 的初始空态、无 active Session 索引但存在持久 `needs-reconciliation` 总控 Runtime 的恢复展示，以及“先取消、队列为空后才重试”；真实 Windows 运行全部 tool-plan handoff 测试，确保相对句柄 rename、覆盖安装、回读和清理均通过。Responses 回归覆盖 system / user / assistant 文本分别序列化，并保留 user `input_text + input_image`；Runtime 回归覆盖“无效计划 → repair transport 等待 → steer → 新 cursor 再修复”，断言 cursor `0 / 1` 各有一条审计且不冲突。
 
 ## 固定画布产物返工不能变成任意覆盖，design-foundation 不能越权修程序
@@ -3958,6 +4064,35 @@
 - 处理：灰度页只能以 `/admin/api/feature-gates` 为数据源，固定目标列表只登记现役功能；新增或退役业务 target 只修改固定目标注册，不得让通用页面依赖业务列表接口。旧 `creation-entry:*` 目标、接口和页面保持退役。
 - 验证：`adminRoutes` 必须包含 `gray-release`，admin-web TypeScript/ESLint/Vitest 不得排除灰度页；页面测试必须断言只请求 feature-gates，并继续覆盖现役固定 target、直接 Gate Key 保存与新 target 状态重置。
 - 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/app/adminRoutes.ts`、`server-rs/crates/api-server/src/modules/admin.rs`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。
+
+## 角色动作不能靠素材主图或通用生成输入恢复
+
+- 现象：角色动作在整画布导出时正常，但从素材库单项下载只得到第一帧 PNG，拖回画布也成为普通静态图片。
+- 原因：`editor_asset.image_src` 只指向首帧；若 worker 把完整帧集塞进 `generation_inputs_json`，素材 DTO、用户输入清洗或画布布局任一层丢字段，就会退化成 PNG。再增加一个 `mediaType` 只能掩盖结果字段没有落到正式资源的问题。
+- 处理：worker 只把完整帧集与图片序列毫秒时长写入 `editor_project_resource` / `editor_asset` 的 `image_sequence_frames_json`、`image_sequence_duration_ms`；数组位置是唯一帧序，不保存 `frameIndex`，帧数和 FPS 均按需派生。`assetKind=character-animation` 决定序列渲染。素材映射、单项下载和拖回画布只读取这两个正式字段，项目 resource 在保存 / 刷新后继续作为主真相；动作 layout 只保留资源引用和 placement，不再复制正式媒体结果。账号素材提交精选审核时，`editor_showcase_asset` 必须冻结复制相同字段，公开 read model 只返回正式字段。外部 helper 只调用一次动作生成接口并直接使用响应 `resource` / `asset`。
+- 画布回填：角色动作会形成“原角色资源 → 预览视频资源 → 最终序列资源”的血缘链。生成响应必须返回已经持久化的最终 resource，前端图层直接使用其 `resourceId`；不能继续构造 `local-resource-character-animation-*`，否则 `appendCanvasLayersWithResources` 会再次创建重复资源。新图层的 `sourceResourceId` 同时使用最终 resource 的直接来源（预览视频 resource），不能继续沿用请求中的原角色 resource；否则结构化保存会在已生成并计费后因血缘不一致而拒绝。修复时只替换资源关联与血缘字段，不要顺带把动作图层显示尺寸从生成占位尺寸改成原始帧分辨率。
+- 历史处理：不要再在 read mapper 增加 `generationInputs` / layout fallback。使用 migration operator procedure 按 `asset → project-resource → showcase → canvas` 迁移；只有动作身份已由 `assetKind`、正式字段、嵌套 `characterAnimation` 或权威对象证明后，才解释顶层 `frames/durationSeconds`，否则会把无关任意 JSON 误分类。同一 task 可能同时存在误标为动作的预览 MP4 和最终首帧 PNG，候选查找必须先按权威对象类型做计划态分类，排除视频并要求唯一正式图片序列，不能按原始 `assetKind` 计数。账号素材仍有旧帧、但后来拖入画布的 project-resource 只剩清洗后 `fields/references` 时，project-resource dry-run 必须按同 owner / task / 首帧对象精确消费 asset 计划态结果；apply 仍要求前置 asset scope 已物理完成。canvas 判断已有 resource 是否为动作时也必须消费 project-resource 的计划态类型：旧库误标为动作、但权威对象证明为 preview MP4 且 layout 本身是 video 的图层直接跳过动作清理；layout 明确为 `image-sequence` 却指向该视频时继续形成 blocker，资源规划本身有 blocker 时也不得静默跳过。正式序列还要逐帧用稳定对象路径匹配同 owner / task 的已登记图片对象并补齐 `objectKey/assetObjectId`。迁移不得验证 layout 复制的 `sourceResourceId`：历史 layer 可能仍指向原角色，而最终素材已指向预览资源；清理副本后采用最终素材的 DB 血缘即可，新生成链路仍保持严格校验。正式与旧版结果冲突、候选为零或多个均形成 blocker；脚本诊断应直接打印 scope、ID、原因、owner/project/task、对象身份和来源资源，不能只报 blocker ID。普通 layer 顶层 `mediaType` 在迁移和响应清洗时删除，但嵌套生成参考的 `mediaType` 保留。
+- 新写入与验证：动作 `generationInputs` 出现 `characterAnimation/frames/previewVideoPath/frameCount/fps/durationSeconds/screenColorHex`，或正式帧出现 `frameIndex`，HTTP 与 storage 双层拒绝；其它 asset kind 的任意 JSON 不受该动作门禁影响。测试覆盖两种历史 JSON、无关顶层同名字段、正式/旧版相等与冲突、可选帧引用合并、screen color 和 frameIndex 清理、预览 MP4 重分类、幂等、blocker/hash apply、画布 placement 清理/资源补建、正式字段缺失失败关闭和 helper 单请求。
+
+## 图片序列时长不要复用通用媒体秒数
+
+- 现象：把角色动作、视频、音频和上传媒体都写进通用 `duration_seconds`，随后又尝试用持久化 `frame_count/fps/duration_seconds` 互相校验，造成取整口径、生成参数和实际播放时长彼此污染。
+- 原因：角色动作需要的是一组图片完整播放一次的精确时长；视频 / 音频的 `durationSeconds` 是生成请求或临时运行态参数。帧数已经由数组长度唯一确定，FPS 也可按需要推导，无需维护三份可冲突真相。
+- 处理：资源 / 素材只保存 `image_sequence_frames_json` 与 `image_sequence_duration_ms`，精选审核快照只冻结复制这两个正式字段。角色动作要求至少两帧且毫秒时长大于 0；播放器按 `时长毫秒 / 数组长度` 计算间隔，Spine 导出时再换算秒数并推导 FPS。音频 / 视频 `durationSeconds` 不映射到这两个字段。
+- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasExportModel.ts`。
+
+## 精选角色动作显示首帧还要检查前端 renderer 与逐帧授权
+
+- 现象：精选接口已经返回 `imageSequenceFrames` 和正确的 5 / 6 秒成本，但创作主页或后台审核仍只显示首帧；接入播放器后又可能只有第一帧成功、后续帧换签返回 404。
+- 原因：快照字段、展示 renderer 和私有对象授权是三道独立边界。公开 `imageSrc/objectKey` 只代表首帧，不能让前端自动获得完整帧集；顶层精选 exact grant 也不会自动覆盖其它帧对象。
+- 处理：公开精选模型必须把 `assetKind=character-animation` 映射到序列 renderer，并携带完整帧与毫秒时长；后台素材查询和精选审核共同透传同一字段并复用 `AdminEditorAssetMedia`。生成端不能在 `ProcessedEditorCharacterAnimationFrame → EditorCharacterAnimationFramePayload` 收口时丢弃逐帧 `assetObjectId/objectKey`，正式序列 JSON 必须保留已确认对象的稳定引用。公开授权在 SpacetimeDB 同一事务快照中只按有效精选动作的同 owner 逐帧 `assetObjectId/objectKey` 匹配，不能放宽 generated 前缀。列表未交互时只读首帧，打开或激活动作预览后也只挂载当前帧和有界预读窗口，避免再次制造换签突发；单帧换签或解码失败时跳过该帧、暂停全帧失败的序列并提供显式重试，不能长期显示空白或旧帧。卡片 hover 与 focus 分别跟踪，只要任一状态仍成立就继续播放，系统请求 `prefers-reduced-motion` 时卡片和弹窗默认暂停，用户仍可在弹窗中手动播放。
+- 验证：模型 / 组件测试覆盖 4 / 5 / 6 秒动作、损坏序列不回退 PNG、后台两页共用播放器和未激活列表不逐帧请求；SpacetimeDB 测试覆盖主对象、每帧对象、无关对象、跨 owner 与取消展示后的授权撤销。真实浏览器和端到端验收由人工单独执行，不把 unit / component 结果写成 E2E PASS。
+
+## 可复用资源回填必须保持时间戳单调
+
+- 现象：延迟重试携带比既有行更旧的调用方时间，回填图片序列字段时若无条件写入，会使 `updated_at` 倒退，导致基于时间戳的同步看不到更新或排序错误。
+- 处理：同源图片序列字段只允许 `None → Some`，非空冲突失败关闭；发生回填时 `updated_at = max(existing.updated_at, request_timestamp)`。legacy 音频 repair 不派生资源级图片序列或通用时长，重放继续精确匹配。
+
 ## 历史钱包消费不能从最近流水或通用订单快照推算
 
 - 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。
@@ -4056,6 +4191,14 @@
 - 验证：`external_editor_api.rs` 的 openapi 断言只校验 schema 形状，不校验兼容性，通过不等于契约安全；判定 breaking 与否以「删字段、移出 required、收窄类型、改语义、新增必填」为准。
 - 关联：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`、`docs/openapi/genarrative-external-v1.openapi.json`、`server-rs/crates/api-server/src/external_editor_api.rs`、`server-rs/crates/api-server/src/modules/external_api.rs`。
 
+## “继续”不能成为新游戏主题或触发首版整文件覆盖（2026-08-03）
+
+- 现象：原根 run 已经写出并验证目标玩法，但父 Runtime 因预算、上下文或 Provider 失败；用户在同一项目输入“继续”后，页面标题变成“继续”，玩法被默认收集/点击模板替换，美术规范总览图被直接铺进游戏画面。
+- 原因：终态失败 run 不能 steer，提交层因此创建 task 只有继续短语的新 root；每个新 autonomous 根合同又无条件 reset seed manifest；game-chat fallback 从当前 root task 取主题并直接 `file.write game/index.html`。同时快车道把 `icon-spec` 误当运行素材，要求整图背景和象限裁剪实体。通用 smoke/generic playtest 只验证结构与最小交互，无法发现玩法目标已经漂移。
+- 处理：严格继续意图必须在同一 Supervisor Session、同一持久 source 内继承最近失败根 run 的原始目标和 baseline，但保持新的 run/Provider/sidecar 身份；纯继续词表只能有一个权威实现，中英文短语都走同一入口，真正新需求仍独立 reset。非占位入口禁止 fallback 整体覆盖，也不能反复运行只读 smoke；当前 `code-prototype` 必须先读取并实际 patch，取得本人 mutation 后才能验证和交付。占位 fallback 只支持具备真实语义的显式模板，俄罗斯方块必须实际实现棋盘、下落、旋转、锁定和消行，未知玩法失败关闭。`art-spec.png` 只作规范参考，核心运行时位图必须来自独立派生的透明 `art-spritesheet.png` 及其 `iconImageSrcs` 本地切片；切片清单绑定当前图集 resourceId，Canvas 分别使用玩家、目标、场景和反馈四类素材。不得猜测图集是 2×2 等分、把规范板塞进画面或以纯代码核心实体绕过派生素材。
+- 验证：覆盖失败根任务“水晶俄罗斯方块”后输入“继续”、连续 successor、跨 Session、跨 source、正常完成后新输入、带具体新需求、既有非占位入口先 patch 后 smoke、初始化占位的俄罗斯方块真实语义、未知玩法失败关闭、纯继续目标缺失、规范图不在运行 DOM/Canvas、真实动作前后 `sequence` 与 RAF 空转。浏览器验收必须同时比较 baseline 玩法关键文本/控件/状态和当前 revision，不能只看 Canvas 非空与三个固定按钮。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_driver/game_chat_fast_path.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/provider_request_builders.rs`。
+
 ## Tauri beforeDevCommand 失败不等于已启动客户端会自动退出（2026-08-03）
 
 - 现象：旧 worktree 的 AGC Vite 长期占用 `127.0.0.1:3080`，marker 仍指向旧 API；新 worktree 启动 game-chat 后，配套后端在新端口 ready，随后 `beforeDevCommand` 因代理 target 不匹配返回非零，终端已经回到提示符，但原生客户端和它启动的 Runner 仍存活。客户端 WebView 实际加载旧 Vite，因此当前 master 的界面优化看起来全部缺失。
@@ -4072,14 +4215,16 @@
 - 处理：从当前 root source 的 seed lane 动态解析全部零依赖首波任务，只对这些 child 容忍 hydration `Pending`，后续 code prototype / preview 仍严格要求 Running/Completed。`streaming / ready` 仍要求当前 revision，`committed` 回复改为依据 finalization 的稳定身份查询，不随后续项目 revision 失效。
 - 验证：覆盖 `design-director / art-director / code-director` 三个 Pending 首波 child 均可投影 Completed、`code-prototype` Pending 仍被拒绝；非流式专业 Agent 在 finalization 前无 stream，提交后形成 committed stream，再推进项目 revision 后仍可查询且正文不变。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/response_stream.rs`。
+
 ## 异步生成结果未知时不能换幂等键重提（2026-07-31）
 
 - 现象：生成提交发生客户端超时、连接中断或响应丢失后，调用方创建新的 `Idempotency-Key` 再提交一次；原任务其实已经入队，最终造成重复生成、重复扣费和重复画布 / 素材库写入。
 - 原因：把“客户端没有收到结果”误判为“服务端没有受理”，又没有持久保留逻辑请求的幂等键和服务端返回的 `operationId`。托管 MCP 若绕过 External REST router 直接调用 worker 或 SpacetimeDB，也会形成第二套去重与状态语义。
-- 处理：一次逻辑生成只分配一个稳定幂等键。桌面 Runtime 在 POST 前先把精确请求体、SHA-256 和幂等键原子写入私有生成账本并回读一致；收到 `202 + operationId` 后先把账本升级为 `accepted` 再轮询。重启时 `accepted` 只恢复 GET，`prepared`、响应丢失、`202` 缺 operationId、轮询超时和状态损坏都进入 `needs-reconciliation`，绝不自动 POST。game-chat 五分钟硬截止可以结束本轮、关闭预览和客户端，但 executing 的 `canvas.asset_generate` 必须保留 pending action、provider batch 与生成账本；旧 `200` 图集的 `spritesheetResource` 允许为空，此时只在顶层 `spritesheetImageSrc` 是有效下载引用时优先使用，否则回退可用 `objectKey`。`postprocess-failed-source-preserved` 进入不可自动重生的对账边界；其它 non-blocking warning 继续消费成功结果并单独展示。旧 `200` 兼容不改变权威 External v1 的异步契约。MCP 生成工具必须把 `idempotencyKey` 映射到同一 REST header，并复用同一 External router、owner 和任务账本。
+- 处理：一次逻辑生成只分配一个稳定幂等键。桌面 Runtime 在 POST 前先把 endpoint、精确请求体字节、SHA-256 和幂等键原子写入私有生成账本并回读一致；收到 `202 + operationId` 后先把账本升级为 `accepted` 再轮询。`accepted` 只恢复 GET；`prepared` 或提交响应丢失时，只允许校验账本身份、配置指纹和请求 SHA 后，以账本保存的原 endpoint、原始正文与同一键恢复同一逻辑 POST，不得重建画布上下文、重组正文或换键。恢复 `202` 后继续 GET，恢复再次 transport 失败仍保留原账本；轮询超时只保留既有 operation 并恢复 GET。game-chat 的 4500 秒硬截止可以结束本轮、关闭预览和客户端，但 executing 的 `canvas.asset_generate` 必须保留 pending action、provider batch 与生成账本；旧 `200` 图集的 `spritesheetResource` 允许为空，此时只在顶层 `spritesheetImageSrc` 是有效下载引用时优先使用，否则回退可用 `objectKey`。`202` 缺 operationId、状态损坏与 `postprocess-failed-source-preserved` 仍进入对账边界；其它 non-blocking warning 继续消费成功结果并单独展示。旧 `200` 兼容不改变权威 External v1 的异步契约。MCP 生成工具必须把 `idempotencyKey` 映射到同一 REST header，并复用同一 External router、owner 和任务账本。这是 External v1 的专用幂等恢复，不是通用副作用自动重放。
 - 补充：不能把“accepted 分支里没有生成 POST”误当成 GET-only 恢复。若读取账本前仍重做项目/素材目录准备、输出路径预检或请求正文构造，恢复仍可能创建远端资源或在查询 operation 前失败。恢复必须直接使用 durable snapshot；清理必须最后删除 pending 身份锚点，活动 orphan 不得自动删除。完整恢复 future 还要在默认 Tokio worker 栈下验证，不能靠测试环境调大 `RUST_MIN_STACK` 掩盖栈溢出。
-- 加固：durable snapshot 必须绑定不含明文凭据的 base URL/API Key 配置指纹，配置漂移时连 GET 也必须阻断。accepted operation 明确 failed 也不能在 observation 持久化前删账本。旧 `200` durable result 只保留允许字段与安全 objectKey/相对路径，签名 URL、query/fragment 和未知字段不落盘。提交只有契约明确的 `400 / 401 / 403` 可证明未入队并清理 prepared 账本；超时、冲突、限流、网关错误及其它意外状态均保留账本进入对账。账本根目录、扫描和删除必须通过受控路径解析逐级拒绝符号链接，不能让项目内链接把清理目标指向项目外。
-- 验证：覆盖“服务端已入队但提交响应丢失”后原键重试仍返回同一 operation、换 owner 不可见、查询最终只出现一份 completed result 和一次计费 / 写回；MCP 与 REST 对同一 owner、同一请求和同一键必须命中同一 operation。
+- 加固：durable snapshot 必须绑定不含明文凭据的 base URL/API Key 配置指纹，配置漂移时恢复 POST 和 GET 都必须阻断。accepted operation 明确 failed 也不能在 observation 持久化前删账本。旧 `200` durable result 只保留允许字段与安全 objectKey/相对路径，签名 URL、query/fragment 和未知字段不落盘。只有首次提交直接返回契约明确的 `400 / 401 / 403` 才可证明未入队并清理 prepared 账本；首次结果已经未知后，恢复请求的临时鉴权错误、超时、冲突、限流、网关错误及其它意外状态均保留同一账本。账本根目录、扫描和删除必须通过受控路径解析逐级拒绝符号链接，不能让项目内链接把清理目标指向项目外。
+- 代理 DNS：Clash 等透明代理可能把公网对象存储域名解析到 RFC 2544 的 `198.18.0.0/15` fake-IP。下载器只对已通过鉴权 `objectKey` 或受控 legacy path 换签得到的 URL 接受“全部地址均位于该 benchmark 段”的窄例外；直接 URL、其它本机/私网地址、公私混合解析和重定向仍必须失败关闭，不能为了兼容代理整体移除 SSRF 校验。
+- 验证：覆盖“服务端已入队但提交响应丢失”后两次 POST 的 endpoint、正文 bytes 与 `Idempotency-Key` 完全相同，原键重试仍返回同一 operation，最终只出现一份 completed result 和一次计费 / 写回；恢复再次 transport 失败或临时鉴权失败仍保留同一账本；换 owner 不可见；MCP 与 REST 对同一 owner、同一请求和同一键必须命中同一 operation。
 - 关联：`server-rs/crates/api-server/src/external_generation.rs`、`server-rs/crates/api-server/src/external_mcp.rs`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
 
 ## api-server 嵌入仓库外资源时必须同步容器构建上下文（2026-07-31）
@@ -4130,3 +4275,121 @@
 - 处理：测试 HTTP reader 继续保留单次 socket 超时，并在明确的总 deadline 内重试 `WouldBlock / TimedOut`；超过总 deadline 或出现其它 I/O 错误仍失败关闭。不能移除超时或无限重试，否则真正的请求缺失会把 CI 挂死。
 - 验证：定向复跑 `recovery_scan_resumes_accepted_generation_on_default_worker_stack`，并在 `--test-threads=1` 的完整 AI 游戏壳 suite 中确认生成恢复、下载和账本清理全部通过。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs`。
+
+## 下游 manifest 回调测试不能冒充实时数据源（2026-08-05）
+
+- 现象：工作台的资源、任务与版本重投影单测保持绿色，但后台 Agent 已更新 `.agent/manifest.json` 后，打开中的工作台仍长期显示旧快照，只有重开项目才更新。
+- 原因：测试 Supervisor 直接调用 `onManifestChange`，只证明 `App manifest -> WorkspaceLauncher -> ProjectDevelopmentView` 的下游桥接；真实 Runtime event 没有失效字段，监听器也没有重读 manifest。External Runner 又与 GUI 分属不同进程，Runner 内无法使用 GUI `AppHandle`，只补普通 Tauri event 仍不能形成生产链路。
+- 处理：后台 manifest mutation 收敛到共用 Runtime emitter；GUI 内进程用带 `manifestInvalidated` 的 Runtime update，External Runner 通过 GUI owner attach 登记的受令牌保护 loopback sink 转发专用失效事件。App 对当前项目做 single-flight manifest 重读，并以 mounted、项目路径和 scope version 丢弃迟到结果；WorkspaceLauncher 继续只消费完整 manifest 快照，不新增平行状态或轮询。
+- 验证：集成测试必须渲染真实 `App + WorkspaceLauncher`、捕获真实 Tauri listener，让 `get_local_game_manifest` 从旧快照切换到新快照，并由非 Supervisor Agent 事件驱动资产、completed 任务、运行入口和版本卡出现；另测项目切换时旧请求迟到。旧的直接 `onManifestChange` 测试只能标记为下游桥接证据。
+
+## React 资源详情焦点不能依赖重建对象身份（2026-08-05）
+
+- 现象：音频 / 视频播放器、文档链接或收起按钮正在获得焦点时，后台 manifest 更新会把焦点突然移回详情 region；若当前资源被删除，详情虽然消失，stale focused ID 和焦点可能残留到 `body`。
+- 原因：资源投影每次生成新对象，`useLayoutEffect([focusedResource])` 把同一资源的内容更新误判为重新进入详情；删除路径没有显式恢复状态和可聚焦 fallback，项目 / 运行视图切换也可能沿用旧 trigger。
+- 处理：焦点状态机只比较稳定 `resourceId`：`null -> id` 与 `idA -> idB` 聚焦详情，`idA -> idA` 保持当前 active element。显式收起 / Escape 才恢复原卡片与滚动；后台删除清理 focused / matching selected ID 并聚焦搜索框；项目或运行视图切换清空 trigger / restore。媒体预览副作用依赖稳定 ID、路径和类别，不因同 ID 对象重建先卸载控件。
+- 验证：媒体控件获得焦点后用同 ID 新 manifest 重渲染并断言 active element 不变；删除资源后断言详情关闭、选中清理且搜索框获得焦点；既有收起、Escape、项目切换和运行切换测试继续通过。
+
+## 不要用自然语言精确 `.replace()` 维护 Runtime Prompt
+
+- 现象：Prompt 文案稍作改写、增删空格或调整段落后，替换静默失效，代码中出现难以审阅的链式 `.replace()`。
+- 原因：把自然语言全文同时当内容和结构锚点，没有稳定 section 身份。
+- 处理：稳定片段拆为版本化 Bundle section，由 Rust 显式按角色、平台和配置组合；`agent_runtime_native_executable_tools()` 是原生可执行工具的权威源列表，同时供 Prompt 工具目录与 native capability registry 使用，`mcp.call` 只服从当前请求的动态 MCP catalog。最终 Provider 请求构建器同样必须使用显式 section 与条件组合，不能以后置自然语言精确 `.replace()` 注入工具合同、平台规则或角色规则。安全规则保留在代码中。
+- 验证：manifest 覆盖所有嵌入资源、版本一致、源列表中的原生工具全部进入 Prompt 与 native capability registry、`mcp.call` 不进入静态目录、Supervisor section 顺序和关键角色合同保持不变，并扫描 `prompt.rs` 与最终 Provider 请求构建器不再出现自然语言链式 `.replace()`；对最终 Provider 请求直接断言各角色、平台和配置分支的合同内容。
+
+## 动态 MCP 函数参数不能只依赖 Provider schema
+
+- 现象：动态 MCP 函数虽然带 catalog `inputSchema`，Runtime 却只检查 `arguments.input` 是 object；非 strict 或兼容 Provider 可以返回缺 required、类型错误、enum 外值或 schema 外隐藏字段，并把它们原样送到外部工具。
+- 风险：Provider 工具约束不是本地安全边界；特别是 `writes + readOnlyHint=true` 自动放行的工具，schema 外字段可能改变外部副作用而不进入预期确认路径。
+- 处理：使用完整 JSON Schema validator 校验原始 catalog schema，不手写 required/type 子集；native parser、fingerprint enrichment 与实际 MCP 调用边界复用同一校验器。enrichment 错误必须映射回 classified `arguments-schema` repair，不能以普通字符串直接终止 run；执行点重验用于阻断升级前已经落盘的 schema 外 pending。关闭网络和文件 `$ref` 解析，schema 无法安全编译时不广告或不执行。`serde` 类型错误会包含实际字符串值，catalog miss 也会包含模型提交的 server/tool，因此这两类错误同样只能返回稳定类别，不能拼接原始错误、参数值或 schema 内容。
+- 验证：覆盖 required、additionalProperties、type、enum、本地 `$defs/$ref`、HTTP/file 外部引用、无效 schema、错误脱敏，证明 legacy wrapper 在注入 fingerprint 前进入 repair，并证明带旧有效 fingerprint 的历史 pending 在实际调用前仍被 schema 拒绝。
+
+## 2026-08-05 不要把 static smoke 当作完整专业交付
+
+- 现象：code-prototype 已通过 `game.static_smoke`，但完成门明确报告 `missing-visible-art-slice-use`；随后每轮 thinking summary 都是“已取得验证证据”，没有新 action，最终 loop-budget-exhausted。
+- 根因：game-chat 快车道只看 verification gate 就返回确定性交付，完整 autonomous completion blocker 直到空 action 的最终收束阶段才被发现；Provider 因而永远拿不到下一轮修复机会。失败的 `file.patch` 也会因验证凭证保守失效而推进 revision，若快车道只比较 `mutationRevision`，会把“文件未修改”误认成本 Run 已修改。已有未完成计划收到 steer 后若再追加一整套新步骤，还会与 retained completed 步骤合并成超过 8 步，随后稳定重复 `runtime.plan_update blocked`。
+- 处理：确定性交付与自动 plan completion 都必须先通过完整 completion gate，并要求当前 Run 最后一条同 mutation 工具调用与 Agent DB 中严格绑定当前身份的 `status=ok` receipt 一致；pending action 的 steer cursor fingerprint 也必须一致，失败 patch 或旧 Run receipt 不能取得交付资格。新 blocker 不回退旧 completed 步骤：已有非终态步骤时用明确 repair step 替换首个非终态步骤，其余保持 pending；只有全 completed 且仍有容量时才追加。8 步已满时进入外部 repair lane；计划已有 failed 步骤时立即失败关闭。回归同时覆盖失败 patch、跨 Run receipt、非零 steer cursor、8 个 completed 与 blocker，以及 failed plan 在 ownership/blocker 不同组合下都不会继续空转。
+
+## 2026-08-05 Runtime 时间戳必须验证 Date 范围并保持来源身份
+
+- 现象：极大但有限的持久时间值会让 `toISOString()` 抛 `RangeError`，或让界面显示 `Invalid Date`；实时回复又借用其它 Runtime 的最近活动时间，文字继续流入时仍显示几分钟前，缺失时还随前端定时器漂移。
+- 处理：秒/毫秒归一化后必须再检查 `Date#getTime()`；不可表示的值统一显示“时间未知”并省略 `datetime`。实时回复只使用 response stream 自己的 `updatedAt`，不能借父/子 Runtime 活动时间或 `Date.now()`。
+
+## 2026-08-05 Pending manifest 容错必须覆盖真实终态时序
+
+- 现象：手工把内存 state 改为 Completed 的测试通过，但真实 finalization 先写 durable Completed、再投影 manifest 时仍被 Pending 状态门拒绝；或 stale manifest 全 Completed 后，父 Run 忽略仍在运行的真实 child。
+- 根因：测试没有写 durable terminal record，Pending 容错只验证了非终态 journal；DAG 又把 manifest `completed=true` 放在 active child 之前。终态投影和收束前检查使用了不同事实时序。
+- 处理：测试必须按真实顺序分别写 durable Running 和 durable Completed。Pending 漂移只允许 state/journal 的 Running-Running 或 Completed-Completed 对；queued/waiting/failed/reconciliation 一律拒绝。active child 在无 Failed 时独立保持 DAG 活跃，项目 mutation gate 在写锁内核对当前 root，防止旧 child 污染新根 Run。
+
+## 2026-08-05 Canvas 可达性不能在扇入调用图中回退 visited
+
+- 现象：game-chat 的 code-director 长期显示 queued，Runner 单核持续高 CPU，durable cancel 也无法被事件循环处理；manifest 已提前显示 running，用户看起来像“稳定卡死”。
+- 根因：大 classic script 虽使用了 bounded direct-call graph，但 `javascript_named_function_is_reachable` 在递归返回时删除 visited，只阻止当前环，不记忆已经遍历的祖先。render/update 图的大量重复调用让同一节点指数重算；父完成门又在 code-prototype 未完成时提前深验四个 Canvas 切片，使第一次 wake 就同步阻塞，200 次外层重试预算完全没有机会推进。
+- 处理：单次可达性查询每个 function node 最多访问一次；全 `None` alias 历史直接返回，稳定外层初始化使用有调用前置证明的快路。父完成门只深验 Completed seed task，wake 预算耗尽写入 reconciliation。格子游戏的符号坐标只在唯一数值 `COLS / ROWS / CELL` 与画布范围能共同证明时接受，普通无界动态坐标继续拒绝。
+- 验证：永久 fixture 至少包含 48 层重复扇入调用、IIFE 外层素材初始化、格子常量绘制、无界坐标反例和整画布尺寸引用；真实项目的全部四个切片还要在同一轮秒级返回 true。禁止用延长 queued timeout、Tokio timeout 或 synthetic 小脚本通过来替代真实大脚本复验。
+
+## 2026-08-05 Canvas clamp 与 parent wake 不能走字符串或易失兜底
+
+- 现象：通用 game-chat fallback 明明把玩家坐标限制在当前 Canvas 内，完成门仍报 `missing-visible-art-slice-use`；反向放开任意动态坐标又会让离屏绘制或错误 Canvas 假通过。
+- 根因：Canvas owner 收紧后正确禁用了含尺寸成员的字符串兜底，但 AST 数值区间器尚不认识嵌套 `Math.min / Math.max` clamp。若只查源码包含 `canvas.width`，无法证明该 Canvas 创建了当前 context，也无法排除局部伪造 `Math`。
+- 处理：只在 semantic 证明未遮蔽全局 `Math`、上界读取当前 context 所属 Canvas、下界为 `0` 时生成有限区间；加入错误 Canvas、遮蔽 Math 和无界坐标负向回归。不要用字符串包含、变量名白名单或把未知动态值当 `0`。
+- 现象：parent wake 的 200 次瞬态预算耗尽后 Runtime 仍长期显示 running，或 lane 忙、取消、child 前进、manifest 损坏时 reconciliation 被静默丢弃或覆盖新状态。
+- 处理：预算耗尽错误必须向上传递；lane 忙先持久化 deferred signal，再在 lane + 项目锁内重检最新事实。结构损坏路径使用不依赖 manifest hydration 的专用 journal/state 写入，CAS 失败转为继续对账，绝不覆写并发取消或 DAG 进展。可解析的空对象/空 runId 仍是损坏身份，只有完整有效的新 Run 才能阻止旧 marker；event/audit 的同键记录必须完整比对并拒绝冲突或重复。旧 task 已终态、Runtime 非 waiting 或新 Run 接管时，deferred signal 必须写 resolved/superseded，不能留给后续 wake 永久重复 settle。
+- 测试注意：autonomous child fixture 先 linked Pending、后正式 Running；终态 runId 必须拒绝复用。判断 Completed-only 诊断时按每个 seed task 的实际状态分析，不能因为 `code-prototype` Pending 就忽略已经 Completed 的 `art-asset-plan` 深验。
+
+## macOS 安全路径测试必须使用规范化临时目录（2026-08-05）
+
+- 现象：调用仓库上下文、Runtime context bundle 或 pending recovery 的 Rust 测试在 macOS 报“Repository root and its ancestors must not be symbolic links”，Linux CI 却可能通过；本地 HTTP 恢复夹具在完整串行测试中还可能偶发 `WouldBlock`。
+- 原因：`tempfile::tempdir()` 默认返回 `/var/folders/...`，而 macOS 的 `/var` 是指向 `/private/var` 的符号链接，生产安全校验会按设计拒绝该祖先；恢复测试的服务端读超时若仅为 2 秒，也会与完整测试负载下约 2 秒的首次请求形成窄竞态。
+- 处理：凡测试会进入仓库可信路径校验，统一使用 `crate::tests::canonical_test_tempdir(...)`，不得削弱生产符号链接拒绝规则；loopback 夹具保留有界超时，但为完整 CI 负载留足稳定裕量。
+- 验证：在 macOS 上定向运行 provider request、pending recovery、autonomous continuation 与 generation recovery 用例，再运行完整 `npm run check:native-shells`。
+
+## Mach-O 文件头校验必须覆盖反字节序魔数（2026-08-05）
+
+- 现象：macOS arm64 的 Tauri release 已成功构建且 `file` 明确认定为 Mach-O，产物 staging 仍报“must be an executable Mach-O file”。
+- 原因：脚本用 `Buffer.readUInt32BE(0)` 读取文件头，却只比较 `0xfeedfacf` 等正序数值；arm64 常见头字节是 `cf fa ed fe`，读取结果为 `0xcffaedfe`。
+- 处理：文件头白名单同时覆盖 32/64 位与 fat Mach-O 的正序和反字节序合法魔数，并由桌面配置门禁同时反查 staging 脚本和根级产物检查，不能改成只按扩展名或构建退出码判断。
+- 验证：在 macOS 上构建真实 desktop-shell release，运行 `npm run desktop-shell:stage-release-binary`，再由 `npm run check:native-shells` 校验 staged 产物。
+
+## 托管 MCP 新增公开域名时不能只更新网关路由（2026-08-05）
+
+- 现象：`https://dev.genarrative.world/api/external/v1/mcp` 的 manifest、OpenAPI 和 Bearer 鉴权都正常，但鉴权后的 `initialize` 返回 `403 FORBIDDEN`；通过 SSH 隧道访问同一 api-server 的 loopback 地址却可以正常列出 tools/resources。
+- 原因：`rmcp` Streamable HTTP transport 自带 DNS rebinding 防护。公网网关已经接入 dev 域名，但 `external_mcp::service()` 的 `allowed_hosts` / `allowed_origins` 仍只登记正式域名和 localhost，因此请求在 MCP 协议处理前被 transport 拒绝。
+- 处理：新增公开 MCP 环境时，同批登记对应 Host 与 HTTPS Origin；不要通过客户端伪造 `Host`、关闭防护或改走内部 SpacetimeDB MCP 规避。allowlist 变更属于 api-server 发布内容，必须随正常 API release 部署到目标环境。
+- 验证：自动测试使用真实公开 Host/Origin 执行 `initialize`；部署后再从公网域名完成带 Key 的 `initialize`、`tools/list`、`resources/list`、Skill resource 读取和至少一个只读业务 tool 调用。loopback 成功只能证明 MCP 实现和 Key 可用，不能替代公网 Host 验收。
+- 关联：`server-rs/crates/api-server/src/external_mcp.rs`、`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。
+
+## 异步任务接受后的刷新回调不能统一套用 dialog 所有权（2026-08-05）
+
+- 现象：正式生成任务已被后端接受，用户随后删除 dialog 或切换项目，任务仍继续并可能扣费，但钱包和任务列表没有刷新；反向问题是账号切换时若 project ID 暂时相同，旧任务可能刷新新账号的任务列表。
+- 原因：把 dialog / canvas 的完整 UI 所有权同时用于账号级钱包和账号内项目级任务列表，或者任务列表只比较 project ID，没有校验账号。
+- 处理：按副作用分层校验。钱包只比较账号；任务列表比较账号加项目；dialog、canvas、asset 和 layer 写回继续比较账号、项目、scope version 与原 dialog。正式请求已接受后，删除 UI 状态不等于取消后端任务。
+- 验证：分别覆盖删除 dialog、同账号切项目、账号 A 切到账号 B 且 project ID 保持相同，以及原账号原项目原 dialog 仍有效的正常回写。
+
+## GUI owner 锁不能替代逐 boot 的事件接收端登记（2026-08-05）
+
+- 现象：GUI 首次启动后 manifest 事件转发正常，但 Runner 被替换为新 boot 后只剩 owner 锁和 endpoint 可用，后台更新不再到达 GUI；或者 attach 响应只确认 owner，客户端却误记当前 boot 已完整登记，后续 ensure 不再重试。
+- 原因：把 OS owner 生命周期约束与进程内事件 sink attachment 混成同一状态，或在 `ensure_external_agent_runner` 之外执行一次性 attach；测试若用 actionId 等无关字段代替真实 sink port/token，也无法证明新 boot 重放的是可用接收端。
+- 处理：GUI 按规范化 AppData 私有登记真实 sink port/token，`ensure_external_agent_runner` 的 endpoint 复用和新 Runner 就绪两条成功路径都按 `bootId` 重放。同 boot 成功后幂等，新 boot 必须重挂；RPC、`attached` 或 `eventSinkAttached` 任一失败或缺失都不得记录成功 boot，并允许同 boot 后续重试。不同 AppData 不共享登记，未登记 CLI 不触发 attach；sink token 不进入日志、错误或公共状态。
+- 验证：分别覆盖真实 port/token 跨 boot 原样重放、同 boot 幂等、新 boot 重挂、普通 attach 失败、`eventSinkAttached` 缺失与 false 后同 boot 重试、AppData 隔离和未登记 CLI 零副作用。
+
+## manifest relay 测试不能并行覆盖同一个全局 sink（2026-08-05）
+
+- 现象：crate 根 relay 测试在配置全局 sink 后阻塞等待 `TcpListener::accept()`，同时 Runner GUI owner attach 测试通过另一条路径覆盖并清空 sink；事件可能被发往另一端口，原 listener 随后永久等待。断言或 `expect` 提前失败时，成功路径末尾的手动 clear 也不会执行。
+- 原因：两个跨模块测试读写同一进程全局状态，却没有共用隔离边界；只给 accept 后取得的 stream 设置 read timeout 无法约束 accept 本身，payload 读取也缺少总 deadline。
+- 处理：全部全局 sink 测试共用一把 test-only 串行锁，并由 RAII guard 在 `Drop` 中无条件清空；测试统一使用 `manifest_invalidation_sink_isolation_` 前缀。relay fixture 对 accept 和 payload 分别使用非阻塞轮询与总 deadline，不使用固定 sleep；生产 loopback、token、连接 / 写入超时和 payload 大小校验保持不变。
+- 验证：用 `--test-threads=2` 重复运行统一 filter，覆盖正常 relay、无事件 accept 超时、不完整 payload 超时、panic 展开清理，以及 GUI owner attach 配置与 guard 清理。
+
+## 编辑器生成不能把传输重试、参考图截断和客户端 provenance 当成独立小问题（2026-08-05）
+
+- 现象：生成 POST 首次已经入队但响应丢失时，客户端自动重试产生第二个任务；第 6 张或更多参考图仍显示在 UI / 元数据里，却没有送给 provider；直接构造请求还能把任意资源 ID 写成最终素材引用。
+- 原因：客户端虽在重试中复用 `x-request-id`，队列入口却用随机 job id 生成 dedupe key；前端允许无限追加，api-server 和 provider 用 `.take(...)` 静默截断；`generationInputs.references` 被当成可信持久 provenance。
+- 处理：主站生成 POST 禁止自动重试，把显式复用的稳定 request id 接到队列唯一键并校验 replay payload；所有边界显式拒绝超限，前端还要预留主图槽位、统计在途上传，并在上传完成前拒绝模型切换、画布选图、提交生成、关联源图删除 / 剪切 / 素材删除和面板切换 / 关闭；reservation 必须绑定原面板上下文，批量部分失败时不能丢弃已经持久化的成功项。入队、完美像素及直接创建资源 / 素材时删除客户端 references，执行时按真实参考源和 owner 资源记录重建权威引用。历史任务比较必须兼容仅差已删除 references 的旧 payload，不能只保留旧 hash 却让 payload 比较误报冲突。
+- 验证：覆盖同键同 payload / 不同 payload、普通图片第 6 张、带主图的 GPT-image-2 第 5 张额外引用、provider 6 / 15 张边界、伪造引用删除和 owned 资源 / 素材重建。
+
+## 共享音频 Composer 架构冲突不能按单行选边（2026-08-06）
+
+- 现象：master 的音频 composer 同时承载 SFX 与 BGM，并在组件内定义 `isSoundEffect`；功能分支把 BGM 拆成独立组件后，原组件变成 SFX-only。合并时只把 master 的条件占位表达式带回 SFX-only 组件，没有带回变量定义，最终在测试渲染阶段报 `isSoundEffect is not defined`。
+- 原因：冲突两侧代表不同组件架构，逐行保留看似有用的 JSX 会把一个架构中的局部条件拼进另一个架构。import 排序、格式检查和只覆盖单一 mode 的测试都不能证明这种组合成立。
+- 处理：先确定权威组件边界，再按完整调用链解决冲突。图片画布音频入口当前决策是恢复一个共享 `ImageCanvasAudioGenerationComposerView`，由组件内 `isSoundEffect` 分流；BGM/SFX 的 validator、写回、锁和提交契约仍分别保持。不要只补一个常量后继续维持已经废弃的双 composer 边界。
+- 验证：同时渲染 `audio-sound-effect` 与 `audio-background-music`，覆盖两个 mode 的正向控件和互斥负向断言、dialog / mode 切换、BGM 稳定 ID 与 controller 缺失的失败关闭，并运行 `ImageCanvasGenerationComposerView.test.tsx` 与 typecheck。