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

2026-09-14 17:41:36 +08:00
parent ad8f42a68f 2566ae705f
commit b082addc34
70 changed files with 3601 additions and 611 deletions
@@ -30,6 +30,8 @@
 - [LLM 累计额度结算](./technical/【技术方案】LLM累计额度结算-2026-09-05.md)：Router 累计额度、首次基线与原子钱包结算。

 - [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)：当前 DirectProject、受控语义工具、UI workflow、资源和运行时合同。
+- [AGC 异步操作可恢复闭环](./【技术方案】AGC异步操作可恢复闭环-2026-09-14.md)：认证响应体、最近项目检查和首页自动创建的超时、逐项恢复与跨页防重合同。
+- [AGC 客户端稳定版生命周期大切换](./【技术方案】AGC客户端稳定版生命周期大切换-2026-09-14.md)：统一 operation、认证/Runner、项目入口、本地恢复和 dev-stack 身份边界。
 - [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：新单 Agent 策划会话、GDD 策略、未来 MCP/Skill 兼容插槽、阶段任务与退役验收合同。
 - [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。
 - [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
@@ -0,0 +1,26 @@
+Version: 1.0
+Status: implemented; real-project runtime smoke pending
+Date: 2026-09-14
+Parent Milestone: docs/project-memory/plans/【里程碑】DirectProject Phaser迁移闭环-2026-09-14.md
+
+## 修改顺序
+
+1. 扩展 shared command contract 与原生工具 schema。
+2. 增加 `project.bootstrap` 的安全校验、npm install 执行、审计与分发。
+3. 扩展 `project.verify` 的 cwd/package/dist 门禁和提示词。
+4. 更新 DirectProject 迁移工程指导与前端命令显示。
+5. 补充定向测试并运行 typecheck、Rust 检查、编码与 diff 检查。
+
+## 验证命令
+
+- `npm run ai-game-creator-shell:typecheck`
+- `cargo test -p ai-game-creator-shell project_bootstrap`
+- `cargo test -p ai-game-creator-shell project_verify`
+- `npm run check:encoding`
+- `git diff --check`
+
+## 风险与回滚
+
+- 旧 `project.verify` 输入不带 cwd 时保持项目根行为。
+- bootstrap 不修改 command.exec 的 npm 白名单；失败关闭并返回可诊断错误。
+- 若 sandbox 网络能力无法在当前平台验证，仅保留实现与单测证据，不宣称真实安装通过。
@@ -0,0 +1,37 @@
+# 【实施计划】项目客户端占用锁收敛-2026-09-14
+
+Version: 1
+Status: in-progress
+Date: 2026-09-14
+Milestone: `【里程碑】项目客户端占用锁收敛-2026-09-14.md`
+
+## 代码边界
+
+- `apps/ai-game-creator-shell/src-tauri/src/project/write_lock.rs`
+- `apps/ai-game-creator-shell/src-tauri/src/runner/project_owner.rs`
+- `apps/ai-game-creator-shell/src-tauri/src/runner/protocol.rs`
+- 锁恢复、Runtime 写入和 Runner owner 定向测试
+
+## 修改顺序
+
+1. 统一同进程嵌套调用的项目锁语义，禁止自等待。
+2. 收窄复用判据：按 `pid` 放行会放过本进程其它线程的并行写，改为按“当前线程就是真实持锁线程”判定重入，并保住同进程跨线程的等待与终态占用。
+3. 盘点并迁移 Runner 的项目级 owner 文件到统一锁，保留诊断投影与跨 boot 恢复。
+4. 删除重复项目级锁路径及其专属调用，保留底层原子写和 Git 锁。
+5. 补齐同进程重入、同进程跨线程争用、跨进程占用、崩溃恢复和锁释放测试。
+
+## 验证命令
+
+- `cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check`
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --test-threads=1`
+- `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_write_lock --no-default-features`
+- Runner owner 与 response stream 相关定向测试
+- `npm run check:encoding`
+- `git diff --check`
+
+## 风险与回滚点
+
+- Runner 与 GUI 可能是不同进程；统一锁前必须验证同一客户端不会互相阻塞。
+- 旧 `.agent/runtime/execution-owner.lock` 残留需要按 PID/启动身份安全回收，不能直接删除。
+- 复用判据按线程判定：出现同进程跨线程重入的现场时先按 `*_locked` 入口处置，不要把判据退回按 `pid` 一律放行（那会放过并行写，见里程碑「边界」末条）。
+- 若跨 boot 恢复或 GUI/Runner 联动回归，回滚统一路径迁移，保留已验证的同进程重入修复。
@@ -0,0 +1,28 @@
+Version: 1.0
+Status: implemented; real-project runtime smoke pending
+Date: 2026-09-14
+Parent Spec: docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+
+## 目标
+
+为 DirectProject 建立单 HTML 到 Phaser 4 + Vite 的可运行迁移闭环：项目文件真实落盘、受控依赖初始化、`game` 子目录构建验证、`game/dist` 预览与桌面/移动验收。
+
+## 边界
+
+- DirectProject 迁移请求固定使用 `workspaceMode=DirectProject`，不再通过 JSON Generator 的 `gameHtml` 协议生成 npm 工程。
+- `project.bootstrap` 只允许在项目内 `game` 目录执行无参数 `npm install`，读取并记录 package/lock 指纹。
+- `project.verify` 支持相对 `cwd`，构建验证必须读取该目录 package.json 的原始脚本并确认 `dist/index.html`。
+- 预览继续只读取构建产物；不实现自动迁移未知游戏玩法语义或真实 Provider 生成。
+
+## 验收标准
+
+1. 命令契约、原生工具 schema、运行时分发、权限面板和提示词包含 `project.bootstrap`。
+2. bootstrap 拒绝越界 cwd、非 `game` 目录、参数注入和缺失/非法 package 文件，并在成功后返回依赖指纹。
+3. `project.verify` 能在 `cwd=game` 执行原样 `npm run build`，成功条件包含 `game/dist/index.html`。
+4. DirectProject 提示明确要求 Phaser 4.2.1、`import Phaser from 'phaser'`、Vite 输出 `game/dist` 及完整玩法迁移。
+5. 定向 Rust/TypeScript 测试、类型检查、编码检查和 `git diff --check` 通过；无法运行真实 Provider/浏览器时明确记录。
+
+## 依赖
+
+- 现有 project command sandbox、verification gate、preview resolver 和 command run/audit 持久化。
+- 用户选择的真实项目目录必须包含 `game/index.html` 才能执行实际迁移。
@@ -0,0 +1,30 @@
+# 【里程碑】项目客户端占用锁收敛-2026-09-14
+
+Version: 1
+Status: in-progress
+Date: 2026-09-14
+Parent Spec: `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`
+
+## 目标
+
+项目只保留一个面向客户端占用的项目级跨进程锁，防止多个客户端同时打开同一项目；同一客户端进程内**同一条写调用链（同一线程）的嵌套调用**复用既有项目锁，不因自身持锁进入等待。
+
+## 边界
+
+- 项目客户端占用锁与项目写入调用的职责统一，跨进程竞争仍返回占用语义。
+- Agent DB、session lane、manifest 原子写和 Git 自身的底层一致性机制不在本里程碑删除范围内。
+- 不改变项目 revision、权限、幂等、恢复和数据格式合同。**本进程其它线程的并发写入必须继续串行化**：按 `pid` 一律返回 advisory guard 会放过并行写，直接违反本边界（见验收标准第 2 条）。
+
+## 验收标准
+
+- 同一线程（同一条写调用链）嵌套取得项目锁立即返回 advisory guard，不等待、不删除真实持有者锁。
+- 本进程另一条线程持锁（模拟“另一个写通道/另一个客户端”的既有用例形态）时仍保持等待与终态占用：项目 revision 侧车、steer 序号分配、一致快照读、pending sidecar 复核和恢复安装不得被复用判据放过。
+- 不同进程持有项目锁时仍保持占用失败与残留回收判据。
+- 客户端项目占用入口与 Runtime 写入入口不会各自维护第二个项目级锁文件。
+- 锁释放后下一客户端可重新取得锁。
+- 定向 Rust 锁测试、`cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过；锁语义变更必须跑 `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --test-threads=1` 全量，定向用例覆盖不到 `project_tools` / `command_runtime` / `parallel_actions` / `runtime_state` / `response_stream` / `direct_tool_bridge` / `ui_editor::persistence` 里的锁不变量。
+
+## 未决事项
+
+- Runner 的 `execution-owner.lock` 如何迁移到统一客户端占用锁，需要补充跨进程启动、恢复和诊断测试后再落地。
+- 同进程**跨线程**重入（持锁调用链在 `await` / `spawn_blocking` 之后于其它线程再次取锁）仍会走有界等待，预算耗尽时报“项目正在被其他写操作占用”。发现这类现场时按 2026-08-27 的既有处置改用 `*_locked` 入口复用已有 guard（`project-memory/shared-memory/pitfalls.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)。
@@ -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 镜像缓存，再重跑门禁。
@@ -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。
@@ -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`；付费资源调用仍由客户端绑定回合、幂等账本、请求上限和投影权威。
@@ -1761,4 +1761,4 @@ V1.54 的公共编排层可以在运行前构造动态 DAG，但 LLM 在执行

 本文中 V1.1/V1.52 关于 app-server 全局关闭 native shell、network、browser、plugin 和 multi-agent 的表述继续适用于 ToolHost/DirectHome 与 legacy Runtime；不再作为 DirectProject 的现行实现。DirectProject 恢复原生文件/搜索/命令、图片查看和 Skill，始终注入审核后的 `agc_tools` MCP，并可在启动时从客户端扩展仓库接入用户已启用的独立第三方 MCP 配置；第三方配置不进入全局 Codex home，不开启完整 Plugin Runtime。平台美术、资源投影、浏览器试玩、受控搜索、付费副作用和 durable delegation 仍必须走 AGC 权威链路。

-DirectProject 的写入根固定为真实 `game/`，审批策略为 `never`，原生命令网络保持关闭，联网资料继续走受控 `agc_web_search`；shell 使用 Codex `shell_environment_policy` 的 glob 排除 API key、proxy、loopback bridge 和受控开关。配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只由 AGC 本地 provider proxy 持有，Codex 仅获得连接级随机代理令牌；无法安全代理的 OAuth `auth.json` 继续关闭 native shell/unified exec。Codex 原生子 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 以及未接入 AGC 证据链的浏览器/电脑控制保持关闭。系统提示词只传入最小身份、工作区、Skill 索引和副作用边界，不再批量注入源码快照或 Skill 正文。sandbox writableRoots 不提供 deny-read；`.agent` 与 `../assets` 的不可读约束仍需通过 prompt/Skill 行为合同和真实 smoke 验证，不能误称为 OS 强制隔离。
+DirectProject 的历史写入根规则由 2026-09-14 覆盖：现使用 `danger-full-access` sandbox，取消 `workspaceWrite(writableRoots=...)` 与文件变更批准根白名单；项目根继续作为 cwd、连接池和审计身份根。审批策略为 `never`，原生命令网络随完整 sandbox 开放；联网资料仍可走受控 `agc_web_search`；shell 使用 Codex `shell_environment_policy` 的 glob 排除 API key、proxy、loopback bridge 和受控开关。配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只由 AGC 本地 provider proxy 持有，Codex 仅获得连接级随机代理令牌；无法安全代理的 OAuth `auth.json` 继续关闭 native shell/unified exec。Codex 原生子 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 以及未接入 AGC 证据链的浏览器/电脑控制保持关闭。系统提示词只传入最小身份、工作区、Skill 索引和副作用边界，不再批量注入源码快照或 Skill 正文。sandbox writableRoots 不提供 deny-read；`.agent` 与 `../assets` 的不可读约束仍需通过 prompt/Skill 行为合同和真实 smoke 验证，不能误称为 OS 强制隔离。
@@ -40,9 +40,9 @@ DirectProject 自身的 `read_direct_project_conversation` 也必须在 blocking

 新建 Web 游戏使用 npm 工程：默认 `game/package.json` 声明 Phaser 4.2.1 和 Vite 构建工具，源码使用 `import Phaser from 'phaser'`，`package-lock.json` 由 npm 维护。默认脚手架文件位于 `game/`，包含 `index.html`、`game.js`、`style.css`、`vite.config.js` 和 npm 配置/锁文件；已有根目录 npm 工程沿用原根，可按需求拆分模块并添加任意其它 npm 依赖，不设置包名白名单。客户端不手工分发 Phaser bundle，不用 import map 模拟 package 导入。

-Agent 在包含 `package.json` 的目录执行 `npm ci`（依赖变更使用 `npm install`）和 `npm run build`；默认可从工作区根执行 `npm --prefix game ci` 与 `npm --prefix game run build`。DirectProject 保持 workspace-write 目录边界并开放网络，以支持 npm 依赖解析和安装；凭据仍由客户端代理持有，不进入项目或原生命令环境。其它执行模式维持现有权限。新游戏完成后执行 `npm run build` 并用真实浏览器试玩；依赖安装与构建失败必须反馈真实错误，不能回退成未解析裸模块导入的静态页面。
+Agent 在包含 `package.json` 的目录执行 `npm ci`（依赖变更使用 `npm install`）和 `npm run build`；默认可从工作区根执行 `npm --prefix game ci` 与 `npm --prefix game run build`。DirectProject 保持 workspace-write 目录边界并开放网络，以支持 npm 依赖解析和安装；凭据仍由客户端代理持有，不进入项目或原生命令环境。依赖初始化必须通过受控 `project.bootstrap`（固定 `cwd=game`、无参数 `npm install`、只读取 package/lock 并记录 SHA-256 指纹），不得放开通用 `command.exec npm install`。构建使用 `project.verify` 的相对 cwd（例如 `cwd=game`）；`build` 通过后还必须存在 `game/dist/index.html` 才能签发验证凭证。其它执行模式维持现有权限。新游戏完成后执行 `npm run build` 并用真实浏览器试玩；依赖安装与构建失败必须反馈真实错误，不能回退成未解析裸模块导入的静态页面。

-npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.html`，静态 smoke 校验构建入口及本地文件引用，实际可玩性由浏览器验证。预览服务与导出读取该构建目录，所有运行素材必须由构建纳入 dist；npm 预览不回退读取源码或项目素材目录，保证试玩与导出一致。源码投影包含 package、锁文件、配置和真实游戏源码，排除 `node_modules/`、`dist/`、控制文件与凭据；npm 试玩包将 dist 文件映射到 `game/` 并附带发布说明，不包含源码依赖安装目录。现有单 HTML 项目不自动迁移，Godot 项目保持原合同。旧 JSON Generator 仅接受已初始化的单 HTML 项目，npm 项目或新建请求在调用 LLM 前明确拒绝并引导使用 DirectProject，避免静态草案伪装为 npm 构建产物。本节覆盖下文仅适用于旧单 HTML 产物的 Canvas API、手写动画循环和禁止外部本地脚本要求。
+npm 游戏的可预览产物固定为对应 package 目录下的 `dist/index.html`，静态 smoke 校验构建入口及本地文件引用，实际可玩性由浏览器验证。预览服务与导出读取该构建目录，所有运行素材必须由构建纳入 dist；npm 预览不回退读取源码或项目素材目录，保证试玩与导出一致。源码投影包含 package、锁文件、配置和真实游戏源码，排除 `node_modules/`、`dist/`、控制文件与凭据；npm 试玩包将 dist 文件映射到 `game/` 并附带发布说明，不包含源码依赖安装目录。单 HTML → Phaser 迁移必须在 DirectProject 中完成：先识别 `game/index.html`，再将状态、输入、敌人/守卫、波次、胜负、重开和画布绘制迁移到 Phaser Scene 与 update 循环，并落盘 `game/package.json`、`game/game.js`、`game/style.css`、`game/vite.config.js` 和锁文件；不得把迁移目标伪装成 `gameHtml`。现有单 HTML 项目不自动迁移，Godot 项目保持原合同。旧 JSON Generator 仅接受已初始化的单 HTML 项目，npm 项目或新建请求在调用 LLM 前明确拒绝并引导使用 DirectProject，避免静态草案伪装为 npm 构建产物。本节覆盖下文仅适用于旧单 HTML 产物的 Canvas API、手写动画循环和禁止外部本地脚本要求。

 ## 2026-09-02 项目名称显示与自动提炼

@@ -1271,9 +1271,15 @@ game-project/

 ## DirectProject 工具权限现行覆盖（2026-08-24）

-本文早期关于“DirectProject 关闭通用 shell、原生网络和主动工具”的描述属于迁移前基线，现由以下覆盖规则取代：DirectProject 仅在真实 `game/` cwd 与 `workspaceWrite(writableRoots=[game])` 内恢复 Codex 原生文件/搜索/命令、图片查看和 Skill；其余 ToolHost/DirectHome 合同不变。客户端审核的 `agc_tools` MCP 继续承担平台美术、资源登记、去背景、浏览器试玩和受控搜索，并保留项目锁、幂等账本、下载校验、恢复与投影权威。
+本文早期关于“DirectProject 关闭通用 shell、原生网络和主动工具”的描述属于迁移前基线；2026-09-14 起，DirectProject 的 Codex sandbox 与审批规则由下方“完整访问覆盖”取代。其余 ToolHost/DirectHome 合同不变。客户端审核的 `agc_tools` MCP 继续承担平台美术、资源登记、去背景、浏览器试玩和受控搜索，并保留项目锁、幂等账本、下载校验、恢复与投影权威。

-DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过泛化 ToolHost 包装；原生命令网络保持关闭，联网资料继续走受控 `agc_web_search`。多 Agent、Apps、完整插件 Runtime、hooks、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制仍关闭，避免绕过 AGC durable delegation、浏览器证据和副作用审计；图片生成通过客户端审核的 `agc_tools.agc_generate_image` 暴露普通单图、角色图、视觉规范图和 UI 设计图，完整游戏美术包继续使用 `agc_tools.taonier_prepare_game_art`，两者都复用同一客户端登录态、幂等账本、下载校验和 manifest/revision 投影，不开放 Codex 原生 image tool。app-server 使用隔离 `CODEX_HOME`：内置 `agc_tools` 由客户端启动参数注入，用户在客户端扩展列表启用的独立第三方 MCP 以原生配置写入该次隔离 home；全局 Codex MCP、禁用项、Plugin hooks/apps 和其它插件能力不进入 DirectProject。第三方项固定非 required，配置或启动失败只记录该项，不替换 `agc_tools`；provider session token、工具桥地址和受控搜索标记不得通过第三方 MCP 的环境转发字段泄露。配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只由 AGC 本地 provider proxy 持有，Codex 仅使用连接级随机代理令牌；无法安全代理的 OAuth `auth.json` 继续关闭 native shell/unified exec。`agc_tools` 的平台授权由 AGC 客户端当前登录会话和受控后端完成，普通客户端不得把 DirectProject 请求改成外部 API Key 请求；401/403 只投影为客户端登录或权限异常，不向用户索要凭据或暴露内部 URL。shell 子进程采用 `shell_environment_policy` core 继承及 secret/proxy/bridge 排除，provider key 和桥接凭据不得进入命令环境。系统提示词不再预注入项目源码快照或 Skill 正文，Codex 按需读取当前 cwd 文件。
+## DirectProject Codex 完整访问覆盖（2026-09-14）
+
+DirectProject 现明确采用 Codex app-server 的 `danger-full-access` sandbox：thread 使用 `sandbox="danger-full-access"`，turn 使用 `sandboxPolicy.type="dangerFullAccess"`，不再发送 `workspaceWrite`、`writableRoots` 或项目根文件批准白名单。DirectProject 收到 app-server 的文件变更、命令执行和权限请求时直接接受，Codex 原生能力不再按项目路径做二次白名单裁剪；用户选择的项目目录仍作为 cwd 和 AGC 业务身份根，用于连接池、审计与客户端受控 MCP 的项目绑定。
+
+这项覆盖只改变 Codex 原生 app-server 的 sandbox 与审批边界：首页只读对话、AGC `agc_tools` MCP 的业务授权、Provider 凭据隔离、Runtime 审计与客户端 `agc_write_file` 的产品契约继续有效。系统提示词不再把 `.agent/`、`.git/`、项目外路径等描述为 Codex 原生能力禁区，但仍要求不要把 Token、Cookie、auth.json、`.env` 或 Runtime 私有控制面主动输出到对话、工具参数和日志。
+
+DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过泛化 ToolHost 包装；原生命令网络随完整 sandbox 开放；联网资料仍可走受控 `agc_web_search`。多 Agent、Apps、完整插件 Runtime、hooks、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制仍关闭，避免绕过 AGC durable delegation、浏览器证据和副作用审计；图片生成通过客户端审核的 `agc_tools.agc_generate_image` 暴露普通单图、角色图、视觉规范图和 UI 设计图，完整游戏美术包继续使用 `agc_tools.taonier_prepare_game_art`，两者都复用同一客户端登录态、幂等账本、下载校验和 manifest/revision 投影，不开放 Codex 原生 image tool。app-server 使用隔离 `CODEX_HOME`：内置 `agc_tools` 由客户端启动参数注入，用户在客户端扩展列表启用的独立第三方 MCP 以原生配置写入该次隔离 home；全局 Codex MCP、禁用项、Plugin hooks/apps 和其它插件能力不进入 DirectProject。第三方项固定非 required，配置或启动失败只记录该项，不替换 `agc_tools`；provider session token、工具桥地址和受控搜索标记不得通过第三方 MCP 的环境转发字段泄露。配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只由 AGC 本地 provider proxy 持有，Codex 仅使用连接级随机代理令牌；无法安全代理的 OAuth `auth.json` 继续关闭 native shell/unified exec。`agc_tools` 的平台授权由 AGC 客户端当前登录会话和受控后端完成，普通客户端不得把 DirectProject 请求改成外部 API Key 请求；401/403 只投影为客户端登录或权限异常，不向用户索要凭据或暴露内部 URL。shell 子进程采用 `shell_environment_policy` core 继承及 secret/proxy/bridge 排除，provider key 和桥接凭据不得进入命令环境。系统提示词不再预注入项目源码快照或 Skill 正文，Codex 按需读取当前 cwd 文件。
 ## 2026-08-24 AGC UI 原型桥接与自主 UI workflow

 - 2026-08-24 起，`ui-prototype` 与 UI 编辑器的 `UI` JSON 资源明确分离。设计图生成后必须由白名单 `ui.workflow.run` 按页面执行 `prepare → recognize → status → finalize`：为每个功能页面创建并关联 `UI` JSON，载入页面设计图和已登记图片/图标/字体，调用 UI Editor 的 provider-backed 结构识别、多树合并与分批自动切分素材，持久化 State/revision，写入 `game/` 应用标记，并把 `reference-ready → structure-ready → merge-ready → binding-ready → application-ready → completed` 各阶段的 `generationKind` 和 manifest revision 投影给客户端。Provider 未配置、请求失败、工具调用缺失、结果不匹配、未知字体引用或未产出可渲染组件时保留最近真实阶段并返回 blocker，不得使用 deterministic seed 冒充完成；自动切分达到返工上限的 problematic 节点则回写 UI State 的 `component_status = NeedReview(...)`，作为已尽力完成、交由用户在 UI 编辑器中处理的结果。工作台点击 `ui-prototype` 时通过 `ensure_ui_design_resource_for_prototype` 幂等补齐关联资源；工作流完成后自动打开首个页面的 UI 编辑器 `asset-separation` 最终阶段，交给用户检查和手动调整。UI 编辑器独立的语义建议请求也必须复用统一 LLM 传输选择，`llm.stream=true` 时发送 `stream=true` 并聚合完整工具调用后再校验结果。只生成图片、登记空 JSON 或进入普通图片画布均不构成 UI 工作流完成，详见 [`【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`](../【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md)。
@@ -1363,3 +1369,8 @@ DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过
 - **成功后行为**：重读 manifest，**不切换版本**（没有新版本可切），**不自动重载 / 重启运行中的预览**（PRD §3.2 末条），不做运行时资源重映射。可见变化只有资源卡「当前使用」高亮移到替换素材、`@` 面板「当前版本素材」更新。
 - **已知代价（用户已确认接受）**：**替换历史不可回溯**——替换前身份只剩那条审计与 manifest 的 `.previous` 副本；需要"某版本历史上换过什么"时要另立切片（PRD §3.2 / §5.3 保留为未来合同正是为此）。
 - **验证**：绑定改写通道定向 7 条（`project/manifest/version_binding_rewrite_tests.rs`）+ 替换定向 8 条 + `shared-contracts` 20 条。**变异验证**：① 去掉「未放行版本整条相等」→ 两周转红；② 放行集合改成整个版本数组 → 「未放行版本」转红；③ 去掉长度检查 → 「不增不删」转红；④ 准入删掉 category → 硬门禁与候选两条转红；另有 ⑤ 改回"原地改既有版本但绕过放行口"→ 被「项目版本记录写入后不可修改、删除或重排」拦下。前端 13 条（模型 9 + 真链路 4）。AGC 全量 1231 passed / 4 skipped / 0 failed；共享美术画布组件 1385 passed；`npm run ai-game-creator-shell:typecheck`（含 check-config）、`cargo check --locked --all-targets`、`npm run check:encoding`、`git diff --check` 全绿。`/api/external/v1`、SpacetimeDB schema、`packages/shared` 与 `shared-contracts` 的 wire DTO、manifest 结构、布局 sidecar schema 均未改动。
+
+## 2026-09-14 项目客户端占用锁收敛
+
+项目锁职责收敛为“客户端占用项目”这一事实：跨进程竞争继续沿用现有占用、残留回收和权限分类。同进程复用的判据收窄到**同一条写调用链（同一线程）重入**——本线程已落盘持有该项目的 `.agent/project.lock` 时再次取锁，返回 advisory guard，不再等待自身持有的锁。本进程**其它线程**的写入通道仍走有界等待与终态占用：项目 revision 侧车、steer 序号分配、一致快照读、pending sidecar 复核和恢复安装都依赖这把锁把同进程的并发写入串行化，按 `pid` 一律放行会让它们静默竞态。自主游戏构建流水线沿用既有的并行专家动作豁免。Runner 的 `.agent/runtime/execution-owner.lock` 迁移到统一项目占用锁仍属于进行中的里程碑，完成前不改变其恢复诊断合同。
+
@@ -36,7 +36,7 @@ npm run dev
 - 主站 Vite。
 - 后台 Vite。

-`npm run dev` 和单模块 `npm run dev:web`、`npm run dev:api-server`、`npm run dev:bgfilter-worker`、`npm run dev:spacetime`、`npm run dev:admin-web` 启动后都会更新根目录 `.app/dev-stack.json`。该文件记录本次命令、数据库、更新时间，以及 `spacetime`、`api-server`、`bgfilter-worker`、`web`、`admin-web` 的 `pid`、监听 host / port、可访问 URL、启动状态和当前命令。`.app/` 是本地运行态目录，不提交 Git；端口漂移、服务重启或子进程退出后以该文件里的实际状态为准。
+`npm run dev` 和单模块 `npm run dev:web`、`npm run dev:api-server`、`npm run dev:bgfilter-worker`、`npm run dev:spacetime`、`npm run dev:admin-web` 启动后都会更新根目录 `.app/dev-stack.json`。该文件记录本次命令、数据库、更新时间，以及 `spacetime`、`api-server`、`bgfilter-worker`、`web`、`admin-web` 的 `pid`、监听 host / port、可访问 URL、启动状态和当前命令；稳定版状态还记录顶层 `repoRoot + instanceId`，每个服务记录 `repoRoot + instanceId + dataDir`，与端口组成复用身份。`.app/` 是本地运行态目录，不提交 Git；端口漂移、服务重启或子进程退出后以该文件里的实际状态为准。缺少身份字段或身份不匹配的旧状态不得被 AGC 静默复用。

 通过 `nohup` 在仓库根目录启动 dev 栈且未显式重定向 stdout / stderr 时，默认 `nohup.out` 会持续收集 SpacetimeDB、api-server、bgfilter-worker、主站 Vite 和后台 Vite 的整套 dev 栈输出；该文件已被主站 Vite watcher 和 Git 忽略，避免日志追加触发页面刷新循环，重启主站 Vite 后生效。若把输出显式重定向到其它仓库内文件（例如 `> dev.out`），该自定义文件不会自动获得同样的 watcher 保护，应改为写到 Vite root 之外，或同步配置精确的忽略规则。

@@ -62,7 +62,7 @@ Linux 本机多用户并发开发时，`npm run dev`、`npm run dev:*` 单模块

 后端日志默认写入 `logs/api-server/`，独立 BgFilter worker 日志默认写入 `logs/bgfilter-worker/`。后端 API smoke 使用 `npm run dev:api-server`，先检查 BgFilter worker `/readyz`，再检查 API `/healthz`；需要确认 API 实例可接生产流量时检查 API `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。

-AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。端口健康不等于归属正确：复用前还必须证明端口上的监听进程属于当前工作树（Windows 按 `server-rs/target/debug/api-server.exe` 绝对路径与 SpacetimeDB `--data-dir` 校验，探测不可用时退化为旧行为），无法证明归属时一律不复用，改为启动本工作树自己的后端并在需要时端口漂移；否则上个工作树 Ctrl+C 残留的后端会被当成自己的后端复用，改了数据库的工作树会连到旧库。启动器在创建原生窗口前预检最终地址；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
+AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。端口健康不等于归属正确：复用前还必须证明端口上的监听进程属于当前工作树（Windows 按 `server-rs/target/debug/api-server.exe` 绝对路径与 SpacetimeDB `--data-dir` 校验，探测不可用时退化为旧行为），无法证明归属时一律不复用，改为启动本工作树自己的后端并在需要时端口漂移；否则上个工作树 Ctrl+C 残留的后端会被当成自己的后端复用，改了数据库的工作树会连到旧库。启动器在创建原生窗口前预检最终地址；AGC Vite marker 同时提供 `repoRoot + processId + port`，与 `.app/dev-stack.json` 的 `instanceId` 和 API target 交叉核对；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。

 Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：选定地址上若已有旧 Vite，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Windows 下每个长驻服务都经 `cmd.exe /d /s /c` 包装层启动，Ctrl+C 会先杀掉包装层（退出码 `0xC000013A`），因此清理不能只看直接子进程是否存活：`taskkill` 对已退出的 PID 只会失败，必须继续按记录下来的根 PID 遍历，并在退出时按本工作树 `api-server.exe` 绝对路径（以及本次自己拉起的 SpacetimeDB `--data-dir`）做一次身份兜底清扫；`scripts/dev-windows-process.mjs` 是这套判定的唯一实现。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对控制台输出的 AGC Vite 实际地址及其 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。

@@ -262,16 +262,20 @@ npm run check

 ### Gitea Actions PR 门禁

-仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成四个必须通过的 job：
+仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成十一个必须通过的 job。job 声明顺序就是 runner 领取顺序，因此把 4 个 AGC 壳 Rust 分片 job 排在最前：并发槽位不足时它们必须最先开始，AGC 侧的关键路径才由自己而不是由排队决定。

 所有 CI job 和 Jenkins Web Build 在根 workspace 安装前都必须确认 `npm --version` 为 `10.9.7`。Gitea job 使用预构建镜像内的固定版本；Jenkins Web Build 在每个独立 `bash -lc` 中 source `scripts/jenkins-prepare-npm-env.sh`，首次为 Jenkins 运行用户的版本隔离目录引导同版 npm，后续复用并把该 `bin` 放到 `PATH` 首位。旧固定镜像缺少版本元数据时只能报告 `npm_version=partial` 并由当前 job 的根 `npm ci` 继续校验 lock，不能把过渡状态当作工具链已闭合。

 - `Repository checks`：调用唯一入口 `npm run check:repository-ci`，执行 `npm run lint`、AI 游戏创作壳 AppSurface 定向测试、主站与后台生产构建和提交差异空白检查。本地 master `pre-push` 复用同一入口，禁止在 workflow 与 hook 中维护两份近似命令。
 - `Frontend tests`：按唯一根 workspace lockfile 执行一次干净的 `npm ci`，再独立执行根 `npm run test`、`npm run bgfilter-worker:smoke-test`、`npm run check:production-health-patrol`、`npm run check:production-api-release` 和 `npm run check:production-api-deploy`，让 Vitest、Node test smoke harness 及不依赖真实服务的生产巡检 / 发布 / 部署行为 fixture 在 Gitea job 中持续执行；其中 `.test.mjs` 使用 Node test runner，不依赖 Vitest 的 `scripts/**/*.test.ts` 收集规则。
 - `Backend tests`：先对 `server-rs/Cargo.lock` 执行带 5 次整命令级有界重试的 `cargo fetch --locked`，再执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`、`cargo test --locked -p spacetime-module --no-fail-fast`、`api-server --all-targets` 编译和 `cargo check --locked -p spacetime-module`；普通 workspace host 测试排除 `spacetime-module` 以避免其 `spacetime-types` feature 统一污染领域 crate，模块自身的纯单元测试通过独立 package test 纳入门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，不能把 host 链接支持当作运行时替身。依赖准备必须位于会触发 Cargo build 的 DDD / 产物边界门禁之前，避免锁新增依赖未命中镜像缓存时绕过既有下载重试。runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。
- `Native shell tests`：按唯一根 workspace lockfile 安装全部 App 依赖后执行 `npm run check:native-shells`，对所有触发方式一致覆盖微信壳、Expo 和 Tauri 的完整验收，并执行 `npm run ai-game-creator-shell:check` 与 AI 游戏创作壳 release build smoke；最后确认桌面壳与 AI 游戏创作壳的 `Cargo.lock` 都没有被构建过程改写。共享 Agent Runtime 后台锁 suite 固定 `--test-threads=1`，不能用并行偶发失败后的逐项通过替代整套稳定门禁。
+- `Native shell tests`：按唯一根 workspace lockfile 安装全部 App 依赖后，用 `npm run check:native-shells:contract`、`npm run check:native-shells:shells` 和 `npm run check:native-shells:release` 分别执行静态契约、H5 / 微信 / Expo / Tauri 桌面壳运行时门禁，以及依赖发布产物的构建 smoke，最后确认桌面壳与 AI 游戏创作壳的 `Cargo.lock` 都没有被构建过程改写。
+- `AI game creator shell web tests`：执行 `npm run check:native-shells:agc-web`（即 `npm run ai-game-creator-shell:check:web`：AGC 壳 typecheck 与壳内测试）。该分组不触碰 Cargo，因此不预热 Rust 依赖。
+- `AI game creator shell Rust shard 1/4` ~ `4/4`：四个片 job 各自只预热 AGC 壳自己那份锁定依赖（`apps/ai-game-creator-shell/src-tauri/Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`），然后执行 `npm run check:native-shells:agc-rust-shard-<i>`（即分片运行器的 `--shard-index=<i>`）：AGC 壳 bin target 的 2466 条 Rust 单测按 `--list` 名单排序后切 4 片，每个 job 只跑自己那片，片内保持 `--test-threads=1`、各片独立 `TMPDIR`，片与片之间靠 job 级并发摊开；每个 job 都会自校验「片并集等于全集且互斥」。**不要**改回「一个 job 里多进程并行这几片」：同一容器内它们共享 `HOME`、target 与固定临时路径，实测（run 2102）比整套串行还慢。这些 job 只用 cargo 与 node 内建模块，因此不装 npm 依赖。
+- `AI game creator shell Rust smoke`：同样只预热 AGC 壳那份锁定依赖，执行 `npm run check:native-shells:agc-rust-smoke`（即 `npm run ai-game-creator-shell:agent-run:smoke`）。smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`，单独一个 job 以免把已经压到分钟级的片 job 拖长；只用 cargo 与 node 内建模块（脚本只 import `node:*`），因此不装 npm 依赖。
+- `AI game creator shell Rust crates`：预热 `server-rs/Cargo.toml` 与两个无锁独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）后执行 `npm run check:native-shells:agc-rust-crates`（即 `npm run ai-game-creator-shell:check:rust:crates`），覆盖 `agent-runtime-core`、`agent-runtime-orchestration`、`platform-llm` 与 `shared-contracts`。这四条命令用的是 server-rs workspace 与独立 crate 的 manifest，属另一套依赖图，因此单独一个 job，也只跑 cargo、不装 npm 依赖。

-四个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 BgFilter worker smoke harness、无密钥生产巡检 / 发布 / 部署行为 fixture、server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。
+十一个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 BgFilter worker smoke harness、无密钥生产巡检 / 发布 / 部署行为 fixture、server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。客户端门禁的拆分口径是 `scripts/check-native-shells.mjs` 的 `--groups=`：十个分组（`contract`、`shells`、`agc-web`、`agc-rust-crates`、`agc-rust-shard-1` ~ `agc-rust-shard-4`、`agc-rust-smoke`、`release`）各自对应一个 `check:native-shells:<group>` 根脚本，并在 workflow 的某个 job 里被恰好调用一次；不带 `--groups=` 时脚本仍然串行跑全部分组，本地语义不变。`scripts/project-ci-workflow.test.ts` 会同时校验分组清单、根脚本内容、job 覆盖与分片运行器，新增分组必须三处同步。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。

 PR checkout 必须保留完整 Git 历史，并把 PR base SHA 传给 `SPACETIME_SCHEMA_BASE_REF`。`check:spacetime-schema` 依赖该基线识别已有表字段删除、改名、重排和改类型；事件给出的基线缺失或本地不可解析时必须直接失败，不能退化为空差异检查。Gitea 的 PR checkout 是 PR head，不是与目标分支的预合并 commit，因此 workflow 还会验证 PR head 包含事件中的最新 base commit；分支保护必须继续开启“PR 过期禁止合并”，过期分支先更新再重跑。向 `master` 直接推送时使用 push before SHA；手工触发先尝试 `origin/master`，若它与 `HEAD` 相同则改用 `HEAD^`，仍无法得到不同提交时失败关闭。

@@ -290,15 +294,15 @@ bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-git
 bash scripts/gitea-ci-job-image.sh load-runner
 ```

-执行账号只要有权访问宿主 Docker API 并管理 runner 容器即可，不强制使用 root；无该权限时由 runner 运维人员执行。更新顺序必须是 `build/verify -> export 仓库外镜像归档与 SHA-256 sidecar -> load-runner -> 确认无活跃 job -> 备份当前 config -> 增加或替换 label -> docker restart --timeout 660 gitea-runner`。`--timeout 660` 只是停止宽限，不是 drain API；rootless DinD supervisor 可能同时停止内层 dockerd，因此重启前必须确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。config 和镜像归档只保存到仓库外受控位置，不在文档、仓库或日志中记录注册信息。重启后先重跑真实 PR 的四个 job，复核隔离边界并确认全部通过，再清理旧镜像。回滚时先把 workflow 的 `runs-on` 改回 `ubuntu-latest`，再恢复 config 备份并重启 runner。
+执行账号只要有权访问宿主 Docker API 并管理 runner 容器即可，不强制使用 root；无该权限时由 runner 运维人员执行。更新顺序必须是 `build/verify -> export 仓库外镜像归档与 SHA-256 sidecar -> load-runner -> 确认无活跃 job -> 备份当前 config -> 增加或替换 label -> docker restart --timeout 660 gitea-runner`。`--timeout 660` 只是停止宽限，不是 drain API；rootless DinD supervisor 可能同时停止内层 dockerd，因此重启前必须确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。config 和镜像归档只保存到仓库外受控位置，不在文档、仓库或日志中记录注册信息。重启后先重跑真实 PR 的十一个 job，复核隔离边界并确认全部通过，再清理旧镜像。回滚时先把 workflow 的 `runs-on` 改回 `ubuntu-latest`，再恢复 config 备份并重启 runner。

-四个 job 先运行镜像内 `genarrative-gitea-checkout`，再以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，校验 Node 与 npm 固定版本、仓库 Rust toolchain、受信任 PATH、四份缓存锁命中状态、原生命令、pkg-config 依赖、完整 bwrap sandbox 和 Chrome headless。运行时发现锁不匹配时必须输出对应 `*_cache_lock=partial` 和 Actions warning，提示可信分支落地后刷新镜像，不能把陈旧缓存误报为闭合。`RUSTUP_AUTO_INSTALL=0`，因此仓库 `rust-toolchain.toml` 变更必须先更新镜像，不能让 job 现场下载。每个 job 仍独立运行一次根 `npm ci`，以唯一 workspace lock 验证 PR 的全部 App 依赖；统一通过 `scripts/ci-npm-ci-with-retry.sh` 做最多 3 次整命令级有界重试，同时保留 `NPM_CONFIG_PREFER_OFFLINE=true` 和 npm 自身 10 次 fetch retry。命中镜像 cache 时只做干净解包，lock 变化时允许补齐差量。不在镜像内烘入 `node_modules`，也不挂载跨 PR 可写缓存。任何 job 的 sandbox canary 失败都必须停止，不允许跳过。Cargo 通过受控 proxy 下载 lock 差量时继续关闭 HTTP multiplexing，并设置 `CARGO_NET_RETRY=10`。
+十一个 job 先运行镜像内 `genarrative-gitea-checkout`，再以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，校验 Node 与 npm 固定版本、仓库 Rust toolchain、受信任 PATH、四份缓存锁命中状态、原生命令、pkg-config 依赖、完整 bwrap sandbox 和 Chrome headless。运行时发现锁不匹配时必须输出对应 `*_cache_lock=partial` 和 Actions warning，提示可信分支落地后刷新镜像，不能把陈旧缓存误报为闭合。`RUSTUP_AUTO_INSTALL=0`，因此仓库 `rust-toolchain.toml` 变更必须先更新镜像，不能让 job 现场下载。需要 `node_modules` 的 job 仍各自独立运行一次根 `npm ci`，以唯一 workspace lock 验证 PR 的全部 App 依赖；4 个 AGC 壳 Rust 分片 job、`AI game creator shell Rust smoke` 与 `AI game creator shell Rust crates` 是纯 cargo 门禁（只用 cargo 与 node 内建模块），显式不装 npm 依赖，这也由 `scripts/project-ci-workflow.test.ts` 钉住。`npm ci` 统一通过 `scripts/ci-npm-ci-with-retry.sh` 做最多 3 次整命令级有界重试，同时保留 `NPM_CONFIG_PREFER_OFFLINE=true` 和 npm 自身 10 次 fetch retry。命中镜像 cache 时只做干净解包，lock 变化时允许补齐差量。不在镜像内烘入 `node_modules`，也不挂载跨 PR 可写缓存。任何 job 的 sandbox canary 失败都必须停止，不允许跳过。Cargo 通过受控 proxy 下载 lock 差量时继续关闭 HTTP multiplexing，并设置 `CARGO_NET_RETRY=10`。

 站点 stack 仍由宿主受控目录管理，`.env`、runner 注册文件和数据库凭据不进入仓库。Compose 必须在 helper/container 内把该目录挂到与宿主相同的绝对路径再执行；挂载到不同路径会让相对 bind source 被 Docker daemon 解析到错误的宿主目录并启动空数据。升级或 runner 迁移前先停止 Gitea 写入，并把 Gitea 冷快照、数据库导出、compose/env 与 runner config/.runner 保存到仓库外受控备份位置。备份文件、绝对宿主配置和注册 token 不得提交 Git，也不在共享文档中记录具体路径或注册内容。

-workflow 首次成功运行后，在 Gitea `master` 分支保护中把 `Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)` 四个完整 context 都设为合并必需检查，并从最近一周已上报 context 表复核名称后再保存。不能只填裸 job 名，否则无法匹配 Gitea 实际上报的 `<workflow> / <job> (<event>)`。只提交 workflow 文件不会自动创建 runner，也不会自动修改分支保护；如果 Actions 长时间停留在等待状态，先到仓库或组织的 Actions runner 页面确认存在在线、带 `genarrative-ci` 标签的 runner，再检查精确 Image ID 是否已装入内层 Docker。
+workflow 首次成功运行后，在 Gitea `master` 分支保护中把 `Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)`、`Project CI / AI game creator shell web tests (pull_request)`、`Project CI / AI game creator shell Rust shard 1/4 (pull_request)` ~ `Project CI / AI game creator shell Rust shard 4/4 (pull_request)`、`Project CI / AI game creator shell Rust smoke (pull_request)`、`Project CI / AI game creator shell Rust crates (pull_request)` 十一个完整 context 都设为合并必需检查，并从最近一周已上报 context 表复核名称后再保存。客户端 CI 拆分的迁移是**追加式**的：旧 job 名继续上报，但 `Native shell tests` 的内容已收窄到壳级与发布构建门禁，因此新增的 AGC context 必须补进必需检查，否则 AGC 门禁在合并前不生效。不能只填裸 job 名，否则无法匹配 Gitea 实际上报的 `<workflow> / <job> (<event>)`。只提交 workflow 文件不会自动创建 runner，也不会自动修改分支保护；如果 Actions 长时间停留在等待状态，先到仓库或组织的 Actions runner 页面确认存在在线、带 `genarrative-ci` 标签的 runner，再检查精确 Image ID 是否已装入内层 Docker。

-master 日常交付必须禁止直接 push，只允许经 PR 在当前 head 的四个 required context 全绿后合并；本地 `pre-commit` 的 staged ESLint/Prettier 和 master `pre-push` 的 Repository checks parity 只用于提前发现问题，可被 `--no-verify` 绕过，不能充当服务端权威门禁。紧急直推白名单如需保留，应按人员和时限最小化，并要求执行同一 `npm run check:repository-ci <base> <head>` 后回读 push CI。
+master 日常交付必须禁止直接 push，只允许经 PR 在当前 head 的七个 required context 全绿后合并；本地 `pre-commit` 的 staged ESLint/Prettier 和 master `pre-push` 的 Repository checks parity 只用于提前发现问题，可被 `--no-verify` 绕过，不能充当服务端权威门禁。紧急直推白名单如需保留，应按人员和时限最小化，并要求执行同一 `npm run check:repository-ci <base> <head>` 后回读 push CI。

 SpacetimeDB bindings：

@@ -0,0 +1,107 @@
+# 【技术方案】AGC 客户端稳定版生命周期大切换
+
+更新时间：`2026-09-14`
+
+## 目标
+
+在 AGC 尚未对外发布的前提下，统一现役客户端入口的异步操作生命周期，并删除会继续制造重复状态机的旧局部防重路径。现有本地项目、`.agent` 文件、Runner 账本和公开后端契约继续作为迁移边界。
+
+## 非目标
+
+- 不删除或重排本地 manifest、会话、资源生成账本和 Runtime journal。
+- 不删除 `/api/external/v1`、账号、编辑器素材、生成接口、SpacetimeDB schema 或共享 DTO。
+- 不把新玩法、插件、支付、编辑器大功能和主站架构调整并入稳定版切换。
+- 不自动重放无法确认已经受理的 pending 外部操作。
+
+## 新的内部合同
+
+### ClientOperation
+
+所有 renderer 异步入口必须能投影以下字段：`operationId`、`requestId`、`kind`、`phase`、`startedAt`、`deadlineAt`、`scope`、`cancelled`。phase 使用 `idle / network / runner / project / success / retryable-failure / unknown`；迟到结果只能在 operationId、scope 和 session generation 都仍匹配时写回。
+
+### AuthTransition / RunnerTransition
+
+启动恢复、手工登录、发送验证码、退出和 401 refresh 共享认证 operation 身份与 session generation。Runner 安装/清除在 blocking worker 执行；前端只展示 network/runner/success/retryable-failure/unknown，并提供重试或重新登录。
+
+### HomeCreationOperation
+
+首页创建由 Launcher controller 持有，payload 保留 draft 快照和 startMode，scope 在建项后绑定 projectPath；创建、附件导入、首轮投递分别推进 phase。页面卸载不取消 operation；成功、可重试失败和不确定状态均可被重新投影。
+
+### RecentProjectInspection
+
+每个最近项目拥有独立 operation 和结果。检查中、可打开、失败、超时、不存在、非目录、未初始化和可导入不能通过一个全局刷新 gate 互相覆盖。
+
+### DevStackIdentity
+
+`.app/dev-stack.json` 和服务 marker 必须包含 `repoRoot + processId + port + dataDir + instanceId` 可验证的身份信息。客户端发现状态时，数据库名、dataDir、repoRoot 或进程归属不匹配就拒绝复用并启动/提示当前工作树自己的服务。
+
+## 本地数据迁移
+
+- 旧 manifest、项目资源、Planning/GDD、会话和 Runtime journal 继续按现有读取与恢复规则打开。
+- 缺少 operationId 的旧 pending 记录只能转换为可重试或 `unknown`，不自动重放外部副作用。
+- 旧 Runner endpoint 只有在当前 dataDir、repoRoot、进程归属和协议/可用性都匹配时才能复用。
+- 迁移失败保留原文件并给出可操作错误，不以新状态覆盖旧数据。
+
+## 任务列表与验收顺序
+
+1. **操作合同**：建立共享 `ClientOperation` 类型、状态转移和 stale-result 规则；认证 refresh 与首页创建接入。
+2. **认证/Runner**：统一登录恢复、手工登录、退出、401 refresh 的 operation 投影，保留 session generation 和 blocking worker。
+3. **入口迁移**：首页创建、手动打开、附件导入、Planning V2、DirectProject、资源生成和预览入口复用 operation scope，不再新增 component-level busy ref。
+4. **开发栈身份**：dev-stack snapshot、Vite marker、AGC 配套后端复用门禁统一使用 repoRoot/processId/port/dataDir/instanceId。
+5. **本地恢复**：对旧 pending operation、旧 endpoint 和正在写入的项目执行失败关闭、可重试或人工核对迁移。
+6. **旧路径清理**：仅删除无现役调用方、无持久化合同、无公开契约的旧分支；每次删除前补调用方和持久化证据。
+7. **完整验收**：启动、登录、进入首页、打开项目、对话、确认、资源、预览、切项目、恢复对话/运行态、失败重试、退出登录，并验证坏项目、迟到结果、Runner 重复启动和旧 worktree 串用门禁。
+
+## 当前实现状态
+
+- HTTP body-aware timeout、refresh singleflight 清理、Runner blocking worker、最近项目逐项检查和首页创建跨页防重已完成并在 PR #346 中提交。
+- `ClientOperation` 基础合同、认证 refresh 与 Runner auth-transition operation 投影、首页创建 operation 投影和 dev-stack `instanceId` 已在本轮切换中落地。
+- 稳定版基础切换里程碑已完成；后续入口只允许复用该合同，不再新增 component-level busy/ref 状态机。
+- Planning/DirectProject/资源生成/预览已有各自 durable operation 或 request scope；本轮只补统一投影与身份校验，不重写其持久化账本。
+
+### 生命周期残留收口（本轮）
+
+上一轮在 master（`0f829cd25`）上做故障注入复现出四类"每走一步都卡住"的残留，本轮按"超时后真正隔离并核对底层操作"收口，不再新增 operation 字段：
+
+1. **本地会话写入队列不再被卡死**：`platformSession.ts` 的 native mutation 队列改为带"解围期限"的闸门（60s）。Rust `install_platform_session_in` / `clear_platform_session_in` 本来就按 generation 单调校验（更旧的 install/clear 一律拒绝），所以渲染层只需保证新 generation 不被旧调用无限挡住；迟到的旧写入由 Rust 拒绝。
+2. **generation floor 读取失败可重试**：`reserveNativePlatformSessionGeneration` 不再把一次瞬时失败缓存成永久失败（原先 `??=` 缓存了已 reject 的 promise，导致同一次渲染进程内后续登录/退出全部失败）。
+3. **登录围栏超时后的迟到结果必须落地**：UI 的 45s 围栏只放弃等待，不再放弃结果。本地运行时确实装好会话时，界面跟着进入工作区，避免"后端已登录、前端停在登录页"。
+4. **首页自动建项有兜底期限与恢复入口**：`home-create` 从 `deadlineMs: null` 改为 10 分钟兜底期限；到点后首页入口解围（底层创建继续在后台跑，迟到成功照常进项目），并把已建好的工作区登记进最近项目、在首页给出「打开已创建的工作区」入口。外层 catch 不再用初始 operation 覆盖内层已写入的 `scope.projectPath`；底层创建未返回期间只挡"再建一个"，不挡打开已有项目。
+
+## 现役边界审计
+
+以下能力在本次切换前已经具备 durable 恢复或失败关闭合同，因此本轮按现有实现接入统一投影，不重复重写：
+
+| 边界 | 当前证据 | 切换结论 |
+| --- | --- | --- |
+| 本地 manifest、Godot/Cocos 导入和项目 revision | `src-tauri/src/project/manifest/`、`import_tests.rs`、`recovery_tests.rs` | 保留旧文件格式，失败关闭，不复制平行项目根 |
+| 资源生成与 pending operation | `src-tauri/src/project/resource_editor.rs`、`generation/*` 测试 | 已有 operation/幂等/needs-reconciliation，禁止未知结果自动重放 |
+| Agent Runtime、Planning V2、DirectProject | `runtime_driver/recovery_scan.rs`、`runtime_protocol/`、`direct_runtime.rs` | 继续使用 durable task/session/run，统一 renderer operation 投影 |
+| 公开后端与共享契约 | `server-rs`、`packages/shared`、`docs/openapi` | 不删除、不改公开契约 |
+| 已退役客户端入口 | 当前 `WorkspaceLauncher`、`App.tsx` 和路由调用方审计 | 无现役调用方的旧分支才允许后续删除，暂不以猜测删除 |
+
+完整真实 Provider、原生安装包和跨重启端到端时序仍需在具备登录/Provider 的环境中执行；本次代码门禁已覆盖 deterministic surface、operation、认证和 dev-stack identity。
+
+## 验收证据
+
+| 条款 | 证据 |
+| --- | --- |
+| operation identity 与 stale-result | `clientOperation.test.ts`、认证/home 定向测试 |
+| HTTP/auth/Runner | client HTTP/API 测试、Rust cargo check、认证 appSurface |
+| 最近项目逐行刷新 | `recentProjectsModel.test.ts`、home appSurface |
+| dev-stack 身份 | `scripts/dev.test.ts`、`start-dev-stack.test.ts`、端口 marker 检查 |
+| 本地恢复边界 | 现有 manifest/runtime/resource recovery tests；未确认外部副作用不自动重放 |
+| 超时隔离与迟到结果 | `auth.suite.ts`（stalled native install 不阻塞后续登录、floor 瞬时失败可重试、围栏超时后迟到安装落地）、`home.suite.ts`（建项看门狗解围并保留迟到成功、设计运行时初始化失败后保留工作区并可打开） |
+| 完整流程 | AGC appSurface、开发栈 smoke；真实 Provider/安装包另行记录 |
+
+### 本轮门禁执行记录
+
+- `npm --prefix apps/ai-game-creator-shell run typecheck`（含 skill-pack、check-config）通过。
+- `apps/ai-game-creator-shell/tests/appSurface.test.ts` 428/428 通过（含本轮新增 5 个故障注入回归）。
+- 定向：`clientHttp`、`clientApi`、`clientOperation`、`recentProjectsModel`、`clientRuntimeErrorBoundary`、`sessionPreview`、`start-dev-stack`、`dev-port`、`start-tauri-dev` 全部通过。
+
+### 待验证（本轮未确认，不作为结论）
+
+- 原生（真实 Runner/IPC）与真实 Provider 下的同一批时序未执行：本轮结论来自 deterministic surface 与 mock 故障注入。
+- `src-tauri/src/project/bootstrap.rs` 在 `npm install` 之前读取 `package-lock.json` 计算 `lockSha256`，安装后仍使用旧字节；疑似只影响审计准确性，未复现、未修改。
+- 同 PID 下的写入 advisory guard（`write_lock.rs` 的 `bypassed_same_process`）是否会放过并行写：**已确认会**。只比 `pid` 的豁免让同进程其它线程的写通道也跳过 `.agent/project.lock`，`Project CI` 的 Rust 全量门禁因此红了 12 条（4 路并行直写撞项目 revision 侧车报 `File exists`、8 线程并发 steer 序号重复、一致快照读 / pending 复核 / 恢复安装不再等待、写锁失败不再失败关闭）。已把复用判据收窄为**同线程重入**：本进程其它线程继续走有界等待与终态占用，详见 `docs/project-memory/shared-memory/pitfalls.md`「项目写锁的同进程复用判据不能只看 pid」与 `docs/project-memory/plans/【里程碑】项目客户端占用锁收敛-2026-09-14.md`。
@@ -0,0 +1,44 @@
+# 【技术方案】AGC 异步操作可恢复闭环
+
+更新时间：`2026-09-14`
+
+## 目标
+
+让 AGC 的认证、最近项目检查和首页自动创建在响应体卡住、单目录慢、页面切换或操作迟到时仍然可观察、可重试且不会重复创建或覆盖当前项目。
+
+## 非目标
+
+- 本轮不改变认证接口、Runner 协议、SpacetimeDB schema 或 External API。
+- 不处理环境中其它 worktree 的进程；运行环境清理需单独按进程归属执行。
+- 不把 UI 测试警告全部清零，除非它们阻碍本轮新增行为验证。
+
+## 入口与边界
+
+- 用户/系统入口：AGC 登录恢复、登录/验证码/退出、首页最近项目、首页做游戏/做素材/做方案。
+- 涉及模块：`clientHttp`、`clientAuth`、`AuthenticatedClient`、最近项目 controller/model、`useHomeProjectCreation`、`HomeView`。
+- 正式状态来源：认证 token 与 platform session、Tauri 项目 manifest；前端操作状态仅用于防重和恢复提示。
+
+## 必须成立的行为
+
+1. HTTP 响应头已返回但响应体未结束时，认证请求在有界时间内失败并释放 refresh singleflight；下一次重试必须发起新请求。
+2. 最近项目逐项独立检查；单项超时/失败只影响该行，已完成且可打开的项目立即可操作。
+3. 首页自动创建状态由 `WorkspaceLauncher` 生命周期持有；切页期间仍防重，迟到结果不能覆盖用户已打开的其它项目。
+4. 认证恢复和 Runner 连接继续有明确超时、错误和重试入口；本地 Runner 会话安装/清除的阻塞工作不得占用 Tauri 窗口线程。
+
+## 契约与迁移
+
+不新增公开 API、DTO、schema 或持久化字段。Runner command 协议保持不变。
+
+## 验收标准与证据
+
+| 条款 | 验收方式 | 证据 |
+| --- | --- | --- |
+| 响应体超时 | client auth/http 定向测试 | body 卡住抛出稳定超时，第二次 refresh 请求计数为 2 |
+| 最近项目独立完成 | model/controller 定向测试或 appSurface 场景 | A 完成时可打开，B 继续检查 |
+| 首页创建跨页防重 | appSurface 场景 | 切页返回后按钮仍禁用，迟到创建不覆盖已有项目 |
+| Runner 会话不阻塞窗口 | Rust 编译检查与登录/退出 UI fence | command 使用 blocking worker，前端使用 45 秒可恢复超时 |
+| 现有行为不回归 | typecheck、AGC 定向测试、编码和 diff 检查 | 命令输出 |
+
+## 未决问题与决策
+
+Runner 同步 Tauri command 的窗口线程影响需要通过当前 Rust command 注册与调用链复核；若要改为异步 command，应单独补 Rust 线程/取消语义测试，不在未验证前引入表面异步包装。