diff --git a/apps/ai-game-creator-shell/src/services/appUpdate.ts b/apps/ai-game-creator-shell/src/services/appUpdate.ts
index 97af09a26..678b74e04 100644
--- a/apps/ai-game-creator-shell/src/services/appUpdate.ts
+++ b/apps/ai-game-creator-shell/src/services/appUpdate.ts
@@ -6,7 +6,7 @@ import {
 
 import { appUpdateCheckEnabled } from '../app/featureFlags';
 import { resolveTauriInvoke } from '../app/tauri';
-import { visibleClientErrorMessage } from './errorReporting';
+import { appendWebviewLog, visibleClientErrorMessage } from './errorReporting';
 
 /** 更新提示所需的元数据；清单请求、版本比较、下载、校验与安装都由官方更新插件在原生侧完成。 */
 export type AppUpdateInfo = {
@@ -130,7 +130,12 @@ function restartAppAfterUpdate() {
   const invoke = resolveTauriInvoke();
   if (!invoke) return;
   // Windows 的 install 已在启动安装程序后退出进程，这里只覆盖 macOS / Linux 的重启收敛。
-  void invoke('restart_agc_app').catch(() => undefined);
+  void invoke('restart_agc_app').catch((error) => {
+    appendWebviewLog('error', [
+      '[AGC] 更新安装后重启客户端失败',
+      visibleClientErrorMessage(error),
+    ]);
+  });
 }
 
 export function resetAppUpdateCheckForTests() {
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 6906d9b0a..09d829f3e 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -36,6 +36,8 @@ Direct 的 Tauri 进度、活动回合和 manifest 事件不能忽略 `app.emit`
 
 窗口标题栏的最大化状态读取、resize 订阅、最小化、最大化和关闭失败也要保留 WebView 诊断，不能用空 catch 让原生窗口 IPC 失败无迹可寻。
 
+更新安装完成后的 `restart_agc_app` 失败也必须写入诊断；安装已启动但重启 IPC 失败时，不能让用户只看到“下载完成”后客户端继续停留在旧进程。
+
 `WindowChrome.test.tsx` 当前没有在用例间清理挂载的 `WindowChrome`，多用例运行会出现重复标题和重复窗口按钮；这属于测试隔离问题，不能把它误判成窗口 IPC 行为回归。
 
 ## 2026-10-03 AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过