chainlesschain 0.162.158 → 0.162.159

package/src/commands/session.js

@@ -197,6 +197,15 @@ export function registerSessionCommand(program) {
           process.exit(1);
         }
 
+        // PR/session linking: surface PRs this session created/touched.
+        try {
+          const { getPrLinks } = await import("../lib/pr-link-ledger.js");
+          const prLinks = getPrLinks(sess.id);
+          if (prLinks.length > 0) sess.prLinks = prLinks;
+        } catch (_err) {
+          // PR decoration is cosmetic
+        }
+
         if (options.json) {
           console.log(JSON.stringify(sess, null, 2));
         } else {
@@ -206,6 +215,15 @@ export function registerSessionCommand(program) {
               `ID: ${sess.id}  Provider: ${sess.provider}  Model: ${sess.model}  Messages: ${sess.message_count}`,
             ),
           );
+          if (sess.prLinks) {
+            for (const pr of sess.prLinks) {
+              logger.log(
+                chalk.magenta(
+                  `PR: #${pr.number}${pr.state ? ` ${pr.state}` : ""}${pr.url ? `  ${pr.url}` : ""}`,
+                ),
+              );
+            }
+          }
           logger.log("");
 
           let messages = sess.messages;
@@ -248,6 +266,10 @@ export function registerSessionCommand(program) {
     )
     .option("--model <model>", "Model name")
     .option("--provider <provider>", "LLM provider")
+    .option(
+      "--allow-tampered",
+      "Resume even when the transcript hash chain is broken (context is untrusted)",
+    )
     .action(async (id, options) => {
       try {
         const ctx = await bootstrap({ verbose: program.opts().verbose });
@@ -270,6 +292,29 @@ export function registerSessionCommand(program) {
 
         // Try JSONL first
         if (feature("JSONL_SESSION") && sessionExists(id)) {
+          // Tamper gate: a broken hash chain means the transcript was edited
+          // outside the store — never silently rebuild it as trusted context.
+          const { verifySession } =
+            await import("../harness/jsonl-session-store.js");
+          const trust = verifySession(id);
+          if (trust.status === "tampered") {
+            if (!options.allowTampered) {
+              logger.error(
+                `Session ${id} transcript failed integrity verification: ${trust.reason}` +
+                  (trust.firstInvalidLine
+                    ? ` (line ${trust.firstInvalidLine})`
+                    : ""),
+              );
+              logger.error(
+                "Refusing to resume tampered context. Inspect it read-only with " +
+                  `'cc session show ${id}' / 'cc session verify ${id}', or pass --allow-tampered to override.`,
+              );
+              process.exit(1);
+            }
+            logger.warn(
+              `⚠ Resuming a TAMPERED transcript (${trust.reason}) — treat restored context as untrusted.`,
+            );
+          }
           const events = readEvents(id);
           const startEvent = events.find((e) => e.type === "session_start");
           sess = {
@@ -594,6 +639,143 @@ export function registerSessionCommand(program) {
       }
     });
 
+  // session verify — transcript hash-chain integrity (tamper-evidence).
+  // Distinct from `validate` (structural: parseable lines + session_start):
+  // verify recomputes the per-event hash chain and flags edits / deletions /
+  // insertions / reordering of chained records.
+  session
+    .command("verify")
+    .description(
+      "Verify transcript hash-chain integrity (tamper-evidence); omit id to verify all",
+    )
+    .argument("[id]", "Session ID to verify (omit to verify every session)")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      try {
+        const store = await import("../harness/jsonl-session-store.js");
+        const result = id ? store.verifySession(id) : store.verifyAllSessions();
+
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          const results = Array.isArray(result) ? result : [result];
+          if (results.length === 0) {
+            logger.log("No sessions to verify.");
+          }
+          for (const item of results) {
+            const color =
+              item.status === "tampered"
+                ? chalk.red
+                : item.status === "verified"
+                  ? chalk.green
+                  : chalk.yellow;
+            const counts =
+              item.chainedEvents != null
+                ? ` (${item.chainedEvents} chained, ${item.legacyEvents} legacy${item.truncatedTail ? ", truncated tail" : ""})`
+                : "";
+            logger.log(`${color(item.status)} ${item.sessionId}${counts}`);
+            if (item.reason) {
+              const where = item.firstInvalidLine
+                ? ` at line ${item.firstInvalidLine}`
+                : "";
+              logger.log(`  ${chalk.gray(item.reason + where)}`);
+            }
+          }
+        }
+
+        const anyTampered = (Array.isArray(result) ? result : [result]).some(
+          (item) => item.status === "tampered",
+        );
+        if (anyTampered) process.exit(1);
+      } catch (err) {
+        logger.error(`Failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // session index — SQLite index over the JSONL store (gap P2#14). Gives fast
+  // list/search without scanning every transcript, and can mirror sessions to a
+  // configured off-box target (fs/http). The index is a derived cache: safe to
+  // delete and rebuild from the JSONL at any time.
+  session
+    .command("index")
+    .description(
+      "Build/refresh the SQLite session index; search it, or mirror sessions off-box",
+    )
+    .argument("[query]", "Search the index for a term (omit to just sync)")
+    .option("--rebuild", "Force a full re-index (ignore mtime cache)")
+    .option("--stats", "Show index-wide counters")
+    .option("--mirror <ids...>", "Push session id(s) to the configured mirror")
+    .option(
+      "--limit <n>",
+      "Max rows for search/list",
+      (v) => parseInt(v, 10),
+      20,
+    )
+    .option("--json", "Output as JSON")
+    .action(async (query, options) => {
+      let db;
+      try {
+        const idx = await import("../harness/session-index.js");
+        db = idx.openIndex();
+        const sync = idx.syncIndex(db, { force: Boolean(options.rebuild) });
+
+        if (options.mirror && options.mirror.length) {
+          const result = await mirrorSessions(options.mirror);
+          if (options.json) return console.log(JSON.stringify(result, null, 2));
+          for (const r of result.pushed)
+            logger.log(chalk.green(`  mirrored ${r.id} (${r.bytes} bytes)`));
+          for (const r of result.errors) logger.error(`  ${r.id}: ${r.error}`);
+          if (!result.target)
+            logger.log(
+              chalk.yellow(
+                "No mirror configured — set session.mirror.kind (fs|http) + target in config.",
+              ),
+            );
+          return;
+        }
+
+        if (options.stats) {
+          const st = idx.indexStats(db);
+          if (options.json) return console.log(JSON.stringify(st, null, 2));
+          logger.log(
+            `${st.sessions} sessions, ${st.messages} messages, ${st.events} events indexed`,
+          );
+          return;
+        }
+
+        if (query) {
+          const hits = idx.searchSessions(db, query, { limit: options.limit });
+          if (options.json) return console.log(JSON.stringify(hits, null, 2));
+          if (hits.length === 0) {
+            logger.log(chalk.gray(`No sessions match "${query}".`));
+            return;
+          }
+          for (const h of hits) {
+            logger.log(
+              `${chalk.cyan(h.id)}  ${chalk.gray(h.title)}  ${chalk.gray(h.updated_at)}`,
+            );
+            if (h.snippet) logger.log(`  …${h.snippet}…`);
+          }
+          return;
+        }
+
+        if (options.json) return console.log(JSON.stringify(sync, null, 2));
+        logger.success(
+          `Index synced: ${sync.updated} updated, ${sync.removed} removed, ${sync.total} total.`,
+        );
+      } catch (err) {
+        logger.error(`Failed: ${err.message}`);
+        process.exit(1);
+      } finally {
+        try {
+          db?.close();
+        } catch {
+          /* best-effort */
+        }
+      }
+    });
+
   // session policy — Managed Agents parity Phase E1 approval policy
   session
     .command("policy")
@@ -822,14 +1004,106 @@ export function registerSessionCommand(program) {
   // ---------------------------------------------------------------
   // session usage [id] — Phase I: aggregate token usage
   // ---------------------------------------------------------------
+  const USAGE_BY_DIMENSIONS = [
+    "origin",
+    "skill",
+    "subagent",
+    "tool",
+    "mcp",
+    "model",
+  ];
+
+  // Shared `--by` renderer for the per-session and global modes (both result
+  // shapes carry the same `attribution` section). turnTokens is a turn-level
+  // approximation — a turn's tokens count once per distinct tool, so the
+  // column must not be summed across rows.
+  const printUsageBy = (result, by) => {
+    const a = result.attribution || {};
+    const tokRow = (label, r) =>
+      logger.log(
+        `  ${chalk.gray(String(label).padEnd(28))} in=${r.inputTokens}  out=${r.outputTokens}  total=${chalk.cyan(r.totalTokens.toLocaleString())}  calls=${r.calls}`,
+      );
+    const toolRow = (label, r) =>
+      logger.log(
+        `  ${chalk.gray(String(label).padEnd(28))} calls=${r.calls}  errors=${r.errors}  turnTokens≈${chalk.cyan((r.turnTokens || 0).toLocaleString())}`,
+      );
+    const empty = (what) => logger.log(chalk.gray(`  (no ${what} recorded)`));
+
+    switch (by) {
+      case "model": {
+        const rows = result.byModel || [];
+        if (rows.length === 0) return empty("token_usage events");
+        for (const r of rows)
+          tokRow(`${r.provider || "?"}/${r.model || "?"}`, r);
+        return;
+      }
+      case "origin": {
+        const rows = a.byOrigin || [];
+        if (rows.length === 0) return empty("token_usage events");
+        for (const r of rows) tokRow(r.origin, r);
+        return;
+      }
+      case "skill": {
+        const rows = a.bySkill || [];
+        if (rows.length === 0)
+          return empty("skill-attributed usage (isolated skill runs)");
+        for (const r of rows) tokRow(r.skill, r);
+        return;
+      }
+      case "subagent": {
+        const rows = a.bySubagent || [];
+        if (rows.length === 0) return empty("sub-agent-attributed usage");
+        for (const r of rows)
+          tokRow(`${r.subagentId}${r.role ? ` [${r.role}]` : ""}`, r);
+        return;
+      }
+      case "tool": {
+        const rows = a.tools?.byTool || [];
+        if (rows.length === 0) return empty("tool_call events");
+        for (const r of rows) toolRow(r.tool, r);
+        logger.log(
+          chalk.gray(
+            "  turnTokens = tokens of turns that used the tool (approximation; do not sum across rows)",
+          ),
+        );
+        return;
+      }
+      case "mcp": {
+        const rows = a.tools?.byMcpServer || [];
+        if (rows.length === 0)
+          return empty("MCP tool calls (mcp__<server>__*)");
+        for (const r of rows) toolRow(r.server, r);
+        logger.log(
+          chalk.gray(
+            "  turnTokens = tokens of turns that used the server (approximation; do not sum across rows)",
+          ),
+        );
+        return;
+      }
+      default:
+        break;
+    }
+  };
+
   session
     .command("usage")
     .description("Aggregate token usage (per-session or global)")
     .argument("[id]", "Session ID (omit for global rollup)")
     .option("--json", "Output as JSON")
+    .option(
+      "--by <dimension>",
+      `Breakdown dimension: ${USAGE_BY_DIMENSIONS.join("|")}`,
+    )
     .option("--limit <n>", "Max sessions for global rollup", "1000")
     .action(async (id, options) => {
       try {
+        const by = options.by ? String(options.by).toLowerCase() : null;
+        if (by && !USAGE_BY_DIMENSIONS.includes(by)) {
+          logger.error(
+            `Invalid --by "${options.by}" — expected one of: ${USAGE_BY_DIMENSIONS.join(", ")}`,
+          );
+          process.exit(1);
+        }
         const { sessionUsage, allSessionsUsage } =
           await import("../lib/session-usage.js");
         const result = id
@@ -841,6 +1115,22 @@ export function registerSessionCommand(program) {
           return;
         }
 
+        if (by) {
+          const t = result.total;
+          logger.log(
+            chalk.bold(
+              id
+                ? `Session ${chalk.gray(id.slice(0, 16))} — by ${by}`
+                : `Global usage — by ${by}`,
+            ),
+          );
+          logger.log(
+            `  total: ${chalk.cyan(t.totalTokens.toLocaleString())} tokens  in=${t.inputTokens}  out=${t.outputTokens}  calls=${t.calls}`,
+          );
+          printUsageBy(result, by);
+          return;
+        }
+
         if (id) {
           logger.log(chalk.bold(`Session ${chalk.gray(id.slice(0, 16))}`));
           const t = result.total;
@@ -1194,6 +1484,42 @@ export function registerSessionCommand(program) {
     });
 }
 
+/**
+ * Push the given session ids to the configured off-box mirror (gap P2#14).
+ * Mirror config: session.mirror = { kind: "fs"|"http", dir|baseUrl, token? }.
+ * Returns { target, pushed, errors }; target null when no mirror is configured.
+ */
+async function mirrorSessions(ids) {
+  const { createMirror } = await import("../harness/session-mirror.js");
+  const store = await import("../harness/jsonl-session-store.js");
+  let cfg = {};
+  try {
+    cfg =
+      (await import("../lib/config-manager.js")).loadConfig()?.session
+        ?.mirror || {};
+  } catch {
+    cfg = {};
+  }
+  const mirror = createMirror(cfg);
+  if (!mirror) return { target: null, pushed: [], errors: [] };
+
+  const pushed = [];
+  const errors = [];
+  const { readFileSync, existsSync } = await import("node:fs");
+  for (const id of ids) {
+    try {
+      if (store.isUnsafeSessionId(id)) throw new Error("unsafe session id");
+      const file = store.sessionPath(id);
+      if (!existsSync(file)) throw new Error("session not found");
+      const bytes = readFileSync(file, "utf-8");
+      pushed.push(await mirror.push(id, bytes));
+    } catch (err) {
+      errors.push({ id, error: err.message });
+    }
+  }
+  return { target: mirror.target, pushed, errors };
+}
+
 // === Iter21 V2 governance overlay ===
 export function registerSesgovV2Commands(program) {
   const parent = program.commands.find((c) => c.name() === "session");

package/src/data/changelog.json

@@ -3,7 +3,7 @@
   "releases": [
     {
       "productVersion": "Unreleased",
-      "cliVersion": "0.162.158",
+      "cliVersion": "0.162.159",
       "cliVersions": [
         "0.4.46",
         "0.4.51",
@@ -16,11 +16,16 @@
         "0.162.155",
         "0.162.156",
         "0.162.157",
-        "0.162.158"
+        "0.162.158",
+        "0.162.159"
       ],
       "date": null,
       "title": "",
       "sections": [
+        {
+          "heading": "Added — cc CLI 0.162.159：Claude-Code 平价 gap-analysis 14 项收口（cloud handoff + /tui + /voice + /fast + plugin 治理 + session SQLite 索引）（CLI-only npm 发版）",
+          "body": "> `chainlesschain` 0.162.158 → **0.162.159** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` 增量；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。顶层命令数 **173 → 175**（新增 `cc cloud` + `cc routine`；`cc session index` 是 `session` 子命令、`/tui` `/voice` `/fast` 为 REPL-only 均不计数）。对照 `docs/internal/cli-claude-code-gap-analysis-2026-07-11.md` 14 项全落地。\n\n- **`cc cloud`（P1#7）自托管 cloud handoff**：`cc cloud run/status/attach/list`——`git bundle`（base64）当前分支上传到配置的私有 runner（`cloud.baseUrl`/`cloud.token` 或 `CC_CLOUD_URL`/`CC_CLOUD_TOKEN`），runner 完成后 `cc cloud attach` 轮询到终态并 `git apply --3way` 回流 patch、落 plan/artifacts、显示 PR——无 Anthropic 云依赖。本地 job 台账 `~/.chainlesschain/cloud-jobs/`（穿越守卫），不落地的 patch 存旁不失败。\n- **`/tui`（P1#10）全屏无闪烁视图**：`/tui fullscreen` 进备用屏缓冲（`?1049h`，保滚动历史）+ 尾锚定视口窗口化 + diff 重绘（仅改动行光标寻址重写，无整屏清屏→无闪烁）；`/tui default` 退回流式滚动；`CC_NO_FLICKER=1` 启动即全屏；屏幕阅读器模式强制 default。持久化 `cli.tuiMode`。\n- **`/voice`（P2#11）语音听写**：`/voice hold|tap|off`（hold=按住说话，tap=切换）；严格 local-first STT 优先级（本地 Whisper > 系统 STT > 云，云需 `voice.allowCloud` 显式开）；SSH/无 TTY/CI/`CC_NO_VOICE` 环境清晰降级不假装监听；真实采集是主机绑定 DI seam。\n- **`/fast`（P2#12）延迟档**：`/fast on|off|status`——下一轮最小化推理（thinking off）+ 除非用户 `/model` 钉过模型否则换到 provider 的低延迟模型（anthropic→haiku-4-5、openai→4o-mini、deepseek/dashscope/mistral/gemini），始终显示成本/质量权衡。持久化 `cli.fastMode`。\n- **插件治理（P2#13）三项**：manifest `dependencies`（插件名→semver 区间 + 保留 `host`/`cc` 约束 CLI 版本）经 `cc plugin validate` 校验缺失/越界依赖；LSP 注册表改**每 languageId 有序候选表**——一个插件 LSP server 二进制缺失不再遮蔽 builtin（回退到下一候选/内建，扩展名不再\"变黑\"）；`isPluginInUse` 把 LSP/MCP/hooks/monitors 被动组件视为 in-use，不再被\"未调用即弃用\"误判。\n- **`cc session index`（P2#14）外部 session 存储**：JSONL 仍是权威源，新增 SQLite 索引（`~/.chainlesschain/session-index.db`）——增量按 mtime+size 同步 + 内容/标题搜索（LIKE 转义通配符）+ stats + `--rebuild`，取代逐文件解析（1072 真 session 验过）；可插拔 off-box mirror（`fs`/`http` 驱动，S3/WebDAV/Redis 同接口待配），`session.mirror.{kind,dir|baseUrl,token}` 配置，加密/访问控制由驱动独立负责。\n- **P0/P1 早前提交同随本版发出**：`cc bg view` 交互式 agent 面板（P0#1）+ background supervisor 稳定性加固（P0#2）+ `/doctor` 可修复 checkup + `/checkup` 别名（P0#3）+ transcript hash-chain 防篡改 `cc session verify`（P0#4）+ Inbound Channels（webhook/telegram allowlist，P0#5）+ computer-use MCP 显式开启（P1#6）+ Routines（cron/once/webhook/github，P1#8）+ PR/session linking（P1#9）。"
+        },
         {
           "heading": "Added — cc CLI 0.162.158：browser_state agent 工具 + REPL /remote-control + web-panel 直连配对/审批卡片 + 交付物预览下载（CLI-only npm 发版）",
           "body": "> `chainlesschain` 0.162.157 → **0.162.158** 发 npm `latest`（经 `npm-publish.yml`，`--provenance --access public`）。纯 `packages/cli/src` + web-panel dist 随包；未触 `pdh/lib` → 无 Android cc bundle rollover / 无 USR_VERSION 改动。命令数不变（**173**）；AGENT_TOOLS **24 → 25**（新增 `browser_state`）。\n\n- **`browser_state` 一等 agent 工具（IDE gap P1 #8 收口）**：Chrome CDP 连接器（`cc browse chrome`）暴露为第 25 个 agent 工具——URL/标题/标签页 + 观察窗口 console/失败网络请求 + DOM 快照（agent 面 40k cap，CLI 命令面 150k）+ 可选截图（**生成的**临时路径，防 agent 自选路径经读工具覆盖任意文件）；LOW/READ/plan 模式可用，纯观察不点击不输入不导航，仅 loopback CDP。\n- **REPL `/remote-control`（别名 `/rc`）on|off|status（批 26）**：交互式会话内起自托管 WS + RemoteApprovalBridge 配对（URI + 可选二维码），TAB 补全 + /help；`cc agent --remote-control` 对交互式会话同样生效（启动失败降级 local-only 不中断会话）。**交互式远程审批赛跑语义**（新 `src/repl/remote-approval.js`）：两个交互 confirmer（ApprovalGate + settings/hook ask）把终端 prompt 与已配对设备赛跑，先答先赢；与 headless 刻意不同——远端超时/断开**不是决定**（静默的手机永不代键盘用户 auto-deny），设备先答则取消本地 readline 并压掉其搁浅的 idle-timeout。\n- **web-panel 直连（direct-LAN）配对 + `permission.request` 审批卡片（批 28）**：remoteSession store 自动识别双 URI 方案——relay E2EE 路径不变，新增 `chainlesschain://remote-control/pair#` 直连 transport（browser 版 parseDirectPairingUri + 客户端过期检查）；直连控制走 remote-session-publish **顶层 commandId+seq**（applyControlIdempotent direct-client 契约）；一次性 pairing token → 直连断开**刻意不自动重连**（重 join 必失败，诚实 disconnected 态 + 重配对提示）；两种 transport 喂同一 pendingApprovals 卡片（requestId 去重 + permission.resolved 任意裁决方清除 + 首等公民审批卡列表批准/拒绝）。\n- **交付物 Markdown 预览 + 浏览器下载（批 25）**：面板 text/markdown 预览走既有 MarkdownRenderer（marked+DOMPurify+hljs，零新依赖）；新 `GET /api/artifacts/<id>/download` 流式下载完整存档副本（WS 预览仍 cap）——Content-Disposition（RFC 5987）+ no-store/nosniff + 配置 wsToken 时同 WS 强度 token 门（sha256+timingSafeEqual，Bearer 头不进 URL）+ basename 防篡改守卫。\n- **安全修复 ×2**：① **直连配对信任边界**——直连（LAN）配对无密码学主机身份（区别 relay E2EE），钓鱼配对 URI 可把面板指向任意公网 ws:// 端点导走 serverToken/prompt/审批决定；两端 parser（web-panel + CLI 孪生）现拒绝指向非私网主机的明文 ws://（仅 loopback/RFC-1918/link-local/ULA，即 pickLanAddress 可能产出的全集；wss:// 不限），IPv6 括号 + IPv4-mapped 点分/hex 双形态识别，RED 反证过。② **chrome-connector launch-arg 加固**——launch URL 曾逐字进 Chrome argv（`--` 开头值被 Chrome 当开关解析=潜在命令执行面），现限 http(s)://、about:（URL parse 校验字节原样透传）+ CDP 端口处处整型边界校验。\n- **健壮性**：web-panel 审批卡发送失败恢复——approve() 乐观清除后若答复未离开本端（直连 publish 拒绝/socket 断/relay 未配对）恢复卡片并浮错，可重新裁决；失败窗口内别设备已 resolved 则抑制恢复（无僵尸卡）。RED 反证 + web-panel 全套 2512 绿。\n- **测试稳健性（仓库面，不进 npm 包）**：checkpoint-store `vi.setConfig 30s` + web-panel doctor 90s 两处负载敏感预算加固（trap #31 形态）；ai-doc-creator 集成测试改 chdir tmpDir，不再向仓库根泄漏 12 个产物文件。"

package/src/harness/jsonl-session-store.js

@@ -14,6 +14,12 @@ import {
 import { join, basename, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { getHomeDir } from "../lib/paths.js";
+import {
+  computeEventHash,
+  latestChainHash,
+  verifyTranscriptText,
+  TRANSCRIPT_CHAIN_STATUS,
+} from "./transcript-integrity.js";
 
 function getSessionsDir() {
   const dir = join(getHomeDir(), "sessions");
@@ -54,11 +60,66 @@ export function appendTokenUsage(sessionId, usage) {
   appendEvent(sessionId, "token_usage", usage || {});
 }
 
+// Chain-tail cache: hash of the last chained record per session, so appends
+// stay O(1) instead of re-reading the file. Keyed per process — two processes
+// appending the SAME session concurrently could fork the chain (verify would
+// then flag it), but the store has always assumed a single writer per session.
+const _chainTailCache = new Map();
+
+function _resolveChainTail(sessionId, filePath) {
+  if (!existsSync(filePath)) {
+    // Missing file self-heals a stale cache entry (file deleted externally,
+    // or a test tearing down the sessions dir between cases).
+    _chainTailCache.set(sessionId, null);
+    return null;
+  }
+  const cached = _chainTailCache.get(sessionId);
+  if (cached !== undefined) return cached;
+  const tail = latestChainHash(readFileSync(filePath, "utf-8"));
+  _chainTailCache.set(sessionId, tail);
+  return tail;
+}
+
 export function appendEvent(sessionId, type, data) {
-  const line = JSON.stringify({ type, timestamp: Date.now(), data }) + "\n";
-  appendFileSync(sessionPath(sessionId), line, "utf-8");
+  const filePath = sessionPath(sessionId);
+  const prevHash = _resolveChainTail(sessionId, filePath);
+  const core = { type, timestamp: Date.now(), data };
+  const hash = computeEventHash(prevHash, core);
+  const line = JSON.stringify({ ...core, prevHash, hash }) + "\n";
+  appendFileSync(filePath, line, "utf-8");
+  _chainTailCache.set(sessionId, hash);
+}
+
+/**
+ * Verify a session transcript's hash chain (tamper-evidence).
+ * Statuses: verified | partial (legacy prefix + valid chain) | legacy
+ * (pre-chaining transcript) | tampered | empty — plus not-found / invalid-id.
+ */
+export function verifySession(sessionId) {
+  if (isUnsafeSessionId(sessionId)) {
+    return { sessionId, status: "invalid-id", reason: "invalid session id" };
+  }
+  const filePath = sessionPath(sessionId);
+  if (!existsSync(filePath)) {
+    return { sessionId, status: "not-found", reason: "session file not found" };
+  }
+  return {
+    sessionId,
+    ...verifyTranscriptText(readFileSync(filePath, "utf-8")),
+  };
 }
 
+export function verifyAllSessions(options = {}) {
+  const dir = getSessionsDir();
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => file.endsWith(".jsonl"))
+    .slice(0, options.limit || 1000)
+    .map((file) => verifySession(basename(file, ".jsonl")));
+}
+
+export { TRANSCRIPT_CHAIN_STATUS };
+
 export function startSession(sessionId, meta = {}) {
   const id =
     sessionId ||
@@ -85,6 +146,25 @@ export function appendToolCall(sessionId, toolName, args) {
   appendEvent(sessionId, "tool_call", { tool: toolName, args });
 }
 
+/**
+ * Compact tool-call record for usage attribution (用量归因): tool name +
+ * error flag (+ an optional skill hint for `run_skill`) — deliberately NOT
+ * the args, which can carry whole file bodies (write_file content) and would
+ * bloat the transcript. Written at tool-result time by the agent drivers so
+ * `cc session usage --by tool|mcp` and `cc insights` can aggregate tool use
+ * for any persisted session.
+ */
+export function appendToolCallCompact(
+  sessionId,
+  { tool, isError, skill } = {},
+) {
+  appendEvent(sessionId, "tool_call", {
+    tool: tool || "?",
+    is_error: Boolean(isError),
+    ...(skill ? { skill: String(skill) } : {}),
+  });
+}
+
 export function appendToolResult(sessionId, toolName, result) {
   appendEvent(sessionId, "tool_result", { tool: toolName, result });
 }