Merge branch 'master' into opt/win-ssache

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

@@ -1,5 +1,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 卡死，更不能重放不确定写操作。

docs/【技术方案】AGC客户端稳定版生命周期大切换-2026-09-14.md

@@ -59,6 +59,15 @@
 - 稳定版基础切换里程碑已完成；后续入口只允许复用该合同，不再新增 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 恢复或失败关闭合同，因此本轮按现有实现接入统一投影，不重复重写：
@@ -82,4 +91,17 @@
 | 最近项目逐行刷新 | `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`）是否会放过并行写，尚未排除误报。