dsh-recall-plugin 1.7.1 → 2.1.0

package/lib/maintenance.js

@@ -1,145 +1,263 @@
-/**
- * dsh-recall-plugin — 快照维护（ctx 绑定的工厂，无模块级副作用）
- *
- * 职责：磁盘占用治理，两件事——
- * 1. 定期 git gc：全量保留策略下把 loose 对象压 pack + 跨版本 delta，
- *    无损（所有 tag 可达对象一个不丢），通常省一半以上空间；
- * 2. 会话删除联动清理：会话日志已从磁盘消失时，删除该会话全部快照 tag
- *    并重写索引，空间由紧随的同一次 gc --prune=now 真正释放。
- *
- * 触发点在每条用户消息快照之后的同一条串行队列里（见 index.js 的事件
- * 接线），因此 gc/清理与快照天然互斥，不存在 git 锁竞态。
- */
-
-// gc 节流阈值来自 config 域（设置页「插件配置」卡片可实时改写 cfg，
-// 因此这里按调用时取值而不是工厂创建时快照；环境变量
-// DSH_RECALL_GC_SNAPS/GC_HOURS 仍最高优先，见 config.js）：
-// 每 gcSnaps 条快照或距上次 gc gcHours 小时，先到先触发。默认「50 条或
-// 24 小时」——重活（gc）一天至多一次的量级，轻会话用户也不会等太久。
-export function createMaintenance(ctx, rt, snaps, config) {
-  const sessions = ctx.sessions
-  const state = rt.state
-  // 平台选择的脚本模板（gc/purge 两套模板同名导出）
-  const S = rt.scripts
-
-  // 删除一个会话的全部快照：按 root 分组（同一会话可能换过工作目录），
-  // tag 分块删除规避命令行长度上限，索引重写交给 snaps.saveIndex。
-  // best-effort：单块失败只记日志，剩余块继续；tag 残留由下次清理幂等收尾。
-  async function purgeSession(sessionId) {
-    const byRoot = new Map()
-    for (const [id, s] of state.snapshots.entries()) {
-      if (!s || s.sessionId !== sessionId) continue
-      if (!byRoot.has(s.root)) byRoot.set(s.root, [])
-      byRoot.get(s.root).push(id)
-    }
-    let purged = 0
-    for (const [root, ids] of byRoot) {
-      let store = state.stores.get(root)
-      if (!store) {
-        // 冷启动时 store 缓存可能还没建：现场解析一次而不是直接跳过——
-        // 跳过会让该 root 的快照永远清不掉（sweep 每轮都 miss）
-        try { store = await rt.resolveStore(root) } catch (error) { store = null }
-      }
-      if (!store || !state.gitExe) continue
-      try {
-        for (let i = 0; i < ids.length; i += 100) {
-          await rt.runShell(S.purgeTagsScript(store, state.gitExe, ids.slice(i, i + 100).map((id) => 'snap-' + id)), { timeoutMs: 120000, stdoutMaxBytes: 4096 })
-        }
-        for (const id of ids) state.snapshots.delete(id)
-        await snaps.saveIndex(root, sessionId)
-        purged += ids.length
-      } catch (error) {
-        rt.recordError('recall purge session failed: ' + String(error))
-      }
-    }
-    if (purged > 0) console.error('recall purged snapshots of deleted session:', sessionId, purged)
-    return purged
-  }
-
-  // 扫描索引里出现过的全部会话：既不在 sessions 注册表、冷读日志又失败的，
-  // 才认定「已删除」。两个保守闸门：
-  // - sessionQuery 服务不存在时整体跳过——没有冷读能力就无法区分
-  //   「已删除」和「只是冷着」，误删快照不可逆，宁可不清理；
-  // - 归档会话（撤回功能自己归档的）日志仍在磁盘上，readSession 仍成功，
-  //   不会被误清——只有日志真正消失才触发。
-  async function sweepDeletedSessions() {
-    const ids = new Set()
-    for (const s of state.snapshots.values()) {
-      if (s && s.sessionId) ids.add(s.sessionId)
-    }
-    if (!ids.size) return
-    const query = ctx.get('sessionQuery')
-    if (!query || typeof query.readSession !== 'function') return
-    for (const id of ids) {
-      if (sessions.get(id)) continue
-      let alive = false
-      try {
-        const log = await query.readSession(id)
-        alive = Boolean(log)
-      } catch (error) {
-        alive = false
-      }
-      if (!alive) await purgeSession(id)
-    }
-  }
-
-  // 维护核心（节流判定 + 清理 + gc）：force 供设置页「立即 gc」手动触发，
-  // 跳过阈值检查但仍走同一条串行队列调用方——与快照天然互斥的约束不变。
-  // 失败也推进 gcLastAt：gc 失败往往是环境性的（磁盘/杀软），不推进时间戳
-  // 会让后续每条消息都重试一次重量级 gc，把队列堵住。
-  async function runGc(sessionId, force) {
-    const root = await rt.resolveRoot(sessionId)
-    if (!root) return false
-    const store = state.stores.get(root)
-    if (!store || !state.gitExe) return false
-    const now = Date.now()
-    const last = state.gcLastAt.get(store.git) || 0
-    const count = (state.gcCount.get(store.git) || 0) + 1
-    state.gcCount.set(store.git, count)
-    if (!force && count < config.gcSnaps && now - last < config.gcHours * 3600000) return false
-    state.gcCount.set(store.git, 0)
-    try {
-      await sweepDeletedSessions()
-      await rt.runShell(S.gcScript(store, state.gitExe), { timeoutMs: 600000, stdoutMaxBytes: 4096 })
-    } catch (error) {
-      rt.recordError('recall maintenance failed: ' + String(error))
-    }
-    state.gcLastAt.set(store.git, Date.now())
-    return true
-  }
-
-  // 全局 gc（设置卡片没有会话上下文）：清理扫描一次 + 逐 store gc。
-  // store 全集取内存缓存（启动预热与历次操作会填齐已知工作区）；逐个
-  // best-effort，单个失败记错误继续。调用方（manage 端点）把它排进同一条
-  // 串行队列，与快照天然互斥，无 git 锁竞态。
-  async function runGcAll() {
-    const stores = Array.from(new Set(Array.from(state.stores.values()).filter(Boolean)))
-    if (!stores.length || !state.gitExe) return false
-    try {
-      await sweepDeletedSessions()
-    } catch (error) {
-      rt.recordError('recall sweep failed: ' + String(error))
-    }
-    let done = 0
-    for (const store of stores) {
-      try {
-        await rt.runShell(S.gcScript(store, state.gitExe), { timeoutMs: 600000, stdoutMaxBytes: 4096 })
-        done++
-      } catch (error) {
-        rt.recordError('recall gc failed for ' + (store && store.git) + ': ' + String(error))
-      }
-      state.gcLastAt.set(store.git, Date.now())
-      state.gcCount.set(store.git, 0)
-    }
-    return true
-  }
-
-  // 每条消息快照后串行调用（见 index.js 事件接线）
-  async function maybeMaintain(sessionId) {
-    await runGc(sessionId, false)
-  }
-
-  // 模块收敛：只导出被装配层消费的入口；sweepDeletedSessions /
-  // purgeSession 是 gc 的内部步骤，不对外暴露面
-  return { maybeMaintain, runGc, runGcAll }
-}
+/**
+ * dsh-recall-plugin — 快照维护（ctx 绑定的工厂，无模块级副作用）
+ *
+ * 职责：磁盘占用治理，两件事——
+ * 1. 定期 git gc：全量保留策略下把 loose 对象压 pack + 跨版本 delta，
+ *    无损（所有 tag 可达对象一个不丢），通常省一半以上空间；
+ * 2. 会话删除联动清理：会话日志已从磁盘消失时，删除该会话全部快照 tag
+ *    并重写索引，空间由紧随的同一次 gc --prune=now 真正释放。
+ *
+ * 触发点在每条用户消息快照之后的同一条串行队列里（见 index.js 的事件
+ * 接线），因此 gc/清理与快照天然互斥，不存在 git 锁竞态。
+ */
+
+// gc 节流阈值来自 config 域（设置页「插件配置」卡片可实时改写 cfg，
+// 因此这里按调用时取值而不是工厂创建时快照；环境变量
+// DSH_RECALL_GC_SNAPS/GC_HOURS 仍最高优先，见 config.js）：
+// 每 gcSnaps 条快照或距上次 gc gcHours 小时，先到先触发。默认「50 条或
+// 24 小时」——重活（gc）一天至多一次的量级，轻会话用户也不会等太久。
+
+// P1-3 纯逻辑：按 root 分组选出超限部分的最旧快照（time 升序，time=0 孤儿
+// 最旧优先），模块级导出供 tests/unit 直接钉边界；工厂内 enforceLimits 复用。
+export function selectOverLimitVictims(snapshots, limit) {
+  if (!limit || limit <= 0) return new Map() // 0 或负值 = 不限制
+  const byRoot = new Map()
+  for (const [id, s] of snapshots.entries()) {
+    if (!s || !s.root) continue
+    if (!byRoot.has(s.root)) byRoot.set(s.root, [])
+    byRoot.get(s.root).push({ id, time: s.time })
+  }
+  const victims = new Map()
+  for (const [root, list] of byRoot) {
+    if (list.length <= limit) continue
+    const excess = list.length - limit
+    // 按时间升序排：time=0 最旧，优先清；同时间保插入序（先入先出）
+    list.sort((a, b) => (a.time || 0) - (b.time || 0))
+    victims.set(root, list.slice(0, excess))
+  }
+  return victims
+}
+
+// S2-3 按时间保留的纯逻辑：retentionDays <= 0 不启用；按 root 分组，
+// 命中「time > 0 且早于 cutoff」的入选（time=0 孤儿视为最旧，一并最先
+// 清——与 selectOverLimitVictims 同构）。模块级导出供单测钉边界。
+export function selectExpiredVictims(snapshots, retentionDays, now) {
+  if (!retentionDays || retentionDays <= 0) return new Map()
+  const cutoff = (typeof now === 'number' ? now : Date.now()) - retentionDays * 86400000
+  const byRoot = new Map()
+  for (const [id, s] of snapshots.entries()) {
+    if (!s || !s.root) continue
+    // time=0 孤儿（rebuildOrphans 重建）无真实时间，视为最旧列入
+    if (s.time > 0 && s.time >= cutoff) continue
+    if (!byRoot.has(s.root)) byRoot.set(s.root, [])
+    byRoot.get(s.root).push({ id, time: s.time })
+  }
+  return byRoot
+}
+
+export function createMaintenance(ctx, rt, snaps, config) {
+  const sessions = ctx.sessions
+  const state = rt.state
+  // 平台选择的脚本模板（gc/purge 两套模板同名导出）
+  const S = rt.scripts
+
+  // 删除一个会话的全部快照：按 root 分组（同一会话可能换过工作目录），
+  // tag 分块删除规避命令行长度上限，索引重写交给 snaps.saveIndex。
+  // best-effort：单块失败只记日志，剩余块继续；tag 残留由下次清理幂等收尾。
+  async function purgeSession(sessionId) {
+    const byRoot = new Map()
+    for (const [id, s] of state.snapshots.entries()) {
+      if (!s || s.sessionId !== sessionId) continue
+      if (!byRoot.has(s.root)) byRoot.set(s.root, [])
+      byRoot.get(s.root).push(id)
+    }
+    let purged = 0
+    for (const [root, ids] of byRoot) {
+      let store = state.stores.get(root)
+      if (!store) {
+        // 冷启动时 store 缓存可能还没建：现场解析一次而不是直接跳过——
+        // 跳过会让该 root 的快照永远清不掉（sweep 每轮都 miss）
+        try { store = await rt.resolveStore(root) } catch (error) { store = null }
+      }
+      if (!store || !state.gitExe) continue
+      try {
+        for (let i = 0; i < ids.length; i += 100) {
+          await rt.runShell(S.purgeTagsScript(store, state.gitExe, ids.slice(i, i + 100).map((id) => 'snap-' + id)), { timeoutMs: 120000, stdoutMaxBytes: 4096 })
+        }
+        for (const id of ids) state.snapshots.delete(id)
+        await snaps.saveIndex(root, sessionId)
+        purged += ids.length
+      } catch (error) {
+        rt.recordError('recall purge session failed: ' + String(error))
+      }
+    }
+    if (purged > 0) console.error('recall purged snapshots of deleted session:', sessionId, purged)
+    return purged
+  }
+
+  // 扫描索引里出现过的全部会话：既不在 sessions 注册表、冷读日志又失败的，
+  // 才认定「已删除」。两个保守闸门：
+  // - sessionQuery 服务不存在时整体跳过——没有冷读能力就无法区分
+  //   「已删除」和「只是冷着」，误删快照不可逆，宁可不清理；
+  // - 归档会话（撤回功能自己归档的）日志仍在磁盘上，readSession 仍成功，
+  //   不会被误清——只有日志真正消失才触发。
+  async function sweepDeletedSessions() {
+    const ids = new Set()
+    for (const s of state.snapshots.values()) {
+      if (s && s.sessionId) ids.add(s.sessionId)
+    }
+    if (!ids.size) return
+    const query = ctx.get('sessionQuery')
+    if (!query || typeof query.readSession !== 'function') return
+    for (const id of ids) {
+      if (sessions.get(id)) continue
+      let alive = false
+      try {
+        const log = await query.readSession(id)
+        alive = Boolean(log)
+      } catch (error) {
+        alive = false
+      }
+      if (!alive) await purgeSession(id)
+    }
+  }
+
+  // 存储总量上限（P1-3）：按 root 分组统计，超限按 time 升序删最旧。
+  // 调用点（runGc/runGcAll）都在串行队列里，与快照互斥，无 git 锁竞态。
+  // 删除前 console.error 留痕（静默删历史撤回点必须可追溯，与 purgeSession
+  // 同款）；删除后重写索引。time=0 的孤儿条目（rebuildOrphans 重建）视为
+  // 最旧优先清理——它们没有真实时间，先于有时间的快照被清。
+  // 分组与选中逻辑在模块级 selectOverLimitVictims（单测直接钉边界）。
+  async function enforceLimits() {
+    const victimsMap = selectOverLimitVictims(state.snapshots, config.maxSnapshotsPerWorkspace)
+    if (!victimsMap.size) return 0
+    let dropped = 0
+    for (const [root, victims] of victimsMap) {
+      let store = state.stores.get(root)
+      if (!store) {
+        try { store = await rt.resolveStore(root) } catch (error) { store = null }
+      }
+      if (!store || !state.gitExe) continue
+      try {
+        for (let i = 0; i < victims.length; i += 100) {
+          await rt.runShell(S.purgeTagsScript(store, state.gitExe, victims.slice(i, i + 100).map((v) => 'snap-' + v.id)), { timeoutMs: 120000, stdoutMaxBytes: 4096 })
+        }
+        for (const v of victims) state.snapshots.delete(v.id)
+        await snaps.saveIndex(root, null)
+        dropped += victims.length
+        console.error('recall enforceLimits dropped ' + victims.length + ' oldest snapshots for: ' + root + ' (max ' + config.maxSnapshotsPerWorkspace + ')')
+      } catch (error) {
+        rt.recordError('recall enforceLimits failed for ' + root + ': ' + String(error))
+      }
+    }
+    return dropped
+  }
+
+  // 按时间保留（S2-3）：对每个 root 清掉早于保留窗口的快照。结构与
+  // enforceLimits 同款（tag 分块删除 + saveIndex + 留痕），与条数上限
+  // 各自独立触发，在同一轮 gc 周期里先后执行。时间维度的删除同样
+  // 静默丢历史撤回点，故 console.error 留痕与 enforceLimits 一致。
+  async function enforceRetention() {
+    const victimsMap = selectExpiredVictims(state.snapshots, config.retentionDays, Date.now())
+    if (!victimsMap.size) return 0
+    let dropped = 0
+    for (const [root, victims] of victimsMap) {
+      let store = state.stores.get(root)
+      if (!store) {
+        try { store = await rt.resolveStore(root) } catch (error) { store = null }
+      }
+      if (!store || !state.gitExe) continue
+      try {
+        for (let i = 0; i < victims.length; i += 100) {
+          await rt.runShell(S.purgeTagsScript(store, state.gitExe, victims.slice(i, i + 100).map((v) => 'snap-' + v.id)), { timeoutMs: 120000, stdoutMaxBytes: 4096 })
+        }
+        for (const v of victims) state.snapshots.delete(v.id)
+        await snaps.saveIndex(root, null)
+        dropped += victims.length
+        console.error('recall enforceRetention dropped ' + victims.length + ' expired snapshots for: ' + root + ' (retention ' + config.retentionDays + 'd)')
+      } catch (error) {
+        rt.recordError('recall enforceRetention failed for ' + root + ': ' + String(error))
+      }
+    }
+    return dropped
+  }
+
+  // 维护核心（节流判定 + 清理 + gc）：force 供设置页「立即 gc」手动触发，
+  // 跳过阈值检查但仍走同一条串行队列调用方——与快照天然互斥的约束不变。
+  // 失败也推进 gcLastAt：gc 失败往往是环境性的（磁盘/杀软），不推进时间戳
+  // 会让后续每条消息都重试一次重量级 gc，把队列堵住。
+  async function runGc(sessionId, force) {
+    const root = await rt.resolveRoot(sessionId)
+    if (!root) return false
+    const store = state.stores.get(root)
+    if (!store || !state.gitExe) return false
+    const now = Date.now()
+    const last = state.gcLastAt.get(store.git) || 0
+    const count = (state.gcCount.get(store.git) || 0) + 1
+    state.gcCount.set(store.git, count)
+    if (!force && count < config.gcSnaps && now - last < config.gcHours * 3600000) return false
+    state.gcCount.set(store.git, 0)
+    try {
+      await sweepDeletedSessions()
+      // P1-3：总量上限清理（sweep 之后、gc 之前）——与快照在同一条串行
+      // 队列里，删除 tag 与 gc 互斥，无 git 锁竞态；best-effort，
+      // 自身失败不进 catch 的主错误路径（enforceLimits 内部已兜）。
+      await enforceLimits()
+      // S2-3：按时间保留清理（与条数上限维度各自独立，同条串行队列）
+      await enforceRetention()
+      await rt.runShell(S.gcScript(store, state.gitExe), { timeoutMs: 600000, stdoutMaxBytes: 4096 })
+    } catch (error) {
+      rt.recordError('recall maintenance failed: ' + String(error))
+    }
+    state.gcLastAt.set(store.git, Date.now())
+    return true
+  }
+
+  // 全局 gc（设置卡片没有会话上下文）：清理扫描一次 + 逐 store gc。
+  // store 全集取内存缓存（启动预热与历次操作会填齐已知工作区）；逐个
+  // best-effort，单个失败记错误继续。调用方（manage 端点）把它排进同一条
+  // 串行队列，与快照天然互斥，无 git 锁竞态。
+  async function runGcAll() {
+    const stores = Array.from(new Set(Array.from(state.stores.values()).filter(Boolean)))
+    if (!stores.length || !state.gitExe) return false
+    try {
+      await sweepDeletedSessions()
+    } catch (error) {
+      rt.recordError('recall sweep failed: ' + String(error))
+    }
+    try {
+      // P1-3：全局清理一次（runGcAll 无会话上下文，enforceLimits 自身按
+      // root 遍历内存快照，天然覆盖全部已知工作区）
+      await enforceLimits()
+    } catch (error) {
+      rt.recordError('recall enforceLimits failed: ' + String(error))
+    }
+    try {
+      // S2-3：按时间保留全局清理一次
+      await enforceRetention()
+    } catch (error) {
+      rt.recordError('recall enforceRetention failed: ' + String(error))
+    }
+    let done = 0
+    for (const store of stores) {
+      try {
+        await rt.runShell(S.gcScript(store, state.gitExe), { timeoutMs: 600000, stdoutMaxBytes: 4096 })
+        done++
+      } catch (error) {
+        rt.recordError('recall gc failed for ' + (store && store.git) + ': ' + String(error))
+      }
+      state.gcLastAt.set(store.git, Date.now())
+      state.gcCount.set(store.git, 0)
+    }
+    return true
+  }
+
+  // 每条消息快照后串行调用（见 index.js 事件接线）
+  async function maybeMaintain(sessionId) {
+    await runGc(sessionId, false)
+  }
+
+  // 模块收敛：runGc/runGcAll 之外的内部步骤不对外暴露面；enforceLimits
+  // 保留导出供单测以工厂形态驱动（注入假 rt/ctx 钉执行链路）
+  return { maybeMaintain, runGc, runGcAll, enforceLimits, enforceRetention }
+}

package/lib/routes-core.js

@@ -0,0 +1,162 @@
+/**
+ * dsh-recall-plugin — 核心路由域（R2 从 index.js 拆出）
+ *
+ * init / snapshot-info / preview / execute / status / lineage-record 六个核心
+ * 端点。依赖经 deps 注入（rt/snaps/state/cfg/enqueue/agentBusy/rescueRollback
+ * 等），无模块级可变状态（HMR 假设）。preview/execute 内部跑 git add -A，
+ * 经 enqueue 排进与快照/gc 同一条串行队列，避免 index.lock 竞态。
+ */
+
+import { ENV_HINTS } from './diagnostics.js'
+
+export function createRoutesCore(deps) {
+  // ctx 不解构（A4）：本域所有服务访问都已由 rt/snaps 封装，直接摸 ctx 会
+  // 绕过工厂分层——留空位只会诱导未来代码破坏依赖注入约定
+  const { rt, snaps, state, cfg, supported, enqueue, agentBusy, rescueRollback, E } = deps
+
+  return {
+    'init': async (args) => {
+      if (!supported) {
+        return { ok: false, root: null, notice: { unsupported: true } }
+      }
+      const sessionId = args && args.sessionId ? String(args.sessionId) : null
+      const root = await rt.resolveRoot(sessionId)
+      let notice = null
+      if (root) {
+        let store = await rt.resolveStore(root)
+        store = await rt.tryUpgradeToHome(root)
+        await rt.ensureGit(root, store)
+        await snaps.loadIndex(root, sessionId)
+        await snaps.rebuildOrphans(root, sessionId)
+        rt.cleanupLegacy(root)
+        // 降级状态随 init 下发，Client 弹一次性提示（每次页面加载各弹一次）：
+        // gitMissing=未检测到 git CLI（撤回按钮不出现）；homeFallback=home
+        // 不可写，快照降级存进项目内 .dsh-recall-snapshots。
+        notice = {
+          gitMissing: state.gitExe === '',
+          homeFallback: store ? !store.home : false
+        }
+      }
+      // 顺带下发客户端行为开关（fillDraft 等）：Client 无须为读配置单开请求，
+      // init 是每会话必经的预热通道
+      return { ok: Boolean(root), root: root || null, notice, config: { refillDraft: cfg.refillDraft, archiveOriginal: cfg.archiveOriginal } }
+    },
+
+    'snapshot-info': async (args) => {
+      const id = args && args.messageId ? String(args.messageId) : ''
+      const snap = state.snapshots.get(id)
+      // 失败/跳过/熔断反馈（issue #7 失败可见性）：客户端轮询到 failed 即
+      // 终止轮询并 toast，不再空等 20 次；has 时附带 skipped 让用户知道
+      // fail-open 跳过了哪些路径
+      const feedback = await snaps.feedbackFor(args && args.sessionId, id)
+      return { has: Boolean(snap), time: snap ? snap.time : null, id, ...feedback }
+    },
+
+    'preview': async (args) => {
+      const id = args && args.messageId ? String(args.messageId) : ''
+      const sessionId = args && args.sessionId ? String(args.sessionId) : null
+      // P0-1：目标工作区 agent 运行中直接拒绝预览（避免用户确认时文件被
+      // agent 改动，预览清单与实际回退内容脱节）。同会话优先命中（最常见
+      // 场景），快照存在时叠加跨会话同工作区检查。
+      const snap = state.snapshots.get(id)
+      if (agentBusy(sessionId, snap ? snap.root : null)) return { ok: false, code: E.RECALL_AGENT_BUSY, message: 'Agent 正在运行中，请先停止后再撤回' }
+      const result = await enqueue(() => snaps.diffFor(id))
+      if (result === null) return { ok: false, code: E.RECALL_NO_SNAPSHOT, message: '该消息没有可用的项目快照' }
+      const snap2 = state.snapshots.get(id)
+      const cutSeq = await snaps.resolveCutSeq(sessionId, id)
+      return { ok: true, changes: result.changes, total: result.total, truncated: result.truncated, time: snap2 ? snap2.time : null, root: snap2 ? snap2.root : null, cutSeq }
+    },
+
+    'execute': async (args) => {
+      const id = args && args.messageId ? String(args.messageId) : ''
+      const sessionId = args && args.sessionId ? String(args.sessionId) : null
+      const result = await enqueue(async () => {
+        const snap = state.snapshots.get(id)
+        if (!snap) return { ok: false, code: E.RECALL_NO_SNAPSHOT, message: '该消息没有可用的项目快照' }
+        const store = state.stores.get(snap.root)
+        if (!store) return { ok: false, code: E.RECALL_NO_STORE, message: '快照存储不可用' }
+        // P0-1：队列内第一步——执行前再查一次 agent 状态。检查放在互斥
+        // 队列内，检查后紧接执行，中间不可能插进别的操作，窗口为零。
+        if (agentBusy(sessionId, snap.root)) return { ok: false, code: E.RECALL_AGENT_BUSY, message: 'Agent 正在运行中，请先停止后再撤回' }
+        // P0-3：preview→execute 失效校验。只由带 previewTotal 的新版
+        // Client 触发（老版本/直调 API 不带则跳过，向后兼容）。校验失败
+        // 连安全快照都不打——省一次全量 add。同数不同文件的边缘情形由
+        // 下方 pre-rollback 安全快照兜底。
+        if (args && typeof args.previewTotal === 'number') {
+          const fresh = await snaps.diffFor(id)
+          if (!fresh || fresh.total !== args.previewTotal) {
+            return { ok: false, code: E.RECALL_STALE, message: '预览后项目文件发生了变化，请重新预览确认' }
+          }
+        }
+        // 回退前自动打安全快照：回退覆盖工作区且不回写 index（旧的
+        // 「当前状态」从此无任何快照可找回），用消息 ID 打 tag 会与该消息
+        // 的既有快照碰撞，故用独立前缀的时间戳 tag——不进 index.json
+        // （列表不展示），但孤儿重建/手动 git tag 仍能找到它，误回退后
+        // 用户可让插件从该 tag 恢复，堵住唯一的不可逆操作缺口。
+        // 失败时 safetyOk 置 false：后续回退若也失败将无救援点（H1），
+        // 行为退化为现状（fail-loud），不更差。
+        const safetyId = 'pre-rollback-' + Date.now()
+        let safetyOk = false
+        try {
+          await rt.runShell(rt.scripts.snapshotScript(snap.root, store, state.gitExe, safetyId, cfg.baseExcludes), { timeoutMs: 600000, stdoutMaxBytes: 65536 })
+          safetyOk = true
+        } catch (error) {
+          // 安全快照失败不阻断回退本身：用户已确认覆盖，记录后照原计划执行
+          rt.recordError('recall safety snapshot failed: ' + String(error))
+        }
+        const rolled = await snaps.rollbackFor(id)
+        if (rolled.ok) return rolled
+        // 回退失败（rollbackFor 返回 partial，工作区可能半回退）：用安全快照
+        // 救援（H1）。rescueRollback 是 snapshots.js 模块级纯逻辑，副作用经
+        // deps 注入，三分支（无救援点/救援成功/救援失败）单测直接钉。
+        return rescueRollback(
+          { runShell: rt.runShell, scripts: rt.scripts, gitExe: state.gitExe, recordError: rt.recordError },
+          { root: snap.root, store, safetyId, safetyOk, rollbackError: rolled.error }
+        )
+      })
+      if (!result.ok) return result
+      // 文件回退后再解析切点：切点只依赖会话日志，与快照是否删除无关（命中缓存，瞬时）
+      const cutSeq = await snaps.resolveCutSeq(sessionId, id)
+      return { ok: true, count: result.count, cutSeq }
+    },
+
+    // 设置页排障：最近错误（Host 侧 console.error 的页面可见副本）。
+    // M1-D3/D5：条目自带 count/kind（recordError 富集）——count 在服务端
+    // 拼成「（×N）」展示文本，设置页按 message 渲染即显示重复计数，零
+    // Client 改动；hint 是分类后的可行动提示（API 自描述，本次无客户端
+    // 消费，设置页未来展示零成本）。storeBase（M2-D3）暴露快照存储根，
+    // 供设置页未来展示「快照存在哪里」，失败为 null。
+    'status': async (args) => {
+      const storeBase = await rt.resolveHomeContainer()
+      if (args && args.op === 'clear') {
+        state.errors.length = 0
+        return { ok: true, errors: [], storeBase }
+      }
+      const errors = state.errors.slice(-20).reverse().map((e) => ({
+        ...e,
+        message: e.message + (e.count > 1 ? '（×' + e.count + '）' : ''),
+        hint: ENV_HINTS[e.kind] || null
+      }))
+      return { ok: true, errors, storeBase }
+    },
+
+    // F1：client fork 成功后上报撤回链（childId ↔ parentId），Host 持久化到
+    // lineage.json 供快照管理树聚族展示「版本家族」。root 优先按 fork 源
+    // parentId 解析（fork 时它仍是 live 会话；归档只隐藏列表、对象在内存），
+    // 失败回退 childId。
+    'lineage-record': async (args) => {
+      const childId = args && args.childId ? String(args.childId) : ''
+      const parentId = args && args.parentId ? String(args.parentId) : ''
+      if (!childId || !parentId) return { ok: false, code: E.RECALL_BAD_TYPE, message: '缺少会话 ID' }
+      const root = (await rt.resolveRoot(parentId)) || (await rt.resolveRoot(childId))
+      if (!root) return { ok: false, code: E.RECALL_NO_ROOT, message: '无法解析工作区' }
+      let store = state.stores.get(root)
+      if (!store) {
+        try { store = await rt.resolveStore(root) } catch (error) { store = null }
+      }
+      if (!store) return { ok: false, code: E.RECALL_NO_STORE, message: '快照存储不可用' }
+      await snaps.recordLineage(root, childId, parentId)
+      return { ok: true }
+    }
+  }
+}