Merge remote-tracking branch 'origin/master' into feat/ui-editor-auto-seperation

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

@@ -3,6 +3,28 @@
 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
 
+## 2026-09-14 AGC 壳 Rust 套件按「一片一 job」拆分，客户端 Rust 关键路径压到 7 分钟以内
+
+- 背景：`AI game creator shell Rust tests` 是客户端 CI 的关键路径（run 2097 实测 15 分 27 秒）。拆开来看：前置 5 分 30 秒（checkout 10s + `npm ci` 2m45s + Cargo fetch 2m35s）、编译 1m39s、**AGC 壳 bin target 的 2466 条单测串行 507s**、`agent-run` smoke 51s。这 2466 条全在 `apps/ai-game-creator-shell/src-tauri` 的 bin target 里，一条 `cargo test … -- --test-threads=1` 跑完。
+- 为什么原本整套串行：2026-07-21 的 `a273377b1`（「稳定AI原生壳全量测试」）把 Tauri suite 固定为 `--test-threads=1`，理由是**共享 Agent Runtime 后台锁与异步终态在 libtest 并行调度下互相干扰**——即同进程内的全局锁、异步终态与进程级 static 被交叉触发；另有少量用例自身 spawn 当前测试二进制跑 fixture，会碰容器里共享的 target 与固定临时路径。当时的口径是「修正 suite 调度口径，不放宽断言」。
+- 决策：**把 2466 条按名单切成 4 片，一片一个 CI job**（片内仍严格 `--test-threads=1`，不放宽任何断言），片与片之间靠 job 级并发摊开。新增 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`：`cargo test --no-run` 编译一次拿到测试可执行文件，`--list` 取全部用例名，排序后按 `index % shards` 切片；CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片（`--exact <名单>` 加独立 `TMPDIR`），本地不传该参数时仍是一条命令把 4 片放进程里并行。
+- 反面实验（run 2102，已废弃，勿重做）：起先让**同一个 job** 内的 4 个进程并行跑这 4 片，门禁步骤跑满 18 分钟仍未结束，比整套串行的 507 秒还慢——同一容器内多片共享 `HOME`、target 目录与固定临时路径，会互相拖慢。所以 CI 走 job 级分片，`--shard-index` 是唯一入口。
+- 不变量：片并集必须等于 `--list` 的全集且互斥，数量或成员不符立即失败（`assertShardsCoverEveryTest`）；该校验与「只跑一片」无关，因此在每个分片 job 上都会执行，防止分片规则改动后静默漏跑门禁。
+- 配套拆分：`npm run ai-game-creator-shell:check:rust` 拆成 `:rust:crates`（`agent-runtime-core`、`agent-runtime-orchestration`、`platform-llm`、`shared-contracts`）与 `:rust:shell`（分片运行器），聚合脚本保持同序，因而 `ai-game-creator-shell:check` 与本地 `npm run check:native-shells` 语义不变。AGC 相关门禁在 CI 里变成 6 个 job：`AI game creator shell Rust shard 1/4` ~ `4/4`、`AI game creator shell Rust smoke`、`AI game creator shell Rust crates`。
+- 前置瘦身：AGC 壳有独立 `Cargo.lock`，其 path 依赖已包含 `platform-llm` / `platform-agent` / `agent-runtime-core` / `shared-contracts`，所以 4 个分片 job 与 smoke job 只需预热 AGC 壳这一份 manifest；这些 job 只用 cargo 与 node 内建模块，因此 **5 个壳 job 与 crates job 都不再执行 `npm ci`**（每个省 1~3 分钟）。
+- 影响范围：`.gitea/workflows/project-ci.yml`（十一个 job）、`scripts/check-native-shells.mjs`（分组由五个到十个：新增 `agc-rust-crates`、`agc-rust-shard-1..4`、`agc-rust-smoke`，移除 `agc-rust` 与随后的 `agc-rust-shell`）、根 `package.json`、`scripts/project-ci-workflow.test.ts`（新增纯 cargo job 免 `npm ci`、分片运行器覆盖校验、crate 级 job 预热顺序断言）、开发运维文档与共享记忆。Gitea `master` 分支保护的 required context 是追加式的，需补上 6 个新 context（共十一个）。
+- 验证方式：`npx vitest run scripts/project-ci-workflow.test.ts`；分片运行器本地以 `agent-runtime-core`（7 条 → 2/2/2/1）与 `platform-llm`（146 条 → 49/49/48）验证分片、`--exact` 与片 TMPDIR 隔离，负例 `--shard-index=5` 立即失败；`node scripts/check-native-shells.mjs --groups=contract` 回归。预期每个分片 job 收敛到 5 分钟以内（前置约 1 分 30 秒 + 编译约 1 分 39 秒 + 约 617 条用例）。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)、[踩坑记录](pitfalls.md)。
+
+## 2026-09-14 客户端 CI 按门禁组拆成三个 job，AGC 的 web / rust 两段并行
+
+- 背景：`Project CI / Native shell tests` 把微信壳、Expo 移动壳、Tauri 桌面壳、H5 HostBridge 与 AI 游戏创作壳的全部门禁串在一个 job 里，实测 18 分 37 秒；同一次运行的 Repository / Frontend / Backend 分别只要 3 分 21 秒、4 分 16 秒、6 分 14 秒，其余三个 job 结束后客户端 job 还要再跑十几分钟。日志时间戳显示门禁段 932 秒里：AGC `ai-game-creator-shell:check` 占 654 秒（其中壳内 Rust 套件 2451 个用例 `--test-threads=1` 单跑 441.58 秒、编译 79 秒），AGC vitest 75 秒，两个发布构建 smoke 加落盘断言 230 秒，而 h5 / 微信 / 移动 / 桌面壳的全部运行时门禁加起来不到 50 秒。
+- 决策：`scripts/check-native-shells.mjs` 引入 `--groups=`，把门禁分成 `contract`（静态契约断言）、`shells`（H5 / 微信 / Expo / 桌面壳运行时门禁）、`agc-web`（AGC typecheck 与壳内测试）、`agc-rust`（共享 / 平台 crate 测试、AGC 串行壳测试、agent-run smoke）、`release`（AGC 与桌面壳发布构建 smoke、落盘产物断言）五组，每组暴露一个 `check:native-shells:<group>` 根脚本；不带 `--groups=` 时仍然串行跑全部分组，本地 `npm run check:native-shells` 语义不变。CI 据此把原客户端 job 拆成 `Native shell tests`（contract + shells + release）、`AI game creator shell web tests`（agc-web）、`AI game creator shell Rust tests`（agc-rust）三个 job，并把最长的 AGC Rust job 声明在最前，使 runner 领取顺序与关键路径一致。
+- 命令等价：`npm run ai-game-creator-shell:check` 拆成 `:check:web`（typecheck + 壳内测试）与 `:check:rust`（agent-runtime 两个独立 crate + `platform-llm` + `shared-contracts` + AGC 壳串行测试），聚合脚本仍是 `web && rust && agent-run:smoke` 同序同命令，本地与文档入口不变。`agent-run:smoke` 会用 `src-tauri/Cargo.toml` spawn `cargo`，因此归入 `agc-rust` 分组，与 AGC 依赖预热同 job。
+- 影响范围：`.gitea/workflows/project-ci.yml`（六个 job）、`scripts/check-native-shells.mjs`、根 `package.json` 门禁脚本、`scripts/project-ci-workflow.test.ts`（校验分组清单、根脚本内容与 job 覆盖，防止新增分组时静默漏跑）、开发运维文档与开发流程记忆。门禁覆盖不变，只有执行位置改变；Gitea `master` 分支保护的 required context 是追加式的（旧四个继续上报，需补上两个新 AGC context）。
+- 验证方式：`npx vitest run scripts/project-ci-workflow.test.ts`（11 条）；`node scripts/check-native-shells.mjs --groups=contract` 本地 0.6 秒通过；`--groups=` 未知组与空组都要报错关闭。拆分前同一类运行的 wall-clock 是 22 分 15 秒（run 2094，`Native shell tests` 单 job 19 分 50 秒）；拆分后 run 2097 六 job 全绿、wall-clock 15 分 27 秒，关键路径转移到 `AI game creator shell Rust tests`（15 分 27 秒 = 前置 5 分 30 秒 + 门禁 11 分 43 秒），其余五个 job 3 分 45 秒 ~ 8 分 36 秒。AGC 壳内串行套件（2451 用例）实测 507 秒，是这条关键路径的硬底，再切 job 只会重复 `npm ci` 与 Cargo 预热。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)、[踩坑记录](pitfalls.md)。
+
 ## 2026-09-10 策划 Agent 迁移只复用生产基建
 
 - 决策：待实施的生产迁移以自由协作策划原型为行为基线，仅复用 Provider、恢复、文件操作、审计和 UI 通信；不继承旧 Planning V2 的强制工具、问询轮数、GDD 内容校验和版本审批。保留五阶段与顾问态、当前阶段资源注入和产物存在性检查，系统阶段空必需清单不增加解析或登记功能。
@@ -42,7 +64,7 @@
 - 影响范围：`src/view/project-development/ResourceClassificationPanel.tsx`（选择器 + 写回分叉）、`src/view/project-development/index.tsx`（角标取值）、`tests/resourceClassificationPanel.test.tsx`、`tests/projectResourceLiveIntegration.test.tsx`（真宿主跟随链）、`tests/appSurface/project-development.suite.ts`（原媒体类型角标断言改资源类型）、PRD §5.3、AGC 资源工作台 V3 端到端验收用例 S5、[`【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md) 的写入命令一节。Rust / manifest 字段构成 / SpacetimeDB 都不动。
 - 验证方式：`npm run test -- apps/ai-game-creator-shell/tests/resourceClassificationPanel.test.tsx apps/ai-game-creator-shell/tests/projectResourceLiveIntegration.test.tsx apps/ai-game-creator-shell/tests/appSurface.test.ts` + `npm run typecheck` + `npm run check:encoding` + `git diff --check`。变异验证（均已实测）：①写入改回"永远回传落盘原值" → 3 条面板用例红；②没碰控件时改回"回传自愈值"（`gameCreationAppAssetCategory`）→ 2 条对照用例红；③选择器改读落盘值 → 选择器用例红；④角标改回 `projectResourceTypeLabel` → 角标用例与 appSurface 断言红。**不可构造**的变异：把角标"只在挂载时算一次"—— 选中资源本身就会把画布切进它所在栏目，改类型又让卡片换到另一个栏目分组，React 每次都卸载重建卡片宿主，挂载快照与实时读数在 DOM 上同形。
 
-## 2026-09-11 pre-commit 补 Rust 格式守卫：lint-staged 增 *.rs，本地不再只靠 CI 的 check:rustfmt
+## 2026-09-11 pre-commit 补 Rust 格式守卫：lint-staged 增 \*.rs，本地不再只靠 CI 的 check:rustfmt
 
 - 背景：本 PR 已因 `check:rustfmt` 红过一次（`15660a98b` 修掉本批遗留的 8 处格式偏差）。根因是 `.husky/pre-commit` 只跑 `lint-staged`，而它的 glob 只覆盖 `*.{js,mjs,cjs,ts,tsx}` —— **Rust 格式在本地没有任何守卫**，唯一防线是 CI 那一侧（`check-repository-ci.sh` → `npm run lint` → `check:rustfmt`）；本地没人跑得到的门禁等于没有门禁，「本地全绿、CI 才红」就会反复发生。
 - 决策：lint-staged 增 `"*.rs": ["node scripts/lint-staged-rustfmt.mjs"]`。`cargo fmt` 只按 workspace 粒度格式化、**不接受文件参数**（lint-staged 会把命中的暂存路径追加到命令末尾），所以用包装脚本忽略 argv，对 `server-rs` 与 `apps/ai-game-creator-shell/src-tauri` 两个 workspace 各跑一次 `cargo fmt --all --manifest-path <m> -- --check`，**只查不改** —— pre-commit 不应该自动改写别人正在改的 Rust 文件。workspace 路径与既有 `check:rustfmt` 一样写成 cwd 相对，因为 lint-staged 以 git 根为 cwd 运行任务。
@@ -8569,6 +8591,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 原因：预览起停不是源码变更，不能靠"给它也推一次 revision"来消除冲突——那会让运行时的验证凭证（`expected_revision` / `verified_revision` / `failed_playtest_revision`）凭空漂移，把自主构建流程拖进无谓的重新验证。正确的修法是把判据面收回到契约所说的对象，而不是让簿记写入承担源码语义。
 - 验证：`projectResourceLiveUpdateModel.test.ts` 新增「同 revision 只有 `preview` 变化必须被接受」与「同 revision 资产变化必须仍被拒收」两条；变异回整份 JSON 指纹后前者以 `expected 'revision-conflict' to be 'accepted'` 失败。定向：模型 17 passed、workspaceLauncherManifestMerge 5 passed、appSurface 413 passed、typecheck exit 0、check:encoding 4399 files passed。
 - 影响范围：`apps/ai-game-creator-shell/src/view/project-development/projectResourceLiveUpdateModel.ts`、`apps/ai-game-creator-shell/tests/projectResourceLiveUpdateModel.test.ts`、`pitfalls.md` 本条。
+
 ## 2026-09-11 AGC 资源替换按 PRD 恢复为「版本级替换」：改绑定落在追加的新版本上
 
 - 背景：PRD §3.2（`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md:36-41`）要求「替换版本引用资源时创建下一迭代版本，不原地修改既有版本」，并要求新版本记录 `parentVersionId`、替换前后资源身份与创建原因；§5.3（:356-387）给出 `ProjectVersionResourceReplacement` 与「三项兼容性必须同时为 true 才能创建下一版本」。本文件 2026-09-10 那条（`decision-log.md:8263`）与 Issue #309 的 C1 决策 / 贯穿性决策 6 / 验收总纲当时写的是相反口径：「改 manifest 绑定……**不创建新版本**」「替换功能（候选素材 / 替换关系 / 替换队列 / Agent 审核 / 单点替换）整条取消，不实现」。用户裁决：**按 PRD 来**，实际机制仍是「改 manifest 绑定」。
@@ -8634,8 +8657,23 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 影响范围：`apps/ai-game-creator-shell/src/features/resource-canvas/{resourceCanvasBottomToolbarModel.ts,ResourceCanvasBottomToolbarView.tsx,ResourceCanvasAssetGenerationPanelView.tsx,ResourceCanvasGenerationPanelView.tsx,resourceCanvasChrome.css}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、测试 `apps/ai-game-creator-shell/tests/{resourceCanvasBottomToolbar.test.tsx(新增),resourceCanvasGenerationEntry.test.tsx,projectResourceLiveIntegration.test.tsx,appSurface/project-development.suite.ts}`、PRD §3.10 / §7.9 / §8、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`（新增）、验收用例 S11 / S11a。**未动**：Rust、external v1 / OpenAPI、`packages/`（只消费共享 chrome）、SpacetimeDB。
 - 验证方式：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`（423 passed，含新增 6 条：栏目分流与总览不渲染、UI 栏 5 个入口载荷、前置缺失可点击说明且零请求、角色栏 2 个入口、音频入口走既有链路、上传 + 配对读清单，另 1 条工具栏与 Dock 的 CSS 几何契约）；`resourceCanvasBottomToolbar.test.tsx` 15 passed（新增）；`resourceCanvasGenerationEntry.test.tsx` 11 passed（新增单类型用例 1 条）；`projectResourceLiveIntegration.test.tsx` 25 passed（「生成素材」面板改名断言同步更新）；`npm run agc:typecheck` 全绿（**其中的 `check-config.mjs` 报错已因本轮落地调用方而消失**）、`npm run check:encoding`、`git diff --check` 干净。未 commit。
 - 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9 / §8）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11 / S11a / §7.3）。
+
 ## 2026-09-13 Cocos 插件按当前项目类型暴露
 
 - 决策：`agc-cocos-editor` 只有在当前受控项目通过 Cocos Creator 根目录识别（`package.json.creator.version` + 普通 `assets/`）时才暴露插件、面板和 Cocos 工具；无项目或其它项目类型均隐藏并失败关闭。
 - 决策：项目切换离开 Cocos 时立即停止已运行的插件实例；启动、面板读取、插件 RPC、Runtime execute 和 DirectProject MCP 工具目录/执行入口全部再次校验项目类型。Cocos 编辑器操作优先经内置插件入口，禁止回退到项目 `extensions/`、`package.json` 插件或第三方 MCP。
 - 验证：新增 builtin/plugin host 项目级门禁测试，Direct MCP fixture 补最小 Cocos 工程结构；Rust 定向测试、显式 `cocos-editor-execute` feature 编译、编码检查和 `git diff --check` 已执行。
+
+## 2026-09-14 DirectProject Codex 取消路径白名单并启用完整 sandbox
+
+- 背景：DirectProject 原先以 `workspaceWrite(writableRoots=[项目根])` 和 `item/fileChange/requestApproval` 的项目根校验限制 Codex 原生文件与命令能力，系统提示词还把 `.agent/`、`.git/`、项目外路径列为不可访问边界。
+- 决策：DirectProject app-server thread 改为 `sandbox="danger-full-access"`，turn 改为 `sandboxPolicy.type="dangerFullAccess"`，不再发送 `writableRoots` 或 workspace 网络开关，原生命令网络随完整 sandbox 开放；app-server 交互请求不再按 grant root 做白名单裁剪，直接项目会话统一接受文件变更、命令执行和权限请求。首页只读对话、AGC `agc_tools` 业务授权、Provider 凭据隔离、Runtime 审计和客户端受控文件工具合同继续保留。
+- 提示词同步：DirectProject 不再把路径范围描述成 Codex 原生能力禁区，但仍禁止主动输出 Token、Cookie、auth.json、`.env` 和 Runtime 私有控制面。
+- 验证：Rust 定向单测覆盖 `danger-full-access` / `dangerFullAccess`、无 `writableRoots`、外部 grant root 仍接受，以及 DirectHome 继续只读拒绝。
+
+## 2026-09-14 项目写锁的同进程复用收窄为同线程重入
+
+- 背景：`write_lock.rs` 的 advisory 复用判据曾放宽为「`.agent/project.lock` 的 `pid` 等于当前进程」，使本进程所有写通道都不再等待。`Project CI` 的 Rust 全量门禁因此出现 12 条失败：另一线程持锁时一致快照读 / `project.diff` / `action_history` / `command.output_read` / steer 不再等待，4 路并行直写撞项目 revision 侧车（`File exists (os error 17)`），8 线程并发 steer 拿到重复序号，`file.write` 锁失败脱敏与恢复安装的失败关闭变成成功。
+- 决策：复用判据收窄为**同一条写调用链（同一线程）重入**——按锁路径登记真实持锁线程，只有当前线程就是持锁线程时才返回 advisory guard；本进程其它线程的争用继续走有界等待与终态占用。自主游戏构建流水线的并行专家动作豁免保持不变；跨进程占用、残留回收、权限分类、等待预算和错误文案不变。
+- 边界：锁定这些不变量的既有用例（`project_tools` / `command_runtime` / `parallel_actions` / `runtime_state` / `response_stream` / `direct_tool_bridge` / `ui_editor::persistence`）不得为了让锁语义通过而改写；用「同线程自持锁」模拟「另一个写者」的两条用例改为**在另一条线程持锁**，断言语义不变。同进程跨线程重入（持锁链在 `await` / `spawn_blocking` 后于其它线程再取锁）仍会等满预算，出现现场时按 2026-08-27 的既有处置改用 `*_locked` 入口，不放宽判据。
+- 关联文档：[项目客户端占用锁收敛里程碑](../plans/【里程碑】项目客户端占用锁收敛-2026-09-14.md)、[踩坑记录](pitfalls.md)。

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

@@ -74,4 +74,4 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
 
 ## Gitea CI 依赖闭合
 
-`.gitea/workflows/project-ci.yml` 的 `Native shell tests` 在运行原生壳门禁前，必须使用 `cargo fetch --locked` 预取 `server-rs/Cargo.toml`、桌面壳和 AGC 壳三份依赖。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。
+`.gitea/workflows/project-ci.yml` 的客户端门禁拆成八个 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust shard 1/4` 到 `4/4` 各只预取 AGC 壳 manifest 并各跑一片（AGC 壳那份 `Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`），`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与两个独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。AGC 壳的 4 个分片 job、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译一次后按 `--list` 名单分 4 片：CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并各自使用独立 `TMPDIR`，片与片之间靠 job 级并发摊开；本地不传 `--shard-index` 时仍是同一条命令把 4 片放进程里并行。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。

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

@@ -1,5 +1,58 @@
 # 踩坑与排障记录
 
+## 2026-09-14 AGC 壳 Rust 套件按「一片一 job」拆分，且分片必须自校验覆盖
+
+- **现象**：`AI game creator shell Rust tests` 一直是客户端 CI 的关键路径。run 2097 实测 15 分 27 秒，其中 `apps/ai-game-creator-shell/src-tauri` 的 bin target 单测（2466 条）一条 `cargo test -- --test-threads=1` 串行占 507 秒。
+- **为什么原本是整个 suite 串行**：2026-07-21 `a273377b1` 的判据是「共享 Agent Runtime 后台锁与异步终态在 libtest 并行调度下互相干扰」，即**同进程内**的全局后台锁、异步终态与进程级 static 被交叉触发；另有少数用例自身 spawn 当前测试二进制（`std::env::current_exe()`）跑 fixture，会碰容器里共享的 target 与固定临时路径。
+- **处理（现行口径）**：新增 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`：`cargo test --no-run` 编译一次后用 `--list` 名单把用例按 `index % shards` 切成 4 片，CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片（`--exact <名单> --test-threads=1`，片内串行），片与片之间靠 **job 级并发**摊开。配套把 `ai-game-creator-shell:check:rust` 拆成 `:rust:crates` 与 `:rust:shell`，AGC 相关门禁在 CI 里共 6 个 job（4 个分片 + smoke + crates）。
+- **反面实验（run 2102，勿重做）**：起先把 4 片放进**同一个 job** 内的 4 个进程并行，结果门禁步骤跑满 18 分钟仍未结束，比整套串行的 507 秒还慢——同一容器内这几片共享 `HOME`、target 目录与固定临时路径，会互相拖慢。因此 `--shard-index` 是 CI 的唯一入口；不带 `--shard-index` 的「单命令内多片并行」只留给本地全量自测。
+- **易错点**：① 分片规则必须自校验「片并集等于 `--list` 全集且互斥」，否则改分片方式会静默漏跑门禁；② 每片要拿独立 `TMPDIR`，`tempfile::tempdir()` 默认落在它下面（测试里的硬编码 `/tmp/...` 多是「必须拒绝」的负向断言，不是真实读写）；③ 不要给分片 job 装 `npm ci`——AGC 壳 Rust 门禁与 `agent-run` smoke 只用 cargo 与 node 内建模块，那些 `npm ci` 正是达标 7 分钟的主要障碍；④ 片 job 只需预热 AGC 壳自己的 manifest（其 `Cargo.lock` 的 path 依赖已覆盖 `platform-llm` / `platform-agent` / `agent-runtime-core` / `shared-contracts`），`server-rs` 那份预热属于 crate 级 job；⑤ 分片后 `--test-threads=1` 不再出现在 workflow 里，但它是分片运行器的片内参数，别再往 workflow 里补整套串行命令。
+- **不要做的事**：不要退回「整套 `--test-threads=1`」（507 秒长尾回来了），不要放开成整套并行（同进程内后台锁与异步终态会再互相干扰），也不要在单个 job 内多进程并行多个片（实测比串行还慢）。
+- **关联**：`apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`、`.gitea/workflows/project-ci.yml`、`scripts/check-native-shells.mjs`（`agc-rust-shard-1..4` / `agc-rust-smoke` / `agc-rust-crates` 分组）、`package.json`。
+
+## 2026-09-14 根门禁的 `[check:native-shells] <label>` 是别处按字面量校验的契约
+
+- **现象**：客户端 CI 拆成六个 job 后，`Native shell tests` 在 `desktop-shell:typecheck` 步骤红了：`Error: root native shell gate must keep desktop release artifact check console.log('[check:native-shells] desktop-release-binary-artifact')`。
+- **原因**：拆分时给 `scripts/check-native-shells.mjs` 加了公共打印函数 `runNativeShellGate(group, label, gate)`，把各门禁的 `console.log('[check:native-shells] <label>')` 换成了模板字符串。而 `apps/desktop-shell/scripts/check-config.mjs` 与 `apps/mobile-shell/scripts/check-config.mjs` 会读取根门禁脚本源码，对这类 label 做**字面量**断言（含 `assertDesktopReleaseBinaryArtifact();` 调用本身），label 一变形断言就失败。
+- **处理**：`runNativeShellGate` 收窄为 `(group, gate)`，label 回到各门禁执行体里以字面量打印；分组能力与 `--groups=` 语义不变。脚本内已注明"不要把 label 抽成变量"，外部壳的 `check-config` 是它的消费者。
+- **验证**：`node apps/mobile-shell/scripts/check-config.mjs` exit 0；`node apps/desktop-shell/scripts/check-config.mjs` 已越过第 740–777 行的根脚本断言段（本机随后卡在本机不存在的 Tauri 生成产物目录，与本次改动无关）；`--groups=contract`、vitest `scripts/project-ci-workflow.test.ts`、eslint 均通过。修复后 run 2097 六个 job 全绿。
+- **关联**：`scripts/check-native-shells.mjs`（`runNativeShellGate`）、`apps/desktop-shell/scripts/check-config.mjs`、`apps/mobile-shell/scripts/check-config.mjs`。
+
+## 2026-09-14 客户端 CI 拆分后，选组运行会跳过未选分组，且必须同步分支保护
+
+- **现象**：把 `Native shell tests` 拆成客户端三个 job 后，如果只跑 `npm run check:native-shells:release`，静态契约和壳运行时门禁都不会执行；如果只跑 `--groups=contract`，`desktop-release-binary-artifact` 又会因为缺少 `build/native/desktop/` 产物而失败。
+- **原因**：分组是执行范围，不是"额外检查"。`desktop-release-binary-artifact` 断言依赖同 job 内的 `desktop-shell-stage-release-binary` 步骤，所以它归 `release` 组，不能放进 `contract`；反过来，任何"只跑一组"的命令都不能被当成完整门禁。
+- **处理**：分组与 job 的对应关系固定为 `contract`+`shells`+`release` → `Native shell tests`，`agc-web` → `AI game creator shell web tests`，`agc-rust-shard-1..4` → `AI game creator shell Rust shard 1/4 .. 4/4`，`agc-rust-smoke` → `AI game creator shell Rust smoke`，`agc-rust-crates` → `AI game creator shell Rust crates`；`scripts/project-ci-workflow.test.ts` 校验"每个分组恰好被一个 job 调用一次"和"CI 不再调用全量 `npm run check:native-shells`"，新增分组必须同步门禁脚本、根脚本与 workflow 三处。
+- **易错点**：① 拆 job 后 Gitea `master` 分支保护的 required context 要补齐两个新 AGC context，只改 workflow 不改分支保护会让新门禁在合并前不生效；② 每个 job 只预热自己会构建的 Cargo 依赖，`agent-run:smoke` 因为会 spawn `cargo` 必须留在 `agc-rust` 所在 job；③ 本地全量 `npm run check:native-shells` 仍会串行跑完所有分组，用它作为本地完整门禁，不要用单组脚本冒充。
+- **关联**：`.gitea/workflows/project-ci.yml`、`scripts/check-native-shells.mjs`、`scripts/project-ci-workflow.test.ts`、`.gitea` 分支保护设置。
+
+## 2026-09-14 `check:native-shells` 的调用链扫描在 Windows 上恒假
+
+- **现象**：Windows 本机运行 `npm run check:native-shells:contract` 时，`production-shell-dev-scaffold-scan` 报 `H5 HostBridge call chain scan is missing required files: src/ActiveApp.tsx, ...`，而仓库里这些文件都存在，Linux CI 从不报。
+- **原因**：`collectFiles` 在 Windows 上返回 `src\ActiveApp.tsx`，调用链扫描把该路径原样放进 `scannedFiles`，再与 POSIX 写法的期望清单（`h5HostBridgeRequiredCallChainFiles` 的 `src/ActiveApp.tsx`）比较，成员判断恒假。注意 `normalizeModulePath` 不能直接复用：它还会去掉 `.ts/.tsx` 后缀。
+- **处理**：新增 `normalizeScannedFilePath`（只统一分隔符、保留后缀）用于 `scannedFiles` 的登记；Linux 上 `split('/').join('/')` 是恒等变换，行为不变。
+- **验证**：`node scripts/check-native-shells.mjs --groups=contract` 在 Windows 上 0.6 秒通过（修复前同一条命令必红）。
+- **同一类限制（未改）**：Windows 本机跑 `shells` / `agc-web` / `agc-rust-shard-*` / `agc-rust-smoke` / `release` 这些**带步骤**的分组会在第一条 npm 步骤直接失败：`spawnSync npm.cmd EINVAL`（Node 24 起不能不带 shell 直接执行 `.cmd`；而根 `npm run test` 另有 chmod/0600 语义的 Windows 专属失败）。因此 Windows 本机可用的只有 `--groups=contract`，完整门禁交给 Linux CI；不要为此把 `spawnSync` 改成 `shell: true`（步骤参数里含空格与中文字符串，会被 shell 重新解析）。
+- **关联**：`scripts/check-native-shells.mjs` 的 `collectH5HostBridgeCallChainFiles` / `normalizeScannedFilePath`。
+
+## 2026-09-14 项目写锁的同进程复用判据不能只看 pid
+
+- **现象**：`master` 的 `Project CI / Native shell tests` 红在 `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --test-threads=1`，12 条用例失败（`2439 passed; 12 failed`）。断言分三类：① 另一线程持锁时快照读 / `project.diff` / `action_history` / `command.output_read` / steer 不再等待（`... must wait for the project consistency lock`）；② 并发写不再串行化——4 路并行直写撞项目 revision 侧车报 `File exists (os error 17)`，8 线程并发 steer 拿到 `[1, 1, 1, 1, 1, 1, 1, 2]`；③ 别的写通道持锁时 `file.write` 与恢复安装必须失败关闭，实测变成 `ok` / 不再报占用。
+- **原因**：`project/write_lock.rs` 的 advisory 复用判据从「自主游戏构建流水线 + 本进程持锁」放宽成「本进程持锁」，而判据只比 `.agent/project.lock` JSON 里的 `pid`。`pid` 只能证明锁由本进程持有，分不清「同一条调用链再次取锁（必须放行，否则自己等自己）」和「本进程另一条写通道正在写（必须继续串行化）」；于是同进程其它线程的写通道也拿到 advisory guard。
+- **处理**：复用判据收窄到**同线程重入**。新增 `PROJECT_WRITE_LOCK_THREAD_OWNERS`（按锁路径登记真实持锁线程）与 `project_write_lock_reentered_by_current_thread`：登记在 `create_new` 成功处，注销在 guard `Drop` 里并且**按路径**注销（guard 会被移到别的线程再 Drop，例如写入路径交给阻塞线程池的持有者）。只有当前线程就是该路径的持锁线程（或自主游戏构建流水线）才返回 advisory guard；本进程其余争用继续走有界等待与终态占用。
+- **易错点**：① 用「同线程」近似重入后，靠**同线程自持锁 + 同线程调用**模拟「另一个写者」的用例会失去信号（`agent_runtime_file_write_lock_failure_redacts_project_path`、`recovery_install_respects_the_project_write_lock`）：它们必须改成**在另一条线程持锁**，断言才有意义；② 不要用「同进程还有 guard 活着」当重入依据，那等于退回按 `pid` 放行；③ 同进程**跨线程**重入（持锁调用链在 `await` / `spawn_blocking` 之后于其它线程再次取锁）仍会等满预算并在耗尽时报占用，出现这类现场按 2026-08-27 的处置改用 `*_locked` 入口复用已有 guard，不要放宽判据。
+- **验证**：本地定向 36 条（`--test-threads=1`，过滤 `_after_project_lock` / `bridge_write_file` / `project_write_lock` 等）：CI 那 12 条里 9 条转绿（覆盖 `project_tools` / `command_runtime` / `parallel_actions` / `runtime_state` / `response_stream` / `external_generation_state`），3 条在本机被 Windows 临时目录 owner/DACL 挡在 setup（与本次改动无关，见 2026-09-13 条）；`project_write_lock_reuses_same_process_owner_and_releases_on_drop`（同线程重入）继续通过。`cargo fmt --check`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 全绿。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/project/write_lock.rs`、`src/agent/runtime_actions/project_gates.rs`（有界等待预算）、`docs/project-memory/plans/【里程碑】项目客户端占用锁收敛-2026-09-14.md`、`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`「2026-09-14 项目客户端占用锁收敛」。
+
+## 2026-09-14 UI 超时围栏只能放弃等待，不能放弃结果；排队闸门不能无限等
+
+- **现象**：登录/建项在 UI 上"超时"后报错，用户重试仍然无效；界面停在原页面，而后端/Runner 其实已经接受了这次操作（登录后本机登录态已装好、项目目录已建好）。
+- **原因**：两个独立缺陷叠加。(1) `withAuthCheckTimeout` 一类围栏用 `Promise.race` 只让界面提前失败，底层 native mutation 仍在队列里跑；而队列尾是"无限等上一次完成"的串接，一次卡住的 invoke 会让之后每次登录/退出都排在它后面（故障注入：连续两次登录只产生 1 次 install 调用）。(2) `platformNativeGenerationFloorPromise` 用 `??=` 缓存 promise，一次瞬时读取失败被缓存成永久失败。
+- **处理**：(1) 围栏超时后仍要有人接手结果——`AuthenticatedClient` 用尝试代次 + `currentPlatformSessionGeneration()` 判定，迟到成功才写回界面，绝不覆盖更新的尝试；(2) native 写入队列改成带解围期限的闸门（`PLATFORM_SESSION_NATIVE_MUTATION_ABANDONMENT_MS`）。普通队列"串行"看起来更安全，但本地会话写入的真正不变量在 Rust：`install_platform_session_in` / `clear_platform_session_in` 按 generation 单调拒绝更旧写入，所以渲染层只要保证新 generation 不被旧调用永久挡住即可；(3) 首页 `home-create` 从 `deadlineMs: null` 改为有兜底期限，到点用 `Promise.race` 返回提示字符串解围（**不要抛错**：首页 catch 会把错误统一压成「创建未完成，请重试」，反而丢掉"只是慢"）而底层创建继续跑，迟到成功照常进项目；已建好的工作区要登记最近项目并留「打开已创建的工作区」入口。
+- **易错点**：失败分支里不要用**初始** operation 去覆盖已经带上 `scope.projectPath` 的状态——`transitionClientOperation(初始 operation, ...)` 会把内层写好的路径丢掉，导致"项目已建好但用户拿不到"。看门狗解围后仍要保留"底层创建未返回"标记：放行会真的建出第二个工作区；但这条只挡"再建一个"，不能挡打开已有项目。
+- **验证**：`apps/ai-game-creator-shell/tests/appSurface.test.ts`（`auth.suite.ts` 的 stalled install / floor 瞬时失败 / 围栏后迟到安装；`home.suite.ts` 的建项看门狗与设计运行时初始化失败后的恢复入口）。
+- **关联**：`apps/ai-game-creator-shell/src/services/platformSession.ts`、`src/app/AuthenticatedClient.tsx`、`src/features/app-shell/useHomeProjectCreation.ts`、`src-tauri/src/platform_session.rs`、`docs/【技术方案】AGC客户端稳定版生命周期大切换-2026-09-14.md`
+
 ## 2026-09-13 Cocos 操作必须核对实际回执与引擎就绪状态
 
 - named pipe 使用真实换行分帧；测试客户端若写入字面量反斜杠 n，服务端不会执行请求。不能仅凭这类超时推断 Scene WebView 卡死，更不能重放不确定写操作。
@@ -5353,6 +5406,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **排查顺序**：① 先看失败耗时——几十毫秒说明该入口没等，是等待窗口缺失，不是锁没释放。② 看错误里的 `ownerIsSelf`：`true` 指向同进程另一条写通道，`false` 指向外部进程；该字段只比 PID，PID 复用会把外人报成自己人，只当线索、不当判据（回收判据另有 `processStartedAt` 兜底）。③ **锁文件在失败后通常已被 Drop 删掉，现场缺文件不否定争用**；同理 `agc_list_registered_assets` 的 `pendingOperations: []` 只表示没有在跑的付费生成，与项目写锁无关，不构成“锁没有持有者”的证据。④ `.agent/.manifest.json.lock` 是 manifest 的持久 OS 文件锁（Windows 不共享写句柄 / Unix `flock`），0 字节长期存在是设计如此，不是残留锁，也不要用项目写锁的回收判据去处理它。⑤ 看到“项目写锁路径权限被拒绝”时注意它的含义：这是**等满等待窗口后**的终态改判（Windows 上真实 ACL 拒绝就走这条路），不是某一瞬间的 metadata 观察；反过来，`项目正在被其他写操作占用：…（持锁方身份不可读：锁文件此刻不存在…）` 是零等待入口无法区分拆链窗口与 ACL 拒绝时的并列表述，两者不要互相否定。
 - **验证**：Rust 定向覆盖同进程重叠写等待、同轮并行写、有界等待不占 runtime worker、活外部进程持锁带身份、权限拒绝不投影成争用，以及两条平台无关判据用例（重试性只由错误码决定、终态改判三条件）；`runtime_project_write_lock_waits_for_delete_pending_target` 继续覆盖带句柄的 delete-pending 必须等到成功。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs`、`apps/ai-game-creator-shell/src-tauri/src/project/write_lock.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/runtime_actions/project_gates.rs`。
+
 ## 2026-09-11 裸 rustfmt 会把「一个文件」放大成整个模块树，并行工作树里不要盲跑整仓 fmt
 
 - **现象**：只想按 `check:rustfmt` 的报错格式化 1 个 Rust 文件，跑完 `git diff --stat` 却显示 `src/agent/` 下 **50 个文件**被改动（`cargo fmt --all` 之后同样会扫到别人未提交的半成品）。
@@ -5385,7 +5439,6 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **推广**：任何"进入栏目后应恢复上次 viewport"的用例，在 jsdom 里必须避免经过总览往返；要覆盖往返本身，得先给 `resourceBookSceneSize` 造出非零尺寸。
 - **关联**：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`（`openResourceBookChild` / `resourceCanvasFitKeysRef` / 分页画布 layout effect）、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`。
 
-
 ## 2026-09-11 新增文件后必须重跑完整 typecheck：lint-staged 不跑 tsc，pre-commit 绿不等于类型正确
 
 - **现象**：新增 `ResourceFilterPanel.tsx` 后提交成功（pre-commit 全绿、定向测试通过），但随后补跑 `npm run ai-game-creator-shell:typecheck` 报出真实类型错误：`ResourceFilterPanel.tsx(113,10): error TS2322: Type 'RefObject<HTMLElement | null>' is not assignable to type 'Ref<HTMLDivElement> | undefined'`（`useRef<HTMLElement | null>` 被挂到了外层 `<div>` 上）。`exit 2`。
@@ -5426,7 +5479,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **现象**：在多个 Agent 共用同一 worktree 时，我的一次提交 `28781a420` 里出现两个 hunk：一个是我这次新增的用例（`@@ -1260,6 +1260,51 @@`），另一个是**别人的在途改动**（`@@ -9562,37 +9607,83 @@`：他们改「所有资源」测试的期望）。该笔 `107 insertions(+), 16 deletions(-)` 里只有约 45 行是我的。**没有丢内容**（对方的改动只是被冻在我名下的提交里），但**提交描述与实际内容不符**，而且对方那份文件立刻变成"干净"，很容易被误以为已经收口。
 - **原因**：`git add <路径>` 暂存的是该文件**当前工作区的整份内容**，不是"我这一份 diff"。只要对方的编辑已经落在工作区，`git add` 就会连带暂存。**事后回看 `git status --short` 那一行是 `M `（第一列 `M`、第二列空格）——这正是"对方编辑早于我的 `git add` 就已进入工作区"的特征**：索引与工作区一致，所以从状态行上看不出任何异样；若是 `MM`（add 之后工作区又被改过）反而更容易察觉。
 - **与前三类的区别**：前三类索引事故都是「**别人的文件**被卷走」——① `git add -A` 卷走别人的在途文件；② `stash pop` 弹出别人的 stash；③ `npx lint-staged --diff=…` 在收尾反向 `git add`。本类是「**同一个文件里别人的 hunk** 被卷走」，而**按文件名做校验的护栏在这里失效**：文件名本来就是我该提交的那一个，`git diff --cached --name-only` 必然通过。
-- **处理（正确护栏）**：对"可能被他人同时编辑的文件"，把 **`git add <path>` + `git diff --cached`（看**内容**，不只看文件名）+ `git commit` 压进**同一条命令**——窗口越小，对方编辑撞进来的概率越低；并在 `git diff --cached` 的输出里**逐 hunk** 确认"每一个 hunk 都是我这次要写的"。发现混入他人 hunk 后，**不要**在共享树里用 `--amend` / `reset` / `checkout --` / `revert` 做手术（本仓库会话明令禁止），**保持现状并立即上报**，由对方在自己的新提交里接着改（零风险，内容也没丢）。
+- **处理（正确护栏）**：对"可能被他人同时编辑的文件"，把 **`git add <path>` + `git diff --cached`（看**内容**，不只看文件名）+ `git commit` 压进**同一条命令**——窗口越小，对方编辑撞进来的概率越低；并在 `git diff --cached` 的输出里**逐 hunk** 确认"每一个 hunk 都是我这次要写的"。发现混入他人 hunk 后，**不要**在共享树里用 `--amend` / `reset` / `checkout --` / `revert` 做手术（本仓库会话明令禁止），**保持现状并立即上报\*\*，由对方在自己的新提交里接着改（零风险，内容也没丢）。
 - **状态信号速查**：`M ` = 已暂存且工作区与索引一致；`MM` = 已暂存 + 工作区又改过；` M` = 只有工作区改动（未暂存）。**`M ` 只能说明"我 add 之后没人再动过"，不能说明"这份文件里只有我的改动"**——判断后者唯一可靠的办法是看 `git diff --cached` 的内容。
 - **同类隐患（pre-commit 的 lint-staged）**：`lint-staged` 会对**它格式化过的文件**做 `git add`（日志里的 `prettier --write` 之后紧跟 `Applying modifications from tasks`）。因此"把可能有他人 hunk 的文件交给 lint-staged 格式化"与 `npx lint-staged --diff=…` 是同一类反向 `git add`；要么先与对方约定谁提交该文件，要么等它干净再动。
 - **验证**：用内容级复核定案——`git show 28781a420 -- <file> | Select-String '^@@'` 得到两个 hunk；`git show` 的 `^-` 行里出现对方特有的 `data-resource-book-all-page` / `allSections` 字样。这同时排除了另一种解释（"只是 prettier 重排"）：重排会表现为 `-`/`+` 成对出现且**语义相同**，而这里 `-` 掉的断言在 `+` 侧并不存在。
@@ -5495,3 +5548,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **真机判据**：点进任一栏目（或展开「所有资源」）时，**每一张**卡片都从它那一摞的位置/尺寸位移并缩放到自己的位置，而不只是总览里那 3 张；同一栏目里不同类型的两摞各自飞各自的卡。`prefers-reduced-motion: reduce` 下仍不播放动画（口径未改）。
 - **已知未覆盖**：① 子画布内直接切到另一个栏目（分页画布换栏目）时目标栏目的卡片在该次 `begin` 时未渲染、拿不到任何 First，整段转场仍按旧口径跳过（`play` 的 `!captured.entries.size` 早退），本次未改；② 真机动画观感由浏览器渲染，jsdom 只覆盖几何与调用契约，需要按上面那条判据人工确认一次。
 - **关联**：`apps/ai-game-creator-shell/src/view/project-development/resourceBookController.ts`（`begin` 的堆锚点 / `syncNodes` 的合成 First）、`resourceBookLayout.ts`（`allOpen` 列号）、`index.tsx`（宿主 `data-resource-book-stack-*`）、`apps/ai-game-creator-shell/tests/{resourceBookController,resourceBookLayout}.test.ts`、`tests/appSurface/project-development.suite.ts`、`docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md`。
+
+## 稳定版 AGC 复用开发栈必须核对 instance identity
+
+- 现象：端口和 `/healthz` 都正常，但 AGC 连接了另一个 worktree 的 API、SpacetimeDB 或旧 Vite，表现为登录、项目列表、Runner 状态与当前代码不一致。
+- 原因：健康检查只能证明“有服务响应”，不能证明服务属于当前工作树；旧 `.app/dev-stack.json` 可能没有当前 `repoRoot`、`instanceId` 和服务级 dataDir 身份。
+- 处理：先读取 `.app/dev-stack.json`，核对顶层 `repoRoot + instanceId`，再核对服务 `repoRoot + instanceId + dataDir + pid + port`；AGC Vite marker 还必须带 `repoRoot + processId + port`。任何字段缺失或不匹配都拒绝静默复用，改为启动当前工作树自己的服务或明确提示清理。
+- 验证：`scripts/dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 覆盖 snapshot identity 和旧状态拒绝复用；运行时记录实际端口、进程命令行和 dataDir，不要只记录 HTTP 200。

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

@@ -51,7 +51,7 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐
 
 ## AGC DirectProject 与 UI workflow
 
-- 新 Web 游戏为 `game/` 下的 npm + Vite + Phaser 4.2.1 工程，使用包导入且允许其它依赖；npm 预览与导出只读取 dist，运行素材需纳入构建，已有单 HTML/Godot 不自动迁移。
+- 新 Web 游戏为 `game/` 下的 npm + Vite + Phaser 4.2.1 工程，使用包导入且允许其它依赖；npm 预览与导出只读取 dist，运行素材需纳入构建。单 HTML → Phaser 迁移固定走 DirectProject：文件落盘后先用受控 `project.bootstrap` 在 `game` 执行无参数 `npm install`，再用支持相对 cwd 的 `project.verify` 构建并确认 `game/dist/index.html`，已有单 HTML/Godot 不通过 JSON Generator 伪装成 npm 工程。
 
 - 通用 Agent Rust 分层为 `agent-runtime-core`（catalog、执行生命周期、ToolHost/spawn/all-join/Provider 契约）、`agent-runtime-orchestration`（动态无环任务图、ready、依赖波次、返工下游闭包和受限自主扩图提案）与 `platform-agent` 游戏适配器；循环返工通过新 pass / epoch 表达，不在单张依赖图中建立回边。LLM 可经宿主结构化 function call 提出新增节点/边，编排层只生成经校验的新候选图，epoch 与持久化仍由宿主掌控。
 - DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP，并在启动时额外读取客户端扩展仓库中已启用的第三方 MCP 独立项。第三方 STDIO/HTTP 配置只写入本次隔离 `CODEX_HOME`，单项非 required，启停、重命名和内容指纹进入 app-server pool identity；完整 Plugin Runtime、hooks/apps 和单文件脚本手动指定入口仍关闭。Skill 正文与 references 由 Codex 原生按需读取；`agc_tools` 负责标准美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`；付费资源调用仍由客户端绑定回合、幂等账本、请求上限和投影权威。