Merge remote-tracking branch 'origin/codex/ai-game-creator-app' into HEAD

apps/ai-game-creator-shell/scripts/check-config.mjs

@@ -436,6 +436,28 @@ async function runConfigWizardRegressionChecks() {
     path.join(os.tmpdir(), 'genarrative-agc-config-check-'),
   );
   try {
+    const canonicalTestRoot = fs.realpathSync.native(testRoot);
+    const realConfigAncestor = path.join(testRoot, 'real-config-ancestor');
+    const linkedConfigAncestor = path.join(testRoot, 'linked-config-ancestor');
+    fs.mkdirSync(realConfigAncestor);
+    fs.symlinkSync(
+      realConfigAncestor,
+      linkedConfigAncestor,
+      process.platform === 'win32' ? 'junction' : 'dir',
+    );
+    const missingLinkedConfigDir = path.join(
+      linkedConfigAncestor,
+      'missing-appdata',
+    );
+    assert.equal(fs.existsSync(missingLinkedConfigDir), false);
+    assert.equal(
+      await assertSafeGameCreatorConfigDestination(missingLinkedConfigDir),
+      path.join(
+        fs.realpathSync.native(realConfigAncestor),
+        'missing-appdata',
+      ),
+    );
+
     const gitRoot = path.join(testRoot, 'tracked-repository');
     const trackedConfigDir = path.join(gitRoot, 'runtime-config');
     fs.mkdirSync(trackedConfigDir, { recursive: true });
@@ -463,7 +485,7 @@ async function runConfigWizardRegressionChecks() {
     const outsideConfigDir = path.join(testRoot, 'outside-appdata');
     assert.equal(
       await assertSafeGameCreatorConfigDestination(outsideConfigDir),
-      outsideConfigDir,
+      path.join(canonicalTestRoot, 'outside-appdata'),
     );
     await assert.rejects(
       assertSafeGameCreatorConfigDestination(outsideConfigDir, {
@@ -476,7 +498,7 @@ async function runConfigWizardRegressionChecks() {
       await assertSafeGameCreatorConfigDestination(dedicatedConfigDir, {
         requireDedicatedLeaf: true,
       }),
-      dedicatedConfigDir,
+      path.join(canonicalTestRoot, appIdentifier),
     );
 
     const injectedNonGitConfigDir = path.join(testRoot, 'injected-non-git');
@@ -489,7 +511,7 @@ async function runConfigWizardRegressionChecks() {
               'fatal: not a git repository (or any of the parent directories): .git\n',
           }),
       }),
-      injectedNonGitConfigDir,
+      path.join(canonicalTestRoot, 'injected-non-git'),
     );
     await assert.rejects(
       assertSafeGameCreatorConfigDestination(

apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts

@@ -4231,7 +4231,7 @@ export function registerProjectSupervisorSurfaceTests() {
           ([command]) => command === 'get_local_game_preview_status',
         ).length,
       ).toBeGreaterThan(previewStatusReads);
-    });
+    }, { timeout: 3000 });
     expect(driver.readAuthorization()?.authorizationId).toBe(
       steerAuthorizationId,
     );

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

@@ -3737,6 +3737,7 @@
 - 处理：GUI 与 `npm run agc:config` 共用系统 AppData `game-creator.config.json`，终端隐藏输入 API Key 并禁止 `--api-key`；更新时保留 `agentLlm`、`editorApi`、`mcpServers` 等其它配置，POSIX 权限维持目录 `0700` / 文件 `0600` 并原子替换。显式 `--config-dir` 必须以 `world.genarrative.ai-game-creator` 为独立叶目录，不能让向导对 `/tmp`、AppData 根或共享目录整体 chmod / 重建 DACL。隐藏输入调用 `stdin.resume()` 后必须记住原 pause 状态，在成功、取消、异常和 `SIGINT / SIGTERM / SIGHUP` 路径恢复 raw mode 并 `pause()`，信号恢复后重发；只移除 `data` listener 会让 `--configure-only`、配置检查失败或 Ctrl+C 保持活动 stdin。缺配置时仅 TTY 人工会话可询问进入向导，非 TTY 立即失败并提示配置命令。
 - Windows 密钥复制：`mode: 0o600` 和 POSIX `chmod` 在 Windows 上不能代替 DACL。隔离 AppData 目录必须先设置仅当前用户、禁止继承的 DACL；目标配置文件先以空文件创建并收紧 DACL，之后才允许把 API Key 字节写入。先 `copyFile` 再依赖 Rust 只读检查或事后收紧会留下密钥暴露窗口，也可能因继承 ACL 不满足 Runtime 合同而在首次 `--llm-status` 失败。
 - Windows PowerShell 参数：不要把 DACL 目标路径和目录标记直接追加在 `powershell.exe -Command <script>` 后；Windows Node `spawn` 会让 PowerShell 5.1 把这些值拼入命令文本，带空格的临时路径会被拆分并使 `GetFullPath($args[0])` 失败。当前实现只通过子进程私有环境变量传入路径和布尔值，并由真实 Windows `npm run agc:typecheck` 覆盖 DACL 回归。
+- 跨平台临时路径比较：macOS 的 `os.tmpdir()` 可返回 `/var/folders/...`，而 `realpath` 会返回同一目录的 `/private/var/folders/...`；Windows 也可存在驱动器号大小写、junction 或链接解析差异。测试安全路径函数时，fixture 期望值必须基于平台原生 `realpath` 后的根目录构造，不能直接与 `mkdtemp` 的逻辑路径字符串严格比较。不能只依赖开发机自带的路径别名；CI 应创建真实父目录、指向它的符号链接（Windows 使用 junction）和不存在的叶目录，断言安全函数返回真实父目录下的叶路径。`realpath` 和全部断言都应放在 `try/finally` 内，确保失败也能清理 fixture。
 - 超时与进程树：`setTimeout` 后只对直接 Cargo PID 调一次 `kill()` 不是硬超时；Cargo 启动的 CLI / Runner 仍可能持有 stdio，使 `close` 永远不返回，清理阶段也可能无界等待。POSIX 必须创建独立进程组并按负 PID 终止，Windows 必须使用 `taskkill /T`；宽限期后升级强杀，Runner shutdown 和清理另设短硬超时。重复 Ctrl+C 也必须升级，不能一直被自定义 signal handler 吞掉。
 - 模式拆分：自动化使用默认的 `agc:test:chat`，由脚本投递固定植物塔防需求；正式产物、最新 revision 静态检查和 Runtime 浏览器验收通过后立即收束并清理，不启动持续 preview。`agc:test:chat:manual` 不注入 `--task`，用于多轮 stdin 手工聊天，并保留 preview 直到显式退出；不能用 EOF 或是否存在 `game/index.html` 猜测当前模式。
 - 验证：覆盖 `--api-key` 拒绝、各平台 AppData 路径、Provider 预设、旧配置节点保留、URL 安全校验、原子写入、POSIX 权限、隐藏输入恢复 pause、Windows 写密钥前 DACL、整棵进程树超时终止、缺配置时 TTY / 非 TTY 分支，以及 `--task` 成功后不进入长期 preview、手工模式仍可持续试玩。测试和错误输出只验证“密钥已配置”状态，不读取或打印密钥本体；源码字符串断言和 Linux 上的 Windows mock 不能替代真实 Windows ACL / `taskkill` 复验。
@@ -3921,6 +3922,7 @@
 - 根因：旧实现调用 `start_local_game_preview` 前就把“项目 + parent run”的授权加入 attempted 集合并清空；首版完成投影与后续专业任务仍在写项目时，启动恰逢项目写锁竞争，catch 只显示错误却无法重试。
 - 约束：一次性语义应按“成功或确定性终态”消费，不按“函数调用次数”消费。项目写锁竞争保留同一授权并轮询重试；成功、显式 deny 与非瞬时失败才清除。授权需持久化项目路径和 accepted runId，重启恢复时仍必须逐项匹配，切换项目不得继承。
 - 回归：AppSurface 模拟第一次 `start_local_game_preview` 返回 `项目正在被其他写操作占用`、第二次成功，断言最终渲染游戏区域且启动调用恰为两次；完整 AppSurface 仍需覆盖显式 deny、停止隐藏与项目切换隔离。
+- CI 时序：生产预览状态每 `1000ms` 轮询一次，回归若也使用 `waitFor` 默认 `1000ms` 上限，会在 CI 负载下于首次 interval 回调附近竞争超时。验证“授权保留期间仍继续轮询”应使用明确 `3000ms` 上限，不改生产轮询周期。合并长测试文件后还要运行全量 ESLint；单纯 autofix 只会排序、不会消除两个分支同时引入的重复 import。
 
 ## 跨窗口 CAS 锁不能用 mtime stale 删除模拟系统互斥（2026-07-30）
 

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -43,7 +43,7 @@
 - 固定试玩契约：`generic-v1` 初始状态必须为 `ready` 且 `level > 0`；点击 start 后 sequence 必须推进、phase 必须进入 `playing`，并先持续观察 2 秒、取得至少 8 个实际样本，期间保持 `playing`，以确认玩家获得正常操作机会。随后必须点击唯一可见、启用且真实可交互的 `data-playtest-id="primary-action"` 控件；该控件必须映射游戏的真实主要玩法操作，并以 sequence 相对点击前严格推进证明操作已被接受。玩家获得这次正常操作机会之前进入 `won | lost` 属于过早结束并失败；操作被接受后的单次 `lost` 是合法游戏结局，但不能成为所有受控尝试的唯一结果；若主要操作后仍为 `playing`，则继续观察 3 秒并取得至少 12 个实际样本，`won` 可提前证明非失败推进。点击 restart 后 sequence 必须再次推进并恢复到 `ready | playing`，随后持续观察 3 秒且取得至少 12 个实际样本。若首轮结果为 `lost`，重开稳定后必须再执行一次必要的 start、2 秒 / 8 样本操作机会和真实 primary-action；第二次必须进入或保持 `playing`（再观察 3 秒 / 12 样本且不得转为 `lost`）或进入 `won`，两次都固定 `lost` 代表无法正常推进的恶性 bug，必须失败。各观察窗口内 sequence 不得回退，restart 窗口只能保持 `ready | playing`；样本数门槛不能替代时长门槛，窗口末端必须强制再读取一次有效状态，不能只在前段快速取得足够样本后提前通过。控件 selector、观察时长、最少样本数、终态边界、非失败推进、末端覆盖、sequence 单调 / 严格推进规则及完整 required assertions 都进入 scenario fingerprint。读取旧 fingerprint 回执和检查 plan liveness 时，把合同升级造成的 fingerprint 不匹配视为 stale missing，允许同一 run 重新执行 `preview.validate` 自愈；身份、路径、digest 或内容完整性篡改仍失败关闭。最终完成门每次按当前合同重算 fingerprint，并严格拒绝旧 fingerprint、旧 assertion 集或仅保存历史 `passed=true` 的证据。
 - 试玩证据展示：game-chat 的进度卡、可玩 revision 和自动预览只接受结构化 `preview.validate` detail 同时满足 `passed=true` 与 `playtestPassed=true`；工具 summary 中的 `：ok` 不能作为兜底。`image.inspect` 的 `status=ok` 只代表工具执行成功，不代表视觉验收通过；结构化 `passed=null` 或缺少布尔结论时，UI 必须以中性“截图分析完成”展示，只有显式 `passed=true` 才能显示“截图检查通过”。
 - 一次性自动预览授权：用户在该入口成功提交本轮自主生成需求，即视为对“当前项目 + 当前 Supervisor 父 run”的一次 `preview.start` 授权。授权以仅含项目路径与 accepted parent runId 的客户端本地记录持久化，App / WebView 重启后仍可恢复，但项目或 run 身份不匹配时不得使用。只有当前 accepted parent run 成功完成 `preview.validate` 且给出有效 revision 后，客户端才可消费授权，由 Tauri 首次启动并自动展示该 revision 的用户可见预览；一次授权最多成功启动一个 Tauri preview server，并必须继续走现有权限、项目写锁、审计和客户端 `PreviewRegistry` 链路。项目或 Agent 策略的显式 deny 始终优先，不得被此授权绕过。启动成功、显式 deny、非瞬时失败、父 run 在首版验证前终止或切换项目后授权失效；`preview.start` 恰逢项目写锁竞争属于瞬时失败，不消费授权，释放写锁后由同一轮询链路重试。
-- 增量预览刷新：Tauri 客户端记录当前 iframe 已展示的 validated revision；同一当前 run 后续成功 `preview.validate` 的 revision 严格高于已展示 revision 时，只在原 Tauri preview server 和原 loopback origin 上刷新 iframe，不得再次调用 `preview.start`、新增 server 或切换到 Runner registry。相同或更低 revision 不触发刷新。preview HTTP server 对 HTML、脚本、样式、资源和错误响应统一发送 `Cache-Control: no-store`，iframe 刷新必须读取新 revision，不能继续命中 WebView 缓存中的旧版本。
+- 增量预览刷新：Tauri 客户端记录当前 iframe 已展示的 validated revision；同一当前 run 后续成功 `preview.validate` 的 revision 严格高于已展示 revision 时，只在原 Tauri preview server 和原 loopback origin 上刷新 iframe，不得再次调用 `preview.start`、新增 server 或切换到 Runner registry。相同或更低 revision 不触发刷新。preview HTTP server 对 HTML、脚本、样式、资源和错误响应统一发送 `Cache-Control: no-store`，iframe 刷新必须读取新 revision，不能继续命中 WebView 缓存中的旧版本。自动预览轮询回归的等待上限必须严格大于生产 `1000ms` 轮询间隔，不得使用同为 `1000ms` 的默认上限制造 CI 边界竞争。
 - 退出与 Runner：独立 game-chat release 正常退出 Tauri 事件循环时调用仅供该 flavor 使用的认证 `runner.shutdown_for_client_exit`。Runner 先进入 draining、拒绝新的 Runtime 写请求，再无条件请求结束本 boot；已有 durable task / handoff / retry / reconciliation 状态不得伪装为 completed 或被删除，下次启动按既有 reconciliation 合同恢复。Windows game-chat 客户端以 `CREATE_SUSPENDED` 创建 Runner，在其执行用户代码前立即加入由客户端持有的 `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` Job，严格复核唯一主线程后再恢复运行；分配或恢复失败必须 kill + wait 并令客户端启动失败。Runner 的 command、MCP、Git、PTY 及其它未 breakaway 后代随客户端异常退出或 Job handle 关闭一起终止；Runner 正常退出前仍先执行既有进程会话收束。普通 dev / release 与 CLI 继续使用 `runner.shutdown_if_idle`，不改变共享 Runner 的原生命周期。
 - Windows 后台进程可见性：所有不需要交互控制台的 `command.exec / project.verify`、STDIO MCP、Repository Context Git、`git.inspect / project.git_commit` 和清理用 `taskkill` 必须使用 `CREATE_NO_WINDOW`；需要独立终止边界的命令可同时使用 `CREATE_NEW_PROCESS_GROUP`，不得使用会增加孤儿风险的 `DETACHED_PROCESS`。game-chat release 禁止再打开 launcher、workspace 或其它平行 Tauri 页面。
 - 真实浏览器回归：显式运行 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml real_chrome_generic_playtest_ --features game-chat-release -- --ignored --nocapture --test-threads=1`，同时用真实 Chrome / Chromium / Edge 证明尚未接受真实 `primary-action` 就瞬时进入 `lost`、以及两次受控尝试都固定 `lost` 的页面必须判失败；首轮合法 `lost`、restart 恢复后第二轮进入 `playing | won` 的页面可以判通过。
@@ -777,6 +777,7 @@ game-project/
 - 验证：`npm run agc:test` 已通过确定性 loopback Provider、真实 Runtime、项目写入和浏览器链路验收：同一父 Run 下 16 个 manifest task 均只有一个 logical run、一次 start、一次 completed 和一次 manifest projection，且无 failed / cancelled；父 run 与全部子 run 完成，最终 revision 为 `11`，基础正式产物、静态 smoke、桌面 / 移动 `37/37` 试玩通过，pending、reconciliation、Provider 失败、重复和泄漏计数均为 `0`。该结果不替代独立外部 Provider 验收。
 - 2026-07-26 本轮已验证 `npm run agc:config` 的终端配置链路。向导与 GUI 使用同一 Tauri identifier 对应的系统 AppData 和同名 `game-creator.config.json` / 可选 local overlay；读取已有配置时只更新有效 LLM 层，保留 `agentLlm`、`editorApi`、`mcpServers` 等其它配置。API Key 只从隐藏输入读取，拒绝 `--api-key`、仓库内目录、Git 已跟踪配置、符号链接，以及不是以 `world.genarrative.ai-game-creator` 为独立叶目录的 `--config-dir`，防止把任意父目录整体改成私有权限。保存使用同目录 `0600` 临时文件原子替换，POSIX AppData 目录保持 `0700`，Windows 使用当前用户独占 DACL，写后复用真实 `--llm-status` 检查；隐藏输入收到 `SIGINT / SIGTERM / SIGHUP` 时先恢复 raw mode 和 pause 状态再重发原信号，向导启动的 Cargo / npm 使用独立进程组并在信号路径有界收束整棵子进程树。
 - 2026-07-27 Windows DACL 启动回归修正：`powershell.exe -Command` 后追加的位置参数会被 PowerShell 5.1 拼接进命令文本，不能用 `$args` 安全接收包含空格的 AppData / 临时目录。DACL 脚本改为从仅传给该子进程的环境变量读取目标绝对路径和目录标记；`npm run agc:typecheck` 必须在真实 Windows 上执行配置回归，保证 `npm run agc` 的 `beforeDevCommand` 不因路径解析失败退出。
+- 2026-07-31 macOS 临时路径回归修正：配置目的地安全检查返回解析过现存父目录的真实路径，回归 fixture 的期望值也必须先使用平台原生 `realpath` 规范化临时根目录。macOS 下 `/var/folders/...` 与 `/private/var/folders/...` 是同一目录身份，不得用未规范化字符串阻断 `agc:typecheck`。CI 还必须使用“真实目录 + 符号链接父目录 + 不存在叶目录”确定性复现该语义；Windows 使用 junction 覆盖驱动器号、大小写与链接路径差异。fixture 的规范化与断言必须位于同一 `try/finally` 清理边界内。
 - 2026-07-27 项目总控右栏空态与持久状态水合修正：项目尚未产生 Runtime 时仍显示“尚未开始”状态块和创作入口，不把消息列表的弹性剩余空间裸露为空白；若 active Session 索引缺失但项目内已有 `project-supervisor` Runtime，工作台必须从 `read_game_creator_agent_runtimes` 的权威项目列表恢复总控 Session 与状态。`needs-reconciliation` 统一显示为“失败 / 待核对”，不能因对话索引缺失隐藏已落盘的失败事实。
 - 2026-07-28 Windows `tool-plan` 成功响应交接修正：相对目录句柄下安装 handoff 账本改用 `NtSetInformationFile(FileRenameInformation)`；`SetFileInformationByHandle(FileRenameInfo)` 不接受当前实现所需的非空 `RootDirectory`，会稳定返回 `ERROR_INVALID_PARAMETER (87)` 并让总控首轮进入 `needs-reconciliation`。实现继续绑定已验证的父目录句柄和相对 hash 文件名，不退化为绝对路径 rename；“按句柄安装”归入 `tool-plan-storage`。总控对 reconciliation 提供“已核对，结束旧任务”，取消后有 pending task 时只等待 Runner 续跑，队列为空时才允许显式 retry；自主构建 Supervisor 的 retry source 从原 Run Profile 绑定恢复并重新验证为可信 GUI / CLI 根入口，不降级成普通后台任务来源。
 - 2026-07-28 `tool-plan` 格式修复协议与 steer 审计修正：OpenAI Responses 请求按角色映射内容块，system / user 文本为 `input_text`，assistant 计划预览为 `output_text`，assistant `input_image` 在本地校验阶段拒绝，避免 repair 请求因非法 `input_text` 被上游以 HTTP 400 拒绝。tool-plan protocol / repair 审计增加 `appliedSteerCursor`，幂等键也纳入该 cursor；等待 Provider retry 期间 steer 后，同一 run / loop 可在新 cursor 下合法重用 `repair-0` 逻辑槽。旧记录缺少 cursor 时仅视为 `0`，保持升级后 replay 幂等。回归必须覆盖 Responses 多角色序列化、user 多模态，以及“无效计划 → repair retry 等待 → steer → 新 cursor repair”链路。