dsh-recall-plugin 1.0.3 → 1.2.0

package/lib/scripts.pwsh.js

@@ -0,0 +1,334 @@
+/**
+ * dsh-recall-plugin — PowerShell 脚本模板（纯函数，无 ctx 依赖，win32 专用）
+ *
+ * 职责：集中拼装所有发给 shell 的 PowerShell 脚本文本。只做字符串构造，
+ * 不执行、无状态；执行侧（runShell）见 store.js，调用侧见
+ * snapshots.js / maintenance.js。集中在这里是为了：
+ * 1) PS 5.1 / pwsh 7 双版本兼容的坑只在一处处理；
+ * 2) 脚本片段（gitlink 清理、超大文件排除、用户排除同步）在多个
+ *    流程里逐字复用，散落各处必然改漏。
+ * POSIX（Linux/macOS）对应模板见 scripts.posix.js，两者导出同名接口，
+ * 由 store.js 按 process.platform 选择。
+ */
+
+// 单引号字面量转义：PS 单引号串里只有 '' 表示一个单引号，且不展开变量，
+// 是把 JS 值安全嵌进命令串的唯一可靠方式（杜绝 $、反引号注入）。
+export function psq(value) {
+  return "'" + String(value).replace(/'/g, "''") + "'"
+}
+
+// 统一 UTF-8 输出前导：中文等非 ASCII 机器的默认代码页（如 GBK）下，
+// PowerShell 重定向 stdout 按 [Console]::OutputEncoding 编码，而 DSH 按
+// UTF-8 解码——不强制时含中文的用户名/路径会变乱码。PS 5.1 / 7 均支持。
+export const UTF8_PRELUDE = '$OutputEncoding = [Text.UTF8Encoding]::new($false)\ntry { [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false) } catch {}'
+
+// 与 TraeWork 同级的超大文件跳过阈值：git 对象库对大文件极不友好，
+// 回退语义也不该被一个 200MB 的构建产物拖垮。
+export const MAX_FILE_BYTES = 104857600
+
+// 去除 PS 5.1 Set-Content -Encoding utf8 写出的 BOM：JSON 解析前必须剥掉，
+// 否则 JSON.parse 把 BOM 当正文首字符直接抛错。
+export function stripBom(text) {
+  return text.replace(/^\uFEFF/, '')
+}
+
+// 嵌套 git 仓库（工作区里的子项目自带 .git）会被 add -A 记成 gitlink（160000）；
+// gitlink 残留在 index 时 add -A 会 fatal "in unpopulated submodule"，
+// 且 gitlink 对文件回退毫无意义——所以 add 前后各清一次，子仓库内容不进快照。
+// 依赖外层脚本已定义的 $git/$g；被 snapshot/diff/rollback 三处复用。
+function dropGitlinksBlock() {
+  return [
+    "& $git --git-dir=$g ls-files --stage | Where-Object { $_ -like '160000*' } | ForEach-Object {",
+    "  $p = ($_ -split \"`t\")[1]",
+    '  & $git --literal-pathspecs --git-dir=$g update-index --force-remove -- $p',
+    '}'
+  ].join('\n')
+}
+
+// 剔除超大文件：扫描加 SilentlyContinue 是因为 EAP=Stop 下个别不可访问
+// 子目录（杀软锁定、异常 ACL、损坏 junction）的非致命错误会被升级为终止，
+// 整条快照作废；本扫描只用于排除超大文件，漏看个别文件是 fail-open，可接受。
+// 依赖外层已定义的 $git/$g/$root。
+function oversizeBlock() {
+  return [
+    'Get-ChildItem -LiteralPath $root -Recurse -File -Force -ErrorAction SilentlyContinue | Where-Object { $_.Length -gt ' + MAX_FILE_BYTES + ' } | ForEach-Object {',
+    "  $rel = $_.FullName.Substring($root.Length + 1).Replace('\\','/')",
+    '  & $git --literal-pathspecs --git-dir=$g update-index --force-remove -- $rel',
+    '}'
+  ].join('\n')
+}
+
+// 用户自定义排除同步：把基础排除表与用户 exclude.txt 合并重写进 info/exclude，
+// 再用 ls-files -i -c 找出「已被跟踪但命中排除」的条目从 index 清掉。
+// - 只用 --exclude-from 指 info/exclude，不用 --exclude-standard：后者会
+//   连带项目自己的 .gitignore 语义（后加 ignore 的已跟踪文件会被悄悄移出
+//   快照），行为超出用户配置的本意。
+// - 放在 add -A 之前：排除表先生效，新增的排除路径根本不会被暂存，
+//   已跟踪的旧条目由 ls-files -i -c 补刀，两条路径一次覆盖。
+// - 首行留空元素吸收 PS 5.1 utf8 BOM（BOM 粘在首行会废掉第一条模式），
+//   与下方 ensureGitScript 的老技巧一致。
+// - 依赖外层已定义的 $git/$g；被 ensureGit/snapshot/diff/rollback 复用，
+//   因此 exclude.txt 的改动在下一次快照/diff/回退时即时生效，无需重启。
+function excludeSyncBlock(excludeFile) {
+  return [
+    "$exFile = " + psq(excludeFile),
+    '$userPats = @()',
+    "if (Test-Path -LiteralPath $exFile) { $userPats = @(Get-Content -LiteralPath $exFile -Encoding UTF8 -ErrorAction SilentlyContinue | Where-Object { $t = $_.Trim(); $t -and -not $t.StartsWith('#') }) }",
+    "$lines = @('') + @('.git','node_modules/','.dsh-recall-snapshots/') + $userPats",
+    "$exc = Join-Path $g 'info\\exclude'",
+    'Set-Content -LiteralPath $exc -Value $lines -Encoding utf8',
+    '& $git -c core.quotePath=false --literal-pathspecs --git-dir=$g ls-files -i -c --exclude-from=$exc | ForEach-Object {',
+    '  if ($_) { & $git --literal-pathspecs --git-dir=$g update-index --force-remove -- $_ }',
+    '}'
+  ].join('\n')
+}
+
+// 解析 git 可执行文件路径：DSH 进程 PATH 可能不含 git，脚本里用绝对路径调用。
+// 逐项判空再 Join-Path：个别 env 在特殊环境（32 位系统无 ProgramFiles(x86)）
+// 取到 null，EAP=Stop 下 Join-Path 抛错会让整个探测失败、误报 gitMissing。
+export function resolveGitScript() {
+  return [
+    '$candidates = @()',
+    '$g = (Get-Command git -ErrorAction SilentlyContinue).Source',
+    'if ($g) { $candidates += $g }',
+    "if (${env:ProgramFiles}) { $candidates += (Join-Path ${env:ProgramFiles} 'Git\\cmd\\git.exe') }",
+    "if (${env:ProgramFiles(x86)}) { $candidates += (Join-Path ${env:ProgramFiles(x86)} 'Git\\cmd\\git.exe') }",
+    "if (${env:LocalAppData}) { $candidates += (Join-Path ${env:LocalAppData} 'Programs\\Git\\cmd\\git.exe') }",
+    "$g = $candidates | Where-Object { $_ -and (Test-Path -LiteralPath $_ -PathType Leaf) } | Select-Object -First 1",
+    'if ($g) { Write-Output $g }'
+  ].join('\n')
+}
+
+// 计算项目对应的 home 存储目录（DSH_HOME 优先，否则 ~/.dsh）。
+// 哈希用 Create()+ComputeHash+BitConverter 而不是 HashData+ToHexString：
+// 后两者是 .NET 5+（仅 PS 7）API，别人机器的 shell 若是 Windows PowerShell
+// 5.1 会抛错，导致 home 存储永远降级到项目内；前者两个版本都可用。
+export function homeDirScript(root, envHome) {
+  return [
+    '$r = ' + psq(root),
+    "$h = if ($env:DSH_HOME) { $env:DSH_HOME } elseif (" + psq(envHome) + ") { " + psq(envHome) + " } else { Join-Path $env:USERPROFILE \".dsh\" }",
+    '$sha = [Security.Cryptography.SHA256]::Create()',
+    "$hex = ([BitConverter]::ToString($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($r))) -replace '-','').ToLower()",
+    "Write-Output (Join-Path $h ('dsh-recall-snapshots\\' + $hex))"
+  ].join('\n')
+}
+
+export function mkdirScript(dir) {
+  return 'New-Item -ItemType Directory -Force -Path ' + psq(dir) + ' | Out-Null'
+}
+
+// 旧版迁移：把降级时代落在项目内的影子仓库整体搬回 home 并删源目录
+export function migrateScript(src, dst) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$src = ' + psq(src),
+    '$dst = ' + psq(dst),
+    "if (Test-Path -LiteralPath (Join-Path $src 'git')) { Move-Item -LiteralPath (Join-Path $src 'git') -Destination (Join-Path $dst 'git') -Force }",
+    "if (Test-Path -LiteralPath (Join-Path $src 'index.json')) { Move-Item -LiteralPath (Join-Path $src 'index.json') -Destination (Join-Path $dst 'index.json') -Force }",
+    'Remove-Item -Recurse -Force -LiteralPath $src -ErrorAction SilentlyContinue',
+    "Write-Output 'MIGRATE_OK'"
+  ].join('\n')
+}
+
+// 建立影子仓库：普通 init（index 留在仓库内跨快照复用，git add 的 stat 缓存
+// 让未变文件近乎零成本），core.longpaths 放开 Windows 深路径。
+// autocrlf=false：按原始字节入快照（回退时逐字节还原），也避免用户全局
+// autocrlf=true 时的 LF/CRLF stderr 警告；addEmbeddedRepo=false：嵌套仓库
+// hint/warning 走 stderr，在 DSH shell（EAP=Stop）下会让整条脚本非零退出，
+// 必须在仓库级配置里静默掉。
+// 结尾回读 gc.stamp（maintenance.js 上次 gc 时间戳）：让重启后的 gc 节流
+// 不归零——没有它，天天重启 DSH 的用户每次开机第一条消息都会触发一次
+// 全量 gc，纯浪费。
+export function ensureGitScript(store, gitExe) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$repo = ' + psq(store.repo),
+    '$g = ' + psq(store.git),
+    'if (-not (Test-Path -LiteralPath $g)) {',
+    '  & $git init $repo | Out-Null',
+    '}',
+    '& $git --git-dir=$g config core.longpaths true',
+    '& $git --git-dir=$g config core.autocrlf false',
+    '& $git --git-dir=$g config advice.addEmbeddedRepo false',
+    excludeSyncBlock(store.excludeFile),
+    "$stamp = Join-Path $g 'gc.stamp'",
+    "if (Test-Path -LiteralPath $stamp) { Write-Output ('GIT_OK ' + [String](Get-Content -LiteralPath $stamp -TotalCount 1 -ErrorAction SilentlyContinue)) } else { Write-Output 'GIT_OK' }"
+  ].join('\n')
+}
+
+// 快照：git add -A 增量同步 index（.gitignore/exclude 语义由 git 统一处理），
+// write-tree 生成树、commit-tree 生成无父孤儿提交、tag 保对象可达。
+// 不做 parent 链、不修剪：像 TraeWork 一样保留全量历史，tag 永远可查。
+export function snapshotScript(root, store, gitExe, messageId) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    '$root = ' + psq(root),
+    dropGitlinksBlock(),
+    excludeSyncBlock(store.excludeFile),
+    '& $git --git-dir=$g --work-tree=$root add -A',
+    dropGitlinksBlock(),
+    oversizeBlock(),
+    '$tree = (& $git --git-dir=$g --work-tree=$root write-tree).Trim()',
+    "$commit = (& $git --git-dir=$g -c user.name=dsh-recall -c user.email=recall@dsh.local commit-tree $tree -m ('snapshot ' + " + psq(messageId) + ")).Trim()",
+    '& $git --git-dir=$g tag ' + psq('snap-' + messageId) + ' $commit | Out-Null',
+    "Write-Output 'SNAP_OK'"
+  ].join('\n')
+}
+
+// diff：把当前状态 add 进 index 后用 ls-files --stage 取当前清单，
+// 与目标 tag 的 ls-tree 对比——ignore/exclude 语义两侧一致，不会把
+// node_modules 等误报为“新增”。
+// 不用 -z：PowerShell 捕获原生命令输出会丢弃含 NUL 的行（实测整段变 null），
+// 改用 core.quotePath=false 让非 ASCII 路径原样输出，逐行按 TAB 解析。
+// 代价是文件名含换行的极端情况会解析错乱——概率可忽略，记录为已知限制。
+// （UTF-8 输出编码由 runShell 注入的 UTF8_PRELUDE 统一保证，此处不再重复设置。）
+export function diffScript(root, store, gitExe, tag) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    '$root = ' + psq(root),
+    dropGitlinksBlock(),
+    excludeSyncBlock(store.excludeFile),
+    '& $git --git-dir=$g --work-tree=$root add -A',
+    dropGitlinksBlock(),
+    oversizeBlock(),
+    '$curOut = & $git -c core.quotePath=false --git-dir=$g --work-tree=$root ls-files --stage',
+    // 旧 tag 的树里可能仍有 gitlink（修复前留下的），从目标侧一并剔除，
+    // 否则 diff 会报出“恢复 dsh-recall-plugin”这类幻影条目
+    "$targetOut = @(& $git -c core.quotePath=false --git-dir=$g ls-tree -r " + psq(tag) + " | Where-Object { -not $_.StartsWith('160000') })",
+    '$curMap = @{}',
+    'foreach ($r in @($curOut)) {',
+    '  if (-not $r) { continue }',
+    '  $tab = $r.IndexOf("`t"); $path = $r.Substring($tab + 1)',
+    '  $sha = ($r.Substring(0, $tab) -split " ")[1]',
+    '  $curMap[$path] = $sha',
+    '}',
+    '$targetMap = @{}',
+    'foreach ($r in @($targetOut)) {',
+    '  if (-not $r) { continue }',
+    '  $tab = $r.IndexOf("`t"); $path = $r.Substring($tab + 1)',
+    '  $sha = ($r.Substring(0, $tab) -split " ")[2]',
+    '  $targetMap[$path] = $sha',
+    '}',
+    '$result = @()',
+    'foreach ($k in $curMap.Keys) {',
+    '  if (-not $targetMap.ContainsKey($k)) { $result += [pscustomobject]@{ rel = $k; kind = "added" } }',
+    '  elseif ($targetMap[$k] -ne $curMap[$k]) { $result += [pscustomobject]@{ rel = $k; kind = "modified" } }',
+    '}',
+    'foreach ($k in $targetMap.Keys) {',
+    '  if (-not $curMap.ContainsKey($k)) { $result += [pscustomobject]@{ rel = $k; kind = "restored" } }',
+    '}',
+    '$sorted = @($result | Sort-Object rel)',
+    'Write-Output (ConvertTo-Json -InputObject $sorted -Depth 3 -Compress)'
+  ].join('\n')
+}
+
+// 回退：archive 生成 zip 直接落盘（二进制不经 shell 文本管道），
+// Expand-Archive 覆盖回工作区；再删除“当前有、目标无”的文件。
+// 空树跳过 archive（空 zip 会让 Expand-Archive 报错），只执行删除。
+// 回退后保留快照 tag 与索引：git delta 空间便宜，保留历史可再次
+// 用该快照恢复（幂等），也避免误回退后无法找回。
+export function rollbackScript(root, store, gitExe, tag) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    '$root = ' + psq(root),
+    dropGitlinksBlock(),
+    excludeSyncBlock(store.excludeFile),
+    '& $git --git-dir=$g --work-tree=$root add -A',
+    dropGitlinksBlock(),
+    oversizeBlock(),
+    // 同 diffScript：-z 的 NUL 输出会被 PowerShell 捕获丢弃，改为逐行 + quotePath=false
+    '$curOut = & $git -c core.quotePath=false --git-dir=$g --work-tree=$root ls-files --stage',
+    "$targetOut = @(& $git -c core.quotePath=false --git-dir=$g ls-tree -r " + psq(tag) + " | Where-Object { -not $_.StartsWith('160000') })",
+    '$targetMap = @{}',
+    'foreach ($r in @($targetOut)) {',
+    '  if (-not $r) { continue }',
+    '  $tab = $r.IndexOf("`t"); $path = $r.Substring($tab + 1)',
+    '  $targetMap[$path] = $true',
+    '}',
+    '$restored = $targetMap.Count',
+    'if ($restored -gt 0) {',
+    '  $zip = ' + psq(store.dir + '\\restore-tmp.zip'),
+    '  & $git --git-dir=$g archive --format=zip --output=$zip ' + psq(tag),
+    '  Expand-Archive -LiteralPath $zip -DestinationPath $root -Force',
+    '  Remove-Item -LiteralPath $zip -Force',
+    '}',
+    '$deleted = 0',
+    'foreach ($r in @($curOut)) {',
+    '  if (-not $r) { continue }',
+    '  $tab = $r.IndexOf("`t"); $path = $r.Substring($tab + 1)',
+    '  if (-not $targetMap.ContainsKey($path)) {',
+    "    $full = Join-Path $root ($path.Replace('/','\\'))",
+    '    if (Test-Path -LiteralPath $full) { Remove-Item -LiteralPath $full -Force; $deleted++ }',
+    '  }',
+    '}',
+    "Write-Output ('ROLLBACK_OK ' + $deleted + ' ' + $restored)"
+  ].join('\n')
+}
+
+export function listTagsScript(store, gitExe) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    '& $git --git-dir=$g tag -l "snap-*"'
+  ].join('\n')
+}
+
+// 定期 gc：全量保留策略下对象只增不减，且默认 loose 存储（每对象一个
+// 小文件，NTFS 最小簇 4KB）非常浪费；gc 压 pack + 跨版本 delta 通常省一半
+// 以上。--prune=now 让「会话删除联动清理」删掉的 tag 立即真正释放空间
+// （默认 2 周宽限期内对象仍占盘）——安全前提是 gc 与快照在同一条串行
+// 队列里执行（见 maintenance.js），不存在并发竞态。
+// 结尾写 gc.stamp：跨重启的节流凭据（ensureGit 回读）。
+export function gcScript(store, gitExe) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    '& $git --git-dir=$g gc --quiet --prune=now',
+    "Set-Content -LiteralPath (Join-Path $g 'gc.stamp') -Value ([DateTimeOffset]::UtcNow.ToUnixTimeSeconds().ToString()) -Encoding ascii",
+    "Write-Output 'GC_OK'"
+  ].join('\n')
+}
+
+// 删除指定快照 tag（会话已删联动清理用）。best-effort：个别 tag 已不存在时
+// git 非零退出，但其余 tag 已被删除——所以显式 exit 0 吞掉退出码，
+// 残留的由下一次清理幂等地收尾；JS 侧无论脚本结果都会同步索引。
+export function purgeTagsScript(store, gitExe, tags) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    '& $git --git-dir=$g tag -d ' + tags.map((t) => psq(t)).join(' '),
+    "Write-Output 'PURGE_DONE'",
+    'exit 0'
+  ].join('\n')
+}
+
+// 索引写入：base64 以内联字面量传递时受 Windows 命令行 32767 字符硬上限
+// 约束（DSH 的 pwsh 执行器把命令串作为 -Command 的单个 argv 元素 spawn），
+// 快照攒到几百条就会超限 spawn 失败——按 20000 字符分块，首块 Set-Content、
+// 续块 Add-Content。piece 为当前块的 base64 解码表达式，first 决定覆盖还是追加。
+export function indexWriteCmd(dir, piece, first) {
+  const file = psq(dir + '\\index.json')
+  if (first) {
+    return 'New-Item -ItemType Directory -Force -Path ' + psq(dir) + ' | Out-Null; ' + piece + 'Set-Content -LiteralPath ' + file + ' -Encoding utf8 -NoNewline'
+  }
+  return piece + 'Add-Content -LiteralPath ' + file + ' -Encoding utf8 -NoNewline'
+}
+
+export function indexReadCmd(dir) {
+  return 'Get-Content -LiteralPath ' + psq(dir + '\\index.json') + ' -Raw -ErrorAction SilentlyContinue'
+}
+
+// 旧版项目内 blobs 目录清理（仅 home 存储可用时调用，见 store.js cleanupLegacy）
+export function legacyRmScript(path) {
+  return 'Remove-Item -Recurse -Force -LiteralPath ' + psq(path)
+}

package/lib/snapshots.js

@@ -0,0 +1,192 @@
+/**
+ * dsh-recall-plugin — 快照域（ctx 绑定的工厂，无模块级副作用）
+ *
+ * 职责：快照捕获（captureSnapshot）、索引落盘/载入/孤儿重建、
+ * diff 清单（diffFor）、回退执行（rollbackFor）、会话切点解析
+ * （resolveCutSeq）。依赖 store.js 的执行与存储层，脚本文本全部
+ * 来自 rt.scripts（按平台选择的 scripts.pwsh.js / scripts.posix.js）。
+ */
+
+export function createSnapshots(ctx, rt) {
+  const sessions = ctx.sessions
+  const state = rt.state
+  // 平台选择的脚本模板（rt.scripts = scripts.pwsh.js / scripts.posix.js）：
+  // 两套导出同名接口但实现分属 pwsh/bash，所有调用统一走 S.*
+  const S = rt.scripts
+
+  // 索引落盘。win32：base64 分块内联（见 scripts.pwsh.js indexWriteCmd 注释，
+  // 受 Windows 命令行 32767 字符上限约束）。POSIX：官方 ShellExecRequest
+  // 的 stdin 契约字段直写全文——不经命令行传参，没有 argv 长度上限，
+  // 也省掉 base64 往返；单次调用即完成。
+  async function saveIndex(root, sessionId) {
+    const store = state.stores.get(root)
+    if (!store) return
+    const entries = Array.from(state.snapshots.entries())
+      .filter(([, s]) => s.root === root)
+      .map(([id, s]) => ({ id, time: s.time, count: s.count, sessionId: s.sessionId }))
+    const json = JSON.stringify(entries)
+    try {
+      if (rt.isWin) {
+        const b64 = Buffer.from(json, 'utf8').toString('base64')
+        let first = true
+        for (let i = 0; i < b64.length; i += 20000) {
+          const piece = "[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('" + b64.slice(i, i + 20000) + "')) | "
+          await rt.runShell(S.indexWriteCmd(store.dir, piece, first), { stdoutMaxBytes: 4096 })
+          first = false
+        }
+      } else {
+        await rt.runShell('cat > ' + S.psq(store.dir + '/index.json'), { stdin: json, stdoutMaxBytes: 4096 })
+      }
+    } catch (error) {
+      console.error('recall saveIndex failed:', String(error))
+    }
+  }
+
+  async function loadIndex(root, sessionId) {
+    if (state.indexLoaded.has(root)) return
+    state.indexLoaded.add(root)
+    const store = state.stores.get(root)
+    if (!store) return
+    try {
+      const raw = S.stripBom(await rt.runShell(S.indexReadCmd(store.dir), { stdoutMaxBytes: 4194304 })).trim()
+      if (!raw) return
+      const entries = JSON.parse(raw)
+      if (!Array.isArray(entries)) return
+      for (const entry of entries) {
+        if (!entry || typeof entry.id !== 'string') continue
+        state.snapshots.set(entry.id, {
+          root,
+          time: typeof entry.time === 'number' ? entry.time : Date.now(),
+          count: typeof entry.count === 'number' ? entry.count : 0,
+          sessionId: entry.sessionId || sessionId
+        })
+      }
+    } catch (error) {
+      /* 索引缺失或损坏时按空历史处理 */
+    }
+  }
+
+  // 索引丢失时从仓库 tag 重建：tag 名 snap-<messageId> 本身就是快照主键
+  async function rebuildOrphans(root, sessionId) {
+    const store = state.stores.get(root)
+    const gitExe = await rt.resolveGit()
+    if (!store || !gitExe) return
+    try {
+      const listing = S.stripBom(await rt.runShell(S.listTagsScript(store, gitExe), { stdoutMaxBytes: 4194304 })).trim()
+      if (!listing) return
+      for (const name of listing.split(/\r?\n/)) {
+        const id = name.trim().replace(/^snap-/, '')
+        if (!id || state.snapshots.has(id)) continue
+        state.snapshots.set(id, { root, time: 0, count: 0, sessionId })
+      }
+      await saveIndex(root, sessionId)
+    } catch (error) {
+      console.error('recall rebuildOrphans failed:', String(error))
+    }
+  }
+
+  async function captureSnapshot(sessionId, messageId, time) {
+    const root = await rt.resolveRoot(sessionId)
+    if (!root) return
+    let store = await rt.resolveStore(root)
+    store = await rt.tryUpgradeToHome(root)
+    const ok = await rt.ensureGit(root, store)
+    if (!ok) return
+    await loadIndex(root, sessionId)
+    try {
+      await rt.runShell(S.snapshotScript(root, store, state.gitExe, messageId), { timeoutMs: 600000, stdoutMaxBytes: 65536 })
+      state.snapshots.set(String(messageId), { root, time: time || Date.now(), count: 0, sessionId })
+      await saveIndex(root, sessionId)
+    } catch (error) {
+      console.error('recall snapshot failed:', String(error))
+    }
+  }
+
+  // POSIX 侧 diff 输出是 TSV「kind<TAB>path」逐行（bash 模板不拼 JSON，
+  // 避免 jq 依赖与转义坑）；win32 侧是 ConvertTo-Json。这里按平台分叉解析。
+  function parseChanges(text) {
+    if (rt.isWin) {
+      const parsed = JSON.parse(text)
+      if (Array.isArray(parsed)) return parsed
+      if (parsed && typeof parsed === 'object') return [parsed]
+      return []
+    }
+    const out = []
+    for (const line of text.split(/\r?\n/)) {
+      if (!line) continue
+      const tab = line.indexOf('\t')
+      if (tab < 0) continue
+      out.push({ kind: line.slice(0, tab), rel: line.slice(tab + 1) })
+    }
+    return out
+  }
+
+  async function diffFor(messageId) {
+    const snap = state.snapshots.get(String(messageId))
+    if (!snap) return null
+    const store = state.stores.get(snap.root)
+    if (!store) return null
+    const text = S.stripBom(await rt.runShell(S.diffScript(snap.root, store, state.gitExe, 'snap-' + messageId), { timeoutMs: 600000, stdoutMaxBytes: 4194304 }))
+    const trimmed = text.trim()
+    if (!trimmed) return []
+    return parseChanges(trimmed)
+  }
+
+  async function rollbackFor(messageId) {
+    const snap = state.snapshots.get(String(messageId))
+    if (!snap) return { ok: false, error: '该消息没有可用的项目快照' }
+    const store = state.stores.get(snap.root)
+    if (!store) return { ok: false, error: '快照存储不可用' }
+    const text = S.stripBom(await rt.runShell(S.rollbackScript(snap.root, store, state.gitExe, 'snap-' + messageId), { timeoutMs: 600000, stdoutMaxBytes: 65536 }))
+    const m = text.trim().match(/^ROLLBACK_OK\s+(\d+)\s+(\d+)/)
+    const deleted = m ? parseInt(m[1], 10) : 0
+    const restored = m ? parseInt(m[2], 10) : 0
+    return { ok: true, count: (Number.isNaN(deleted) ? 0 : deleted) + (Number.isNaN(restored) ? 0 : restored) }
+  }
+
+  // 在事件序列里找“该消息之前最近一次 turn/end 的 seq”。
+  function scanCutSeq(events, messageId) {
+    let anchor = -1
+    for (let i = 0; i < events.length; i++) {
+      const e = events[i]
+      if (e && e.type === 'user/message' && e.data && String(e.data.id) === String(messageId)) {
+        anchor = i
+        break
+      }
+    }
+    if (anchor < 0) return null
+    for (let i = anchor - 1; i >= 0; i--) {
+      const e = events[i]
+      if (e && e.type === 'turn/end' && typeof e.seq === 'number') return e.seq
+    }
+    return null
+  }
+
+  // 解析“整段回退”的会话切点：优先读 live 会话的内存事件（零 IO、毫秒级），
+  // 冷会话回退到 sessionQuery.readSession；结果按 (会话, 消息) 缓存——
+  // 消息一旦入日志，其之前的 turn/end 永不变化，缓存终身有效。
+  async function resolveCutSeq(sessionId, messageId) {
+    if (!sessionId || !messageId) return null
+    const cacheKey = String(sessionId) + '\u0000' + String(messageId)
+    if (state.cutSeqCache.has(cacheKey)) return state.cutSeqCache.get(cacheKey)
+    let result = null
+    const live = sessions.get(sessionId)
+    if (live && Array.isArray(live.events)) {
+      result = scanCutSeq(live.events, messageId)
+    } else {
+      const query = ctx.get('sessionQuery')
+      if (query) {
+        try {
+          const log = await query.readSession(sessionId)
+          result = scanCutSeq(Array.isArray(log && log.events) ? log.events : [], messageId)
+        } catch (error) {
+          result = null
+        }
+      }
+    }
+    state.cutSeqCache.set(cacheKey, result)
+    return result
+  }
+
+  return { saveIndex, loadIndex, rebuildOrphans, captureSnapshot, diffFor, rollbackFor, resolveCutSeq }
+}