dsh-retrace 0.4.16 → 0.4.18

package/lib/adapter/contract.js

@@ -0,0 +1,48 @@
+/**
+ * dsh-retrace — lib/adapter/contract.js
+ *
+ * 适配器层契约(2026-09-01)——业务层与平台解耦的接口定义。
+ *
+ * 目标:换架构(不用 DSH)时,业务层(message-list.js/守卫)零改动,
+ * 只需实现新的「读事件 + 写替换」两个适配器。
+ *
+ * 三个角色:
+ * - 业务层:message-list.js(纯函数,零依赖)——消费「通用事件」,产出消息列表/遮蔽;
+ * - 适配器层(本文件):定义「事件读取器」和「替换写入器」两个接口;
+ * - 平台实现:dsh-adapter.js(DSH 实现)、未来 self-runtime-adapter.js 等。
+ *
+ * 通用事件格式(业务层消费的最小形态):
+ *   { seq, type, turn, data, source }——与具体平台的存储格式无关。
+ */
+
+/**
+ * 事件读取器接口:按 sessionId 提供「全量事件」(可靠事实,非内存视图)。
+ * @typedef {Object} EventReader
+ * @property {(sessionId: string) => Promise<Array<{seq:number, type:string, turn?:number, data?:object, source?:object}>>} readEvents
+ *   - 返回按 seq 升序的全量事件;
+ *   - 必须从持久化层读(文件/存储),不依赖运行内存(host 内存可能稀疏/窗口化);
+ *   - 失败返回 null/throw 由调用方 fallback。
+ */
+
+/**
+ * 替换写入器接口:在会话上写「遮蔽替换」(模型侧消费)。
+ * @typedef {Object} ReplaceWriter
+ * @property {(sessionId: string, span: {start:number, end:number, shadowedSeqs:number[]}) => Promise<object>} writeReplace
+ *   - 用平台机制写替换标记(DSH = session.append + surfaceOp replace);
+ *   - 返回写入结果(marker seq 等)。
+ */
+
+/**
+ * 组装一个「完整适配器」:读事件 + 写替换,业务层只依赖它。
+ * @param {EventReader} reader
+ * @param {ReplaceWriter} writer
+ */
+export function createAdapter(reader, writer) {
+  return { reader, writer }
+}
+
+/** 空适配器(无平台时,业务层可独立运行)。 */
+export const NULL_ADAPTER = createAdapter(
+  { readEvents: async () => null },
+  { writeReplace: async () => null },
+)

package/lib/adapter/dsh-writer.js

@@ -0,0 +1,230 @@
+/**
+ * dsh-retrace — lib/adapter/dsh-writer.js
+ *
+ * DSH 平台的「遮蔽写入器」（ReplaceWriter 的 DSH 实现）——把业务意图
+ * 「遮蔽这些消息」翻译成 DSH 事件形状。
+ *
+ * 抽象设计（工程-生产级运行时/编辑撤销分支跳过-消息列表投影抽象-设计-20260902.md）：
+ * 编辑/撤销/分支/跳过 = 通用消息列表投影操作，业务层只表达「遮蔽 roundRange」。
+ * **DSH 翻译成本全部隔离在本文件**：
+ * - 官方 token-meter 要求 assistant/message 必须有打开的 step（T1）→
+ *   marker 必须落在合法 turn/step 位置（三情形）：
+ *   ① 有打开的 step（回合中）→ 携带该 step 的 turn/step；
+ *   ② 无打开 step 但有打开着的 turn（回合内 step 间隙，1e99e1ff 现场）
+ *      → 该 turn 号 + 新 step 号（文件全量 max + 1，绕开窗口化内存）；
+ *   ③ 无打开 turn（真轮次间）→ 完整 turn 信封 + 推进 agent-loop lastTurn
+ *      （防重发/下一条消息复用同一 turn 号 = duplicate start）；
+ * - 客户端渲染层（复盘 2026-09-02）：任何 step/marker 不得写 turn:null
+ *   （D8 白屏死循环）、同 turn 内 step 不得复用（step key 冲突白屏）——
+ *   T3/T4 检测规则见 dsh-log-contract。
+ *
+ * host-core 零 import（动态插件 realm 可运行），本文件被 index.js 引用，
+ * 依赖方向 adapter → host-core（安全）；host-core 通过 hooks.writeMarker
+ * 注入本 writer，不反向 import。
+ */
+import { editorError, editorId, lastModelSource } from '../host-core.js'
+// 零 import 链（host-core 零 import）：本文件可被 generate-dynamic.mjs inline 进
+// dynamic-host（动态插件 realm 不能 import）。文件全量的 step 号（readMaxStep）
+// 由装配者注入；本文件自带内存 maxStepInTurn 兜底。
+
+/**
+ * 创建 DSH 遮蔽写入器。
+ * @param {object} deps
+ * @param {object} deps.agents      — agent 注册表（agents.get，情形③计数器推进）。
+ * @param {Function} [deps.validateMarker] — 写前校验钩子（prewrite-guard）。
+ * @param {(line: string) => void} [deps.log]
+ */
+export function createDshMarkerWriter({ agents, validateMarker, readMaxStep, log = () => {} } = {}) {
+  return {
+    /**
+     * 写入一个「遮蔽 marker」：业务意图（遮蔽 span）翻译成 DSH 事件形状。
+     * @param {object} session - DSH Session 实例。
+     * @param {{start:number, end:number, shadowedSeqs:number[]}} span - 遮蔽范围（业务层算好）。
+     * @param {{op:string, targetSeq:number, originalText:string}} meta - 业务元数据。
+     * @returns {Promise<object>} markerEvent（调用方读取 seq/editor 等）。
+     */
+    async writeMarker(session, span, meta) {
+      const op = String(meta?.op ?? '')
+      const targetSeq = Number(meta?.targetSeq)
+      const model = lastModelSource(session)
+      if (!model) {
+        throw editorError(
+          'no-model-header',
+          'This session has no model header yet; send at least one message before recalling or editing.',
+        )
+      }
+      const marker = {
+        id: editorId(op),
+        role: 'assistant',
+        content: [],
+        source: { kind: 'model', provider: model.provider, model: model.model },
+      }
+      // ── 三情形 turn/step 赋值（DSH 翻译核心，见文件头注释）──
+      const openStep = findOpenStep(session)
+      const openTurn = openStep === null ? findOpenTurn(session) : null
+      let markerTurn
+      let markerStep
+      let wrappedBefore = [] // marker 前的包裹事件（turn/start、step/start）
+      let wrappedAfter = [] // marker 后的包裹事件（step/end、turn/end）
+      if (openStep) {
+        markerTurn = openStep.turn
+        markerStep = openStep.step
+      } else if (openTurn) {
+        markerTurn = openTurn.turn
+        // 情形② step 号 = **max(内存, 文件) + 1**（独立审查 2026-09-02 处置）：
+        // - 内存 maxStepInTurn 覆盖本进程刚写的 marker（文件 flush 滞后时文件
+        //   读不到——同一打开 turn 内连续两次情形② 若只信文件会取到同一 step
+        //   → step key 冲突白屏）；
+        // - 文件全量 readMaxStep 覆盖窗口外既有 step（host 窗口化内存不可信，
+        //   算小会与窗口外冲突，复盘 2026-09-02 §五）；
+        // 两者取大 = 双向覆盖。readMaxStep 由装配者注入（index.js 从文件全量算），
+        // 动态路径（dynamic-host inline）未注入时仅内存覆盖（窗口外风险已文档化）。
+        let maxStep = maxStepInTurn(session, openTurn.turn)
+        if (typeof readMaxStep === 'function') {
+          const fromFile = await readMaxStep(session.id, openTurn.turn)
+          if (typeof fromFile === 'number' && Number.isSafeInteger(fromFile) && fromFile > maxStep) maxStep = fromFile
+        }
+        markerStep = maxStep + 1
+        wrappedBefore = [{ type: 'step/start', data: { turn: markerTurn, step: markerStep } }]
+        wrappedAfter = [{ type: 'step/end', data: { turn: markerTurn, step: markerStep } }]
+      } else {
+        markerTurn = nextTurnOf(session)
+        markerStep = 1
+        wrappedBefore = [
+          { type: 'turn/start', data: { turn: markerTurn } },
+          { type: 'step/start', data: { turn: markerTurn, step: 1 } },
+        ]
+        wrappedAfter = [
+          { type: 'step/end', data: { turn: markerTurn, step: 1 } },
+          // 官方契约（逐字镜像 dsh-agent-loop/lib/index.js:620）：turn/end 必须带
+          // reason.kind（completed|max-tokens|blocked|aborted|error|interrupted）——
+          // 缺失 = malformed → 官方 validation 拒绝 → 会话加载失败（1f4d986e 事故，
+          // 修复线 check-turn-end-reason.mjs 固化）。我们的信封 turn 立即完整关闭 →
+          // kind: 'completed'（与 agent-loop 正常完成一致）。
+          { type: 'turn/end', data: { turn: markerTurn, reason: { kind: 'completed' } } },
+        ]
+      }
+      const data = {
+        turn: markerTurn,
+        step: markerStep,
+        message: marker,
+        editor: {
+          targetSeq,
+          text: typeof meta?.originalText === 'string' ? meta.originalText.slice(0, 2000) : '',
+        },
+      }
+      const surfaceOp = { op: 'replace', start: span.start, end: span.end }
+      const sourceEventSeqs = Array.isArray(span.shadowedSeqs) ? span.shadowedSeqs.slice() : []
+      // 2026-09-01：把遮蔽 seq 冗余进 data.shadowedSeqs——部分客户端事件管道会剥离
+      // event 顶层 sourceEventSeqs（0.4.12 实测：撤回/编辑后消息不隐藏 = client 拿不到
+      // shadowedSeqs）。data 里的字段随事件体持久化，client 读 data 更稳（fallback 顶层）。
+      data.shadowedSeqs = sourceEventSeqs
+      // 包裹事件**先于校验构建**（校验与落盘共用同一组事件），校验钩子拿到完整序列
+      // （wrappedBefore + envelope + wrappedAfter）做 T1 自检——消除"自检只见裸信封 →
+      // 恒报 markerT1Broken"的误报（0.4.12-0.4.16 每次轮次间编辑刷 31 行日志的根因）。
+      if (typeof validateMarker === 'function') {
+        const result = await validateMarker(
+          session,
+          { type: 'assistant/message', data, surfaceOp, sourceEventSeqs },
+          { wrappedBefore, wrappedAfter },
+        )
+        if (result && result.t1Ok === false) {
+          // 理论上三情形信封后 T1 恒通过；残留 fallback 标注（防御）。
+          data.editor.markerT1Broken = true
+        }
+      }
+      for (const w of wrappedBefore) session.append(w.type, w.data)
+      const markerEvent = session.append('assistant/message', data, { surfaceOp, sourceEventSeqs })
+      for (const w of wrappedAfter) session.append(w.type, w.data)
+      // 情形③：我们消费了 nextTurn（信封里的 turn/start），把 agent-loop 的 lastTurn
+      // 推进到该 turn——重发/下一条消息才落到 nextTurn+1，不会复用（防 duplicate start）。
+      if (wrappedBefore.length >= 2) {
+        const agent = agents?.get?.(session.id)
+        advanceLoopTurn(agent, markerTurn, log)
+      }
+      return markerEvent
+    },
+  }
+}
+
+/**
+ * 找当前打开的 step（最近一次未闭合的 step/start 的 turn/step）。
+ * 扫描 session.events：step/start 开、step/end 关；末尾仍开即返回。
+ * 无打开 step 返回 null（轮次间编辑）。
+ */
+export function findOpenStep(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  let open = null
+  for (const event of events) {
+    if (event?.type === 'step/start') {
+      open = { turn: event.data?.turn, step: event.data?.step }
+    } else if (event?.type === 'step/end') {
+      open = null
+    }
+  }
+  return open
+}
+
+/**
+ * 找当前打开着的 turn（最近一次 turn/start 无配对 turn/end）。
+ * 扫描 session.events：turn/start 开、turn/end 关；末尾仍开即返回。
+ * 无打开 turn 返回 null（真轮次间，情形③）。
+ */
+export function findOpenTurn(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  let open = null
+  for (const event of events) {
+    if (event?.type === 'turn/start') {
+      open = { turn: event.data?.turn }
+    } else if (event?.type === 'turn/end') {
+      open = null
+    }
+  }
+  return open
+}
+
+/** 某 turn 内已出现的最大 step 号（无 step 返回 0）。内存扫描（窗口化不可信时用文件版）。 */
+export function maxStepInTurn(session, turn) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  let max = 0
+  for (const event of events) {
+    if (event?.data?.turn !== turn) continue
+    const step = event?.data?.step
+    if (typeof step === 'number' && Number.isSafeInteger(step) && step > max) max = step
+  }
+  return max
+}
+
+/**
+ * 下一个 turn 号：scan 最大 turn（turn/start、step/start、assistant/message、user/message
+ * 的 data.turn 中取最大）+1。无任何 turn 时从 1 起。
+ */
+export function nextTurnOf(session) {
+  const events = Array.isArray(session?.events) ? session.events : []
+  let max = 0
+  for (const event of events) {
+    const t = event?.data?.turn
+    if (typeof t === 'number' && Number.isSafeInteger(t) && t > max) max = t
+  }
+  return max + 1
+}
+
+/**
+ * 推进 agent-loop 的 turn 计数器（情形③专用）。
+ * 仅在 loop 处于 idle 且 lastTurn+1 === consumedTurn 时推进——守卫防误伤
+ * （loop 已推进/文件被外部改号时跳过；信封的 turn/start 已让文件 max turn 前移，
+ * 跨重启自愈，这里只补同一 loop 实例的内存计数器）。
+ */
+function advanceLoopTurn(agent, consumedTurn, log = () => {}) {
+  if (!agent || typeof agent !== 'object') return
+  const phase = agent.phase
+  if (!phase || phase.kind !== 'idle') {
+    log(`retrace: advanceLoopTurn skipped — agent not idle (${phase?.kind ?? 'no-phase'})`)
+    return
+  }
+  if (!Number.isSafeInteger(phase.lastTurn) || phase.lastTurn + 1 !== consumedTurn) {
+    log(`retrace: advanceLoopTurn skipped — lastTurn ${phase?.lastTurn} +1 !== consumed ${consumedTurn}`)
+    return
+  }
+  phase.lastTurn = consumedTurn
+}

package/lib/adapter/dsh.js

@@ -0,0 +1,118 @@
+/**
+ * dsh-retrace — lib/adapter/dsh.js
+ *
+ * DSH 平台适配器(2026-09-01)——实现 EventReader 接口。
+ *
+ * 职责:从 DSH 会话文件(session.jsonl.zstd)读全量事件——可靠事实,
+ * 不依赖 host 内存视图(DSH 2.0.3 host 的 session.events 可能稀疏/窗口化)。
+ *
+ * 换架构时:业务层(message-list.js/守卫)零改动,新平台实现自己的 EventReader
+ * (读自己的日志格式 → 同样的通用事件结构)。
+ */
+import { readdirSync, accessSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+/** 找 DSH 会话文件路径(遍历 ~/.dsh/sessions 各工作区)。 */
+export function sessionFilePath(sessionId) {
+  const root = join(homedir(), '.dsh', 'sessions')
+  for (const workspace of readdirSync(root)) {
+    const candidate = join(root, workspace, String(sessionId), 'session.jsonl.zstd')
+    try { accessSync(candidate); return candidate } catch { /* keep looking */ }
+  }
+  return null
+}
+
+/** 是否是真实的用户输入(轮边界)——排除 context/steering 注入。 */
+export function isRoundBoundary(event) {
+  return event?.type === 'user/message' && event?.data?.source?.kind === 'user'
+}
+
+/**
+ * DSH 事件读取器:从文件读全量事件(通用事件结构)。
+ * @returns {Promise<Array<{seq:number, type:string, turn?:number, data?:object, source?:object}>|null>}
+ */
+async function readEvents(sessionId) {
+  const filePath = sessionFilePath(sessionId)
+  return readEventsFromFile(filePath)
+}
+
+/** 从指定文件路径读全量事件(测试可注入路径;生产走 readEvents 找 ~/.dsh)。 */
+async function readEventsFromFile(filePath) {
+  try {
+    if (!filePath) return null
+    const { loadSessionLog } = await import('dsh-log-contract')
+    const log = loadSessionLog(filePath)
+    return log.events.map((r) => r.event)
+  } catch { return null }
+}
+
+/**
+ * 从全量事件计算遮蔽范围(业务逻辑,基于通用事件,与 DSH 无关)。
+ * @param {Array} events - 全量事件(通用格式)。
+ * @param {number|string} target - seq 或 messageId。
+ * @param {'round'|'tail'} [mode] - round=遮蔽目标轮;tail=遮蔽目标之后(编辑 fromScratch)。
+ */
+export function computeSpan(events, target, mode = 'round') {
+  if (!Array.isArray(events)) return null
+  let seq = typeof target === 'number' ? target : -1
+  if (seq === -1) {
+    for (let i = events.length - 1; i >= 0; i--) {
+      const ev = events[i]
+      const id = ev?.type === 'user/message' ? ev.data?.id : ev?.type === 'assistant/message' ? ev.data?.message?.id : undefined
+      if (typeof id === 'string' && id === target) { seq = ev.seq; break }
+    }
+  }
+  if (seq === -1 || !events[seq]) return null
+  // surface 节点 = user/assistant/tool 消息(近似 surface 节点,与官方 foldSurface 一致)
+  const nodes = []
+  for (const ev of events) {
+    if (ev && (ev.type === 'user/message' || ev.type === 'assistant/message' || ev.type === 'tool/result')) nodes.push(ev.seq)
+  }
+  if (mode === 'tail') {
+    const shadowedSeqs = nodes.filter((s) => s >= seq)
+    if (shadowedSeqs.length === 0) return null
+    return { start: shadowedSeqs[0], end: shadowedSeqs[shadowedSeqs.length - 1], shadowedSeqs }
+  }
+  const index = nodes.indexOf(seq)
+  if (index === -1) return null
+  let startIdx = index
+  for (let i = index; i >= 0; i--) { if (isRoundBoundary(events[nodes[i]])) { startIdx = i; break } }
+  let endIdx = nodes.length - 1
+  for (let i = startIdx + 1; i < nodes.length; i++) { if (isRoundBoundary(events[nodes[i]])) { endIdx = i - 1; break } }
+  const span = nodes.slice(startIdx, endIdx + 1)
+  if (span.length === 0) return null
+  return { start: span[0], end: span[span.length - 1], shadowedSeqs: span }
+}
+
+/**
+ * DSH 适配器:EventReader 实现。
+ * 从文件读全量事件(可靠事实),并提供基于它的遮蔽计算。
+ */
+export const dshAdapter = {
+  reader: { readEvents },
+  /** 便捷:读事件 + 算遮蔽一步到位(供 index.js/http.js 注入 args.span)。 */
+  async spanFromFile(sessionId, target, mode = 'round') {
+    const events = await readEvents(sessionId)
+    return computeSpan(events, target, mode)
+  },
+  /**
+   * 从文件全量事件算某 turn 内的最大 step 号(情形② marker step 分配用)。
+   * 绕开 host 窗口化 session.events(稀疏内存视图可能看不到 turn 内全部 step,
+   * 算小 → 新 step 号与窗口外既有 step 冲突 = step key 冲突白屏,1e99e1ff 复盘)。
+   * 失败返回 null(调用方 fallback 内存扫描)。
+   * @param {string} [filePath] 可选:直接指定会话文件路径(测试注入)。
+   */
+  async maxStepInTurnFromFile(sessionId, turn, filePath) {
+    const events = filePath ? await readEventsFromFile(filePath) : await readEvents(sessionId)
+    if (!Array.isArray(events)) return null
+    let max = 0
+    for (const ev of events) {
+      if (ev?.type === 'step/start' && ev.data?.turn === turn) {
+        const step = ev.data?.step
+        if (typeof step === 'number' && Number.isSafeInteger(step) && step > max) max = step
+      }
+    }
+    return max
+  },
+}

package/lib/client.bundle.js

@@ -179,7 +179,9 @@ var zh = {
   "fork.lineageRoot": "\u6839\u4F1A\u8BDD",
   "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"
+  "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"
 };
 var en = {
   "action.edit": "Edit",
@@ -275,7 +277,9 @@ var en = {
   "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)."
+  "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):"
 };
 var SURFACE_TYPES = /* @__PURE__ */ new Set(["user/message", "assistant/message", "tool/result"]);
 function isReplacementSurfaceEvent(event) {
@@ -1134,6 +1138,7 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   const [gitBusy, setGitBusy] = (0, import_react.useState)(false);
   const [preview, setPreview] = (0, import_react.useState)(null);
   const [previewScope, setPreviewScope] = (0, import_react.useState)("both");
+  const [badge, setBadge] = (0, import_react.useState)("");
   const [rollbackBusy, setRollbackBusy] = (0, import_react.useState)(false);
   const [scrollTop, setScrollTop] = (0, import_react.useState)(0);
   const [doctor, setDoctor] = (0, import_react.useState)(null);
@@ -1157,6 +1162,14 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
     if (projected === void 0) refresh();
     refreshGit();
     timelineGet(`/doctor?sessionId=${encodeURIComponent(sessionId)}`).then((result) => setDoctor(result?.ok === true ? result.value : null)).catch(() => setDoctor(null));
+    callOp("setBadgeTitle", { sessionId }).catch(() => {
+    });
+    callOp("sessionBadge", { sessionId }).then((result) => {
+      if (result && result.ok === true && typeof result.value?.badge === "string") {
+        setBadge(result.value.badge);
+      }
+    }).catch(() => {
+    });
   }, []);
   const jump = (boundarySeq) => jumpToAnchor(store, boundarySeq);
   const requestPreview = (record) => {
@@ -1200,6 +1213,8 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   return (0, import_react.createElement)("div", { className: "dsh-rt-view" }, [
     (0, import_react.createElement)("div", { key: "head", className: "dsh-rt-timeline-head" }, [
       (0, import_react.createElement)("span", { key: "title", className: "dsh-rt-timeline-title" }, t("timeline.title")),
+      // 会话铭牌（2026-09-01）：所有界面统一展示短码，沟通任务用
+      sessionId && (0, import_react.createElement)("code", { key: "badge", className: "dsh-rt-fork-badge-code", title: t("fork.badgeHint") }, `[${badge}]`),
       (0, import_react.createElement)("button", {
         key: "refresh",
         type: "button",
@@ -1326,6 +1341,7 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
   const [error, setError] = (0, import_react.useState)(null);
   const [scrollTop, setScrollTop] = (0, import_react.useState)(0);
   const [lineage, setLineage] = (0, import_react.useState)(null);
+  const [badge, setBadge] = (0, import_react.useState)("");
   const projected = typeof useProjection === "function" ? useProjection("retrace/forkmap") : void 0;
   const versions = typeof useProjection === "function" ? useProjection("retrace/versions") : void 0;
   const markerBySeq = new Map((versions?.versions ?? []).map((v) => [v.boundarySeq, v.markerText]));
@@ -1346,6 +1362,30 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
       if (result && result.ok === true && Array.isArray(result.value)) setLineage(result.value);
     }).catch(() => {
     });
+    callOp("sessionBadge", { sessionId }).then((result) => {
+      if (result && result.ok === true && typeof result.value?.badge === "string") {
+        setBadge(result.value.badge);
+        if (store && typeof store.rename === "function") {
+          const current = typeof store.getTitle === "function" ? store.getTitle() : null;
+          const base = typeof current === "string" && current.trim() ? current : sessionId.slice(0, 16);
+          const tagged = `[${result.value.badge}] ${base.replace(/^\[[a-z0-9]{6,}\]\s*/, "")}`;
+          store.rename(tagged).catch(() => callOp("setBadgeTitle", { sessionId }).catch(() => {
+          }));
+        } else {
+          callOp("setBadgeTitle", { sessionId }).catch(() => {
+          });
+        }
+      } else {
+        callOp("setBadgeTitle", { sessionId }).catch(() => {
+        });
+      }
+    }).catch(() => {
+    });
+    if (!window.__dshRetraceBadgeInit) {
+      window.__dshRetraceBadgeInit = true;
+      callOp("initBadgeTitles", {}).catch(() => {
+      });
+    }
   }, []);
   const nodes = fork?.nodes ?? [];
   const boundaries = fork?.boundaries ?? [];
@@ -1373,8 +1413,27 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
     // 会话铭牌（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)
+      (0, import_react.createElement)("code", { key: "code", className: "dsh-rt-fork-badge-code" }, `[${badge}]`),
+      (0, import_react.createElement)("span", { key: "id", className: "dsh-rt-fork-badge-id" }, sessionId),
+      // 编辑名称（2026-09-01）：用户可自定义会话名，自动拼短码 + 固定（停自动改名）
+      (0, import_react.createElement)("button", {
+        key: "rename",
+        type: "button",
+        className: "dsh-rt-chip",
+        onClick: () => {
+          const name2 = window.prompt(t("fork.renamePrompt"), "");
+          if (name2 && name2.trim()) {
+            const tagged = `[${badge}] ${name2.trim()}`;
+            if (store && typeof store.rename === "function") {
+              store.rename(tagged).catch(() => callOp("setUserTitle", { sessionId, title: name2.trim() }).catch(() => {
+              }));
+            } else {
+              callOp("setUserTitle", { sessionId, title: name2.trim() }).catch(() => {
+              });
+            }
+          }
+        }
+      }, t("fork.rename"))
     ]),
     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")),

package/lib/client.js

@@ -151,6 +151,8 @@ const zh = {
   'fork.lineageEmpty': '本会话没有父会话（独立根会话）。',
   'fork.badge': '会话短码',
   'fork.badgeHint': '短码由会话唯一 id 确定性导出，永不变（标题会变）。',
+  'fork.rename': '改名称',
+  'fork.renamePrompt': '输入会话名称（自动拼接短码，设置后固定不再自动改名）：',
 }
 /** English dictionary, checked complete against the zh key set. */
 const en = {
@@ -248,6 +250,8 @@ const en = {
   '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).',
+  'fork.rename': 'Rename',
+  'fork.renamePrompt': 'Enter a session name (badge is prefixed automatically; the title is then pinned, no auto-rename):',
 }
 
 // ---------------------------------------------------------------------------
@@ -1428,6 +1432,9 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   const [gitBusy, setGitBusy] = useState(false)
   const [preview, setPreview] = useState(null)
   const [previewScope, setPreviewScope] = useState('both')
+  // 语义短码（2026-09-01）：默认空,异步从 host 短码表拿（工作区+序号语义）。
+  // 不用 FNV 兜底显示——修复线规则是 op065op016 这类语义码,不是随机 hash。
+  const [badge, setBadge] = useState('')
   const [rollbackBusy, setRollbackBusy] = useState(false)
   const [scrollTop, setScrollTop] = useState(0)
   const [doctor, setDoctor] = useState(null)
@@ -1467,6 +1474,14 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
     timelineGet(`/doctor?sessionId=${encodeURIComponent(sessionId)}`)
       .then((result) => setDoctor(result?.ok === true ? result.value : null))
       .catch(() => setDoctor(null))
+    // 写入短码 title（一次：如果标题已含短码则跳过）
+    callOp('setBadgeTitle', { sessionId }).catch(() => {})
+    // 语义短码（2026-09-01）：host 短码表优先（工作区+序号），FNV 兜底
+    callOp('sessionBadge', { sessionId }).then((result) => {
+      if (result && result.ok === true && typeof result.value?.badge === 'string') {
+        setBadge(result.value.badge)
+      }
+    }).catch(() => {})
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
@@ -1529,6 +1544,8 @@ function RetraceView({ sessionId, useProjection, t, actions, store }) {
   return createElement('div', { className: 'dsh-rt-view' }, [
     createElement('div', { key: 'head', className: 'dsh-rt-timeline-head' }, [
       createElement('span', { key: 'title', className: 'dsh-rt-timeline-title' }, t('timeline.title')),
+      // 会话铭牌（2026-09-01）：所有界面统一展示短码，沟通任务用
+      sessionId && createElement('code', { key: 'badge', className: 'dsh-rt-fork-badge-code', title: t('fork.badgeHint') }, `[${badge}]`),
       createElement('button', {
         key: 'refresh',
         type: 'button',
@@ -1679,6 +1696,9 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
   const [error, setError] = useState(null)
   const [scrollTop, setScrollTop] = useState(0)
   const [lineage, setLineage] = useState(null)
+  // 语义短码（2026-09-01）：默认空,异步从 host 短码表拿（工作区+序号语义）。
+  // 不用 FNV 兜底显示——修复线规则是 op065op016 这类语义码,不是随机 hash。
+  const [badge, setBadge] = useState('')
 
   // Live push-frame path (projection standard kit) — falls back to HTTP.
   const projected = typeof useProjection === 'function' ? useProjection('retrace/forkmap') : undefined
@@ -1712,6 +1732,29 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
         if (result && result.ok === true && Array.isArray(result.value)) setLineage(result.value)
       })
       .catch(() => { /* lineage is a best-effort enrichment */ })
+    // 语义短码（2026-09-01）：host 短码表优先（工作区+序号），FNV 兜底
+    callOp('sessionBadge', { sessionId }).then((result) => {
+      if (result && result.ok === true && typeof result.value?.badge === 'string') {
+        setBadge(result.value.badge)
+        // 用官方 rename 更新 title（投影立即刷新，侧边栏/标题栏显示 [短码] 名称）
+        // rename 会写 user source title → 停自动改名。若 rename 不可用，fallback host setBadgeTitle。
+        if (store && typeof store.rename === 'function') {
+          const current = typeof store.getTitle === 'function' ? store.getTitle() : null
+          const base = (typeof current === 'string' && current.trim()) ? current : sessionId.slice(0, 16)
+          const tagged = `[${result.value.badge}] ${base.replace(/^\[[a-z0-9]{6,}\]\s*/, '')}`
+          store.rename(tagged).catch(() => callOp('setBadgeTitle', { sessionId }).catch(() => {}))
+        } else {
+          callOp('setBadgeTitle', { sessionId }).catch(() => {})
+        }
+      } else {
+        callOp('setBadgeTitle', { sessionId }).catch(() => {})
+      }
+    }).catch(() => {})
+    // 批量初始化所有会话标题短码（只跑一次，会话列表侧边栏直接显示）
+    if (!window.__dshRetraceBadgeInit) {
+      window.__dshRetraceBadgeInit = true
+      callOp('initBadgeTitles', {}).catch(() => {})
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
@@ -1757,8 +1800,25 @@ function ForkView({ sessionId, useProjection, t, actions, store }) {
     // 会话铭牌（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('code', { key: 'code', className: 'dsh-rt-fork-badge-code' }, `[${badge}]`),
       createElement('span', { key: 'id', className: 'dsh-rt-fork-badge-id' }, sessionId),
+      // 编辑名称（2026-09-01）：用户可自定义会话名，自动拼短码 + 固定（停自动改名）
+      createElement('button', {
+        key: 'rename',
+        type: 'button',
+        className: 'dsh-rt-chip',
+        onClick: () => {
+          const name = window.prompt(t('fork.renamePrompt'), '')
+          if (name && name.trim()) {
+            const tagged = `[${badge}] ${name.trim()}`
+            if (store && typeof store.rename === 'function') {
+              store.rename(tagged).catch(() => callOp('setUserTitle', { sessionId, title: name.trim() }).catch(() => {}))
+            } else {
+              callOp('setUserTitle', { sessionId, title: name.trim() }).catch(() => {})
+            }
+          }
+        },
+      }, t('fork.rename')),
     ]),
 
     Array.isArray(lineage) && lineage.length > 1 && createElement('div', { key: 'lineage', className: 'dsh-rt-fork-lineage' }, [