合并主线并解决无限画布冲突

合并主线 Runtime、编辑器与 SpacetimeDB 最新改动
保留无限画布资源投影、布局与焦点恢复合同
统一共享画布历史和生成对话框类型
同步更新技术方案、项目记忆与回归测试

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

@@ -81,9 +81,19 @@ 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 输出、`design-director / art-director / art-asset-plan / code-director / code-prototype / preview-readiness / preview-playtest` 七个专业 Agent 的 durable `final-reply`，以及 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`。game-chat 必须配置可用的 External Editor API，按 `art-spec.png -> icon-spritesheet -> art-spritesheet.png + iconImageSrcs 本地切片 -> code-prototype Canvas 使用四类切片` 推进；缺少任一环节都必须失败关闭。
+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 素材完整快车道采用七任务口径。父 Run 与全部 child Run 共用 4200 秒软预算和 4500 秒累计硬上限；先确定性生成并登记 `art-spec.png`，再由 `art-asset-plan` 通过专用 icon-spritesheet 路由生成透明 `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、完整图集直绘、单个猜测裁切和路径诱饵均失败。对应定向测试至少包括：
+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。定向复验至少运行：
+
+提交前还要覆盖启动崩溃窗口：仅 `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 只允许显式支持的真实玩法模板，俄罗斯方块必须验证棋盘、下落、旋转、锁定和消行语义，未知玩法必须失败关闭。
 
@@ -654,7 +664,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

@@ -62,6 +62,77 @@
 - 验证：使用 deferred commit/layout Promise，依次在请求后切项目、切 run/overview、新开 session、改选择和改筛选；断言 manifest 只更新对应项目，新资源仍进入投影/布局，但所有失效守卫都不切中央状态、不改选择、不清查询。条件未变化且资源可见时才自动定位。
 - 关联：`docs/technical/【技术方案】客户端素材创作无限画布阶段一合同-2026-08-05.md`、`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`。
 
+## 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` 的系统别名误判为用户符号链接。
@@ -389,10 +460,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`。
+
 ## 图片画布序列帧播放不要复用普通图片淡入样式
 
 - 现象：角色动作序列帧播放时看起来像每帧之间在渐变或闪烁。
@@ -3284,9 +3363,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 本地表缓存读取
 
@@ -4207,6 +4286,38 @@
 - 处理：使用完整 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`。
@@ -4272,3 +4383,9 @@
 - 原因：把 Pointer 事件接线、宿主生命周期胶水和可复用 history 算法放在同一组件中，误以为没有复制整个画布目录就已经满足共享源码边界。
 - 处理：两宿主直接消费共享 `useCanvasHistory`；共享 snapshot 统一覆盖 viewport、selection、图层位置和 width/height，宿主只声明本地媒体是否允许安全移除/重做。Tauri 仍可保留 Pointer capture/epoch/host callback 接线，但选择、平移、缩放、变换、renderer 和 history 状态机不得在宿主重写。
 - 验证：主站 history 定向测试覆盖 resize undo/redo；Tauri 新建、导入、编辑、撤销重做和 durable commit 用例必须在同一共享 hook 下通过。
+## 编辑器生成不能把传输重试、参考图截断和客户端 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 资源 / 素材重建。