dsh-tracepoint 0.0.0-stage → 0.6.2

package/index.js

@@ -0,0 +1,1629 @@
+/**
+ * dsh-trace —— 痕迹（v0.2）
+ *
+ * 动手前拍一个点；改坏了能退回去；退回本身也能退回。
+ *
+ * 三条底线（写死在代码里，不是设置项）：
+ *   1. 不自动删任何快照。到上限就拒绝新快照，让你清（要清得显式点名 forget）。
+ *   2. 不整目录覆盖。restore 只碰那份 manifest 里记过的文件，不删你新增的。
+ *   3. 写文件一律"临时文件 → 校验 → rename"，中途被杀也不会留半个文件。
+ *
+ * v0.2 加的四样：
+ *   · diff 给内容（不只是文件名）：+n/-n 和改动那一块的前后文
+ *   · forget / gc：能按名字删一个点，能回收没人引用的块（都不自动）
+ *   · 并发锁：两个 restore 同时跑会被挡住
+ *   · 长路径（Windows >260）自动走 \\?\ 前缀
+ *
+ * v0.3：save({paths}) 只拍点名的那几个文件（毫秒级）；局部快照的 diff 不报"新增"。
+ *
+ * v0.4：主动用兜底。写文件类工具跑完，如果这个文件不在拍过的点里，
+ *       就在结果末尾补一句「［痕迹］…」（每场最多 3 次，config.json 可关）。
+ *       不拦调用、不改结果本身、不假装成功。
+ *
+ * v0.5：再往前一步——把一句提醒**写进系统提示词**（位置在 write 工具说明前面）。
+ *       兜底只在写完那一刻出声，第一笔改动保不住；这一句在动手之前就在。
+ *       同一份 config.json 的 {"remind": false} 把这两层一起关掉（提示词要重开才消失）。
+ *
+ * v0.5.2：restore({paths:[...]}) 只退点名的文件（以前整份快照一起退）；
+ *         没拍到的文件直说退不了，不假装成功。真用出来的：只想退卡片却动了 README。
+ *
+ * v0.6：第三层兜底——写文件类工具**真正执行前**自动拍点（tools/pre-execute 钩子）。
+ *       模型忘了拍点，插件自己拍，第一笔改动也退得回去。拍不成静默跳过，靠写完那层提醒补。
+ *       关掉：config.json 写 {"autoSave": false}。
+ *
+ * v0.6.1：0.6.0 的自动拍点在真宿主上**从没触发**——它只认 agent.cwd，而 DSH 0.2.2 的
+ *         ReactLoopAgent 没有 cwd 字段，工作区根在 agent.session.header.cwd。两个都认。
+ *
+ * 发布命名：npm 包名 / 仓库名 = dsh-tracepoint（npm 防混淆拒绝 dsh-trace，与 dd-trace 太像）。
+ *           内部标识保留 dsh-trace：数据目录 ~/.dsh/dsh-trace、提示词段 dsh-trace:remind，
+ *           工具名 trace_anchor / trace_attempt 不变——既有快照与配置不因改名失效。
+ *
+ * v0.6.2：仅重写 npm 门面描述（「后悔药」与「安全网」），逻辑零改动。
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+export const name = 'dsh-tracepoint'
+export const inject = ['tools', 'systemPrompt']
+
+const VERSION = '0.6.2'
+const HOME = path.join(os.homedir(), '.dsh', 'dsh-trace')
+const BLOB_DIR = path.join(HOME, 'blobs')
+const MAN_DIR = path.join(HOME, 'manifests')
+const ATTEMPT_FILE = path.join(HOME, 'attempts.jsonl')
+const INDEX_FILE = path.join(HOME, 'index.json')
+const TMP_PREFIX = '.dst-tmp-'
+
+const MAX_BYTES = 500 * 1024 * 1024
+const BIG_FILE = 50 * 1024 * 1024
+const TEXT_DIFF_LIMIT = 256 * 1024
+const EXCLUDES = new Set(['node_modules', '.git', '.obsidian', '备份', '.dsh-trace'])
+const ATTEMPT_KEEP_DAYS = 90
+const LOCK_TTL = 5 * 60 * 1000
+const LOCK_BEAT = 20 * 1000
+
+/* 活着的锁：长时间同步操作（GC 实测能跑 7 分钟）里要手动刷 mtime，
+   否则另一头会把还在用的锁当成死锁抢走（评审 2026-11-14 的 P1）。 */
+const ACTIVE_LOCKS = new Set()
+function beatLocks() {
+  if (ACTIVE_LOCKS.size === 0) return
+  const now = new Date()
+  for (const f of ACTIVE_LOCKS) {
+    try {
+      utimes(f, now, now)
+    } catch {}
+  }
+}
+
+/* ---------------- 小工具 ---------------- */
+
+const sha = (buf) => crypto.createHash('sha256').update(buf).digest('hex')
+const nowIso = () => new Date().toISOString().replace('T', ' ').slice(0, 16)
+const mb = (n) => (n / 1048576).toFixed(1) + ' MB'
+const KB = (n) => (n / 1024).toFixed(0) + ' KB'
+
+/* Windows 长路径：超过 248 字符加 \\?\ 前缀，否则后端会 ENOENT */
+function wp(p) {
+  if (process.platform !== 'win32') return p
+  const abs = path.isAbsolute(p) ? p : path.resolve(p)
+  if (abs.startsWith('\\\\?\\')) return abs
+  return abs.length >= 248 ? '\\\\?\\' + abs : abs
+}
+
+const ex = (p) => fs.existsSync(wp(p))
+const st = (p) => fs.statSync(wp(p))
+const rd = (p, o) => fs.readFileSync(wp(p), o)
+const wr = (p, b, o) => fs.writeFileSync(wp(p), b, o)
+const mk = (p, o) => fs.mkdirSync(wp(p), o)
+const rn = (a, b) => fs.renameSync(wp(a), wp(b))
+const rm = (p, o) => fs.rmSync(wp(p), o)
+const listDir = (p, o) => fs.readdirSync(wp(p), o)
+const chmod = (p, m) => fs.chmodSync(wp(p), m)
+const utimes = (p, a, b) => fs.utimesSync(wp(p), a, b)
+const appendF = (p, s) => fs.appendFileSync(wp(p), s, 'utf8')
+
+function ensureDirs() {
+  mk(BLOB_DIR, { recursive: true })
+  mk(MAN_DIR, { recursive: true })
+}
+
+function tmpName(target) {
+  return path.join(path.dirname(target), TMP_PREFIX + crypto.randomBytes(6).toString('hex'))
+}
+
+/* 原子写入：先写临时文件，校验通过再 rename 换上去 */
+function atomicWrite(target, buf) {
+  mk(path.dirname(target), { recursive: true })
+  const t = tmpName(target)
+  wr(t, buf)
+  if (sha(rd(t)) !== sha(buf)) {
+    rm(t, { force: true })
+    throw new Error('TMP_VERIFY_FAILED')
+  }
+  rn(t, target)
+}
+
+/* 并发锁：同一时刻只允许一个 save / 一个 restore。
+   锁里写一个随机 token：只删自己的锁；跑着的时候有心跳刷 mtime，
+   只有"进程真的没了"（mtime 停住超过 TTL）才会被别人接管。 */
+function acquire(kind) {
+  ensureDirs()
+  const f = path.join(HOME, '.lock-' + kind)
+  const token = process.pid + ':' + crypto.randomBytes(6).toString('hex')
+  if (ex(f)) {
+    try {
+      if (Date.now() - st(f).mtimeMs < LOCK_TTL) throw new Error('BUSY:' + kind)
+      rm(f, { force: true })
+    } catch (e) {
+      if (String(e.message).startsWith('BUSY:')) throw e
+    }
+  }
+  try {
+    wr(f, token, { flag: 'wx' })
+  } catch {
+    throw new Error('BUSY:' + kind)
+  }
+  ACTIVE_LOCKS.add(f)
+  const beat = setInterval(() => beatLocks(), LOCK_BEAT)
+  if (beat.unref) beat.unref()
+  let released = false
+  return () => {
+    if (released) return
+    released = true
+    ACTIVE_LOCKS.delete(f)
+    try {
+      clearInterval(beat)
+    } catch {}
+    try {
+      if (rd(f, 'utf8') === token) rm(f, { force: true })
+    } catch {}
+  }
+}
+
+function sweepTmp(root) {
+  const cutoff = Date.now() - 10 * 60 * 1000
+  let n = 0
+  const walk = (dir) => {
+    let ents
+    try {
+      ents = listDir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of ents) {
+      const p = path.join(dir, e.name)
+      if (e.isDirectory()) {
+        if (!EXCLUDES.has(e.name)) walk(p)
+        continue
+      }
+      if (e.name.startsWith(TMP_PREFIX)) {
+        try {
+          if (st(p).mtimeMs < cutoff) {
+            rm(p, { force: true })
+            n++
+          }
+        } catch {}
+      }
+    }
+  }
+  if (root && ex(root)) walk(root)
+  return n
+}
+
+function usedBytes(dir = HOME) {
+  let s = 0
+  let ents
+  try {
+    ents = listDir(dir, { withFileTypes: true })
+  } catch {
+    return 0
+  }
+  for (const e of ents) {
+    const p = path.join(dir, e.name)
+    if (e.isDirectory()) s += usedBytes(p)
+    else
+      try {
+        s += st(p).size
+      } catch {}
+  }
+  return s
+}
+
+function inside(root, rel) {
+  const abs = path.resolve(root, rel)
+  const norm = path.resolve(root)
+  return abs === norm || abs.startsWith(norm + path.sep)
+}
+
+/* 真实路径：把"最深一层还存在的祖先"换成它的真实路径，再拼回不存在的尾巴。
+   词法上在工作区里、实际被目录联接/符号链接指到外面去的情况，只有这条路能看出来。 */
+function realPathOf(p) {
+  let cur = path.resolve(p)
+  const tail = []
+  for (;;) {
+    try {
+      const real = fs.realpathSync.native(cur)
+      return tail.length ? path.join(real, ...tail.reverse()) : real
+    } catch {
+      const parent = path.dirname(cur)
+      if (parent === cur) return path.resolve(p)
+      tail.push(path.basename(cur))
+      cur = parent
+    }
+  }
+}
+
+const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b)
+
+/* 真实目标还在不在 root 里（root 自己也可能是联接，所以两边都取真实路径） */
+function realInside(root, target) {
+  const r = realPathOf(root)
+  const t = realPathOf(target)
+  if (samePath(r, t)) return true
+  const rel = path.relative(r, t)
+  if (!rel || path.isAbsolute(rel)) return false
+  return rel !== '..' && !rel.startsWith('..' + path.sep)
+}
+
+/* ---------------- 文本差异（单块，不做完整 LCS） ---------------- */
+
+function hunkOf(oldBuf, newBuf, ctx = 2, maxLines = 24) {
+  const a = oldBuf.toString('utf8').split('\n')
+  const b = newBuf.toString('utf8').split('\n')
+  let s = 0
+  while (s < a.length && s < b.length && a[s] === b[s]) s++
+  let ea = a.length - 1
+  let eb = b.length - 1
+  while (ea >= s && eb >= s && a[ea] === b[eb]) {
+    ea--
+    eb--
+  }
+  const removed = a.slice(s, ea + 1)
+  const added = b.slice(s, eb + 1)
+  const out = []
+  for (let i = Math.max(0, s - ctx); i < s; i++) out.push('  ' + a[i])
+  for (const l of removed.slice(0, maxLines)) out.push('- ' + l)
+  if (removed.length > maxLines) out.push(`- …（还有 ${removed.length - maxLines} 行被删）`)
+  for (const l of added.slice(0, maxLines)) out.push('+ ' + l)
+  if (added.length > maxLines) out.push(`+ …（还有 ${added.length - maxLines} 行新增）`)
+  const tail = Math.min(a.length, ea + 1 + ctx)
+  for (let i = ea + 1; i < tail; i++) out.push('  ' + a[i])
+  return { added: added.length, removed: removed.length, lines: out, at: s + 1 }
+}
+
+function isProbablyText(buf) {
+  const n = Math.min(buf.length, 8000)
+  let bad = 0
+  for (let i = 0; i < n; i++) if (buf[i] === 0) bad++
+  return bad === 0
+}
+
+/* ---------------- 增量索引 ----------------
+   只靠 size + mtime 判断"没变过"，就不再重读那个文件。
+   代价：如果某个文件被改过、但大小和 mtime 都没变（极少见），会漏判。
+   换来的是：364MB 的工作区，第二次拍照从 20 秒降到几十毫秒。 */
+
+function loadIndex() {
+  try {
+    const j = JSON.parse(rd(INDEX_FILE, 'utf8'))
+    if (j && j.version === 1 && j.entries) return j
+  } catch {}
+  return { version: 1, entries: {} }
+}
+
+function saveIndex(idx) {
+  try {
+    atomicWrite(INDEX_FILE, Buffer.from(JSON.stringify(idx)))
+  } catch {}
+}
+
+/* ---------------- 拍点 ---------------- */
+
+function takeSnapshot(root, label, auto = false, opts = {}) {
+  const release = acquire('save')
+  try {
+    ensureDirs()
+    const t0 = Date.now()
+    const files = []
+    const dirs = []
+    const excluded = []
+    const skipped = []
+    const unreadable = []
+    const concurrent = []
+    const idx = loadIndex()
+    let reused = 0
+    let hashed = 0
+
+    /** 收一个文件：读、哈希、落块、记账。走遍历和走 paths 都用这一份。 */
+    const addFile = (p, rel) => {
+      let st1
+      try {
+        st1 = st(p)
+      } catch {
+        unreadable.push(rel)
+        return false
+      }
+      if (st1.size > BIG_FILE) {
+        skipped.push({ rel, why: '超过 50MB' })
+        return false
+      }
+      const key = root + '|' + rel
+      const hit = idx.entries[key]
+      let h = null
+      if (
+        hit &&
+        hit.size === st1.size &&
+        hit.mtimeMs === st1.mtimeMs &&
+        ex(path.join(BLOB_DIR, hit.hash.slice(0, 2), hit.hash))
+      ) {
+        h = hit.hash
+        reused++
+      } else {
+        let buf
+        try {
+          buf = rd(p)
+        } catch {
+          unreadable.push(rel)
+          return false
+        }
+        let st2 = null
+        try {
+          st2 = st(p)
+        } catch {}
+        if (!st2 || st2.size !== st1.size || st2.mtimeMs !== st1.mtimeMs || st2.size !== buf.length) {
+          concurrent.push(rel)
+        }
+        h = sha(buf)
+        const blob = path.join(BLOB_DIR, h.slice(0, 2), h)
+        if (!ex(blob)) atomicWrite(blob, buf)
+        idx.entries[key] = { size: st1.size, mtimeMs: st1.mtimeMs, hash: h }
+        hashed++
+      }
+      files.push({ rel, hash: h, size: st1.size, mode: st1.mode & 0o777, mtimeMs: st1.mtimeMs })
+      return true
+    }
+
+    const walk = (dir) => {
+      let ents
+      try {
+        ents = listDir(dir, { withFileTypes: true })
+      } catch {
+        unreadable.push(path.relative(root, dir).split(path.sep).join('/') || '.')
+        return
+      }
+      for (const e of ents) {
+        const p = path.join(dir, e.name)
+        const rel = path.relative(root, p).split(path.sep).join('/')
+        if (EXCLUDES.has(e.name)) {
+          excluded.push(rel)
+          continue
+        }
+        if (e.isSymbolicLink()) {
+          skipped.push({ rel, why: '符号链接（首版不支持）' })
+          continue
+        }
+        if (e.isDirectory()) {
+          dirs.push(rel)
+          walk(p)
+          continue
+        }
+        if (!e.isFile()) {
+          skipped.push({ rel, why: '非普通文件' })
+          continue
+        }
+        addFile(p, rel)
+      }
+    }
+
+    /* paths 模式：只拍点名的那些文件。改两个文件就只存两个，
+       不再为了"万一"把 7000 个文件全读一遍（他 20:2x 问的 23 秒）。 */
+    const wanted = Array.isArray(opts.paths)
+      ? opts.paths.filter((x) => typeof x === 'string' && x.trim())
+      : null
+    const requested = []
+    const missing = []
+
+    if (wanted) {
+      const seen = new Set()
+      for (const raw of wanted) {
+        const abs = path.isAbsolute(raw) ? raw : path.join(root, raw)
+        const rel = path.relative(root, abs).split(path.sep).join('/')
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+          skipped.push({ rel: String(raw), why: '不在工作区里' })
+          continue
+        }
+        if (seen.has(rel)) continue
+        seen.add(rel)
+        requested.push(rel)
+        if (rel.split('/').some((x) => EXCLUDES.has(x))) {
+          skipped.push({ rel, why: '按约定排除（node_modules 之类）' })
+          continue
+        }
+        let s1
+        try {
+          /* lstat：看这个路径本身，别顺着符号链接去看它指向的东西 */
+          s1 = fs.lstatSync(wp(abs))
+        } catch {
+          missing.push(rel)
+          continue
+        }
+        if (s1.isSymbolicLink()) {
+          skipped.push({ rel, why: '符号链接（首版不支持）' })
+          continue
+        }
+        if (!realInside(root, abs)) {
+          skipped.push({ rel, why: '真实路径不在工作区里（上面某级目录是链接）' })
+          continue
+        }
+        if (s1.isDirectory()) {
+          skipped.push({ rel, why: 'paths 只收文件，不收目录' })
+          continue
+        }
+        // 把它的上级目录也记下来：退回时万一目录被删了，能补建
+        const parts = rel.split('/')
+        for (let i = 1; i < parts.length; i++) {
+          const d = parts.slice(0, i).join('/')
+          if (!dirs.includes(d)) dirs.push(d)
+        }
+        addFile(abs, rel)
+      }
+    } else {
+      walk(root)
+    }
+
+    const id = 's' + Date.now().toString(36) + crypto.randomBytes(2).toString('hex')
+    saveIndex(idx)
+    const incomplete =
+      concurrent.length > 0 || unreadable.length > 0 || skipped.some((s) => s.why === '超过 50MB')
+
+    const manifest = {
+      id,
+      version: VERSION,
+      label: label || '',
+      auto,
+      mode: wanted ? 'paths' : 'workspace',
+      requested,
+      missing,
+      at: Date.now(),
+      atText: nowIso(),
+      root,
+      status: incomplete ? 'incomplete' : 'complete',
+      files,
+      dirs,
+      excluded,
+      skipped,
+      unreadable,
+      concurrent,
+      reused,
+      hashed,
+      bytes: files.reduce((s, f) => s + f.size, 0),
+    }
+    atomicWrite(path.join(MAN_DIR, id + '.json'), Buffer.from(JSON.stringify(manifest)))
+    manifest.ms = Date.now() - t0
+    return manifest
+  } finally {
+    release()
+  }
+}
+
+function loadManifest(id) {
+  if (!/^s[0-9a-z]+$/.test(String(id || ''))) throw new Error('BAD_ID')
+  const p = path.join(MAN_DIR, id + '.json')
+  if (!ex(p)) throw new Error('NOT_FOUND')
+  return JSON.parse(rd(p, 'utf8'))
+}
+
+function listManifests(limit = 60) {
+  ensureDirs()
+  return listDir(MAN_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      try {
+        return JSON.parse(rd(path.join(MAN_DIR, f), 'utf8'))
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.at - a.at)
+    .slice(0, limit)
+}
+
+/* ---------------- 看改了什么 ---------------- */
+
+function diffOf(m, { withContent = true, maxFiles = 6 } = {}) {
+  const out = { modified: [], deleted: [], added: [], same: 0, details: [] }
+  const seen = new Set()
+  for (const f of m.files) {
+    if (!inside(m.root, f.rel)) continue
+    const p = path.join(m.root, f.rel)
+    seen.add(f.rel)
+    if (!ex(p)) {
+      out.deleted.push(f.rel)
+      continue
+    }
+    let buf
+    try {
+      buf = rd(p)
+    } catch {
+      out.modified.push(f.rel)
+      continue
+    }
+    if (sha(buf) === f.hash) {
+      out.same++
+      continue
+    }
+    out.modified.push(f.rel)
+
+    if (withContent && out.details.length < maxFiles) {
+      if (f.size > TEXT_DIFF_LIMIT) {
+        out.details.push({ rel: f.rel, tooBig: true, size: f.size })
+      } else if (!isProbablyText(buf)) {
+        out.details.push({ rel: f.rel, binary: true, size: buf.length })
+      } else {
+        try {
+          const oldBuf = rd(path.join(BLOB_DIR, f.hash.slice(0, 2), f.hash))
+          if (!isProbablyText(oldBuf)) out.details.push({ rel: f.rel, binary: true, size: buf.length })
+          else {
+            const h = hunkOf(oldBuf, buf)
+            out.details.push({ rel: f.rel, ...h, size: buf.length })
+          }
+        } catch {
+          out.details.push({ rel: f.rel, blobMissing: true })
+        }
+      }
+    }
+  }
+  const walkAdd = (dir) => {
+    let ents
+    try {
+      ents = listDir(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of ents) {
+      if (EXCLUDES.has(e.name)) continue
+      const p = path.join(dir, e.name)
+      const rel = path.relative(m.root, p).split(path.sep).join('/')
+      if (e.isDirectory()) {
+        walkAdd(p)
+        continue
+      }
+      if (e.isFile() && !seen.has(rel)) out.added.push(rel)
+    }
+  }
+  // 局部快照（paths）没扫过整个工作区，不能把"没记录的文件"说成"新增"
+  if (m.mode !== 'paths') walkAdd(m.root)
+  out.scope = m.mode || 'workspace'
+  return out
+}
+
+/* ---------------- 退回去 ---------------- */
+
+function restoreFrom(m, { dryRun, coverId, only }) {
+  const report = { wrote: [], already: [], refused: [], failed: [], dirsCreated: 0, coverId }
+
+  if (!dryRun) {
+    if (!coverId) throw new Error('NO_COVER')
+    const cover = loadManifest(coverId)
+    if (cover.status !== 'complete') throw new Error('COVER_INCOMPLETE')
+    if (usedBytes() > MAX_BYTES) throw new Error('OVER_QUOTA')
+  }
+
+  /* only：只退点名的这几个文件（他的原话：「我只想退卡片、不想动 README」）。
+     目录也只补建这些文件的上级，不去碰整份快照里的目录。 */
+  const files = only ? m.files.filter((f) => only.has(f.rel)) : m.files
+  const needDirs = new Set()
+  if (only) {
+    for (const f of files) {
+      const parts = f.rel.split('/')
+      for (let i = 1; i < parts.length; i++) needDirs.add(parts.slice(0, i).join('/'))
+    }
+  }
+  for (const d of m.dirs) {
+    if (only && !needDirs.has(d)) continue
+    if (!inside(m.root, d)) continue
+    const p = path.join(m.root, d)
+    if (!dryRun && !ex(p)) {
+      mk(p, { recursive: true })
+      report.dirsCreated++
+    }
+  }
+
+  for (const f of files) {
+    if (!inside(m.root, f.rel)) {
+      report.failed.push({ rel: f.rel, why: '路径越界' })
+      continue
+    }
+    const p = path.join(m.root, f.rel)
+    /* 词法上在里、真实路径也可能在外（父目录被换成目录联接）→ 先看真实路径，
+       再看目标本身是不是个链接；两样都不放过（评审 2026-11-14 的 P1）。 */
+    let lst = null
+    try {
+      lst = fs.lstatSync(wp(p))
+    } catch {}
+    if (lst && lst.isSymbolicLink()) {
+      report.refused.push({ rel: f.rel, why: '目标是符号链接，没敢覆盖（要退就先手动删掉这个链接）' })
+      continue
+    }
+    if (!realInside(m.root, p)) {
+      report.refused.push({ rel: f.rel, why: '真实路径不在工作区里（上面某级目录是链接），没写' })
+      continue
+    }
+    let cur = null
+    try {
+      cur = ex(p) ? sha(rd(p)) : null
+    } catch {
+      cur = null
+    }
+    if (cur === f.hash) {
+      report.already.push(f.rel)
+      continue
+    }
+    if (dryRun) {
+      report.wrote.push(f.rel)
+      continue
+    }
+
+    let before = null
+    try {
+      before = st(p)
+    } catch {}
+    try {
+      const blob = path.join(BLOB_DIR, f.hash.slice(0, 2), f.hash)
+      if (!ex(blob)) throw new Error('BLOB_MISSING')
+      const buf = rd(blob)
+      if (sha(buf) !== f.hash) throw new Error('BLOB_CORRUPT')
+
+      const t = tmpName(p)
+      mk(path.dirname(p), { recursive: true })
+      /* 写临时文件之前再确认一次：这一小会儿里父目录也可能被换成链接 */
+      if (!realInside(m.root, p)) throw new Error('OUTSIDE_REAL_ROOT')
+      wr(t, buf)
+      if (sha(rd(t)) !== f.hash) {
+        rm(t, { force: true })
+        throw new Error('TMP_VERIFY_FAILED')
+      }
+      let after = null
+      try {
+        after = st(p)
+      } catch {}
+      if (before && after && (before.size !== after.size || before.mtimeMs !== after.mtimeMs)) {
+        rm(t, { force: true })
+        throw new Error('TARGET_CHANGING')
+      }
+      rn(t, p)
+      try {
+        chmod(p, f.mode)
+        utimes(p, new Date(), new Date(f.mtimeMs))
+      } catch {}
+      if (sha(rd(p)) !== f.hash) throw new Error('POST_VERIFY_FAILED')
+      report.wrote.push(f.rel)
+    } catch (e) {
+      const code = String(e.message || e)
+      if (code === 'TARGET_CHANGING') report.refused.push({ rel: f.rel, why: '目标正在被改，没敢动' })
+      else if (code === 'OUTSIDE_REAL_ROOT') report.refused.push({ rel: f.rel, why: '真实路径不在工作区里，没写' })
+      else report.failed.push({ rel: f.rel, why: code })
+    }
+  }
+  return report
+}
+
+/* 一个文件都写不了的时候（真实路径越界／目标是链接／目标正在被改）：把原因说清楚，
+   别把"没写"说成"本来就一致"——那是假成功。 */
+function restoreBlockedText(head, r) {
+  const lines = []
+  if (r.refused.length) {
+    lines.push(
+      '没敢动 ' +
+        r.refused.length +
+        ' 个：\n' +
+        r.refused
+          .slice(0, 8)
+          .map((x) => '  · ' + x.rel + (x.why ? '：' + x.why : ''))
+          .join('\n'),
+    )
+  }
+  if (r.failed.length) {
+    lines.push('失败 ' + r.failed.length + ' 个：\n' + r.failed.slice(0, 8).map((x) => '  · ' + x.rel + '：' + x.why).join('\n'))
+  }
+  return head + '\n\n没有退成——这些文件写不了：\n\n' + lines.join('\n\n') + '\n\n修好再来一次（这个操作是幂等的）。'
+}
+
+/* ---------------- 清（都不自动，要点名） ---------------- */
+
+/* 一次性把所有被引用的块收集起来（别在循环里反复读 manifest，那是 O(n²)） */
+function allReferencedHashes(skipId) {
+  const refs = new Set()
+  let n = 0
+  for (const f of listDir(MAN_DIR)) {
+    if (!f.endsWith('.json')) continue
+    if (skipId && f === skipId + '.json') continue
+    if ((++n & 255) === 0) beatLocks()
+    try {
+      const m = JSON.parse(rd(path.join(MAN_DIR, f), 'utf8'))
+      ;(m.files || []).forEach((x) => refs.add(x.hash))
+    } catch {}
+  }
+  return refs
+}
+
+function forgetSnapshot(id) {
+  const m = loadManifest(id)
+  rm(path.join(MAN_DIR, id + '.json'), { force: true })
+  const refs = allReferencedHashes()
+  const orphanSet = new Set()
+  for (const f of m.files) if (!refs.has(f.hash)) orphanSet.add(f.hash)
+  return { id, files: m.files.length, orphanBlobs: orphanSet.size }
+}
+
+function gcBlobs() {
+  const t0 = Date.now()
+  const refs = allReferencedHashes()
+  let removed = 0
+  let bytes = 0
+  let bulkDirs = 0
+
+  /* 先按"前缀目录"整批看：一个目录里只要有一个块还被引用，就逐个处理；
+     整个目录都没被引用就直接整目录删——比一个个 rm 快几十倍。 */
+  let prefixes = []
+  try {
+    prefixes = listDir(BLOB_DIR, { withFileTypes: true }).filter((e) => e.isDirectory())
+  } catch {
+    return { removed: 0, bytes: 0, ms: Date.now() - t0, bulkDirs: 0 }
+  }
+
+  for (const d of prefixes) {
+    /* 这一段是整份 GC 最慢的地方（一个前缀目录里可能几万个块）：
+       每删一批就刷一下锁，别让 5 分钟的 TTL 把还活着的锁判死（评审 2026-11-14 的 P1）。 */
+    beatLocks()
+    const dir = path.join(BLOB_DIR, d.name)
+    let names = []
+    try {
+      names = listDir(dir, { withFileTypes: true }).filter((e) => e.isFile())
+    } catch {
+      continue
+    }
+    const keep = names.filter((e) => refs.has(e.name))
+    const drop = names.filter((e) => !refs.has(e.name))
+    drop.forEach((e) => {
+      try {
+        bytes += st(path.join(dir, e.name)).size
+      } catch {}
+    })
+    if (keep.length === 0) {
+      try {
+        rm(dir, { recursive: true, force: true })
+        removed += drop.length
+        bulkDirs++
+      } catch {}
+    } else {
+      let k = 0
+      for (const e of drop) {
+        try {
+          rm(path.join(dir, e.name), { force: true })
+          removed++
+        } catch {}
+        if ((++k & 1023) === 0) beatLocks()
+      }
+    }
+  }
+  return { removed, bytes, ms: Date.now() - t0, bulkDirs }
+}
+
+/* ---------------- 尝试簿 ---------------- */
+
+function appendAttempt(rec) {
+  ensureDirs()
+  appendF(ATTEMPT_FILE, JSON.stringify(rec) + '\n')
+  try {
+    const cutoff = Date.now() - ATTEMPT_KEEP_DAYS * 86400000
+    const lines = rd(ATTEMPT_FILE, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .filter((l) => {
+        try {
+          return JSON.parse(l).at >= cutoff
+        } catch {
+          return false
+        }
+      })
+    atomicWrite(ATTEMPT_FILE, Buffer.from(lines.join('\n') + '\n'))
+  } catch {}
+}
+
+function recallAttempts(paths, limit = 5) {
+  if (!ex(ATTEMPT_FILE)) return []
+  const want = new Set((paths || []).map(String))
+  const out = []
+  const lines = rd(ATTEMPT_FILE, 'utf8').split('\n').filter(Boolean)
+  for (const l of lines.reverse()) {
+    let r
+    try {
+      r = JSON.parse(l)
+    } catch {
+      continue
+    }
+    if (!r.outcome || r.outcome === 'ok') continue
+    if (want.size && !(r.paths || []).some((p) => want.has(p))) continue
+    out.push(r)
+    if (out.length >= limit) break
+  }
+  return out
+}
+
+/* ---------------- 工具一：trace_anchor ---------------- */
+
+const ANCHOR_DESC = [
+  '痕迹：动手之前拍一个点，改坏了能退回去。**只有改文件之前才用它**，只读操作不用拍。',
+  '',
+  '什么时候该按：',
+  '· 要用 write / edit / 批量替换 / 删文件 / 跑可能改文件的脚本之前 → 先 save',
+  '· 改完了想知道自己到底动了哪些、动了什么 → diff（它给的是内容差异，不只是文件名）',
+  '· 改坏了 / 他不满意 / 想换个做法 → restore',
+  '· 不确定要不要退 → 先 diff，再 restore（不带 confirm 时它只给清单，不写）',
+  '',
+  '动作：',
+  '· save    —— 拍一个点。整个工作区要 2 毫秒到几十秒（第一次慢，之后约 1 秒）。',
+  '  **只拍要改的那几个文件就快得多**：save({paths:["src/a.js","src/b.js"]}) —— 毫秒级，而且 restore 也只退这几个。',
+  '· list    —— 看拍过哪些点。',
+  '· diff    —— 看某个点到现在改了什么，带 +n/-n 和改动那几行的前后文。',
+  '· restore —— 退回去。**第一次不给 confirm 只返回清单，看完再带 confirm:true 才真写。**',
+  '  只想退某几个文件就带 paths:[...]（必须是那个点里拍过的；没拍到的退不了）。',
+  '· forget  —— 删掉某一个点（要 confirm）。块不会立刻回收，接着跑一次 gc。',
+  '· gc      —— 回收没有任何点引用的块。只动自己的数据目录。',
+  '   先带 compact:true 可以只算不删；真删几百 MB 可能要一两分钟，那期间别重复调。',
+  '',
+  '拍照有多快：第二次以后靠增量索引，只 stat 不重读。实测 7000 个文件 / 364MB 的工作区，',
+  '第一次约 30 秒（要读全量并落盘），之后每次约 1 秒。',
+  '',
+  '三条底线（改不了）：不自动删快照；不整目录覆盖（只碰这份快照记过的文件，不删你新增的）；',
+  '写文件一律临时文件+校验+原子替换，中途被杀也不会留半个文件。',
+  '',
+  '源文件被排除或跳过时（node_modules、.git、超过 50MB、符号链接），快照会标成 incomplete 并当场告诉你。',
+  'incomplete 的快照仍然能退回，但它"不全"这件事你必须知道——所以 restore 的保护快照必须是 complete 的。',
+  '',
+  '没拍点就直接写文件时，write / edit 的结果末尾会多出一句「［痕迹］…」——',
+  '那是我在提醒你"这次改动退不回去"，不是工具报错，也不是哪儿坏了。',
+].join('\n')
+
+const ANCHOR_PARAMS = {
+  type: 'object',
+  properties: {
+    action: {
+      type: 'string',
+      enum: ['save', 'list', 'diff', 'restore', 'forget', 'gc'],
+      description: '要做什么。',
+    },
+    root: {
+      type: 'string',
+      description: '工作区根目录（绝对路径）。save 时必填；其余动作可省略，沿用快照里记的那个根。',
+    },
+    label: { type: 'string', description: 'save 时给这个点起一句人话，比如"改导出功能之前"。' },
+    paths: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'save 时只拍这几个文件（相对 root 或绝对路径），毫秒级；给了它就只收这些，restore 也只退这些。restore 时给 paths 就只退点名的文件（必须是那个点里拍过的）。不给 = 整个工作区。',
+    },
+    id: { type: 'string', description: 'diff / restore / forget 时指定哪个点。' },
+    confirm: { type: 'boolean', description: 'restore / forget 专用。第一次别给，看完清单再给 true。' },
+    compact: {
+      type: 'boolean',
+      description: 'gc 专用。true 就只算要删多少、不真删。',
+    },
+    withContent: {
+      type: 'boolean',
+      description: 'diff 专用，默认 true。false 就只给文件名和条数（文件多时省 token）。',
+    },
+  },
+  required: ['action'],
+  additionalProperties: false,
+}
+
+const ANCHOR = {
+  name: 'trace_anchor',
+  description: ANCHOR_DESC,
+  parameters: ANCHOR_PARAMS,
+  output: {
+    schema: {
+      type: 'object',
+      properties: {
+        ok: { type: 'boolean' },
+        action: { type: 'string' },
+        text: { type: 'string' },
+        needsConfirm: { type: 'boolean' },
+        id: { type: 'string' },
+      },
+      required: ['ok', 'text'],
+    },
+    render: (_a, v) => [{ type: 'text', text: (v && v.text) || '' }],
+  },
+  async execute(args) {
+    const a = args || {}
+    const action = a.action
+
+    if (action === 'list') {
+      const list = listManifests(60)
+      if (!list.length) return { ok: true, action, text: '还没拍过任何点。' }
+      const manual = list.filter((m) => !m.auto)
+      const autos = list.filter((m) => m.auto)
+      const line = (m) =>
+        `${m.id}  ${m.atText}  ${m.status === 'complete' ? '完整' : '不完整'}  ${m.files.length} 个文件  ${mb(m.bytes)}  ${m.label || ''}`
+      const body = manual.length ? manual.slice(0, 20).map(line).join('\n') : '（没有手动拍的点）'
+      const total = usedBytes()
+      return {
+        ok: true,
+        action,
+        text:
+          `拍过的点（新的在上）：\n` +
+          body +
+          (autos.length
+            ? `\n\n另有 ${autos.length} 张自动快照（写文件前自动拍点 / restore 前的保护）：${autos
+                .slice(0, 5)
+                .map((m) => m.id)
+                .join('、')}${autos.length > 5 ? ' 等' : ''}`
+            : '') +
+          `\n\n占用合计 ${mb(total)} / 上限 ${mb(MAX_BYTES)}` +
+          `\n要腾地方：forget 掉某个点，再 gc 一次。`,
+      }
+    }
+
+    if (action === 'save') {
+      const root = a.root
+      if (!root) return { ok: false, action, text: 'save 需要给 root（工作区根目录的绝对路径）。' }
+      if (!ex(root) || !st(root).isDirectory()) {
+        return { ok: false, action, text: `这个目录不存在或者是文件：${root}` }
+      }
+      /* 局部快照不该为拍两个文件去扫整棵工作区（评审 2026-11-14 实测：3000 文件时 sweepTmp 占 22ms，
+         而且随工作区规模线性增长，与"paths 只 stat 点名的文件"的承诺不符）。
+         只拍点名文件时跳过；清残留临时文件的活留给全量快照。 */
+      const cleaned = Array.isArray(a.paths) && a.paths.length ? 0 : sweepTmp(root)
+      if (usedBytes() > MAX_BYTES) {
+        return {
+          ok: false,
+          action,
+          text: `存储到上限了（${mb(usedBytes())} / ${mb(MAX_BYTES)}）。我不自动删，先 forget 掉几个再 gc。`,
+        }
+      }
+      let m
+      try {
+        m = takeSnapshot(root, a.label, false, { paths: Array.isArray(a.paths) ? a.paths : null })
+      } catch (e) {
+        const code = String(e.message || e)
+        if (code === 'BUSY:save') return { ok: false, action, text: '另一个快照正在拍，等它完了再来（最多几分钟）。' }
+        throw e
+      }
+      if (m.mode === 'paths' && m.files.length === 0) {
+        return {
+          ok: false,
+          action,
+          text:
+            `一个文件都没拍下来（paths 模式）。\n` +
+            (m.missing.length ? `不存在：${m.missing.join('、')}\n` : '') +
+            (m.skipped.length ? `跳过：${m.skipped.map((s) => s.rel + '（' + s.why + '）').join('、')}\n` : '') +
+            `路径要相对工作区根目录，或者写绝对路径。`,
+        }
+      }
+      const warn =
+        m.status === 'incomplete'
+          ? `\n注意：这份不完整 —— ` +
+            [
+              m.concurrent.length ? `疑似正在被写 ${m.concurrent.length} 个` : '',
+              m.unreadable.length ? `读不了 ${m.unreadable.length} 个` : '',
+              m.skipped.length ? `跳过 ${m.skipped.length} 个（${m.skipped[0].why} 等）` : '',
+            ]
+              .filter(Boolean)
+              .join('；') +
+            `\n退回时不会碰这些文件，别以为它们在快照里。`
+          : ''
+      const scope =
+        m.mode === 'paths'
+          ? `只拍了点名的 ${m.files.length} 个文件 —— **restore 也只退这几个，别的文件一概不碰**。\n`
+          : ''
+      const gone = m.missing.length
+        ? `\n这几个现在还不存在，没有版本可存：${m.missing.join('、')}（退回时它们也不会被删掉）\n`
+        : ''
+      return {
+        ok: true,
+        action,
+        id: m.id,
+        text:
+          scope +
+          `拍好了：${m.id}${m.label ? '（' + m.label + '）' : ''}\n` +
+          `${m.files.length} 个文件 / ${m.dirs.length} 个目录 / ${mb(m.bytes)}，用时 ${m.ms}ms` +
+          (m.reused ? `（按上次记录复用 ${m.reused} 个，只重读 ${m.hashed} 个）` : '') +
+          `\n` +
+          (m.mode === 'workspace' && m.hashed > m.files.length * 0.5 && m.ms > 3000
+            ? `（第一次拍要读全量所以慢；同一个工作区之后每次约 1 秒。\n想更快就只拍要改的那几个：save({paths:['src/a.js']})）\n`
+            : '') +
+          `状态：${m.status === 'complete' ? '完整' : '不完整'}` +
+          (m.excluded.length ? `\n按约定排除：${m.excluded.length} 项（node_modules 之类）` : '') +
+          gone +
+          warn +
+          (cleaned ? `\n顺手清掉 ${cleaned} 个上次残留的临时文件。` : ''),
+      }
+    }
+
+    if (action === 'gc') {
+      /* 评审 2026-11-14：gc 以前没有锁，可能和 in-flight save 抢——
+         save 先写 blob、后写 manifest，gc 恰在中间跑会把新 blob 当孤儿删掉。
+         现在和 save 共用一把锁（同一时刻只允许一个快照/回收动作）。 */
+      let releaseGc
+      try {
+        releaseGc = acquire('save')
+      } catch (e) {
+        if (String(e.message || e).startsWith('BUSY:')) {
+          return { ok: false, action, text: '另一个快照正在拍（或回收正在跑），等它完了再来。' }
+        }
+        throw e
+      }
+      try {
+        if (a.compact) {
+          const refs = allReferencedHashes()
+          let n = 0
+          let bytes = 0
+          let dirs = 0
+          try {
+            for (const d of listDir(BLOB_DIR, { withFileTypes: true })) {
+              if (!d.isDirectory()) continue
+              const dir = path.join(BLOB_DIR, d.name)
+              const names = listDir(dir, { withFileTypes: true }).filter((e) => e.isFile())
+              const drop = names.filter((e) => !refs.has(e.name))
+              if (!drop.length) continue
+              if (drop.length === names.length) dirs++
+              for (const e of drop) {
+                n++
+                try {
+                  bytes += st(path.join(dir, e.name)).size
+                } catch {}
+              }
+            }
+          } catch {}
+          return {
+            ok: true,
+            action,
+            text: n
+              ? `要删 ${n} 个没人引用的块，约 ${mb(bytes)}（其中 ${dirs} 个目录会整个删掉）。\n真的删要一会儿——几百 MB 大概一两分钟。确认就再调一次不带 compact 的 gc。`
+              : '没有可回收的块。',
+          }
+        }
+        const r = gcBlobs()
+        return {
+          ok: true,
+          action,
+          text:
+            r.removed === 0
+              ? '没有可回收的块。'
+              : `回收了 ${r.removed} 个没人引用的块，腾出 ${mb(r.bytes)}，用了 ${(r.ms / 1000).toFixed(1)} 秒` +
+                (r.bulkDirs ? `（其中 ${r.bulkDirs} 个目录整个删掉）` : '') +
+                `。现在占用 ${mb(usedBytes())}。`,
+        }
+      } finally {
+        releaseGc()
+      }
+    }
+
+    if (action === 'forget') {
+      if (!a.id) return { ok: false, action, text: '要给 id。先 list 看有哪些。' }
+      let m
+      try {
+        m = loadManifest(a.id)
+      } catch {
+        return { ok: false, action, text: `没有这个点：${a.id}` }
+      }
+      if (!a.confirm) {
+        return {
+          ok: true,
+          action,
+          id: a.id,
+          needsConfirm: true,
+          text:
+            `要删的是：${m.id}（${m.atText}${m.label ? ' · ' + m.label : ''}）\n` +
+            `${m.files.length} 个文件 / ${mb(m.bytes)}\n\n` +
+            `删掉这个点以后就退不回它了。**这一步不动你工作区里的任何文件**，只动我自己的存档。\n` +
+            `确认要删，再调一次带 confirm:true。`,
+        }
+      }
+      /* 评审 2026-11-14：forget 也和 save 共用一把锁，避免删到正在拍的那份 */
+      let releaseF
+      try {
+        releaseF = acquire('save')
+      } catch (e) {
+        if (String(e.message || e).startsWith('BUSY:')) {
+          return { ok: false, action, text: '另一个快照正在拍（或回收正在跑），等它完了再来。' }
+        }
+        throw e
+      }
+      try {
+        const r = forgetSnapshot(a.id)
+        return {
+          ok: true,
+          action,
+          id: a.id,
+          text: `删掉了 ${r.id}。它的 ${r.files} 个文件记录没了，其中 ${r.orphanBlobs} 个内容块变成没人引用。\n接着跑一次 gc 就能把地方腾出来。`,
+        }
+      } finally {
+        releaseF()
+      }
+    }
+
+    if (action === 'diff' || action === 'restore') {
+      if (!a.id) return { ok: false, action, text: '要给 id。先 trace_anchor({action:"list"}) 看有哪些。' }
+      let m
+      try {
+        m = loadManifest(a.id)
+      } catch (e) {
+        return {
+          ok: false,
+          action,
+          text: String(e.message) === 'NOT_FOUND' ? `没有这个点：${a.id}` : '点 id 不合法。',
+        }
+      }
+      if (!ex(m.root)) return { ok: false, action, text: `那个工作区不在了：${m.root}` }
+
+      const d = diffOf(m, { withContent: a.withContent !== false })
+      const scopeNote = d.scope === 'paths' ? `\n（这是个**局部快照**：只记了 ${m.files.length} 个文件，所以不报"新增"——没记录的不等于新加）` : ''
+      const head =
+        `对比 ${m.id}（${m.atText}${m.label ? ' · ' + m.label : ''}）→ 现在\n` +
+        `改了 ${d.modified.length} 个 / 删了 ${d.deleted.length} 个` +
+        (d.scope === 'paths' ? '' : ` / 新增 ${d.added.length} 个`) +
+        ` / 没变 ${d.same} 个` +
+        scopeNote
+
+      if (action === 'diff') {
+        const cap = (arr) => arr.slice(0, 12).map((x) => '  · ' + (x.rel || x)).join('\n')
+        const more = (arr) => (arr.length > 12 ? `\n  …… 还有 ${arr.length - 12} 个` : '')
+        const blocks = d.details
+          .map(
+            (x) =>
+              `\n── ${x.rel}  ${x.added != null ? `+${x.added}/-${x.removed}` : ''}${x.at ? `（第 ${x.at} 行起）` : ''}\n` +
+              (x.binary
+                ? '  （二进制文件，只报条数，不塞内容）'
+                : x.tooBig
+                  ? `  （${KB(x.size)}，太大了，只报条数）`
+                  : x.blobMissing
+                    ? '  （原始内容丢了，只报条数）'
+                    : x.lines.slice(0, 26).join('\n')),
+          )
+          .join('')
+        return {
+          ok: true,
+          action,
+          id: m.id,
+          text:
+            head +
+            (d.modified.length ? '\n\n改了：\n' + cap(d.modified) + more(d.modified) : '') +
+            (d.deleted.length ? '\n\n删了：\n' + cap(d.deleted) + more(d.deleted) : '') +
+            (d.added.length ? '\n\n新增（退回去时不会删它们）：\n' + cap(d.added) + more(d.added) : '') +
+            (blocks ? '\n\n内容差异：' + blocks : ''),
+        }
+      }
+
+      /* restore：带 paths 就只退点名的这几个文件（退不了没拍过的） */
+      let only = null
+      if (Array.isArray(a.paths) && a.paths.length) {
+        const wanted = a.paths.filter((x) => typeof x === 'string' && x.trim())
+        only = new Set(
+          wanted.map((raw) => {
+            const abs = path.isAbsolute(raw) ? raw : path.join(m.root, raw)
+            return path.relative(m.root, abs).split(path.sep).join('/')
+          }),
+        )
+        const have = new Set(m.files.map((f) => f.rel))
+        const missing = [...only].filter((x) => !have.has(x))
+        if (missing.length) {
+          const sample = m.files.slice(0, 10).map((f) => '  · ' + f.rel).join('\n')
+          return {
+            ok: false,
+            action,
+            id: m.id,
+            text:
+              `这个点里没有这几个文件，退不了：\n` +
+              missing.map((x) => '  · ' + x).join('\n') +
+              `\n\n可能是拍点之后才新建的——新建的文件本来就不在快照里，restore 也不会删它。\n` +
+              `这个点里拍到的是这些：\n${sample}${m.files.length > 10 ? `\n  …… 还有 ${m.files.length - 10} 个` : ''}`,
+          }
+        }
+      }
+
+      /* restore */
+      if (!a.confirm) {
+        const plan = restoreFrom(m, { dryRun: true, only })
+        if (!plan.wrote.length) {
+          if (plan.refused.length || plan.failed.length) {
+            return { ok: false, action, id: m.id, text: restoreBlockedText(head, plan) }
+          }
+          return { ok: true, action, id: m.id, text: head + '\n\n现在就和那个点一致，不用退。' }
+        }
+        return {
+          ok: true,
+          action,
+          id: m.id,
+          needsConfirm: true,
+          text:
+            head +
+            (only ? `\n\n（只退点名的 ${only.size} 个文件，别的文件一概不碰）` : '') +
+            `\n\n退回去会写 ${plan.wrote.length} 个文件，其余 ${plan.already.length} 个本来就一致。` +
+            `\n它不会删你新增的文件，也不会碰这份快照没记过的东西。` +
+            `\n写之前会先拍一张"回滚前的现场"，那张拍不成就整个不执行。` +
+            `\n\n要退的：\n${plan.wrote.slice(0, 12).map((x) => '  · ' + x).join('\n')}${plan.wrote.length > 12 ? `\n  …… 还有 ${plan.wrote.length - 12} 个` : ''}` +
+            `\n\n确认要退，就再调一次，带 confirm:true。`,
+        }
+      }
+
+      /* 确认了但本来就不用退：不拍保护快照、不写着 0 个的"成功" */
+      const pre = restoreFrom(m, { dryRun: true, only })
+      if (!pre.wrote.length) {
+        if (pre.refused.length || pre.failed.length) {
+          return { ok: false, action, id: m.id, text: restoreBlockedText(head, pre) }
+        }
+        return {
+          ok: true,
+          action,
+          id: m.id,
+          text: head + '\n\n现在就和那个点一致，不用退。' + (only ? `（只看了点名的 ${only.size} 个）` : ''),
+        }
+      }
+
+      const releaseR = acquire('restore')
+      try {
+        let cover
+        try {
+          /* 保护快照只需要"这次要写的这几个文件"的旧样子。
+             整工作区快照会因为他那几个 1GB 视频被"超过 50MB 跳过"而永远标成不完整，
+             于是一次 restore 都退不了（2026-11-13 23:2x 真机实测撞出来的）。
+             restore 本来就只碰这份快照记过的文件，保护快照也只拍这些就够了。 */
+          const coverPaths = only ? [...only] : (m.files || []).map((x) => x.rel).filter(Boolean)
+          cover = takeSnapshot(m.root, '回滚前的现场（自动）', true, { paths: coverPaths })
+          if (cover.status !== 'complete') {
+            return {
+              ok: false,
+              action,
+              text: `没退。保护快照不完整（这次要退的 ${coverPaths.length} 个文件里，有正在被写或读不了的），这时候退下去就没法再救回来。等几秒再试。`,
+            }
+          }
+        } catch (e) {
+          return { ok: false, action, text: '没退。保护快照没拍成：' + String(e.message || e) }
+        }
+
+        let r
+        try {
+          r = restoreFrom(m, { dryRun: false, coverId: cover.id, only })
+        } catch (e) {
+          const code = String(e.message || e)
+          const why =
+            code === 'OVER_QUOTA'
+              ? '存储到上限了，先 forget 几个点再 gc。'
+              : code === 'COVER_INCOMPLETE'
+                ? '保护快照不完整。'
+                : code
+          return { ok: false, action, text: '没退。' + why }
+        }
+
+        const bad = r.failed.length + r.refused.length
+        return {
+          ok: bad === 0,
+          action,
+          id: m.id,
+          text:
+            `退回 ${m.id}：写了 ${r.wrote.length} 个，本来一致 ${r.already.length} 个` +
+            (only ? `（只退点名的 ${only.size} 个）` : '') +
+            (r.dirsCreated ? `，补建 ${r.dirsCreated} 个空目录` : '') +
+            `\n保护快照：${cover.id}（想反悔就用它再退一次）` +
+            (r.refused.length
+              ? `\n\n没敢动 ${r.refused.length} 个：\n` +
+                r.refused
+                  .slice(0, 8)
+                  .map((x) => '  · ' + x.rel + (x.why ? '：' + x.why : ''))
+                  .join('\n')
+              : '') +
+            (r.failed.length
+              ? `\n\n失败 ${r.failed.length} 个：\n` + r.failed.slice(0, 8).map((x) => '  · ' + x.rel + '：' + x.why).join('\n')
+              : '') +
+            (bad ? `\n\n上面这些没退成，可以修好再退一次（这个操作是幂等的）。` : ''),
+        }
+      } catch (e) {
+        const code = String(e.message || e)
+        if (code === 'BUSY:restore') return { ok: false, action, text: '另一个退回正在跑，等它完（最多几分钟）。' }
+        throw e
+      } finally {
+        releaseR()
+      }
+    }
+
+    return { ok: false, action, text: '不认识的 action：' + action }
+  },
+}
+
+/* ---------------- 工具二：trace_attempt ---------------- */
+
+const ATTEMPT_DESC = [
+  '尝试簿：把"我试了什么、怎么挂的"记下来，免得在同一个坑里试第三遍。',
+  '',
+  '· log    —— 记一条。失败了就该记：动作是什么、报错原文、你判断的原因、什么条件下值得再试。',
+  '· recall —— 按文件路径捞历史失败记录。**它只回记录，不判断、不拦你**，你自己决定要不要换个路子。',
+  '',
+  '一次就成的事不用记。反复挂、或者"看起来该成却没成"的，才值得记。',
+  '注意：这里没有"自动判定这是不是同一个坑"的功能。第一版故意不做——判错了会让我不信它。',
+].join('\n')
+
+const ATTEMPT = {
+  name: 'trace_attempt',
+  description: ATTEMPT_DESC,
+  parameters: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['log', 'recall'], description: '记一条，还是捞记录。' },
+      did: { type: 'string', description: 'log 必填：你做了什么（一句话，具体到动作）。' },
+      paths: { type: 'array', items: { type: 'string' }, description: '涉及的相对路径。' },
+      error: { type: 'string', description: '报错原文，别转述。' },
+      why: { type: 'string', description: '你判断的原因。' },
+      retryWhen: { type: 'string', description: '什么条件下值得再试。' },
+      outcome: { type: 'string', enum: ['ok', 'failed', 'partial'], description: '结果。默认 failed。' },
+    },
+    required: ['action'],
+    additionalProperties: false,
+  },
+  output: {
+    schema: {
+      type: 'object',
+      properties: { ok: { type: 'boolean' }, text: { type: 'string' } },
+      required: ['ok', 'text'],
+    },
+    render: (_a, v) => [{ type: 'text', text: (v && v.text) || '' }],
+  },
+  async execute(args) {
+    const a = args || {}
+    if (a.action === 'log') {
+      if (!a.did) return { ok: false, text: 'log 至少要给 did。' }
+      appendAttempt({
+        at: Date.now(),
+        atText: nowIso(),
+        did: a.did,
+        paths: a.paths || [],
+        error: a.error || '',
+        why: a.why || '',
+        retryWhen: a.retryWhen || '',
+        outcome: a.outcome || 'failed',
+      })
+      return { ok: true, text: `记下了：${a.did}${a.why ? '（' + a.why + '）' : ''}` }
+    }
+    if (a.action === 'recall') {
+      const rs = recallAttempts(a.paths, 5)
+      if (!rs.length) return { ok: true, text: '这些文件上没有失败记录。' }
+      return {
+        ok: true,
+        text:
+          '历史上在这几个文件上挂过：\n' +
+          rs
+            .map(
+              (r, i) =>
+                `${i + 1}. ${r.atText} · ${r.did}\n   ${r.error ? '报错：' + r.error.slice(0, 200) + '\n   ' : ''}${r.why ? '原因：' + r.why + '\n   ' : ''}${r.retryWhen ? '值得再试：' + r.retryWhen : ''}`.trim(),
+            )
+            .join('\n\n'),
+      }
+    }
+    return { ok: false, text: '不认识的 action。' }
+  },
+}
+
+/* ---------------- 主动用兜底：没拍点，就在写文件的结果里补一句 ----------------
+ *
+ * 这插件最大的风险不是"退不回去"，是"装了却想不起来用"。
+ * 所以它要在模型动手的那一刻自己出声，而不是等人记得它。
+ *
+ * 只做一件事：写文件类工具跑完，如果这次写的文件不在拍过的点里，
+ * 就在那份结果的末尾追加一段文字（不改结果本身、不拦调用、不假报成功）。
+ *
+ * 克制：每场最多 3 次，两次之间至少隔 2 次写。宁可漏，不要吵。
+ * 关掉：~/.dsh/dsh-trace/config.json 写 {"remind": false}。
+ */
+
+const WRITE_TOOL_RE = /^(write|edit|insert|apply_patch|multi_edit|str_replace.*)$/i
+const REMIND_MAX = 3
+const REMIND_GAP = 2
+const CONFIG_FILE = path.join(HOME, 'config.json')
+const SESSION_STATE = new WeakMap()
+
+function remindEnabled() {
+  if (!ex(CONFIG_FILE)) return true
+  try {
+    const cfg = JSON.parse(rd(CONFIG_FILE, 'utf8'))
+    return !(cfg && cfg.remind === false)
+  } catch {
+    return true
+  }
+}
+
+function autoSaveEnabled() {
+  if (!ex(CONFIG_FILE)) return true
+  try {
+    const cfg = JSON.parse(rd(CONFIG_FILE, 'utf8'))
+    return !(cfg && cfg.autoSave === false)
+  } catch {
+    return true
+  }
+}
+
+function normRel(p) {
+  return String(p || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '')
+    .toLowerCase()
+}
+
+function relFor(root, p) {
+  const n = normRel(p)
+  if (!root) return n
+  const r = normRel(root).replace(/\/+$/, '')
+  if (n === r) return ''
+  return n.startsWith(r + '/') ? n.slice(r.length + 1) : n
+}
+
+/* 这个文件在不在拍过的点里：全工作区快照覆盖一切；paths 快照只认点名的 */
+function coveredBy(saves, target, root) {
+  const t = relFor(root, target)
+  if (!t) return false
+  for (const s of saves) {
+    if (!s.paths) return true
+    if (s.paths.has(relFor(s.root, target))) return true
+  }
+  return false
+}
+
+function stateOf(agent) {
+  let s = SESSION_STATE.get(agent)
+  if (!s) {
+    s = { saves: [], writes: 0, nags: 0, lastNagAt: -999 }
+    SESSION_STATE.set(agent, s)
+  }
+  return s
+}
+
+function reminderFor(exec, result) {
+  if (!exec || !exec.agent) return null
+  const name = String(exec.name || '')
+  const a = exec.arguments && typeof exec.arguments === 'object' ? exec.arguments : {}
+
+  if (name === 'trace_anchor') {
+    if (a.action === 'save' && !(result && result.isError) && !(result && result.value && result.value.ok === false)) {
+      stateOf(exec.agent).saves.push({
+        root: a.root || null,
+        paths: Array.isArray(a.paths) ? new Set(a.paths.map((p) => relFor(a.root, p))) : null,
+      })
+    }
+    return null
+  }
+  if (!WRITE_TOOL_RE.test(name)) return null
+  if (!remindEnabled()) return null
+
+  const s = stateOf(exec.agent)
+  s.writes++
+  const target = a.file_path || a.path || a.filePath || ''
+  if (coveredBy(s.saves, target, null)) return null
+  if (s.nags >= REMIND_MAX) return null
+  if (s.writes - s.lastNagAt < REMIND_GAP) return null
+  s.nags++
+  s.lastNagAt = s.writes
+
+  const file = target ? String(target).replace(/\\/g, '/').split('/').pop() : '要改的文件'
+  const text =
+    s.saves.length === 0
+      ? `［痕迹］这次会话还没拍过点——刚才这次写退不回去。\n` +
+        `下次动手前先 trace_anchor save({paths:["${file}"]})：只拍点名的文件是毫秒级，改坏了能退。`
+      : `［痕迹］"${file}" 不在你拍过的点里，它退不回去。\n` +
+        `要保它就 trace_anchor save({paths:["${file}"]}) 再写。`
+  return { type: 'text', text: '\n\n' + text }
+}
+
+/* ---------------- 自动拍点：写文件之前先把"现在的样子"存下来 ----------------
+ *
+ * 两层提醒（提示词 + 写完补一句）都只能"劝"模型想起来拍点，第一笔改动还是保不住。
+ * 所以加第三层：写文件类工具**真正执行前**，如果这个文件还没进过任何点，
+ * 就自动拍一张（paths 模式，毫秒级），第一笔改动也退得回去。
+ *
+ * 只拍"还没拍过的、真实存在的、≤50MB 的普通文件"；拍不成（新文件/太大/在工作区外/
+ * 根拿不到）就静默跳过，交给写完那层的提醒兜底。不拦调用、不改结果、失败也不抛。
+ * 关掉：config.json 写 {"autoSave": false}。
+ */
+
+function writeTargetOf(a) {
+  return String((a && (a.file_path || a.path || a.filePath)) || '')
+}
+
+function autoSaveBeforeWrite(exec) {
+  if (!autoSaveEnabled()) return null
+  const name = String(exec.name || '')
+  if (!WRITE_TOOL_RE.test(name)) return null
+  const a = exec.arguments && typeof exec.arguments === 'object' ? exec.arguments : {}
+  const target = writeTargetOf(a)
+  if (!target || !path.isAbsolute(target)) return null
+  if (!ex(target)) return null // 新文件没有"旧样子"，跳
+  let stt
+  try {
+    stt = fs.lstatSync(wp(target))
+  } catch {
+    return null
+  }
+  if (!stt.isFile() || stt.size > BIG_FILE) return null
+
+  /* 根：宿主给的会话工作区根。DSH 0.2.2 的 Agent 上没有 cwd（cwd 在 agent.session.header.cwd，
+     session header 是深冻结的创建元数据）；旧宿主/测试可能仍放在 agent.cwd。两个都认。
+     拿不到就跳过，靠写完那层提醒兜底。 */
+  const ag = exec.agent
+  const root =
+    (ag && typeof ag.cwd === 'string' && ag.cwd) ||
+    (ag && ag.session && ag.session.header && typeof ag.session.header.cwd === 'string' && ag.session.header.cwd) ||
+    null
+  if (!root || !path.isAbsolute(root)) return null
+  try {
+    if (!st(root).isDirectory()) return null
+  } catch {
+    return null
+  }
+  if (!realInside(root, target)) return null
+
+  const s = stateOf(exec.agent)
+  if (coveredBy(s.saves, target, null)) return null
+
+  let m
+  try {
+    m = takeSnapshot(root, '自动拍点', true, { paths: [target] })
+  } catch {
+    return null
+  }
+  if (!m.files.length) return null // 没拍下来（排除/太大/读不了），别假装拍过
+  s.saves.push({ root, paths: new Set([relFor(root, target)]) })
+  return { id: m.id, rel: relFor(root, target) }
+}
+
+/* ---------------- 系统提示词里那一句（v0.5） ----------------
+ *
+ * 兜底只能落在"写完之后"，第一笔改动保不住。要在动手之前就在，就得进系统提示词。
+ * 位置放在 write 工具说明的前一条（1200 是 TOOL_WRITE 的位置，1199 正好在它前面），
+ * 模型读到 write 的时候，上一句就是"先拍个点"。
+ *
+ * 只有一句，不解释原理、不重复工具描述。{"remind": false} 时整条不注册。
+ */
+
+const PROMPT_SECTION = 'dsh-trace:remind'
+const PROMPT_ORDER = 1199
+const PROMPT_TEXT =
+  '写文件前会自动拍点，改坏了能 restore；想留个明确的检查点就手动 trace_anchor save({root, paths:["要改的文件"]})。'
+
+function registerPromptHint(ctx) {
+  if (!remindEnabled()) return
+  const sp = ctx.systemPrompt
+  if (!sp || typeof sp.section !== 'function') return
+  const reg = () =>
+    sp.section({
+      name: PROMPT_SECTION,
+      order: PROMPT_ORDER,
+      text: PROMPT_TEXT,
+    })
+  if (typeof ctx.effect === 'function') ctx.effect(reg, 'dsh-trace.promptHint()')
+  else reg()
+}
+
+export function apply(ctx) {
+  ensureDirs()
+  ctx.tools.register(ANCHOR)
+  ctx.tools.register(ATTEMPT)
+
+  try {
+    registerPromptHint(ctx)
+  } catch {
+    /* 没有提示词口（离线测试的假 ctx）就当没这一层，工具照用 */
+  }
+
+  /* 宿主没有事件口时（离线测试的假 ctx）就只注册工具，不硬连 */
+  if (typeof ctx.on !== 'function') return
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    /* 写之前自动拍点：拍得成就在本会话记一笔，拍不成就静默，交给写完那层提醒。 */
+    try {
+      autoSaveBeforeWrite(exec)
+    } catch {
+      /* 绝不因为自动拍点失败拦住这次写 */
+    }
+    return next()
+  })
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    let extra = null
+    try {
+      extra = reminderFor(exec, result)
+    } catch {
+      extra = null
+    }
+    const downstream = await next()
+    if (!extra || !downstream || typeof downstream !== 'object') return downstream
+    if (downstream.kind === 'block' || Object.hasOwn(downstream, 'value')) return downstream
+    const base = Array.isArray(downstream.content) ? downstream.content : (result && result.content) || []
+    return { ...downstream, content: [...base, extra] }
+  })
+}
+
+export { ANCHOR, ATTEMPT, VERSION, HOME, takeSnapshot, loadManifest, restoreFrom, diffOf, gcBlobs }