dsh-retrace 0.4.20 → 0.4.25

package/README.md

@@ -77,6 +77,21 @@ Full steps in [📦 Installation](#-installation).
 | 🧭 | **Jump-to-conversation** | one click from a version to that point in the conversation (auto-loads history, anchor highlight) |
 | 🧹 | **Bounded storage** | snapshots keep the most recent N versions (default 50); throttled background sweep prunes truncated ones |
 
+**Close guard (don't lose work by accident)** — before you exit or reload, know what is still running:
+
+| | What | |
+|---|---|---|
+| 🛡️ | **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.
+
 **Why it's different** (the interaction layer — the guarantees above are the storage layer):
 
 - 🎯 **Whole-round recall** — removes the input *and* its output (tool rows included), not just a single bubble.

package/README.zh.md

@@ -233,6 +233,21 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
 
 ---
 
+**关闭守卫（防误关丢进度）** —— 退出/重载前先看清还有什么在跑：
+
+| | 是什么 | |
+|---|---|---|
+| 🛡️ | **运行中检测** | 逐会话扫描运行中工作：agent 正在跑 / inbox 排队 / 后台 jobs / 未闭合轮 |
+| 📋 | **运行中横幅** | 有运行中工作的会话显示页面常驻横幅（会话短码 + 原因），退出前可见 |
+| ⚠️ | **退出提示** | 插件 dispose（应用退出/重载）时中文提示列出每个运行中会话与原因——只提示，绝不代你取消 agent |
+| 🔒 | **页面关闭拦截（Web）** | `beforeunload` 拦截：有运行中任务强确认（明细模态，`[仍关闭]` 即确认离开），无任务轻确认 |
+| 🔎 | **查询面** | `retrace.runningState`（host RPC）+ `GET|POST /api/plugins/retrace/runningState`（HTTP），两入口同形状 |
+
+> 桌面说明：Electron 宿主退出时销毁窗口，页面 `beforeunload` 不会触发，宿主也未暴露
+> 插件可用的退出否决点——桌面侧由运行中横幅 + dispose 提示覆盖；Web 端拦截完整生效。
+
+---
+
 ## 🗺️ 路线图
 
 **当前已具备（0.4.x）：**

package/lib/adapter/dsh.js

@@ -41,13 +41,37 @@ async function readEvents(sessionId) {
   return readEventsFromFile(filePath)
 }
 
-/** 从指定文件路径读全量事件(测试可注入路径;生产走 readEvents 找 ~/.dsh)。 */
+/** 从指定文件路径读全量事件(测试可注入路径;生产走 readEvents 找 ~/.dsh)。
+ *  P0-6(代码 M-5):单次编辑/查询操作会连读多次(span+文件快照事实),每次全量
+ *  zstd 解压+JSON+foldSurface(1.37M 事件秒级)→ 加**进程级短缓存**(同批次
+ *  内共享一次读取;以 mtime+size 校验文件未变,变了即失效,防与写入撕裂)。
+ *  TTL 很短(300ms)只覆盖单次命令的连续读取,不缓存跨命令的陈旧数据。 */
+const readCache = new Map() // filePath → { sig, events, at }
+const READ_CACHE_TTL_MS = 300
 async function readEventsFromFile(filePath) {
   try {
     if (!filePath) return null
+    const { statSync } = await import('node:fs')
+    // 文件签名(mtimeMs+size):写入会改 mtime/size → 缓存自动失效
+    let sig = null
+    try {
+      const st = statSync(filePath)
+      sig = `${st.mtimeMs}:${st.size}`
+    } catch { sig = 'unreadable' }
+    const hit = readCache.get(filePath)
+    if (hit && hit.sig === sig && Date.now() - hit.at < READ_CACHE_TTL_MS) {
+      return hit.events
+    }
     const { loadSessionLog } = await import('dsh-log-contract')
     const log = loadSessionLog(filePath)
-    return log.events.map((r) => r.event)
+    const events = log.events.map((r) => r.event)
+    // 只缓存有效读取(失败不缓存,下次重试)
+    if (Array.isArray(events) && events.length > 0) {
+      readCache.set(filePath, { sig, events, at: Date.now() })
+      // 防膨胀:超过 32 个文件清空(单命令最多几个会话文件)
+      if (readCache.size > 32) readCache.clear()
+    }
+    return events
   } catch { return null }
 }
 
@@ -108,6 +132,67 @@ export function computeSpan(events, target, mode = 'round') {
   return { start: span[0], end: span[span.length - 1], shadowedSeqs: span }
 }
 
+/**
+ * 文件侧「目标同一轮的前置 user 原文」(M-1,独立审查 74e580d 后续)——regenerate
+ * 重发文本的唯一可靠来源。
+ *
+ * 为什么必须算在文件侧:host 内存 session.events 是窗口化/稀疏视图(带 undefined 洞),
+ * regenerate 在内存里「向前找最近的前置 user」会越过洞(洞里正是该轮 user)或越过被
+ * 遮蔽区间,选到**更早轮**的 user → 重发错文本 + marker targetSeq 指向错轮。round span
+ * 的起点在文件全量 events + 官方 foldSurface nodes 上就是目标同一轮的轮首 user
+ * (computeSpan round 模式向前找 isRoundBoundary 的落点),从该点单点取原文不可能跨轮。
+ *
+ * 纯函数(零平台 import)。
+ * @returns {{seq: number, text: string}|null} span 起点非轮边界 user(孤儿回复:向前
+ *   找不到 user;或非 round 模式)→ null(调用方保守处理:绝不重发更早轮的文本)。
+ */
+export function roundPromptOf(events, span, mode = 'round') {
+  if (mode !== 'round' || !span || !Array.isArray(events)) return null
+  const seq = span.start
+  if (typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0) return null
+  const event = events[seq]
+  if (!isRoundBoundary(event)) return null
+  const content = event.data?.content
+  const text = Array.isArray(content)
+    ? content.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('')
+    : ''
+  return { seq, text }
+}
+
+/**
+ * computeSpan + 文件快照事实(comm-200):一次遍历同时给出遮蔽 span 与
+ * 「文件快照已知最大 seq / 目标在快照里的 seq」。span 为 null 时,调用方
+ * (withFileSpan/http.js)把这些事实注入 args.spanFacts,host-core 据此区分:
+ *  - 目标 seq > 文件快照最大 seq → 文件尚未 flush 该消息(提交中)→ message-pending;
+ *  - 快照已覆盖目标位置却不在其 surface(span null)→ 真被遮蔽 → target-shadowed。
+ * 纯函数(与 computeSpan 同构,平台无关;零平台 import)。
+ *
+ * M-1(独立审查 74e580d 后续):同时带回 prompt = round span 起点 user 的原文
+ * (roundPromptOf)。span 命中时调用方把它注入 args.regeneratePrompt —— regenerate
+ * 的重发文本/ marker targetSeq 一律取自文件侧,不再直扫 host 稀疏 events
+ * (直扫会越过洞选中更早轮 user,重发错文本)。
+ *
+ * @returns {{span: object|null, facts: {fileMaxSeq: number, targetSeq: number},
+ *   prompt: {seq: number, text: string}|null}}
+ */
+export function computeSpanProbe(events, target, mode = 'round', opts = {}) {
+  const span = computeSpan(events, target, mode, opts)
+  let targetSeq = typeof target === 'number' ? target : -1
+  let fileMaxSeq = -1
+  if (Array.isArray(events)) {
+    for (let i = events.length - 1; i >= 0; i--) {
+      const ev = events[i]
+      if (!ev) continue
+      if (typeof ev.seq === 'number' && ev.seq > fileMaxSeq) fileMaxSeq = ev.seq
+      if (targetSeq === -1) {
+        const id = ev?.type === 'user/message' ? ev.data?.id : ev?.type === 'assistant/message' ? ev.data?.message?.id : undefined
+        if (typeof id === 'string' && id === target) targetSeq = ev.seq
+      }
+    }
+  }
+  return { span, facts: { fileMaxSeq, targetSeq: targetSeq >= 0 ? targetSeq : -1 }, prompt: roundPromptOf(events, span, mode) }
+}
+
 /**
  * DSH 适配器:EventReader 实现。
  * 从文件读全量事件(可靠事实),并提供基于它的遮蔽计算。
@@ -119,6 +204,17 @@ export const dshAdapter = {
     const events = await readEvents(sessionId)
     return computeSpan(events, target, mode)
   },
+  /**
+   * 便捷:读事件一次,同时给出 span 与文件快照事实(comm-200)。span 为 null 时
+   * 调用方(withFileSpan/http.js)注入 facts → host-core 区分「提交中(message-pending)」
+   * 与「真被遮蔽(target-shadowed)」——文件 flush 滞后不再误报「已不在活跃对话」。
+   * M-1(独立审查 74e580d 后续):probe.prompt = round span 起点 user 的**文件侧原文**
+   * ——regenerate 的重发文本/ marker targetSeq 取自这里,不直扫 host 稀疏 events。
+   */
+  async spanProbeFromFile(sessionId, target, mode = 'round', opts = {}) {
+    const events = await readEvents(sessionId)
+    return computeSpanProbe(events, target, mode, opts)
+  },
   /**
    * 从文件全量事件算某 turn 内的最大 step 号(情形② marker step 分配用)。
    * 绕开 host 窗口化 session.events(稀疏内存视图可能看不到 turn 内全部 step,

package/lib/client.bundle.js

@@ -27,8 +27,11 @@ var client_exports = {};
 __export(client_exports, {
   __setMessageEditorWire: () => __setMessageEditorWire,
   apply: () => apply,
+  en: () => en,
   inject: () => inject,
-  name: () => name
+  name: () => name,
+  opFailureText: () => opFailureText,
+  zh: () => zh
 });
 module.exports = __toCommonJS(client_exports);
 var import_react = require("react");
@@ -69,6 +72,98 @@ function sessionBadge(sessionId) {
   return toBase36(fnv1a64(uuid)).padStart(10, "0").slice(0, 10);
 }
 
+// lib/close-guard-client.js
+var GUARD_POLL_MS = 5e3;
+var GUARD_TTL_MS = 3e4;
+var GUARD_ARM_TTL_MS = 3e4;
+function localeOf(locale) {
+  return locale === "en" ? "en" : "zh";
+}
+function parseReason(reason) {
+  const raw = typeof reason === "string" ? reason : "";
+  let match;
+  if (raw === "agent-running") return { code: "agent-running" };
+  if (match = raw.match(/^queued-(\d+)$/)) return { code: "queued", count: Number(match[1]) };
+  if (match = raw.match(/^jobs-(\d+)$/)) return { code: "jobs", count: Number(match[1]) };
+  if (match = raw.match(/^unclosed-turn-(.+)$/)) {
+    const turns = match[1].split(",").map((t) => Number(t)).filter((t) => Number.isInteger(t));
+    return { code: "unclosed-turn", turns };
+  }
+  return { code: "other", raw };
+}
+function describeReason(reason, locale = "zh") {
+  const lang = localeOf(locale);
+  const r = parseReason(reason);
+  switch (r.code) {
+    case "agent-running":
+      return lang === "zh" ? "\u6B63\u5728\u8FD0\u884C" : "agent running";
+    case "queued":
+      return lang === "zh" ? `\u6392\u961F\u5F85\u529E ${r.count} \u6761` : `${r.count} queued`;
+    case "jobs":
+      return lang === "zh" ? `\u540E\u53F0\u4EFB\u52A1 ${r.count} \u4E2A` : `${r.count} background job${r.count === 1 ? "" : "s"}`;
+    case "unclosed-turn":
+      return lang === "zh" ? `\u672A\u95ED\u5408\u8F6E\u6B21 ${r.turns.join("\u3001")}` : `unclosed turn ${r.turns.join(",")}`;
+    default:
+      return r.raw || (lang === "zh" ? "\u8FD0\u884C\u4E2D" : "running");
+  }
+}
+function sessionLine(item, { locale = "zh", label } = {}) {
+  const lang = localeOf(locale);
+  const id = label || item?.sessionId || "?";
+  const reasons = Array.isArray(item?.reasons) ? item.reasons : [];
+  const body = reasons.length > 0 ? reasons.map((r) => describeReason(r, lang)).join("; ") : lang === "zh" ? "\u8FD0\u884C\u4E2D(\u539F\u56E0\u672A\u8BC6\u522B)" : "running (reason unknown)";
+  return `- ${lang === "zh" ? "\u4F1A\u8BDD" : "session"} ${id}: ${body}`;
+}
+function runningLines(running, { locale = "zh", labelOf } = {}) {
+  const items = Array.isArray(running) ? running : [];
+  return items.map((item) => sessionLine(item, {
+    locale,
+    label: typeof labelOf === "function" ? labelOf(item.sessionId) : void 0
+  }));
+}
+function classifySnapshot(snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.running)) return "unknown";
+  return snapshot.running.length > 0 ? "running" : "idle";
+}
+function isStale(snapshot, { ttlMs = GUARD_TTL_MS, now = Date.now() } = {}) {
+  return !snapshot || typeof snapshot.at !== "number" || now - snapshot.at > ttlMs;
+}
+function buildRunningCopy(snapshot, { locale = "zh", labelOf, now = Date.now(), ttlMs = GUARD_TTL_MS } = {}) {
+  const lang = localeOf(locale);
+  const running = Array.isArray(snapshot?.running) ? snapshot.running : [];
+  const count = running.length;
+  const head = lang === "zh" ? `\u6709 ${count} \u4E2A\u4F1A\u8BDD\u5B58\u5728\u8FD0\u884C\u4E2D\u4EFB\u52A1,\u5173\u95ED\u5C06\u4E2D\u65AD\u8FDB\u5EA6` : `${count} session${count === 1 ? "" : "s"} with running work \u2014 closing will interrupt progress`;
+  const lines = runningLines(running, { locale: lang, labelOf });
+  const stale = isStale(snapshot, { ttlMs, 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 createGuardStore({ now = Date.now, armTtlMs = GUARD_ARM_TTL_MS } = {}) {
+  let snapshot = null;
+  let armedAt = 0;
+  return {
+    /** 设置最新 host 快照(runningSessions 形状 { running: [...] })。 */
+    set(next) {
+      snapshot = next && typeof next === "object" ? { ...next, at: next.at ?? now() } : null;
+    },
+    get() {
+      return snapshot;
+    },
+    /** 用户确认仍关闭 → 放行标记(二次触发有效)。 */
+    arm() {
+      armedAt = now();
+    },
+    /** 放行标记是否仍有效(未过期)。 */
+    isArmed() {
+      return armedAt > 0 && now() - armedAt <= armTtlMs;
+    },
+    /** 状态重变(运行中→静止→运行中)或手动重置时清除放行。 */
+    disarm() {
+      armedAt = 0;
+    }
+  };
+}
+
 // lib/client.js
 var name = "dsh-retrace";
 var inject = ["slots", "locale", "conversationEvents"];
@@ -163,6 +258,10 @@ var zh = {
   "timeline.gitInitConfirm": "\u786E\u5B9A\u8981\u521D\u59CB\u5316 git \u5417\uFF1F",
   "error.generic": "\u64CD\u4F5C\u5931\u8D25\uFF0C\u8BF7\u91CD\u8BD5",
   "error.busy": "\u8BF7\u5148\u505C\u6B62\u5F53\u524D\u56DE\u590D\u518D\u64CD\u4F5C",
+  // comm-199/200:不再原样透传 host 错误(曾为英文 "no longer part of the active
+  // conversation"——把「提交中」误报成「已不在活跃对话」)。按 code 本地化:
+  "error.targetShadowed": "\u8BE5\u6D88\u606F\u4F4D\u4E8E\u5DF2\u6298\u53E0\u5757(\u5386\u53F2\u53EA\u8BFB):\u5C55\u5F00\u8BE5\u5757\u540E\u7F16\u8F91,\u6216\u8FFD\u52A0\u65B0\u6D88\u606F\u4FEE\u8BA2",
+  "error.messagePending": "\u6D88\u606F\u751F\u6210\u4E2D,\u5B8C\u6210\u540E\u53EF\u7F16\u8F91",
   "view.fork": "\u5206\u53C9",
   "fork.title": "\u5206\u53C9\u56FE",
   "fork.empty": "\u8FD8\u6CA1\u6709\u5206\u53C9\u3002\u64A4\u56DE / \u7F16\u8F91 / \u91CD\u65B0\u751F\u6210 / \u6062\u590D\u4F1A\u5728\u6B64\u4EA7\u751F\u5206\u53C9\u3002",
@@ -181,7 +280,9 @@ var zh = {
   "fork.badge": "\u4F1A\u8BDD\u77ED\u7801",
   "fork.badgeHint": "\u77ED\u7801\u7531\u4F1A\u8BDD\u552F\u4E00 id \u786E\u5B9A\u6027\u5BFC\u51FA\uFF0C\u6C38\u4E0D\u53D8\uFF08\u6807\u9898\u4F1A\u53D8\uFF09\u3002",
   "fork.rename": "\u6539\u540D\u79F0",
-  "fork.renamePrompt": "\u8F93\u5165\u4F1A\u8BDD\u540D\u79F0\uFF08\u81EA\u52A8\u62FC\u63A5\u77ED\u7801\uFF0C\u8BBE\u7F6E\u540E\u56FA\u5B9A\u4E0D\u518D\u81EA\u52A8\u6539\u540D\uFF09\uFF1A"
+  "fork.renamePrompt": "\u8F93\u5165\u4F1A\u8BDD\u540D\u79F0\uFF08\u81EA\u52A8\u62FC\u63A5\u77ED\u7801\uFF0C\u8BBE\u7F6E\u540E\u56FA\u5B9A\u4E0D\u518D\u81EA\u52A8\u6539\u540D\uFF09\uFF1A",
+  "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"
 };
 var en = {
   "action.edit": "Edit",
@@ -261,6 +362,9 @@ var en = {
   "timeline.gitInitConfirm": "Initialize git in this workspace?",
   "error.generic": "Operation failed; please try again",
   "error.busy": "Stop the current reply before recalling or editing",
+  // comm-199/200:localized by code (see zh). Never show the raw host copy verbatim.
+  "error.targetShadowed": "This message is inside a folded (read-only) history block: expand that block to edit it, or append a new message instead",
+  "error.messagePending": "Message is still being generated; edit it once it finishes",
   "view.fork": "Fork",
   "fork.title": "Fork map",
   "fork.empty": "No forks yet. Recall / edit / regenerate / restore fork the path here.",
@@ -279,8 +383,16 @@ var en = {
   "fork.badge": "Session badge",
   "fork.badgeHint": "A stable shortcode derived from the session id (titles change, badges never do).",
   "fork.rename": "Rename",
-  "fork.renamePrompt": "Enter a session name (badge is prefixed automatically; the title is then pinned, no auto-rename):"
+  "fork.renamePrompt": "Enter a session name (badge is prefixed automatically; the title is then pinned, no auto-rename):",
+  "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)."
 };
+function opFailureText(code, message, t) {
+  if (code === "agent-busy") return t("error.busy");
+  if (code === "target-shadowed") return t("error.targetShadowed");
+  if (code === "message-pending") return t("error.messagePending");
+  return message ?? t("error.generic");
+}
 var SURFACE_TYPES = /* @__PURE__ */ new Set(["user/message", "assistant/message", "tool/result"]);
 function isReplacementSurfaceEvent(event) {
   return SURFACE_TYPES.has(event.type) && event.surfaceOp !== void 0 && event.surfaceOp !== "append";
@@ -305,7 +417,7 @@ function retraceConfigHeaders() {
   return { "x-retrace-config": JSON.stringify({ versioning, git, retentionLimit }) };
 }
 var CONFIG_VERSION = 3;
-var CONFIG_DEFAULTS = { version: CONFIG_VERSION, showOriginalInput: true, editFromScratch: false, hideShadowed: true, versioning: true, git: true, retentionLimit: 50, prewrite: true };
+var CONFIG_DEFAULTS = { version: CONFIG_VERSION, showOriginalInput: true, editFromScratch: false, hideShadowed: true, versioning: true, git: true, retentionLimit: 50, prewrite: true, closeGuard: true };
 var configListeners = /* @__PURE__ */ new Set();
 var configCache = readConfig();
 var editReferences = /* @__PURE__ */ new Map();
@@ -652,7 +764,7 @@ function AssistantActions({ messageId, sessionId, useSession, t }) {
         if (!result || result.ok !== true) {
           const message = result?.error?.message || "Operation failed; please try again";
           const code = result?.error?.code;
-          setFailure(code === "agent-busy" ? t("error.busy") : message);
+          setFailure(opFailureText(code, message, t));
         }
       },
       (error) => {
@@ -724,7 +836,7 @@ function UserActionsRow({ node, sessionId, useSession, inputActions, t }) {
     setBusy(false);
     if (!result || result.ok !== true) {
       const code = result?.error?.code;
-      setFailure(code === "agent-busy" ? t("error.busy") : result?.error?.message ?? t("error.generic"));
+      setFailure(opFailureText(code, result?.error?.message ?? null, t));
       return;
     }
     if (result.value?.markerT1Broken === true) {
@@ -859,6 +971,7 @@ function OptionsRow({ t }) {
     optionRow("hideShadowed", "options.hideShadowed", "options.hideShadowedDesc"),
     optionRow("versioning", "options.versioning", "options.versioningDesc"),
     optionRow("git", "options.git", "options.gitDesc"),
+    optionRow("closeGuard", "options.closeGuard", "options.closeGuardDesc"),
     (0, import_react.createElement)("div", { key: "retention", className: "dsh-rt-option dsh-rt-option-number" }, [
       (0, import_react.createElement)("span", { className: "dsh-rt-option-text" }, [
         (0, import_react.createElement)("span", { className: "dsh-rt-option-label" }, t("options.retention")),
@@ -989,6 +1102,24 @@ var CSS = `
 .dsh-rt-fork-badge-tag{font-size:11px;font-weight:500;line-height:16px;color:var(--dsw-alias-label-secondary);flex:none}
 .dsh-rt-fork-badge-code{font-family:var(--dsw-font-mono);font-size:12px;font-weight:600;line-height:16px;color:var(--dsw-alias-state-info-primary);flex:none}
 .dsh-rt-fork-badge-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+/* \u5173\u95ED\u5B88\u536B V2(comm-176):\u8FD0\u884C\u4E2D\u6A2A\u5E45 / A \u660E\u7EC6\u6A21\u6001 / \u653E\u884C\u63D0\u793A(\u72EC\u7ACB\u4E8E\u4F1A\u8BDD\u89C6\u56FE) */
+.dsh-rt-guard-banner{position:fixed;top:10px;right:10px;z-index:2147483000;max-width:min(430px,calc(100vw - 20px));background:var(--dsw-alias-bg-elevated,#262626);border:1px solid #b8860b;border-radius:10px;padding:8px 10px;font-size:12px;line-height:18px;color:var(--dsw-alias-label-primary,#eee);box-shadow:0 4px 20px rgba(0,0,0,.4);display:flex;flex-direction:column;gap:4px;text-align:left}
+.dsh-rt-guard-banner-head{display:flex;align-items:center;gap:6px;font-weight:600;color:#f0c674}
+.dsh-rt-guard-banner-note{color:var(--dsw-alias-label-caption,#aaa);font-size:11px;line-height:16px}
+.dsh-rt-guard-banner-list{margin:2px 0 0;padding:0 0 0 14px;color:var(--dsw-alias-label-primary,#eee);font-family:var(--dsw-font-mono,ui-monospace,monospace);font-size:11px;line-height:17px;white-space:pre-line}
+.dsh-rt-guard-link{background:none;border:none;padding:0;color:var(--dsw-alias-state-info-primary,#7ab8ff);font-size:11px;cursor:pointer}
+.dsh-rt-guard-link:hover{text-decoration:underline}
+.dsh-rt-guard-btn{border:1px solid var(--dsw-alias-border-l2,#555);background:transparent;color:var(--dsw-alias-label-primary,#eee);border-radius:6px;padding:2px 10px;font-size:12px;line-height:20px;cursor:pointer}
+.dsh-rt-guard-btn:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.08))}
+.dsh-rt-guard-btn-primary{border-color:#a33;background:#8b1f1f;color:#fff;font-weight:600}
+.dsh-rt-guard-btn-primary:hover{background:#a33}
+.dsh-rt-guard-overlay{position:fixed;inset:0;z-index:2147483001;background:rgba(0,0,0,.45);display:flex;align-items:center;justify-content:center;padding:16px}
+.dsh-rt-guard-modal{background:var(--dsw-alias-bg-elevated,#202020);border:1px solid #b8860b;border-radius:12px;max-width:min(520px,calc(100vw - 32px));padding:14px 16px;font-size:13px;line-height:20px;color:var(--dsw-alias-label-primary,#eee);box-shadow:0 10px 40px rgba(0,0,0,.5);display:flex;flex-direction:column;gap:10px}
+.dsh-rt-guard-modal-title{font-weight:700;color:#f0c674;font-size:14px}
+.dsh-rt-guard-modal-lines{margin:0;padding:0 0 0 16px;font-family:var(--dsw-font-mono,ui-monospace,monospace);font-size:12px;line-height:19px;white-space:pre-line}
+.dsh-rt-guard-modal-hint{color:var(--dsw-alias-label-caption,#aaa);font-size:11px;line-height:16px}
+.dsh-rt-guard-modal-actions{display:flex;justify-content:flex-end;gap:8px}
+.dsh-rt-guard-toast{position:fixed;left:50%;bottom:28px;transform:translateX(-50%);z-index:2147483002;background:var(--dsw-alias-bg-elevated,#262626);border:1px solid var(--dsw-alias-border-l2,#555);border-radius:8px;padding:6px 12px;font-size:12px;line-height:18px;color:var(--dsw-alias-label-primary,#eee);box-shadow:0 4px 16px rgba(0,0,0,.35);max-width:min(560px,calc(100vw - 24px))}
 `;
 var JUMP_PAGE_BUDGET = 24;
 function switchToViewTab(viewId) {
@@ -1535,11 +1666,255 @@ function ForkHistRow({ boundary, markerText, t, onJump }) {
     (0, import_react.createElement)("button", { key: "jump", type: "button", className: "dsh-rt-chip", onClick: onJump }, t("timeline.jump"))
   ]);
 }
+var GUARD_MODAL_ID = "dsh-rt-guard-modal";
+var GUARD_BANNER_ID = "dsh-rt-guard-banner";
+var GUARD_TOAST_ID = "dsh-rt-guard-toast";
+function installCloseGuard(t) {
+  if (typeof window === "undefined" || typeof document === "undefined") return () => {
+  };
+  const locale = () => t("action.cancel") === "\u53D6\u6D88" ? "zh" : "en";
+  const store = createGuardStore();
+  const ui = { banner: null, modal: null, toast: null, toastTimer: 0, dismissed: null, expanded: false, lastSig: "" };
+  let supported = true;
+  let failures = 0;
+  const labelOf = (sessionId) => {
+    try {
+      const badge = sessionBadge(sessionId);
+      return badge || String(sessionId);
+    } catch {
+      return String(sessionId);
+    }
+  };
+  const runningSig = (snapshot) => {
+    const running = snapshot?.running;
+    if (!Array.isArray(running)) return "";
+    return running.map((r) => `${r.sessionId}:${(r.reasons ?? []).join(",")}`).join("|");
+  };
+  function queryRunningState() {
+    if (typeof wire === "function") return wire("runningState", {});
+    return fetch(`${ROUTE_BASE}/runningState`, {
+      method: "GET",
+      headers: retraceConfigHeaders(),
+      cache: "no-store"
+    }).then((res) => {
+      if (res.status < 200 || res.status >= 300) throw new Error(`HTTP ${res.status}`);
+      return res.json();
+    });
+  }
+  function refresh() {
+    if (!supported) return;
+    queryRunningState().then((payload) => {
+      failures = 0;
+      const value = payload && payload.ok ? payload.value : null;
+      if (!value || !Array.isArray(value.running)) return;
+      const prev = store.get();
+      store.set({ running: value.running });
+      if (runningSig(store.get()) !== runningSig(prev)) ui.dismissed = null;
+      renderBanner();
+    }).catch(() => {
+      failures += 1;
+      if (failures >= 3) {
+        supported = false;
+        removeBanner();
+        console.warn("[dsh-retrace] close-guard: running-state \u901A\u9053\u4E0D\u53EF\u7528(3 \u6B21\u5931\u8D25),\u672C\u9875\u5173\u95ED\u5B88\u536B\u505C\u7528");
+      }
+    });
+  }
+  function removeBanner() {
+    if (ui.banner) {
+      ui.banner.remove();
+      ui.banner = null;
+    }
+  }
+  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)";
+  }
+  function renderBanner() {
+    const cfg = getConfig();
+    if (!cfg.closeGuard || !supported) return removeBanner();
+    const snap = store.get();
+    if (classifySnapshot(snap) !== "running") return removeBanner();
+    const lang = locale();
+    const lines = runningLines(snap.running, { locale: lang, labelOf });
+    const sig = lines.join("\n");
+    if (ui.dismissed === sig) return;
+    if (ui.banner && ui.banner.isConnected && ui.lastSig === sig) return;
+    if (!ui.banner) {
+      ui.banner = document.createElement("div");
+      ui.banner.id = GUARD_BANNER_ID;
+      ui.banner.className = "dsh-rt-guard-banner";
+      const head2 = document.createElement("div");
+      head2.className = "dsh-rt-guard-banner-head";
+      ui.banner.appendChild(head2);
+      const note = document.createElement("div");
+      note.className = "dsh-rt-guard-banner-note";
+      ui.banner.appendChild(note);
+      const list = document.createElement("div");
+      list.className = "dsh-rt-guard-banner-list";
+      list.style.display = "none";
+      ui.banner.appendChild(list);
+      document.body.appendChild(ui.banner);
+    }
+    const n = snap.running.length;
+    const head = ui.banner.firstChild;
+    head.textContent = "";
+    head.appendChild(document.createTextNode(lang === "zh" ? `\u26A0\uFE0F ${n} \u4E2A\u4F1A\u8BDD\u8FD0\u884C\u4E2D` : `\u26A0\uFE0F ${n} session${n === 1 ? "" : "s"} running`));
+    const toggle = document.createElement("button");
+    toggle.type = "button";
+    toggle.className = "dsh-rt-guard-link";
+    toggle.textContent = ui.expanded ? lang === "zh" ? "\u6536\u8D77" : "Hide" : lang === "zh" ? "\u660E\u7EC6" : "Details";
+    toggle.onclick = () => {
+      ui.expanded = !ui.expanded;
+      const list = ui.banner.querySelector(".dsh-rt-guard-banner-list");
+      if (list) list.style.display = ui.expanded ? "block" : "none";
+      toggle.textContent = ui.expanded ? lang === "zh" ? "\u6536\u8D77" : "Hide" : lang === "zh" ? "\u660E\u7EC6" : "Details";
+    };
+    const dismiss = document.createElement("button");
+    dismiss.type = "button";
+    dismiss.className = "dsh-rt-guard-link";
+    dismiss.textContent = "\xD7";
+    dismiss.title = lang === "zh" ? "\u5FFD\u7565(\u4EFB\u52A1\u7ED3\u675F\u6216\u53D8\u5316\u540E\u518D\u63D0\u793A)" : "Dismiss (re-shows when the running set changes)";
+    dismiss.onclick = () => {
+      ui.dismissed = sig;
+      removeBanner();
+    };
+    head.appendChild(toggle);
+    head.appendChild(dismiss);
+    ui.banner.querySelector(".dsh-rt-guard-banner-note").textContent = bannerNote(lang);
+    const listEl = ui.banner.querySelector(".dsh-rt-guard-banner-list");
+    listEl.textContent = lines.join("\n");
+    listEl.style.display = ui.expanded ? "block" : "none";
+    ui.lastSig = sig;
+  }
+  function hideModal() {
+    if (ui.modal) {
+      ui.modal.remove();
+      ui.modal = null;
+    }
+  }
+  function showModal() {
+    const snap = store.get();
+    if (classifySnapshot(snap) !== "running") return;
+    const lang = locale();
+    const copy = buildRunningCopy(snap, { locale: lang, labelOf });
+    hideModal();
+    const overlay = document.createElement("div");
+    overlay.className = "dsh-rt-guard-overlay";
+    overlay.id = GUARD_MODAL_ID;
+    overlay.onclick = (event) => {
+      if (event.target === overlay) hideModal();
+    };
+    const modal = document.createElement("div");
+    modal.className = "dsh-rt-guard-modal";
+    modal.onclick = (event) => event.stopPropagation();
+    const title = document.createElement("div");
+    title.className = "dsh-rt-guard-modal-title";
+    title.textContent = copy.head;
+    modal.appendChild(title);
+    const lines = document.createElement("div");
+    lines.className = "dsh-rt-guard-modal-lines";
+    lines.textContent = copy.lines.join("\n");
+    modal.appendChild(lines);
+    if (copy.hint) {
+      const hint = document.createElement("div");
+      hint.className = "dsh-rt-guard-modal-hint";
+      hint.textContent = copy.hint;
+      modal.appendChild(hint);
+    }
+    const actions = document.createElement("div");
+    actions.className = "dsh-rt-guard-modal-actions";
+    const cancel = document.createElement("button");
+    cancel.type = "button";
+    cancel.className = "dsh-rt-guard-btn";
+    cancel.textContent = lang === "zh" ? "\u53D6\u6D88" : "Cancel";
+    cancel.onclick = () => hideModal();
+    const proceed = document.createElement("button");
+    proceed.type = "button";
+    proceed.className = "dsh-rt-guard-btn dsh-rt-guard-btn-primary";
+    proceed.textContent = lang === "zh" ? "\u4ECD\u5173\u95ED" : "Close anyway";
+    proceed.onclick = () => {
+      store.arm();
+      hideModal();
+      try {
+        window.close();
+      } catch {
+      }
+      showToast(lang === "zh" ? "\u5DF2\u653E\u884C\u2014\u2014\u82E5\u672A\u81EA\u52A8\u9000\u51FA,\u8BF7\u518D\u6B21\u70B9\u51FB\u5173\u95ED\u7A97\u53E3/\u6807\u7B7E\u9875(30 \u79D2\u5185\u6709\u6548,\u8FC7\u671F\u9700\u91CD\u65B0\u786E\u8BA4)" : "Armed \u2014 if the window did not close, click close again (valid 30s, then re-confirm)");
+    };
+    actions.appendChild(cancel);
+    actions.appendChild(proceed);
+    modal.appendChild(actions);
+    overlay.appendChild(modal);
+    document.body.appendChild(overlay);
+    ui.modal = overlay;
+  }
+  function showToast(text) {
+    if (!ui.toast) {
+      ui.toast = document.createElement("div");
+      ui.toast.id = GUARD_TOAST_ID;
+      ui.toast.className = "dsh-rt-guard-toast";
+      document.body.appendChild(ui.toast);
+    }
+    ui.toast.textContent = text;
+    clearTimeout(ui.toastTimer);
+    ui.toastTimer = setTimeout(() => {
+      if (ui.toast) {
+        ui.toast.remove();
+        ui.toast = null;
+      }
+    }, 8e3);
+  }
+  function onBeforeUnload(event) {
+    if (!getConfig().closeGuard || !supported) return;
+    if (store.isArmed()) return;
+    const kind = classifySnapshot(store.get());
+    if (kind === "unknown") return;
+    try {
+      event.preventDefault?.();
+    } catch {
+    }
+    try {
+      event.returnValue = "";
+    } catch {
+    }
+    if (kind === "running") {
+      setTimeout(() => {
+        if (classifySnapshot(store.get()) === "running" && !store.isArmed()) showModal();
+      }, 0);
+    }
+  }
+  function onVisibility() {
+    if (document.visibilityState === "visible") refresh();
+  }
+  window.addEventListener("beforeunload", onBeforeUnload);
+  document.addEventListener("visibilitychange", onVisibility);
+  const timer = window.setInterval(refresh, GUARD_POLL_MS);
+  refresh();
+  const unsubscribe = subscribeConfig(() => {
+    renderBanner();
+    if (getConfig().closeGuard) refresh();
+  });
+  return () => {
+    window.removeEventListener("beforeunload", onBeforeUnload);
+    document.removeEventListener("visibilitychange", onVisibility);
+    window.clearInterval(timer);
+    unsubscribe();
+    removeBanner();
+    hideModal();
+    if (ui.toast) {
+      ui.toast.remove();
+      ui.toast = null;
+    }
+    clearTimeout(ui.toastTimer);
+  };
+}
 function apply(ctx) {
   const disposeStyle = ensureStyle();
   ctx.effect(() => () => disposeStyle(), "dsh-retrace: styles");
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-retrace: dictionaries");
   const t = ctx.locale.bind(NS);
+  const disposeCloseGuard = installCloseGuard(t);
+  ctx.effect(() => () => disposeCloseGuard(), "dsh-retrace: close guard");
   const conversationEvents = ctx.get("conversationEvents");
   if (conversationEvents) {
     const disposeDefinitions = [