Merge remote-tracking branch 'origin/master' into feat/play-count-with-cache

# Conflicts:
#	docs/project-memory/shared-memory/decision-log.md

docs/project-memory/plans/【实施计划】Web预检浏览器失败恢复-2026-10-02.md

@@ -0,0 +1,31 @@
+# Web 预检浏览器失败恢复实现计划
+
+- Version: `1`
+- Status: `active`
+- Date: `2026-10-02`
+- Milestone: [`Web 预检浏览器失败恢复`](./【里程碑】Web预检浏览器失败恢复-2026-10-02.md)
+
+## 实现顺序
+
+1. 将浏览器启动失败建模为带阶段、原因、子进程退出确认、清理确认的内部结果；Windows root spawn 后立即绑定 Job，并把绑定瞬间已经出现的子树逐 PID 纳入同一 Job，失败收束必须复用本轮 `BrowserProcessGuard`，并在成功收束时确认 Windows Job 为空。
+2. 在 Web 预检使用的一次浏览器启动入口加入一次有界恢复：仅 WS/CDP 瞬态失败且首次清理确认后创建新的临时目录/Profile 重试；其余失败直接失败关闭。
+3. 保留/加强 owner 与 sweep 的归属门禁，使用 Windows argv 解析核对完整 Profile 参数；无 owner、身份未知、PID 退出或复用均不得按猜测杀进程。
+4. 将启动失败和清理失败的安全诊断保留到预检 blocked 报告和 Tauri 错误中；稳定错误码独立于诊断文本，前端继续区分宿主阻塞与 IPC 故障。
+5. 补充 Rust 纯策略测试、清理边界测试和现有真实 Edge/Chromium ignored smoke；补充首页错误展示的定向测试。
+
+## 验证命令
+
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell browser::`
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell environment_check::web_creation::tests`
+- `npx vitest run apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx`
+- `npm run typecheck --workspace apps/ai-game-creator-shell`
+- `npm run check:encoding`
+- `git diff --check`
+
+可选真实环境证据：安装 Windows Edge 时运行现有 `real_browser_health_checks_can_run_concurrently` 及新增恢复 smoke；无浏览器时保持 ignored，不把缺失环境写成通过。
+
+## 风险与回滚
+
+- Windows 进程命令行读取失败按不匹配处理，不执行杀进程；这可能留下临时目录，但保证不误杀。
+- 首次失败进程树收束未确认时不自动重试，避免第二个 Edge 与残留树并存；错误返回安全诊断。
+- 回滚点为浏览器启动恢复入口和 owner/sweep 归属校验，不触及 Web 预检的 Node/npm 或项目写入流程。

docs/project-memory/plans/【实施计划】支付应用与订单收银台-2026-10-03.md

@@ -0,0 +1,52 @@
+# 【实施计划】支付应用与订单收银台
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】支付应用与订单收银台-2026-10-03.md` |
+| Status | completed |
+| Owner | Codex |
+
+## 修改边界
+
+允许修改：
+
+- 主规范、shared-contracts、OpenAPI、支付领域 module、spacetime-module / migration / bindings、spacetime-client facade、api-server payment module、platform-wechat provider。
+- `src` 的 profile 支付入口、收银台页面、支付客户端和页面样式。
+- `apps/admin-web` 的支付 API 类型、路由、页面和后台样式。
+- 与本里程碑直接相关的测试和文档索引。
+
+明确不修改：
+
+- 现有个人钱包充值、微信虚拟支付和退款状态机的行为。
+- 生产商户密钥、环境文件、个人配置和构建产物。
+- 支付宝 provider、分账、提现、手续费和自动结算。
+
+## 实现顺序
+
+1. 从现有充值订单、微信 Native provider、外部 API Key、profile 路由和后台列表组件提取可复用边界，确认没有重复的公开订单模型。
+2. 冻结支付 DTO、状态枚举、错误码、幂等语义和 OpenAPI，然后补契约测试。
+3. 增加支付领域表、migration、procedure / facade 和 schema 绑定，先完成订单创建、查询、关闭与幂等。
+4. 在 `platform-wechat` 增加支付服务需要的 Native 请求 / 响应和通知确认复用，保持商户配置只在服务端。
+5. 在 `api-server` 接入外部 API、收银台 read model、微信通知、查单和外部回调 outbox；所有到账入口复用统一确认事务。
+6. 增加个人中心支付应用 / Key / 订单页面和公共收银台，按截图参考实现桌面双栏与移动端纵向布局。
+7. 增加后台支付概览、应用、订单、通知和回调投递页面，复用 `packages/shared` 后台公共组件。
+8. 运行定向测试、schema / OpenAPI / 编码检查，启动 api-server 做 healthz 和 mock provider smoke；条件具备时执行真实沙箱二维码 smoke。
+
+## 验证命令
+
+1. `npm run check:encoding`
+2. `git diff --check`
+3. `npm run check:spacetime-schema`
+4. `npm run typecheck`
+5. `npm run admin-web:typecheck`
+6. 支付领域和 api-server 定向 `cargo test`
+7. 外部 API、profile、收银台和 admin 页面定向 Vitest
+8. `npm run dev:api-server` 后检查 `/healthz`
+9. mock provider + Playwright 收银台 smoke；真实商户沙箱可用时再补动态二维码验证
+
+## 风险与回滚点
+
+- 商户 API 证书或通知地址不可用时，保留 provider mock 证据，不把 mock 结果标成真实支付通过。
+- schema 变更失败时停止在绑定生成前，保留主规范和计划，不能通过删除数据绕过迁移。
+- 订单确认事务或回调 outbox 未完成时，关闭新支付渠道开关，不影响现有充值渠道。
+- 发现需要余额、提现、分账或支付宝真实接入时，先更新主规范和后续里程碑，再扩展实现。

docs/project-memory/plans/【里程碑】Web预检浏览器失败恢复-2026-10-02.md

@@ -0,0 +1,41 @@
+# Web 预检浏览器失败恢复
+
+- Version: `1`
+- Status: `active`
+- Date: `2026-10-02`
+- Parent Spec: [`AI游戏创作智能体 App 实施计划`](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#自动预检与可信脚手架)
+
+## 目标
+
+修复 Issue #584：Web 游戏环境预检在受控 Edge/Chrome 的 WS 握手或 CDP 连接失败时，能够只针对本轮 AGC 浏览器实例完成清理、使用新的隔离 Profile 重试一次，并在仍失败时保留安全、可行动的诊断信息。
+
+## 边界
+
+- 只改 AGC Rust 浏览器启动/清理、Web 预检错误投影及其定向测试、对应现行专题文档。
+- 清理对象必须同时满足 AGC 临时 Profile、进程启动身份、可信浏览器可执行文件和 Windows 进程树归属；无法确认时 fail-closed。
+- 不执行全量 `taskkill /IM msedge.exe`，不影响用户 Edge、其它 AGC 实例、其它项目或 worktree。
+- 不改变 Web 预检的失败关闭、Node/npm 检查、桌面/移动双视口检查和首次生成顺序。
+- 不新增网络、自动下载、跳过浏览器验证或伪造 ready 的旁路。
+
+## 行为合同
+
+1. WS 握手失败、WS 超时、CDP 连接失败或 CDP 连接超时属于可恢复的浏览器启动瞬态失败。
+2. 第一次失败后，宿主必须先确认本轮进程树已退出并清理本轮 Profile / owner 记录 / 临时目录；清理未确认时不得启动第二次浏览器。
+3. 清理确认后，第二次启动必须创建新的隔离临时目录和 Profile；第二次成功后继续现有 desktop/mobile 预检。
+4. 连续失败或清理被阻断时，结果保持 blocked，并带有阶段（WS 握手或 CDP 连接）、子进程是否退出、清理是否确认、是否执行恢复重试等安全诊断。
+5. owner.json 缺失/写入失败、目录过新、进程已退出、PID 被复用、身份未知或归属不明时只能按保守路径处理：不杀不明进程；可安全删除的临时目录才删除。
+
+## 验收标准
+
+- 定向测试构造 `browser-ws-failed` 后证明只在清理确认时重试，且重试使用新的 Profile；第二次成功返回成功。
+- 定向测试覆盖 WS/CDP 阶段、连续失败、清理未确认、owner.json 缺失/无效、刚创建目录、进程退出、PID 复用和非 AGC 进程跳过。
+- Windows 真实 Edge 安装版 smoke 保留在现有真实浏览器测试入口中；无 Edge 的环境明确跳过而不是伪造通过。
+- 现有首页预检、正常 Edge 使用、首次生成失败关闭和前端 IPC/宿主错误区分回归通过。
+
+## 依赖
+
+- `apps/ai-game-creator-shell/src-tauri/src/browser/process.rs`
+- `apps/ai-game-creator-shell/src-tauri/src/browser/sweep.rs`
+- `apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs`
+- `apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts`
+- 对应 Rust 与 Vitest 测试。

docs/project-memory/plans/【里程碑】支付应用与订单收银台-2026-10-03.md

@@ -0,0 +1,59 @@
+# 【里程碑】支付应用与订单收银台
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | completed |
+| Date | 2026-10-03 |
+| Parent Spec | `docs/【技术方案】外部产品支付服务接入-2026-10-03.md` |
+
+## 目标
+
+建立首个可运行的支付服务闭环：账号创建支付应用并管理 API Key，客户端或外部产品创建订单，用户进入 Web 收银台，平台通过微信 Native provider 生成动态二维码，通知 / 查单确认订单，之后通过签名回调通知接入方，后台可查询应用和订单。
+
+## 范围
+
+- 支付应用、API Key 元数据和账号归属。
+- 外部支付订单、商品快照、支付尝试和状态机。
+- 微信 Native 动态二维码 provider 适配；支付宝只保留渠道扩展结构，不纳入本里程碑的可用渠道。
+- 公共收银台和移动端纵向布局。
+- 支付平台通知、主动查单、确认幂等和接入方回调 outbox。
+- 个人中心支付服务入口、应用配置页和订单列表。
+- 后台支付总览、应用列表、订单列表、通知 / 回调失败列表。
+- `/api/external/v1/payment/*` OpenAPI、共享 DTO、契约测试和支付领域 schema。
+
+## 不在范围内
+
+- 支付宝真实下单、退款、分账和沙箱联调。
+- 外部产品余额、手续费、提现、自动结算和自动分账。
+- 用户钱包充值商品的迁移或现有微信虚拟支付协议改造。
+- 自动履约发货、数字权益回收和支付争议处理。
+
+## 依赖与前置条件
+
+- 平台微信 Native 商户号、API 证书 / 密钥和正式或沙箱通知地址可由部署环境注入。
+- 当前微信支付 Native provider、充值订单状态与验签测试可复用。
+- 外部回调域名必须通过应用配置的 HTTPS 和白名单校验。
+- SpacetimeDB schema、migration、生成绑定和 API OpenAPI 可以在同一里程碑同步更新。
+
+## 验收标准
+
+- [x] 账号能创建、停用支付应用，API Key 仅在创建响应中展示一次，撤销后立即拒绝请求。
+- [x] 外部 API 使用 `Idempotency-Key` 创建订单，重放返回原订单，字段冲突返回业务错误。
+- [x] 订单金额以整数分保存，商品和金额快照创建后不可被应用配置改写。
+- [x] 收银台使用不可猜测 token，桌面端双栏、移动端纵向显示商品、金额、二维码、过期和状态。
+- [x] 微信 Native 下单返回的二维码对应当前本地平台订单号和金额。
+- [x] 支付平台通知 / 查单确认前，客户端轮询或伪造回调不能把订单改为 `paid`。
+- [x] 重复、乱序、错误金额、错误签名、错误应用归属的通知不会重复确认或改变订单。
+- [x] 接入方回调异步投递、签名、重试和失败状态可查询。
+- [x] 个人中心和后台均能按归属和权限查看应用、订单及失败记录。
+- [x] `shared-contracts`、OpenAPI、schema 绑定和契约测试同步通过。
+
+## 证据要求
+
+2026-10-03 验收复核：支付专用 schema、typed facade、API、应用管理、provider-attempt claim、通知确认、签名回调 outbox、后台投递状态、profile/payment 路由和前端 build 已完成。项目 dev stack 发布后 `GET /healthz` 返回 HTTP 200，live schema 包含 `payment_order` / `payment_webhook_delivery`；真实商户沙箱二维码和真实微信通知因环境未注入商户凭据未验证，按“有可用沙箱时补充”处理。
+
+- 自动化：Rust 领域 / API / provider 测试、前端页面与契约测试、schema 检查、OpenAPI 检查、编码和 diff 检查。
+- 运行时：项目 dev stack 发布当前 schema 后，api-server 使用正确端口和 bootstrap 配置，`GET /healthz` 返回 HTTP 200；live schema 已包含 `payment_order` 与 `payment_webhook_delivery`；微信 provider mock 由现有 provider 测试覆盖。
+- 未验证：真实商户沙箱动态二维码和真实微信通知，当前环境没有可安全使用的商户凭据；代码保留 provider 配置失败和支付状态失败关闭语义。
+- 边界：权限、幂等、重放、金额不一致、回调失败、过期、未知通知和敏感日志检查。

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

@@ -19,6 +19,22 @@
 - 权威文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 的 `game_distribution_game` 节，以及 `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 的「游玩计数（已实现）」节。
 - 验证：`cargo check -p api-server` 与 `cargo test -p api-server game_play_counter`（9 passed）通过；前端定向 vitest（点击上报断言 + clientId 稳定性）与 `eslint --max-warnings 0` 通过；`npm run check:server-rs-ddd`、`npm run check:generated-bindings`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。
 
+## 2026-10-03 AGC 画布引用统一走「活跃聊天输入区」注册表（Issue 602）
+
+- 背景：画布的「引用」按钮与「拖拽批量引用」只派发 window 事件，消费者只有 `App.tsx` 一处，而它插的是绑在 `PlanningChatView` 上的 `chatComposerRef`；2026-09-22 DirectProject 拆分后普通项目走 `directProjectMode` 提前 return，渲染不到策划面 → ref 恒为 `null`，可选链静默吞掉点击（画布上是死按钮）。同一批合并冲突还丢了 `RESOURCE_REFERENCE_INSERT_MANY_EVENT` 的监听，批量引用连消费者都没有。
+- 决策：新增 `features/project-workspace/activeChatComposer.ts`，模块级只保存**当前挂载的那一个**输入区句柄（`registerActiveChatComposer` 返回带身份校验的注销函数，并检测到第二个输入区注册时留一条 dev 告警——不改运行时语义；`insertChatReferences` 在空批次 / 无输入区 / 句柄报「这一批没插进去」三种情况返回 `false`）。`DirectProjectComposer` 用 `useImperativeHandle` 暴露 `DirectProjectComposerHandle`（按 ref 转发、由它回答插入是否真的递到输入区），`DirectProjectChatView` 与 `PlanningChatView` 挂载期间各自注册**按 ref 转发**的句柄（注册时不读输入区是否就位，因此不依赖父子 effect 顺序）（两条链路互斥渲染，同一时刻只有一个句柄）。`App.tsx` 收敛为一处监听，单条 + 批量两个事件都走 `insertChatReferences`（空批次直接返回：没有要插的东西，不能报成「没有可用的输入区」）；返回 `false` 时 dev 下 `console.warn`。`chatComposerRef` 只保留给策划输入盒自己的 `getDraft` / `clear`。
+- 边界：不采用「给 DirectProjectComposer 单独加 ref 出口 + App 按模式分流」的备选（那会把「哪个 ref 此刻是活的」继续留在检测点上）。插入仍经 `ResourceReferenceInput.insertReferences` + `focus()`（光标落在插入之后，连点两次按顺序追加）。真正根治的形态是画布与聊天的共同宿主用 context 下发插入能力；注册表语义与之一致，将来换实现不必动画布。
+- 影响范围：`apps/ai-game-creator-shell/src/features/project-workspace/activeChatComposer.ts`（新增）、`src/App.tsx`、`src/view/project-development/chat/DirectProjectChatView.tsx`、`.../chat/components/DirectProjectComposer/DirectProjectComposer.tsx`、`.../planning/PlanningChatView.tsx`、`tests/activeChatComposer.test.ts`（新增，钉注册表合同）、`tests/resourceCanvasChatReferenceDrop.test.tsx`、`tests/appSurface/{project-development,design-agent}.suite.ts`、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`、`pitfalls.md`、本文件。
+- 验证（合并 master 后的最终一轮）：`npx vitest run apps/ai-game-creator-shell/tests`（197 passed / 1 skipped 文件，1918 passed / 17 skipped 用例）、`npx vitest run tests/activeChatComposer.test.ts tests/resourceCanvasChatReferenceDrop.test.tsx`（2 files / 12 passed，含注册表合同：空批次、无输入区、句柄报落空、注销身份校验、重复注册告警、乱序注销）、`npx vitest run tests/appSurface.test.ts -t 引用`（4 passed）、`npm run agc:typecheck`（含 `check:tests:types`，exit 0）、`npm run check:encoding`、`git diff --check`、eslint `--max-warnings 0`（改动文件）。反向证伪：去掉注册调用后端到端用例变红；去掉空批次短路 / 重复注册告警后对应新用例各红一处。
+
+## 2026-10-03 AGC 栏目画布上传素材按入口栏目登记（Issue 359）
+
+- 背景：AGC 客户端在资源栏目子画布（「UI 交互 / 角色与对象 / 场景与环境 / 音频」）左下角工具栏点「上传」后，提示条给出「已上传 1 个素材」，但当前栏目计数不变（仍「0 项」）、素材出现在「待归类」，用户看到的是"上传成功了但它从这一页消失了"。原因是上传登记的 manifest `kind` 只由**内容证据**推导（`assets.rs::uploaded_asset_kind`：图片 / 视频 / 代码 → `unclassified`，音频 → `audio`，文档 / 字体 → `document`），kind 派生分类与栏目词汇（`ui-interaction` / `character` / `scene` / `audio`）不是同一套，而 `upload_local_asset` 原先不接受入口栏目。
+- 决策：`upload_local_asset` 增加可选 `targetCategory`，Rust 走既有的 `register_local_asset_entry_with_category`（与生成入口 `start_local_project_asset_generation` 的 `targetCategory` **同一口径**：GUI 完成登记以入口栏目为准）；前端 `uploadProjectAssetFilesAndReadSnapshot` 透传该字段，栏目画布工具栏上传取工具栏自己的栏目（`resourceCanvasBottomToolbarCategory`）。取值只接受共享分类枚举，非法值由原生失败关闭，前端不做伪分类。
+- 边界：不传 `targetCategory` 时保持既有 kind 派生行为——资源面板（`ResourceCanvasPanelView`，跨栏目列表而不是栏目工具）、UI 编辑器图片导入（`import_ui_editor_local_files`）、聊天附件上传都不变。`upload_local_asset_at` 签名保持不变（委托到新的 `upload_local_asset_at_with_category`），既有约 25 处调用点与 Rust 单测零改动。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/{assets.rs,commands/desktop.rs}`、`apps/ai-game-creator-shell/src/view/project-development/{projectResourceLiveUpdateModel.ts,index.tsx}`、`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`、PRD §3.10、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`（§4 载荷表）、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11a）、`pitfalls.md`。
+- 验证：`cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute --bin genarrative-ai-game-creator-shell assets::tests`（新增 `upload_registers_into_the_explicit_entry_category`：显式栏目 → `character`、不传 → `unclassified`、非法 `version` 失败关闭且不新增登记）；`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`（196 passed / 9 skipped，含新增「uploads toolbar files into the entry column so they stay visible where they were uploaded」断言工具栏上传载荷带 `targetCategory: 'character'`）；`npm run agc:typecheck`、`npm run check:encoding`、`git diff --check`。
+
 ## 2026-10-03 生成绑定不再经 prettier：ts-rs 原始输出即提交形态
 
 - 背景：`scripts/check-generated-bindings.mjs` 对 AGC 的 `chat/generated` / `services/generated` 在重生成后会就地跑一遍 `npx prettier --write` 再比较。这会直接改写生成文件，还把「Rust 声明真的变了」与「prettier 版本 / 配置造成的格式漂移」混在同一条告警里——本次报出的 `ThreadRequestKind.ts` / `TurnCompletedStatus.ts`「内容变化」无法复现为语义变化（已提交内容与当前 Rust 枚举一致），prettier 归一化把格式差异也报成了「与 Rust 声明不一致」；生成物被仓库格式化工具二次改写后，重跑 `cargo test export_bindings` 也不再幂等。

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

@@ -119,3 +119,7 @@ Gitea 缓存部署必须区分网络：runner 的 RPC 走 `gitea-runner-fetch-ga
 AGC Rust 两条 lane、crates、smoke、Backend 和桌面壳测试使用镜像内可信 sccache 对象快照；Native shell release step 显式清空双 wrapper，前端/repository checks 不启用。仅首次人工 bootstrap 时，维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中按实际 cwd/profile/目标预热全部测试组，仅编译、不执行测试/应用；后端 workspace 与 spacetime-module 保持独立，AGC 的三个 cwd 入口之间清理预热 target，防止 fresh 判断漏产缓存键。最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。容量上限 4 GiB，不替代宿主旧镜像/归档清理。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计；两个 lane 的测试和前置检查不同，耗时差不是严格 A/B。线上存在活跃 CI 时不得重启 runner 或切换标签；全组启用前须刷新完整快照并逐组验证，详见开发运维文档。
 
 `.gitea/workflows/project-ci.yml` 的客户端门禁拆成 lane 与功能 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust lane 1/2`、`lane 2/2` 各自预取一次 AGC 壳 manifest，并顺序运行两片 Rust bin 单测；`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，不预热。两条 Rust lane 与 smoke job 必须在编译前通过 `scripts/ci-npm-ci-with-retry.sh` 执行根 `npm ci`：AGC 壳的 `build.rs` 会从 `node_modules` 准备 Claude Agent SDK 与目标平台原生运行时，镜像中的 npm 下载缓存不能替代安装。人工 `scripts/build-gitea-rust-cache.sh` bootstrap 同样在首次编译 AGC 壳前安装 npm 依赖；只有不构建壳的 crates job 继续省略 npm 安装。两个被 `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 片：每次分片调用用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并使用独立 `TMPDIR`；两条 lane 之间并发，lane 内顺序运行两片，避免重复依赖预热和同一容器内多进程争抢。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片调用都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。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 镜像缓存，再重跑门禁。
+
+## AGC 测试类型门禁
+
+AGC 测试（`apps/ai-game-creator-shell/tests/`）与生产 `src/` 同受类型门禁。`apps/ai-game-creator-shell/tsconfig.tests.json` 以 `include: ["src", "tests", "vite.config.ts"]`、`types: ["vite/client", "vitest/globals"]`、`allowImportingTsExtensions`、`allowJs` 全量覆盖：新增测试文件自动纳入，不存在基线、豁免名单或 `@ts-nocheck`。入口 `npm --prefix apps/ai-game-creator-shell run check:tests:types`（`tsc -p tsconfig.tests.json --noEmit`）已并入该 app 的 `typecheck`，因此 `npm run agc:typecheck`、`npm run ai-game-creator-shell:check:web` 与 CI 的 `AI game creator shell web tests` 都会执行。修测试只做类型层改动，不改断言与行为；禁止 `@ts-ignore`、`as any`，仅当 mock 泛型函数确实不可兼容时才允许带中文注释的 `as unknown as`。

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

@@ -2,6 +2,22 @@
 
 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。
 
+## 2026-10-03 AGC 画布「引用」死按钮：window 事件的消费者挂在一个只在另一条链路赋值的 ref 上
+
+- **现象**（Issue 602）：AGC 资源画布选中一张已登记素材，选中工具条点「引用」（图标 `@`、可见文案与 `title` 都是「引用」）没有任何反应——聊天输入框里不出现 `@素材名` 芯片，也没有任何提示。普通项目（`directProjectMode`）必现，立项策划项目（`planningStartMode`）复现不出来；把素材卡拖到对话栏的批量引用同样没反应。
+- **原因**：画布侧只 `dispatchResourceReferenceInsert` / `dispatchResourceReferenceInsertMany`，而这两个 window 事件的**唯一**消费者是 `App.tsx` 里的 `chatComposerRef.current?.insertReferences(...)`，`chatComposerRef` 又只赋给 `PlanningChatView`；2026-09-22 DirectProject 拆分引入的 `directProjectMode` 提前 return 让普通项目整段跳过后面的策划面渲染 → ref 恒为 `null`，可选链把整次调用静默吞掉。同一批合并冲突还把 2026-09-21 新加的 `RESOURCE_REFERENCE_INSERT_MANY_EVENT` 监听整段丢掉，批量引用连消费者都没有。
+- **处理（现行口径）**：`features/project-workspace/activeChatComposer.ts` 保存当前挂载的**那一个**输入区句柄（`registerActiveChatComposer` 返回带身份校验的注销函数 / `insertChatReferences`），`DirectProjectChatView` 与 `PlanningChatView` 挂载期间各自注册（两条链路互斥，同一时刻只有一个句柄）；`App.tsx` 收敛为一处监听，单条与批量都走 `insertChatReferences`，返回 `false`（空批次 / 此刻没有输入区）时 dev 下 `console.warn`；`chatComposerRef` 只留给策划输入盒自己的 `getDraft` / `clear`。
+- **判据/取证**：`npm run test -- apps/ai-game-creator-shell/tests` 里的 `resourceCanvasChatReferenceDrop.test.tsx`、`appSurface/project-development.suite.ts`（工具条「引用」）、`appSurface/design-agent.suite.ts`（策划链路）都断言**真实输入盒草稿**里出现 `[data-resource-reference-id="<assetId>"]`，不再是「事件被派发」；临时去掉注册调用后这三条会红，证明用例钉的是真链路。详见 [`【功能说明】AGC聊天素材引用-2026-09-08`](../../【功能说明】AGC聊天素材引用-2026-09-08.md) 文首一节。
+- **边界**：只要还保留「window 事件 + 模块外 ref 约定」这种形态，新增聊天面就必须一起进注册表；更彻底的形态是画布与聊天的共同宿主（`ProjectDevelopmentView`）用 context 下发插入能力，注册表语义与它一致，将来换实现不必动画布。
+
+## 2026-10-03 AGC 栏目画布上传素材落「待归类」：kind 派生分类不等于入口栏目
+
+- **现象**（Issue 359）：在 AGC 资源栏目子画布（如「UI 交互」「角色与对象」）左下角工具栏点「上传」选图片 / 视频 / 代码类文件，提示条给出「已上传 1 个素材」，但当前栏目计数纹丝不动（仍「0 项」），素材出现在「待归类」。用户看到的是"上传成功了，可它就消失在这个页面里"。
+- **原因**：上传登记的 manifest `kind` 只由**内容证据**推导（`assets.rs::uploaded_asset_kind`：图片 / 视频 / 代码 → `unclassified`，音频 → `audio`，文档 / 字体 → `document`），kind 派生分类与栏目词汇（`ui-interaction` / `character` / `scene` / `audio`）不是同一套；`upload_local_asset` 原先不接受入口栏目，GUI 工具栏上传只能落 kind 派生分类。
+- **处理（现行口径）**：`upload_local_asset` 增加可选 `targetCategory`，Rust 走既有的 `register_local_asset_entry_with_category`（非法值失败关闭，不回退 kind 派生）；栏目画布工具栏上传时取工具栏自己的栏目（`resourceCanvasBottomToolbarCategory`）。生成入口 `start_local_project_asset_generation` 的 `targetCategory` 是同一口径——GUI 完成登记以入口栏目为准。
+- **判据/取证**：`cargo test --locked ... --bin genarrative-ai-game-creator-shell upload_` 的 `assets::tests::upload_registers_into_the_explicit_entry_category`（显式栏目 → `character`；不传 → `unclassified`；非法 `version` 失败关闭且不新增登记）；appSurface「uploads toolbar files into the entry column so they stay visible where they were uploaded」断言工具栏上传载荷带 `targetCategory: 'character'`。
+- **边界**：资源面板（跨栏目列表）、UI 编辑器图片导入、聊天附件上传都**不带**入口栏目，保持 kind 派生。任何新增的「某个栏目里的上传入口」都必须显式带上当前栏目，否则又会复现本坑。
+
 ## 2026-10-01 用户输错一次密码被当成"客户端出问题了"引导上报
 
 - **现象**：登录页密码输错（或密码长度不合规）后弹出「发现问题」，报告面板「错误事件（2）」列出 `密码长度需要在 6 到 128 位之间 — auth · 1 次` 与 `手机号或密码错误 — auth · 1 次`，默认全选，与 react-render / 5xx / agent-runtime 终态失败视觉等价。
@@ -4145,7 +4161,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 现象：target 注册了 SIGTERM 清理逻辑，但 `command.terminate` 只偶尔出现 stopped marker；耗时 300-500ms 的清理经常被提前截断。
 - 原因：如果先向 wrapper/bwrap/trampoline/target 共用的外层进程组发送 SIGTERM，wrapper 会先退出，bwrap 的 die-with-parent 随即收走 namespace；名义上的 800ms 宽限并没有真正留给 target。
 - 处理：process-session target 在 child pre-exec 内暂时屏蔽 SIGTTOU，完成 setpgid + PTY slave tcsetpgrp 并恢复信号掩码后才 exec；不能先 spawn 到后台组再由 parent 设前台，否则 target 可能已经因 immediate read 收到 SIGTTIN。Runtime 通过两级私有控制通道请求 trampoline 只向 target group 发 SIGTERM。direct leader 退出后 trampoline 继续检查同组后代，外层 wrapper/bwrap 在最多 800ms 宽限期保持存活，超时才强杀 containment group。reader 发现未换行输出超过上限时必须先原子投影 `output-limit-exceeded` 并唤醒 poll，再异步发送终止控制，不能让高负载下的 supervisor 调度延迟把已越界进程继续暴露为 `running`。
-- 验证：使用直接 bash target 启动同组后台子进程；leader 在输出 READY 后自然退出，仍存活的子进程收到 TERM 后由 trap 延迟 400ms 写 marker 并退出，terminate 返回前 marker 必须存在。正式 `command.exec` 测试夹具仍必须走允许的 `npm run` 等程序，不能为了构造 stdin race 绕过白名单直接解析 `bash -lc`。另跑 immediate stdin/EOF、Runner owner SIGKILL 和后代隔离用例，确认前台切组没有破坏交互或 fail-closed 回收；测试互斥锁在前序 panic 后应恢复 guard 继续报告后续独立结果，不能用 `PoisonError` 掩盖真实失败范围。
+- 验证：使用直接 bash target 启动同组后台子进程；leader 打印 READY 后用 `wait` 保持存活直到 terminate 真正到达（leader 若自己先退出，客户端调度就被拖进 800ms 宽限窗口，见 2026-10-04「graceful terminate 断言」条），仍存活的子进程收到 TERM 后由 trap 延迟 400ms 写 marker 并退出，terminate 返回前 marker 必须存在。正式 `command.exec` 测试夹具仍必须走允许的 `npm run` 等程序，不能为了构造 stdin race 绕过白名单直接解析 `bash -lc`。另跑 immediate stdin/EOF、Runner owner SIGKILL 和后代隔离用例，确认前台切组没有破坏交互或 fail-closed 回收；测试互斥锁在前序 panic 后应恢复 guard 继续报告后续独立结果，不能用 `PoisonError` 掩盖真实失败范围。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/process_session.rs`、`process_session_bridge.rs`、`command_sandbox_trampoline.rs`。
 
 ## 启动记录必须封闭状态组合，child 不能自行猜 durable commit 超时
@@ -6280,7 +6296,47 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **根因 3（工具被拒）**：sidecar 用 `permissionMode: 'dontAsk'` 且没有 `allowedTools`，宿主 MCP 工具（`mcp__agc__*`）一律被直接拒绝，模型只能回"没有权限"。
 - **根因 4（界面看不到回复）**：聊天区是按 `item.completed` 事件流投影的（codex 路径在 `rawResponseItem/completed` 时下发 `ThreadItem::Message`），只把回复落进 `project.jsonl` 不会让本轮出现在界面上——用户看到"用户气泡 + 本轮结束于 … · 耗时"，回复只在重进项目时从历史读出来。
 - **根因 5（验收反馈复用 assistant ID）**：同一 client turn 进入 `ReviewRequired` 后会再次调用 cc。首次回复已经占用 `direct-codex:<clientTurnId>:assistant`，第二次不同正文沿用该 ID 会被历史层正确拒绝为冲突，随后却被错误投影成 `runtime-unclassified`。真实诊断中可见「写入本项目对话历史失败：…assistant」且历史已经有该条回复。
-- **现行口径**：cc 成功出口由放行侧补写 `DirectTurnTerminal::completed()`（`finish_if_unfinished` 幂等，codex 已写过终态时是空操作）；cc 每次解析成功后都把实际落盘的回复 item id 同步下发 `ThreadEvent::item_completed(ThreadItem::Message{role:"assistant"})`。首个回复沿用 `direct-codex:<clientTurnId>:assistant`，同一回合的反馈回复遇到内容冲突时追加 `:assistant:<uuid>`，相同内容仍按原 ID 幂等；落盘失败按回合失败收口。sidecar 按 `mcp__<server>` 前缀整体放行请求里声明的 MCP 服务器（权限策略在宿主侧执行）。
+- **根因 6（cc 字符串错误覆盖了上游分类）**：DirectProject 的 Claude Code 路由原本把 sidecar 返回的所有字符串都包装成 `LlmError::Transport`，因此 HTTP 429、401、408、5xx、sidecar 超时、空回执和无效 JSON 都显示成「执行通道未能建立或已断开」。
+- **根因 7（内部 Claude MCP 桥误用外部只读模式）**：Claude Code sidecar 使用的 loopback MCP 原本调用 `start_external_client_tool_bridge(..., false)`，桥状态 `direct_turn_execution=false` 且没有 `begin_user_turn()` 授权；`agc_register_delivery_contract`、`agc_delivery_status`、`agc_update_plan` 每次都会返回 `ToolRequiresDirectTurn`，模型收到错误后又重复注册计划，最终陷入反馈死循环直到超时。
+- **根因 8（MCP 全局单槽位）**：外部 MCP 注册表原本只有一个 `Option<ExternalMcpServer>`，不同项目的 Claude 回合会互相 abort；一个回合结束时的全局 stop 还可能误停另一个项目的桥。
+- **现行口径**：cc 成功出口由放行侧补写 `DirectTurnTerminal::completed()`（`finish_if_unfinished` 幂等，codex 已写过终态时是空操作）；cc 每次解析成功后都把实际落盘的回复 item id 同步下发 `ThreadEvent::item_completed(ThreadItem::Message{role:"assistant"})`。首个回复沿用 `direct-codex:<clientTurnId>:assistant`，同一回合的反馈回复遇到内容冲突时追加 `:assistant:<uuid>`，相同内容仍按原 ID 幂等；落盘失败按回合失败收口。Claude Code 的失败文本先投影到与 Codex 相同的 `LlmError` 分类：HTTP 状态、sidecar 超时、空回执和无效 JSON 分别复用上游、超时、空响应和反序列化语义；上游状态摘要与重试建议按状态码给出。内部 Claude Direct MCP 必须使用 `direct_turn_execution=true` 的工具桥并持有 `begin_user_turn()` guard；用户手动启动的外部 MCP 仍保持非 Direct 模式。MCP 注册表按 canonical project root 分桶，停止操作再核对 server token，迟到的旧回合不能误停同项目的新桥。sidecar 按 `mcp__<server>` 前缀整体放行请求里声明的 MCP 服务器（权限策略在宿主侧执行）。
 - **诊断口径**：`agent.direct_turn.host_dropped` / `agent.direct_turn.panic` 里的令牌字段必须写 `tt=`，写 `turnToken=` 会命中脱敏标记，整行变成 `<sensitive diagnostic details redacted>`，离线只剩"说不出原因"的 HostDropped。
 - **验证**：dev 栈里用 CDP 注入真实回合（`node %TEMP%\agc-cdp.mjs <expr>`）：①读文件轮 `claude-parse-done chars=108`，`.agent/conversations/project.jsonl` 出现 `direct-codex:cdp-…:assistant` 条目，回复内容与 `game/index.html` 前两行（`<!doctype html>` / `<html lang="zh-CN">`）逐字一致（证明宿主工具真的执行了）；②聊天视图打开时注入 `只回三个字：收到了`，DOM 断言（`document.body.innerText`）同时出现用户气泡 `11:40:05`、助手回复 `收到了` 与 `本轮结束于 11:40:16 · 耗时 10.7秒`（证明 `item.completed` 实时投影生效，不必重进项目）；同一日志不再出现新的 `host_dropped`。另有 `agent::claude_code_cli::tests::direct_claude_feedback_reply_does_not_fail_on_a_reused_client_turn_id` 回归覆盖同一回合两次不同回复。`cargo test … -- claude_code_cli::tests direct_turn_failure::tests` 19 passed。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/thread_manager/dispatch.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/direct_turn_failure.rs`、`apps/ai-game-creator-shell/src-tauri/src/agent/claude_code_cli.rs`、`apps/ai-game-creator-shell/agent-sidecar/src/index.mjs`。
+
+## 2026-10-03 AGC 测试不在任何 tsconfig 里时，`satisfies` / `vi.fn<(...)>` 这类类型断言是空写
+
+- **现象**：`apps/ai-game-creator-shell/tests/` 从未进过任何 tsconfig，vitest 0.34 用 esbuild 转译不做类型检查，`satisfies TurnFailure`、`vi.fn<(input: X) => void>()` 全部静默通过。把 tests 挂进 `tsconfig.tests.json` 后一次暴露 683 条既有错误（99 个文件、约 47% 的测试文件），单个文件最多 73 条。
+- **根因 1（配置缺口）**：app `tsconfig.json` 的 `include` 只有 `["src","vite.config.ts"]`；根 `typecheck` 只跑 `tsconfig.typecheck-guardrails.json` 的根 `src` 白名单；CI `agc-web` lane 只跑 vitest。三处都不覆盖 app tests。
+- **根因 2（vitest 0.34 口径）**：本仓库固定 `vitest@0.34.6`，其 `fn<TArgs extends any[], R>` 收的是**参数元组**；写成 vitest 1.x 习惯的 `vi.fn<(input: X) => void>()` 会把函数类型当作 `TArgs`，报 `TS2344`（constraint `any[]`）并连带 `TS7053`/`TS2493`。正确口径是 `vi.fn<[X], R>()` 或直接 `vi.fn(impl)`；`.mock.calls[0]` 在 `noUncheckedIndexedAccess` 下需要非空断言。
+- **根因 3（脚本 `.mjs`）**：测试 import `../scripts/*.mjs`，`allowJs: false` 报 `TS7016`；打开 `allowJs` 后 TS 按 JS 默认值推导出过窄签名（回调参数、`spawn`/`spawnSync` 重载、`never[]`、`null`），需要在测试里按运行时真实契约声明局部签名。
+- **根因 4（过期桩）**：62 条 `TS2339/TS2353/TS2739/TS2741` 是测试桩与当前真实类型脱节（字段被删除/改名/新增必填），例如 `setAgentChatProjectPath`、`conversationKey`、`runId`、`supervisor`→`chat`。
+- **现行口径**：见 `development-workflow.md` 的「AGC 测试类型门禁」；tests 必须 0 error，不引入基线或豁免，只改类型层。
+- **环境提示**：Node 24+ 默认启用实验性 Web Storage，全局 `localStorage` 未配置即 `undefined`，会顶掉 vitest 0.34 jsdom 环境里的 Storage，`recentProjectsHook.test.tsx`、`gameDistributionPublish.test.ts` 在 Node 26 上失败（HEAD 即如此）。项目按 `@types/node ^22.14` 面向 Node 22，本机用 fnm 装 v22.23.3 并设为 default（`~/.configure/profile.d/fnm.sh` 在 shell 启动时 `eval "$(fnm env)"`），Node 22 不暴露该全局、jsdom 的 localStorage 正常，仓库无需任何改动。不要用 `--localstorage-file=…` 绕：那只是把 Node 自己的文件型 Storage 顶上来，多个用例文件共享同一份状态。
+- **关联**：`apps/ai-game-creator-shell/tsconfig.tests.json`、`apps/ai-game-creator-shell/package.json`、`apps/ai-game-creator-shell/tests/`。
+
+## 2026-10-04 tracing 的 callsite interest 是进程级缓存：并发测试会把 span 调用点缓存成 never，span 看起来"根本没产生"
+
+- **现象**：`app::tests::http_tracing::unavailable_router_rejection_keeps_generated_context_and_headers` 偶发 `each rejected request should have one HTTP span  left: 0 / right: 1`（`server-rs/crates/api-server/src/app.rs`），同一族断言在 `server-rs/crates/platform-llm/src/observability_tests.rs` 偶发 `provider_spans.len() == 1` 失败。同一批代码时而绿时而红，且失败用例都是最早跑的一批。
+- **原因**：`span!`/`info_span!` 宏在调用点缓存 interest 为 `never` 时**静默返回空 span**，连 `new_span` 都不会调用（tracing 0.1.44 `macros.rs` 的 `span!` 分支）。而 `DefaultCallsite` 的 interest **只在调用点首次被命中时算一次**，且计算时用 `DISPATCHERS.rebuilder()`——进程里只注册过一个 dispatcher 时它会退化成 `dispatcher::get_default()`，即**命中线程自己的 dispatcher**（tracing-core 0.1.36 `callsite.rs` 的 `Rebuilder::JustOne`）。libtest 默认并发跑同一二进制里的上千个用例，没有 subscriber 的测试线程一旦抢到 `http.request` / `llm.request` 调用点的首次注册，就会把它永久缓存成 `never`。`with_subscriber` 只在**每次 poll** 设线程本地 dispatcher，纠正不了这个进程级缓存，于是"span 没产生"。
+- **处理（现行口径）**：测试采集不要依赖 `with_subscriber`。改为在整个被测流程期间持有 scoped default（`tracing::subscriber::set_default`，其内部 `Dispatch::new` 会触发 tracing 重建 interest 缓存），并用同一调用点预热探测到连续两轮采集成功为止；测试 subscriber 显式实现 `register_callsite`（目标 span 恒 `always`、其余 `sometimes`），避免自己的重建把其它调用点永久标记成 `never`。**不要**把断言改成"允许 0 个 span"，**不要** sleep 赌时序。
+- **验证**：`cargo test --locked -p api-server --bin api-server app::tests::http_tracing`（默认并发与 `--test-threads=1` 各连跑 20 次）、`cargo test -p platform-llm observability_tests`；更接近 CI 并发的是整段 `app::tests::`（91 用例同进程）与 `--skip bgfilter_worker --skip wallet_refund_outbox` 的全量 bin（1133 用例）连跑。
+- **关联**：`server-rs/crates/api-server/src/app.rs`、`server-rs/crates/platform-llm/src/observability_tests.rs`。
+
+## 2026-10-04 AGC 通知计数与 graceful terminate 的断言偶发都来自"跨线程 / 跨用例串台"
+
+- **现象**：`agent::thread_manager::tests::active_turn_changes_publish_one_notification_per_real_change` 偶发 `left: 8 / right: 7`（进度内容变化必须通知一次）；`process_session::tests::process_session_graceful_terminate_keeps_wrapper_alive_for_target_cleanup` 偶发 `left: "exited" / right: "terminated"`；两者都在 `AI game creator shell Rust lane 2/2` 分片里红。
+- **原因 1（通知计数串台）**：测试计数器 `DIRECT_ACTIVE_TURNS_EVENT_TEST_COUNT` 在 *2026-10-01 已按线程作用域隔离*（`thread_local! Cell`），但 2026-10-02 退役 `runtime_driver` 把这段接缝搬进 `agent/direct_events.rs` 时**降级回进程级 `static AtomicU64`**。`--test-threads=1` 只串行测试线程，宿主 `tauri::async_runtime` 的后台回合仍在自己的工作线程上广播「运行中的项目」变了，于是断言取到别的回合的广播。
+- **原因 2（terminate 竞速）**：测试命令里 leader 打印 READY 后立刻 `exit 0`，同组后代仍存活，trampoline 从 leader 被回收那一刻开始 `PROCESS_SESSION_TARGET_TERMINATE_GRACE_MS=800ms` 宽限；客户端只要在 leader 退出后 >800ms 才发出 terminate（CI 高负载下要跨 durable record 写盘、registry 注册、线程 spawn），会话已按 `exited` 收口，terminate 只能读到既成事实——不是产品缺陷，是测试赌了客户端调度。
+- **处理（现行口径）**：①测试专用的通知计数必须留在测试线程作用域（`thread_local! Cell`），不要用进程级 Atomic；②graceful terminate 用例的 leader 打印 READY 后要用 `wait` 等后台子进程，让 terminate 必然落在会话仍 running 时（断言、trap、`sleep 0.4`、marker 名字都不改）。
+- **验证**：①修复前把计数器临时改回 Atomic 时同一并行口径 42/50 红；修复后并行 50 次 0 红、`--test-threads=1` 200 次 0 红、CI 现场等价块（145 用例）3 次 0 红；②该用例是 `#[cfg(target_os = "linux")]`，Windows 本机跑不到，用真实 Linux 内核（WSL Alpine）验证命令形状：leader 活到 TERM、同组后代完成 400ms 延迟清理（marker=done，real 0.41s）、清理后组内零残留；CI 侧仍应跑 `node apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs --shards=4 --shard-index=4` 复核。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_events.rs`、`apps/ai-game-creator-shell/src-tauri/src/process_session/tests.rs`、`command_sandbox_trampoline.rs`。
+
+## 2026-10-04 SPA 深链的前缀路由（`/pay/<checkoutToken>`）必须进 allowlist，裸前缀不够
+
+- **现象**：只把 `/pay`、`/profile/payment` 加进 Nginx SPA allowlist 让门禁变绿，并不代表真实收银台链接能打开。`payment.rs` 生成的 `checkoutUrl` 是 `/pay/<checkoutToken>`，三份模板原先只有 `location ~* "^/(?:…|pay|profile|profile/payment|…)/?$"` 这条精确 location，深链落回默认 `location /` 的 `try_files $uri $uri/ =404` → **404**。
+- **原因/代价**：前端 `resolveSelectionStageFromPath` 用 `startsWith('/pay/')` 判定并取最后一个路径段当 token，Nginx / Pingora 侧却只放行裸前缀（2026-10-03 的支付接入 commit 只改了前端路由源）。同一批漂移里还有一条被掩盖的失败：`check:nginx-spa-routes` 在 `npm run lint` 链里先跑，它红的时候看不到后面的 `check:pingora-route-parity` 也红（Pingora `MAIN_SPA_PATHS` 缺 `/pay`、`/profile/payment`）——修一条门禁时要把整条链跑到底，不要只看第一个红。
+- **处理（现行口径）**：前缀路由的真相源是 `src/routing/activeAppPageRoutes.ts` 的 `APP_PREFIX_ROUTE_ENTRIES`。`scripts/check-nginx-spa-routes.mjs` 据此要求三份模板都写锚定前缀 location（`location ~* "^/pay/[^/]+/?$"`，只放行「前缀 + 恰好一个路径段」，裸前缀仍由精确 location 负责，并要求镜像精确 location 的维护闸）；`check:pingora-route-parity` 要求 Rust 的 `MAIN_SPA_PREFIX_PATHS` 与 `is_main_spa_prefix_path` 同口径（大小写不敏感、多段与 `/payment/x` 这类同名邻居不收）。
+- **别踩**：不要写成裸前缀正则（`^/pay`）——它会吞掉 `/payment/x`、`/paycheckout/x` 这类同名邻居；也不要把深链塞进精确 allowlist 的 alternatives 里（`pay` 的 alternatives 只匹配 `/pay`）。
+- **判据/取证**：`node --test scripts/check-nginx-spa-routes.test.mjs`（正/反用例，含「写回精确匹配即红」）、`npm run check:nginx-spa-routes`、`npm run check:pingora-route-parity`、`cargo test -p pingora-gateway -- pay_checkout_deep_link matches_nginx_route_parity_matrix`；线上复验 `curl -s -o /dev/null -w '%{http_code}' https://<平台域名>/pay/<checkoutToken>` → 200 且正文与 `/` 同一份 `index.html`。
+- **关联**：`scripts/check-nginx-spa-routes.mjs`、`deploy/pingora/nginx-route-parity.matrix.json`、`server-rs/crates/pingora-gateway/src/main.rs`、`server-rs/crates/api-server/src/payment.rs`、`deploy/nginx/genarrative.conf`。