Merge branch 'master' into codex/dependency-graph

docs/project-memory/shared-memory/decision-log.md

@@ -5919,3 +5919,12 @@
 - Runtime 恢复确认：GUI 自动扫描 `agent.resume` 前必须先用只读方式判断是否存在可恢复任务或 durable recovery artifact；全新项目与已完全终态、无任何恢复工作的项目直接返回空结果，不弹出“恢复未完成 Runtime 任务”；一旦存在 task、retry、handoff、finalization、pending action 或 reconciliation 等可恢复工作，仍必须经过原 `agent.resume` policy 门禁，不得通过吞掉 policy error 绕过确认。
 - 每条输出入聊天：事件文件中的原始 `summary / detail` 仍是私有 Runtime 证据，不可由前端直接持久化。Rust 只对白名单用户进度生成 `publicText`，同时为每次真实追加生成 `eventId`；action 重放沿用 action 身份，普通事件使用进程、毫秒与单调序列组成唯一身份。前端把 `eventId + publicText` 和四阶段专业 Agent 的 durable final reply 作为独立 assistant 消息，按顶层 `messageId` 幂等写入项目 conversation；重载恢复、轮询与实时事件并发不得重复或漏掉当前已观察输出。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`、`docs/project-memory/shared-memory/development-workflow.md`。
+
+## 2026-08-03 game-chat 开发态前后端同源与快车道恢复
+
+- 启动决策：`npm run agc` 与 `npm run agc:game-chat` 统一先经外层 Node 启动器预检 `3080`。在 marker 尚不能证明 worktree 归属时，任何已占用的 3080 都不得复用，并必须在原生窗口创建前失败关闭；Tauri CLI 退出后必须收束已启动的客户端进程树，不允许终端已退出但窗口与 Runner 仍假在线。
+- 首波决策：普通 GUI / CLI 的正式 16 节点 DAG 与 game-chat 首版 lane 都只把 `design-director / art-director / code-director` 作为首波 ready Agent。正式 DAG 的 `design-foundation` 等待策划与美术 Director，`code-prototype` 等待程序 Director 及数值、美术、音频三条底层产物链；game-chat 则在三个 Director 全部完成后才启动 `code-prototype`，再串行执行静态检查和试玩。首波以外的非 repair 底层 Agent 只能由依赖就绪调度或上层明确返工合同按需激活。
+- Runtime 决策：game-chat 六任务 lane、平台美术、单轮收束和自动预览只由持久 `project-supervisor-game-chat` root source 启用。hydration 对 `Pending` 的容忍只适用于当前 source-aware lane 的三个零依赖首波任务，不再硬编码单个历史任务。页面进度、阶段记录和 final-reply 白名单统一使用六项任务与 `x/6`。
+- 显式协作合同：autonomous 的旧 `code-prototype + quality-review` 首批合同退出。显式 project collaboration policy 或持久 batch 恢复若进入首批 `agent.delegate` 路径，只允许且要求三个 Director 各一次；策划与程序 Director 是只读规划且 `expectedArtifacts=[]`，美术 Director 是非只读规范图任务且必须交付 `assets/art-spec.png`。任何非 repair 底层委派与 isolated child 都在首批失败关闭；默认 manifest DAG 仍是唯一自动首轮执行链，不额外复制三个 Director 委派。
+- 输出决策：保留未提交 `streaming / ready` 的当前 revision 门；已提交的专业 Agent final reply 继续使用既有 durable response-stream 身份，后续项目 revision 变化不再隐藏早期阶段回复。
+- 关联：`apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs`、`start-dev-stack.mjs`、`src-tauri/src/agent/runtime_protocol/autonomous_completion.rs`、`response_stream.rs`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`。

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

@@ -4022,3 +4022,19 @@
 - 处理：改外部 v1 响应前先确认 `external_api_key` 是否已有非内部账号的活跃密钥。仍无调用方时可按现行豁免直接改，但必须同步更新接入方案的「版本与兼容策略」；已有调用方时按该节规则择一处理（兼容值 / 弃用期 / 升 v2），只改 JSON 不构成合规变更。
 - 验证：`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`。
+
+## 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 的界面优化看起来全部缺失。
+- 原因：Tauri 的字符串 `beforeDevCommand` 默认 `wait=false`。只要固定 `devUrl` 上已有可访问页面，Tauri CLI 可以在配套启动脚本完成前创建原生窗口；旧实现又直接从 npm 启动 Tauri CLI，没有在 CLI leader 退出后继续持有其 PGID / Windows 进程树。`start-dev-stack.mjs` 虽会在后端 ready 后识别 marker/API 错配，但检查时机已经晚于窗口创建，且只清理自己登记的后端和 Vite。
+- 处理：`dev` 与 `game-chat` 统一先进入 `start-tauri-dev.mjs`，在启动 Tauri CLI 前无副作用检查 3080。现有 marker 只有 API target，不能证明监听器属于当前 worktree，因此任何已存在的 3080 都失败关闭，不主动杀不能证明归属的旧服务，也不因 target 看似匹配而复用。Tauri CLI 使用独立 POSIX 进程组，任意退出后按负 PGID 先 TERM、有界等待、再 KILL；Windows 固定调用 `taskkill /PID <pid> /T /F`。`start-dev-stack.mjs` 自己的后端 / Vite 独立组也在返回前有界收束。
+- 验证：定向测试必须覆盖旧 marker target 在 CLI spawn 前被拒绝、target 看似匹配仍拒绝无归属 Vite、非 HTTP 3080 失败、预检调用顺序、CLI leader 先退出后同 PGID 客户端仍收到 TERM、忽略 TERM 时升级 KILL，以及 Windows taskkill 的 `/PID /T /F` 参数。人工复验旧 worktree 占用 3080 时，新命令不得启动后端或弹出新窗口；正常启动后退出，确认 Tauri 客户端、Runner 和本轮自有后端 / Vite 均按生命周期收束。
+- 关联：`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/tests/start-tauri-dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts`。
+
+## game-chat 快车道首波与已提交回复不能被后续 revision 破坏（2026-08-03）
+
+- 现象：首波从单个美术任务扩展为三个 Director 后，hydration 若仍只容忍 seed lane 的第一个任务在 manifest 短暂恢复 `Pending` 时收束，另外两个已启动 Director 会被卡住。另外默认 `llm.stream=false` 下的专业 final reply 虽已由 finalization 提交，但后续阶段推进项目 revision 后，早期回复会从 Runtime 查询中消失。
+- 原因：hydration 例外把“首波”错误收窄成了单个固定或数组第一项任务；`visible_game_creator_agent_runtime_response_stream_at` 又把未提交流的 revision 新鲜度门误用到了已终态提交的 durable final reply。
+- 处理：从当前 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`。