dsh-recall-plugin 2.0.0 → 2.1.0

package/lib/scripts.posix.js

@@ -30,6 +30,19 @@ export const UTF8_PRELUDE = 'export LC_ALL=C'
 // 实际生效值以 store.maxFileBytes（用户 config 可调）经 oversizeBlock 注入为准
 export const MAX_FILE_BYTES = 104857600
 
+// 失败清扫的 stale 锁阈值（分钟，M3）：锁文件 mtime 超过该值才视为残留可清；
+// 更新的锁视为「有 git 操作正在进行」让路。本插件单条快照/回退的超时是
+// 10 分钟，阈值取其一半，保证本方超时遗留的锁（≥10 分钟）一定能被清。
+// 与 pwsh 版必须同值（scripts-contract 钉）；属内部安全策略常量，与
+// snapshots.js 的 FUSE_AFTER 同类，不走 Config。
+export const STALE_LOCK_MIN = 5
+
+// 心跳文件有效窗口（秒，M3）：超过该时长的心跳视为失效实例（崩溃/重启
+// 遗留或长期空闲），不再阻止清扫。心跳随 ensureGit/快照刷新，活动中的
+// 实例窗口内必然有新心跳；长 git 操作（≤10 分钟）期间心跳写于操作开头，
+// 仍在窗口内。
+export const HEARTBEAT_TTL_S = 900
+
 // bash/cat 输出无 BOM；保留同名导出维持两套模板接口一致（幂等无害）
 export function stripBom(text) {
   return text.replace(/^\uFEFF/, '')
@@ -83,18 +96,31 @@ function excludeSyncBlock(excludeFile, base) {
     '  while IFS= read -r line || [ -n "$line" ]; do',
     "    t=${line%$'\\r'}",
     '    t="${t#"${t%%[![:space:]]*}"}"; t="${t%"${t##*[![:space:]]}"}"',
-    '    [ -z "$t" ] && continue',
+    '    if [ -z "$t" ]; then continue; fi',
     '    case "$t" in \\#*) continue ;; esac',
     '    user_pats="$user_pats$t\\n"',
     '  done < "$ex_file"',
     'fi',
     "printf '\\n" + baseLines.replace(/\\/g, '\\\\').replace(/%/g, '%%') + "%b' \"$user_pats\" > \"$exc\"",
     '"$git" -c core.quotePath=false --literal-pathspecs --git-dir="$g" ls-files -i -c --exclude-from="$exc" -z 2>/dev/null | while IFS= read -r -d \'\' p; do',
-    '  [ -n "$p" ] && "$git" --literal-pathspecs --git-dir="$g" update-index --force-remove -- "$p"',
+    '  if [ -n "$p" ]; then "$git" --literal-pathspecs --git-dir="$g" update-index --force-remove -- "$p"; fi',
     'done || true'
   ].join('\n')
 }
 
+// 心跳写入（M3）：随 git 操作顺手把「宿主 PID + epoch 秒」写进 store 目录
+// （store.dir = git-dir 上两级），供对方实例的失败清扫判定「另一个 DSH 实例
+// 正在使用此快照库」。PID 在模板生成期取宿主进程的 process.pid，无需调用方
+// 传参。fail-open（|| true，set -e 下安全）：心跳写失败绝不能连累快照本身
+// ——最坏退化为无心跳，清扫只剩新锁分级保护。
+// 依赖外层已定义的 $g；被 ensureGitScript / snapshotScript 复用。
+function heartbeatBlock() {
+  return [
+    'hbf="$(dirname "$(dirname "$g")")/heartbeat"',
+    'printf \'%s %s\\n\' ' + psq(String(process.pid)) + ' "$(date +%s)" > "$hbf" 2>/dev/null || true'
+  ].join('\n')
+}
+
 // 解析 git 可执行文件路径：bash 从 PATH 找（POSIX 上 git 装了就在 PATH，
 // 没有 Windows 那种四类安装位置的散装问题）
 export function resolveGitScript() {
@@ -132,6 +158,25 @@ export function migrateScript(src, dst) {
   ].join('\n')
 }
 
+// 旧快照容器一次性迁移（POSIX 专属，I24 漂移修复的存量数据兜底，输出四态
+// 由 store.js resolvePosixHomeBase 消费）：仅当「旧容器存在且新容器不存在」
+// 才整容器 mv——同卷（home 内部）rename 原子，无部分移动状态；容器级整移
+// 自然带上根级 exclude.txt，语义无损。BOTH_PRESENT（双容器并存）/MIGRATE_FAIL
+// 输出后不动任何数据。无 set -e（要靠分支输出状态而非中途退出）；if 条件
+// 内的 && 链豁免 I16 约束（该坑只针对循环体与裸列表）。非 git 命令，不适用
+// g= 赋值 / RECALL_CLEANUP 哨兵约定。
+export function legacyHomeMigrateScript(homedir) {
+  return [
+    'old=' + psq(homedir + '/dsh-recall-snapshots'),
+    'new=' + psq(homedir + '/.dsh/dsh-recall-snapshots'),
+    'if [ -d "$old" ] && [ ! -d "$new" ]; then',
+    '  if mkdir -p -- "$(dirname "$new")" && mv -f -- "$old" "$new"; then echo MIGRATE_OK',
+    '  else echo MIGRATE_FAIL; fi',
+    'elif [ -d "$old" ]; then echo BOTH_PRESENT',
+    'else echo OLD_ABSENT; fi'
+  ].join('\n')
+}
+
 // 建立影子仓库 + 排除同步 + 回读 gc.stamp（语义与 pwsh 版一致，
 // 见 scripts.pwsh.js 同名函数注释）
 export function ensureGitScript(store, gitExe, base) {
@@ -140,7 +185,19 @@ export function ensureGitScript(store, gitExe, base) {
     'git=' + psq(gitExe),
     'repo=' + psq(store.repo),
     'g=' + psq(store.git),
-    '[ -d "$g" ] || "$git" init "$repo" >/dev/null',
+    heartbeatBlock(),
+    // 冷启动首消息快照与启动预热（或双实例）并发时，两个 git init 在空
+    // repo 目录同跑，输家报 fatal: cannot mkdir <git>: File exists——窗口
+    // 极小但首条消息的快照会因此丢失。git init 幂等：失败后 HEAD 已出现
+    // 即同伴建成，视同成功继续；HEAD 也没有才是真失败，带错误退出（诊断
+    // 不丢）。检查 HEAD 而非目录存在：半截目录也会被 init 补齐。pwsh 版
+    // 无需同款改动——native 非零退出不抛（I14），输家继续跑 config 时
+    // 同伴已建好 repo，竞态天然容忍，真失败由快照 add 的显式检查兜底。
+    'if [ ! -f "$g/HEAD" ]; then',
+    '  init_log=$("$git" init "$repo" 2>&1) || {',
+    '    if [ ! -f "$g/HEAD" ]; then printf \'%s\\n\' "$init_log" >&2; exit 1; fi',
+    '  }',
+    'fi',
     '"$git" --git-dir="$g" config core.longpaths true',
     '"$git" --git-dir="$g" config core.autocrlf false',
     '"$git" --git-dir="$g" config advice.addEmbeddedRepo false',
@@ -159,6 +216,7 @@ export function snapshotScript(root, store, gitExe, messageId, base) {
     'git=' + psq(gitExe),
     'g=' + psq(store.git),
     'root=' + psq(root),
+    heartbeatBlock(),
     dropGitlinksBlock(),
     excludeSyncBlock(store.excludeFile, base),
     // fail-open add（issue #7 加固，语义见 pwsh 版同款注释）：--ignore-errors
@@ -240,6 +298,11 @@ export function diffScript(root, store, gitExe, tag, base) {
 // 回退：archive | tar 直接管到工作区（无需 Windows 的 zip 中转），
 // 空目标跳过；再删除「当前有、目标无」的文件（awk 求差集）。
 // pipefail 保证 git archive 失败时整条非零退出。
+// 删除侧失败必须响亮（F-G2）：set -e 豁免 if 条件内的 rm 失败——若写成
+// `rm ... && deleted++` 裸链，rm 失败（权限等）被静默跳过、脚本仍输出
+// ROLLBACK_OK，半回退报成功、救援永不触发；改为 if/fi + 失败显式 exit 1，
+// 与 pwsh 版「EAP=Stop 下 Remove-Item 抛终止错误」对齐「删除失败即失败」
+// 的语义（见 scripts.pwsh.js rollbackScript 同位置注释）。
 export function rollbackScript(root, store, gitExe, tag, base) {
   return [
     'set -e -o pipefail',
@@ -265,13 +328,31 @@ export function rollbackScript(root, store, gitExe, tag, base) {
     "' \"$tmpc\" \"$tmpt\" > \"$tmpd\"",
     'deleted=0',
     'while IFS= read -r p; do',
-    '  [ -z "$p" ] && continue',
-    '  rm -f -- "$root/$p" && deleted=$((deleted + 1))',
+    // 循环体禁裸 && 链（AGENTS.md 已知坑同款规矩）：&& 列表条件为假时整条
+    // 退出码为 1，set -e 会把脚本杀掉；if 语句天然豁免。rm 失败必须响亮
+    // exit 1——半回退假成功会让救援永不触发（F-G2）
+    '  if [ -z "$p" ]; then continue; fi',
+    '  if rm -f -- "$root/$p"; then deleted=$((deleted + 1)); else echo "RM_FAILED $p" >&2; exit 1; fi',
     'done < "$tmpd"',
     'echo "ROLLBACK_OK $deleted $restored"'
   ].join('\n')
 }
 
+// 回退失败救援（H1，语义见 pwsh 版同款注释）：reset --hard 回安全快照。
+// 入参 tag 是完整 tag 名（snap- 前缀由调用侧 rescueRollback 拼齐）。
+// set -e 下 git 非零退出自然终止脚本，与 pwsh 版 $LASTEXITCODE 显式自检
+// 对齐「失败即抛」语义。
+export function rescueScript(root, store, gitExe, tag) {
+  return [
+    'set -e',
+    'git=' + psq(gitExe),
+    'g=' + psq(store.git),
+    'root=' + psq(root),
+    '"$git" --git-dir="$g" --work-tree="$root" reset --hard ' + psq(tag),
+    'echo RESCUE_OK'
+  ].join('\n')
+}
+
 export function listTagsScript(store, gitExe) {
   return [
     'set -e',
@@ -284,6 +365,20 @@ export function listTagsScript(store, gitExe) {
   ].join('\n')
 }
 
+// 孤儿重建用 tag 清单（带 creatordate）：rebuildOrphans 据此恢复快照
+// 时间——只列 tag 名会让重建条目 time=0，管理列表时间前缀缺失、
+// retention/limits 按「最旧」误清。lightweight tag 无 tag 对象，
+// creatordate 即指向 commit 的提交日期。输出每行「<tag名> <秒级时间戳>」。
+export function listTagsWithTimeScript(store, gitExe) {
+  return [
+    'set -e',
+    'git=' + psq(gitExe),
+    'g=' + psq(store.git),
+    '[ -d "$g" ] || exit 0',
+    '"$git" --git-dir="$g" for-each-ref --format=\'%(refname:short) %(creatordate:unix)\' \'refs/tags/snap-*\''
+  ].join('\n')
+}
+
 // 定期 gc（语义同 pwsh 版）；date +%s 写秒级时间戳，JS 侧 ×1000
 export function gcScript(store, gitExe) {
   return [
@@ -308,28 +403,59 @@ export function pruneScript(store, gitExe) {
   ].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')
-}
-
+// 失败后的孤儿进程清扫 + stale 锁清理（issue #7 兜底 + issue #11 根因治理）。
+// 三级出口（M3）：
+// 1. CLEANUP_OTHER_INSTANCE <pid>——心跳文件（宿主 PID + epoch 秒）显示另一
+//    个存活实例正在使用同一快照库：直接让路，不杀进程、不动锁。这是两个
+//    DSH 实例并发互踩（一方清扫误杀另一方活跃 git → 对方也失败 → 循环）的
+//    根治；心跳由 ensureGit/snapshotScript 随操作刷新，TTL 外视为失效。
+// 2. CLEANUP_SKIPPED_FRESH_LOCK——存在 STALE_LOCK_MIN 分钟内的新锁（疑似有
+//    git 操作正在进行）：同样让路，锁陈旧后下次失败自然进入第 3 级。
+// 3. CLEANUP_DONE——两级保护均未命中，按原有行为清孤儿进程与 stale 锁。
+// POSIX 版差异：pgrep -f 按扩展正则匹配整条命令行——路径元字符（[、+ 等）
+// 会让模式失配，清扫静默失效，属安全降级（等价于本兜底加入前的行为）；
+// 标记在运行期拼接，本脚本自身命令行里只有未展开的 $g 字面量，不会自杀。
+// 全程无 set -e + 逐步容错：清扫自身的失败不能抛。mtime 判定用 find -mmin
+// 而非 stat：GNU/BSD stat 参数不同（macOS bash 3.2 约束），find 的 -mmin
+// 两平台语义一致。
+export function killOrphansScript(gitDir) {
+  return [
+    '# RECALL_CLEANUP',
+    'g=' + psq(gitDir),
+    'hbf="$(dirname "$(dirname "$g")")/heartbeat"',
+    'if [ -f "$hbf" ]; then',
+    '  hbl=$(head -n1 "$hbf" 2>/dev/null | tr -d \'\\r\')',
+    '  hbp=${hbl%% *}',
+    '  hbt=${hbl#* }',
+    "  case \"$hbp\" in ''|*[!0-9]*) hbp='' ;; esac",
+    "  case \"$hbt\" in ''|*[!0-9]*) hbt=0 ;; esac",
+    '  hbage=$(( $(date +%s) - hbt ))',
+    '  if [ -n "$hbp" ] && [ "$hbp" != ' + psq(String(process.pid)) + ' ] && [ "$hbage" -ge 0 ] && [ "$hbage" -lt ' + HEARTBEAT_TTL_S + ' ]; then',
+    '    if kill -0 "$hbp" 2>/dev/null; then',
+    '      echo "CLEANUP_OTHER_INSTANCE $hbp"',
+    '      exit 0',
+    '    fi',
+    '  fi',
+    'fi',
+    "fresh=$(find \"$g\" -maxdepth 1 -type f \\( -name '*.lock' -o -name 'gc.pid' \\) -mmin -" + STALE_LOCK_MIN + " 2>/dev/null; find \"$g/refs\" -type f -name '*.lock' -mmin -" + STALE_LOCK_MIN + ' 2>/dev/null)',
+    'if [ -n "$fresh" ]; then',
+    '  echo CLEANUP_SKIPPED_FRESH_LOCK',
+    '  exit 0',
+    'fi',
+    '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" -mmin +' + STALE_LOCK_MIN + ' -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) {
@@ -341,12 +467,24 @@ export function purgeTagsScript(store, gitExe, tags) {
   ].join('\n')
 }
 
+// 原子 rename（H2，语义见 pwsh 版同款注释）：mv -f 同卷 move 为 O(1) 元
+// 数据操作；也用于 loadIndex 把损坏索引改名 .corrupt-<ts> 保留现场。
+export function renameFileCmd(src, dst) {
+  return 'mv -f -- ' + psq(src) + ' ' + psq(dst)
+}
+
 // 索引读取（写入走 stdin：见 snapshots.js saveIndex 的 POSIX 分支，
 // 不经命令行传参，天然没有 32767/128KB argv 上限问题）
 export function indexReadCmd(dir) {
   return 'cat ' + psq(dir + '/index.json') + ' 2>/dev/null || true'
 }
 
+// fork lineage 读取（F1，语义见 pwsh 版同款注释）：lineage.json 与 index.json
+// 同层、原子写；缺失文件输出空串。
+export function lineageReadCmd(dir) {
+  return 'cat ' + psq(dir + '/lineage.json') + ' 2>/dev/null || true'
+}
+
 // 旧版项目内 blobs 目录清理（仅 home 存储可用时调用）
 export function legacyRmScript(path) {
   return 'rm -rf -- ' + psq(path)

package/lib/scripts.pwsh.js

@@ -27,6 +27,12 @@ export const UTF8_PRELUDE = '$OutputEncoding = [Text.UTF8Encoding]::new($false)\
 // 生效值以 store.maxFileBytes（用户 config 可调）经 oversizeBlock 注入为准。
 export const MAX_FILE_BYTES = 104857600
 
+// 失败清扫的 stale 锁阈值（分钟，M3）与心跳有效窗口（秒，M3）：语义、取值
+// 理由与「不走 Config」的定性见 scripts.posix.js 同名常量注释，两侧必须
+// 同值（scripts-contract 钉）。
+export const STALE_LOCK_MIN = 5
+export const HEARTBEAT_TTL_S = 900
+
 // 去除 PS 5.1 Set-Content -Encoding utf8 写出的 BOM：JSON 解析前必须剥掉，
 // 否则 JSON.parse 把 BOM 当正文首字符直接抛错。
 export function stripBom(text) {
@@ -89,6 +95,18 @@ function excludeSyncBlock(excludeFile, base) {
   ].join('\n')
 }
 
+// 心跳写入（M3，语义见 scripts.posix.js 同名注释）：Set-Content 用 ascii
+// 编码——内容纯数字，关键是绝不能带 BOM（POSIX 侧按空白分词解析首字段，
+// 5.1 的 utf8 默认编码会写 BOM 破坏首字段）；-ErrorAction SilentlyContinue
+// 让心跳写失败不连累外层 EAP=Stop 的快照主流程（与 POSIX 的 || true 对齐）。
+// 依赖外层已定义的 $g；被 ensureGitScript / snapshotScript 复用。
+function heartbeatBlock() {
+  return [
+    "$hbf = Join-Path (Split-Path -Parent (Split-Path -Parent $g)) 'heartbeat'",
+    "Set-Content -LiteralPath $hbf -Value ('" + String(process.pid) + " ' + [DateTimeOffset]::Now.ToUnixTimeSeconds()) -Encoding ascii -ErrorAction SilentlyContinue"
+  ].join('\n')
+}
+
 // 解析 git 可执行文件路径：DSH 进程 PATH 可能不含 git，脚本里用绝对路径调用。
 // 逐项判空再 Join-Path：个别 env 在特殊环境（32 位系统无 ProgramFiles(x86)）
 // 取到 null，EAP=Stop 下 Join-Path 抛错会让整个探测失败、误报 gitMissing。
@@ -151,6 +169,7 @@ export function ensureGitScript(store, gitExe, base) {
     '$git = ' + psq(gitExe),
     '$repo = ' + psq(store.repo),
     '$g = ' + psq(store.git),
+    heartbeatBlock(),
     'if (-not (Test-Path -LiteralPath $g)) {',
     '  & $git init $repo | Out-Null',
     '}',
@@ -175,6 +194,7 @@ export function snapshotScript(root, store, gitExe, messageId, base) {
     '$git = ' + psq(gitExe),
     '$g = ' + psq(store.git),
     '$root = ' + psq(root),
+    heartbeatBlock(),
     dropGitlinksBlock(),
     excludeSyncBlock(store.excludeFile, base),
     // fail-open add（issue #7 加固）：--ignore-errors 让「个别路径无法索引」
@@ -296,6 +316,10 @@ export function rollbackScript(root, store, gitExe, tag, base) {
     '  Expand-Archive -LiteralPath $zip -DestinationPath $root -Force',
     '  Remove-Item -LiteralPath $zip -Force',
     '}',
+    // 删除失败语义与 POSIX 版对齐（F-G2）：本侧 EAP=Stop 下 Remove-Item
+    // 失败直接抛终止错误、pwsh 以非零码退出；POSIX 侧 rm 在 set -e 的 if
+    // 条件里失败不会自动终止，须显式 exit 1（见 scripts.posix.js rollbackScript）。
+    // 任何一侧半回退都不许报 ROLLBACK_OK——假成功会让救援永不触发（H1）。
     '$deleted = 0',
     'foreach ($r in @($curOut)) {',
     '  if (-not $r) { continue }',
@@ -309,6 +333,25 @@ export function rollbackScript(root, store, gitExe, tag, base) {
   ].join('\n')
 }
 
+// 回退失败救援（H1）：rollback 脚本未输出 ROLLBACK_OK（工作区可能半回退）
+// 时，用 execute 预先打下的安全快照把工作区 reset 回「回退前」状态。
+// 入参 tag 是完整 tag 名（snap-pre-rollback-<ts>，snap- 前缀由调用侧
+// rescueRollback 拼齐——snapshotScript 打 tag 无条件加前缀，本模板保持
+// 通用只接受完整名）。命令与 rollbackScript 同款 --git-dir/--work-tree 形态；
+// pwsh 对 native 非零退出不抛（EAP 不作用于 native），必须显式查
+// $LASTEXITCODE 并 throw，否则救援失败被静默吞掉、工作区停在半回退状态。
+export function rescueScript(root, store, gitExe, tag) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    '$root = ' + psq(root),
+    '& $git --git-dir=$g --work-tree=$root reset --hard ' + psq(tag),
+    'if ($LASTEXITCODE -ne 0) { throw ("git reset --hard failed (exit " + $LASTEXITCODE + ")") }',
+    "Write-Output 'RESCUE_OK'"
+  ].join('\n')
+}
+
 export function listTagsScript(store, gitExe) {
   return [
     "$ErrorActionPreference = 'Stop'",
@@ -321,6 +364,20 @@ export function listTagsScript(store, gitExe) {
   ].join('\n')
 }
 
+// 孤儿重建用 tag 清单（带 creatordate）：语义同 POSIX 版同名导出——
+// rebuildOrphans 据此恢复快照时间，time=0 会让管理列表时间前缀缺失、
+// retention/limits 按「最旧」误清。lightweight tag 的 creatordate 即
+// 指向 commit 的提交日期。输出每行「<tag名> <秒级时间戳>」。
+export function listTagsWithTimeScript(store, gitExe) {
+  return [
+    "$ErrorActionPreference = 'Stop'",
+    '$git = ' + psq(gitExe),
+    '$g = ' + psq(store.git),
+    'if (-not (Test-Path -LiteralPath $g -PathType Container)) { exit 0 }',
+    '& $git --git-dir=$g for-each-ref --format="%(refname:short) %(creatordate:unix)" "refs/tags/snap-*"'
+  ].join('\n')
+}
+
 // 定期 gc：全量保留策略下对象只增不减，且默认 loose 存储（每对象一个
 // 小文件，NTFS 最小簇 4KB）非常浪费；gc 压 pack + 跨版本 delta 通常省一半
 // 以上。--prune=now 让「会话删除联动清理」删掉的 tag 立即真正释放空间
@@ -354,36 +411,73 @@ export function pruneScript(store, gitExe) {
   ].join('\n')
 }
 
-// 失败后的孤儿进程清扫 + stale 锁清理（issue #7 实测：超时被杀的 shell 留下
-// 孤儿 git 继续持有 index.lock 30+ 分钟）。DSH 的 subprocess 服务本身已做
-// 树级终止（taskkill /T /F），这里是竞态窗口与旧版本漏网的兜底：按「命令行
-// 含 --git-dir=<本仓库>」定位孤儿——该标记只出现在本插件派生的 git 进程
-// 参数里，编辑器等无关进程不会命中；再删掉被硬杀的 git 来不及清理的锁文件
-// （git 对强杀不做锁回收，残留 index.lock 会让后续每条快照持续 fatal）。
-// 全程 SilentlyContinue + best-effort：调用点在 runShell 的失败路径上，
-// 清扫自身再抛错只会掩盖原始错误。首行哨兵注释供 runShell 识别本脚本、
-// 防止「清扫失败 → 再清扫」的递归。
-export function killOrphansScript(gitDir) {
-  return [
-    '# RECALL_CLEANUP',
-    "$ErrorActionPreference = 'SilentlyContinue'",
-    '$g = ' + psq(gitDir),
-    // 标记用变量拼接而非字面量：本脚本进程的命令行（-Command 全文）只有
-    // 未展开的 '$g'，Where-Object 不会匹配到自己
-    "$marker = '--git-dir=' + $g",
-    "Get-CimInstance Win32_Process -Filter 'CommandLine IS NOT NULL' | Where-Object { $_.CommandLine.Contains($marker) } | ForEach-Object {",
-    '  & taskkill /T /F /PID $_.ProcessId | Out-Null',
-    '}',
-    // 锁清单：index.lock 是 add/checkout 的持久锁，其余是 gc/tag/pack 链路
-    // 可能残留的；refs 下的 per-ref 锁用递归兜底
-    "foreach ($n in @('index.lock','config.lock','HEAD.lock','gc.pid','packed-refs.lock','shallow.lock')) {",
-    '  Remove-Item -LiteralPath (Join-Path $g $n) -Force',
-    '}',
-    "Get-ChildItem -LiteralPath (Join-Path $g 'refs') -Recurse -File -Filter '*.lock' | Remove-Item -Force",
-    "Write-Output 'CLEANUP_DONE'"
-  ].join('\n')
-}
-
+// 失败后的孤儿进程清扫 + stale 锁清理（issue #7 实测：超时被杀的 shell 留下
+// 孤儿 git 继续持有 index.lock 30+ 分钟）。M3 三级出口（语义与动机见
+// scripts.posix.js 同名函数注释）：另一活实例心跳让路（CLEANUP_OTHER_INSTANCE）
+// → 新锁让路（CLEANUP_SKIPPED_FRESH_LOCK）→ 原有清扫（CLEANUP_DONE）。
+// DSH 的 subprocess 服务本身已做树级终止（taskkill /T /F），这里是竞态窗口
+// 与旧版本漏网的兜底：按「命令行含 --git-dir=<本仓库>」定位孤儿——该标记只
+// 出现在本插件派生的 git 进程参数里，编辑器等无关进程不会命中。
+// 全程 SilentlyContinue + best-effort：调用点在 runShell 的失败路径上，
+// 清扫自身再抛错只会掩盖原始错误。首行哨兵注释供 runShell 识别本脚本、
+// 防止「清扫失败 → 再清扫」的递归。
+export function killOrphansScript(gitDir) {
+  return [
+    '# RECALL_CLEANUP',
+    "$ErrorActionPreference = 'SilentlyContinue'",
+    '$g = ' + psq(gitDir),
+    // —— 第 1 级保护：另一活实例心跳（store.dir 是 git-dir 上两级）——
+    "$hbf = Join-Path (Split-Path -Parent (Split-Path -Parent $g)) 'heartbeat'",
+    'if (Test-Path -LiteralPath $hbf -PathType Leaf) {',
+    '  $hl = Get-Content -LiteralPath $hbf -TotalCount 1',
+    '  if ($hl) {',
+    "    $hp = ('' + $hl).Trim() -split '\\s+'",
+    '    $a = [int64]0; $b = [int64]0',
+    '    if (($hp.Count -ge 2) -and [int64]::TryParse($hp[0], [ref]$a) -and [int64]::TryParse($hp[1], [ref]$b)) {',
+    '      $age = [DateTimeOffset]::Now.ToUnixTimeSeconds() - $b',
+    '      if (($a -gt 0) -and ($a -ne ' + String(process.pid) + ') -and ($age -ge 0) -and ($age -lt ' + HEARTBEAT_TTL_S + ')) {',
+    '        if (Get-Process -Id $a -ErrorAction SilentlyContinue) {',
+    "          Write-Output ('CLEANUP_OTHER_INSTANCE ' + $a)",
+    '          exit 0',
+    '        }',
+    '      }',
+    '    }',
+    '  }',
+    '}',
+    // —— 第 2 级保护：新锁（有 git 操作可能正在进行）——
+    "$cutoff = (Get-Date).AddMinutes(-" + STALE_LOCK_MIN + ')',
+    '$fresh = $false',
+    "foreach ($n in @('index.lock','config.lock','HEAD.lock','gc.pid','packed-refs.lock','shallow.lock')) {",
+    '  $lp = Join-Path $g $n',
+    '  if (Test-Path -LiteralPath $lp -PathType Leaf) {',
+    '    if ((Get-Item -LiteralPath $lp).LastWriteTime -gt $cutoff) { $fresh = $true; break }',
+    '  }',
+    '}',
+    'if (-not $fresh) {',
+    "  $fl = @(Get-ChildItem -LiteralPath (Join-Path $g 'refs') -Recurse -File -Filter '*.lock' -ErrorAction SilentlyContinue | Where-Object { $_.LastWriteTime -gt $cutoff })",
+    '  if ($fl.Count -gt 0) { $fresh = $true }',
+    '}',
+    'if ($fresh) {',
+    "  Write-Output 'CLEANUP_SKIPPED_FRESH_LOCK'",
+    '  exit 0',
+    '}',
+    // —— 保护未命中：原有清扫（杀孤儿 + 清 stale 锁）——
+    // 标记用变量拼接而非字面量：本脚本进程的命令行（-Command 全文）只有
+    // 未展开的 '$g'，Where-Object 不会匹配到自己
+    "$marker = '--git-dir=' + $g",
+    "Get-CimInstance Win32_Process -Filter 'CommandLine IS NOT NULL' | Where-Object { $_.CommandLine.Contains($marker) } | ForEach-Object {",
+    '  & taskkill /T /F /PID $_.ProcessId | Out-Null',
+    '}',
+    // 锁清单：index.lock 是 add/checkout 的持久锁，其余是 gc/tag/pack 链路
+    // 可能残留的；refs 下的 per-ref 锁用递归兜底（能走到这里说明锁已陈旧）
+    "foreach ($n in @('index.lock','config.lock','HEAD.lock','gc.pid','packed-refs.lock','shallow.lock')) {",
+    '  Remove-Item -LiteralPath (Join-Path $g $n) -Force',
+    '}',
+    "Get-ChildItem -LiteralPath (Join-Path $g 'refs') -Recurse -File -Filter '*.lock' | Remove-Item -Force",
+    "Write-Output 'CLEANUP_DONE'"
+  ].join('\n')
+}
+
 // 删除指定快照 tag（会话已删联动清理用）。best-effort：个别 tag 已不存在时
 // git 非零退出，但其余 tag 已被删除——所以显式 exit 0 吞掉退出码，
 // 残留的由下一次清理幂等地收尾；JS 侧无论脚本结果都会同步索引。
@@ -406,14 +500,35 @@ export function purgeTagsScript(store, gitExe, tags) {
 // 表达式，first 决定覆盖还是追加。目录创建归调用方（writeExclude 的
 // mkdirScript 兜底 / index.json 的父目录在建仓时已存在）。
 export function fileWriteCmd(file, piece, first) {
+  // EAP=Stop：Set-Content/Add-Content 是 cmdlet，失败（权限/磁盘满）在
+  // 默认 EAP=Continue 下只写 error stream、退出码仍 0，半截写入被静默吞掉。
+  // 显式 Stop 让失败抛终止错误，runShell 据此检测非零退出并抛错（H2）。
+  const prelude = "$ErrorActionPreference = 'Stop'\n"
   if (first) {
-    return piece + 'Set-Content -LiteralPath ' + psq(file) + ' -Encoding utf8 -NoNewline'
+    return prelude + piece + 'Set-Content -LiteralPath ' + psq(file) + ' -Encoding utf8 -NoNewline'
   }
-  return piece + 'Add-Content -LiteralPath ' + psq(file) + ' -Encoding utf8 -NoNewline'
+  return prelude + piece + 'Add-Content -LiteralPath ' + psq(file) + ' -Encoding utf8 -NoNewline'
 }
 
+// 原子 rename（H2）：同卷 move 是 O(1) 元数据操作，把「已完整写完的 tmp」
+// 一步替换成目标文件，杜绝分块写中途崩溃留下的截断 JSON；也用于 loadIndex
+// 把损坏索引改名 .corrupt-<ts> 保留现场（见 snapshots.js quarantineCorruptIndex）。
+export function renameFileCmd(src, dst) {
+  return "$ErrorActionPreference = 'Stop'\nMove-Item -Force -LiteralPath " + psq(src) + ' -Destination ' + psq(dst)
+}
+
+// 显式 -Encoding UTF8：写侧（writeTextViaShell base64 解码落盘）产出的是
+// 无 BOM UTF-8，PS 7 默认即按 UTF-8 读，但 PS 5.1 兜底（pwsh-local 解析链
+// 降级）按 ANSI 活动代码页解码——中文 root 乱码 → JSON.parse 失败 → 误走
+// H2 隔离分支。与 excludeReadCmd 等同文件其他读取处的既有写法对齐。
 export function indexReadCmd(dir) {
-  return 'Get-Content -LiteralPath ' + psq(dir + '\\index.json') + ' -Raw -ErrorAction SilentlyContinue'
+  return 'Get-Content -LiteralPath ' + psq(dir + '\\index.json') + ' -Raw -Encoding UTF8 -ErrorAction SilentlyContinue'
+}
+
+// fork lineage 读取（F1）：lineage.json 记录 childId↔parentId 撤回链，
+// 与 index.json 同层、原子写（writeTextViaShell）。文件不存在时输出空串。
+export function lineageReadCmd(dir) {
+  return 'Get-Content -LiteralPath ' + psq(dir + '\\lineage.json') + ' -Raw -Encoding UTF8 -ErrorAction SilentlyContinue'
 }
 
 // 旧版项目内 blobs 目录清理（仅 home 存储可用时调用，见 store.js cleanupLegacy）

package/lib/session-info.js

@@ -0,0 +1,71 @@
+/**
+ * dsh-recall-plugin — 会话信息域（R2 从 index.js 拆出）
+ *
+ * 会话标题/消息文本的「两段式」读取：纯函数（titleFromEvents /
+ * messageTextFromEvents）模块级导出供单测与工厂共用；live 快速查询
+ * （liveTitleFast / liveMessageTextFast）带 apply 级跨请求缓存（sessionTitles /
+ * messageTexts Map），由 createSessionInfo 工厂生产——无模块级可变状态（HMR 假设）。
+ *
+ * 冷会话标题/文本要 readSession 整日志解压（10 秒级），列表首屏只查 live/缓存
+ * （同步、瞬时），冷数据由 Client 拿到列表后异步调 titles/messages 端点补齐。
+ */
+
+// 从事件序列里取最新一条 session/title（倒序，标题事件通常靠后）
+export function titleFromEvents(events) {
+  if (!Array.isArray(events)) return null
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i]
+    if (e && e.type === 'session/title' && e.data && typeof e.data.title === 'string' && e.data.title) return e.data.title
+  }
+  return null
+}
+
+// 从事件序列里取指定用户消息的纯文本（text 块拼接）
+export function messageTextFromEvents(events, messageId) {
+  if (!Array.isArray(events) || !messageId) return null
+  for (const e of events) {
+    if (e && e.type === 'user/message' && e.data && String(e.data.id) === String(messageId)) {
+      const blocks = Array.isArray(e.data.content) ? e.data.content : []
+      const text = blocks
+        .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('')
+      return text || null
+    }
+  }
+  return null
+}
+
+export function createSessionInfo(ctx) {
+  // 会话标题缓存：值为 null 表示「查过、确实没有」（已删除会话），同样命中缓存
+  const sessionTitles = new Map()
+  // 消息文本缓存：null 也缓存（避免无文本消息每次刷新重复解压冷日志）
+  const messageTexts = new Map()
+
+  function liveMessageTextFast(sessionId, messageId) {
+    if (!sessionId || !messageId) return null
+    const key = String(sessionId) + '\u0000' + String(messageId)
+    if (messageTexts.has(key)) return messageTexts.get(key)
+    let text = null
+    try {
+      const live = ctx.sessions.get(sessionId)
+      if (live) text = messageTextFromEvents(live.events, messageId)
+    } catch (error) { text = null }
+    if (text !== null) messageTexts.set(key, text)
+    return text
+  }
+
+  function liveTitleFast(sessionId) {
+    if (!sessionId) return null
+    if (sessionTitles.has(sessionId)) return sessionTitles.get(sessionId)
+    let t = null
+    try {
+      const live = ctx.sessions.get(sessionId)
+      if (live) t = titleFromEvents(live.events)
+    } catch (error) { t = null }
+    if (t !== null) sessionTitles.set(sessionId, t)
+    return t
+  }
+
+  return { sessionTitles, messageTexts, liveTitleFast, liveMessageTextFast }
+}