dsh-retrace 0.4.11 → 0.4.12

package/lib/badge.js

@@ -0,0 +1,65 @@
+/**
+ * dsh-retrace — lib/badge.js
+ *
+ * 会话短码（identity badge）——2026-08-31 用户指定的小功能。
+ *
+ * 需求：与人交互时需要稳定的会话识别符（标题会变、session id 太长）。
+ * 解法：**从 session id（唯一值）确定性导出短码**——不依赖全量扫描、
+ * 不依赖外部短码表、插件运行时自算即可。同一 session id 永远得到同一短码。
+ *
+ * 与 `会话短码表.json`（工作区+序号语义格式 dx023dx001）的关系：
+ * - 外部表 = 人工维护的语义短码（线名/父子关系可读），由修复线维护；
+ * - 本模块 = 插件自算的确定性短码（人机交互兜底），任何环境可复现；
+ * - 两者并存：铭牌优先显示外部语义短码（若可查），否则用本模块兜底。
+ *
+ * 算法：FNV-1a 64-bit（uuid 段）→ base36 → 固定 10 位（补 0）。
+ * - 10 位纯字母数字（36^10 ≈ 3.6e15 空间，会话规模下碰撞可忽略）；
+ * - 只依赖 id 本身，无状态、无 IO、纯函数（可测试、可在 client/host 复用）。
+ */
+
+/** 提取 id 中的 uuid 段（hex），无匹配则退回 hex 清洗。 */
+export function uuidOf(id) {
+  const text = String(id ?? '')
+  const m = text.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i)
+  if (m) return m[0].replace(/-/g, '').toLowerCase()
+  const cleaned = text.replace(/[^0-9a-f]/gi, '').toLowerCase()
+  return cleaned.length >= 8 ? cleaned.slice(0, 32) : ''
+}
+
+/** FNV-1a 64-bit（BigInt，避免精度丢失）。 */
+export function fnv1a64(text) {
+  let hash = 0xcbf29ce484222325n
+  const prime = 0x100000001b3n
+  const mask = 0xffffffffffffffffn
+  for (let i = 0; i < text.length; i++) {
+    hash ^= BigInt(text.charCodeAt(i))
+    hash = (hash * prime) & mask
+  }
+  return hash
+}
+
+const BASE36 = '0123456789abcdefghijklmnopqrstuvwxyz'
+
+/** BigInt → base36 字符串。 */
+export function toBase36(value) {
+  if (value < 0n) value = -value
+  if (value === 0n) return '0'
+  let out = ''
+  let v = value
+  while (v > 0n) {
+    out = BASE36[Number(v % 36n)] + out
+    v /= 36n
+  }
+  return out
+}
+
+/**
+ * 会话短码：uuid 段 → FNV-1a 64 → base36 → 固定 10 位（补 0 截断）。
+ * @param {string} sessionId - 会话 id（`session-<uuid>` 或裸 uuid）。
+ * @returns {string} 10 位短码；无法提取 uuid 时返回空串（调用方自行兜底）。
+ */
+export function sessionBadge(sessionId) {
+  const uuid = uuidOf(sessionId)
+  if (uuid.length === 0) return ''
+  return toBase36(fnv1a64(uuid)).padStart(10, '0').slice(0, 10)
+}

package/lib/client.bundle.js

@@ -32,6 +32,44 @@ __export(client_exports, {
 });
 module.exports = __toCommonJS(client_exports);
 var import_react = require("react");
+
+// lib/badge.js
+function uuidOf(id) {
+  const text = String(id ?? "");
+  const m = text.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i);
+  if (m) return m[0].replace(/-/g, "").toLowerCase();
+  const cleaned = text.replace(/[^0-9a-f]/gi, "").toLowerCase();
+  return cleaned.length >= 8 ? cleaned.slice(0, 32) : "";
+}
+function fnv1a64(text) {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mask = 0xffffffffffffffffn;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= BigInt(text.charCodeAt(i));
+    hash = hash * prime & mask;
+  }
+  return hash;
+}
+var BASE36 = "0123456789abcdefghijklmnopqrstuvwxyz";
+function toBase36(value) {
+  if (value < 0n) value = -value;
+  if (value === 0n) return "0";
+  let out = "";
+  let v = value;
+  while (v > 0n) {
+    out = BASE36[Number(v % 36n)] + out;
+    v /= 36n;
+  }
+  return out;
+}
+function sessionBadge(sessionId) {
+  const uuid = uuidOf(sessionId);
+  if (uuid.length === 0) return "";
+  return toBase36(fnv1a64(uuid)).padStart(10, "0").slice(0, 10);
+}
+
+// lib/client.js
 var name = "dsh-retrace";
 var inject = ["slots", "locale", "conversationEvents"];
 var NS = "retrace";
@@ -139,7 +177,9 @@ var zh = {
   "fork.lineageThis": "\u5F53\u524D\u4F1A\u8BDD",
   "fork.lineageParent": "\u7236\u4F1A\u8BDD",
   "fork.lineageRoot": "\u6839\u4F1A\u8BDD",
-  "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002"
+  "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002",
+  "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"
 };
 var en = {
   "action.edit": "Edit",
@@ -233,7 +273,9 @@ var en = {
   "fork.lineageThis": "This session",
   "fork.lineageParent": "Parent session",
   "fork.lineageRoot": "Root session",
-  "fork.lineageEmpty": "This session has no parent (standalone root)."
+  "fork.lineageEmpty": "This session has no parent (standalone root).",
+  "fork.badge": "Session badge",
+  "fork.badgeHint": "A stable shortcode derived from the session id (titles change, badges never do)."
 };
 var SURFACE_TYPES = /* @__PURE__ */ new Set(["user/message", "assistant/message", "tool/result"]);
 function isReplacementSurfaceEvent(event) {
@@ -931,6 +973,10 @@ var CSS = `
 .dsh-rt-fork-lineage-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-primary);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .dsh-rt-fork-lineage-arrow{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);flex:none}
 .dsh-rt-fork-lineage-empty{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:6px 8px;flex:none}
+.dsh-rt-fork-badge{display:flex;align-items:center;gap:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-elevated);border-radius:8px;padding:6px 8px;flex:none;min-width:0}
+.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}
 `;
 var JUMP_PAGE_BUDGET = 24;
 function switchToViewTab(viewId) {
@@ -1316,6 +1362,12 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
         onClick: refresh
       }, t("fork.refresh"))
     ]),
+    // 会话铭牌（2026-08-31）：短码 = 从 session id 确定性导出，永不变（标题会变）。
+    sessionId && (0, import_react.createElement)("div", { key: "badge", className: "dsh-rt-fork-badge", title: t("fork.badgeHint") }, [
+      (0, import_react.createElement)("span", { key: "tag", className: "dsh-rt-fork-badge-tag" }, t("fork.badge")),
+      (0, import_react.createElement)("code", { key: "code", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(sessionId)}]`),
+      (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-badge-id" }, sessionId)
+    ]),
     Array.isArray(lineage) && lineage.length > 1 && (0, import_react.createElement)("div", { key: "lineage", className: "dsh-rt-fork-lineage" }, [
       (0, import_react.createElement)("div", { key: "lt", className: "dsh-rt-fork-spine-label" }, t("fork.lineage")),
       lineage.map((hop, i) => (0, import_react.createElement)("div", {
@@ -1327,6 +1379,7 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
           { key: "tag", className: "dsh-rt-fork-lineage-tag" },
           i === 0 ? t("fork.lineageThis") : i === lineage.length - 1 ? t("fork.lineageRoot") : t("fork.lineageParent")
         ),
+        (0, import_react.createElement)("code", { key: "badge", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(hop.id)}]`),
         (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-lineage-id" }, hop.id),
         i < lineage.length - 1 && (0, import_react.createElement)("span", { key: "arrow", className: "dsh-rt-fork-lineage-arrow" }, "\u2190")
       ]))

package/lib/client.js

@@ -16,6 +16,7 @@
  * `/api/plugins/retrace/*` registered by the Host half.
  */
 import { createElement, useEffect, useState } from 'react'
+import { sessionBadge } from './badge.js'
 
 export const name = 'dsh-retrace'
 export const inject = ['slots', 'locale', 'conversationEvents']
@@ -148,6 +149,8 @@ const zh = {
   'fork.lineageParent': '父会话',
   'fork.lineageRoot': '根会话',
   'fork.lineageEmpty': '本会话没有父会话（独立根会话）。',
+  'fork.badge': '会话短码',
+  'fork.badgeHint': '短码由会话唯一 id 确定性导出，永不变（标题会变）。',
 }
 /** English dictionary, checked complete against the zh key set. */
 const en = {
@@ -243,6 +246,8 @@ const en = {
   'fork.lineageParent': 'Parent session',
   'fork.lineageRoot': 'Root session',
   'fork.lineageEmpty': 'This session has no parent (standalone root).',
+  'fork.badge': 'Session badge',
+  'fork.badgeHint': 'A stable shortcode derived from the session id (titles change, badges never do).',
 }
 
 // ---------------------------------------------------------------------------
@@ -1164,6 +1169,10 @@ const CSS = `
 .dsh-rt-fork-lineage-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-primary);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .dsh-rt-fork-lineage-arrow{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);flex:none}
 .dsh-rt-fork-lineage-empty{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:6px 8px;flex:none}
+.dsh-rt-fork-badge{display:flex;align-items:center;gap:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-elevated);border-radius:8px;padding:6px 8px;flex:none;min-width:0}
+.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}
 `
 
 const JUMP_PAGE_BUDGET = 24
@@ -1726,6 +1735,13 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       }, t('fork.refresh')),
     ]),
 
+    // 会话铭牌（2026-08-31）：短码 = 从 session id 确定性导出，永不变（标题会变）。
+    sessionId && createElement('div', { key: 'badge', className: 'dsh-rt-fork-badge', title: t('fork.badgeHint') }, [
+      createElement('span', { key: 'tag', className: 'dsh-rt-fork-badge-tag' }, t('fork.badge')),
+      createElement('code', { key: 'code', className: 'dsh-rt-fork-badge-code' }, `[${sessionBadge(sessionId)}]`),
+      createElement('span', { key: 'id', className: 'dsh-rt-fork-badge-id' }, sessionId),
+    ]),
+
     Array.isArray(lineage) && lineage.length > 1 && createElement('div', { key: 'lineage', className: 'dsh-rt-fork-lineage' }, [
       createElement('div', { key: 'lt', className: 'dsh-rt-fork-spine-label' }, t('fork.lineage')),
       lineage.map((hop, i) => createElement('div', {
@@ -1734,6 +1750,7 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       }, [
         createElement('span', { key: 'tag', className: 'dsh-rt-fork-lineage-tag' },
           i === 0 ? t('fork.lineageThis') : (i === lineage.length - 1 ? t('fork.lineageRoot') : t('fork.lineageParent'))),
+        createElement('code', { key: 'badge', className: 'dsh-rt-fork-badge-code' }, `[${sessionBadge(hop.id)}]`),
         createElement('span', { key: 'id', className: 'dsh-rt-fork-lineage-id' }, hop.id),
         i < lineage.length - 1 && createElement('span', { key: 'arrow', className: 'dsh-rt-fork-lineage-arrow' }, '←'),
       ])),

package/lib/dynamic-client.js

@@ -38,6 +38,44 @@ return {
       });
       module.exports = __toCommonJS(client_exports);
       var import_react = require("react");
+      
+      // lib/badge.js
+      function uuidOf(id) {
+        const text = String(id ?? "");
+        const m = text.match(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i);
+        if (m) return m[0].replace(/-/g, "").toLowerCase();
+        const cleaned = text.replace(/[^0-9a-f]/gi, "").toLowerCase();
+        return cleaned.length >= 8 ? cleaned.slice(0, 32) : "";
+      }
+      function fnv1a64(text) {
+        let hash = 0xcbf29ce484222325n;
+        const prime = 0x100000001b3n;
+        const mask = 0xffffffffffffffffn;
+        for (let i = 0; i < text.length; i++) {
+          hash ^= BigInt(text.charCodeAt(i));
+          hash = hash * prime & mask;
+        }
+        return hash;
+      }
+      var BASE36 = "0123456789abcdefghijklmnopqrstuvwxyz";
+      function toBase36(value) {
+        if (value < 0n) value = -value;
+        if (value === 0n) return "0";
+        let out = "";
+        let v = value;
+        while (v > 0n) {
+          out = BASE36[Number(v % 36n)] + out;
+          v /= 36n;
+        }
+        return out;
+      }
+      function sessionBadge(sessionId) {
+        const uuid = uuidOf(sessionId);
+        if (uuid.length === 0) return "";
+        return toBase36(fnv1a64(uuid)).padStart(10, "0").slice(0, 10);
+      }
+      
+      // lib/client.js
       var name = "dsh-retrace";
       var inject = ["slots", "locale", "conversationEvents"];
       var NS = "retrace";
@@ -145,7 +183,9 @@ return {
         "fork.lineageThis": "\u5F53\u524D\u4F1A\u8BDD",
         "fork.lineageParent": "\u7236\u4F1A\u8BDD",
         "fork.lineageRoot": "\u6839\u4F1A\u8BDD",
-        "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002"
+        "fork.lineageEmpty": "\u672C\u4F1A\u8BDD\u6CA1\u6709\u7236\u4F1A\u8BDD\uFF08\u72EC\u7ACB\u6839\u4F1A\u8BDD\uFF09\u3002",
+        "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"
       };
       var en = {
         "action.edit": "Edit",
@@ -239,7 +279,9 @@ return {
         "fork.lineageThis": "This session",
         "fork.lineageParent": "Parent session",
         "fork.lineageRoot": "Root session",
-        "fork.lineageEmpty": "This session has no parent (standalone root)."
+        "fork.lineageEmpty": "This session has no parent (standalone root).",
+        "fork.badge": "Session badge",
+        "fork.badgeHint": "A stable shortcode derived from the session id (titles change, badges never do)."
       };
       var SURFACE_TYPES = /* @__PURE__ */ new Set(["user/message", "assistant/message", "tool/result"]);
       function isReplacementSurfaceEvent(event) {
@@ -937,6 +979,10 @@ return {
       .dsh-rt-fork-lineage-id{font-family:var(--dsw-font-mono);font-size:11px;line-height:16px;color:var(--dsw-alias-label-primary);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
       .dsh-rt-fork-lineage-arrow{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);flex:none}
       .dsh-rt-fork-lineage-empty{font-size:11px;line-height:16px;color:var(--dsw-alias-label-caption);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:6px 8px;flex:none}
+      .dsh-rt-fork-badge{display:flex;align-items:center;gap:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-elevated);border-radius:8px;padding:6px 8px;flex:none;min-width:0}
+      .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}
       `;
       var JUMP_PAGE_BUDGET = 24;
       function switchToViewTab(viewId) {
@@ -1322,6 +1368,12 @@ return {
               onClick: refresh
             }, t("fork.refresh"))
           ]),
+          // 会话铭牌（2026-08-31）：短码 = 从 session id 确定性导出，永不变（标题会变）。
+          sessionId && (0, import_react.createElement)("div", { key: "badge", className: "dsh-rt-fork-badge", title: t("fork.badgeHint") }, [
+            (0, import_react.createElement)("span", { key: "tag", className: "dsh-rt-fork-badge-tag" }, t("fork.badge")),
+            (0, import_react.createElement)("code", { key: "code", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(sessionId)}]`),
+            (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-badge-id" }, sessionId)
+          ]),
           Array.isArray(lineage) && lineage.length > 1 && (0, import_react.createElement)("div", { key: "lineage", className: "dsh-rt-fork-lineage" }, [
             (0, import_react.createElement)("div", { key: "lt", className: "dsh-rt-fork-spine-label" }, t("fork.lineage")),
             lineage.map((hop, i) => (0, import_react.createElement)("div", {
@@ -1333,6 +1385,7 @@ return {
                 { key: "tag", className: "dsh-rt-fork-lineage-tag" },
                 i === 0 ? t("fork.lineageThis") : i === lineage.length - 1 ? t("fork.lineageRoot") : t("fork.lineageParent")
               ),
+              (0, import_react.createElement)("code", { key: "badge", className: "dsh-rt-fork-badge-code" }, `[${sessionBadge(hop.id)}]`),
               (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-lineage-id" }, hop.id),
               i < lineage.length - 1 && (0, import_react.createElement)("span", { key: "arrow", className: "dsh-rt-fork-lineage-arrow" }, "\u2190")
             ]))

package/lib/http.js

@@ -81,8 +81,8 @@ function sendError(res, error) {
 }
 
 /** Route one request. `seam` is the versioning seam (lib/versioning.js). */
-export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback, log = () => {} }) {
-  const api = createEditorApi(ctx, sessions, agents, log)
+export function createRetraceHttpHandler(ctx, { sessions, agents, seam, rollback, hooks = {}, log = () => {} }) {
+  const api = createEditorApi(ctx, sessions, agents, log, hooks)
 
   function handleVersions(req, res, sessionId, config) {
     seam.setConfig(sessionId, config)

package/lib/index.js

@@ -25,6 +25,8 @@ import { createVersioningSeam } from './versioning.js'
 import { createRollbackExecutor } from './rollback.js'
 import { createMarkerGuard } from './prewrite-guard.js'
 import { createWatchdog } from './watchdog.js'
+import { attachExitWarning } from './interrupt-guard.js'
+import { sessionBadge } from './badge.js'
 
 export const name = 'dsh-retrace'
 export const inject = ['sessions', 'agents', 'webServer', 'fs', 'subprocess', 'sandboxPolicy']
@@ -52,6 +54,7 @@ export function apply(ctx) {
     agents: ctx.agents,
     seam,
     rollback,
+    hooks,
     log,
   })
 
@@ -78,6 +81,11 @@ export function apply(ctx) {
       harness.handle('retrace.recall', (args) => api.recall(args)),
       harness.handle('retrace.editAndResend', (args) => api.editAndResend(args)),
       harness.handle('retrace.regenerate', (args) => api.regenerate(args)),
+      // 会话短码（2026-08-31）：session id → 确定性 10 位短码，人机交互识别用。
+      harness.handle('retrace.sessionBadge', (args) => {
+        const sessionId = String(args?.sessionId ?? '')
+        return { ok: true, value: { sessionId, badge: sessionBadge(sessionId) } }
+      }),
     ]
     return () => disposers.forEach((dispose) => dispose())
   })()
@@ -85,9 +93,13 @@ export function apply(ctx) {
   // R1 实时看门狗：轮询文件尾部 seq vs 内存长度，捕获并发写入/旧光标回放现场。
   const watchdog = createWatchdog(ctx, log)
 
+  // R4 中断轮次治理：退出/重载时对未闭合 turn 会话提示（只检测不写事件）。
+  const warnUnclosed = attachExitWarning(ctx, log)
+
   ctx.effect(() => () => {
     disposeRoute()
     disposeHarness()
     watchdog.dispose()
+    warnUnclosed()
   }, 'dsh-retrace: transports')
 }

package/lib/interrupt-guard.js

@@ -0,0 +1,89 @@
+/**
+ * dsh-retrace · lib/interrupt-guard.js
+ *
+ * R4 中断轮次治理（2026-08-30 任务书 §4）。
+ *
+ * 目标：退出/关闭会话前对「未闭合 turn」的会话提示用户，避免误以为任务
+ * 已干净结束。
+ *
+ * 设计（按实现方案 §R4，铁律「先核实官方 turn 关闭路径」）：
+ *   - 官方 `dsh-agent-loop/lib/index.js:620` 在 finally 块保证 `turn/end`
+ *     必然写入（含 reason.kind='error' 的中断）——正常退出/中断路径不会
+ *     留下未闭合 turn；
+ *   - 未闭合 turn 只出现在「崩溃 / 强杀 / 断电」场景：有 turn/start 无
+ *     turn/end（interrupted/aborted 是官方正常闭合，不在此列）；
+ *   - 因此本守卫**只检测 + 提示，绝不自动写 turn/end**（与官方持久化竞态
+ *     会引入双写；且插件不应在运行期补写持久化事件——铁律「插件内不要
+ *     删除/重编号持久化事件」的同类约束）。
+ *
+ * 检测函数：
+ *   unclosedTurns(session) → { turn, state: 'open' }[]
+ *     扫描 session.events：turn/start 开、turn/end 关；尾部仍开 = 未闭合。
+ */
+
+/**
+ * 扫描会话，找未闭合的轮次。
+ * @param {object} session - DSH session 对象（session.events 为事件数组）。
+ * @returns {Array<{turn: number, state: 'open'}>}
+ *
+ * ⚠️ 判定（2026-08-31 独立审查修正）：只报**真正未闭合**的轮次——有
+ * turn/start 且尾部没有对应 turn/end（崩溃/强杀现场）。
+ * turn/end 的 reason.kind 为 'interrupted'/'aborted' 是官方**正常闭合**
+ * （用户主动中断，agent-loop finally 保证写入），archive 实测 69 会话中
+ * 666 aborted + 126 interrupted 全是正常闭合、真 open 只 10 个——把它们
+ * 当"未闭合"会在每次退出对 91% 会话打误导性 warning。
+ */
+export function unclosedTurns(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  const found = []
+  let openTurn = null
+  for (const event of events) {
+    if (!event || typeof event !== 'object') continue
+    if (event.type === 'turn/start') {
+      openTurn = event.data?.turn
+    } else if (event.type === 'turn/end') {
+      openTurn = null
+    }
+  }
+  // 尾部仍有未闭合 turn（崩溃/强杀现场）
+  if (openTurn !== null) {
+    found.push({ turn: openTurn, state: 'open' })
+  }
+  return found
+}
+
+/**
+ * 挂载退出前提示：在插件 dispose 时对「当前 attach 且有未闭合轮次」的会话
+ * 记录一条 warning（非阻断）。调用方（apply 的 ctx.effect 清理）负责在
+ * 退出/重载时触发。
+ *
+ * 不做客户端弹窗（非阻断提示由宿主 UI 在会话内呈现——本插件只负责检测与
+ * 日志；客户端时间线渲染未闭合轮次的提示属 UI 层，后续可扩展）。
+ * @param {object} ctx - cordis ctx。
+ * @param {(line: string) => void} log - 日志函数。
+ * @param {() => Array<object>} [sessionList] - 活跃会话列表（默认 ctx.sessions）。
+ */
+export function attachExitWarning(ctx, log, sessionList) {
+  return () => {
+    const sessions = typeof sessionList === 'function' ? sessionList() : ctx?.sessions
+    if (!sessions || typeof sessions !== 'object') return
+    const ids = typeof sessions.keys === 'function' ? [...sessions.keys()] : Object.keys(sessions)
+    for (const id of ids) {
+      const session = typeof sessions.get === 'function' ? sessions.get(id) : sessions[id]
+      if (!session) continue
+      const unclosed = unclosedTurns(session)
+      if (unclosed.length === 0) continue
+      const summary = unclosed.map((u) => `turn ${u.turn} (${u.state})`).join(', ')
+      log(`retrace-interrupt-guard: 会话 ${id} 存在未闭合轮次 ${summary}——中断未干净收尾，重启后可能触发旧光标回放；建议退出前先体检（dsh-log-contract check）`)
+    }
+  }
+}
+
+/**
+ * 在给定会话上运行检测（供 CLI/测试直接调用）。
+ * @param {object} session - 会话对象或 { events: [...] }。
+ * @returns {Array<{turn: number, state: string}>}
+ */
+export function detectUnclosed(session) {
+  return unclosedTurns(session)
+}

package/lib/prewrite-guard.js

@@ -32,6 +32,45 @@
  */
 import { editorError } from './host-core.js'
 
+/**
+ * 回档幅度阈值（快照点守卫，2026-08-31 c2d05ce9 事故闭环）。
+ *
+ * 业务语义（生产级运行保障，见 工程-生产级运行时/快照点与回档机制-设计-20260831.md）：
+ * - 一次编辑/撤回/重发遮蔽的 surface 节点占比 > 本阈值 = **回档请求**——
+ *   等于把生产基线大幅改写 → 拒绝落盘，引导从快照点创建官方分支；
+ * - 与 client 侧 SHADOW_SAFETY_RATIO（0.4）同源：UI 降级判定与写前拦截共用同一阈值；
+ * - 阈值可通过 createMarkerGuard({ rollbackRatio }) 覆盖（测试/未来配置）。
+ */
+export const ROLLBACK_RATIO = 0.4
+
+/**
+ * 短会话豁免阈值（2026-08-31 独立审查问题 B）：surface 节点 ≤ 6（≈ 3 轮）
+ * 的会话不做回档幅度拦截——否则 1-2 轮新会话编辑/撤回/重发 100% 被拒，
+ * 现有功能回归。事故防御针对大会话的「编辑早期消息遮蔽几十轮」，短会话无此风险。
+ */
+export const ROLLBACK_MIN_SURFACE = 6
+
+/**
+ * 该 marker 是否来自 rollback（restore op）——rollback 本身就是「从快照点
+ * 回档」的官方机制，不应再被回档幅度守卫拦截（否则大范围回档永远不可用，
+ * 且错误文案引导「打分支」而插件内无此操作 = 死路）。2026-08-31 独立审查问题 A。
+ */
+export function isRestoreMarker(envelope) {
+  const id = envelope?.data?.message?.id
+  return typeof id === 'string' && id.startsWith('retrace-restore-')
+}
+
+/** 计算一次 replace 的遮蔽占比（0..1）。无 surface/无 sourceEventSeqs/短会话 → 0（不拦截）。 */
+export function rollbackShareOf(session, envelope) {
+  if (!session || !envelope) return 0
+  const shadowed = Array.isArray(envelope.sourceEventSeqs) ? envelope.sourceEventSeqs.length : 0
+  if (shadowed <= 0) return 0
+  const surfaceNodes = session.surface?.nodes
+  const total = Array.isArray(surfaceNodes) ? surfaceNodes.length : 0
+  if (total <= ROLLBACK_MIN_SURFACE) return 0 // 短会话豁免（问题 B）
+  return shadowed / total
+}
+
 /** R2 —— T1 折叠自检：与 dsh-token-meter/_foldEvent 及 checks.js T1 同语义。 */
 export function tokenMeterFoldOk(events) {
   // 与 checks.js:372 同语义：无任何 step/start 的日志（极早期格式/简化夹具）
@@ -61,7 +100,7 @@ export function tokenMeterFoldOk(events) {
  * @param {(sessionId: string) => boolean} [options.enabled] 门控（默认恒 true）。
  * @returns {{ validateMarkerAppend(session, envelope): Promise<void> }}
  */
-export function createMarkerGuard({ log = () => {}, prewriterFactory, enabled = () => true } = {}) {
+export function createMarkerGuard({ log = () => {}, prewriterFactory, enabled = () => true, rollbackRatio = ROLLBACK_RATIO } = {}) {
   let factory = prewriterFactory ?? null
   return {
     /**
@@ -72,6 +111,27 @@ export function createMarkerGuard({ log = () => {}, prewriterFactory, enabled =
      */
     async validateMarkerAppend(session, envelope) {
       if (typeof enabled === 'function' && enabled(session?.id) === false) return { t1Ok: true }
+      // 快照点守卫（2026-08-31 c2d05ce9 事故闭环）：回档请求（遮蔽 > 阈值）
+      // 拒绝落盘——生产基线不支持原地大幅改写，引导从快照点创建官方分支。
+      // 在契约校验之前独立检查（业务规则，与合法性正交）；host 层强制，UI 绕过也拦。
+      // 豁免（2026-08-31 独立审查）：restore（rollback 回档本身合法）与短会话（≤3 轮）。
+      if (
+        envelope?.surfaceOp?.op === 'replace' &&
+        Array.isArray(envelope.sourceEventSeqs) &&
+        !isRestoreMarker(envelope)
+      ) {
+        const share = rollbackShareOf(session, envelope)
+        if (share > rollbackRatio) {
+          const pct = Math.round(share * 100)
+          log(
+            `retrace: rollback guard — replace shadows ${envelope.sourceEventSeqs.length}/${session?.surface?.nodes?.length ?? '?'} surface nodes (${pct}% > ${Math.round(rollbackRatio * 100)}%); refusing in-place rewrite; guide user to fork a branch from the snapshot point`,
+          )
+          throw editorError(
+            'rollback-guide',
+            `此操作将回档到较早的快照点（遮蔽 ${pct}% 的对话）。生产基线不支持原地大幅改写；请从快照点创建会话分支，在新分支中继续——原会话完整保留。`,
+          )
+        }
+      }
       if (factory === null) {
         try {
           factory = (await import('dsh-log-contract')).createPreWriter

package/package.json

@@ -1,10 +1,17 @@
 {
   "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.11",
+  "version": "0.4.12",
+  "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
+  "scripts": {
+    "build": "node scripts/generate-dynamic.mjs && node scripts/build-client.mjs",
+    "check": "node scripts/check-syntax.mjs && node scripts/check-dynamic.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm check && pnpm build && pnpm test"
+  },
   "exports": {
     ".": {
       "default": "./lib/index.js"
@@ -95,10 +102,5 @@
   },
   "bin": {
     "retrace": "bin/retrace.mjs"
-  },
-  "scripts": {
-    "build": "node scripts/generate-dynamic.mjs && node scripts/build-client.mjs",
-    "check": "node scripts/check-syntax.mjs && node scripts/check-dynamic.mjs",
-    "test": "vitest run"
   }
-}
+}