合并 master（48eb3d500）：CI 缓存与运行时测试重组并入运行页入口收口

- 只冲突 docs/project-memory/shared-memory/pitfalls.md：保留双方新增的排障记录（本分支的 Codex 原生包版本 + master 的 Rust 对象快照）
- 其余 master 改动（CI 缓存脚本、process_session 测试拆分等）自动合并

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

@@ -4,7 +4,7 @@
 
 ## 标准流程
 
-前端测试稳定性验证使用根目录 `npm test`（与 Frontend tests job 相同），保留 Vitest 的 8 worker 上限。涉及异步资源展示时，组件测试必须 mock 所有会触发的网络请求，每次调用创建独立 `Response`，并等待最终 DOM 状态而非仅等待 fetch 被调用。换签 Hook 的测试通过 `vitest.config.ts` 的 include 纳入全量运行；新增测试文件后需确认实际执行名单，命令参数指定文件不会绕过 include 白名单。排查顺序依赖可使用 `npm test -- --sequence.shuffle --sequence.seed=9467`，但不能以重试成功替代失败原因分析。
+前端测试稳定性验证使用根目录 `npm test` 执行全量集合，保留 Vitest 的 8 worker 上限。CI 的 `Frontend tests` 使用 `npm run test:ci:frontend`，继承根配置并排除 `apps/ai-game-creator-shell/tests/**`；该目录由 `AI game creator shell web tests` 执行，两个 job 的 Vitest 文件集合互斥且并集等于本地全量。原生壳定向检查与 Repository checks 的 AppSurface 检查仍保留。涉及异步资源展示时，组件测试必须 mock 所有会触发的网络请求，每次调用创建独立 `Response`，并等待最终 DOM 状态而非仅等待 fetch 被调用。换签 Hook 的测试通过 `vitest.config.ts` 的 include 纳入全量运行；新增测试文件后需确认实际执行名单，命令参数指定文件不会绕过 include 白名单。排查顺序依赖可使用 `npm test -- --sequence.shuffle --sequence.seed=9467`，但不能以重试成功替代失败原因分析。
 
 用例隔离必须包括浏览器状态与 mock 实现：修改 `window.history` 后恢复基线路由；`spyOn(window, 'getSelection')` 等 spy 在用例结束后 restore；`clearAllMocks` 仅清调用记录，不能恢复被上一个用例替换的返回值。顺序打乱暴露的失败应修复泄漏来源，保留原有业务断言。
 
@@ -61,6 +61,8 @@ AGC 预览快捷操作的界面测试按独立命令或有状态短流程注册
 
 Rust 分片失败日志保留有界的失败详情，包括 panic 位置、断言和最终通过/失败数量；分片选中数量标为 selected，避免误读为失败数量。修改分片日志时运行 `node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`，用最小 Rust fixture 验证失败详情和成功摘要。
 
+Linux process-session 的 owner SIGKILL 测试在启动 owner 后立即建立清理 guard，正常结束和 panic 展开都必须终止并回收 owner，再按独立临时项目目录清理残留进程。先完成「杀掉 owner 后子进程自行退出」的原有断言，guard 只在退出测试作用域时兜底，不得提前清理子树使生命周期回归假绿；清理本身不得 panic 或无限等待。
+
 AGC 运行时配置默认值调整时，同步核对 Rust 默认值、分发配置模板、设置弹窗默认草稿和 `runtime-settings.suite.ts` 的恢复默认断言；显式传入旧值的配置读取用例仍验证原值保留，不批量替换测试数据。
 
 AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。
@@ -94,4 +96,6 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
 
 ## Gitea CI 依赖闭合
 
+AGC Rust lane 1 试点镜像内可信 sccache 对象快照，lane 2 保持直接 rustc 作为对照。维护者通过 `scripts/build-gitea-rust-cache.sh` 从远端 master 在限额、无宿主挂载的临时容器中生成快照，最终镜像只追加 sccache、对象和来源元数据，不包含源码或 target。PR 只写当前容器层、不回传，不开放 Docker API/发布权限；继续禁用 incremental。`ci-rust-cache.sh` 在快照缺失、工具链不符或 wrapper 探测失败时直接编译，并隔离远程缓存配置和 daemon。分片日志记录编译耗时，收尾输出命中统计。线上存在活跃 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 与 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 片：每次分片调用用 `--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 镜像缓存，再重跑门禁。

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

@@ -5950,3 +5950,12 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理（现行口径）**：在仓库根目录执行 `npm ci`（不要改成子目录或单包安装），随后 `node_modules/@openai/codex/package.json` 与 vendor 的 `codex-package.json` 版本应当一致。Windows 上 `npm ci` 会先 unlink 整个 `node_modules`：RustRover 的 Tailwind language server / `oxide-helper` 进程会占住 `@tailwindcss/oxide-*.node`，报 `EPERM: operation not permitted, unlink ...` 时先结束这些 helper 再重试，否则会停在半装状态。
 - **验证**：`npm ci` 后 `cargo build --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 通过，不再触发该 panic。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/build.rs`、`apps/ai-game-creator-shell/src-tauri/build_support/codex_bundle.rs`、`package-lock.json`。
+
+## 2026-09-22 Rust 对象快照必须对齐 CI 编译目录和 Cargo 环境
+
+- 现象：sccache 快照已包含数百 MiB 对象，但全新 target 的“热缓存”仍然全部 miss，甚至比直接 rustc 更慢。
+- 原因：Rust cache key 包含编译 cwd；sccache `0.18.0` 还会 hash `CARGO_*` 环境（jobserver、jobs 等少数例外除外）。不同 checkout 根目录、随机的 `CARGO_BUILD_RUSTC_WRAPPER` 路径、预热遗漏 workflow 的 HTTP/retry/color 环境都可能让整套缓存 miss。小型真实 Rust 实验显示仅配置 `SCCACHE_BASEDIRS` 不能消除 cwd 差异。快照存在不等于缓存有效。
+- 处理：预热使用已核实的 Gitea 路径 `/workspace/GenarrativeAI/Genarrative`，并与分片运行器一样从 AGC `src-tauri` 启动 Cargo；保存 `workspace.txt`，路径不符时回退直接编译。wrapper 放在容器内固定路径，daemon 状态与 Unix socket 仍使用随机私有目录；预热环境与 workflow 的 Cargo 环境由定向契约测试核对。不要为命中率随意增加 `RUSTFLAGS`、改写源码路径或恢复共享可写 target。
+- 验证：相同源码、资源上限和独立干净 target 下分别记录无缓存、冷缓存、热缓存的编译耗时和 hit/miss；只有真实热命中有净收益才切换候选镜像。PR 的写入始终留在 job 容器层，公共快照仍由可信维护流程生成。
+- 统计：job 私有 daemon 设置 `SCCACHE_IDLE_TIMEOUT=0`，由 `report` 显式停止；最终测试 bin 的不可缓存编译或测试可能超过一分钟，短 idle timeout 会让 daemon 提前退出，结尾查询启动新 daemon 后误报零次请求。容器销毁仍会回收该 job 的全部进程。
+- 磁盘：快照构建拒绝含 `/opt/genarrative-ci/rust-cache` 的基础镜像，始终从无对象缓存的镜像重建；容器内删除旧对象不能释放 Docker 底层。2 GiB 上限不涵盖宿主旧镜像及导出归档，切换验证后按运维文档人工保留当前版和一个回滚版，同时保护运行中 CI 使用的镜像。

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -288,12 +288,14 @@ npm run check
 
 ### Gitea Actions PR 门禁
 
+Linux process-session 的 owner SIGKILL 用例必须在启动 owner 后立即建立测试清理 guard：正常退出或断言 panic 时终止、回收 owner，并在有界时间内清理其独立临时项目目录中的残留进程。原有「owner 退出后子进程自行消失」断言在兜底清理之前执行，不能由 guard 代替生产生命周期验证。清理覆盖 panic 路径及临时项目间隔离，且不得因清理失败再次 panic。
+
 仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成九个必须通过的 job。job 声明顺序就是 runner 领取顺序，因此把两条 AGC 壳 Rust lane 排在最前：并发槽位不足时它们必须最先开始，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` 收集规则。
+- `Frontend tests`：按唯一根 workspace lockfile 执行一次干净的 `npm ci`，再独立执行根 `npm run test:ci:frontend`、`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:ci:frontend` 使用 `vitest.frontend-ci.config.ts` 继承根配置，仅排除 `apps/ai-game-creator-shell/tests/**`，由 `AI game creator shell web tests` 执行该目录，避免两个 job 重复运行 AGC 前端测试；本地 `npm test` 仍执行原有全量集合。CI 契约测试使用 Vitest 实际文件发现验证两组互斥、并集等于全量；原生壳定向检查与 Repository checks 的 AppSurface 检查仍保留。其中 `.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: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 依赖。
@@ -330,6 +332,22 @@ workflow 首次成功运行后，**不**把 Project CI 的 job 配成 Gitea `mas
 
 master 日常交付必须禁止直接 push，只允许经 PR 在最近一次 Project CI 全绿后合并；本地 `pre-commit` 的 staged ESLint/Prettier 和 master `pre-push` 的 Repository checks parity 只用于提前发现问题，可被 `--no-verify` 绕过，不能充当服务端权威门禁。紧急直推白名单如需保留，应按人员和时限最小化，并要求执行同一 `npm run check:repository-ci <base> <head>` 后回读 push CI。
 
+#### AGC Rust lane 1 的隔离编译缓存试验
+
+每次生成快照必须使用不含对象缓存的原始 CI 基础镜像；构建脚本在拉取源码和预热前拒绝已存在 `/opt/genarrative-ci/rust-cache` 的基础镜像，避免重复叠加不可释放的旧对象层。切换并完成真实 CI 验证后，按 `deploy/container/README.md` 的保留规则人工定向清理旧缓存镜像及归档，保护运行中 CI 使用的版本。
+
+只在 `AI game creator shell Rust lane 1/2` 启用 sccache，lane 2 保持直接 rustc。继续设置 `CARGO_INCREMENTAL=0`，不共享 target、不恢复 Actions 可写缓存。可信快照通过已有固定 Image ID 分发：镜像只增加固定版本的 sccache、编译对象和来源元数据，不包含源码、target 或凭据；容器写时复制层承接本 job 的新增对象，job 删除后丢弃，PR 没有 Docker API 或快照发布权限。该权限边界由 runner 基础设施保证，不能仅用 workflow 的分支条件替代。
+
+维护者在受信任 checkout 中运行 `bash scripts/build-gitea-rust-cache.sh <已验证基础镜像> <候选镜像tag>`。脚本从 origin 获取 master 的确定提交，在无宿主目录挂载、无凭据且有 CPU/内存上限的临时容器中编译 AGC bin 测试，仅导出 sccache 对象；最终镜像从原基础镜像重新组装，不提交预热容器。公共快照不接受 PR 上传，也不复用 Jenkins 发布缓存。工具链或系统依赖变化时重新生成快照，缓存命中仍由 sccache 的编译输入校验决定，不能省略 Cargo 构建。
+
+lane 1 在编译前执行 `scripts/ci-rust-cache.sh prepare`：检查快照与 rustc 身份，隔离 sccache 配置和 daemon，限时探测真实 wrapper。旧镜像没有快照或探测失败时保留空 wrapper，输出 fallback 原因；缓存故障不得把真实编译/测试失败改成成功，也不允许重跑整个测试组掩盖失败。结束时 `report` 输出命中统计；分片日志单独记录 Cargo 编译耗时。对象缓存上限为 2 GiB，最终测试 bin 的链接仍须执行。
+
+候选镜像沿用 `gitea-ci-job-image.sh verify/export/load-runner` 验证和装载。现役 CI 正在运行时只允许准备候选镜像，不停止 job、不重启 runner、不切换标签；待确认无运行中的 job 后再按上述镜像更新顺序切换。验收分别记录独立 target 的无缓存、冷缓存和热缓存构建耗时及命中率，并检查失效/故障回退、两容器写入互不影响。未完成真实 CI 验证前不能宣称提速或推广到其它 job。
+
+Rust 对象 key 包含编译工作目录。预热必须使用已核实的 Gitea checkout 路径 `/workspace/GenarrativeAI/Genarrative`，并像分片运行器一样从 `apps/ai-game-creator-shell/src-tauri` 启动 Cargo；快照保存 `workspace.txt`，job 根路径不符时直接编译，避免零命中的缓存开销。不要仅设置 `SCCACHE_BASEDIRS` 就假定 Rust 可以跨 cwd 命中，也不为缓存改写 `RUSTFLAGS` 或源码路径语义。固定 sccache `0.18.0` 的基础设施错误码 `2` 会由 wrapper 回退执行本次 rustc；其它退出码原样返回，升级 sccache/Rust 时须复核此约定。
+
+sccache `0.18.0` 还会 hash 大部分 `CARGO_*` 环境变量。因此 wrapper 固定在每个容器自己的 `/opt/genarrative-ci/rust-cache/rustc-wrapper`，prepare 重写 launcher 后才启用；daemon 状态与 socket 仍各自随机隔离。预热同步 workflow 的 `CARGO_INCREMENTAL`、`CARGO_HTTP_MULTIPLEXING`、`CARGO_NET_RETRY` 和 `CARGO_TERM_COLOR`，由现有 CI 契约测试验证一致；新增 Cargo 环境配置时须同步评估 cache key，不能只看快照文件是否存在。
+
 SpacetimeDB bindings：
 
 ```bash