thincoder 0.12.53 → 0.12.58

package/src/tools/apply_patch.md

@@ -1,5 +1,7 @@
 Apply a unified diff to one or more files, atomically: if any hunk fails to apply, nothing is written.
 
+**Use it for whole-file and multi-file changes:** creating MULTIPLE new files at once (`--- /dev/null` header per file), whole-file replacement, and cross-file refactors — one unified-diff call covers the whole change. A batched call is one permission ask and one turn instead of N separate calls.
+
 Parameters:
 - patch (required): Unified diff text. One `--- a/path` / `+++ b/path` header pair per file, then `@@ -old,count +new,count @@` hunks. Use `--- /dev/null` to create a new file.
 

package/src/tools/bash.md

@@ -33,5 +33,5 @@ Notes:
 - Never use bash to read, copy, or transmit secret files (.env, keys, tokens)
 - Do NOT run destructive commands (rm -rf, force-push, drop table) without explicit user confirmation
 - After commands that change files (git checkout, npm install, etc.), repo_outline and code_search may be stale — re-run them to get current results.
-- Prefer read/glob/grep/ls for file operations inside the project — bash has no directory confinement.
-- NEVER use bash to write or modify files (echo/sed/printf > file, cat << EOF, etc.). Use write/edit/insert_after/apply_patch instead — they handle encoding, escaping, and directory confinement correctly.
+- Prefer read/glob/grep/ls for file operations inside the project — file tools and bash reach the same paths (no directory restriction).
+- NEVER use bash to write or modify files (echo/sed/printf > file, cat << EOF, etc.). Use write/edit/insert_after/apply_patch instead — they handle encoding, escaping, and EOL conventions correctly.

package/src/tools/edit-batch.mjs

@@ -0,0 +1,104 @@
+/**
+ * edit-batch.mjs — edit 工具的数组形态（edits: [...]）：一次多文件原子替换。
+ * （2026-08-31 工具顺手度 §9 ②；2026-09-01 缺陷修复"同文件多条串行累积"。）
+ * 从 file.mjs 拆出（500 行硬限，先例 git-ext.mjs）——纯移动，零行为变化。
+ *
+ * 语义：同一 path 的多条编辑按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的
+ * 累积内容做匹配与替换；跨 path 条目互不影响（并行原子语义）；任一条失败 →
+ * 全不写（原子性保留）。
+ */
+import { readFile, writeFile } from "node:fs/promises"
+import { resolveInCwd, normalizeEOL, joinWithEol, gitDiffOne, autoSyntaxCheck } from "./shared.mjs"
+// file.mjs ↔ edit-batch.mjs 循环引用：两侧导入的都是函数声明（提升初始化），
+// 仅在调用期使用——ESM 循环下安全（无模块求值期取值）。
+import { recordWrite, appendWriteContext } from "./file.mjs"
+
+/**
+ * Apply the `edits` array form: multi-file atomic replacement. Throws on any
+ * failure (atomic — nothing written). Returns the per-entry result text (joined).
+ */
+export async function applyEditBatch(args, ctx) {
+  if (!Array.isArray(args.edits) || args.edits.length === 0) {
+    throw new Error("edits must be a non-empty array of {path, old_string, new_string}")
+  }
+  if (args.path || args.old_string !== undefined || args.new_string !== undefined) {
+    throw new Error("edits array is mutually exclusive with path/old_string/new_string")
+  }
+  // 原子：先全量检查（所有文件的替换都可执行）——任一失败全不写。
+  // 2026-09-01 缺陷修复（TOOLS.md §9 ②"同文件多条规则"）：同一 path 的多条编辑
+  // 按序**串行累积应用**——第 n 条基于前 n-1 条已应用后的累积内容做匹配与替换
+  // （原实现每条都基于盘上原始内容计算、写盘循环后置，同文件后者覆盖前者 →
+  // 除最后一条外全部静默丢失）；跨 path 条目互不影响（并行原子语义不变）。
+  const groups = new Map() // abs → 每文件一条流水线
+  for (const e of args.edits) {
+    if (!e.path) throw new Error("each edit must have a path")
+    if (!e.old_string) throw new Error(`edit for ${e.path}: old_string must not be empty`)
+    if (typeof e.new_string !== "string") {
+      throw new Error(
+        `edit for ${e.path}: new_string must be a string` +
+        `${e.new_string === undefined ? " (missing)" : ` (got ${typeof e.new_string})`}`,
+      )
+    }
+    const abs = resolveInCwd(ctx, e.path)
+    let g = groups.get(abs)
+    if (!g) {
+      const raw = await readFile(abs, "utf8")
+      g = { abs, path: e.path, raw, content: normalizeEOL(raw), edits: [] }
+      groups.set(abs, g)
+    }
+    g.edits.push(e)
+  }
+  const prepared = [] // 顺序 = args.edits 顺序（回显按条）；recordWrite 每组一条合并快照
+  for (const g of groups.values()) {
+    g.netShift = 0 // 组内行数差累积（合并快照的 shift = 全组净漂移）
+    for (const e of g.edits) {
+      const content = g.content
+      const occurrences = content.split(e.old_string).length - 1
+      if (occurrences === 0) {
+        throw new Error(
+          `edit aborted (atomic — no files written): old_string not found in ${g.path}\n` +
+          `  searched: "${e.old_string.slice(0, 100).split("\n")[0]}${e.old_string.length > 100 ? "…" : ""}"`
+        )
+      }
+      if (occurrences > 1 && !e.replace_all) {
+        throw new Error(
+          `edit aborted (atomic — no files written): old_string matches ${occurrences} times in ${g.path}; ` +
+          `provide more context or set replace_all`
+        )
+      }
+      const matchIdx = content.indexOf(e.old_string)
+      const editStartLine = matchIdx >= 0 ? content.slice(0, matchIdx).split("\n").length : 1
+      const lineShift = e.new_string.split("\n").length - e.old_string.split("\n").length
+      const updated = e.replace_all
+        ? content.split(e.old_string).join(e.new_string)
+        : content.replace(e.old_string, () => e.new_string)
+      prepared.push({
+        g,
+        editStartLine, // 基于累积内容计算——已天然计入前面条目的行偏移，不再累加
+        lineShift,
+        occurrences: e.replace_all ? occurrences : 1,
+      })
+      g.content = updated // 串行累积：下一条基于本条应用后的内容
+      g.netShift += lineShift
+    }
+  }
+  // 全部检查通过——每文件一次写盘（同文件多条：写入串行累积后的最终内容）；
+  // recordWrite 每组一条合并快照：startLine = 组内**所有**编辑受影响行的最小值
+  // （#2，2026-09-01 交付评审尾巴——原实现取首条 = 调用序第一条，逆序条目时
+  // 护栏下界过高、受影响区内的 insert_after 被放行），shift = 全组行数差累积
+  // ——受影响区护栏覆盖组内所有编辑
+  for (const g of groups.values()) {
+    const startLine = Math.min(...prepared.filter((p) => p.g === g).map((p) => p.editStartLine))
+    await writeFile(g.abs, joinWithEol(normalizeEOL(g.content).split("\n"), g.raw), "utf8")
+    recordWrite(g.abs, { type: "edit", startLine, shift: g.netShift })
+  }
+  const results = []
+  for (const p of prepared) {
+    // #4（2026-09-01 交付评审尾巴）：与单文件路径对齐——每条结果附 git diff +
+    // autoSyntaxCheck（同文件多条会重复 diff/检查，换取格式一致、实现零分支）
+    const diff = gitDiffOne(ctx.cwd, p.g.abs)
+    const base = `Edited ${p.g.path}: replaced ${p.occurrences} occurrence(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(p.g.abs)}`
+    results.push(await appendWriteContext(p.g.abs, p.editStartLine, base))
+  }
+  return results.join("\n")
+}

package/src/tools/edit.md

@@ -8,11 +8,14 @@ Edit a file by exact string replacement. old_string must match exactly once unle
 - Rewrite an entire file → `write`
 - Rename a symbol project-wide → `lsp` or `grep` first to map every caller
 
+**Batch multiple edits into ONE call via the `edits` array** (preferred over N single edit calls): multiple changes to the SAME file go into one `edits` array (entries are applied serially, each based on the previous one's result); independent changes across MULTIPLE files also go into the same `edits` array — one call, atomic (any failure writes nothing). A batched call is one permission ask, one undo unit, and one turn instead of N.
+
 Parameters:
 - path (required): File path
 - old_string (required): Exact text to find and replace
 - new_string (required): Replacement text
 - replace_all: Replace all occurrences instead of just one (default false)
+- edits: Array of {path, old_string, new_string, replace_all?} entries — batch form; mutually exclusive with path/old_string/new_string
 
 Notes:
 - Prefer this over write for targeted edits — it's safer and keeps changes targeted

package/src/tools/execute.md

@@ -1,4 +1,4 @@
-Execute JavaScript — either inline `code` or a workspace `scriptFile`. Runs in a real `node` process with top-level `await` and dynamic `import()`. Use inline `code` to compose multiple operations into one call — read, write, glob, grep, log, import, or require() — without shelling out to `bash node -e`.
+Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real `node` process with top-level `await` and dynamic `import()`. Use inline `code` to compose multiple operations into one call — read, write, glob, grep, log, import, or require() — without shelling out to `bash node -e`.
 
 **Route to execute instead of bash:**
 - `node -e "…"` → execute (inline code; top-level await + import() + console all work)
@@ -7,15 +7,15 @@ Execute JavaScript — either inline `code` or a workspace `scriptFile`. Runs in
 
 Parameters:
 - code: JavaScript to run inline. Top-level `await` and `import('./x.mjs')` are supported. Globals: readFile(path), writeFile(path, content), glob(pattern), grep(pattern, file), log(...args) — plus native require/process/console/fetch/import. Use this OR scriptFile.
-- scriptFile: run a workspace .mjs/.js file with node (self-contained — no prelude; the file imports what it needs). Path relative to workdir, confined to the workspace. Use this OR code.
+- scriptFile: run a .mjs/.js file with node (self-contained — no prelude; the file imports what it needs). Path relative to workdir — no directory restriction. Use this OR code.
 - nodeArgs: (scriptFile) extra node flags before the script, e.g. ["--test"], ["--check"]. Eval-like flags (--eval/--input-type/--inspect) are rejected.
-- workdir: run in this directory (relative to cwd, confined to the workspace; default cwd)
+- workdir: run in this directory (relative to cwd — no directory restriction; default cwd)
 - filter: optional — only return output lines matching this regex (case-insensitive)
 - timeoutMs: Timeout in milliseconds (default 30000, max 600000 — covers slow `node --test` suites and long package scripts)
 
 Notes:
 - `console.log(...)` and `log(...)` both print to the result; objects are JSON-stringified by `log`.
-- File paths are confined to the workspace root (`..` traversal is denied) — but `require`/`process`/`import()` are full Node, same boundary as bash.
+- The prelude's readFile/writeFile/glob/grep helpers resolve paths against the working directory (helper-only guard — `require`/`process`/`import()` are full Node, same boundary as bash).
 - A non-zero exit / thrown exception returns the stderr (error + stack) as the result.
 - Output capped at ~50KB; use `writeFile` to a file if you need more.
 - Use `write`/`edit`/`apply_patch` for source edits. Still use `bash` for package-manager/CLI subprocesses (`npm test`/`npm publish`/`vsce`), servers, and interactive/TTY programs — execute covers in-process JS and `node <script>`/`node --test`/`node --check`, not arbitrary CLI or long-running programs.

package/src/tools/execute.mjs

@@ -11,19 +11,20 @@
  * process is killed like bash).
  *
  * The child `import()`-s exec-prelude.mjs first for readFile/writeFile/glob/grep/
- * log/require (paths confined to the workspace root). Full Node via require()/
- * process/import() is available — same boundary as bash, no fake sandbox.
+ * log/require (helper paths resolve against the working directory — orthopedic
+ * guard, not a sandbox). Full Node via require()/process/import() is available —
+ * same boundary as bash, no fake sandbox.
  *
  * Parameters:
  *   code       — JS to run inline (top-level await and import() supported). Use this OR scriptFile.
- *   scriptFile — run a workspace .mjs/.js file with node (self-contained, no prelude). Use this OR code.
+ *   scriptFile — run a .mjs/.js file with node (self-contained, no prelude). Use this OR code.
  *   nodeArgs   — (scriptFile) extra node flags before the script (e.g. --test, --check); eval-like flags rejected
- *   workdir    — run in this sub-directory (confined to the workspace)
+ *   workdir    — run in this sub-directory (no directory restriction)
  *   filter     — return only output lines matching this regex (case-insensitive)
  *   timeoutMs  — timeout (default 30s, max 60s)
  */
 import { spawn } from "node:child_process"
-import { dirname, resolve, relative, isAbsolute, sep } from "node:path"
+import { dirname, resolve } from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
 import { DESC } from "./shared.mjs"
 
@@ -34,20 +35,12 @@ const DEFAULT_TIMEOUT = 30_000
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const PRELUDE_URL = pathToFileURL(resolve(__dirname, "exec-prelude.mjs")).href
 
-/** True when `abs` is inside `root` (handles `..` and cross-drive, which
- *  relative() returns as an absolute path on Windows). */
-function isInside(root, abs) {
-  const rel = relative(root, abs)
-  if (isAbsolute(rel)) return false
-  return rel !== ".." && !rel.startsWith(".." + sep)
-}
-
-/** Resolve workdir relative to cwd, asserting it stays within the workspace. */
+/** Resolve workdir relative to cwd — no boundary assertion
+ *  (§10.1 2026-09-02: workspace confinement removed; the child node process is
+ *  not directory-limited — same boundary as bash). */
 function resolveBaseDir(cwd, workdir) {
   if (!workdir || typeof workdir !== "string") return cwd
-  const abs = resolve(cwd, workdir)
-  if (!isInside(cwd, abs)) throw new Error(`workdir escapes the workspace: ${workdir}`)
-  return abs
+  return resolve(cwd, workdir)
 }
 
 /** Keep only output lines matching a regex (execute filter, case-insensitive). */
@@ -143,7 +136,7 @@ export const executeTool = {
       },
       scriptFile: {
         type: "string",
-        description: "Run a workspace .mjs/.js file with node (self-contained, no prelude). Path relative to workdir, confined to the workspace. Use this OR code. For `node <script>` / `node --test <file>` / `node --check <file>`.",
+        description: "Run a .mjs/.js file with node (self-contained, no prelude). Path relative to workdir — no directory restriction. Use this OR code. For `node <script>` / `node --test <file>` / `node --check <file>`.",
       },
       nodeArgs: {
         type: "array",
@@ -152,7 +145,7 @@ export const executeTool = {
       },
       workdir: {
         type: "string",
-        description: "Run in this directory (relative to cwd, confined to the workspace; default cwd)",
+        description: "Run in this directory (relative to cwd — no directory restriction; default cwd)",
       },
       filter: {
         type: "string",
@@ -180,10 +173,9 @@ export const executeTool = {
     let childArgs
     if (args.scriptFile) {
       if (args.code?.trim()) return "Error: pass code OR scriptFile, not both"
-      // scriptFile mode: run a workspace .mjs/.js file with node [nodeArgs...]. Self-contained —
-      // no prelude (a real node process imports what it needs). Confined to the workspace.
+      // scriptFile mode: run a .mjs/.js file with node [nodeArgs...]. Self-contained —
+      // no prelude (a real node process imports what it needs). No directory restriction.
       const scriptAbs = resolve(baseDir, args.scriptFile)
-      if (!isInside(ctx.cwd, scriptAbs)) return `Error: scriptFile escapes the workspace: ${args.scriptFile}`
       let nodeArgs
       try { nodeArgs = validateNodeArgs(args.nodeArgs) }
       catch (e) { return `Error: ${e.message}` }

package/src/tools/file.mjs

@@ -13,13 +13,10 @@ import {
   findCandidates,
   FFFD_WARNING,
 } from "./shared.mjs";
+import { applyEditBatch } from "./edit-batch.mjs";
 import { specForModel } from "../config.mjs";
 import { createHash } from "node:crypto";
-import { mkdir } from "node:fs/promises";
-import { readFile } from "node:fs/promises";
-import { stat } from "node:fs/promises";
-import { writeFile } from "node:fs/promises";
-import { unlink } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile, unlink } from "node:fs/promises";
 import { join, relative, dirname } from "node:path";
 
 const MAX_FILE_READ_BYTES = 10_000_000
@@ -54,8 +51,9 @@ export function clearLastWrite(abs) { lastWrites.delete(abs) }
  *  模型拿到的不只是"inserted at L395"，而是"L395 这行是什么内容"——下次再操作时
  *  能自检"我的行号 vs 实际内容"是否匹配，匹配不上 = 行号漂了，先 read——
  *  死循环就断了（根因：模型对行号锚点的"新鲜度"没有感知——数字本身不携带语义）。
- *  write 全文重写跳过（无行号锚点——模型刚写的知道内容）。 */
-async function appendWriteContext(abs, writeLine, baseResult) {
+ *  write 全文重写跳过（无行号锚点——模型刚写的知道内容）。
+ *  edit-batch.mjs（数组形态）复用——导出仅供内部模块，非公共 API。 */
+export async function appendWriteContext(abs, writeLine, baseResult) {
   const content = normalizeEOL(await readFile(abs, "utf8"))
   const lines = content.split("\n")
   const start = Math.max(1, writeLine - 3)
@@ -77,7 +75,7 @@ export const readTool = {
       path: { type: "string", description: "File path (relative to cwd or absolute)" },
       offset: { type: "number", description: "1-based line number to start from" },
       limit: { type: "number", description: `Max lines to return (default ${MAX_READ_LINES})` },
-      allowExternal: { type: "boolean", description: "Allow reading files outside the working directory. Only set true when the user explicitly provided an external path — never use this to explore beyond cwd on your own." },
+      allowExternal: { type: "boolean", description: "No-op retained for API compatibility — path resolution no longer asserts a working-directory boundary (all paths resolve relative to cwd)." },
       hashes: { type: "boolean", description: "Include SHA256 line hashes for hash-based editing (default false). Use when you plan to edit the file with hashline_edit." },
     },
     required: ["path"],
@@ -222,7 +220,7 @@ export const editTool = {
       replace_all: { type: "boolean", description: "Replace all occurrences (default false)" },
       edits: {
         type: "array",
-        description: "2026-08-31 工具顺手度：一次多文件原子替换——任一失败全不写（先全量检查所有替换可执行）。与 path/old_string/new_string 互斥。",
+        description: "Batch form — multiple edits in ONE call, atomic (any failure writes nothing; same-file entries apply serially, each based on the previous result). Use it for multiple changes to the same file AND for independent changes across multiple files — prefer one batched call over N single edits. Mutually exclusive with path/old_string/new_string.",
         items: {
           type: "object",
           properties: {
@@ -244,58 +242,22 @@ export const editTool = {
   },
   async execute(args, ctx) {
     // 2026-08-31 工具顺手度（用户批准）：数组形态——一次多文件原子替换
-    if (args.edits) {
-      if (!Array.isArray(args.edits) || args.edits.length === 0) {
-        throw new Error("edits must be a non-empty array of {path, old_string, new_string}")
-      }
-      if (args.path || args.old_string !== undefined || args.new_string !== undefined) {
-        throw new Error("edits array is mutually exclusive with path/old_string/new_string")
-      }
-      // 原子：先全量 read+match 检查（所有文件都能替换）——任一失败全不写
-      const prepared = []
-      for (const e of args.edits) {
-        if (!e.path) throw new Error("each edit must have a path")
-        if (!e.old_string) throw new Error(`edit for ${e.path}: old_string must not be empty`)
-        const abs = resolveInCwd(ctx, e.path)
-        const raw = await readFile(abs, "utf8")
-        const content = normalizeEOL(raw)
-        const occurrences = content.split(e.old_string).length - 1
-        if (occurrences === 0) {
-          throw new Error(
-            `edit aborted (atomic — no files written): old_string not found in ${e.path}\n` +
-            `  searched: "${e.old_string.slice(0, 100).split("\n")[0]}${e.old_string.length > 100 ? "…" : ""}"`
-          )
-        }
-        if (occurrences > 1 && !e.replace_all) {
-          throw new Error(
-            `edit aborted (atomic — no files written): old_string matches ${occurrences} times in ${e.path}; ` +
-            `provide more context or set replace_all`
-          )
-        }
-        const updated = e.replace_all
-          ? content.split(e.old_string).join(e.new_string)
-          : content.replace(e.old_string, () => e.new_string)
-        const matchIdx = content.indexOf(e.old_string)
-        const editStartLine = matchIdx >= 0 ? content.slice(0, matchIdx).split("\n").length : 1
-        const lineShift = e.new_string.split("\n").length - e.old_string.split("\n").length
-        prepared.push({ abs, path: e.path, raw, updated, editStartLine, lineShift, occurrences: e.replace_all ? occurrences : 1 })
-      }
-      // 全部检查通过——逐个写
-      const results = []
-      for (const p of prepared) {
-        await writeFile(p.abs, joinWithEol(normalizeEOL(p.updated).split("\n"), p.raw), "utf8")
-        recordWrite(p.abs, { type: "edit", startLine: p.editStartLine, shift: p.lineShift })
-        const withCtx = await appendWriteContext(p.abs, p.editStartLine, `Edited ${p.path}: replaced ${p.occurrences} occurrence(s)`)
-        results.push(withCtx)
-      }
-      return results.join("\n")
-    }
+    // （应用逻辑在 edit-batch.mjs——2026-09-01 拆出，500 行硬限，先例 git-ext.mjs）
+    if (args.edits) return applyEditBatch(args, ctx)
 
     // 单文件（现状路径）
     const abs = resolveInCwd(ctx, args.path)
     if (!args.old_string) {
       throw new Error("old_string must not be empty (empty string matches everywhere and would corrupt the file)")
     }
+    // #5（2026-09-01 交付评审尾巴）：new_string 非字符串（含 undefined）在写盘前拒绝——
+    // 原缺陷：replace 回调返回 undefined 被字符串化成 "undefined" 写入盘，随后
+    // args.new_string.split 才 TypeError——文件已损坏 + 错误信息不知所云。
+    if (typeof args.new_string !== "string") {
+      throw new Error(
+        `new_string must be a string${args.new_string === undefined ? " (missing)" : ` (got ${typeof args.new_string})`} — nothing written`,
+      )
+    }
     const raw = await readFile(abs, "utf8")
     const content = normalizeEOL(raw)
     const occurrences = content.split(args.old_string).length - 1

package/src/tools/file_ops.md

@@ -11,6 +11,6 @@ Parameters:
 - dest (required): destination path
 
 Notes:
-- Paths are confined to the working directory (same safety as write/edit) — bash has NO directory confinement.
+- Paths resolve relative to cwd — no directory restriction (same boundary as bash; the approval gate is the guard).
 - `dest` is overwritten if it already exists. `copy` is recursive for directories.
 - To create a directory, use `write` (creates parent dirs) or `bash mkdir`.

package/src/tools/git-checkpoint.mjs

@@ -0,0 +1,143 @@
+/**
+ * git-checkpoint.mjs — git 工具 checkpoint action 子系统（CHECKPOINT.md F2/F6）。
+ * git.mjs 的 checkpoint case 委托到这里：list/create/rewind/cat/versions + F6 懒清理 +
+ * F2/D7 提示行 + 文件树格式化。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
+ */
+import { runGit } from "./shared.mjs"
+import { escapeXml } from "../agent/helpers.mjs"
+import {
+  createCheckpoint,
+  listCheckpoints,
+  rewind,
+  listFileVersions,
+  catFile,
+  isGitRepo,
+  deleteCheckpointsForCwd,
+} from "../git/checkpoint.mjs"
+
+/** F6 lazy fallback (CHECKPOINT.md D3): an EXTERNAL git commit (via bash / IDE — not the git
+ *  tool) leaves this cwd's checkpoints as pre-commit state. Compare HEAD commit time
+ *  (epoch SECONDS from %ct) against the newest snapshot's meta.time (ms): `%ct × 1000` aligns
+ *  both to ms. HEAD newer → every snapshot predates the commit → clear all. All-or-nothing:
+ *  any snapshot NEWER than HEAD (e.g. a manual create after the external commit) skips the
+ *  whole clear. Best-effort — never blocks the checkpoint op. */
+export async function lazyClearIfCommitted(cwd) {
+  try {
+    const cps = await listCheckpoints(cwd)
+    if (cps.length === 0) return
+    const headSec = runGit(cwd, ["log", "-1", "--format=%ct"])
+    const headMs = Number.parseInt(headSec, 10) * 1000
+    if (!Number.isFinite(headMs) || headMs <= 0) return
+    const newest = cps[0] // listCheckpoints returns newest → oldest
+    if (headMs > newest.time) await deleteCheckpointsForCwd(cwd)
+  } catch {
+    // best-effort (NF7 philosophy) — a lazy-clear failure must not break list/create
+  }
+}
+
+/** checkpoint case 主入口（git 工具 checkpoint action 的全部子动作）。 */
+export async function executeCheckpointAction(args, ctx) {
+  const { checkpointAction: sub, checkpointId: id, path } = args
+  if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
+
+  if (!sub) return "checkpoint: missing checkpointAction — use: list | create | rewind | cat | versions"
+
+  // F6 lazy fallback (list/create entry): an EXTERNAL git commit (HEAD time newer
+  // than the newest snapshot) means every snapshot predates a safety baseline —
+  // clear them. All-or-nothing: if any snapshot is newer than HEAD, skip entirely.
+  if (sub === "list" || sub === "create") await lazyClearIfCommitted(ctx.cwd)
+
+  if (sub === "create") {
+    const cp = await createCheckpoint(ctx.cwd)
+    return `Checkpoint ${cp.id} created (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked)`
+  }
+  if (sub === "versions") {
+    if (!path) throw new Error("path is required for versions — the file whose history you want")
+    const versions = await listFileVersions(ctx.cwd, path)
+    if (versions.length === 0) return `No snapshot copies of "${path}" found (it was never part of an auto/protection snapshot).`
+    return (
+      `Historical versions of "${path}" (${versions.length}, newest first):\n` +
+      versions.map((v) =>
+        `  ${v.snapshotId}  ${new Date(v.time).toISOString()}  ${v.size}B  sha:${v.sha}  (${v.source})` +
+        (v.sha === versions[versions.indexOf(v) - 1]?.sha ? "  ← same content as previous" : "")
+      ).join("\n") +
+      `\nRestore a version: checkpointAction=rewind checkpointId=<snapshotId> path="${path}"`
+    )
+  }
+  if (sub === "rewind") {
+    if (!id) throw new Error("checkpointId is required for rewind — use checkpointAction=list to see snapshot ids")
+    if (!path) throw new Error("path is required for rewind — full restore is disabled (as dangerous as `git checkout -- .`). Restore files individually. Use checkpointAction=versions path=<file> to list a file's historical versions.")
+    const s = await rewind(ctx.cwd, id, { path })
+    return `Restored "${path}" (${s.type}) from checkpoint ${id}.\n(The pre-restore state was snapshotted first — you can restore again to go back.)`
+  }
+  if (sub === "cat") {
+    if (!id) throw new Error("checkpointId is required for cat — use checkpointAction=list to see snapshot ids")
+    if (!path) throw new Error("path is required for cat — specify which file to read")
+    return await catFile(ctx.cwd, id, path)
+  }
+  if (sub === "list") {
+    const cps = await listCheckpoints(ctx.cwd)
+    if (cps.length === 0) return "(no checkpoints yet)"
+
+    // Specific id: show the file tree within that snapshot
+    if (id) {
+      const cp = cps.find((c) => c.id === id)
+      if (!cp) throw new Error(`checkpoint ${id} not found`)
+      return formatFileTree(cp)
+    }
+
+    // Overview: list of all snapshots (file names are XML-escaped: they are
+    // untrusted input that flows back into the model's context). F2/D7: fixed
+    // hint line at the tail — the recovery entry for a snapshot after an accident.
+    return cps.map((c) => {
+      const parts = [`${c.id}  ${new Date(c.time).toISOString()}`]
+      if (c.tracked.length) parts.push(`${c.tracked.length} tracked: ${c.tracked.map(escapeXml).join(", ")}`)
+      if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.map(escapeXml).join(", ")}`)
+      return parts.join("  ")
+    }).join("\n") + "\n(意外丢弃改动？checkpointAction=rewind 可恢复操作前状态)"
+  }
+  throw new Error(`Unknown checkpoint action: ${sub}. Use: list | create | rewind | cat | versions`)
+}
+
+/** Format a checkpoint's file list as a directory tree (directories first, indented display) */
+function formatFileTree(cp) {
+  // File names are XML-escaped: untrusted input that flows back into the model's context
+  const all = [
+    ...(cp.tracked ?? []).map((f) => ({ path: escapeXml(f), type: "" })),
+    ...(cp.untracked ?? []).map((f) => ({ path: escapeXml(f), type: " (untracked)" })),
+  ]
+  if (all.length === 0) return "(empty checkpoint)"
+
+  all.sort((a, b) => a.path.localeCompare(b.path))
+
+  const tree = new Map()
+  for (const { path, type } of all) {
+    const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "."
+    if (!tree.has(dir)) tree.set(dir, [])
+    tree.get(dir).push({ name: path.slice(dir === "." ? 0 : dir.length + 1), type })
+  }
+
+  const lines = []
+  const dirs = [...tree.keys()].sort()
+  for (const dir of dirs) {
+    if (dir !== "." && !lines.includes(dir + "/")) {
+      const parts = dir.split("/")
+      for (let i = 1; i <= parts.length; i++) {
+        const prefix = parts.slice(0, i).join("/") + "/"
+        if (!lines.includes(prefix)) lines.push(prefix)
+      }
+    }
+  }
+  for (const dir of dirs) {
+    if (dir !== ".") {
+      for (const { name, type } of tree.get(dir)) {
+        lines.push(`  ${dir}/${name}${type}`)
+      }
+    }
+  }
+  for (const { name, type } of tree.get(".") ?? []) {
+    lines.push(name + type)
+  }
+
+  return lines.join("\n")
+}