dsh-retrace 0.4.28 → 0.4.29

package/README.md

@@ -360,7 +360,7 @@ Read it before filing an issue.
 ### Upgrading
 
 ```bash
-dsh plugin --profile desktop add dsh-retrace@0.4.28
+dsh plugin --profile desktop add dsh-retrace@0.4.29
 # then restart DSH — plugins are not hot-reloaded
 ```
 
@@ -439,13 +439,19 @@ the **host surface**, not by semver alone.
 | 🛡️ | **Running-work detection** | every session is scanned for live work: agent running, queued inbox items, background jobs, unclosed turns |
 | 📋 | **Running banner** | sessions with live work show a persistent in-page banner (short session code + reasons), so you can see it before quitting |
 | ⚠️ | **Exit prompt** | on plugin dispose (app exit / reload) a Chinese notice lists each running session and why it is considered busy — it only warns, it never cancels your running agent |
-| 🔒 | **Page-close interception (Web)** | `beforeunload` interception: a strong confirm when work is running (details modal, `[仍关闭]` = confirm-and-go), a light confirm otherwise |
-| 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports |
-
-> Desktop note: the Electron shell destroys the window on quit, so the page-level
-> `beforeunload` hook cannot fire there and the host exposes no plugin quit-veto seam —
-> Desktop is covered by the running banner plus the dispose notice; Web gets the full
-> interception.
+| 🔒 | **Page-close interception (web browsers)** | `beforeunload` interception, armed only where the host reports a native confirm dialog: a strong confirm when work is running (details modal, `[仍关闭]` = confirm-and-go), a light confirm otherwise |
+| 🔎 | **Query surface** | `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP) — same shape on both transports; the all-sessions shape also carries the host-reported page surface (`surface` / `quitVeto`) |
+
+> Desktop note: quit entry points differ by version/platform, and the DSH Desktop Electron
+> shell we inspected has no `will-prevent-unload` handler (0 hits across the packaged 2.0.9
+> `app.asar`). Where the entry does reach the page — the external report's DSH Desktop 0.9.0 /
+> Windows — the page `beforeunload` veto is **swallowed silently**: no dialog, no feedback, and
+> the exit looks stuck (only a force-quit works). Where it does not — the 2.0.9 shell we
+> inspected routes the tray item through `requestQuit(0) → window.destroy() → app.exit(0)` — the
+> quit is unaffected either way. The page cannot tell which case it is in, so desktop **never**
+> arms the native gate; it relies on the running banner plus the dispose notice. The gate is
+> armed only where the host reports that the page really surfaces a native dialog
+> (`quitVeto: true`, i.e. browser pages).
 
 > Command surface: `retrace.runningState` (host RPC) + `GET|POST /api/plugins/retrace/runningState` (HTTP).
 

package/README.zh.md

@@ -326,11 +326,16 @@ dsh plugin --profile desktop add dsh-retrace@0.4.26
 | 🛡️ | **运行中检测** | 逐会话扫描运行中工作：agent 正在跑 / inbox 排队 / 后台 jobs / 未闭合轮 |
 | 📋 | **运行中横幅** | 有运行中工作的会话显示页面常驻横幅（会话短码 + 原因），退出前可见 |
 | ⚠️ | **退出提示** | 插件 dispose（应用退出/重载）时中文提示列出每个运行中会话与原因——只提示，绝不代你取消 agent |
-| 🔒 | **页面关闭拦截（Web）** | `beforeunload` 拦截：有运行中任务强确认（明细模态，`[仍关闭]` 即确认离开），无任务轻确认 |
-| 🔎 | **查询面** | `retrace.runningState`（host RPC）+ `GET|POST /api/plugins/retrace/runningState`（HTTP），两入口同形状 |
-
-> 桌面说明：Electron 宿主退出时销毁窗口，页面 `beforeunload` 不会触发，宿主也未暴露
-> 插件可用的退出否决点——桌面侧由运行中横幅 + dispose 提示覆盖；Web 端拦截完整生效。
+| 🔒 | **页面关闭拦截（普通浏览器）** | `beforeunload` 拦截，只在宿主回报会弹原生确认框的页面上武装：有运行中任务强确认（明细模态，`[仍关闭]` 即确认离开），无任务轻确认 |
+| 🔎 | **查询面** | `retrace.runningState`（host RPC）+ `GET|POST /api/plugins/retrace/runningState`（HTTP），两入口同形状；全会话形状另带宿主判定的承载面（`surface` / `quitVeto`） |
+
+> 桌面说明：**退出入口随版本/平台而变**，而我们检查的 Electron 壳没有处理 `will-prevent-unload`
+> （装好的 2.0.9 `app.asar` 全文检索 0 命中）。**会走到该入口的那类版本**（外部报告所在的
+> DSH Desktop 0.9.0 / Windows）上，页面 `beforeunload` 否决被**静默吞掉**：不弹界面、不给
+> 反馈，表现为退出卡住（只能强退）；**不走该入口的版本**（我们检查的 2.0.9：托盘项走
+> `requestQuit(0) → window.destroy() → app.exit(0)`）上，退出本来就不受影响。页面里分不出
+> 自己属于哪一类，因此**桌面端一律不武装**原生门，保护由运行中横幅 + dispose 提示承担；
+> 只有宿主回报"这个页面会弹原生确认框"（`quitVeto: true`，即普通浏览器页）时才武装。
 
 **未来计划**——agent 业务层规划（运行时守护、中断治理、生态开放接口）**尚未发布**，此节是**计划**而非已上线能力。本 README 描述的是**开发线（main）**，可能领先于 npm 上最新发布版。
 

package/lib/boot-pin.js

@@ -0,0 +1,94 @@
+/**
+ * dsh-retrace — lib/boot-pin.js
+ *
+ * 启动批量 pin 的**重试调度**（唯一职责:什么时候再跑一次)。
+ *
+ * 从 lib/index.js 迁出的理由(2026-09-18 外部 issue #1:桌面端托盘退出死锁):
+ * 原实现是内联的递归 `setTimeout`,句柄被丢弃、既不 `unref` 也不在 dispose 里清。
+ * 宿主是 Node 侧 —— 一条 30s 递归(最多 20 次 ≈ 启动后 10 分钟)会把宿主事件循环
+ * 钉住,退出/关机流程得等它跑完(桌面端退不掉的两个拖累之一,另一个见
+ * lib/watchdog.js)。
+ *
+ * 与 lib/watchdog.js 同款:定时器创建/销毁可注入(`schedule` / `unschedule`),
+ * 于是"句柄有没有 unref""dispose 有没有撤销"能被用例直接捕获,不靠 review。
+ * 职责边界:本模块只决定"何时重试";"重试做什么"由 `run()` 注入(装配点传
+ * pinAllResident),"现在有没有可处理的会话"由 `hasResidentSessions()` 注入。
+ * 本模块零 import、零宿主服务引用(可单测,也进得了动态件 realm)。
+ */
+
+/** 默认重试上限(对齐 0.4.19 的启动窗口:20 × 30s ≈ 启动后 10 分钟)。 */
+export const BOOT_PIN_MAX_ATTEMPTS = 20
+/** 默认重试间隔。 */
+export const BOOT_PIN_DELAY_MS = 30_000
+
+/**
+ * 建启动重试链。
+ * @param {object} options
+ * @param {() => Promise<any>} options.run 实际执行体(返回值里的 `value.total` 用于日志)。
+ * @param {() => boolean} options.hasResidentSessions 现在有没有可处理的会话。
+ * @param {(line: string) => void} [options.log] 诊断日志。
+ * @param {number} [options.maxAttempts] 重试上限(含首跑)。
+ * @param {number} [options.delayMs] 重试间隔。
+ * @param {(cb: () => void, ms: number) => unknown} [options.schedule] 定时器创建
+ *   (默认全局 setTimeout;返回的句柄上若有 `unref` 会被调用)。
+ * @param {(handle: unknown) => void} [options.unschedule] 定时器销毁(默认全局 clearTimeout)。
+ * @returns {{ dispose(): void }} dispose = 停止重试链 + 撤掉挂着的定时器(幂等)。
+ */
+export function createBootPinRetry({
+  run,
+  hasResidentSessions,
+  log = () => {},
+  maxAttempts = BOOT_PIN_MAX_ATTEMPTS,
+  delayMs = BOOT_PIN_DELAY_MS,
+  schedule = (cb, ms) => setTimeout(cb, ms),
+  unschedule = (handle) => clearTimeout(handle),
+} = {}) {
+  if (typeof run !== 'function') throw new TypeError('createBootPinRetry: run must be a function')
+  if (typeof hasResidentSessions !== 'function') throw new TypeError('createBootPinRetry: hasResidentSessions must be a function')
+
+  let timer = null
+  let disposed = false
+
+  /** 挂下一次(序号 = next)。序号到顶就不挂,链自然收尾。 */
+  function arm(next) {
+    if (disposed || next >= maxAttempts) return
+    timer = schedule(() => {
+      timer = null
+      step(next + 1)
+    }, delayMs)
+    // 宿主是 Node 侧:不 unref ⇒ 这条 30s 递归把事件循环钉到启动后 10 分钟,
+    // 退出/关机被它拖住。unref 后宿主该退就退(会话仍在时事件循环自有别的句柄撑着)。
+    if (timer && typeof timer.unref === 'function') timer.unref()
+  }
+
+  function step(current) {
+    if (disposed) return
+    const finish = () => arm(current)
+    if (!hasResidentSessions()) {
+      finish()
+      return
+    }
+    Promise.resolve()
+      .then(() => run())
+      .then((result) => {
+        log(`retrace: bootPin(${current}) → ${result?.value?.total ?? 0} 个驻留会话标题已处理`)
+      })
+      .catch((error) => {
+        log(`retrace: bootPin error: ${String(error).slice(0, 160)}`)
+      })
+      .then(finish)
+  }
+
+  step(0)
+
+  return {
+    /** 停止重试链并撤掉挂着的定时器(重复调用安全)。 */
+    dispose() {
+      disposed = true
+      if (timer !== null) {
+        unschedule(timer)
+        timer = null
+      }
+    },
+  }
+}

package/lib/client.bundle.js

@@ -258,6 +258,9 @@ function buildRunningCopy(snapshot, { locale = "zh", labelOf, now = Date.now(),
   const hint = stale ? lang === "zh" ? "(\u72B6\u6001\u540C\u6B65\u4E8E\u8F83\u65E9\u65F6\u523B,\u53EF\u80FD\u5DF2\u53D8\u5316)" : "(state may be stale)" : void 0;
   return { head, lines, hint, stale };
 }
+function quitVetoOf(snapshot) {
+  return snapshot?.quitVeto === true;
+}
 function createGuardStore({ now = Date.now, armTtlMs = GUARD_ARM_TTL_MS } = {}) {
   let snapshot = null;
   let armedAt = 0;
@@ -469,7 +472,7 @@ var zh = {
   "path.round": "\u7B2C {n} \u8F6E",
   "path.empty": "\uFF08\u5F53\u524D\u6CA1\u6709\u5BF9\u8BDD\u8F6E\u6B21\uFF09",
   "options.closeGuard": "\u9000\u51FA\u786E\u8BA4\uFF08\u5173\u95ED\u5B88\u536B\uFF09",
-  "options.closeGuardDesc": "\u5F00\uFF08\u9ED8\u8BA4\uFF09\uFF1A\u9875\u9762/\u7A97\u53E3\u5173\u95ED\u524D\u786E\u8BA4\u9000\u51FA\u2014\u2014\u6709\u8FD0\u884C\u4E2D\u4EFB\u52A1\u6216\u672A\u5B8C\u6210\u5BF9\u8BDD\u65F6\u5F3A\u62E6\u5E76\u5217\u51FA\u660E\u7EC6\uFF08\u9632\u8BEF\u5173\u4E22\u8FDB\u5EA6\uFF09\uFF0C\u65E0\u4EFB\u52A1\u65F6\u8F7B\u786E\u8BA4\u4E00\u6B21\u3002\u6B64\u62E6\u622A\u4F5C\u7528\u4E8E\u6D4F\u89C8\u5668/\u9875\u9762\u5173\u95ED\u8DEF\u5F84\uFF08\u7F51\u9875\u7248\u6807\u7B7E\u9875\uFF1B\u684C\u9762\u7248\u5E94\u7528\u9000\u51FA\u4E3A\u5BBF\u4E3B\u539F\u751F\u8DEF\u5F84\uFF0C\u89C1\u8FD0\u884C\u4E2D\u6A2A\u5E45\u63D0\u793A\uFF09\u3002"
+  "options.closeGuardDesc": "\u5F00\uFF08\u9ED8\u8BA4\uFF09\uFF1A\u9875\u9762\u5173\u95ED\u524D\u786E\u8BA4\u9000\u51FA\u2014\u2014\u6709\u8FD0\u884C\u4E2D\u4EFB\u52A1\u6216\u672A\u5B8C\u6210\u5BF9\u8BDD\u65F6\u5F3A\u62E6\u5E76\u5217\u51FA\u660E\u7EC6\uFF08\u9632\u8BEF\u5173\u4E22\u8FDB\u5EA6\uFF09\uFF0C\u65E0\u4EFB\u52A1\u65F6\u8F7B\u786E\u8BA4\u4E00\u6B21\u3002\u53EA\u5728\u5BBF\u4E3B\u786E\u8BA4\u4F1A\u663E\u793A\u539F\u751F\u786E\u8BA4\u6846\u7684\u9875\u9762\u4E0A\u6B66\u88C5\uFF08\u666E\u901A\u6D4F\u89C8\u5668\u6807\u7B7E\u9875\uFF1B\u5173\u6389\u672C\u9879\u540C\u65F6\u505C\u7528\u8FD0\u884C\u4E2D\u6A2A\u5E45\uFF09\u3002\u684C\u9762\u7AEF\uFF08DSH Desktop\uFF09\u4E00\u5F8B\u4E0D\u6B66\u88C5\uFF1A\u9000\u51FA\u5165\u53E3\u968F\u7248\u672C/\u5E73\u53F0\u800C\u53D8\u2014\u2014\u5916\u90E8\u62A5\u544A\u7684 0.9.0 \u4E00\u7C7B\u5165\u53E3\u4F1A\u89E6\u53D1\u9875\u9762 beforeunload\uFF0C\u800C\u684C\u9762\u58F3\u672A\u5904\u7406 will-prevent-unload \u21D2 \u5426\u51B3\u88AB\u9759\u9ED8\u541E\u6389\u3001\u9000\u51FA\u5361\u4F4F\uFF1B2.0.9 \u7684\u6258\u76D8\u9879\u8D70 requestQuit\u2192window.destroy\u2192app.exit\uFF0C\u6839\u672C\u4E0D\u7ECF\u8FC7\u5B83\u3002\u9875\u9762\u91CC\u5206\u4E0D\u51FA\u662F\u54EA\u4E00\u7C7B\uFF0C\u6545\u684C\u9762\u4FDD\u62A4\u7531\u8FD0\u884C\u4E2D\u6A2A\u5E45\u627F\u62C5\u3002"
 };
 var en = {
   "action.edit": "Edit",
@@ -616,7 +619,7 @@ var en = {
   "path.round": "Round {n}",
   "path.empty": "(no conversation rounds yet)",
   "options.closeGuard": "Exit confirmation (close guard)",
-  "options.closeGuardDesc": "On (default): confirm before the page/window closes \u2014 when sessions have running or unfinished work a strong guard lists them (prevents accidental progress loss); otherwise a light one-time confirm. Applies to browser/page close paths (web tabs; Desktop app exit is a host-native path \u2014 see the running banner)."
+  "options.closeGuardDesc": "On (default): confirm before the page closes \u2014 when sessions have running or unfinished work a strong guard lists them (prevents accidental progress loss); otherwise a light one-time confirm. Armed only where the host reports a native confirm dialog (ordinary browser tabs; turning this off also disables the running banner). Desktop (DSH Desktop) never arms it: quit entries differ by version/platform \u2014 the 0.9.0-class entry in the external report does reach page beforeunload, and the shell has no will-prevent-unload handler, so the veto is swallowed silently and the exit hangs; the 2.0.9 tray item goes requestQuit\u2192window.destroy\u2192app.exit and never reaches it. The page cannot tell which one it is, so the running banner carries that protection instead."
 };
 function opFailureText(code, message, t) {
   if (code === "agent-busy") return t("error.busy");
@@ -2726,7 +2729,7 @@ function installCloseGuard(t) {
       const value = payload && payload.ok ? payload.value : null;
       if (!value || !Array.isArray(value.running)) return;
       const prev = store.get();
-      store.set({ running: value.running });
+      store.set({ running: value.running, quitVeto: value.quitVeto, surface: value.surface });
       if (runningSig(store.get()) !== runningSig(prev)) ui.dismissed = null;
       renderBanner();
     }).catch(() => {
@@ -2745,7 +2748,7 @@ function installCloseGuard(t) {
     }
   }
   function bannerNote(lang) {
-    return lang === "zh" ? "\u5173\u95ED\u9875\u9762/\u9000\u51FA\u524D\u8BF7\u5148\u786E\u8BA4\u2014\u2014\u4EFB\u52A1\u4E2D\u65AD\u53EF\u80FD\u4E22\u5931\u8FDB\u5EA6(\u684C\u9762\u7AEF\u5E94\u7528\u9000\u51FA\u5728\u5BBF\u4E3B\u4FA7,\u8BF7\u4EE5\u6B64\u6A2A\u5E45\u4E3A\u51C6)" : "Confirm before closing/exiting \u2014 interrupting work may lose progress (Desktop app exit is host-side; rely on this banner)";
+    return lang === "zh" ? "\u5173\u95ED\u9875\u9762/\u9000\u51FA\u524D\u8BF7\u5148\u786E\u8BA4\u2014\u2014\u4EFB\u52A1\u4E2D\u65AD\u53EF\u80FD\u4E22\u5931\u8FDB\u5EA6(\u684C\u9762\u7AEF\u4E0D\u6B66\u88C5\u539F\u751F\u9000\u51FA\u786E\u8BA4,\u8BF7\u4EE5\u6B64\u6A2A\u5E45\u4E3A\u51C6)" : "Confirm before closing/exiting \u2014 interrupting work may lose progress (no native exit prompt on Desktop; rely on this banner)";
   }
   function renderBanner() {
     const cfg = getConfig();
@@ -2887,6 +2890,7 @@ function installCloseGuard(t) {
     if (store.isArmed()) return;
     const kind = classifySnapshot(store.get());
     if (kind === "unknown") return;
+    if (!quitVetoOf(store.get())) return;
     try {
       event.preventDefault?.();
     } catch {

package/lib/client.js

@@ -24,6 +24,7 @@ import {
   buildRunningCopy,
   runningLines,
   createGuardStore,
+  quitVetoOf,
 } from './close-guard-client.js'
 
 export const name = 'dsh-retrace'
@@ -238,7 +239,7 @@ export const zh = {
   'path.round': '第 {n} 轮',
   'path.empty': '（当前没有对话轮次）',
   'options.closeGuard': '退出确认（关闭守卫）',
-  'options.closeGuardDesc': '开（默认）：页面/窗口关闭前确认退出——有运行中任务或未完成对话时强拦并列出明细（防误关丢进度），无任务时轻确认一次。此拦截作用于浏览器/页面关闭路径（网页版标签页；桌面版应用退出为宿主原生路径，见运行中横幅提示）。',
+  'options.closeGuardDesc': '开（默认）：页面关闭前确认退出——有运行中任务或未完成对话时强拦并列出明细（防误关丢进度），无任务时轻确认一次。只在宿主确认会显示原生确认框的页面上武装（普通浏览器标签页；关掉本项同时停用运行中横幅）。桌面端（DSH Desktop）一律不武装：退出入口随版本/平台而变——外部报告的 0.9.0 一类入口会触发页面 beforeunload，而桌面壳未处理 will-prevent-unload ⇒ 否决被静默吞掉、退出卡住；2.0.9 的托盘项走 requestQuit→window.destroy→app.exit，根本不经过它。页面里分不出是哪一类，故桌面保护由运行中横幅承担。',
 }
 /** English dictionary, checked complete against the zh key set. */
 export const en = {
@@ -386,7 +387,7 @@ export const en = {
   'path.round': 'Round {n}',
   'path.empty': '(no conversation rounds yet)',
   'options.closeGuard': 'Exit confirmation (close guard)',
-  'options.closeGuardDesc': 'On (default): confirm before the page/window closes — when sessions have running or unfinished work a strong guard lists them (prevents accidental progress loss); otherwise a light one-time confirm. Applies to browser/page close paths (web tabs; Desktop app exit is a host-native path — see the running banner).',
+  'options.closeGuardDesc': 'On (default): confirm before the page closes — when sessions have running or unfinished work a strong guard lists them (prevents accidental progress loss); otherwise a light one-time confirm. Armed only where the host reports a native confirm dialog (ordinary browser tabs; turning this off also disables the running banner). Desktop (DSH Desktop) never arms it: quit entries differ by version/platform — the 0.9.0-class entry in the external report does reach page beforeunload, and the shell has no will-prevent-unload handler, so the veto is swallowed silently and the exit hangs; the 2.0.9 tray item goes requestQuit→window.destroy→app.exit and never reaches it. The page cannot tell which one it is, so the running banner carries that protection instead.',
 }
 
 // ---------------------------------------------------------------------------
@@ -3412,15 +3413,20 @@ function whatBody(what, summaryText, t, { suppressContinue = false, maxLines = n
 // 关闭守卫 V2 — 装配层(纯逻辑/文案在
 // lib/close-guard-client.js,可单测;这里只做 DOM 与事件接线)
 //
-// 验证结论(实证详见提交报告 + close-guard-client.js 头注释):
-//  - Desktop 应用退出 = 宿主 window.destroy()(electron-runtime release 内)
-//    + app.exit()——Electron 语义下 beforeunload 不触发 → 本拦截只覆盖
-//    **web 浏览器 tab/窗口关闭与页面重载路径**;
+// 事实与选型(2026-09-18 外部 issue #1 复核后重写;详见 lib/close-guard-client.js
+// 头注释与 lib/close-guard.js 头注释):
+//  - 退出入口随 Desktop 版本/平台而变:外部报告的 0.9.0 / Windows 那一类入口会触发页面
+//    beforeunload,而 DSH Desktop 的 Electron 壳没有处理 will-prevent-unload
+//    (装好的 2.0.9 app.asar 全文 0 命中)⇒ 否决被静默吞掉,那里表现为"退出卡住、
+//    只能强退";2.0.9 的托盘项走 requestQuit(0) → window.destroy() → app.exit(code),
+//    不经过 beforeunload,那类版本上退出本来就正常;
+//  - ⇒ 原生门的武装条件 = **宿主明确回报本页承载 quit-veto**(普通浏览器页面)。
+//    页面里分不出宿主属于哪一类,而第一类上否决是静默的(会卡住退出),所以桌面端
+//    一律不武装。承载面由宿主随 runningState 载荷下发(quitVeto === true 才武装;
+//    false/未知都不武装,未知取安全侧)。客户端不再自己猜宿主;
+//  - 桌面端的保护 = 运行中横幅(有任务即常驻)+ dispose 提示,两者都与退出路径无关;
 //  - 浏览器 beforeunload 确认框文案/按钮不可自定义(Chromium 统一原生框),
-//    故 A 强拦 = 原生门 + 「取消后」的中文明细模态;B 轻确认 = 原生一次确认;
-//  - Desktop 退出时用户能看到的 client 侧提示 = 运行中横幅(有任务即常驻,
-//    不依赖退出路径)——桌面替代 seam(宿主原生 quit-veto)需官方 shell 支持,
-//    已在报告中向宿主提议(main.js requestQuit / electron-runtime release)。
+//    故 A 强拦 = 原生门 + 「取消后」的中文明细模态;B 轻确认 = 原生一次确认。
 // ---------------------------------------------------------------------------
 const GUARD_MODAL_ID = 'dsh-rt-guard-modal'
 const GUARD_BANNER_ID = 'dsh-rt-guard-banner'
@@ -3468,7 +3474,9 @@ function installCloseGuard(t) {
       const value = payload && payload.ok ? payload.value : null
       if (!value || !Array.isArray(value.running)) return
       const prev = store.get()
-      store.set({ running: value.running })
+      // quitVeto = 宿主回报的"本页是否承载 quit-veto"(见 close-guard-client.js
+      // quitVetoOf)。**原样缓存宿主的值**:缺字段 = 旧宿主 = 未知 ⇒ 不武装。
+      store.set({ running: value.running, quitVeto: value.quitVeto, surface: value.surface })
       if (runningSig(store.get()) !== runningSig(prev)) ui.dismissed = null
       renderBanner()
     }).catch(() => {
@@ -3488,8 +3496,8 @@ function installCloseGuard(t) {
   }
   function bannerNote(lang) {
     return lang === 'zh'
-      ? '关闭页面/退出前请先确认——任务中断可能丢失进度(桌面端应用退出在宿主侧,请以此横幅为准)'
-      : 'Confirm before closing/exiting — interrupting work may lose progress (Desktop app exit is host-side; rely on this banner)'
+      ? '关闭页面/退出前请先确认——任务中断可能丢失进度(桌面端不武装原生退出确认,请以此横幅为准)'
+      : 'Confirm before closing/exiting — interrupting work may lose progress (no native exit prompt on Desktop; rely on this banner)'
   }
   function renderBanner() {
     const cfg = getConfig()
@@ -3618,12 +3626,17 @@ function installCloseGuard(t) {
     ui.toastTimer = setTimeout(() => { if (ui.toast) { ui.toast.remove(); ui.toast = null } }, 8000)
   }
 
-  // -- 页面关闭拦截(beforeunload;仅浏览器/页面路径触发) -----------------------
+  // -- 页面关闭拦截(beforeunload;只在宿主确认承载 quit-veto 的页面上武装) ----
   function onBeforeUnload(event) {
     if (!getConfig().closeGuard || !supported) return
     if (store.isArmed()) return // 已放行(用户已选 [仍关闭])→ 二次触发直接过
     const kind = classifySnapshot(store.get())
     if (kind === 'unknown') return // 状态未同步(host 不可达/刚启动)→ 不打扰
+    // 宿主承载面闸门(2026-09-18 外部 issue #1):桌面 Electron 页面上原生
+    // beforeunload 门没有意义(2.0.9 那类入口不经过它;0.9.0 那类入口经过时否决被
+    // 壳静默吞掉、退出卡住)。仅当宿主明确回报 quitVeto === true(普通浏览器页面)
+    // 才武装;false 与未知一律不武装(未知取安全侧)。
+    if (!quitVetoOf(store.get())) return
     // A/B 共用浏览器原生门:returnValue 触发原生确认(Chromium 文案不可自定义,
     // 见 close-guard-client.js 头注释;用户控制可在设置关闭)。
     try { event.preventDefault?.() } catch { /* ignore */ }
@@ -3701,8 +3714,9 @@ export function apply(ctx) {
   const t = ctx.locale.bind(NS)
 
   // 关闭守卫 V2:页面关闭 beforeunload 拦截(A 强拦/B 轻
-  // 确认,运行中状态经 /runningState 轮询缓存)+ 运行中横幅(Desktop 退出走
-  // 宿主 destroy,横幅是退出前唯一可见的 client 侧提示——替代 seam 见报告)。
+  // 确认,运行中状态经 /runningState 轮询缓存)+ 运行中横幅。原生门只在宿主
+  // 回报本页承载 quit-veto 时武装(见 installCloseGuard 段头注释);桌面端的
+  // 可见提示 = 运行中横幅 + dispose 提示(与退出路径无关)。
   // The close guard is DOM-only (no React), so the panel error boundary does not
   // apply to it: fail CLOSED instead — the guard degrades to "not installed"
   // rather than breaking the plugin's activation (and with it the client half).

package/lib/close-guard-client.js

@@ -4,18 +4,33 @@
  * 关闭守卫 V2 · 客户端纯逻辑层——被 lib/client.js 装配,
  * 零 DOM/零 react 依赖(可单测;client.bundle.js/dynamic-client.js 由构建内联)。
  *
- * 验证结论摘要(2026-09-09,详见提交报告;本模块据此设计):
- *  - Desktop 退出路径 = 主进程 shutdown → generation.release() → 宿主窗口
- *    `window.destroy()`(宿主 electron-runtime release 内)+ 末尾 `app.exit()`:
- *    Electron 语义 destroy 不触发页面 beforeunload(app.exit 亦不)——页面
- *    beforeunload 拦截**不覆盖 Desktop 退出**;
- *  - 页面 beforeunload 只在「web 浏览器 tab/窗口关闭 / 页面重载」时触发 →
- *    本守卫 = **web profile 路径**;Desktop 的可见替代 = 同源 runningState
- *    轮询 + 页内运行中横幅(用户退出前始终可见)+ dispose 日志(V1 保留)+
- *    向官方 shell 提议 quit-veto seam(报告);
- *  - 浏览器 beforeunload 确认框文案/按钮**不可自定义**(Chromium 一律通用
- *    原生框)→ 本模块只产出语义/文案数据,选型由 client.js 装配层决定
- *    (A 强拦 = 原生门 + 取消后中文明细模态;B 轻确认 = 原生一次确认)。
+ * ── 桌面端为什么不武装原生门(2026-09-18 外部 issue #1 复核后重写)────────────
+ * 本文件此前把守卫的前提写成了"桌面端退出不经过页面关闭流程",并据此把守卫当纯
+ * web 能力 —— **那是把没覆盖到的路径当成了结论**(本 issue 的两条根因之一;该前提
+ * 只对**重启**路径 `app.relaunch(); app.exit(0)` 成立)。复核到的事实:
+ *  - **退出入口随版本/平台而变**:外部报告的 DSH Desktop 0.9.0/Windows 上,托盘「退出」
+ *    走的是**会**触发页面 `beforeunload` 的入口;而我们检查的 2.0.9 壳上,托盘项走
+ *    `requestQuit(0)` → `generation.release()` → `window.destroy()` → `app.exit(code)`
+ *    (**不**经过 `beforeunload`)。⇒ 我们**无法保证覆盖所有入口**,
+ *    这正是"桌面端一律不武装"的理由(而不是"桌面端都不会触发");
+ *  - DSH Desktop 的 Electron 壳没有处理 `will-prevent-unload`(装好的 2.0.9
+ *    `app.asar` 全文检索 0 命中;`beforeunload` 三处命中全在第三方库)⇒ Electron
+ *    的默认语义 = 尊重页面否决,且不弹任何界面。于是**在会走到 beforeunload 的那类
+ *    版本上**页面里的 `preventDefault()` 是静默的:否决被吞掉、界面什么都没有,用户
+ *    看到的就是"退出卡住、只能强退"(现场:关掉本插件的「退出确认」即恢复正常);
+ *    在 2.0.9 那类不经过它的版本上,退出本来就正常 —— 两种情况都指向同一个结论。
+ * 结论(与事实一致):桌面端**不武装**原生 `beforeunload` 门;桌面端的保护由
+ * **运行中横幅** + dispose 提示承担(两者都与退出路径无关)。网页端照常武装:
+ * Chromium 会弹原生确认框,页面否决在那里对用户是可见的。
+ *
+ * 承载面由**宿主**判定、随既有 runningState 载荷下发(见 lib/close-guard.js 头注释
+ * 与 `pageSurfaceOf` / `quitVetoFor`),客户端只在 `quitVeto === true` 时武装。
+ * `false`(桌面 Electron 页面)与 `null`/`undefined`(中性态:wire 通道拿不到请求
+ * 证据 / 旧版桌面壳)一律不武装 —— 未知取安全侧,避免再次死锁。
+ *
+ * 浏览器 beforeunload 确认框文案/按钮不可自定义(Chromium 一律通用原生框)
+ * ⇒ 本模块只产出语义/文案数据,选型由 client.js 装配层决定
+ * (A 强拦 = 原生门 + 取消后中文明细模态;B 轻确认 = 原生一次确认)。
  *
  * 检测数据源 = host 侧 runningSessions(ctx)(lib/close-guard.js 复用):
  *   会话有 agent status=running / inbox 排队 / jobs 后台任务 / 未闭合轮 →
@@ -131,6 +146,18 @@ export function buildRunningCopy(snapshot, { locale = 'zh', labelOf, now = Date.
   return { head, lines, hint, stale }
 }
 
+/**
+ * 本页宿主是否承载 quit-veto(页面否决对用户可见):
+ * 宿主在 runningState 载荷里明确回 `quitVeto === true` 才算。
+ * `false`(桌面 Electron 页面:壳不处理 will-prevent-unload,否决静默)与
+ * `null`/`undefined`(中性态)都返回 false —— 未知一律取**不武装**的安全侧。
+ * @param {{quitVeto?:boolean|null}} [snapshot] 宿主快照。
+ * @returns {boolean} 是否可以在本页武装原生 `beforeunload` 门。
+ */
+export function quitVetoOf(snapshot) {
+  return snapshot?.quitVeto === true
+}
+
 /**
  * 关闭守卫客户端状态(纯,可单测):快照缓存 + 已放行标记。
  * 「放行」= 用户在一轮关闭手势中已选 [仍关闭];二次触发 beforeunload 时放行,

package/lib/close-guard.js

@@ -18,6 +18,46 @@
  *
  * 铁律:只检测+提示,绝不中断/取消 agent、绝不写事件(中断属用户显式动作,
  * 守卫只在用户"关闭"动作时确认——本插件无该 seam 时只提示,不代执行)。
+ *
+ * ── 宿主承载面判定(2026-09-18,外部 issue #1:桌面端托盘退出死锁)─────────────
+ *
+ * 现场:DSH Desktop 上托盘「退出」点了没反应,App 退不掉(只能强退);关掉本插件
+ * 的「退出确认」立刻正常;网页端一直正常。逐条核实到的事实:
+ *  ① 客户端 `onBeforeUnload` 对 `kind !== 'unknown'` 一律 `preventDefault()`
+ *     ——空会话也拦;
+ *  ② DSH Desktop 的 Electron 壳**没有**处理 `will-prevent-unload`
+ *     (装好的 2.0.9 `app.asar` 全文检索 0 命中)。Electron 的默认语义 = 尊重页面
+ *     否决,且不弹任何界面 ⇒ **一旦页面否决被抬起来**,它就是静默的:不弹框、
+ *     不给用户任何可见反馈;
+ *  ③ 退出入口**随 Desktop 版本/平台而变**(这是本 issue 的病因:别把某一条入口
+ *     当成全部事实):
+ *     · 外部报告(DSH Desktop 0.9.0 / Windows)那一类入口**会**触发页面
+ *       `beforeunload` ⇒ ② 生效:否决被静默吞掉,用户看到"点了退出没反应、
+ *       只能强退";
+ *     · 本机核对的 2.0.9 壳上,托盘项走 `requestQuit(0)` → `createDesktopShutdown`
+ *       → `generation.release()` → `window.destroy()` → `app.exit(code)`
+ *       (且 `before-quit` 也被 `preventDefault() + requestQuit(0)` 收进同一路径)
+ *       ⇒ `destroy()` / `app.exit()` 都**不**经过页面 `beforeunload`,那类版本上
+ *       退出本来就正常(与本插件无关);
+ *  ④ 反之,普通浏览器(网页版)会为 `beforeunload` 弹原生确认框,页面否决对用户
+ *     是**可见**的 ⇒ 只有这条路径上"武装原生门"才是有效动作。
+ *
+ * ⇒ 页面里分不出宿主属于哪一类,而③第一类上否决是静默的(会卡住退出且毫无反馈)
+ * —— 所以**桌面端一律不武装**原生门(与版本无关):2.0.9 那类版本上它本来是空转,
+ * 0.9.0 那类版本上它能卡死退出。「本页宿主是否承载 quit-veto(否决对用户可见)」
+ * 是**宿主侧**才知道的属性,由宿主判定、随既有的 runningState 载荷下发(复用既有
+ * 通道,不新造)。客户端只在宿主明确回 true 时武装原生门(见
+ * lib/close-guard-client.js quitVetoOf)。
+ *
+ * 判据取**请求级证据**:DSH Desktop 主进程给 renderer 的**每一个** HTTP/WS 请求
+ * 挂一个代际能力头(`electron-runtime` 的 installRendererAccessHeader;
+ * `webRequest.onBeforeSendHeaders({urls:['<all_urls>']})`,且挂之前先剥掉请求里
+ * 同名头 ⇒ 页面 JS 伪造不了)。头在 ⇒ 本请求来自 Desktop 的 Electron 页面;
+ * 头不在且宿主看不出 Electron 痕迹 ⇒ 普通浏览器页面。
+ *
+ * 已知中性态(默认取**不武装**这一侧):动态桥 wire 通道拿不到请求对象;宿主能看出
+ * 自己是 Electron 但请求没带该头(旧版桌面壳/桌面版兼容模式的普通浏览器页)。
+ * 两种都判 unknown ⇒ 客户端不武装原生门,退化为"仅运行中横幅"。
  */
 // unclosedTurns 直接复用 interrupt-guard(该文件零 import,无环),
 // 不再内联复制一份——后续 interrupt-guard 演进(如 reason 感知)自动同步。
@@ -126,6 +166,96 @@ export function sessionRunningState(ctx, sessionId) {
   return runningState(String(sessionId), { agent, session, jobs })
 }
 
+// ── 宿主承载面:判定"本页宿主是否承载 quit-veto" ─────────────────────────────
+/** DSH Desktop 主进程给 renderer 每个请求挂的代际能力头(页面 JS 伪造不了)。 */
+export const DESKTOP_RENDERER_HEADER = 'x-dsh-desktop-renderer'
+
+/** 承载面取值。语义见文件头注释。 */
+export const PAGE_SURFACE = Object.freeze({
+  /** DSH Desktop 的 Electron 页面:原生 `beforeunload` 门在此静默。 */
+  DESKTOP_RENDERER: 'desktop-renderer',
+  /** 普通浏览器页面:原生 `beforeunload` 确认框在此出现。 */
+  BROWSER: 'browser',
+  /** 中性态:拿不到请求证据 / 能看出 Electron 但请求没带能力头。 */
+  UNKNOWN: 'unknown',
+})
+
+/**
+ * DSH Desktop 宿主侧注入的服务名(桌面专属)。任一在场 ⇒ 本宿主是桌面壳。
+ * 只用于"要不要退回中性态"的判断,不参与"是不是 Electron 页面"的判断。
+ */
+const DESKTOP_HOST_SERVICES = ['desktopBrowserAccess', 'desktopRuntime', 'desktopPnpmBootstrap']
+
+/** 安全取一个可选服务(未注册/取值抛错一律当"没有")。 */
+function serviceOf(ctx, name) {
+  try {
+    return typeof ctx?.get === 'function' ? ctx.get(name) : undefined
+  } catch { return undefined }
+}
+
+/** 本宿主是否带 Electron/桌面壳痕迹(多项独立判据,任一命中即为真)。 */
+export function desktopHostEvidence(ctx) {
+  try {
+    if (typeof process !== 'undefined' && process?.versions?.electron) return true
+  } catch { /* 浏览器侧无 process */ }
+  for (const name of DESKTOP_HOST_SERVICES) {
+    if (serviceOf(ctx, name)) return true
+  }
+  return false
+}
+
+/** 请求头里是否带 Desktop renderer 能力头(值不看内容:非空即证据)。 */
+function hasDesktopRendererHeader(headers) {
+  if (!headers || typeof headers !== 'object') return false
+  const present = (value) => {
+    if (typeof value === 'string') return value.length > 0
+    if (Array.isArray(value)) return value.length > 0
+    return Boolean(value)
+  }
+  try {
+    // Node 的 req.headers 名字已小写;非 Node 形状(经序列化/代理)按大小写不敏感兜底。
+    for (const [name, value] of Object.entries(headers)) {
+      if (name.toLowerCase() === DESKTOP_RENDERER_HEADER && present(value)) return true
+    }
+  } catch { return false }
+  return false
+}
+
+/**
+ * 从**请求头 + 宿主痕迹**判定承载面(纯函数,可单测)。
+ * @param {object} [headers] Node `req.headers` 形状;拿不到请求对象时为 undefined。
+ * @param {object} [opts] `{ desktopHost }` = desktopHostEvidence(ctx) 的结果。
+ * @returns {'desktop-renderer'|'browser'|'unknown'}
+ */
+export function pageSurfaceOf(headers, { desktopHost = false } = {}) {
+  if (hasDesktopRendererHeader(headers)) return PAGE_SURFACE.DESKTOP_RENDERER
+  // 无能力头。能看出宿主是 Electron ⇒ 中性态(可能是旧版桌面壳没挂头,也可能是
+  // 桌面版兼容模式下的普通浏览器页;两者分不开)⇒ 交给调用方按安全侧处理。
+  if (desktopHost) return PAGE_SURFACE.UNKNOWN
+  return PAGE_SURFACE.BROWSER
+}
+
+/**
+ * 该承载面能否承载 quit-veto(页面否决对用户可见)。
+ * browser → true;desktop-renderer → false;unknown → null(未知 ⇒ 客户端不武装)。
+ */
+export function quitVetoFor(surface) {
+  if (surface === PAGE_SURFACE.BROWSER) return true
+  if (surface === PAGE_SURFACE.DESKTOP_RENDERER) return false
+  return null
+}
+
+/**
+ * 给 runningState 载荷用的承载面描述。
+ * @param {object} ctx - cordis ctx(用于看宿主痕迹)。
+ * @param {object} [headers] - 发起该请求的 `req.headers`;wire/harness 通道传 undefined。
+ * @returns {{ surface:string, quitVeto:boolean|null }}
+ */
+export function guardSurfaceOf(ctx, headers) {
+  const surface = pageSurfaceOf(headers, { desktopHost: desktopHostEvidence(ctx) })
+  return { surface, quitVeto: quitVetoFor(surface) }
+}
+
 /**
  * 挂载"关闭前强提示":插件 dispose(应用退出/重载)时,若有运行中会话 → 中文提示
  * 列出每个会话与原因(agent-running/queued/jobs/unclosed-turn)。只提示不中断。

package/lib/dynamic-client.js

@@ -264,6 +264,9 @@ return {
         const hint = stale ? lang === "zh" ? "(\u72B6\u6001\u540C\u6B65\u4E8E\u8F83\u65E9\u65F6\u523B,\u53EF\u80FD\u5DF2\u53D8\u5316)" : "(state may be stale)" : void 0;
         return { head, lines, hint, stale };
       }
+      function quitVetoOf(snapshot) {
+        return snapshot?.quitVeto === true;
+      }
       function createGuardStore({ now = Date.now, armTtlMs = GUARD_ARM_TTL_MS } = {}) {
         let snapshot = null;
         let armedAt = 0;
@@ -475,7 +478,7 @@ return {
         "path.round": "\u7B2C {n} \u8F6E",
         "path.empty": "\uFF08\u5F53\u524D\u6CA1\u6709\u5BF9\u8BDD\u8F6E\u6B21\uFF09",
         "options.closeGuard": "\u9000\u51FA\u786E\u8BA4\uFF08\u5173\u95ED\u5B88\u536B\uFF09",
-        "options.closeGuardDesc": "\u5F00\uFF08\u9ED8\u8BA4\uFF09\uFF1A\u9875\u9762/\u7A97\u53E3\u5173\u95ED\u524D\u786E\u8BA4\u9000\u51FA\u2014\u2014\u6709\u8FD0\u884C\u4E2D\u4EFB\u52A1\u6216\u672A\u5B8C\u6210\u5BF9\u8BDD\u65F6\u5F3A\u62E6\u5E76\u5217\u51FA\u660E\u7EC6\uFF08\u9632\u8BEF\u5173\u4E22\u8FDB\u5EA6\uFF09\uFF0C\u65E0\u4EFB\u52A1\u65F6\u8F7B\u786E\u8BA4\u4E00\u6B21\u3002\u6B64\u62E6\u622A\u4F5C\u7528\u4E8E\u6D4F\u89C8\u5668/\u9875\u9762\u5173\u95ED\u8DEF\u5F84\uFF08\u7F51\u9875\u7248\u6807\u7B7E\u9875\uFF1B\u684C\u9762\u7248\u5E94\u7528\u9000\u51FA\u4E3A\u5BBF\u4E3B\u539F\u751F\u8DEF\u5F84\uFF0C\u89C1\u8FD0\u884C\u4E2D\u6A2A\u5E45\u63D0\u793A\uFF09\u3002"
+        "options.closeGuardDesc": "\u5F00\uFF08\u9ED8\u8BA4\uFF09\uFF1A\u9875\u9762\u5173\u95ED\u524D\u786E\u8BA4\u9000\u51FA\u2014\u2014\u6709\u8FD0\u884C\u4E2D\u4EFB\u52A1\u6216\u672A\u5B8C\u6210\u5BF9\u8BDD\u65F6\u5F3A\u62E6\u5E76\u5217\u51FA\u660E\u7EC6\uFF08\u9632\u8BEF\u5173\u4E22\u8FDB\u5EA6\uFF09\uFF0C\u65E0\u4EFB\u52A1\u65F6\u8F7B\u786E\u8BA4\u4E00\u6B21\u3002\u53EA\u5728\u5BBF\u4E3B\u786E\u8BA4\u4F1A\u663E\u793A\u539F\u751F\u786E\u8BA4\u6846\u7684\u9875\u9762\u4E0A\u6B66\u88C5\uFF08\u666E\u901A\u6D4F\u89C8\u5668\u6807\u7B7E\u9875\uFF1B\u5173\u6389\u672C\u9879\u540C\u65F6\u505C\u7528\u8FD0\u884C\u4E2D\u6A2A\u5E45\uFF09\u3002\u684C\u9762\u7AEF\uFF08DSH Desktop\uFF09\u4E00\u5F8B\u4E0D\u6B66\u88C5\uFF1A\u9000\u51FA\u5165\u53E3\u968F\u7248\u672C/\u5E73\u53F0\u800C\u53D8\u2014\u2014\u5916\u90E8\u62A5\u544A\u7684 0.9.0 \u4E00\u7C7B\u5165\u53E3\u4F1A\u89E6\u53D1\u9875\u9762 beforeunload\uFF0C\u800C\u684C\u9762\u58F3\u672A\u5904\u7406 will-prevent-unload \u21D2 \u5426\u51B3\u88AB\u9759\u9ED8\u541E\u6389\u3001\u9000\u51FA\u5361\u4F4F\uFF1B2.0.9 \u7684\u6258\u76D8\u9879\u8D70 requestQuit\u2192window.destroy\u2192app.exit\uFF0C\u6839\u672C\u4E0D\u7ECF\u8FC7\u5B83\u3002\u9875\u9762\u91CC\u5206\u4E0D\u51FA\u662F\u54EA\u4E00\u7C7B\uFF0C\u6545\u684C\u9762\u4FDD\u62A4\u7531\u8FD0\u884C\u4E2D\u6A2A\u5E45\u627F\u62C5\u3002"
       };
       var en = {
         "action.edit": "Edit",
@@ -622,7 +625,7 @@ return {
         "path.round": "Round {n}",
         "path.empty": "(no conversation rounds yet)",
         "options.closeGuard": "Exit confirmation (close guard)",
-        "options.closeGuardDesc": "On (default): confirm before the page/window closes \u2014 when sessions have running or unfinished work a strong guard lists them (prevents accidental progress loss); otherwise a light one-time confirm. Applies to browser/page close paths (web tabs; Desktop app exit is a host-native path \u2014 see the running banner)."
+        "options.closeGuardDesc": "On (default): confirm before the page closes \u2014 when sessions have running or unfinished work a strong guard lists them (prevents accidental progress loss); otherwise a light one-time confirm. Armed only where the host reports a native confirm dialog (ordinary browser tabs; turning this off also disables the running banner). Desktop (DSH Desktop) never arms it: quit entries differ by version/platform \u2014 the 0.9.0-class entry in the external report does reach page beforeunload, and the shell has no will-prevent-unload handler, so the veto is swallowed silently and the exit hangs; the 2.0.9 tray item goes requestQuit\u2192window.destroy\u2192app.exit and never reaches it. The page cannot tell which one it is, so the running banner carries that protection instead."
       };
       function opFailureText(code, message, t) {
         if (code === "agent-busy") return t("error.busy");
@@ -2732,7 +2735,7 @@ return {
             const value = payload && payload.ok ? payload.value : null;
             if (!value || !Array.isArray(value.running)) return;
             const prev = store.get();
-            store.set({ running: value.running });
+            store.set({ running: value.running, quitVeto: value.quitVeto, surface: value.surface });
             if (runningSig(store.get()) !== runningSig(prev)) ui.dismissed = null;
             renderBanner();
           }).catch(() => {
@@ -2751,7 +2754,7 @@ return {
           }
         }
         function bannerNote(lang) {
-          return lang === "zh" ? "\u5173\u95ED\u9875\u9762/\u9000\u51FA\u524D\u8BF7\u5148\u786E\u8BA4\u2014\u2014\u4EFB\u52A1\u4E2D\u65AD\u53EF\u80FD\u4E22\u5931\u8FDB\u5EA6(\u684C\u9762\u7AEF\u5E94\u7528\u9000\u51FA\u5728\u5BBF\u4E3B\u4FA7,\u8BF7\u4EE5\u6B64\u6A2A\u5E45\u4E3A\u51C6)" : "Confirm before closing/exiting \u2014 interrupting work may lose progress (Desktop app exit is host-side; rely on this banner)";
+          return lang === "zh" ? "\u5173\u95ED\u9875\u9762/\u9000\u51FA\u524D\u8BF7\u5148\u786E\u8BA4\u2014\u2014\u4EFB\u52A1\u4E2D\u65AD\u53EF\u80FD\u4E22\u5931\u8FDB\u5EA6(\u684C\u9762\u7AEF\u4E0D\u6B66\u88C5\u539F\u751F\u9000\u51FA\u786E\u8BA4,\u8BF7\u4EE5\u6B64\u6A2A\u5E45\u4E3A\u51C6)" : "Confirm before closing/exiting \u2014 interrupting work may lose progress (no native exit prompt on Desktop; rely on this banner)";
         }
         function renderBanner() {
           const cfg = getConfig();
@@ -2893,6 +2896,7 @@ return {
           if (store.isArmed()) return;
           const kind = classifySnapshot(store.get());
           if (kind === "unknown") return;
+          if (!quitVetoOf(store.get())) return;
           try {
             event.preventDefault?.();
           } catch {

package/lib/http.js

@@ -32,6 +32,13 @@
  * — 关闭守卫 V2 :全会话运行中清单 { running: [...] }(或单会话
  *       runningState)——client beforeunload 拦截的同步读缓存源(纯读,复用
  *       lib/close-guard.js runningSessions)。
+ *       全会话形状另带宿主承载面 `{ surface, quitVeto }`(2026-09-18 外部 issue #1:
+ *       桌面端托盘退出死锁)。surface 由**宿主**按请求头 + 宿主痕迹判定
+ *       (lib/close-guard.js pageSurfaceOf);客户端只在 quitVeto === true 时武装原生
+ *       beforeunload 门 —— 桌面 Electron 页面回报 false:退出入口随 Desktop 版本/
+ *       平台而变,会经过 beforeunload 的那类版本(外部报告的 0.9.0)上否决被壳静默
+ *       吞掉、退出卡住;不经过它的版本(2.0.9 的 requestQuit → app.exit)上那扇门
+ *       本来就是空转。
  *
  * Per PLAN.md §4.6 the client carries its localStorage config on every
  * request as `x-retrace-config: {"versioning":bool,"git":bool,
@@ -42,7 +49,7 @@ import { createEditorApi } from './host-core.js'
 import { dshAdapter } from './adapter/dsh.js'
 // span 显式状态 → 业务层判定输入(与 index.js harness 入口同一处理)
 import { spanMissArgsOf } from './span-semantics.js'
-import { runningSessions, sessionRunningState } from './close-guard.js'
+import { runningSessions, sessionRunningState, guardSurfaceOf } from './close-guard.js'
 import { latestByBoundary, readSummaries, renderSummariesMarkdown } from './summary-store.js'
 import { boundaryTreeOf } from './boundary-tree.js'
 
@@ -289,6 +296,8 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback
    * 异步查询,client 每 GUARD_POLL_MS 拉一次缓存快照)。复用关闭守卫检测:
    * runningSessions(ctx) 全会话运行中清单(agent/queued/jobs/未闭合轮)。
    * 无 sessionId → { running: [...] };有 → 单会话 runningState。
+   * 全会话形状另带 { surface, quitVeto }(承载面,见文件头):**这一段是宿主侧唯一的
+   * 承载面证据来源** —— 请求头带 Desktop renderer 能力头就是 Electron 页面。
    * 纯读,无副作用(守卫只检测+确认,绝不中断/写事件)。
    */
   function handleRunningState(req, res, hostCtx, sessions, agents, searchParams) {
@@ -299,7 +308,7 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback
       const sessionId = searchParams.get('sessionId') ?? ''
       const value = sessionId
         ? sessionRunningState(guardCtx, sessionId)
-        : { running: runningSessions(guardCtx) }
+        : { running: runningSessions(guardCtx), ...guardSurfaceOf(hostCtx, req?.headers) }
       sendJson(res, 200, { ok: true, value })
     } catch (error) {
       sendError(res, error, log)
@@ -501,7 +510,9 @@ export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback
       return handleJsonPost(req, res, async (args) => {
         const guardCtx = { sessions, agents, jobs: ctx?.jobs }
         const sid = String(args?.sessionId ?? '')
-        return sid ? sessionRunningState(guardCtx, sid) : { running: runningSessions(guardCtx) }
+        return sid
+          ? sessionRunningState(guardCtx, sid)
+          : { running: runningSessions(guardCtx), ...guardSurfaceOf(ctx, req?.headers) }
       })
     }
     // 客户端半自报（2026-09-14 事故 2 的可见性补丁）：证明"客户端半装载了 + 注册了

package/lib/index.js

@@ -26,8 +26,9 @@ import { createVersioningSeam } from './versioning.js'
 import { createRollbackExecutor } from './rollback.js'
 import { createMarkerGuard } from './prewrite-guard.js'
 import { createWatchdog } from './watchdog.js'
+import { createBootPinRetry } from './boot-pin.js'
 import { attachExitWarning } from './interrupt-guard.js'
-import { attachCloseGuard, runningSessions, sessionRunningState } from './close-guard.js'
+import { attachCloseGuard, runningSessions, sessionRunningState, guardSurfaceOf } from './close-guard.js'
 import { sessionBadge as fnvBadge } from './badge.js'
 import { dshAdapter, semanticBadgeOf } from './adapter/dsh.js'
 // span 显式状态结果 → 业务层判定输入的统一下传(单一真相模块)
@@ -308,37 +309,28 @@ export function apply(ctx) {
       }
     }
     /**
-     * 启动批量 pin:DSH 会话渐进驻留,定期重试直到覆盖(幂等可重复,alreadyTagged 跳过)。
+     * 启动批量 pin(重试调度在 lib/boot-pin.js):DSH 会话渐进驻留,定期重试直到
+     * 覆盖(幂等可重复,alreadyTagged 跳过)。
      * 0.4.19 缺陷(用户实测前发现):`bootPin(99)` 被 `retries>=8` 挡住 → 30s 重跑永不执行;
      * 启动 24s 窗口内会话未驻留 → 永久放弃 → 短码永不显示(全天 0 条 bootPin 日志)。
-     * 修法:每次(成功或失败)都安排下一次,共 MAX_ATTEMPTS 次(30s×20 ≈ 启动后 10 分钟
+     * 修法:每次(成功或失败)都安排下一次,共 maxAttempts 次(30s×20 ≈ 启动后 10 分钟
      * 窗口,覆盖渐进驻留);错误打日志不静默。
+     * 2026-09-18(外部 issue #1):那串重试定时器的句柄此前被丢弃、不 unref 也不在
+     * dispose 里清 —— 30s 递归会把宿主事件循环钉到启动后 10 分钟,退出/关机被它拖住。
+     * 调度整体迁到 lib/boot-pin.js(可注入 schedule/unschedule ⇒ 句柄可被用例捕获),
+     * 句柄 unref + dispose 撤销,并由下面的 disposers 收口。
      */
-    function bootPin(attempts = 0) {
-      const MAX_ATTEMPTS = 20
-      const schedule = () => {
-        if (attempts < MAX_ATTEMPTS) setTimeout(() => bootPin(attempts + 1), 30000)
-      }
-      const sessionStore = ctx.sessions
-      const hasSessions = sessionStore && (
-        (typeof sessionStore.list === 'function' && sessionStore.list().length > 0) ||
-        (typeof sessionStore.values === 'function' && sessionStore.values().length > 0)
-      )
-      if (!hasSessions) {
-        schedule()
-        return
-      }
-      pinAllResident()
-        .then((result) => {
-          log(`retrace: bootPin(${attempts}) → ${result?.value?.total ?? 0} 个驻留会话标题已处理`)
-          schedule()
-        })
-        .catch((error) => {
-          log(`retrace: bootPin error: ${String(error).slice(0, 160)}`)
-          schedule()
-        })
-    }
-    bootPin(0)
+    const bootPinRetry = createBootPinRetry({
+      run: () => pinAllResident(),
+      hasResidentSessions: () => {
+        const sessionStore = ctx.sessions
+        return Boolean(sessionStore && (
+          (typeof sessionStore.list === 'function' && sessionStore.list().length > 0) ||
+          (typeof sessionStore.values === 'function' && sessionStore.values().length > 0)
+        ))
+      },
+      log,
+    })
     const disposers = [
       // 2026-09-07:recall 语义 = 遮蔽目标轮及之后全部(编辑=从此处分叉)
       // ——不再只遮蔽目标轮(缺陷①断层);tail 在官方 foldSurface
@@ -411,12 +403,17 @@ export function apply(ctx) {
           if (sid) {
             return { ok: true, value: sessionRunningState(ctx, sid) }
           }
-          return { ok: true, value: { running: runningSessions(ctx) } }
+          // 负载形状与 HTTP 面同构(含宿主承载面)。wire 通道拿不到请求对象 ⇒
+          // guardSurfaceOf(ctx, undefined) 只能靠宿主痕迹判:桌面宿主 → unknown
+          // (客户端不武装原生门,安全侧),web 宿主 → browser。
+          return { ok: true, value: { running: runningSessions(ctx), ...guardSurfaceOf(ctx, undefined) } }
         } catch (error) {
           return { ok: false, error: { code: 'internal', message: String(error) } }
         }
       }),
     ]
+    // 启动重试链的定时器收口(不再额外钉住宿主事件循环;dispose 时撤销挂着的那个)。
+    disposers.push(() => bootPinRetry.dispose())
     return () => disposers.forEach((dispose) => dispose())
   })()
 

package/lib/watchdog.js

@@ -49,6 +49,7 @@ const SNAPSHOT_DIR = 'dsh-retrace/snapshots'
  * @param {(cb: () => void, ms: number) => unknown} [options.schedule]
  *   定时器创建（默认全局 setInterval；⚠️ 不要用 ctx.setInterval——cordis ctx 是
  *   Proxy，访问未 inject 的 `timer` 属性会抛 "cannot get property ... without inject"）。
+ *   返回的句柄上若有 `unref`，本模块会调用它（宿主退出不被轮询钉住；测试可用假句柄断言）。
  * @param {(handle: unknown) => void} [options.unschedule]
  *   定时器销毁（默认全局 clearInterval）。
  * @returns {{ dispose(): void }}
@@ -117,6 +118,11 @@ export function createWatchdog(ctx, log = () => {}, options = {}) {
   // 直接抛 "cannot get property \"timer\" without inject"（实测启动崩溃）。
   // 全局 setInterval 由 host-runner sandbox 重定向（sandbox.js:92 TIMER_REDIRECT）。
   timer = schedule(tick, intervalMs)
+  // 2026-09-18（外部 issue #1：桌面端托盘退出死锁）：引用型定时器会把宿主进程钉在
+  // 事件循环上——会话早就跑完、插件也 dispose 过，宿主仍等这个 interval，退出/关机
+  // 被它拖住。宿主是 Node 侧 ⇒ unref（浏览器侧没有 unref，那里也不存在这个问题）。
+  // 注入的 schedule 同样走这一行，所以用例能用一个假句柄捕获到 unref 调用。
+  if (timer && typeof timer.unref === 'function') timer.unref()
   // 立即跑一次，避免启动后首个周期空窗。
   tick().catch((error) => log(`retrace-watchdog: 首轮检查失败：${String(error)}`))
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-retrace",
   "description": "Retrace · 回溯 — Recall, edit-and-resend, regenerate, and conversation/artifact versioning (timeline, rollback, fork map) for DeepSeek Harness — Web and Desktop",
-  "version": "0.4.28",
+  "version": "0.4.29",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",