dsh-recall-plugin 1.7.0 → 2.0.0

package/lib/config.js

@@ -19,18 +19,36 @@ export const Config = Schema.object({
   gcSnaps: Schema.number().default(50).description('每积累多少条快照触发一次 git gc'),
   gcHours: Schema.number().default(24).description('距上次 gc 超过多少小时触发（与条数先到先触发）'),
   maxFileBytes: Schema.number().default(104857600).description('超过该字节数的文件不进快照、不被回退触碰'),
+  maxSnapshotsPerWorkspace: Schema.number().default(500).description('每个工作区保留的最大快照数，超限删除最旧的'),
   // 排除表必须同时覆盖两种存储目录名：降级存储是项目内 .dsh-recall-snapshots/，
   // 而 home 存储目录名是 dsh-recall-snapshots/（无点）——工作区 root 恰为
   // HOME 时（容器 root=/root 等）它落在工作区内，漏排除会让 git add -A
   // 把影子仓库自己吞进去、快照全部失败（issue #6）
   baseExcludes: Schema.array(Schema.string()).default(['.git', 'node_modules/', '.dsh-recall-snapshots/', 'dsh-recall-snapshots/']).description('基础排除表（gitignore 语法，优先级低于 exclude.txt）'),
   refillDraft: Schema.boolean().default(true).description('撤回后把被撤回的消息文本回填到输入框'),
+  snapshotEnabled: Schema.boolean().default(true).description('启用消息快照（关闭后不再新建，已有快照仍可撤回）'),
+  archiveOriginal: Schema.boolean().default(true).description('撤回后归档原会话（关闭后原会话保留在列表中）'),
+  retentionDays: Schema.number().default(0).description('按天数保留快照，超期自动删除；0 表示不启用'),
 })
 
 // schema 默认值的运行时镜像：settings 服务未组装时 createConfig 直接以
-// 入口 config 解析，这组兜底与 Config 保持一致（改默认值两处同步改）
+// 入口 config 解析，这组兜底与 Config 保持一致（改默认值两处同步改）。
+// DEFAULTS 同时供 config-reset 降级路径（settings.replace 不可用时的兜底，
+// 见 index.js config-reset 端点）——默认值只此一份，避免重置与 schema 漂移。
 const BASE_EXCLUDES = ['.git', 'node_modules/', '.dsh-recall-snapshots/', 'dsh-recall-snapshots/']
 
+export const DEFAULTS = {
+  gcSnaps: 50,
+  gcHours: 24,
+  maxFileBytes: 104857600,
+  maxSnapshotsPerWorkspace: 500,
+  baseExcludes: BASE_EXCLUDES,
+  refillDraft: true,
+  snapshotEnabled: true,
+  archiveOriginal: true,
+  retentionDays: 0,
+}
+
 export function createConfig(raw) {
   const cfg = raw && typeof raw === 'object' ? raw : {}
 
@@ -44,6 +62,13 @@ export function createConfig(raw) {
   const gcSnaps = pickNumber(process.env.DSH_RECALL_GC_SNAPS, pickNumber(cfg.gcSnaps, 50, 1), 1)
   const gcHours = pickNumber(process.env.DSH_RECALL_GC_HOURS, pickNumber(cfg.gcHours, 24, 1), 1)
   const maxFileBytes = pickNumber(cfg.maxFileBytes, 104857600, 1024)
+  // 每工作区快照上限：0 或负值语义 = 不限制（给想全保留的用户出口）；
+  // 非数值回退默认 500。默认 500 ≈ 重度使用一周量级，太小会静默丢历史
+  // 撤回点，太大失去防膨胀意义。
+  const rawMax = typeof cfg.maxSnapshotsPerWorkspace === 'number'
+    ? cfg.maxSnapshotsPerWorkspace
+    : parseInt(String(cfg.maxSnapshotsPerWorkspace == null ? '' : cfg.maxSnapshotsPerWorkspace), 10)
+  const maxSnapshotsPerWorkspace = Number.isFinite(rawMax) ? Math.max(0, rawMax) : 500
 
   const baseExcludes = Array.isArray(cfg.baseExcludes) && cfg.baseExcludes.length
     ? cfg.baseExcludes.filter((p) => typeof p === 'string' && p.trim())
@@ -51,5 +76,21 @@ export function createConfig(raw) {
 
   const refillDraft = typeof cfg.refillDraft === 'boolean' ? cfg.refillDraft : true
 
-  return { gcSnaps, gcHours, maxFileBytes, baseExcludes, refillDraft }
+  // 快照总开关：false 冻结「新建」（session/event 短路，见 index.js），
+  // 已有快照的撤回链路不受影响——关闭只停增量，不销毁存量。
+  const snapshotEnabled = typeof cfg.snapshotEnabled === 'boolean' ? cfg.snapshotEnabled : true
+
+  // 撤回后是否归档原会话：关闭时原会话保留在侧栏（fork 新会话仍打开），
+  // 供用户对照回退前后上下文；默认开（归档只是隐藏、可恢复）。
+  const archiveOriginal = typeof cfg.archiveOriginal === 'boolean' ? cfg.archiveOriginal : true
+
+  // 按时间保留（S2-3）：0 或负值 = 不启用（静默删历史撤回点必须显式
+  // opt-in）；非数值回退 0。与 maxSnapshotsPerWorkspace（条数维度）并存，
+  // 各自独立触发——见 maintenance.enforceRetention。
+  const rawDays = typeof cfg.retentionDays === 'number'
+    ? cfg.retentionDays
+    : parseInt(String(cfg.retentionDays == null ? '' : cfg.retentionDays), 10)
+  const retentionDays = Number.isFinite(rawDays) ? Math.max(0, rawDays) : 0
+
+  return { gcSnaps, gcHours, maxFileBytes, maxSnapshotsPerWorkspace, baseExcludes, refillDraft, snapshotEnabled, archiveOriginal, retentionDays }
 }

package/lib/index.js

@@ -12,7 +12,7 @@
  * 文件拆分见 lib/ 下各模块头注释；本文件只做接线，不承载业务逻辑。
  */
 
-import { createConfig, Config } from './config.js'
+import { createConfig, Config, DEFAULTS } from './config.js'
 import { createRuntime } from './store.js'
 import { createSnapshots } from './snapshots.js'
 import { createMaintenance } from './maintenance.js'
@@ -21,8 +21,12 @@ import { installSettingsSection } from '@deepseek-ai/dsh-settings'
 export const name = 'dsh-recall-plugin'
 
 // 硬依赖：shell（PowerShell 执行）、sessions（会话/沙箱策略）、
-// webServer（Client 半的 HTTP API 通道）。其余服务按需 ctx.get。
-export const inject = ['shell', 'sessions', 'webServer']
+// webServer（Client 半的 HTTP API 通道）。agents（dsh-base 无条件装配的
+// agent 注册表）为 P0-1 运行中 agent 拦截读运行状态所需——cordis 4 要求
+// 服务在 inject 中声明才可经 ctx.agents 访问，漏声明会抛
+// "cannot get property ... without inject" 导致检查静默 fail-open（冒烟发现）。
+// 其余服务按需 ctx.get。
+export const inject = ['shell', 'sessions', 'webServer', 'agents']
 
 // 入口配置 schema：cordis 加载器据此校验 insert 行 config 并填充默认值，
 // 非法配置在插件加载时响亮失败（官方「插件配置」文档要求）。
@@ -77,7 +81,7 @@ export function apply(ctx, config) {
   // 快照管理列表的结果缓存：磁盘 dump + 冷会话标题即便已批量/并行化，
   // 也不是零成本（1 条 shell + 若干日志解压）。设置页打开、删除后刷新
   // 都会重拉，30s 缓存让二次打开即时；delete 与新快照落地时失效。
-  let listCache = { at: 0, payload: null }
+  let listCache = { at: 0, items: null }
   // 排除配置枚举缓存（30s）：exclude-get 首次要遍历工作区、逐文件 shell 读，
   // 设置页反复打开时不该每次重算；exclude-set 成功写入后立即失效。
   let excludeCache = { at: 0, payload: null }
@@ -224,6 +228,44 @@ export function apply(ctx, config) {
     return cwds
   }
 
+  // 归一化 cwd/root 路径用于跨会话同工作区比对：Windows 大小写不敏感 +
+  // 去掉尾部分隔符，避免 D:\Foo 与 d:\foo\ 误判为不同目录。
+  function normalizeWorkdir(path) {
+    if (!path) return ''
+    let p = String(path)
+    return (process.platform === 'win32' ? p.toLowerCase() : p).replace(/[\\/]+$/, '')
+  }
+
+  // 回退前重保护检查（P0-1）：目标工作区有 agent 正在跑时拒绝预览/撤回。
+  // 保守策略——不做自动取消（不替用户做决定），仅拦下操作并提示先停止。
+  // API 已在 dsh-agent .d.ts 公开面核验：AgentRegistry.get(id) / list() 均公开，
+  // Agent.status ∈ 'idle' | 'running'，Agent.session.header.cwd 是活动会话的工作区。
+  // 守卫式访问只为防御「未来版本改名 / agent 服务未装配」，失败视为「不忙」
+  // （fail-open，不阻断主流程，只损失保护）。
+  function agentBusy(sessionId, root) {
+    let reg = null
+    try { reg = ctx.agents } catch (error) { return false }
+    if (!reg) return false
+    try {
+      if (typeof reg.list === 'function') {
+        for (const agent of reg.list()) {
+          if (!agent || agent.status !== 'running') continue
+          // 发起会话自身的 agent（覆盖最常见场景：本会话 agent 在跑）
+          if (sessionId && String(agent.id) === String(sessionId)) return true
+          // 跨会话同工作区：另一会话的 agent 在同一个目录跑也会被文件回退波及
+          const cwd = agent.session && agent.session.header && agent.session.header.cwd
+          if (root && cwd && normalizeWorkdir(cwd) === normalizeWorkdir(root)) return true
+        }
+        return false
+      }
+      if (sessionId && typeof reg.get === 'function') {
+        const agent = reg.get(sessionId)
+        return Boolean(agent && agent.status === 'running')
+      }
+    } catch (error) { /* fail-open */ }
+    return false
+  }
+
   // 解析 storesDumpScript 的定界输出：dir → { root, entries }。逐行状态机
   // （==DIR / ROOT / INDEXBEGIN..INDEXEND），单个 store 的 JSON 损坏只丢它自己。
   function parseStoresDump(text) {
@@ -411,7 +453,7 @@ export function apply(ctx, config) {
           rt.recordError('recall batch delete failed for ' + root + ': ' + String(error))
         }
       }
-      listCache.payload = null
+      listCache.items = null
     })
     return deleted
   }
@@ -488,7 +530,7 @@ export function apply(ctx, config) {
       }
       // list 既合并内存也 dump 磁盘；无论完全/部分完成都必须失效，才能让
       // 成功删除的 store 立即从树上消失，而失败 store 仍保留供用户重试。
-      listCache.payload = null
+      listCache.items = null
       return { deleted, stores: clearedStores, failed }
     })
   }
@@ -518,7 +560,7 @@ export function apply(ctx, config) {
       }
       // 顺带下发客户端行为开关（fillDraft 等）：Client 无须为读配置单开请求，
       // init 是每会话必经的预热通道
-      return { ok: Boolean(root), root: root || null, notice, config: { refillDraft: cfg.refillDraft } }
+      return { ok: Boolean(root), root: root || null, notice, config: { refillDraft: cfg.refillDraft, archiveOriginal: cfg.archiveOriginal } }
     },
 
     'snapshot-info': async (args) => {
@@ -534,26 +576,44 @@ export function apply(ctx, config) {
     '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: 'AGENT_BUSY', message: 'Agent 正在运行中，请先停止后再撤回' }
       const result = await enqueue(() => snaps.diffFor(id))
       if (result === null) return { ok: false, code: 'NO_SNAPSHOT', message: '该消息没有可用的项目快照' }
-      const snap = state.snapshots.get(id)
+      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: snap ? snap.time : null, root: snap ? snap.root : null, cutSeq }
+      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: 'NO_SNAPSHOT', message: '该消息没有可用的项目快照' }
+        const store = state.stores.get(snap.root)
+        if (!store) return { ok: false, code: 'NO_STORE', message: '快照存储不可用' }
+        // P0-1：队列内第一步——执行前再查一次 agent 状态。检查放在互斥
+        // 队列内，检查后紧接执行，中间不可能插进别的操作，窗口为零。
+        if (agentBusy(sessionId, snap.root)) return { ok: false, code: '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: 'STALE', message: '预览后项目文件发生了变化，请重新预览确认' }
+          }
+        }
         // 回退前自动打安全快照：回退覆盖工作区且不回写 index（旧的
         // 「当前状态」从此无任何快照可找回），用消息 ID 打 tag 会与该消息
         // 的既有快照碰撞，故用独立前缀的时间戳 tag——不进 index.json
         // （列表不展示），但孤儿重建/手动 git tag 仍能找到它，误回退后
         // 用户可让插件从该 tag 恢复，堵住唯一的不可逆操作缺口。
-        const snap = state.snapshots.get(id)
-        if (!snap) return { ok: false, code: 'NO_SNAPSHOT', message: '该消息没有可用的项目快照' }
-        const store = state.stores.get(snap.root)
-        if (!store) return { ok: false, code: 'NO_STORE', message: '快照存储不可用' }
         const safetyId = 'pre-rollback-' + Date.now()
         try {
           await rt.runShell(rt.scripts.snapshotScript(snap.root, store, state.gitExe, safetyId, cfg.baseExcludes), { timeoutMs: 600000, stdoutMaxBytes: 65536 })
@@ -628,8 +688,12 @@ export function apply(ctx, config) {
           gcSnaps: cfg.gcSnaps,
           gcHours: cfg.gcHours,
           maxFileBytes: cfg.maxFileBytes,
+          maxSnapshotsPerWorkspace: cfg.maxSnapshotsPerWorkspace,
           baseExcludes: cfg.baseExcludes.slice(),
           refillDraft: cfg.refillDraft,
+          snapshotEnabled: cfg.snapshotEnabled,
+          archiveOriginal: cfg.archiveOriginal,
+          retentionDays: cfg.retentionDays,
         },
         overridden,
         envLocks,
@@ -646,7 +710,21 @@ export function apply(ctx, config) {
       if (patch.gcSnaps !== undefined) clean.gcSnaps = Number(patch.gcSnaps)
       if (patch.gcHours !== undefined) clean.gcHours = Number(patch.gcHours)
       if (patch.maxFileBytes !== undefined) clean.maxFileBytes = Number(patch.maxFileBytes)
+      if (patch.maxSnapshotsPerWorkspace !== undefined) {
+        const n = Number(patch.maxSnapshotsPerWorkspace)
+        // 0 或负值 = 不限制（schema 由 number 校验，非法 NaN 在 settings.write 层被拒）
+        if (!Number.isFinite(n)) return { ok: false, code: 'BAD_TYPE', message: '快照总量上限必须是数字' }
+        clean.maxSnapshotsPerWorkspace = Math.max(0, n)
+      }
       if (patch.refillDraft !== undefined) clean.refillDraft = Boolean(patch.refillDraft)
+      if (patch.snapshotEnabled !== undefined) clean.snapshotEnabled = Boolean(patch.snapshotEnabled)
+      if (patch.archiveOriginal !== undefined) clean.archiveOriginal = Boolean(patch.archiveOriginal)
+      if (patch.retentionDays !== undefined) {
+        const n = Number(patch.retentionDays)
+        // 0/负值 = 不启用（schema 校验 base 由 number 承担，NaN 由 settings.write 拒）
+        if (!Number.isFinite(n) || n < 0) return { ok: false, code: 'BAD_TYPE', message: '保留天数必须是 >= 0 的数字（0 表示不启用）' }
+        clean.retentionDays = Math.trunc(n)
+      }
       if (patch.baseExcludes !== undefined) {
         if (!Array.isArray(patch.baseExcludes)) return { ok: false, code: 'BAD_TYPE', message: 'baseExcludes 必须是字符串数组' }
         clean.baseExcludes = patch.baseExcludes.filter((p) => typeof p === 'string' && p.trim())
@@ -673,8 +751,13 @@ export function apply(ctx, config) {
       const sessionId = args && args.sessionId ? String(args.sessionId) : null
       if (op === 'list') {
         // 结果缓存（30s + 删除/新快照失效）：设置页反复打开、删除后刷新
-        // 都会重拉列表，缓存让二次打开零 shell。
-        if (listCache.payload && Date.now() - listCache.at < 30000) return listCache.payload
+        // 都会重拉列表，缓存让二次打开零 shell。缓存存的是全量排序数组，
+        // 响应按请求的 limit 切片——「加载更多」无需重扫磁盘（S1-2）。
+        const limitRaw = args && args.limit !== undefined ? Number(args.limit) : 200
+        const safeLimit = Math.min(Math.max(Number.isFinite(limitRaw) ? Math.trunc(limitRaw) : 200, 1), 2000)
+        if (listCache.items && Date.now() - listCache.at < 30000) {
+          return { ok: true, items: listCache.items.slice(0, safeLimit), total: listCache.items.length }
+        }
         const allItems = []
 
         // 磁盘全量：一条 shell dump（dumpStores 见其注释——旧实现每目录
@@ -732,9 +815,8 @@ export function apply(ctx, config) {
         }
 
         allItems.sort((a, b) => (b.time || 0) - (a.time || 0))
-        const payload = { ok: true, items: allItems.slice(0, 200), total: allItems.length }
-        listCache = { at: Date.now(), payload }
-        return payload
+        listCache = { at: Date.now(), items: allItems }
+        return { ok: true, items: allItems.slice(0, safeLimit), total: allItems.length }
       }
       if (op === 'titles') {
         // 冷会话标题补齐（Client 异步二次请求）：readSession 整日志解压 +
@@ -812,12 +894,18 @@ export function apply(ctx, config) {
       }
       if (op === 'usage') {
         let bytes = 0
+        // 存储健康统计（S2-4）：仅对内存已知 store 计数——与汇总同源，
+        // 冷启动预热未完成时不完整，属已知限制（见 plan-settings-ux S2-4）
+        let homeStores = 0
+        let fallbackStores = 0
         if (sessionId) {
           // 旧调用方（带会话上下文）：单工作区占用
           const root = await rt.resolveRoot(sessionId)
           if (!root) return { ok: false, code: 'NO_ROOT', message: '无法解析当前工作区' }
           const store = state.stores.get(root)
           if (!store) return { ok: false, code: 'NO_STORE', message: '当前工作区尚未创建快照存储' }
+          if (store.home) homeStores++
+          else fallbackStores++
           const out = await rt.runShell(rt.scripts.diskUsageScript(store.dir), { stdoutMaxBytes: 4096 })
           bytes = parseInt(rt.scripts.stripBom(out).trim(), 10) || 0
         } else {
@@ -826,13 +914,15 @@ export function apply(ctx, config) {
           // 不影响汇总，best-effort。
           for (const store of state.stores.values()) {
             if (!store || !store.dir) continue
+            if (store.home) homeStores++
+            else fallbackStores++
             try {
               const out = await rt.runShell(rt.scripts.diskUsageScript(store.dir), { stdoutMaxBytes: 4096 })
               bytes += parseInt(rt.scripts.stripBom(out).trim(), 10) || 0
             } catch (error) { /* 单 store 失败跳过 */ }
           }
         }
-        return { ok: true, bytes }
+        return { ok: true, bytes, gitAvailable: state.gitExe !== '', homeStores, fallbackStores }
       }
       if (op === 'delete') {
         // 统一删除入口：scope=workspace 删除整个工作区全部快照；
@@ -889,7 +979,7 @@ export function apply(ctx, config) {
           state.snapshots.delete(id)
           await snaps.saveIndex(finalRoot, sessionId)
           // 列表缓存失效：Client 删除后会立刻 refresh，必须看到最新状态
-          listCache.payload = null
+          listCache.items = null
         })
         return { ok: true }
       }
@@ -916,8 +1006,44 @@ export function apply(ctx, config) {
       return { ok: false, code: 'UNKNOWN_OP', message: '未知的管理操作: ' + op }
     },
 
-    // 设置页排障：最近错误（Host 侧 console.error 的页面可见副本）
-    'status': async () => ({ ok: true, errors: state.errors.slice(-20).reverse() })
+    // 设置页「插件配置」卡片恢复默认：整段清空 user 层回组合 base——官方
+    // settings RPC 的 replace 明确是「restoration/reset 路径」（section:{}
+    // 重置为组合默认，见 dsh-host-apiproxy api/settings.d.ts S1-3 核验）。
+    // 比逐字段写默认值干净：重置后字段不再被标 user-overridden，schema 或
+    // cordis patch 行默认值变更时 reset 跟随，不冻结历史值。老版本服务
+    // 没有 replace 时降级 settings.update 写 DEFAULTS（user 层仍出现标记，
+    // 行为等价，缺陷见 plan-settings-ux S1-3）。
+    'config-reset': async () => {
+      let settings = null
+      try { settings = ctx.get('settings') } catch (error) { settings = null }
+      if (!settings || typeof settings.update !== 'function') {
+        return { ok: false, code: 'SETTINGS_UNAVAILABLE', message: '设置服务不可用：请在 profile 的 cordis.patch.yml 按 id: recall 覆盖配置' }
+      }
+      try {
+        if (typeof settings.replace === 'function') {
+          await settings.replace('dsh-recall', {})
+        } else {
+          await settings.update('dsh-recall', Object.assign({}, DEFAULTS, { baseExcludes: DEFAULTS.baseExcludes.slice() }))
+        }
+      } catch (error) {
+        return { ok: false, code: 'SETTINGS_WRITE_FAILED', message: '恢复默认失败：' + String(error && error.message ? error.message : error) }
+      }
+      // 重置后热更运行中的 cfg（与 config-set 同链路的 watch 触发，这里做
+      // 双保险：descriptor 已变更，applyResolvedConfig 立即落地）
+      applyResolvedConfig(readSettings())
+      return { ok: true }
+    },
+
+    // 设置页排障：最近错误（Host 侧 console.error 的页面可见副本）。
+    // S3-5：支持 { op: 'clear' } 清空页面可见缓冲——只清 state.errors，
+    // 不影响 console 本身的留痕；清空后设置页「最近错误」为空。
+    'status': async (args) => {
+      if (args && args.op === 'clear') {
+        state.errors.length = 0
+        return { ok: true, errors: [] }
+      }
+      return { ok: true, errors: state.errors.slice(-20).reverse() }
+    }
   }
 
   ctx.effect(() => webServer.register({
@@ -955,9 +1081,12 @@ export function apply(ctx, config) {
     const messageId = data.id
     const time = event.time
     state.queue = state.queue
-      .then(() => snaps.captureSnapshot(session.id, messageId, time))
+      // 快照总开关（S2-1）：cfg 按调用时读取，设置页热更即时生效。
+      // 关闭时只冻结新建，maybeMaintain 照常跑——已停增的存储仍需被
+      // gc/清理治理。
+      .then(() => (cfg.snapshotEnabled ? snaps.captureSnapshot(session.id, messageId, time) : null))
       .then(() => maint.maybeMaintain(session.id))
-      .then(() => { listCache.payload = null })
+      .then(() => { listCache.items = null })
       .catch((error) => rt.recordError('recall snapshot error: ' + String(error)))
   })