dsh-recall-plugin 2.0.0 → 2.1.1

package/lib/scripts.posix.js

@@ -30,6 +30,27 @@ 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
+
+// 影子仓库 info/attributes 固化内容（issue #12 字节保真）：与 pwsh 版同名
+// 常量逐字同值（scripts-contract 钉），完整语义与逐项动机见 scripts.pwsh.js
+// 同名常量注释。一句话：git archive/add 都会应用快照树里项目自己的
+// .gitattributes（text=auto + 缺省 core.eol=native 的转换，仓库级
+// autocrlf=false 挡不住），info/attributes 优先级最高、对全部路径一票否决，
+// 快照 capture/restore 两侧逐字节保真。
+export const FIDELITY_ATTRS = '* -text -filter -ident -export-ignore -export-subst -working-tree-encoding'
+
 // bash/cat 输出无 BOM；保留同名导出维持两套模板接口一致（幂等无害）
 export function stripBom(text) {
   return text.replace(/^\uFEFF/, '')
@@ -83,18 +104,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 +166,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,16 +193,49 @@ 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',
+    // 属性固化（issue #12，内容见 FIDELITY_ATTRS）：info/ 由 git init 自带
+    // （info/exclude 模板，excludeSyncBlock 同样依赖），无需建目录；每次
+    // ensureGit 重写幂等，存量仓库升级后首次 init 自然补上。
+    'printf ' + psq(FIDELITY_ATTRS + '\n') + ' > "$g/info/attributes"',
     excludeSyncBlock(store.excludeFile, base),
     'stamp="$g/gc.stamp"',
     'if [ -f "$stamp" ]; then printf \'GIT_OK %s\\n\' "$(head -n1 "$stamp" 2>/dev/null)"; else echo GIT_OK; fi'
   ].join('\n')
 }
 
+// 存量归一化迁移（issue #12，语义与动机详见 pwsh 版 attrsMigrateBlock 注释）：
+// 属性固化后旧索引条目仍指向归一化 blob（stat 缓存时序依赖地跳过重哈希），
+// --renormalize 按当前属性重哈希一次；无 pathspec 是空操作，必须带 ':(top)'
+// 顶层魔法 pathspec。标记文件每仓库至多跑一次；失败（老 git 无该选项等）
+// 只跳过标记下条消息重试，不连累快照主流程（set -e 下 || rc=$? 捕获）。
+// 依赖外层已定义的 $git/$g/$root；仅 snapshotScript 使用。
+function attrsMigrateBlock() {
+  return [
+    'mig_stamp="$g/attrs-v1.stamp"',
+    'if [ ! -f "$mig_stamp" ]; then',
+    '  migrc=0',
+    '  "$git" --git-dir="$g" --work-tree="$root" add --renormalize --ignore-errors -- \':(top)\' >/dev/null 2>&1 || migrc=$?',
+    '  if [ "$migrc" -le 1 ]; then printf \'1\\n\' > "$mig_stamp" 2>/dev/null || true; fi',
+    'fi',
+  ].join('\n')
+}
+
 // 快照：add -A → write-tree → commit-tree（孤儿提交）→ tag（语义同 pwsh 版）。
 // tag -f：事件重放/重发会产生重复 messageId，裸 tag 对已存在 tag fatal
 // 导致整条快照失败；-f 把 tag 指到最新提交，语义为「同一条消息取最新状态」。
@@ -159,8 +245,10 @@ export function snapshotScript(root, store, gitExe, messageId, base) {
     'git=' + psq(gitExe),
     'g=' + psq(store.git),
     'root=' + psq(root),
+    heartbeatBlock(),
     dropGitlinksBlock(),
     excludeSyncBlock(store.excludeFile, base),
+    attrsMigrateBlock(),
     // fail-open add（issue #7 加固，语义见 pwsh 版同款注释）：--ignore-errors
     // 下「无法索引的路径」以退出码 1 结束但索引已落盘；≥2 才是真 fatal，
     // 显式退出让 runShell 抛错（set -e 对 add 非零本会终止，但 || rc=$?
@@ -240,6 +328,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 +358,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 +395,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 +433,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 +497,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,31 @@ 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
+
+// 影子仓库 info/attributes 固化内容（issue #12 字节保真，两套模板同值，
+// scripts-contract 钉）。为什么必须：回退恢复走 git archive、捕获走 add，
+// 两者都会应用「快照树里项目自己的 .gitattributes」——text=auto（极常见）
+// + 缺省 core.eol=native（Windows 即 CRLF）会让 archive 把 LF 转 CRLF，
+// 仓库级 core.autocrlf=false 挡不住（属性驱动的转换看 core.eol，不看
+// autocrlf，实测）。info/attributes 是优先级最高的属性源，对全部路径
+// 无条件关闭内容转换，capture/restore 两侧逐字节保真；也顺带治掉
+// ensureGit 的 git config 写入静默失败（I14：pwsh 对 native 非零不抛）
+// 后裸露 system autocrlf 的帮凶路径。逐项语义：
+// -text                    关闭全部 EOL 转换（含 autocrlf/text/eol 全部语义）
+// -filter                  关闭 clean/smudge 外部过滤命令（LFS 类，防内容被改写/存指针）
+// -ident                   关闭 $Id$ 展开
+// -export-ignore           防归档静默丢文件（回退恢复缺文件零报错，实测）
+// -export-subst            防归档内容 $Format:$ 替换
+// -working-tree-encoding   防编码转码
+// 快照是备份/还原不是 VCS：字节保真优先于用户在 .gitattributes 里声明的
+// 任何转换策略——那是给 git 仓库的，不是给影子快照库的。
+export const FIDELITY_ATTRS = '* -text -filter -ident -export-ignore -export-subst -working-tree-encoding'
+
 // 去除 PS 5.1 Set-Content -Encoding utf8 写出的 BOM：JSON 解析前必须剥掉，
 // 否则 JSON.parse 把 BOM 当正文首字符直接抛错。
 export function stripBom(text) {
@@ -89,6 +114,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。
@@ -142,6 +179,9 @@ export function migrateScript(src, dst) {
 // autocrlf=true 时的 LF/CRLF stderr 警告；addEmbeddedRepo=false：嵌套仓库
 // hint/warning 走 stderr，在 DSH shell（EAP=Stop）下会让整条脚本非零退出，
 // 必须在仓库级配置里静默掉。
+// info/attributes 固化（issue #12，内容见 FIDELITY_ATTRS）：info/ 由 git init
+// 自带（info/exclude 模板，excludeSyncBlock 同样依赖），无需建目录；每次
+// ensureGit 重写幂等，存量仓库升级后首次 init 自然补上。
 // 结尾回读 gc.stamp（maintenance.js 上次 gc 时间戳）：让重启后的 gc 节流
 // 不归零——没有它，天天重启 DSH 的用户每次开机第一条消息都会触发一次
 // 全量 gc，纯浪费。
@@ -151,18 +191,42 @@ 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',
     '}',
     '& $git --git-dir=$g config core.longpaths true',
     '& $git --git-dir=$g config core.autocrlf false',
     '& $git --git-dir=$g config advice.addEmbeddedRepo false',
+    "$attrDir = Join-Path $g 'info'",
+    "Set-Content -LiteralPath (Join-Path $attrDir 'attributes') -Value '" + FIDELITY_ATTRS + "' -Encoding ascii",
     excludeSyncBlock(store.excludeFile, base),
     "$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')
 }
 
+// 存量归一化迁移（issue #12）：属性固化后，索引里的旧条目仍指向归一化
+// blob 的哈希——stat 缓存让裸 add -A 时序依赖地跳过重哈希（racy 复查只在
+// 「add 与文件同秒写入」时触发，实测不可靠），归一化残留会一直潜伏进新
+// 快照。--renormalize 对全部跟踪文件按当前属性（无转换）重哈希一次；
+// 无 pathspec 时它是空操作（实测「Nothing specified, nothing added」），
+// 必须带 ':(top)' 顶层魔法 pathspec（cwd 无关），也不能加
+// --literal-pathspecs（会废掉魔法解析）。标记文件保证每仓库至多跑一次；
+// 失败（老 git 无该选项退出 129、偶发锁冲突等）只跳过标记、下条消息重试，
+// 不 throw——迁移是 best-effort，不能让老 git 机器的快照从此全挂。
+// 依赖外层已定义的 $git/$g/$root；仅 snapshotScript 使用（execute 的救援
+// 安全快照在回退前必先跑一次快照，回退链路天然被覆盖）。
+function attrsMigrateBlock() {
+  return [
+    "$migStamp = Join-Path $g 'attrs-v1.stamp'",
+    'if (-not (Test-Path -LiteralPath $migStamp)) {',
+    "  & $git --git-dir=$g --work-tree=$root add --renormalize --ignore-errors -- ':(top)'",
+    '  if ($LASTEXITCODE -le 1) { Set-Content -LiteralPath $migStamp -Value 1 -Encoding ascii -ErrorAction SilentlyContinue }',
+    '}',
+  ].join('\n')
+}
+
 // 快照：git add -A 增量同步 index（.gitignore/exclude 语义由 git 统一处理），
 // write-tree 生成树、commit-tree 生成无父孤儿提交、tag 保对象可达。
 // 不做 parent 链、不修剪：像 TraeWork 一样保留全量历史，tag 永远可查。
@@ -175,8 +239,10 @@ export function snapshotScript(root, store, gitExe, messageId, base) {
     '$git = ' + psq(gitExe),
     '$g = ' + psq(store.git),
     '$root = ' + psq(root),
+    heartbeatBlock(),
     dropGitlinksBlock(),
     excludeSyncBlock(store.excludeFile, base),
+    attrsMigrateBlock(),
     // fail-open add（issue #7 加固）：--ignore-errors 让「个别路径无法索引」
     // （无提交的嵌入式仓库、不可读文件等）以退出码 1 结束但索引照常落盘，
     // 快照缺个别路径可接受，好过整条快照 fatal。退出码 ≥2 才是真 fatal
@@ -296,6 +362,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 +379,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 +410,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 +457,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 +546,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）