thincoder 0.8.2 → 0.8.4

package/src/session.mjs

@@ -1,9 +1,9 @@
 /**
- * session.mjs — 会话持久化
- * 每个项目（按 cwd 哈希）最多保留 5 轮会话，按最后使用时间轮转。
- * 两种恢复需求分开存：agent 恢复（history）要上下文连续，用户恢复（display）要所见即所得。
+ * session.mjs — session persistence
+ * Each project (keyed by cwd hash) keeps up to 5 session slots, rotated by last-access time.
+ * Two recovery needs stored separately: agent recovery (history) needs context continuity, user recovery (display) needs WYSIWYG.
  *
- * 文件布局：{hash}.json（当前）、{hash}.json.1~5（槽位）、{hash}.json.manifest（槽位元数据）
+ * File layout: {hash}.json (current), {hash}.json.1~5 (slots), {hash}.json.manifest (slot metadata)
  */
 
 import { createHash } from "node:crypto"
@@ -12,18 +12,20 @@ import { join, dirname } from "node:path"
 import { configDir } from "./config.mjs"
 
 const MAX_SLOTS = 5
+const CWD_HASH_LEN = 12
 
+/** Derive session file path from cwd hash */
 export function sessionPath(cwd) {
-  const hash = createHash("sha1").update(cwd).digest("hex").slice(0, 12)
+  const hash = createHash("sha1").update(cwd).digest("hex").slice(0, CWD_HASH_LEN)
   return join(configDir, "sessions", `${hash}.json`)
 }
 
 function slotPath(cwd, n) { return sessionPath(cwd) + "." + n }
 function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" }
 
-/** 原子写：先写临时文件再 rename 替换，防写入中途崩溃留下截断的 JSON 丢整个会话。
- *  rename 在 POSIX 上原子；Windows 上目标已存在时 Node 24 用 MoveFileExW+REPLACE_EXISTING 也能原子替换。
- *  某些旧 Windows 文件系统可能抛 EPERM，重试一次。 */
+/** Atomic write: write to temp file then rename to replace, preventing truncated JSON from mid-write crash.
+ *  rename is atomic on POSIX; on Windows with existing target, Node 24 uses MoveFileExW+REPLACE_EXISTING for atomic replace.
+ *  Some older Windows filesystems may throw EPERM — retry once. */
 function writeSessionFile(p, data) {
   mkdirSync(dirname(p), { recursive: true })
   const tmp = `${p}.tmp`
@@ -31,13 +33,19 @@ function writeSessionFile(p, data) {
   try {
     renameSync(tmp, p)
   } catch {
-    // Windows EPERM 兜底：删目标后重试（极罕见，仅旧 NTFS/网络盘）
+    // Windows: rename may fail due to antivirus lock / network drive contention — delete target and retry
     try { unlinkSync(p) } catch {}
-    renameSync(tmp, p)
+    try {
+      renameSync(tmp, p)
+      // rename succeeded: clean up temp file
+      try { unlinkSync(tmp) } catch {}
+    } catch {
+      // rename still failed: keep tmp as fallback data (next read prefers main file; if missing, tmp is at least there)
+    }
   }
 }
 
-// ========== 槽位管理 ==========
+// ========== slot management ==========
 
 function loadManifest(cwd) {
   try {
@@ -51,14 +59,14 @@ function saveManifest(cwd, m) {
   writeSessionFile(manifestPath(cwd), m)
 }
 
-/** 归档当前会话到空闲槽位——满了踢最老；exclude 指定一个不许被踢的槽位（switchToSlot 的目标槽） */
+/** Archive current session to a free slot — evict oldest if full; exclude specifies a slot that must not be evicted (switchToSlot target) */
 export function archiveCurrent(cwd, { exclude } = {}) {
   const src = sessionPath(cwd)
   if (!existsSync(src)) return
   const m = loadManifest(cwd)
 
   let slot
-  // 只计数字 key 的槽位，排除 _currentName 等遗留非数字 key
+  // Only count numeric-keyed slots, exclude legacy non-numeric keys like _currentName
   const entries = Object.entries(m.slots).filter(([n]) => /^\d+$/.test(n))
   if (entries.length < MAX_SLOTS) {
     slot = 1
@@ -69,12 +77,12 @@ export function archiveCurrent(cwd, { exclude } = {}) {
   }
 
   const dst = slotPath(cwd, slot)
-  // 复制（rename 会丢当前）；走原子写，防中途崩溃留下截断的 JSON 丢归档
+  // Copy (rename would lose current); use atomic write to prevent truncated JSON in archive from mid-crash
   let data
   try {
     data = JSON.parse(readFileSync(src, "utf8"))
   } catch {
-    // 会话文件损坏，放弃归档，下次保存会覆盖
+    // Session file corrupted, abandon archive; next save will overwrite
     return
   }
   writeSessionFile(dst, data)
@@ -84,7 +92,7 @@ export function archiveCurrent(cwd, { exclude } = {}) {
   return slot
 }
 
-/** 列出所有归档槽位，最新在前 */
+/** List all archive slots, newest first */
 export function listSlots(cwd) {
   const m = loadManifest(cwd)
   return Object.entries(m.slots)
@@ -92,29 +100,29 @@ export function listSlots(cwd) {
     .sort((a, b) => b.timestamp - a.timestamp)
 }
 
-/** 切换到指定槽位：归档当前 → 槽位文件复制到当前 → 返回恢复数据（失败返回 null） */
+/** Switch to a specific slot: archive current → copy slot file to current → return recovered data (null on failure) */
 export function switchToSlot(cwd, slot) {
   const m = loadManifest(cwd)
   if (!m.slots[slot]) return null
 
-  // 归档当前（内部写 manifest；之后我们的 m 已过期，需重读）
-  // 满槽时排除目标槽：否则最老槽=目标槽，归档会把目标覆盖掉再复制回来，目标会话永久丢失
+  // Archive current (internally writes manifest; our `m` is stale after, must reload)
+  // When full, exclude target slot: otherwise oldest=target, archive would overwrite target then copy back, permanently losing the target session
   archiveCurrent(cwd, { exclude: slot })
 
-  // 槽位文件 → 当前（copy+unlink，不用 rename：Windows rename 目标已存在会抛 EPERM）
+  // Slot file → current (copy+unlink, not rename: Windows rename on existing target throws EPERM)
   const src = slotPath(cwd, slot)
   const dst = sessionPath(cwd)
   if (!existsSync(src)) return null
   try {
-    try { unlinkSync(dst) } catch { /* 不存在就算了 */ }
+    try { unlinkSync(dst) } catch { /* doesn't exist, that's fine */ }
     copyFileSync(src, dst)
     unlinkSync(src)
   } catch {
-    // 文件操作失败（磁盘满/权限不足/锁文件），放弃切换
+    // File operations failed (disk full / permissions / lock), abandon switch
     return null
   }
 
-  // 重读 manifest（archiveCurrent 改了它）
+  // Reload manifest (archiveCurrent modified it)
   const m2 = loadManifest(cwd)
   delete m2.slots[slot]
   saveManifest(cwd, m2)
@@ -122,7 +130,7 @@ export function switchToSlot(cwd, slot) {
   return loadSession(cwd)
 }
 
-// ========== 旧版 transient 前缀清理 ==========
+// ========== legacy transient prefix cleanup ==========
 
 const LEGACY_TRANSIENT_PREFIXES = [
   "[System reminder: working directory snapshot:",
@@ -137,8 +145,9 @@ function isLegacyTransient(m) {
   )
 }
 
-// ========== 核心读写 ==========
+// ========== core read/write ==========
 
+/** Save agent state and display lines to the session file (atomic write) */
 export function saveSession(agent, display) {
   const history = agent.history.filter((m) => !m.transient && !isLegacyTransient(m))
   const data = {
@@ -158,22 +167,45 @@ export function saveSession(agent, display) {
   writeSessionFile(sessionPath(agent.cwd), data)
 }
 
+/** Load session data from disk; returns null if missing, corrupted, or version mismatch */
 export function loadSession(cwd) {
-  try {
-    const p = sessionPath(cwd)
-    if (!existsSync(p)) return null
-    const data = JSON.parse(readFileSync(p, "utf8"))
-    if (data?.version !== 1 && data?.version !== 2) return null
-    if (!Array.isArray(data.history)) return null
-    if (data.cwd && data.cwd.toLowerCase() !== cwd.toLowerCase()) return null
-    data.history = data.history.filter((m) => !isLegacyTransient(m))
-    data.display = Array.isArray(data.display)
-      ? data.display.filter((l) => l && typeof l.text === "string").map((l) => ({ text: l.text, color: l.color }))
-      : []
-    return data
-  } catch { return null }
+  const tryLoad = (p) => {
+    try {
+      if (!existsSync(p)) return null
+      const data = JSON.parse(readFileSync(p, "utf8"))
+      if (data?.version !== 1 && data?.version !== 2) return null
+      if (!Array.isArray(data.history)) return null
+      if (data.cwd && data.cwd.toLowerCase() !== cwd.toLowerCase()) return null
+      data.history = data.history.filter((m) => !isLegacyTransient(m))
+      data.display = Array.isArray(data.display)
+        ? data.display.filter((l) => l && typeof l.text === "string").map((l) => ({ text: l.text, color: l.color }))
+        : []
+      data._recovered = false
+      return data
+    } catch (e) {
+      return { _error: e }
+    }
+  }
+  const p = sessionPath(cwd)
+  let result = tryLoad(p)
+  if (result?._error) {
+    // Main file corrupted — try the .tmp fallback from a failed atomic write
+    console.error(`[session] failed to load ${p}: ${result._error.message}. Trying .tmp fallback...`)
+    const tmpResult = tryLoad(`${p}.tmp`)
+    if (tmpResult && !tmpResult._error) {
+      console.error(`[session] recovered from .tmp fallback`)
+      result = tmpResult
+      result._recovered = true
+    } else {
+      console.error(`[session] .tmp fallback also failed — session lost. Backing up corrupted file as .corrupted.`)
+      try { renameSync(p, `${p}.corrupted`) } catch {}
+      return null
+    }
+  }
+  return result && !result._error ? result : null
 }
 
+/** Apply loaded session data onto an agent object; returns true if provider was switched */
 export function applySession(agent, data) {
   agent.history = data.history
   agent.tasks = data.tasks ?? []
@@ -182,9 +214,7 @@ export function applySession(agent, data) {
   agent.goal = data.goal ?? null
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
-  // 重置轮次计数器：切换会话后不应继承旧会话的停滞/压缩状态
-  agent._turnsSinceTaskUpdate = 0
-  agent._turnsInPlanMode = 0
+  // Reset stall/compaction state on session switch
   agent._compressFailures = 0
   agent._verifyRetries = 0
   agent._verifyPassed = false
@@ -199,12 +229,13 @@ export function applySession(agent, data) {
   return false
 }
 
+/** Archive current session and reset the session file to empty state */
 export function clearSession(cwd) {
   try {
     archiveCurrent(cwd)
     const p = sessionPath(cwd)
     writeSessionFile(p, { version: 2, cwd, history: [], tasks: [], display: [], goal: null, autoApprove: false, pendingReminders: [], sessionStart: null })
   } catch {
-    // 清不掉就算了，下次保存会覆盖
+    // Can't clear, oh well — next save will overwrite
   }
 }

package/src/skills.mjs

@@ -1,17 +1,17 @@
 /**
- * skills.mjs — 技能系统
- * 从 .thincoder/skills/ 目录发现 .md 技能文件，
- * 注入到 system prompt 供 agent 按需加载。
- * 用 skill 工具激活指定技能，内容以 <skill-loaded> 包裹写入对话历史。
+ * skills.mjs — skill system
+ * Discovers .md skill files from .thincoder/skills/ directory,
+ * injects into system prompt for agent to load on demand.
+ * Use the skill tool to activate a specific skill; content is written into conversation history wrapped in <skill-loaded>.
  */
 
 import { readFile, readdir, stat } from "node:fs/promises"
 import { join } from "node:path"
 
 /**
- * 扫描 .thincoder/skills/ 目录，返回技能列表。
- * 每个技能：{ name, path, description } — name 取文件名（去扩展名）。
- * 目录不存在或无文件返回空数组。
+ * Scan .thincoder/skills/ directory, return skill list.
+ * Each skill: { name, path, description } — name is the filename (without extension).
+ * Returns empty array if directory is missing or empty.
  */
 export async function loadSkills(cwd) {
   const dir = join(cwd, ".thincoder", "skills")
@@ -23,13 +23,13 @@ export async function loadSkills(cwd) {
   }
   const skills = []
   for (const name of entries) {
-    if (!/^[a-zA-Z0-9_-]+\.md$/.test(name)) continue // 与 readSkill 的名字校验一致，防"列得出、读不了"
+    if (!/^[a-zA-Z0-9_-]+\.md$/.test(name)) continue // must match readSkill's name validation; prevents "listed but unreadable"
     const p = join(dir, name)
     try {
       const s = await stat(p)
       if (!s.isFile()) continue
-      // 提取描述（前 400 字符里第一段非空、非标题行）；文件带 frontmatter 时整块跳过，
-      // 否则会把 frontmatter 字段行（如 "name: x"）误当描述
+      // Extract description (first non-empty, non-heading line in first 400 chars);
+      // skip entire frontmatter block, otherwise frontmatter fields (e.g. "name: x") get mistaken for description
       const head = await readFile(p, "utf8")
       const body = head.slice(0, 400).split("\n")
       let desc = ""
@@ -45,16 +45,16 @@ export async function loadSkills(cwd) {
       }
       skills.push({ name: name.replace(/\.md$/, ""), path: p, description: desc || "(no description)" })
     } catch {
-      // 读失败跳过
+      // Read failure — skip
     }
   }
   return skills
 }
 
 /**
- * 生成技能列表文本，注入 system prompt。
- * 最多 3 个（占位少），超过则标 "... and N more"。
- * 以 DISREGARD 开头：清单刷新（技能增删）后旧清单自动作废，无需删历史（借鉴 kimi-code）。
+ * Generate skill listing text for system prompt injection.
+ * At most 3 (small footprint); overflow marked "... and N more".
+ * Prefixed with DISREGARD: when listing refreshes (skills added/removed), old listings are auto-invalidated without needing to delete history (inspired by kimi-code).
  */
 export function formatSkillListing(skills) {
   if (skills.length === 0) return ""
@@ -65,11 +65,11 @@ export function formatSkillListing(skills) {
 }
 
 /**
- * 读取指定技能文件的完整内容。
- * 返回文本，找不到返回 null。
+ * Read the full content of a specific skill file.
+ * Returns text, or null if not found.
  */
 export async function readSkill(cwd, name) {
-  // 安全检查：技能名只能是字母数字 + 连字符/下划线
+  // Safety check: skill name must be alphanumeric + hyphens/underscores only
   if (!/^[a-zA-Z0-9_-]+$/.test(name)) return null
   const p = join(cwd, ".thincoder", "skills", `${name}.md`)
   try {

package/src/tools/checkpoint.md

@@ -1,11 +1,15 @@
 List, create, and restore workspace snapshots (checkpoints). Git repositories only.
 
 Parameters:
-- action (required): "list" | "create" | "rewind"
-- id: snapshot id (required for rewind)
+- action (required): "list" | "create" | "rewind" | "cat"
+- id: snapshot id (required for rewind and cat; optional for list — when given, shows the file tree inside that snapshot)
+- path: for rewind — restore only this single file; for cat — read this file's content from the snapshot
 
 Notes:
 - A checkpoint is AUTO-CREATED before every user task. If uncommitted work was destroyed (by you, a git command, or a failed refactor), use action=list then action=rewind with the latest id to recover it
 - A checkpoint captures all uncommitted state: tracked-file changes (as a diff) plus copies of untracked files
 - Rewind first snapshots the current state, so rewinding is itself reversible
+- Rewind AUTO-RECOVERS: if git apply fails (corrupt patch), the pre-rewind state is restored — never lose data
 - Create one manually before risky bulk operations
+- list now shows which files changed (tracked + untracked); use path to recover individual files selectively
+- cat reads a file's content from a snapshot without touching the worktree — useful for inspecting before rewinding

package/src/tools/file.mjs

@@ -4,7 +4,8 @@ import {
   MAX_READ_LINES,
   gitDiffOne,
   autoSyntaxCheck,
-  resolveInCwd
+  resolveInCwd,
+  resolveExternal,
 } from "./shared.mjs";
 import { mkdir } from "node:fs/promises";
 import { readFile } from "node:fs/promises";
@@ -13,6 +14,9 @@ import { writeFile } from "node:fs/promises";
 import { unlink } from "node:fs/promises";
 import { join, relative, dirname } from "node:path";
 
+const MAX_FILE_READ_BYTES = 10_000_000
+const MAX_IMAGE_BYTES = 15_000_000
+
 export const readTool = {
   name: "read",
   description: DESC("read"),
@@ -22,15 +26,16 @@ 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." },
     },
     required: ["path"],
   },
   readonly: true,
   async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path)
-    // 大文件保护：先查大小，超 10MB 拒绝整文件读入（offset/limit 只影响返回切片，不影响缓冲）
+    const abs = args.allowExternal ? resolveExternal(ctx, args.path) : resolveInCwd(ctx, args.path)
+    // Large file guard: check size first, reject reading entire file if >10MB (offset/limit only affect the returned slice, not buffering)
     const st = await stat(abs).catch(() => null)
-    if (st && st.size > 10_000_000) throw new Error(`File too large (${Math.round(st.size / 1_000_000)}MB > 10MB limit). Use bash with head/tail or grep for targeted extraction.`)
+    if (st && st.size > MAX_FILE_READ_BYTES) throw new Error(`File too large (${Math.round(st.size / 1_000_000)}MB > 10MB limit). Use bash with head/tail or grep for targeted extraction.`)
     const content = await readFile(abs, "utf8")
     const lines = content.split("\n")
     const offset = Math.max(1, args.offset ?? 1)
@@ -57,15 +62,16 @@ export const readImageTool = {
     required: ["path"],
   },
   readonly: true,
-  /** 返回 JSON：{ text, images }，供 agent 层转为多模态 user 消息 */
+  multimodal: true, // returns JSON { text, images } — agent loop converts to multimodal user message
+  /** Returns JSON: { text, images }, for the agent layer to convert into multimodal user messages */
   async execute(args, ctx) {
     const abs = resolveInCwd(ctx, args.path)
     const ext = abs.slice(abs.lastIndexOf(".") + 1).toLowerCase()
     const mime = IMAGE_EXTENSIONS[ext]
     if (!mime) throw new Error(`Unsupported image format: .${ext}. Supported: ${Object.keys(IMAGE_EXTENSIONS).join(", ")}`)
-    // 先查大小再读入——防超大图片撑爆内存（20MB base64 ≈ 15MB 原始）
+    // Check size before reading — prevent huge images from blowing up memory (20MB base64 ≈ 15MB raw)
     const imgStat = await stat(abs).catch(() => null)
-    if (imgStat && imgStat.size > 15_000_000) throw new Error(`Image too large: ${Math.round(imgStat.size / 1_000_000)}MB (max 15MB)`)
+    if (imgStat && imgStat.size > MAX_IMAGE_BYTES) throw new Error(`Image too large: ${Math.round(imgStat.size / 1_000_000)}MB (max 15MB)`)
     const buf = await readFile(abs) // raw buffer, no encoding
     const b64 = buf.toString("base64")
     const bytes = buf.length
@@ -73,10 +79,10 @@ export const readImageTool = {
       text: `[read_image: ${args.path} (${mime}, ${bytes} bytes)]`,
       images: [{ type: "image_url", image_url: { url: `data:${mime};base64,${b64}` } }],
     })
-    // 粘贴产生的临时文件用完即删，不留垃圾
+    // Paste-created temp files: delete after use, no litter
     const basename = abs.includes("/") ? abs.slice(abs.lastIndexOf("/") + 1) : abs.slice(abs.lastIndexOf("\\") + 1)
     if (basename.startsWith(".thincoder-paste-")) {
-      try { await unlink(abs) } catch { /* 删不掉就算了 */ }
+      try { await unlink(abs) } catch { /* can't delete, so be it */ }
     }
     return result
   },
@@ -103,7 +109,7 @@ export const writeTool = {
     if (st?.isDirectory()) throw new Error(`Path is a directory: ${args.path}`)
     await writeFile(abs, args.content, "utf8")
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Wrote ${args.content.length} chars to ${args.path}${diff ? "\n" + diff : ""}${autoSyntaxCheck(abs)}`
+    return `Wrote ${args.content.length} chars to ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
   },
 }
 
@@ -131,7 +137,7 @@ export const editTool = {
     const content = await readFile(abs, "utf8")
     const occurrences = content.split(args.old_string).length - 1
     if (occurrences === 0) {
-      // 给出线索帮模型定位：首行预览 + 常见原因
+      // Give clues to help the model locate: first-line preview + common causes
       const preview = args.old_string.slice(0, 100).split("\n")[0]
       throw new Error(
         `old_string not found in ${args.path}\n` +
@@ -144,11 +150,11 @@ export const editTool = {
     }
     const updated = args.replace_all
       ? content.split(args.old_string).join(args.new_string)
-      // 函数式替换：避免 new_string 里的 $ 替换模式（匹配串/前后文引用）被展开
+      // Functional replacement: avoid $-substitution patterns in new_string (match string / backreference) being expanded
       : content.replace(args.old_string, () => args.new_string)
     await writeFile(abs, updated, "utf8")
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Edited ${args.path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}${autoSyntaxCheck(abs)}`
+    return `Edited ${args.path}: replaced ${args.replace_all ? occurrences : 1} occurrence(s)${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
   },
 }
 
@@ -199,7 +205,7 @@ export const insertAfterTool = {
     const updated = lines.join("\n")
     await writeFile(abs, updated, "utf8")
     const diff = gitDiffOne(ctx.cwd, abs)
-    return `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${autoSyntaxCheck(abs)}`
+    return `Inserted after line ${targetLine} in ${args.path}${diff ? "\n" + diff : ""}${await autoSyntaxCheck(abs)}`
   },
 }
 

package/src/tools/git.mjs

@@ -20,7 +20,7 @@ export const gitDiffTool = {
   readonly: true,
   execute(args, ctx) {
     const ref = args.ref ?? "HEAD"
-    // ref 由模型提供且位于 "--" 之前：校验字符集，防 "--output=..." 之类被 git 当成选项
+    // ref supplied by model and placed before "--": validate charset, prevent "--output=..." etc. from being treated as git options
     if (!/^[A-Za-z0-9._\/~^][A-Za-z0-9._\/~^-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
     const flags = args.staged ? ["--staged"] : []
     const paths = args.path ? [args.path] : []
@@ -49,14 +49,14 @@ export const gitStatusTool = {
     const conflicts = []
     for (const line of porcelain.split("\n")) {
       if (!line) continue
-      // porcelain: XY path — 2 状态字符 + 空格 + 文件路径（部分环境只 1 空格）
-      // 去掉可能的 CR（execFileSync 在某些 Windows git 下会残留 \r 在行末但不在换行符中）
+      // porcelain: XY path — 2 status chars + space + file path (some environments have only 1 space)
+      // Strip possible CR (execFileSync on some Windows git leaves \r at end of line but not in newline)
       const clean = line.replace(/\r/g, "")
-      // 尝试匹配 "XY path" 或 "XY  path"（可变间距）
+      // Try matching "XY path" or "XY  path" (variable spacing)
       const m = clean.match(/^(..?)\s+(.+)$/)
       if (!m) continue
       const [, status, rawFile] = m
-      // 重命名条目 porcelain 输出为 "R  old -> new"，拆开明确展示而非当成一个字面文件名
+      // Rename entries in porcelain output are "R  old -> new", split for clarity instead of treating as a literal filename
       const file = status.includes("R") && rawFile.includes(" -> ") ? rawFile.replace(" -> ", " → ") : rawFile
       const idx = status[0] ?? " "
       const wt = status[1] ?? " "
@@ -128,7 +128,7 @@ export const questionTool = {
   },
 }
 
-/** 执行 git 命令；非 git 仓库 / git 不可用时返回空字符串 */
+/** Execute a git command; returns empty string when not a git repo / git unavailable */
 
 // ---------------------------------------------------------------- checkpoint
 
@@ -138,8 +138,9 @@ export const checkpointTool = {
   parameters: {
     type: "object",
     properties: {
-      action: { type: "string", enum: ["list", "create", "rewind"], description: "list snapshots / create one now / restore a snapshot by id" },
-      id: { type: "string", description: "Snapshot id (required for rewind)" },
+      action: { type: "string", enum: ["list", "create", "rewind", "cat"], description: "list snapshots / create one now / restore a snapshot by id / read a file's content from a snapshot" },
+      id: { type: "string", description: "Snapshot id (required for rewind and cat; optional for list — shows file tree of that snapshot)" },
+      path: { type: "string", description: "Restore only this single file from the checkpoint (tracked or untracked). Other files are left untouched." },
     },
     required: ["action"],
   },
@@ -149,18 +150,88 @@ export const checkpointTool = {
     if (!isGitRepo(ctx.cwd)) throw new Error("Not a git repository — checkpoints unavailable")
     if (args.action === "create") {
       const cp = await createCheckpoint(ctx.cwd)
-      return `Checkpoint ${cp.id} created (${cp.files} file(s) captured)`
+      return `Checkpoint ${cp.id} created (${cp.files} file(s): ${cp.tracked.length} tracked, ${cp.untracked.length} untracked)`
     }
     if (args.action === "rewind") {
       if (!args.id) throw new Error("id is required for rewind — use action=list to see snapshot ids")
-      const s = await rewind(ctx.cwd, args.id)
-      return `Rewound to checkpoint ${args.id}: patch ${s.patchApplied ? "applied" : "(empty)"}, ${s.restored} untracked file(s) restored, ${s.deleted} file(s) deleted.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+      const s = await rewind(ctx.cwd, args.id, { path: args.path })
+      if (args.path) {
+        return `Restored "${args.path}" (${s.type}) from checkpoint ${args.id}.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+      }
+      return `Rewound to checkpoint ${args.id}: patch ${s.patchApplied ? "applied" : "(empty)"}, ${s.restored ?? 0} untracked file(s) restored, ${s.deleted ?? 0} file(s) deleted.\n(The pre-rewind state was snapshotted first — you can rewind again to go back.)`
+    }
+    if (args.action === "cat") {
+      if (!args.id) throw new Error("id is required for cat — use action=list to see snapshot ids")
+      if (!args.path) throw new Error("path is required for cat — specify which file to read")
+      const { catFile } = await import("../git/checkpoint.mjs")
+      return await catFile(ctx.cwd, args.id, args.path)
     }
     if (args.action === "list") {
       const cps = await listCheckpoints(ctx.cwd)
       if (cps.length === 0) return "(no checkpoints yet — one is auto-created before each user task)"
-      return cps.map((c) => `${c.id}  ${new Date(c.time).toISOString()}  ${c.untracked} untracked file(s)`).join("\n")
+
+      // Specific id: show the file tree within that snapshot
+      if (args.id) {
+        const cp = cps.find((c) => c.id === args.id)
+        if (!cp) throw new Error(`checkpoint ${args.id} not found`)
+        return formatFileTree(cp)
+      }
+
+      // Overview: list of all snapshots
+      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.join(", ")}`)
+        if (c.untracked.length) parts.push(`${c.untracked.length} untracked: ${c.untracked.join(", ")}`)
+        return parts.join("  ")
+      }).join("\n")
     }
     throw new Error(`Unknown action: ${args.action}`)
   },
 }
+
+/** Format a checkpoint's file list as a directory tree (directories first, indented display) */
+function formatFileTree(cp) {
+  const all = [
+    ...(cp.tracked ?? []).map((f) => ({ path: f, type: "" })),
+    ...(cp.untracked ?? []).map((f) => ({ path: f, type: " (untracked)" })),
+  ]
+  if (all.length === 0) return "(empty checkpoint)"
+
+  // Sort by path (directories group naturally)
+  all.sort((a, b) => a.path.localeCompare(b.path))
+
+  // Build directory → file list map
+  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 })
+  }
+
+  // Output sorted by directory
+  const lines = []
+  const dirs = [...tree.keys()].sort()
+  for (const dir of dirs) {
+    if (dir !== "." && !lines.includes(dir + "/")) {
+      // Parent directory before child directory
+      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)
+      }
+    }
+  }
+  // Ensure directories precede files
+  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")
+}

package/src/tools/index.mjs

@@ -1,4 +1,4 @@
-// tools/index.mjs — 后端兼容重导出
+// tools/index.mjs — backend-compatible re-export
 export { toOpenAISchema } from "./shared.mjs";
 
 import { readTool, writeTool, editTool, insertAfterTool, readImageTool } from "./file.mjs";

package/src/tools/ls.md

@@ -5,5 +5,5 @@ Parameters:
 
 Notes:
 - Shows first 500 entries
-- Directories are prefixed with `/` and listed before files
+- Directories are suffixed with `/` and listed before files
 - Use this for a quick overview; use glob when you have a specific file pattern in mind