dsh-recall-plugin 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 本文件格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循语义化版本。
 
+## [1.7.0] - 2026-08-25
+
+### 新增
+
+- 快照失败/跳过可见性（[#7](https://github.com/limbo947/dsh-recall-plugin/issues/7) 加固项 1）：快照失败或熔断时客户端 toast 提示（同一故障文本 10 分钟节流，避免持续故障期间刷屏），轮询到失败即终止、不再空等 20 次；熔断期间的新消息会收到「已暂停，N 分钟后自动重试」提示而非沉默。「按钮为什么消失了」的排障成本由此消掉。
+- `git add --ignore-errors` fail-open 兜底（[#7](https://github.com/limbo947/dsh-recall-plugin/issues/7) 加固项 3）：无法索引的路径（无提交的嵌入式仓库、不可读文件等）以退出码 1 结束但索引照常落盘——快照缺个别路径可接受，好过整条快照 fatal。被跳过的路径以 SNAP_SKIP 行回传，客户端提示「快照已跳过未纳入的路径」（这些路径撤回时既不恢复也不会被删，与排除表语义一致）。
+- 失败后孤儿进程清扫 + stale 锁清理（[#7](https://github.com/limbo947/dsh-recall-plugin/issues/7) 加固项 4）：runShell 失败路径按 `--git-dir=<本仓库>` 命令行标记定位漏网孤儿进程并终止（win: `taskkill /T /F`，POSIX: `pgrep`+`kill`），随后清理 index.lock 等残留锁——DSH subprocess 服务的树级终止有竞态窗口，且 git 被硬杀不做锁回收，残留的 index.lock 会让后续每条快照持续 fatal。
+
+### 修复
+
+- `git add` fatal 时脚本假成功（空树快照）：pwsh 对原生命令非零退出不抛错（ErrorActionPreference 不作用于 native），此前 add fatal 后脚本会带着未更新的旧索引继续走完 write-tree/commit/tag，产出空树 tag 且退出码 0——快照「成功」却什么都回退不了。现显式检查退出码（≥2 抛错终止），diff/rollback 的同款 add 一并修复。
+
+## [1.6.2] - 2026-08-25
+
+### 修复
+
+- 用户消息图片显示空白且刷新无效（[#8](https://github.com/limbo947/dsh-recall-plugin/issues/8)）：会话回放时最早的图片消息先于会话 binding 就绪渲染，`loadImage` 以 unknown session 拒绝后被静默 `catch` 吞掉，图片永久空白。图片加载改为 400ms/1.5s/4s 三次退避自动重试（暂态失败自愈），耗尽后显示「图片加载失败，点击重试」失败态（对齐官方 MessageImage 语义）；顺带修复 attachment 切换时短暂残留上一张图的问题。
+- 快照连续失败无限累积磁盘残骸（[#7](https://github.com/limbo947/dsh-recall-plugin/issues/7) 评论实测一个下午 127GB dangling 对象）：失败重试的每次 `git add` 都会写入无 tag 可达的残骸对象。两道防线——
+  - **失败清理**：每次快照失败后执行 `git prune`（以 refs + 暂存 index 为根做可达性删除），只清当次残骸、不碰任何 tag 快照，已暂存对象保留以维持下次增量。
+  - **熔断退避**：连续 3 次失败后按 5min 起步指数翻倍、60min 封顶的退避跳过快照，冷却期满自动重试，成功一次即全部复位；进入熔断只在跳变沿记一条最近错误。
+
 ## [1.6.1] - 2026-08-23
 
 ### 新增

package/README.md

@@ -12,8 +12,11 @@
 
 ---
 **在任意一条你发过的消息下方**，**点「↶ 撤回」**，**工作区文件和对话历史一起回到那条消息发出之前的状态**。
+---
 
+[更新日志](CHANGELOG.md)
 ## 界面预览
+
 - 撤回按钮位置
 
 ![悬停出现撤回按钮](docs/screenshots/recall-button.png)
@@ -23,7 +26,7 @@
 | --- | --- |
 | ![确认面板 · 变更文件清单](docs/screenshots/confirm-panel-1.png) | ![确认面板](docs/screenshots/confirm-panel-2.png) |
 
-- 撤回后自动把消息文本回填到输入框，方便修改后重发（可在设置卡片关闭）
+- 撤回后自动把消息文本回填到输入框，方便修改后重发（可在设置卡片关闭）
 - 设置页 · 插件配置卡片（阈值 / 排除表 / 快照管理，保存即热生效）
 
  ![设置页](docs/screenshots/settings-exclude-2.png) 
@@ -126,6 +129,4 @@ Copy-Item -Recurse -Force $pkg "$profile\node_modules\dsh-recall-plugin"
 
 MIT
 
----
 
-[更新日志](CHANGELOG.md)

package/lib/client.js

@@ -39,6 +39,8 @@ window.__ModuleLoader__.load({
           '.dsh-recall-stack{flex-direction:column;align-items:flex-end;gap:8px;min-width:0;max-width:min(525px,82%);display:flex}',
           '.dsh-recall-bubble{background:var(--dsw-specific-bubble);max-width:100%;color:var(--dsw-alias-label-primary);border-radius:22px;padding:10px 16px;font-size:16px;line-height:24px;white-space:pre-wrap;word-break:break-word}',
           '.dsh-recall-img{max-width:100%;max-height:320px;border-radius:12px;object-fit:contain}',
+          '.dsh-recall-img-failed{border:1px dashed var(--dsw-alias-border-l2);border-radius:12px;padding:8px 14px;font-size:13px;line-height:20px;color:var(--dsw-alias-label-tertiary);cursor:pointer;background:0 0}',
+          '.dsh-recall-img-failed:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-label-dimmed)}',
           '.dsh-recall-json{margin:0;max-width:100%;font-size:12px;line-height:18px;color:var(--dsw-alias-label-tertiary);white-space:pre-wrap;word-break:break-word;border:1px solid var(--dsw-alias-border-l1);border-radius:10px;padding:8px 10px;background:var(--dsw-alias-markdown-code-block)}',
           '.dsh-recall-actions{align-items:center;gap:10px;height:28px;display:flex}',
           '.dsh-recall-time{color:var(--dsw-alias-label-tertiary);white-space:nowrap;padding-right:12px;font-size:14px;line-height:24px}',
@@ -122,9 +124,9 @@ window.__ModuleLoader__.load({
         // 降级提示：每个种类每次页面加载只弹一次（Set 去重），避免切会话时
         // 反复打扰。纯 DOM 直插（与剪贴板同样的零依赖思路），7 秒后自动淡出。
         const noticeShown = new Set()
-        function showNotice(kind, text) {
-          if (noticeShown.has(kind) || typeof document === 'undefined') return
-          noticeShown.add(kind)
+        // toast 挂载本体：两类提示（降级/快照反馈）共用的纯 DOM 实现
+        function mountToast(text) {
+          if (typeof document === 'undefined') return
           try {
             const el = document.createElement('div')
             el.className = 'dsh-recall-toast'
@@ -149,6 +151,25 @@ window.__ModuleLoader__.load({
             }
           } catch (e) { /* 提示失败不影响主流程 */ }
         }
+        function showNotice(kind, text) {
+          if (noticeShown.has(kind)) return
+          noticeShown.add(kind)
+          mountToast(text)
+        }
+        // 快照失败/跳过提示（issue #7 失败可见性）：与降级提示不同，这类
+        // 事件会在持续故障期间随每条消息反复发生——按「文本前缀 + 时间窗」
+        // 节流，同一故障 10 分钟内至多打扰一次；不同错误（文本不同）各自
+        // 独立计数。Map 规模封顶后整体清空：提示是尽力而为的可见性，不是
+        // 需要精确保留的状态。
+        const toastLastShown = new Map()
+        function showThrottledToast(text) {
+          const key = String(text).slice(0, 80)
+          const now = Date.now()
+          if (now - (toastLastShown.get(key) || 0) < 10 * 60 * 1000) return
+          if (toastLastShown.size > 50) toastLastShown.clear()
+          toastLastShown.set(key, now)
+          mountToast(text)
+        }
 
         // 每个会话只向 Host 注册一次（预热其根目录解析缓存）。
         // 返回 init 的 promise：Host 端 init 要跑数条 PowerShell（建仓/loadIndex），
@@ -247,23 +268,50 @@ window.__ModuleLoader__.load({
           )
         }
 
+        // 图片加载失败的暂态判定（issue #8）：会话回放时最早的图片消息先于
+        // 会话 binding 就绪渲染，loadImage 以 unknown session 拒绝——这类
+        // 失败靠短退避自动重试即可自愈；此前 `.catch(() => {})` 把失败静默
+        // 吞掉且 src 恒为 null，图片永久空白且刷新无法恢复。自动重试耗尽
+        // 后置 failed，由 ImageBox 提供「点击重试」（对齐官方 MessageImage
+        // 的失败态语义），attempt 仅被手动重试递增以复用整条加载链。
+        const IMAGE_RETRY_DELAYS = [400, 1500, 4000]
+
         function useImageSrc(attachment, loadImage) {
           const [src, setSrc] = React.useState(null)
+          const [failed, setFailed] = React.useState(false)
+          const [attempt, setAttempt] = React.useState(0)
           React.useEffect(() => {
             let alive = true
+            let timer = null
             if (!attachment || typeof loadImage !== 'function') return undefined
-            Promise.resolve(loadImage(attachment)).then((url) => {
-              if (alive && url) setSrc(String(url))
-            }).catch(() => {})
-            return () => { alive = false }
-          }, [attachment, loadImage])
-          return src
+            // 复位旧状态：attachment 变化或手动重试时清掉上一轮的 src/failed，
+            // 避免加载期间短暂显示上一张图或残留的失败态
+            setSrc(null)
+            setFailed(false)
+            const tryLoad = (retried) => {
+              Promise.resolve(loadImage(attachment)).then((url) => {
+                if (!alive) return
+                if (url) setSrc(String(url))
+                else if (retried < IMAGE_RETRY_DELAYS.length) timer = setTimeout(() => tryLoad(retried + 1), IMAGE_RETRY_DELAYS[retried])
+                else setFailed(true)
+              }).catch(() => {
+                if (!alive) return
+                if (retried < IMAGE_RETRY_DELAYS.length) timer = setTimeout(() => tryLoad(retried + 1), IMAGE_RETRY_DELAYS[retried])
+                else setFailed(true)
+              })
+            }
+            tryLoad(0)
+            return () => { alive = false; if (timer) clearTimeout(timer) }
+          }, [attachment, loadImage, attempt])
+          return { src, failed, retry: () => setAttempt(attempt + 1) }
         }
 
         function ImageBox(props) {
-          const src = useImageSrc(props.attachment, props.loadImage)
-          if (!src) return null
-          return React.createElement('img', { className: 'dsh-recall-img', src, alt: '' })
+          const { src, failed, retry } = useImageSrc(props.attachment, props.loadImage)
+          if (src) return React.createElement('img', { className: 'dsh-recall-img', src, alt: '' })
+          // 加载中保持原零占位语义（不撑气泡）；只在确定失败后渲染可重试入口
+          if (failed) return React.createElement('button', { type: 'button', className: 'dsh-recall-img-failed', onClick: retry }, '图片加载失败，点击重试')
+          return null
         }
 
         // kind 语义单表承载（文案/徽章类名/汇总顺序）：新增 kind 时只改
@@ -389,12 +437,25 @@ window.__ModuleLoader__.load({
             function schedule() {
               if (!alive || !messageId) return
               attempts++
-              api('snapshot-info', { messageId }).then((res) => {
+              api('snapshot-info', { messageId, sessionId }).then((res) => {
                 if (!alive) return
                 if (res && res.has) {
+                  // fail-open 跳过的路径：快照存在但个别目录没进去（撤回不
+                  // 恢复也不删它们）——仅对正在发生的消息提示，让用户知道
+                  // 快照少了什么（issue #7 失败可见性）
+                  if (recent && Array.isArray(res.skipped) && res.skipped.length) {
+                    const names = res.skipped.slice(0, 5).join('、') + (res.skipped.length > 5 ? ' 等 ' + res.skipped.length + ' 项' : '')
+                    showThrottledToast('快照已跳过未纳入的路径：' + names + '（撤回不会恢复或删除这些路径）')
+                  }
                   setHasSnapshot(true)
                   return
                 }
+                // 失败/熔断是终止态：快照不会迟到，提示后停止轮询——
+                // 「按钮为什么消失了」的排障成本由这条提示消掉（issue #7）
+                if (res && res.failed) {
+                  if (recent) showThrottledToast('快照失败：' + String(res.error || '未知原因').slice(0, 140))
+                  return
+                }
                 if (recent && attempts < MAX_ATTEMPTS) timer = setTimeout(schedule, RETRY_MS)
               }).catch(() => {
                 if (alive && recent && attempts < MAX_ATTEMPTS) timer = setTimeout(schedule, RETRY_MS)

package/lib/index.js

@@ -524,7 +524,11 @@ export function apply(ctx, config) {
     'snapshot-info': async (args) => {
       const id = args && args.messageId ? String(args.messageId) : ''
       const snap = state.snapshots.get(id)
-      return { has: Boolean(snap), time: snap ? snap.time : null, 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) => {

package/lib/maintenance.js

@@ -1,145 +1,145 @@
-/**
- * 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）一天至多一次的量级，轻会话用户也不会等太久。
+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 }
+}

package/lib/scripts.posix.js

@@ -161,7 +161,19 @@ export function snapshotScript(root, store, gitExe, messageId, base) {
     'root=' + psq(root),
     dropGitlinksBlock(),
     excludeSyncBlock(store.excludeFile, base),
-    '"$git" --git-dir="$g" --work-tree="$root" add -A',
+    // fail-open add（issue #7 加固，语义见 pwsh 版同款注释）：--ignore-errors
+    // 下「无法索引的路径」以退出码 1 结束但索引已落盘；≥2 才是真 fatal，
+    // 显式退出让 runShell 抛错（set -e 对 add 非零本会终止，但 || rc=$?
+    // 捕获后必须自检，否则 tolerated/fatal 无法区分）。stderr 合并进变量
+    // 供 fatal 时带回诊断与 SNAP_SKIP 提取。
+    'addrc=0',
+    'add_log=$("$git" --git-dir="$g" --work-tree="$root" add -A --ignore-errors 2>&1) || addrc=$?',
+    'if [ "$addrc" -ge 2 ]; then printf \'%s\\n\' "$add_log" >&2; exit "$addrc"; fi',
+    "printf '%s\\n' \"$add_log\" | sed -n \"s/^error: unable to index file '\\(.*\\)'$/\\1/p\" | sort -u | while IFS= read -r sk; do",
+    // 循环体用 if/fi 而非 && 列表：&& 列表条件为假时整条管道退出码为 1，
+    // set -e 会把脚本杀掉（if 语句天然豁免）
+    '  if [ -n "$sk" ]; then printf \'SNAP_SKIP %s\\n\' "$sk"; fi',
+    'done',
     dropGitlinksBlock(),
     oversizeBlock(store.maxFileBytes),
     'tree=$("$git" --git-dir="$g" --work-tree="$root" write-tree)',
@@ -185,7 +197,12 @@ function collectListsBlock(store, gitExe, root, tag, base) {
     'root=' + psq(root),
     dropGitlinksBlock(),
     excludeSyncBlock(store.excludeFile, base),
-    '"$git" --git-dir="$g" --work-tree="$root" add -A',
+    // fail-open add（语义见 snapshotScript 同款注释）：diff/rollback 的当前
+    // 清单来自这次 add 后的索引——被跳过的路径不进清单，diff 不显示、
+    // rollback 删除清单也不会误删它们；≥2 显式退出防「旧索引假成功」
+    'addrc=0',
+    '"$git" --git-dir="$g" --work-tree="$root" add -A --ignore-errors || addrc=$?',
+    '[ "$addrc" -le 1 ] || exit "$addrc"',
     dropGitlinksBlock(),
     oversizeBlock(store.maxFileBytes),
     'tmpc=' + psq(store.dir + '/diff-cur.$$'),
@@ -279,6 +296,40 @@ export function gcScript(store, gitExe) {
   ].join('\n')
 }
 
+// 快照失败后的残骸清理（语义同 pwsh 版，动机详见其注释）：prune 以
+// refs + 暂存 index 为根删无引用对象，只清失败 add 的残骸、不碰 tag 快照
+export function pruneScript(store, gitExe) {
+  return [
+    'set -e',
+    'git=' + psq(gitExe),
+    'g=' + psq(store.git),
+    '"$git" --git-dir="$g" prune',
+    'echo PRUNE_OK'
+  ].join('\n')
+}
+
+// 失败后的孤儿进程清扫 + stale 锁清理（issue #7，语义与动机见 pwsh 版
+// 同款注释）。POSIX 版差异：pgrep -f 按扩展正则匹配整条命令行——路径
+// 元字符（[、+ 等）会让模式失配，清扫静默失效，属安全降级（等价于本兜底
+// 加入前的行为）；标记在运行期拼接，本脚本自身命令行里只有未展开的 $g
+// 字面量，不会自杀。全程无 set -e + 逐步容错：清扫自身的失败不能抛。
+export function killOrphansScript(gitDir) {
+  return [
+    '# RECALL_CLEANUP',
+    'g=' + psq(gitDir),
+    'marker="--git-dir=$g"',
+    'for p in $(pgrep -f -- "$marker" 2>/dev/null); do',
+    '  [ "$p" = "$$" ] && continue',
+    '  kill "$p" 2>/dev/null || true',
+    'done',
+    // 锁清单对齐 pwsh 版：index.lock 是 add/checkout 持久锁，其余是
+    // gc/tag/pack 链路残留；refs 下 per-ref 锁用 find 兜底
+    'rm -f "$g/index.lock" "$g/config.lock" "$g/HEAD.lock" "$g/gc.pid" "$g/packed-refs.lock" "$g/shallow.lock" 2>/dev/null || true',
+    'find "$g/refs" -type f -name "*.lock" -delete 2>/dev/null || true',
+    'echo CLEANUP_DONE'
+  ].join('\n')
+}
+
 // 删除指定快照 tag（会话已删联动清理用）：tag -d 对不存在 tag 非零退出，
 // || true 吞掉——best-effort，残留 tag 由下次清理幂等收尾（同 pwsh 版）
 export function purgeTagsScript(store, gitExe, tags) {