reasonix 0.4.22 → 0.4.24

package/dist/cli/index.js

@@ -506,6 +506,174 @@ function resolveTemperatures(budget, custom) {
   return out;
 }
 
+// src/hooks.ts
+import { spawn } from "child_process";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+var HOOK_EVENTS = [
+  "PreToolUse",
+  "PostToolUse",
+  "UserPromptSubmit",
+  "Stop"
+];
+var BLOCKING_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "UserPromptSubmit"]);
+var DEFAULT_TIMEOUTS_MS = {
+  PreToolUse: 5e3,
+  UserPromptSubmit: 5e3,
+  PostToolUse: 3e4,
+  Stop: 3e4
+};
+var HOOK_SETTINGS_FILENAME = "settings.json";
+var HOOK_SETTINGS_DIRNAME = ".reasonix";
+function globalSettingsPath(homeDirOverride) {
+  return join2(homeDirOverride ?? homedir2(), HOOK_SETTINGS_DIRNAME, HOOK_SETTINGS_FILENAME);
+}
+function projectSettingsPath(projectRoot) {
+  return join2(projectRoot, HOOK_SETTINGS_DIRNAME, HOOK_SETTINGS_FILENAME);
+}
+function readSettingsFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync2(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed;
+  } catch {
+  }
+  return null;
+}
+function loadHooks(opts = {}) {
+  const out = [];
+  if (opts.projectRoot) {
+    const projPath = projectSettingsPath(opts.projectRoot);
+    const settings2 = readSettingsFile(projPath);
+    if (settings2) appendResolved(out, settings2, "project", projPath);
+  }
+  const globalPath = globalSettingsPath(opts.homeDir);
+  const settings = readSettingsFile(globalPath);
+  if (settings) appendResolved(out, settings, "global", globalPath);
+  return out;
+}
+function appendResolved(out, settings, scope, source) {
+  if (!settings.hooks) return;
+  for (const event of HOOK_EVENTS) {
+    const list = settings.hooks[event];
+    if (!Array.isArray(list)) continue;
+    for (const cfg of list) {
+      if (!cfg || typeof cfg.command !== "string" || cfg.command.trim() === "") continue;
+      out.push({ ...cfg, event, scope, source });
+    }
+  }
+}
+function matchesTool(hook, toolName) {
+  if (hook.event !== "PreToolUse" && hook.event !== "PostToolUse") return true;
+  const m = hook.match;
+  if (!m || m === "*") return true;
+  try {
+    const re = new RegExp(`^(?:${m})$`);
+    return re.test(toolName);
+  } catch {
+    return false;
+  }
+}
+function defaultSpawner(input) {
+  return new Promise((resolve6) => {
+    const child = spawn(input.command, {
+      cwd: input.cwd,
+      shell: true,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let stdout2 = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+      }, 500);
+    }, input.timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout2 += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.once("error", (err) => {
+      clearTimeout(timer);
+      resolve6({
+        exitCode: null,
+        stdout: stdout2,
+        stderr,
+        timedOut: false,
+        spawnError: err
+      });
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      resolve6({
+        exitCode: code,
+        stdout: stdout2.trim(),
+        stderr: stderr.trim(),
+        timedOut
+      });
+    });
+    try {
+      child.stdin.write(input.stdin);
+      child.stdin.end();
+    } catch {
+    }
+  });
+}
+function formatHookOutcomeMessage(outcome) {
+  if (outcome.decision === "pass") return "";
+  const detail = (outcome.stderr || outcome.stdout || "").trim();
+  const tag = `${outcome.hook.scope}/${outcome.hook.event}`;
+  const cmd = outcome.hook.command.length > 60 ? `${outcome.hook.command.slice(0, 60)}\u2026` : outcome.hook.command;
+  const head = `hook ${tag} \`${cmd}\` ${outcome.decision}`;
+  return detail ? `${head}: ${detail}` : head;
+}
+function decideOutcome(event, raw) {
+  if (raw.spawnError) return "error";
+  if (raw.timedOut) return BLOCKING_EVENTS.has(event) ? "block" : "warn";
+  if (raw.exitCode === 0) return "pass";
+  if (raw.exitCode === 2 && BLOCKING_EVENTS.has(event)) return "block";
+  return "warn";
+}
+async function runHooks(opts) {
+  const spawner = opts.spawner ?? defaultSpawner;
+  const event = opts.payload.event;
+  const toolName = opts.payload.toolName ?? "";
+  const matching = opts.hooks.filter((h) => h.event === event && matchesTool(h, toolName));
+  const outcomes = [];
+  let blocked = false;
+  const stdin2 = `${JSON.stringify(opts.payload)}
+`;
+  for (const hook of matching) {
+    const start = Date.now();
+    const timeoutMs = hook.timeout ?? DEFAULT_TIMEOUTS_MS[event];
+    const cwd = hook.cwd ?? opts.payload.cwd;
+    const raw = await spawner({ command: hook.command, cwd, stdin: stdin2, timeoutMs });
+    const decision = decideOutcome(event, raw);
+    outcomes.push({
+      hook,
+      decision,
+      exitCode: raw.exitCode,
+      stdout: raw.stdout,
+      stderr: raw.stderr || (raw.spawnError ? raw.spawnError.message : "") || (raw.timedOut ? `hook timed out after ${timeoutMs}ms` : ""),
+      durationMs: Date.now() - start
+    });
+    if (decision === "block") {
+      blocked = true;
+      break;
+    }
+  }
+  return { event, outcomes, blocked };
+}
+
 // src/repair/flatten.ts
 function analyzeSchema(schema) {
   if (!schema) return { shouldFlatten: false, leafCount: 0, maxDepth: 0 };
@@ -1128,21 +1296,21 @@ function signature2(call) {
 import {
   appendFileSync,
   chmodSync as chmodSync2,
-  existsSync,
+  existsSync as existsSync2,
   mkdirSync as mkdirSync2,
-  readFileSync as readFileSync2,
+  readFileSync as readFileSync3,
   readdirSync,
   statSync,
   unlinkSync,
   writeFileSync as writeFileSync2
 } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname as dirname2, join as join2 } from "path";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname2, join as join3 } from "path";
 function sessionsDir() {
-  return join2(homedir2(), ".reasonix", "sessions");
+  return join3(homedir3(), ".reasonix", "sessions");
 }
 function sessionPath(name) {
-  return join2(sessionsDir(), `${sanitizeName(name)}.jsonl`);
+  return join3(sessionsDir(), `${sanitizeName(name)}.jsonl`);
 }
 function sanitizeName(name) {
   const cleaned = name.replace(/[^\w\-\u4e00-\u9fa5]/g, "_").slice(0, 64);
@@ -1150,9 +1318,9 @@ function sanitizeName(name) {
 }
 function loadSessionMessages(name) {
   const path = sessionPath(name);
-  if (!existsSync(path)) return [];
+  if (!existsSync2(path)) return [];
   try {
-    const raw = readFileSync2(path, "utf8");
+    const raw = readFileSync3(path, "utf8");
     const out = [];
     for (const line of raw.split(/\r?\n/)) {
       const trimmed = line.trim();
@@ -1180,11 +1348,11 @@ function appendSessionMessage(name, message) {
 }
 function listSessions() {
   const dir = sessionsDir();
-  if (!existsSync(dir)) return [];
+  if (!existsSync2(dir)) return [];
   try {
     const files = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
     return files.map((file) => {
-      const path = join2(dir, file);
+      const path = join3(dir, file);
       const stat = statSync(path);
       const name = file.replace(/\.jsonl$/, "");
       const messageCount = countLines(path);
@@ -1216,7 +1384,7 @@ function rewriteSession(name, messages) {
 }
 function countLines(path) {
   try {
-    const raw = readFileSync2(path, "utf8");
+    const raw = readFileSync3(path, "utf8");
     return raw.split(/\r?\n/).filter((l) => l.trim()).length;
   } catch {
     return 0;
@@ -1330,6 +1498,14 @@ var CacheFirstLoop = class {
   branchEnabled;
   branchOptions;
   sessionName;
+  /**
+   * Hook list, mutable so `/hooks reload` can swap it without
+   * reconstructing the loop. Default empty — the filter cost on a
+   * tool call is one array length check.
+   */
+  hooks;
+  /** `cwd` reported to hook stdin. Resolved once at construction. */
+  hookCwd;
   /** Number of messages that were pre-loaded from the session file. */
   resumedMessageCount;
   _turn = 0;
@@ -1348,6 +1524,8 @@ var CacheFirstLoop = class {
     this.tools = opts.tools ?? new ToolRegistry();
     this.model = opts.model ?? "deepseek-chat";
     this.maxToolIters = opts.maxToolIters ?? 64;
+    this.hooks = opts.hooks ?? [];
+    this.hookCwd = opts.hookCwd ?? process.cwd();
     if (typeof opts.branch === "number") {
       this.branchOptions = { budget: opts.branch };
     } else if (opts.branch && typeof opts.branch === "object") {
@@ -1811,7 +1989,37 @@ var CacheFirstLoop = class {
           toolName: name,
           toolArgs: args
         };
-        const result = await this.tools.dispatch(name, args, { signal });
+        const parsedArgs = safeParseToolArgs(args);
+        const preReport = await runHooks({
+          hooks: this.hooks,
+          payload: {
+            event: "PreToolUse",
+            cwd: this.hookCwd,
+            toolName: name,
+            toolArgs: parsedArgs
+          }
+        });
+        for (const w of hookWarnings(preReport.outcomes, this._turn)) yield w;
+        let result;
+        if (preReport.blocked) {
+          const blocking = preReport.outcomes[preReport.outcomes.length - 1];
+          const reason = (blocking?.stderr || blocking?.stdout || "blocked by PreToolUse hook").trim();
+          result = `[hook block] ${blocking?.hook.command ?? "<unknown>"}
+${reason}`;
+        } else {
+          result = await this.tools.dispatch(name, args, { signal });
+          const postReport = await runHooks({
+            hooks: this.hooks,
+            payload: {
+              event: "PostToolUse",
+              cwd: this.hookCwd,
+              toolName: name,
+              toolArgs: parsedArgs,
+              toolResult: result
+            }
+          });
+          for (const w of hookWarnings(postReport.outcomes, this._turn)) yield w;
+        }
         this.appendAndPersist({
           role: "tool",
           tool_call_id: call.id ?? "",
@@ -1898,6 +2106,19 @@ function stripHallucinatedToolMarkup(s) {
   out = out.replace(/<｜DSML｜[\s\S]*$/g, "");
   return out.trim();
 }
+function safeParseToolArgs(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function* hookWarnings(outcomes, turn) {
+  for (const o of outcomes) {
+    if (o.decision === "pass") continue;
+    yield { turn, role: "warning", content: formatHookOutcomeMessage(o) };
+  }
+}
 function reasonPrefixFor(reason, iterCap) {
   if (reason === "aborted") return "[aborted by user (Esc) \u2014 summarizing what I found so far]";
   if (reason === "context-guard") {
@@ -2238,10 +2459,10 @@ function registerFilesystemTools(registry, opts) {
       const after = before.slice(0, firstIdx) + args.replace + before.slice(firstIdx + args.search.length);
       await fs.writeFile(abs, after, "utf8");
       const rel = pathMod.relative(rootDir, abs);
-      const header = `edited ${rel} (${args.search.length}\u2192${args.replace.length} chars)`;
+      const header2 = `edited ${rel} (${args.search.length}\u2192${args.replace.length} chars)`;
       const startLine = before.slice(0, firstIdx).split(/\r?\n/).length;
       const diff = renderEditDiff(args.search, args.replace, startLine);
-      return `${header}
+      return `${header2}
 ${diff}`;
     }
   });
@@ -2493,8 +2714,8 @@ function registerPlanTool(registry, opts = {}) {
 }
 
 // src/tools/shell.ts
-import { spawn } from "child_process";
-import { existsSync as existsSync2, statSync as statSync2 } from "fs";
+import { spawn as spawn2 } from "child_process";
+import { existsSync as existsSync3, statSync as statSync2 } from "fs";
 import * as pathMod2 from "path";
 var DEFAULT_TIMEOUT_SEC = 60;
 var DEFAULT_MAX_OUTPUT_CHARS = 32e3;
@@ -2617,7 +2838,7 @@ async function runCommand(cmd, opts) {
   return await new Promise((resolve6, reject) => {
     let child;
     try {
-      child = spawn(bin, args, effectiveSpawnOpts);
+      child = spawn2(bin, args, effectiveSpawnOpts);
     } catch (err) {
       reject(err);
       return;
@@ -2672,7 +2893,7 @@ function resolveExecutable(cmd, opts = {}) {
 }
 function defaultIsFile(full) {
   try {
-    return existsSync2(full) && statSync2(full).isFile();
+    return existsSync3(full) && statSync2(full).isFile();
   } catch {
     return false;
   }
@@ -2784,11 +3005,11 @@ function registerShellTools(registry, opts) {
   return registry;
 }
 function formatCommandResult(cmd, r) {
-  const header = r.timedOut ? `$ ${cmd}
+  const header2 = r.timedOut ? `$ ${cmd}
 [killed after timeout]` : `$ ${cmd}
 [exit ${r.exitCode ?? "?"}]`;
-  return r.output ? `${header}
-${r.output}` : header;
+  return r.output ? `${header2}
+${r.output}` : header2;
 }
 
 // src/tools/web.ts
@@ -2953,9 +3174,9 @@ function registerWebTools(registry, opts = {}) {
         throw new Error("web_fetch: url must start with http:// or https://");
       }
       const page = await webFetch(args.url, { maxChars: maxFetchChars, signal: ctx?.signal });
-      const header = page.title ? `${page.title}
+      const header2 = page.title ? `${page.title}
 ${page.url}` : page.url;
-      return `${header}
+      return `${header2}
 
 ${page.text}`;
     }
@@ -2975,12 +3196,12 @@ ${i + 1}. ${r.title}`);
 }
 
 // src/env.ts
-import { readFileSync as readFileSync3 } from "fs";
+import { readFileSync as readFileSync4 } from "fs";
 import { resolve as resolve3 } from "path";
 function loadDotenv(path = ".env") {
   let raw;
   try {
-    raw = readFileSync3(resolve3(process.cwd(), path), "utf8");
+    raw = readFileSync4(resolve3(process.cwd(), path), "utf8");
   } catch {
     return;
   }
@@ -2999,7 +3220,7 @@ function loadDotenv(path = ".env") {
 }
 
 // src/transcript.ts
-import { createWriteStream, readFileSync as readFileSync4 } from "fs";
+import { createWriteStream, readFileSync as readFileSync5 } from "fs";
 function recordFromLoopEvent(ev, extra) {
   const rec = {
     ts: (/* @__PURE__ */ new Date()).toISOString(),
@@ -3050,7 +3271,7 @@ function openTranscriptFile(path, meta) {
   return stream;
 }
 function readTranscript(path) {
-  const raw = readFileSync4(path, "utf8");
+  const raw = readFileSync5(path, "utf8");
   return parseTranscript(raw);
 }
 function isPlanStateEmptyShape(s) {
@@ -3784,7 +4005,7 @@ var McpClient = class {
 };
 
 // src/mcp/stdio.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 var StdioTransport = class {
   child;
   queue = [];
@@ -3799,14 +4020,14 @@ var StdioTransport = class {
         opts.command,
         ...(opts.args ?? []).map((a) => quoteArg(a, process.platform === "win32"))
       ].join(" ");
-      this.child = spawn2(line, [], {
+      this.child = spawn3(line, [], {
         env,
         cwd: opts.cwd,
         stdio: ["pipe", "pipe", "inherit"],
         shell: true
       });
     } else {
-      this.child = spawn2(opts.command, opts.args ?? [], {
+      this.child = spawn3(opts.command, opts.args ?? [], {
         env,
         cwd: opts.cwd,
         stdio: ["pipe", "pipe", "inherit"]
@@ -4136,7 +4357,7 @@ async function trySection(load) {
 }
 
 // src/code/edit-blocks.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync5, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync6, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname4, resolve as resolve4 } from "path";
 var BLOCK_RE = /^(\S[^\n]*)\n<{7} SEARCH\n([\s\S]*?)\n?={7}\n([\s\S]*?)\n?>{7} REPLACE/gm;
 function parseEditBlocks(text) {
@@ -4165,7 +4386,7 @@ function applyEditBlock(block, rootDir) {
     };
   }
   const searchEmpty = block.search.length === 0;
-  const exists = existsSync3(absTarget);
+  const exists = existsSync4(absTarget);
   try {
     if (!exists) {
       if (!searchEmpty) {
@@ -4179,7 +4400,7 @@ function applyEditBlock(block, rootDir) {
       writeFileSync3(absTarget, block.replace, "utf8");
       return { path: block.path, status: "created" };
     }
-    const content = readFileSync5(absTarget, "utf8");
+    const content = readFileSync6(absTarget, "utf8");
     if (searchEmpty) {
       return {
         path: block.path,
@@ -4213,12 +4434,12 @@ function snapshotBeforeEdits(blocks, rootDir) {
     if (seen.has(b.path)) continue;
     seen.add(b.path);
     const abs = resolve4(absRoot, b.path);
-    if (!existsSync3(abs)) {
+    if (!existsSync4(abs)) {
       snapshots.push({ path: b.path, prevContent: null });
       continue;
     }
     try {
-      snapshots.push({ path: b.path, prevContent: readFileSync5(abs, "utf8") });
+      snapshots.push({ path: b.path, prevContent: readFileSync6(abs, "utf8") });
     } catch {
       snapshots.push({ path: b.path, prevContent: null });
     }
@@ -4238,7 +4459,7 @@ function restoreSnapshots(snapshots, rootDir) {
     }
     try {
       if (snap.prevContent === null) {
-        if (existsSync3(abs)) unlinkSync2(abs);
+        if (existsSync4(abs)) unlinkSync2(abs);
         return {
           path: snap.path,
           status: "applied",
@@ -4261,9 +4482,9 @@ function sep() {
 }
 
 // src/version.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
-import { homedir as homedir3 } from "os";
-import { dirname as dirname5, join as join4 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+import { homedir as homedir4 } from "os";
+import { dirname as dirname5, join as join5 } from "path";
 import { fileURLToPath } from "url";
 var REGISTRY_URL = "https://registry.npmjs.org/reasonix/latest";
 var LATEST_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
@@ -4272,9 +4493,9 @@ function readPackageVersion() {
   try {
     let dir = dirname5(fileURLToPath(import.meta.url));
     for (let i = 0; i < 6; i++) {
-      const p = join4(dir, "package.json");
-      if (existsSync4(p)) {
-        const pkg = JSON.parse(readFileSync6(p, "utf8"));
+      const p = join5(dir, "package.json");
+      if (existsSync5(p)) {
+        const pkg = JSON.parse(readFileSync7(p, "utf8"));
         if (pkg?.name === "reasonix" && typeof pkg.version === "string") {
           return pkg.version;
         }
@@ -4289,11 +4510,11 @@ function readPackageVersion() {
 }
 var VERSION = readPackageVersion();
 function cachePath(homeDirOverride) {
-  return join4(homeDirOverride ?? homedir3(), ".reasonix", "version-cache.json");
+  return join5(homeDirOverride ?? homedir4(), ".reasonix", "version-cache.json");
 }
 function readCache(homeDirOverride) {
   try {
-    const raw = readFileSync6(cachePath(homeDirOverride), "utf8");
+    const raw = readFileSync7(cachePath(homeDirOverride), "utf8");
     const parsed = JSON.parse(raw);
     if (parsed && typeof parsed.version === "string" && typeof parsed.checkedAt === "number") {
       return parsed;
@@ -4361,8 +4582,134 @@ function isNpxInstall() {
   return false;
 }
 
+// src/usage.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync8, statSync as statSync3 } from "fs";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname6, join as join6 } from "path";
+function defaultUsageLogPath(homeDirOverride) {
+  return join6(homeDirOverride ?? homedir5(), ".reasonix", "usage.jsonl");
+}
+function appendUsage(input) {
+  const record = {
+    ts: input.now ?? Date.now(),
+    session: input.session,
+    model: input.model,
+    promptTokens: input.usage.promptTokens,
+    completionTokens: input.usage.completionTokens,
+    cacheHitTokens: input.usage.promptCacheHitTokens,
+    cacheMissTokens: input.usage.promptCacheMissTokens,
+    costUsd: costUsd(input.model, input.usage),
+    claudeEquivUsd: claudeEquivalentCost(input.usage)
+  };
+  const path = input.path ?? defaultUsageLogPath();
+  try {
+    mkdirSync5(dirname6(path), { recursive: true });
+    appendFileSync2(path, `${JSON.stringify(record)}
+`, "utf8");
+  } catch {
+  }
+  return record;
+}
+function readUsageLog(path = defaultUsageLogPath()) {
+  if (!existsSync6(path)) return [];
+  let raw;
+  try {
+    raw = readFileSync8(path, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const rec = JSON.parse(line);
+      if (isValidRecord(rec)) out.push(rec);
+    } catch {
+    }
+  }
+  return out;
+}
+function isValidRecord(rec) {
+  if (!rec || typeof rec !== "object") return false;
+  const r = rec;
+  return typeof r.ts === "number" && typeof r.model === "string" && typeof r.promptTokens === "number" && typeof r.completionTokens === "number" && typeof r.cacheHitTokens === "number" && typeof r.cacheMissTokens === "number" && typeof r.costUsd === "number" && typeof r.claudeEquivUsd === "number";
+}
+function bucketCacheHitRatio(b) {
+  const denom = b.cacheHitTokens + b.cacheMissTokens;
+  return denom > 0 ? b.cacheHitTokens / denom : 0;
+}
+function bucketSavingsFraction(b) {
+  return b.claudeEquivUsd > 0 ? 1 - b.costUsd / b.claudeEquivUsd : 0;
+}
+function emptyBucket(label, since) {
+  return {
+    label,
+    since,
+    turns: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    cacheHitTokens: 0,
+    cacheMissTokens: 0,
+    costUsd: 0,
+    claudeEquivUsd: 0
+  };
+}
+function addToBucket(b, r) {
+  b.turns += 1;
+  b.promptTokens += r.promptTokens;
+  b.completionTokens += r.completionTokens;
+  b.cacheHitTokens += r.cacheHitTokens;
+  b.cacheMissTokens += r.cacheMissTokens;
+  b.costUsd += r.costUsd;
+  b.claudeEquivUsd += r.claudeEquivUsd;
+}
+function aggregateUsage(records, opts = {}) {
+  const now = opts.now ?? Date.now();
+  const day = 24 * 60 * 60 * 1e3;
+  const today = emptyBucket("today", now - day);
+  const week = emptyBucket("week", now - 7 * day);
+  const month = emptyBucket("month", now - 30 * day);
+  const all = emptyBucket("all-time", 0);
+  const modelCounts = /* @__PURE__ */ new Map();
+  const sessionCounts = /* @__PURE__ */ new Map();
+  let firstSeen = null;
+  let lastSeen = null;
+  for (const r of records) {
+    addToBucket(all, r);
+    if (r.ts >= today.since) addToBucket(today, r);
+    if (r.ts >= week.since) addToBucket(week, r);
+    if (r.ts >= month.since) addToBucket(month, r);
+    modelCounts.set(r.model, (modelCounts.get(r.model) ?? 0) + 1);
+    const sessKey = r.session ?? "(ephemeral)";
+    sessionCounts.set(sessKey, (sessionCounts.get(sessKey) ?? 0) + 1);
+    if (firstSeen === null || r.ts < firstSeen) firstSeen = r.ts;
+    if (lastSeen === null || r.ts > lastSeen) lastSeen = r.ts;
+  }
+  const byModel = Array.from(modelCounts.entries()).map(([model, turns]) => ({ model, turns })).sort((a, b) => b.turns - a.turns);
+  const bySession = Array.from(sessionCounts.entries()).map(([session, turns]) => ({ session, turns })).sort((a, b) => b.turns - a.turns);
+  return {
+    buckets: [today, week, month, all],
+    byModel,
+    bySession,
+    firstSeen,
+    lastSeen
+  };
+}
+function formatLogSize(path = defaultUsageLogPath()) {
+  if (!existsSync6(path)) return "";
+  try {
+    const s = statSync3(path);
+    const bytes = s.size;
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  } catch {
+    return "";
+  }
+}
+
 // src/cli/commands/chat.tsx
-import { existsSync as existsSync5, statSync as statSync3 } from "fs";
+import { existsSync as existsSync8, statSync as statSync4 } from "fs";
 import { render } from "ink";
 import React15, { useState as useState7 } from "react";
 
@@ -4401,7 +4748,7 @@ function registerSkillTools(registry, opts = {}) {
         });
       }
       const rawArgs = typeof args.arguments === "string" ? args.arguments.trim() : "";
-      const header = [
+      const header2 = [
         `# Skill: ${skill.name}`,
         skill.description ? `> ${skill.description}` : "",
         `(scope: ${skill.scope} \xB7 ${skill.path})`
@@ -4409,7 +4756,7 @@ function registerSkillTools(registry, opts = {}) {
       const argsBlock = rawArgs ? `
 
 Arguments: ${rawArgs}` : "";
-      return `${header}
+      return `${header2}
 
 ${skill.body}${argsBlock}`;
     }
@@ -4638,7 +4985,7 @@ function parseBlocks(raw) {
       if (/^\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(next)) {
         flushPara();
         flushList();
-        const header = splitTableRow(line);
+        const header2 = splitTableRow(line);
         const rows = [];
         let j = i + 2;
         while (j < lines.length) {
@@ -4647,7 +4994,7 @@ function parseBlocks(raw) {
           rows.push(splitTableRow(r));
           j++;
         }
-        out.push({ kind: "table", header, rows });
+        out.push({ kind: "table", header: header2, rows });
         i = j - 1;
         continue;
       }
@@ -4714,7 +5061,7 @@ function TableBlockRow({ block }) {
     for (const r of block.rows) cellLengths.push(displayWidth(r[c] ?? ""));
     widths.push(Math.min(40, Math.max(3, ...cellLengths)));
   }
-  const pad2 = (s, w) => {
+  const pad3 = (s, w) => {
     const dw = displayWidth(s);
     if (dw >= w) return s;
     return s + " ".repeat(w - dw);
@@ -4722,12 +5069,12 @@ function TableBlockRow({ block }) {
   const separator = widths.map((w) => "\u2500".repeat(w)).join("\u2500\u253C\u2500");
   return /* @__PURE__ */ React2.createElement(Box2, { flexDirection: "column" }, /* @__PURE__ */ React2.createElement(Box2, null, block.header.map((cell, ci) => (
     // biome-ignore lint/suspicious/noArrayIndexKey: table columns never reorder — derived from a static header array
-    /* @__PURE__ */ React2.createElement(Text2, { key: `h-${ci}`, bold: true, color: "cyan" }, pad2(cell, widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
+    /* @__PURE__ */ React2.createElement(Text2, { key: `h-${ci}`, bold: true, color: "cyan" }, pad3(cell, widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
   ))), /* @__PURE__ */ React2.createElement(Text2, { dimColor: true }, separator), block.rows.map((row2, ri) => (
     // biome-ignore lint/suspicious/noArrayIndexKey: table rows render in source order and don't reorder
     /* @__PURE__ */ React2.createElement(Box2, { key: `r-${ri}` }, Array.from({ length: colCount }).map((_, ci) => (
       // biome-ignore lint/suspicious/noArrayIndexKey: same — column axis is fixed by the table shape
-      /* @__PURE__ */ React2.createElement(Text2, { key: `c-${ri}-${ci}` }, pad2(row2[ci] ?? "", widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
+      /* @__PURE__ */ React2.createElement(Text2, { key: `c-${ri}-${ci}` }, pad3(row2[ci] ?? "", widths[ci] ?? 3), ci < colCount - 1 ? " \u2502 " : "")
     )))
   )));
 }
@@ -5372,6 +5719,114 @@ function formatTokens(n) {
 
 // src/cli/ui/slash.ts
 import { spawnSync } from "child_process";
+
+// src/cli/commands/stats.ts
+import { existsSync as existsSync7, readFileSync as readFileSync9 } from "fs";
+function statsCommand(opts) {
+  if (opts.transcript) {
+    transcriptSummary(opts.transcript);
+    return;
+  }
+  dashboard(opts);
+}
+function transcriptSummary(path) {
+  if (!existsSync7(path)) {
+    console.error(`no such transcript: ${path}`);
+    process.exit(1);
+  }
+  const lines = readFileSync9(path, "utf8").split(/\r?\n/).filter(Boolean);
+  let assistantTurns = 0;
+  let toolCalls = 0;
+  let lastTurn = 0;
+  for (const line of lines) {
+    try {
+      const rec = JSON.parse(line);
+      if (rec.role === "assistant_final") assistantTurns++;
+      if (rec.role === "tool") toolCalls++;
+      if (typeof rec.turn === "number") lastTurn = Math.max(lastTurn, rec.turn);
+    } catch {
+    }
+  }
+  console.log(`transcript:       ${path}`);
+  console.log(`assistant turns:  ${assistantTurns}`);
+  console.log(`tool invocations: ${toolCalls}`);
+  console.log(`last turn index:  ${lastTurn}`);
+}
+function dashboard(opts) {
+  const path = opts.logPath ?? defaultUsageLogPath();
+  const records = readUsageLog(path);
+  if (records.length === 0) {
+    console.log("no usage data yet.");
+    console.log("");
+    console.log(`  ${path}`);
+    console.log("");
+    console.log("run `reasonix chat`, `reasonix code`, or `reasonix run <task>` \u2014 every turn");
+    console.log("appends one line to the log and `reasonix stats` will roll it up.");
+    return;
+  }
+  const agg = aggregateUsage(records, { now: opts.now });
+  console.log(renderDashboard(agg, path));
+}
+function renderDashboard(agg, logPath) {
+  const lines = [];
+  const size = formatLogSize(logPath);
+  lines.push(`Reasonix usage \u2014 ${logPath}${size ? ` (${size})` : ""}`);
+  lines.push("");
+  lines.push(header());
+  lines.push(divider());
+  for (const b of agg.buckets) {
+    lines.push(bucketRow(b));
+  }
+  lines.push("");
+  if (agg.byModel.length > 0) {
+    const totalTurns = agg.buckets[agg.buckets.length - 1]?.turns ?? 0;
+    const top = agg.byModel[0];
+    if (top && totalTurns > 0) {
+      const pct2 = (top.turns / totalTurns * 100).toFixed(0);
+      lines.push(`most used model:   ${top.model} (${pct2}% of turns)`);
+    }
+  }
+  if (agg.bySession.length > 0) {
+    const top = agg.bySession[0];
+    if (top) lines.push(`top session:       ${top.session} (${top.turns} turns)`);
+  }
+  if (agg.firstSeen) {
+    lines.push(`tracked since:     ${new Date(agg.firstSeen).toISOString().slice(0, 10)}`);
+  }
+  return lines.join("\n");
+}
+function header() {
+  return [
+    pad("", 10),
+    pad("turns", 8, "right"),
+    pad("cache hit", 10, "right"),
+    pad("cost (USD)", 14, "right"),
+    pad("vs Claude", 14, "right"),
+    pad("saved", 10, "right")
+  ].join("  ");
+}
+function divider() {
+  return "-".repeat(70);
+}
+function bucketRow(b) {
+  const hit = bucketCacheHitRatio(b);
+  const savings = bucketSavingsFraction(b);
+  return [
+    pad(b.label, 10),
+    pad(b.turns.toString(), 8, "right"),
+    pad(b.turns > 0 ? `${(hit * 100).toFixed(1)}%` : "\u2014", 10, "right"),
+    pad(b.turns > 0 ? `$${b.costUsd.toFixed(6)}` : "\u2014", 14, "right"),
+    pad(b.turns > 0 ? `$${b.claudeEquivUsd.toFixed(4)}` : "\u2014", 14, "right"),
+    pad(b.turns > 0 && savings > 0 ? `${(savings * 100).toFixed(1)}%` : "\u2014", 10, "right")
+  ].join("  ");
+}
+function pad(s, width, align = "left") {
+  if (s.length >= width) return s;
+  const fill = " ".repeat(width - s.length);
+  return align === "right" ? `${fill}${s}` : `${s}${fill}`;
+}
+
+// src/cli/ui/slash.ts
 var SLASH_COMMANDS = [
   { cmd: "help", summary: "show the full command reference" },
   { cmd: "status", summary: "current model, flags, context, session" },
@@ -5395,6 +5850,19 @@ var SLASH_COMMANDS = [
     argsHint: "[list|show <name>|<name> [args]]",
     summary: "list / run user skills (<project>/.reasonix/skills + ~/.reasonix/skills)"
   },
+  {
+    cmd: "hooks",
+    argsHint: "[reload]",
+    summary: "list active hooks (settings.json under .reasonix/) \xB7 reload re-reads from disk"
+  },
+  {
+    cmd: "update",
+    summary: "show current vs latest version + the shell command to upgrade"
+  },
+  {
+    cmd: "stats",
+    summary: "cross-session cost dashboard (today / week / month / all-time \xB7 cache hit \xB7 vs Claude)"
+  },
   { cmd: "think", summary: "dump the last turn's full R1 reasoning (reasoner only)" },
   { cmd: "retry", summary: "truncate & resend your last message (fresh sample)" },
   { cmd: "compact", argsHint: "[cap]", summary: "shrink oversized tool results in the log" },
@@ -5568,6 +6036,16 @@ function handleSlash(cmd, args, loop, ctx = {}) {
     case "skills": {
       return handleSkillSlash(args, ctx);
     }
+    case "hook":
+    case "hooks": {
+      return handleHooksSlash(args, loop, ctx);
+    }
+    case "update": {
+      return handleUpdateSlash(ctx);
+    }
+    case "stats": {
+      return handleStatsSlash();
+    }
     case "think":
     case "reasoning": {
       const raw = loop.scratch.reasoning;
@@ -5804,6 +6282,111 @@ ${entry.text}`
       return { unknown: true, info: `unknown command: /${cmd}  (try /help)` };
   }
 }
+function handleStatsSlash() {
+  const path = defaultUsageLogPath();
+  const records = readUsageLog(path);
+  if (records.length === 0) {
+    return {
+      info: [
+        "no usage data yet.",
+        "",
+        `  ${path}`,
+        "",
+        "every turn you run here appends one record \u2014 this session's turns",
+        "will show up in the dashboard once you send a message."
+      ].join("\n")
+    };
+  }
+  const agg = aggregateUsage(records);
+  return { info: renderDashboard(agg, path) };
+}
+function handleUpdateSlash(ctx) {
+  const latest = ctx.latestVersion ?? null;
+  const lines = [`current: reasonix ${VERSION}`];
+  if (latest === null) {
+    ctx.refreshLatestVersion?.();
+    lines.push(
+      "latest:  (not yet resolved \u2014 background check in flight or offline)",
+      "",
+      "triggered a fresh registry fetch \u2014 retry `/update` in a few seconds,",
+      "or run `reasonix update` in another terminal to force it synchronously."
+    );
+    return { info: lines.join("\n") };
+  }
+  lines.push(`latest:  reasonix ${latest}`);
+  const diff = compareVersions(VERSION, latest);
+  if (diff >= 0) {
+    lines.push("", "you're on the latest. nothing to do.");
+    return { info: lines.join("\n") };
+  }
+  if (isNpxInstall()) {
+    lines.push(
+      "",
+      "you're running via npx \u2014 the next `npx reasonix ...` launch will auto-fetch.",
+      "to force a refresh sooner: `npm cache clean --force`."
+    );
+  } else {
+    lines.push(
+      "",
+      "to upgrade, exit this session and run:",
+      "  reasonix update           (interactive, dry-run supported via --dry-run)",
+      "  npm install -g reasonix@latest   (direct)",
+      "",
+      "in-session install is deliberately disabled \u2014 the npm spawn would",
+      "corrupt this TUI's rendering and Windows can lock the running binary."
+    );
+  }
+  return { info: lines.join("\n") };
+}
+function handleHooksSlash(args, loop, ctx) {
+  const sub = (args[0] ?? "").toLowerCase();
+  if (sub === "reload") {
+    if (!ctx.reloadHooks) {
+      return {
+        info: "/hooks reload is not available in this context (no reload callback wired)."
+      };
+    }
+    const count = ctx.reloadHooks();
+    return { info: `\u25B8 reloaded hooks \xB7 ${count} active` };
+  }
+  if (sub !== "" && sub !== "list" && sub !== "ls") {
+    return {
+      info: "usage: /hooks            list active hooks\n       /hooks reload     re-read settings.json files"
+    };
+  }
+  const hooks = loop.hooks;
+  const projPath = ctx.codeRoot ? projectSettingsPath(ctx.codeRoot) : void 0;
+  const globPath = globalSettingsPath();
+  if (hooks.length === 0) {
+    const lines2 = [
+      "no hooks configured.",
+      "",
+      "drop a settings.json with a `hooks` key into either of:",
+      ctx.codeRoot ? `  \xB7 ${projPath} (project)` : "  \xB7 <project>/.reasonix/settings.json (project)",
+      `  \xB7 ${globPath} (global)`,
+      "",
+      "events: PreToolUse, PostToolUse, UserPromptSubmit, Stop",
+      "exit 0 = pass \xB7 exit 2 = block (Pre*) \xB7 other = warn"
+    ];
+    return { info: lines2.join("\n") };
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const event of HOOK_EVENTS) grouped.set(event, []);
+  for (const h of hooks) grouped.get(h.event)?.push(h);
+  const lines = [`\u25B8 ${hooks.length} hook(s) loaded`];
+  for (const event of HOOK_EVENTS) {
+    const list = grouped.get(event) ?? [];
+    if (list.length === 0) continue;
+    lines.push("", `${event}:`);
+    for (const h of list) {
+      const match = h.match && h.match !== "*" ? ` match=${h.match}` : "";
+      const desc = h.description ? `  \u2014 ${h.description}` : "";
+      lines.push(`  [${h.scope}]${match} ${h.command}${desc}`);
+    }
+  }
+  lines.push("", `sources: project=${projPath ?? "(none \u2014 chat mode)"} \xB7 global=${globPath}`);
+  return { info: lines.join("\n") };
+}
 function handleSkillSlash(args, ctx) {
   const store = new SkillStore({ projectRoot: ctx.codeRoot });
   const sub = (args[0] ?? "").toLowerCase();
@@ -5861,12 +6444,12 @@ function handleSkillSlash(args, ctx) {
     };
   }
   const extra = args.slice(1).join(" ").trim();
-  const header = `# Skill: ${skill.name}${skill.description ? `
+  const header2 = `# Skill: ${skill.name}${skill.description ? `
 > ${skill.description}` : ""}`;
   const argsLine = extra ? `
 
 Arguments: ${extra}` : "";
-  const payload = `${header}
+  const payload = `${header2}
 
 ${skill.body}${argsLine}`;
   return {
@@ -6044,9 +6627,9 @@ function appendSection(lines, label, section) {
 }
 function formatToolList(history) {
   const total = history.length;
-  const header = `Tool calls in this session (${total}, most recent first):`;
+  const header2 = `Tool calls in this session (${total}, most recent first):`;
   const shown = Math.min(total, 10);
-  const lines = [header];
+  const lines = [header2];
   for (let i = 0; i < shown; i++) {
     const entry = history[total - 1 - i];
     if (!entry) continue;
@@ -6129,7 +6712,12 @@ function App({
   const [toolProgress, setToolProgress] = useState5(null);
   const [statusLine, setStatusLine] = useState5(null);
   const [balance, setBalance] = useState5(null);
-  const [updateAvailable, setUpdateAvailable] = useState5(null);
+  const [latestVersion, setLatestVersion] = useState5(null);
+  const updateAvailable = latestVersion && compareVersions(VERSION, latestVersion) < 0 ? latestVersion : null;
+  const [hookList, setHookList] = useState5(
+    () => loadHooks({ projectRoot: codeMode?.rootDir })
+  );
+  const hookCwd = codeMode?.rootDir ?? process.cwd();
   const lastEditSnapshots = useRef2(null);
   const pendingEdits = useRef2([]);
   const [pendingShell, setPendingShell] = useState5(null);
@@ -6185,10 +6773,23 @@ function App({
       system,
       toolSpecs: tools?.specs()
     });
-    const l = new CacheFirstLoop({ client, prefix, tools, model, harvest: harvest2, branch, session });
+    const l = new CacheFirstLoop({
+      client,
+      prefix,
+      tools,
+      model,
+      harvest: harvest2,
+      branch,
+      session,
+      hooks: hookList,
+      hookCwd
+    });
     loopRef.current = l;
     return l;
   }, [model, system, harvest2, branch, session, tools]);
+  useEffect2(() => {
+    loop.hooks = hookList;
+  }, [loop, hookList]);
   useEffect2(() => {
     let cancelled = false;
     void (async () => {
@@ -6206,7 +6807,7 @@ function App({
     void (async () => {
       const latest = await getLatestVersion();
       if (cancelled || !latest) return;
-      if (compareVersions(VERSION, latest) < 0) setUpdateAvailable(latest);
+      setLatestVersion(latest);
     })();
     return () => {
       cancelled = true;
@@ -6383,7 +6984,19 @@ function App({
           memoryRoot: codeMode?.rootDir ?? process.cwd(),
           planMode,
           setPlanMode: codeMode ? togglePlanMode : void 0,
-          clearPendingPlan: codeMode ? clearPendingPlan : void 0
+          clearPendingPlan: codeMode ? clearPendingPlan : void 0,
+          reloadHooks: () => {
+            const fresh = loadHooks({ projectRoot: codeMode?.rootDir });
+            setHookList(fresh);
+            return fresh.length;
+          },
+          latestVersion,
+          refreshLatestVersion: () => {
+            void (async () => {
+              const fresh = await getLatestVersion({ force: true });
+              if (fresh) setLatestVersion(fresh);
+            })();
+          }
         });
         if (result.exit) {
           transcriptRef.current?.end();
@@ -6421,6 +7034,23 @@ function App({
           return;
         }
       }
+      if (hookList.some((h) => h.event === "UserPromptSubmit")) {
+        const promptReport = await runHooks({
+          hooks: hookList,
+          payload: { event: "UserPromptSubmit", cwd: hookCwd, prompt: text }
+        });
+        if (promptReport.outcomes.length > 0) {
+          setHistorical((prev) => [
+            ...prev,
+            ...promptReport.outcomes.filter((o) => o.decision !== "pass").map((o) => ({
+              id: `hp-${Date.now()}-${Math.random()}`,
+              role: "warning",
+              text: formatHookOutcomeMessage(o)
+            }))
+          ]);
+        }
+        if (promptReport.blocked) return;
+      }
       promptHistory.current.push(text);
       setHistorical((prev) => [...prev, { id: `u-${Date.now()}`, role: "user", text }]);
       const assistantId = `a-${Date.now()}`;
@@ -6493,6 +7123,13 @@ function App({
             const repairNote = ev.repair ? describeRepair(ev.repair) : "";
             setStreaming(null);
             setSummary(loop.stats.summary());
+            if (ev.stats?.usage) {
+              appendUsage({
+                session: session ?? null,
+                model: ev.stats.model,
+                usage: ev.stats.usage
+              });
+            }
             const finalText = ev.content || streamRef.text;
             const iterReasoning = streamRef.reasoning || void 0;
             const iterId = `${assistantId}-i${assistantIterCounter.current++}`;
@@ -6581,6 +7218,28 @@ function App({
           }
         }
         flush();
+        if (hookList.some((h) => h.event === "Stop")) {
+          const stopReport = await runHooks({
+            hooks: hookList,
+            payload: {
+              event: "Stop",
+              cwd: hookCwd,
+              lastAssistantText: streamRef.text,
+              turn: loop.stats.summary().turns
+            }
+          });
+          for (const o of stopReport.outcomes) {
+            if (o.decision === "pass") continue;
+            setHistorical((prev) => [
+              ...prev,
+              {
+                id: `hs-${Date.now()}-${Math.random()}`,
+                role: "warning",
+                text: formatHookOutcomeMessage(o)
+              }
+            ]);
+          }
+        }
       } finally {
         if (timer) clearInterval(timer);
         setStreaming(null);
@@ -6606,10 +7265,14 @@ function App({
       codeMode,
       codeUndo,
       exit,
+      hookCwd,
+      hookList,
       loop,
+      latestVersion,
       mcpSpecs,
       mcpServers,
       planMode,
+      session,
       slashSelected,
       togglePlanMode,
       writeTranscript
@@ -6872,8 +7535,8 @@ function formatEditResults(results) {
   });
   const ok = results.filter((r) => r.status === "applied" || r.status === "created").length;
   const total = results.length;
-  const header = `\u25B8 edit blocks: ${ok}/${total} applied \u2014 /undo to roll back, or \`git diff\` to review`;
-  return [header, ...lines].join("\n");
+  const header2 = `\u25B8 edit blocks: ${ok}/${total} applied \u2014 /undo to roll back, or \`git diff\` to review`;
+  return [header2, ...lines].join("\n");
 }
 function formatPendingPreview(blocks) {
   const lines = blocks.map((b) => {
@@ -6882,8 +7545,8 @@ function formatPendingPreview(blocks) {
     const tag = b.search === "" ? "NEW " : "    ";
     return `  ${tag}${b.path}  (-${removed} +${added} lines)`;
   });
-  const header = `\u25B8 ${blocks.length} pending edit block(s) \u2014 /apply (or y) to commit \xB7 /discard (or n) to drop`;
-  return [header, ...lines].join("\n");
+  const header2 = `\u25B8 ${blocks.length} pending edit block(s) \u2014 /apply (or y) to commit \xB7 /discard (or n) to drop`;
+  return [header2, ...lines].join("\n");
 }
 function countLines2(s) {
   if (s.length === 0) return 0;
@@ -7128,7 +7791,7 @@ async function chatCommand(opts) {
     const prior = loadSessionMessages(opts.session);
     if (prior.length > 0) {
       const p = sessionPath(opts.session);
-      const mtime = existsSync5(p) ? statSync3(p).mtime : /* @__PURE__ */ new Date();
+      const mtime = existsSync8(p) ? statSync4(p).mtime : /* @__PURE__ */ new Date();
       sessionPreview = { messageCount: prior.length, lastActive: mtime };
     }
   } else if (opts.session && opts.forceNew) {
@@ -7471,7 +8134,7 @@ function mcpListCommand(opts) {
   console.log("Popular MCP servers you can bridge into Reasonix:");
   console.log("");
   for (const entry of MCP_CATALOG) {
-    console.log(`  ${pad(entry.name, 12)} ${entry.summary}`);
+    console.log(`  ${pad2(entry.name, 12)} ${entry.summary}`);
     console.log(`               ${mcpCommandFor(entry)}`);
     if (entry.note) console.log(`               \xB7 ${entry.note}`);
     console.log("");
@@ -7484,7 +8147,7 @@ function mcpListCommand(opts) {
     "        https://mcp.so                                   \u2014  community-maintained catalog"
   );
 }
-function pad(s, width) {
+function pad2(s, width) {
   return s.length >= width ? s : s + " ".repeat(width - s.length);
 }
 
@@ -7753,6 +8416,9 @@ async function runCommand2(opts) {
 [error] ${ev.error}
 `);
       if (ev.role === "done") process.stdout.write("\n");
+      if (ev.role === "assistant_final" && ev.stats?.usage) {
+        appendUsage({ session: null, model: ev.stats.model, usage: ev.stats.usage });
+      }
       if (transcriptStream && ev.role !== "assistant_delta") {
         writeRecord(transcriptStream, recordFromLoopEvent(ev, { model: opts.model, prefixHash }));
       }
@@ -8149,34 +8815,8 @@ async function setupCommand(_opts = {}) {
   await waitUntilExit();
 }
 
-// src/cli/commands/stats.ts
-import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
-function statsCommand(opts) {
-  if (!existsSync6(opts.transcript)) {
-    console.error(`no such transcript: ${opts.transcript}`);
-    process.exit(1);
-  }
-  const lines = readFileSync7(opts.transcript, "utf8").split(/\r?\n/).filter(Boolean);
-  let assistantTurns = 0;
-  let toolCalls = 0;
-  let lastTurn = 0;
-  for (const line of lines) {
-    try {
-      const rec = JSON.parse(line);
-      if (rec.role === "assistant_final") assistantTurns++;
-      if (rec.role === "tool") toolCalls++;
-      if (typeof rec.turn === "number") lastTurn = Math.max(lastTurn, rec.turn);
-    } catch {
-    }
-  }
-  console.log(`transcript:       ${opts.transcript}`);
-  console.log(`assistant turns:  ${assistantTurns}`);
-  console.log(`tool invocations: ${toolCalls}`);
-  console.log(`last turn index:  ${lastTurn}`);
-}
-
 // src/cli/commands/update.ts
-import { spawn as spawn3 } from "child_process";
+import { spawn as spawn4 } from "child_process";
 function planUpdate(input) {
   const diff = compareVersions(input.current, input.latest);
   if (diff > 0) {
@@ -8207,7 +8847,7 @@ function planUpdate(input) {
 }
 function defaultSpawn(argv) {
   return new Promise((resolve6, reject) => {
-    const child = spawn3(argv[0], argv.slice(1), {
+    const child = spawn4(argv[0], argv.slice(1), {
       stdio: "inherit",
       shell: process.platform === "win32"
     });
@@ -8400,7 +9040,9 @@ program.command("run <task>").description("Run a single task non-interactively,
     mcpPrefix: opts.mcpPrefix
   });
 });
-program.command("stats <transcript>").description("Summarize a JSONL transcript produced by `reasonix chat --transcript`.").action((transcript) => {
+program.command("stats [transcript]").description(
+  "Show usage dashboard (today / week / month / all-time \xB7 turns \xB7 cache hit \xB7 cost \xB7 savings vs Claude). Pass a transcript path to fall back to the per-file summary (assistant turns + tool calls)."
+).action((transcript) => {
   statsCommand({ transcript });
 });
 program.command("sessions [name]").description("List saved chat sessions, or inspect one by name.").option("-v, --verbose", "Include system prompts + tool-call metadata when inspecting").action((name, opts) => {