@konnga/dsh-hud 0.7.1 → 0.9.0

package/lib/index.js

@@ -17,6 +17,9 @@
  *   - `diff { cwd, path, origPath? }` → 一个改动文件的**两侧** unified diff
  *     （工作区 / 已暂存），已解析成带行号的 rows；未跟踪文件与 `--no-index` 对齐，
  *     文本按行截断、行数有上限，二进制只报 `binary`。
+ *   - `image { cwd, path, origPath?, side?, sha? }` → 图片改动**两侧**的字节与像素尺寸
+ *     （`kind` 为 `image` / `too-large` / `not-image` / `missing`），给二进制预览用；
+ *     单侧上限 `MAX_IMAGE_BYTES`，超限只回报字节数。
  *   - `log { cwd, count? }` → 最近提交（短 sha、作者、日期、refs、标题），条数钳制 1..50。
  *   - `commit { cwd, sha }` → 某次提交的元信息与改动清单（相对**第一个父提交**，
  *     合并提交也按第一父提交看），清单形状与 `status.changes` 一致。
@@ -256,7 +259,10 @@ export async function readStatus(cwd) {
     return { repo: null, branch: null, detached: false, oid: null, upstream: null, ahead: 0, behind: 0, dirty: false, counts: emptyCounts(), changes: [], truncated: false }
   }
 
-  const status = await runGit(repoRoot, ['status', '--porcelain=v2', '--branch', '-z', '--untracked-files=normal'])
+  // `--untracked-files=all`：未跟踪**按文件**计，而不是把整个未跟踪目录折成一条。
+  // 不这样写的话，`?n` 会比编辑器（以及 `git status -uall`）报的数小得多 —— 目录里 200 个新文件
+  // 只算 1 条。代价是 git 要走一遍未跟踪树，所以清单仍受 `MAX_CHANGES` 上限保护（超出置 truncated）。
+  const status = await runGit(repoRoot, ['status', '--porcelain=v2', '--branch', '-z', '--untracked-files=all'])
   if (!status.ok) {
     if (status.killed) throw Object.assign(new Error('git status timed out'), { code: 'timeout' })
     throw Object.assign(new Error(status.stderr.trim() || status.message || 'git status failed'), { code: 'git-failed' })
@@ -318,12 +324,29 @@ export async function readSessionOverview() {
       mine: entry === undefined ? 0 : entry.files.size,
       possible: entry === undefined ? 0 : entry.possible.size,
     }
-    if (row.cwd === null) return { ...summary, repo: false, error: null }
+    /**
+     * 「可能相关」里**此刻仍然有差异**的个数（与这份 status 的清单求交）。
+     *
+     * 为什么要两个数：`possible` 是"命令里提到过的路径"（历史，含已经还原/被忽略的），
+     * 面板那一行只数"现在还有差异"的。同一个概念两个口径，界面上必须分别说清，
+     * 否则就会出现"工作区干净 + 14 个可能相关"这种让人以为算错了的组合。
+     */
+    const possibleNow = entry === undefined
+      ? 0
+      : (() => {
+        const status = row.cwd === null ? undefined : byCwd.get(row.cwd)
+        if (status === undefined || status === null || Array.isArray(status.changes) !== true) return 0
+        let count = 0
+        for (const change of status.changes) if (entry.possible.has(change.file)) count += 1
+        return count
+      })()
+    if (row.cwd === null) return { ...summary, possibleNow: 0, repo: false, error: null }
     const status = byCwd.get(row.cwd)
-    if (status === undefined || status === null) return { ...summary, repo: false, error: null, pending: true }
-    if (status.error !== undefined) return { ...summary, repo: false, error: status.error }
+    if (status === undefined || status === null) return { ...summary, possibleNow: 0, repo: false, error: null, pending: true }
+    if (status.error !== undefined) return { ...summary, possibleNow: 0, repo: false, error: status.error }
     return {
       ...summary,
+      possibleNow,
       repo: status.repo !== null,
       branch: status.branch,
       detached: status.detached === true,
@@ -758,6 +781,78 @@ async function resolveCommit(cwd, sha) {
 }
 
 /** 这次提交的改动清单 + 元信息（只读 `git diff` / `git show`）。 */
+/** 标签列表上限（超出的只报 truncated，不硬塞）。 */
+const TAGS_MAX = 100
+
+/**
+ * 读标签列表（`refs/tags`，按 creatordate 倒序 = 最新的在前）。
+ *
+ * 两处容易搞错、这里显式处理：
+ * - **附注 tag**（annotated）的 `%(objectname)` 是 **tag 对象**的 sha，不是它指向的提交；
+ *   要拿提交得用 `%(*objectname)`。轻量 tag 两者相同。列表里显示提交 sha（能对上“最近提交”）。
+ * - 主题用 `%(contents:subject)`：附注 tag 是 tag 说明的首行，轻量 tag 拿到的是提交标题 ——
+ *   两种情况都比只给一个名字有用；它理论上可以是多行，所以最后一个字段按“剩下全部”再取首行。
+ */
+export async function readTags(cwd, count = TAGS_MAX) {
+  const root = await runGit(cwd, ['rev-parse', '--show-toplevel'])
+  if (!root.ok) {
+    if (root.killed) throw Object.assign(new Error('git rev-parse timed out'), { code: 'timeout' })
+    if (root.code === 'ENOENT' && !fs.existsSync(cwd)) throw Object.assign(new Error('cwd does not exist'), { code: 'no-cwd' })
+    if (root.code === 'ENOENT') throw Object.assign(new Error('git executable not found'), { code: 'git-missing' })
+    return { repo: null, tags: [], truncated: false }
+  }
+
+  const repoRoot = root.stdout.split('\n')[0].trim()
+  if (!repoRoot) return { repo: null, tags: [], truncated: false }
+
+  const requested = Number.isFinite(count) ? Math.floor(count) : TAGS_MAX
+  const limit = Math.min(Math.max(1, requested), TAGS_MAX)
+
+  // 多取一条用来判断“还有更多”（比事后猜“正好等于上限”准确）。
+  const result = await runGit(repoRoot, [
+    'for-each-ref',
+    '--sort=-creatordate',
+    `--count=${String(limit + 1)}`,
+    '--format=%(refname:short)%00%(objecttype)%00%(objectname:short)%00%(*objectname:short)%00%(creatordate:short)%00%(creatordate:unix)%00%(contents:subject)',
+    'refs/tags',
+  ])
+  // 没有 tag 时 git 也返回 0（输出为空），不是错误。
+  if (!result.ok) return { repo: repoRoot, tags: [], truncated: false }
+
+  const lines = result.stdout.split('\n').filter(line => line.length > 0)
+  const tags = lines.map((line) => {
+    const parts = line.split('\0')
+    const [name, objecttype, objectname, peeled, date, seconds] = parts
+    // 最后一个字段是主题：附注 tag 的说明可能是多行，这里只取首行。
+    const subject = parts.slice(6).join('\0').split('\n')[0] ?? ''
+    const at = Number(seconds)
+    const annotated = objecttype === 'tag'
+    // 附注 tag 要“剥一层”拿提交 sha；剥不出来（比如 tag 指向 blob/tree）就退回对象自身的 sha。
+    const sha = annotated && peeled ? peeled : objectname
+    return {
+      name: name ?? '',
+      sha: sha ?? '',
+      annotated,
+      date: date ?? '',
+      committedAt: Number.isFinite(at) ? at * 1000 : null,
+      subject,
+    }
+  })
+
+  // creatordate 同一个秒内的先后 git 不保证（测试里三个 tag 常在同一秒建出来），
+  // 再按名字倒序定死 —— 否则界面上同批 tag 每次刷新都可能换位置。
+  //
+  // 顺序：**先排序再截断**。反过来的话截出来的是 git 的任意顺序（t1、t2），排序再好也没用。
+  tags.sort((left, right) => {
+    const diff = (right.committedAt ?? 0) - (left.committedAt ?? 0)
+    if (diff !== 0) return diff
+    return left.name < right.name ? 1 : (left.name > right.name ? -1 : 0)
+  })
+
+  const truncated = tags.length > limit
+  return { repo: repoRoot, tags: tags.slice(0, limit), truncated }
+}
+
 export async function readCommit(cwd, sha) {
   const commit = await resolveCommit(cwd, sha)
   if (!commit.repo) return { repo: null, commit: null, files: [], truncated: false }
@@ -824,6 +919,270 @@ export async function readCommitDiff(cwd, sha, file, origFile = null) {
   }
 }
 
+/* --------------------------------------------- 二进制预览（图片，只读） */
+
+/**
+ * 单侧图片预览的字节上限。
+ *
+ * 超限不等于"看不了这个改动"：仍然回报真实字节数，只是不把内容塞进 JSON
+ * （base64 还要再涨 1/3，RPC 体量必须有界）。
+ */
+export const MAX_IMAGE_BYTES = 4 * 1024 * 1024
+
+/** PNG 的签名（8 字节）。 */
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+/**
+ * 从**内容**而不是扩展名认图片类型（扩展名会骗人：`.png` 里放 gif 很常见）。
+ *
+ * @param buffer - 文件头若干字节。
+ * @returns MIME 字符串，认不出返回 null。
+ */
+export function sniffImageMime(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 12) return null
+  if (buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return 'image/png'
+  if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) return 'image/jpeg'
+  const gif = buffer.subarray(0, 6).toString('latin1')
+  if (gif === 'GIF87a' || gif === 'GIF89a') return 'image/gif'
+  if (buffer.subarray(0, 4).toString('latin1') === 'RIFF' && buffer.subarray(8, 12).toString('latin1') === 'WEBP') return 'image/webp'
+  if (buffer.subarray(0, 2).toString('latin1') === 'BM') return 'image/bmp'
+  return null
+}
+
+/** PNG：IHDR 紧跟签名，宽高各 4 字节大端。 */
+function pngSize(buffer) {
+  if (buffer.length < 24) return null
+  return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) }
+}
+
+/** GIF：逻辑屏幕描述符，宽高各 2 字节小端。 */
+function gifSize(buffer) {
+  if (buffer.length < 10) return null
+  return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) }
+}
+
+/**
+ * JPEG：从头扫段，找 SOFn（C0–CF，但 C4/C8/CC 不是）里的高/宽。
+ *
+ * 段长字段是**含自身两字节**的长度，所以下一段起点是 `index + 2 + length`；
+ * 填充 0xFF、TEM 与 RSTn 都没有长度字段，只前进一字节。
+ */
+function jpegSize(buffer) {
+  let index = 2
+  while (index + 9 < buffer.length) {
+    if (buffer[index] !== 0xff) {
+      index += 1
+      continue
+    }
+    const marker = buffer[index + 1]
+    if (marker === 0xff || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+      index += 1
+      continue
+    }
+    const isFrame = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc
+    if (isFrame) return { width: buffer.readUInt16BE(index + 7), height: buffer.readUInt16BE(index + 5) }
+    const length = buffer.readUInt16BE(index + 2)
+    if (length < 2) return null
+    index += 2 + length
+  }
+  return null
+}
+
+/** WebP：VP8X 是 24 位减一、VP8（有损）内嵌 14 位、VP8L（无损）打包在 32 位里。 */
+function webpSize(buffer) {
+  if (buffer.length < 30) return null
+  const chunk = buffer.subarray(12, 16).toString('latin1')
+  if (chunk === 'VP8X') return { width: buffer.readUIntLE(24, 3) + 1, height: buffer.readUIntLE(27, 3) + 1 }
+  if (chunk === 'VP8 ' && buffer[23] === 0x9d && buffer[24] === 0x01 && buffer[25] === 0x2a) {
+    return { width: buffer.readUInt16LE(26) & 0x3fff, height: buffer.readUInt16LE(28) & 0x3fff }
+  }
+  if (chunk === 'VP8L' && buffer[20] === 0x2f) {
+    const packed = buffer.readUInt32LE(21)
+    return { width: (packed & 0x3fff) + 1, height: ((packed >> 14) & 0x3fff) + 1 }
+  }
+  return null
+}
+
+/** BMP：BITMAPINFOHEADER 的宽为有符号、高可为负（自上而下）。 */
+function bmpSize(buffer) {
+  if (buffer.length < 26) return null
+  const width = buffer.readInt32LE(18)
+  const height = buffer.readInt32LE(22)
+  if (width <= 0 || height === 0) return null
+  return { width, height: Math.abs(height) }
+}
+
+/**
+ * 读出图片的像素尺寸。纯函数，只读头部，认不出返回 `null`（绝不抛）。
+ *
+ * @param buffer - 文件内容（头部足够即可，但这里拿的是完整内容）。
+ * @param mime - `sniffImageMime` 的结果。
+ * @returns `{ width, height }` 或 null。
+ */
+export function readImageSize(buffer, mime) {
+  try {
+    if (mime === 'image/png') return pngSize(buffer)
+    if (mime === 'image/jpeg') return jpegSize(buffer)
+    if (mime === 'image/gif') return gifSize(buffer)
+    if (mime === 'image/webp') return webpSize(buffer)
+    if (mime === 'image/bmp') return bmpSize(buffer)
+    return null
+  }
+  catch {
+    return null
+  }
+}
+
+/**
+ * `runGit` 的字节版。
+ *
+ * `cat-file blob` 的输出是任意二进制，按 utf8 解码会毁掉它（非法序列变成 U+FFFD，
+ * 再编码回去就不是原文件了），所以这条路径必须单独走 buffer 编码。
+ */
+function runGitBytes(cwd, args, maxBytes) {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      args,
+      { cwd, timeout: GIT_TIMEOUT_MS, maxBuffer: maxBytes, windowsHide: true, encoding: 'buffer' },
+      (error, stdout, stderr) => {
+        if (!error) {
+          resolve({ ok: true, stdout })
+          return
+        }
+        resolve({
+          ok: false,
+          stdout,
+          stderr: stderr ? stderr.toString('utf8') : '',
+          killed: Boolean(error.killed) || Boolean(error.signal),
+          code: typeof error.code === 'number' ? error.code : (error.code ?? null),
+          message: error instanceof Error ? error.message : String(error),
+        })
+      },
+    )
+  })
+}
+
+/** 一个 git 对象的字节数；对象不存在（新文件还没有索引副本）返回 null。 */
+async function gitBlobSize(repoRoot, spec) {
+  const result = await runGit(repoRoot, ['cat-file', '-s', spec])
+  if (!result.ok) return null
+  const size = Number.parseInt(result.stdout.trim(), 10)
+  return Number.isFinite(size) && size >= 0 ? size : null
+}
+
+/** 判断一侧的内容：能预览就带上 base64 与像素尺寸，否则只说"为什么不能"。 */
+function describeSide(buffer) {
+  const bytes = buffer.length
+  const mime = sniffImageMime(buffer)
+  if (mime === null) return { kind: 'not-image', bytes }
+  const size = readImageSize(buffer, mime)
+  return {
+    kind: 'image',
+    mime,
+    bytes,
+    width: size === null ? null : size.width,
+    height: size === null ? null : size.height,
+    base64: buffer.toString('base64'),
+  }
+}
+
+/** 读工作区里的一个文件；不是普通文件、或超过上限，都只回报状态。 */
+async function readWorktreeSide(repoRoot, file) {
+  const full = path.resolve(repoRoot, file)
+  const rootPrefix = repoRoot.endsWith(path.sep) ? repoRoot : repoRoot + path.sep
+  // validateDiffPath 已经挡掉绝对路径与 `..`；这里再确认落在仓库内（软链接不越界）。
+  if (!full.startsWith(rootPrefix)) return { kind: 'missing' }
+  let stats
+  try {
+    stats = await fs.promises.stat(full)
+  }
+  catch {
+    return { kind: 'missing' }
+  }
+  if (!stats.isFile()) return { kind: 'missing' }
+  if (stats.size > MAX_IMAGE_BYTES) return { kind: 'too-large', bytes: stats.size, limit: MAX_IMAGE_BYTES }
+  try {
+    return describeSide(await fs.promises.readFile(full))
+  }
+  catch {
+    return { kind: 'missing' }
+  }
+}
+
+/** 读一个 git 对象（`<rev>:<path>`，rev 为空串即索引）：不存在即 missing，超限只回报字节数。 */
+async function readGitSide(repoRoot, rev, file) {
+  const spec = `${rev}:${file}`
+  const size = await gitBlobSize(repoRoot, spec)
+  if (size === null) return { kind: 'missing' }
+  if (size > MAX_IMAGE_BYTES) return { kind: 'too-large', bytes: size, limit: MAX_IMAGE_BYTES }
+  const result = await runGitBytes(repoRoot, ['cat-file', 'blob', spec], MAX_IMAGE_BYTES + 64 * 1024)
+  if (!result.ok) {
+    if (result.killed) throw Object.assign(new Error('git cat-file timed out'), { code: 'timeout' })
+    return { kind: 'missing' }
+  }
+  return describeSide(result.stdout)
+}
+
+/**
+ * 读一个二进制（图片）改动的两侧字节与像素尺寸，全部只读。
+ *
+ * `side` 与文本 diff 的两枚页签一一对应，这样"未暂存 / 已暂存"在两个视图里指的是同一件事：
+ *   - `worktree`（未暂存）：基线 = 索引 `:<path>`，新 = 工作区文件；
+ *   - `index`（已暂存）：基线 = `HEAD`，新 = 索引 `:<path>`；
+ *   - 给了 `sha`（提交明细）：基线 = 第一父提交（根提交则为空），新 = 该提交。
+ *
+ * 两侧各自回答"能不能预览"：`kind` 为 `image` / `too-large` / `not-image` / `missing`。
+ * 任一侧不可预览都不算失败 —— 另一侧照样能看。
+ *
+ * @param cwd - 会话工作区（绝对路径）。
+ * @param file - 仓库内相对路径。
+ * @param origFile - 重命名/复制的原路径，可选。
+ * @param side - `'worktree'` | `'index'`，给了 sha 时忽略。
+ * @param sha - 提交 sha（提交明细用），可选。
+ * @returns `{ repo, path, origPath, side, sha, before, after }`。
+ */
+export async function readImagePair(cwd, file, origFile = null, side = 'worktree', sha = null) {
+  const base = { path: file, origPath: origFile ?? null, side: sha === null ? side : 'commit', sha }
+  const empty = { repo: null, ...base, before: { kind: 'missing' }, after: { kind: 'missing' } }
+
+  if (sha !== null) {
+    const commit = await resolveCommit(cwd, sha)
+    if (!commit.repo) return empty
+    return {
+      repo: commit.repo,
+      shortSha: commit.shortSha,
+      ...base,
+      before: commit.base === null ? { kind: 'missing' } : await readGitSide(commit.repo, commit.base, origFile ?? file),
+      after: await readGitSide(commit.repo, commit.sha, file),
+    }
+  }
+
+  const root = await runGit(cwd, ['rev-parse', '--show-toplevel'])
+  if (!root.ok) {
+    if (root.killed) throw Object.assign(new Error('git rev-parse timed out'), { code: 'timeout' })
+    if (root.code === 'ENOENT' && !fs.existsSync(cwd)) throw Object.assign(new Error('cwd does not exist'), { code: 'no-cwd' })
+    if (root.code === 'ENOENT') throw Object.assign(new Error('git executable not found'), { code: 'git-missing' })
+    return empty
+  }
+
+  const repoRoot = root.stdout.split('\n')[0].trim()
+  if (side === 'index') {
+    return {
+      repo: repoRoot,
+      ...base,
+      before: await readGitSide(repoRoot, 'HEAD', origFile ?? file),
+      after: await readGitSide(repoRoot, '', file),
+    }
+  }
+  return {
+    repo: repoRoot,
+    ...base,
+    before: await readGitSide(repoRoot, '', origFile ?? file),
+    after: await readWorktreeSide(repoRoot, file),
+  }
+}
+
 /* ------------------------------------------------- 会话改动（按会话归因） */
 
 /**
@@ -858,6 +1217,161 @@ const SESSION_COMMAND_MAX = 20
 const COMMAND_TEXT_MAX = 140
 /** 一条命令里最多抽多少个路径（防御性上限）。 */
 const COMMAND_PATHS_MAX = 20
+/** 每个会话留多少条"最近工具调用"（胶囊悬停里列最近几条）。 */
+const TOOL_RECENT_MAX = 12
+/** 最多同时记多少个会话的工具活动（与归因那份各自独立淘汰）。 */
+const TOOL_SESSIONS_MAX = 32
+/** 每个会话最多记多少个技能（超出的只计数不列名）。 */
+const TOOL_SKILLS_MAX = 20
+/** 参数摘要的显示上限（超长命令/路径截断，别把胶囊撑爆）。 */
+const TOOL_SUMMARY_MAX = 60
+
+/**
+ * sessionId → { active, recent, counts, total }：这个会话**跑到哪些工具**。
+ *
+ * 与归因那份记录分开存：归因关心"改了哪些文件"，这份关心"跑了什么"。
+ */
+const sessionTools = new Map()
+
+/** 取（必要时新建）某个会话的工具活动记录，并做数量上限淘汰。 */
+function sessionToolEntry(sessionId) {
+  let entry = sessionTools.get(sessionId)
+  if (entry === undefined) {
+    entry = { active: null, recent: [], counts: new Map(), status: new Map(), skills: new Map(), total: 0 }
+    sessionTools.set(sessionId, entry)
+    if (sessionTools.size > TOOL_SESSIONS_MAX) {
+      const oldest = sessionTools.keys().next().value
+      if (oldest !== undefined && oldest !== sessionId) sessionTools.delete(oldest)
+    }
+  }
+  return entry
+}
+
+/**
+ * 参数里可以安全拿出来做"一行摘要"的键。
+ *
+ * 只认这些**路径/命令类**的键：工具参数里可能带着整个文件内容（write 的 `content`），
+ * 随便取"第一个字符串"就会把内容贴到界面上 —— 所以认不出来就干脆不写摘要。
+ */
+const TOOL_SUMMARY_KEYS = ['command', 'cmd', 'script', 'filePath', 'path', 'file', 'pattern', 'query', 'url']
+
+/** 「调用技能」那件工具的工具名（`dsh-tool-skill` 注册的名字）。 */
+const SKILL_TOOL_NAME = 'skill'
+
+/**
+ * 技能名：`skill` 工具的入参是 `{ name: '技能名' }`。
+ *
+ * 只对这一个工具认 `name` 键 —— 别的工具用 `name` 表达别的东西，不能被当技能名抓走。
+ */
+function skillNameOf(exec) {
+  if (exec === null || typeof exec !== 'object' || exec.name !== SKILL_TOOL_NAME) return null
+  const args = exec.arguments
+  if (args === null || typeof args !== 'object') return null
+  const value = args.name
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim().slice(0, TOOL_SUMMARY_MAX) : null
+}
+
+/** 从工具调用参数里取一行摘要（认不出来返回 null，不用兜底去猜）。 */
+function toolSummaryOf(exec) {
+  const skill = skillNameOf(exec)
+  if (skill !== null) return skill
+  const args = exec && exec.arguments
+  if (args === null || typeof args !== 'object') return null
+  for (const key of TOOL_SUMMARY_KEYS) {
+    const value = args[key]
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.replace(/\s+/g, ' ').trim().slice(0, TOOL_SUMMARY_MAX)
+    }
+  }
+  return null
+}
+
+/** 工具开跑：记下"现在是哪个工具、什么时候开始的"（供胶囊显示实时秒数）。 */
+function noteToolStart(exec) {
+  try {
+    const identity = sessionIdentityOf(exec)
+    if (identity === null) return
+    const entry = sessionToolEntry(identity.sessionId)
+    entry.active = {
+      callId: identity.callId,
+      name: typeof exec.name === 'string' && exec.name.length > 0 ? exec.name : '?',
+      summary: toolSummaryOf(exec),
+      startedAt: Date.now(),
+    }
+    entry.total += 1
+    const name = entry.active.name
+    entry.counts.set(name, (entry.counts.get(name) || 0) + 1)
+    const skill = skillNameOf(exec)
+    if (skill !== null) {
+      const seen = entry.skills.get(skill)
+      entry.skills.set(skill, { count: (seen ? seen.count : 0) + 1, ok: seen ? seen.ok : null })
+    }
+  } catch {
+    // 旁听失败不影响工具本身。
+  }
+}
+
+/** 工具结束：把这一次挪进"最近"，并清掉 active（只有同一个 callId 才清，避免并发调用互相抹掉）。 */
+function noteToolFinish(exec, result) {
+  try {
+    const identity = sessionIdentityOf(exec)
+    if (identity === null) return
+    const entry = sessionToolEntry(identity.sessionId)
+    const active = entry.active
+    const startedAt = active !== null && active.callId === identity.callId ? active.startedAt : null
+    entry.recent.push({
+      name: active !== null && active.callId === identity.callId ? active.name : (typeof exec.name === 'string' ? exec.name : '?'),
+      summary: active !== null && active.callId === identity.callId ? active.summary : toolSummaryOf(exec),
+      ok: !resultFailed(result),
+      at: Date.now(),
+      ms: startedAt === null ? null : Math.max(0, Date.now() - startedAt),
+    })
+    if (entry.recent.length > TOOL_RECENT_MAX) entry.recent.splice(0, entry.recent.length - TOOL_RECENT_MAX)
+    // 每个工具"最近一次调用"的结果：胶囊上每个工具前面那个 ✓/✗ 用它。
+    const finished = entry.recent[entry.recent.length - 1]
+    if (finished !== undefined) entry.status.set(finished.name, finished.ok === true)
+    // 技能自己的最近一次结果（胶囊上可以据此打 ✓/✗）。
+    const skill = skillNameOf(exec)
+    if (skill !== null && entry.skills.has(skill)) {
+      entry.skills.set(skill, { count: entry.skills.get(skill).count, ok: !resultFailed(result) })
+    }
+    if (active !== null && active.callId === identity.callId) entry.active = null
+  } catch {
+    // 同上。
+  }
+}
+
+/**
+ * 读出某个会话的工具活动（端点载荷）。
+ *
+ * `active` 带 `startedAt`：实时秒数由客户端本地计时（否则要为了一个秒数把轮询压到亚秒级 ✗）。
+ */
+export function readSessionTools(sessionId) {
+  const entry = sessionId === null || sessionId === undefined ? undefined : sessionTools.get(sessionId)
+  if (entry === undefined) {
+    return { sessionId: sessionId ?? null, tracking: true, active: null, recent: [], counts: [], skills: [], skillsDropped: 0, total: 0 }
+  }
+  const counts = [...entry.counts].map(([name, count]) => ({
+    name,
+    count,
+    // `null` = 还没看到它结束过（比如正在跑第一次），别替它编一个 ✓。
+    ok: entry.status.has(name) ? entry.status.get(name) : null,
+  }))
+  counts.sort((left, right) => right.count - left.count || (left.name < right.name ? -1 : 1))
+  // 技能按次数排序（用得多在前），超过上限只报前若干个。
+  const skills = [...entry.skills].map(([name, item]) => ({ name, count: item.count, ok: item.ok }))
+  skills.sort((left, right) => right.count - left.count || (left.name < right.name ? -1 : 1))
+  return {
+    sessionId,
+    tracking: true,
+    active: entry.active === null ? null : { ...entry.active },
+    recent: entry.recent.slice(-5).reverse(),
+    counts,
+    skills: skills.slice(0, TOOL_SKILLS_MAX),
+    skillsDropped: Math.max(0, skills.length - TOOL_SKILLS_MAX),
+    total: entry.total,
+  }
+}
 
 /** sessionId → { cwd, since, files: Map<relPath, {...}>, dropped, unconfirmed }。 */
 const sessionChanges = new Map()
@@ -1316,8 +1830,15 @@ function trackSessionChanges(ctx) {
       }),
       // 命令旁听：`tools/post-execute` 是 waterfall，**必须把 next() 的判定原样透传**
       // （兜底是 `{ kind: 'accept' }`，吞掉就等于把工具结果的裁决改掉了）。
+      // 工具开跑：记"现在在跑哪个工具"（胶囊显示实时秒数用）。
+      // `tools/pre-execute` 同样是 waterfall（兜底 `{ kind: 'allow' }`），必须原样透传判定。
+      ctx.on('tools/pre-execute', (exec, next) => {
+        noteToolStart(exec)
+        return next()
+      }),
       ctx.on('tools/post-execute', (exec, result, next) => {
         noteShellCommand(exec, result)
+        noteToolFinish(exec, result)
         return next()
       }),
     ]
@@ -1351,6 +1872,7 @@ function trackSessionChanges(ctx) {
       for (const stop of stops) if (typeof stop === 'function') stop()
       sessionChanges.clear()
       pendingChangeIntents.clear()
+      sessionTools.clear()
       sessionChangeTrackingSince = null
     }
   }, 'dsh-hud: session change tracking')
@@ -1373,6 +1895,12 @@ const ENDPOINTS = {
     return status
   },
 
+  async 'session-tools'(args) {
+    const input = args && typeof args === 'object' ? args : {}
+    const sessionId = typeof input.sessionId === 'string' && input.sessionId.length > 0 ? input.sessionId : null
+    return readSessionTools(sessionId)
+  },
+
   async 'session-statuses'() {
     return readSessionOverview()
   },
@@ -1394,6 +1922,36 @@ const ENDPOINTS = {
     return readDiff(cwd.value, file.value, origFile)
   },
 
+  /**
+   * 图片预览：一个二进制改动两侧的字节与像素尺寸。
+   *
+   * `diff` 对二进制只回一句 `binary: true`（文本 diff 里没有可看的东西），
+   * 浏览器半靠这个端点把"改了哪张图、尺寸变没变"画出来。只读，不写 index / 工作区。
+   */
+  async image(args) {
+    const input = args && typeof args === 'object' ? args : {}
+    const cwd = validateCwd(input.cwd)
+    if (!cwd.ok) throw Object.assign(new Error(cwd.message), { code: cwd.code })
+    const file = validateDiffPath(input.path)
+    if (!file.ok) throw Object.assign(new Error(file.message), { code: file.code })
+
+    let origFile = null
+    if (input.origPath !== undefined && input.origPath !== null && input.origPath !== '') {
+      const checked = validateDiffPath(input.origPath, 'origPath')
+      if (!checked.ok) throw Object.assign(new Error(checked.message), { code: checked.code })
+      origFile = checked.value
+    }
+
+    let sha = null
+    if (input.sha !== undefined && input.sha !== null && input.sha !== '') {
+      const checked = validateCommitSha(input.sha)
+      if (!checked.ok) throw Object.assign(new Error(checked.message), { code: checked.code })
+      sha = checked.value
+    }
+
+    return readImagePair(cwd.value, file.value, origFile, input.side === 'index' ? 'index' : 'worktree', sha)
+  },
+
   async log(args) {
     const input = args && typeof args === 'object' ? args : {}
     const cwd = validateCwd(input.cwd)
@@ -1401,6 +1959,13 @@ const ENDPOINTS = {
     return readLog(cwd.value, input.count)
   },
 
+  /** 标签列表（只读）。点一个 tag 复用 `commit` 那条管道去看它指向的提交。 */
+  async tags(args) {
+    const input = args && typeof args === 'object' ? args : {}
+    const cwd = validateCwd(input.cwd)
+    if (!cwd.ok) throw Object.assign(new Error(cwd.message), { code: cwd.code })
+    return readTags(cwd.value, input.count)
+  },
   async commit(args) {
     const input = args && typeof args === 'object' ? args : {}
     const cwd = validateCwd(input.cwd)