mira-harness 0.2.6 → 0.2.8

package/README.md

@@ -209,6 +209,9 @@ Claude/agent can probe @mira directly via tools.
 | `mira_loop` | `category?`, `max?`, `peer?`, `gapMs?`, `settleMs?`, `timeoutMs?`, `catalogFile?` | run the catalog, **observe-only** (never clicks / spends credits) |
 | `mira_catalog` | `category?`, `catalogFile?` | list the catalog (no network) |
 | `mira_report` | `inFile?`, `category?` | run log → Markdown |
+| `mira_stats` | `inFile?`, `category?` | run-log summary: totals, reply rate, latency, by-category (JSON) |
+| `mira_diff` | `baseline`, `current?` | drift between two run logs (regressions / changes) |
+| `mira_assert` | `inFile?`, `catalogFile?`, `category?` | re-grade a saved run log offline (no network) |
 | `mira_doctor` | — | env / session / connectivity check |
 
 Register it (local build — run `bun run build` first):

package/dist/cli.js

@@ -434,6 +434,9 @@ function clearTitle() {
 // src/commands/report.ts
 import { readFileSync as readFileSync2, writeFileSync } from "node:fs";
 import { resolve as resolve3 } from "node:path";
+function isRunRecord(x) {
+  return typeof x === "object" && x !== null && Array.isArray(x.messages) && typeof x.sent === "string";
+}
 function loadRunRecords(inFile, category) {
   const path = inFile ? resolve3(process.cwd(), inFile) : RUNS_FILE;
   const raw = readFileSync2(path, "utf8");
@@ -444,7 +447,9 @@ function loadRunRecords(inFile, category) {
     if (!t)
       continue;
     try {
-      records.push(JSON.parse(t));
+      const rec = JSON.parse(t);
+      if (isRunRecord(rec))
+        records.push(rec);
     } catch {}
   }
   return category ? records.filter((r) => r.category === category) : records;
@@ -556,6 +561,19 @@ function report(opts) {
 }
 
 // src/commands/assert.ts
+function assertSummary(records, source) {
+  const byId = new Map(source.map((p) => [p.id, p]));
+  const results = [];
+  for (const r of records) {
+    if (!r.probeId)
+      continue;
+    const p = byId.get(r.probeId);
+    if (!p?.expect)
+      continue;
+    results.push({ id: r.probeId, verdict: evaluate(p.expect, r) });
+  }
+  return { graded: results.length, passed: results.filter((g) => g.verdict.ok).length, results };
+}
 function assertLog(opts = {}) {
   let records;
   try {
@@ -570,29 +588,20 @@ function assertLog(opts = {}) {
     process.exit(1);
   }
   const source = opts.catalog ? loadCatalog(opts.catalog) : CATALOG;
-  const byId = new Map(source.map((p) => [p.id, p]));
-  const graded = [];
-  for (const r of records) {
-    if (!r.probeId)
-      continue;
-    const p = byId.get(r.probeId);
-    if (!p?.expect)
-      continue;
-    graded.push({ id: r.probeId, verdict: evaluate(p.expect, r) });
-  }
-  const failed = graded.filter((g) => !g.verdict.ok);
+  const { graded, passed, results } = assertSummary(records, source);
+  const failed = results.filter((g) => !g.verdict.ok);
   if (opts.json) {
-    console.log(JSON.stringify({ graded: graded.length, passed: graded.length - failed.length, results: graded }, null, 2));
+    console.log(JSON.stringify({ graded, passed, results }, null, 2));
     if (failed.length && !opts.noFail)
       process.exit(1);
     return;
   }
   note(c.bold(`assert  ${opts.catalog ?? "(built-in catalog)"} × ${opts.in ?? "(run log)"}`));
-  if (!graded.length) {
+  if (!graded) {
     note(c.dim("  no records matched a probe with `expect` — nothing to grade."));
     return;
   }
-  for (const g of graded) {
+  for (const g of results) {
     note(`  ${g.verdict.ok ? c.green("✓") : c.red("✗")} ${c.cyan(g.id)}`);
     if (!g.verdict.ok) {
       for (const ch of g.verdict.checks.filter((x) => !x.ok))
@@ -600,7 +609,7 @@ function assertLog(opts = {}) {
     }
   }
   note((failed.length ? c.red : c.green)(`
-${graded.length - failed.length}/${graded.length} assertions passed.`));
+${passed}/${graded} assertions passed.`));
   if (failed.length && !opts.noFail)
     process.exit(1);
 }
@@ -867,7 +876,14 @@ function req(name) {
   return v;
 }
 var tgEnv = {
-  apiId: () => Number(req("TG_API_ID")),
+  apiId: () => {
+    const raw = req("TG_API_ID");
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(`TG_API_ID must be a positive integer (got "${raw}") — see .env.example`);
+    }
+    return n;
+  },
   apiHash: () => req("TG_API_HASH"),
   session: () => process.env.TG_SESSION ?? "",
   miraPeer: process.env.MIRA_PEER ?? "mira",
@@ -1325,14 +1341,14 @@ async function send(rawMessage, opts = {}) {
   let verdict;
   try {
     const result = await withProgress(`@${peer}`, () => sendAndCollect(client, peer, message, collect), opts.quiet);
+    if (opts.expect)
+      verdict = evaluate(opts.expect, result);
     if (!opts.noLog)
-      await appendRun(result);
+      await appendRun(result, verdict ? { assert: verdict } : {});
     if (!opts.quiet) {
       note(result.timedOut ? c.yellow("no reply (timed out)") : c.green(`${result.messages.length} message(s) · first reply ${((result.firstReplyMs ?? 0) / 1000).toFixed(1)}s`));
     }
     console.log(JSON.stringify(result, null, 2));
-    if (opts.expect)
-      verdict = evaluate(opts.expect, result);
   } finally {
     await client.disconnect();
   }
@@ -1382,6 +1398,29 @@ function latencyStats(records) {
     max: latencies[latencies.length - 1] ?? 0
   };
 }
+function statsSummary(records) {
+  const replied = records.filter((r) => !r.timedOut);
+  const lat = latencyStats(records);
+  const graded = records.filter((r) => r.assert);
+  const passed = graded.filter((r) => r.assert?.ok);
+  const byCat = new Map;
+  for (const r of records) {
+    const key = r.category ?? "(uncategorized)";
+    const e = byCat.get(key) ?? { total: 0, replied: 0 };
+    e.total += 1;
+    if (!r.timedOut)
+      e.replied += 1;
+    byCat.set(key, e);
+  }
+  return {
+    probes: records.length,
+    replied: replied.length,
+    timedOut: records.length - replied.length,
+    assertions: graded.length ? { graded: graded.length, passed: passed.length } : null,
+    latencyMs: lat.count ? { min: lat.min, median: lat.median, p95: lat.p95, max: lat.max } : null,
+    byCategory: Object.fromEntries([...byCat].map(([k, v]) => [k, v]))
+  };
+}
 function stats(opts = {}) {
   let records;
   try {
@@ -1399,6 +1438,10 @@ function stats(opts = {}) {
     console.error(opts.category ? `no probes in category "${opts.category}" in the run log.` : "run log is empty — run `mira-harness send` or `mira-harness loop` first.");
     process.exit(1);
   }
+  if (opts.json) {
+    console.log(JSON.stringify(statsSummary(records), null, 2));
+    return;
+  }
   const replied = records.filter((r) => !r.timedOut);
   const timedOut = records.length - replied.length;
   const lat = latencyStats(records);
@@ -1414,17 +1457,6 @@ function stats(opts = {}) {
     byCat.set(key, e);
   }
   const series = [...records].sort((a, b) => a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0).filter((r) => !r.timedOut && r.firstReplyMs !== null && r.firstReplyMs > 0).map((r) => r.firstReplyMs);
-  if (opts.json) {
-    console.log(JSON.stringify({
-      probes: records.length,
-      replied: replied.length,
-      timedOut,
-      assertions: graded.length ? { graded: graded.length, passed: passed.length } : null,
-      latencyMs: lat.count ? { min: lat.min, median: lat.median, p95: lat.p95, max: lat.max } : null,
-      byCategory: Object.fromEntries([...byCat].map(([k, v]) => [k, v]))
-    }, null, 2));
-    return;
-  }
   const rate = (n, total) => `${total ? Math.round(n / total * 100) : 0}%`;
   note(c.bold(`\uD83D\uDCCA mira stats${opts.category ? ` [${opts.category}]` : ""}`));
   note(`  ${c.cyan(String(records.length))} probes · ${c.green(`${replied.length} replied`)} · ` + (timedOut ? c.yellow(`${timedOut} timed out`) : c.dim("0 timed out")) + c.dim(`  (${rate(replied.length, records.length)} reply rate)`));
@@ -1634,10 +1666,19 @@ if (process.argv.length <= 2) {
   banner(version);
   console.log(`  Drive @mira from your terminal — QA, learn, and assert on its behavior.
 `);
-  console.log(`  Commands  ${c.cyan("login · doctor · send · loop · catalog · watch")}`);
-  console.log(`            ${c.cyan("report · stats · diff · assert · schema")}
-`);
-  console.log(`  Run ${c.bold("mira-harness --help")} for options + examples, or ${c.bold("mira-harness <command> --help")}.`);
+  console.log(`  ${c.bold("Commands")}`);
+  const cmds = program.commands.filter((cmd) => cmd.name() !== "help");
+  const pad = Math.max(...cmds.map((cmd) => cmd.name().length));
+  for (const cmd of cmds) {
+    console.log(`    ${c.cyan(cmd.name().padEnd(pad))}  ${c.dim(cmd.description())}`);
+  }
+  console.log(`
+  ${c.bold("Quick start")}`);
+  for (const ex of ["login", "doctor", 'send "What can you do?"', "loop --category core"]) {
+    console.log(c.dim(`    $ mira-harness ${ex}`));
+  }
+  console.log(`
+  Run ${c.bold("mira-harness --help")} for all options + examples, or ${c.bold("mira-harness <command> --help")}.`);
   process.exit(0);
 }
 program.parseAsync(process.argv).then(() => process.exit(0)).catch((e) => {

package/dist/commands/report.d.ts

@@ -7,9 +7,9 @@ export type RunRecord = ProbeResult & {
     assert?: Verdict;
 };
 /**
- * Read the JSONL run log into records (malformed lines skipped). Throws ENOENT when
- * the file is absent — callers decide how to surface that. Shared by `report` and
- * `stats` so the two stay in lockstep on the log format.
+ * Read the JSONL run log into records (malformed/wrong-shape lines skipped). Throws
+ * ENOENT when the file is absent — callers decide how to surface that. Shared by
+ * `report` and `stats` so the two stay in lockstep on the log format.
  */
 export declare function loadRunRecords(inFile?: string, category?: string): RunRecord[];
 export declare function buildReport(records: RunRecord[]): string;

package/dist/env.d.ts

@@ -7,6 +7,8 @@
  */
 import "dotenv/config";
 export declare const tgEnv: {
+    /** Telegram api_id — a positive integer. Reject non-numeric/zero up front so
+     *  `doctor` flags a bad value instead of passing NaN into GramJS (cryptic later). */
     apiId: () => number;
     apiHash: () => string;
     /** Empty until `mira-harness login` mints it; required by send/loop. */

package/dist/index.js

@@ -414,7 +414,14 @@ function req(name) {
   return v;
 }
 var tgEnv = {
-  apiId: () => Number(req("TG_API_ID")),
+  apiId: () => {
+    const raw = req("TG_API_ID");
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(`TG_API_ID must be a positive integer (got "${raw}") — see .env.example`);
+    }
+    return n;
+  },
   apiHash: () => req("TG_API_HASH"),
   session: () => process.env.TG_SESSION ?? "",
   miraPeer: process.env.MIRA_PEER ?? "mira",
@@ -596,6 +603,9 @@ async function appendRun(result, meta = {}) {
 }
 
 // src/commands/report.ts
+function isRunRecord(x) {
+  return typeof x === "object" && x !== null && Array.isArray(x.messages) && typeof x.sent === "string";
+}
 function loadRunRecords(inFile, category) {
   const path = inFile ? resolve3(process.cwd(), inFile) : RUNS_FILE;
   const raw = readFileSync2(path, "utf8");
@@ -606,7 +616,9 @@ function loadRunRecords(inFile, category) {
     if (!t)
       continue;
     try {
-      records.push(JSON.parse(t));
+      const rec = JSON.parse(t);
+      if (isRunRecord(rec))
+        records.push(rec);
     } catch {}
   }
   return category ? records.filter((r) => r.category === category) : records;

package/dist/mcp.js

@@ -424,7 +424,14 @@ function req(name) {
   return v;
 }
 var tgEnv = {
-  apiId: () => Number(req("TG_API_ID")),
+  apiId: () => {
+    const raw = req("TG_API_ID");
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(`TG_API_ID must be a positive integer (got "${raw}") — see .env.example`);
+    }
+    return n;
+  },
   apiHash: () => req("TG_API_HASH"),
   session: () => process.env.TG_SESSION ?? "",
   miraPeer: process.env.MIRA_PEER ?? "mira",
@@ -591,9 +598,8 @@ async function subscribe(client, peer, onMessage) {
   };
 }
 
-// src/commands/report.ts
-import { readFileSync as readFileSync2, writeFileSync } from "node:fs";
-import { resolve as resolve3 } from "node:path";
+// src/commands/assert.ts
+import { resolve as resolve4 } from "node:path";
 
 // src/log.ts
 import { appendFile, mkdir } from "node:fs/promises";
@@ -606,7 +612,119 @@ async function appendRun(result, meta = {}) {
 `, "utf8");
 }
 
+// src/ui.ts
+import pc from "picocolors";
+var c = pc;
+function note(msg) {
+  process.stderr.write(`${msg}
+`);
+}
+function center(s, width) {
+  const pad = Math.max(0, width - s.length);
+  const left = Math.floor(pad / 2);
+  return " ".repeat(left) + s + " ".repeat(pad - left);
+}
+function mascot(mood = "neutral") {
+  const faces = {
+    neutral: { top: "*  .  *", eyes: "o   o", mouth: "~" },
+    happy: { top: "*  .  *", eyes: "^   ^", mouth: "\\_/" },
+    sleepy: { top: "z  .  z", eyes: "-   -", mouth: "~" },
+    sad: { top: "       ", eyes: "x   x", mouth: "_" }
+  };
+  const f = faces[mood];
+  return [`     ${f.top}`, "    .-------.", `    | ${f.eyes} |`, `    | ${center(f.mouth, 5)} |`, "    '-------'"];
+}
+var WORDMARK = [
+  " __  __ ___ ____      _",
+  "|  \\/  |_ _|  _ \\    / \\",
+  "| |\\/| || || |_) |  / _ \\",
+  "| |  | || ||  _ <  / ___ \\",
+  "|_|  |_|___|_| \\_\\/_/   \\_\\"
+];
+var TIPS = [
+  'echo "What can you do?" | mira-harness send   — pipe a probe from stdin',
+  "mira-harness loop --list   — preview the probes without sending anything",
+  "touch STOP_MIRA   — instant kill switch; blocks every send until removed",
+  "mira-harness loop --catalog ./my.json   — run your own probe catalog",
+  "mira-harness report --out report.md   — distill the run log into Markdown",
+  "mira-harness stats   — latency records + an ASCII sparkline of your runs",
+  "mira-harness watch   — live-tail @mira while you poke it by hand",
+  "MIRA_NO_BANNER=1 hides this banner · --quiet hides all decoration"
+];
+function banner(version, opts = {}) {
+  if (opts.quiet || process.env.MIRA_NO_BANNER || !process.stderr.isTTY || !process.stdout.isTTY)
+    return;
+  const tip = TIPS[new Date().getDate() % TIPS.length];
+  const lines = [
+    ...mascot("neutral").map((l) => c.magenta(l)),
+    ...WORDMARK.map((l) => c.cyan(l)),
+    c.dim(`mira-harness v${version} · drive @mira from your terminal`),
+    c.dim(`tip: ${tip}`)
+  ];
+  process.stderr.write(`
+${lines.map((l) => `  ${l}`).join(`
+`)}
+
+`);
+}
+var VERBS = [
+  "Summoning",
+  "Consulting the chain",
+  "Poking the bot",
+  "Nudging the oracle",
+  "Pondering",
+  "Channeling TON",
+  "Crunching tokens",
+  "Waiting on a reply"
+];
+var VERBS_SLOW = ["Still pondering", "Deep in thought", "Brewing a big one", "Hang tight", "Almost there"];
+var SLOW_AFTER_MS = 30000;
+var VERB_EVERY_MS = 3500;
+async function withProgress(label, fn, quiet = false) {
+  if (quiet || !process.stderr.isTTY)
+    return fn();
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  const start = Date.now();
+  let i = 0;
+  const timer = setInterval(() => {
+    const elapsed = Date.now() - start;
+    const pool = elapsed >= SLOW_AFTER_MS ? VERBS_SLOW : VERBS;
+    const verb = pool[Math.floor(elapsed / VERB_EVERY_MS) % pool.length];
+    const s = (elapsed / 1000).toFixed(0);
+    process.stderr.write(`\r${pc.cyan(frames[i++ % frames.length])} ${verb} ${pc.dim(`· ${label} · ${s}s`)}  `);
+  }, 100);
+  try {
+    return await fn();
+  } finally {
+    clearInterval(timer);
+    process.stderr.write("\r\x1B[K");
+  }
+}
+function oscSafe(s) {
+  return s.replace(/[\x00-\x1f\x7f]/g, " ").trim();
+}
+function notify(message, opts = {}) {
+  if (opts.quiet || process.env.MIRA_NO_NOTIFY || !process.stderr.isTTY)
+    return;
+  process.stderr.write(`\x1B]9;${oscSafe(message)}\x07`);
+}
+function setTitle(title) {
+  if (process.env.MIRA_NO_TITLE || !process.stderr.isTTY)
+    return;
+  process.stderr.write(`\x1B]0;${oscSafe(title)}\x07`);
+}
+function clearTitle() {
+  if (!process.stderr.isTTY)
+    return;
+  process.stderr.write("\x1B]0;\x07");
+}
+
 // src/commands/report.ts
+import { readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { resolve as resolve3 } from "node:path";
+function isRunRecord(x) {
+  return typeof x === "object" && x !== null && Array.isArray(x.messages) && typeof x.sent === "string";
+}
 function loadRunRecords(inFile, category) {
   const path = inFile ? resolve3(process.cwd(), inFile) : RUNS_FILE;
   const raw = readFileSync2(path, "utf8");
@@ -617,7 +735,9 @@ function loadRunRecords(inFile, category) {
     if (!t)
       continue;
     try {
-      records.push(JSON.parse(t));
+      const rec = JSON.parse(t);
+      if (isRunRecord(rec))
+        records.push(rec);
     } catch {}
   }
   return category ? records.filter((r) => r.category === category) : records;
@@ -682,7 +802,7 @@ function buildReport(records) {
   out.push("");
   out.push(`**${records.length}** probes · **${replied.length}** replied · **${records.length - replied.length}** timed out · ` + (graded.length ? `**${passed.length}/${graded.length}** assertions passed · ` : "") + `first-reply avg **${(avg / 1000).toFixed(1)}s** / max **${(max / 1000).toFixed(1)}s**.`);
   out.push("");
-  const builtin = CATEGORIES.filter((c) => records.some((r) => r.category === c));
+  const builtin = CATEGORIES.filter((c2) => records.some((r) => r.category === c2));
   const custom = [];
   for (const r of records) {
     if (r.category && !CATEGORIES.includes(r.category) && !custom.includes(r.category)) {
@@ -728,6 +848,296 @@ function report(opts) {
   }
 }
 
+// src/commands/assert.ts
+function assertSummary(records, source) {
+  const byId = new Map(source.map((p) => [p.id, p]));
+  const results = [];
+  for (const r of records) {
+    if (!r.probeId)
+      continue;
+    const p = byId.get(r.probeId);
+    if (!p?.expect)
+      continue;
+    results.push({ id: r.probeId, verdict: evaluate(p.expect, r) });
+  }
+  return { graded: results.length, passed: results.filter((g) => g.verdict.ok).length, results };
+}
+function assertLog(opts = {}) {
+  let records;
+  try {
+    records = loadRunRecords(opts.in, opts.category);
+  } catch (e) {
+    if (e?.code === "ENOENT") {
+      const path = opts.in ? resolve4(process.cwd(), opts.in) : RUNS_FILE;
+      console.error(`no run log at ${path} — run \`mira-harness send\` or \`mira-harness loop\` first.`);
+    } else {
+      console.error(e instanceof Error ? e.message : String(e));
+    }
+    process.exit(1);
+  }
+  const source = opts.catalog ? loadCatalog(opts.catalog) : CATALOG;
+  const { graded, passed, results } = assertSummary(records, source);
+  const failed = results.filter((g) => !g.verdict.ok);
+  if (opts.json) {
+    console.log(JSON.stringify({ graded, passed, results }, null, 2));
+    if (failed.length && !opts.noFail)
+      process.exit(1);
+    return;
+  }
+  note(c.bold(`assert  ${opts.catalog ?? "(built-in catalog)"} × ${opts.in ?? "(run log)"}`));
+  if (!graded) {
+    note(c.dim("  no records matched a probe with `expect` — nothing to grade."));
+    return;
+  }
+  for (const g of results) {
+    note(`  ${g.verdict.ok ? c.green("✓") : c.red("✗")} ${c.cyan(g.id)}`);
+    if (!g.verdict.ok) {
+      for (const ch of g.verdict.checks.filter((x) => !x.ok))
+        note(c.dim(`      ✗ ${ch.name}: ${ch.detail}`));
+    }
+  }
+  note((failed.length ? c.red : c.green)(`
+${passed}/${graded} assertions passed.`));
+  if (failed.length && !opts.noFail)
+    process.exit(1);
+}
+
+// src/commands/diff.ts
+import { resolve as resolve5 } from "node:path";
+function lastByProbe(records) {
+  const m = new Map;
+  for (const r of records) {
+    if (r.probeId)
+      m.set(r.probeId, r);
+  }
+  return m;
+}
+function signals2(r) {
+  const buttons = r.messages.reduce((n, m) => n + m.buttons.length, 0);
+  const links = r.messages.reduce((n, m) => n + m.links.length, 0);
+  const media = r.messages.map((m) => m.media?.kind).filter((k) => k !== undefined).join(",");
+  return { buttons, links, media };
+}
+function diffRuns(baseline, current) {
+  const base = lastByProbe(baseline);
+  const cur = lastByProbe(current);
+  const items = [];
+  for (const id of [...new Set([...base.keys(), ...cur.keys()])].sort()) {
+    const b = base.get(id);
+    const c2 = cur.get(id);
+    if (b && !c2) {
+      items.push({ probeId: id, kind: "removed", what: "in baseline, not in current" });
+      continue;
+    }
+    if (c2 && !b) {
+      items.push({ probeId: id, kind: "added", what: "new in current (not in baseline)" });
+      continue;
+    }
+    if (!b || !c2)
+      continue;
+    if (!b.timedOut && c2.timedOut)
+      items.push({ probeId: id, kind: "regression", what: "now times out (was replying)" });
+    else if (b.timedOut && !c2.timedOut)
+      items.push({ probeId: id, kind: "improvement", what: "now replies (was timing out)" });
+    const ba = b.assert;
+    const ca = c2.assert;
+    if (ba && ca && ba.ok !== ca.ok) {
+      if (ba.ok && !ca.ok) {
+        const failed = ca.checks.filter((x) => !x.ok).map((x) => x.name).join(", ");
+        items.push({ probeId: id, kind: "regression", what: `assertion now FAILS (${failed})` });
+      } else {
+        items.push({ probeId: id, kind: "improvement", what: "assertion now passes" });
+      }
+    }
+    if (b.firstReplyMs !== null && c2.firstReplyMs !== null) {
+      const bms = b.firstReplyMs;
+      const cms = c2.firstReplyMs;
+      if (cms > bms * 2 && cms - bms > 5000) {
+        items.push({
+          probeId: id,
+          kind: "regression",
+          what: `first reply ${(bms / 1000).toFixed(1)}s -> ${(cms / 1000).toFixed(1)}s (>2x slower)`
+        });
+      }
+    }
+    const bs = signals2(b);
+    const cs = signals2(c2);
+    if (bs.buttons !== cs.buttons)
+      items.push({ probeId: id, kind: "change", what: `buttons ${bs.buttons} -> ${cs.buttons}` });
+    if (bs.links !== cs.links)
+      items.push({ probeId: id, kind: "change", what: `links ${bs.links} -> ${cs.links}` });
+    if (bs.media !== cs.media)
+      items.push({ probeId: id, kind: "change", what: `media [${bs.media}] -> [${cs.media}]` });
+  }
+  return items;
+}
+function load(path, label) {
+  try {
+    return loadRunRecords(path);
+  } catch (e) {
+    const shown = path ? resolve5(process.cwd(), path) : RUNS_FILE;
+    if (e?.code === "ENOENT")
+      console.error(`${label}: no run log at ${shown}`);
+    else
+      console.error(`${label}: ${e instanceof Error ? e.message : String(e)}`);
+    return null;
+  }
+}
+function diff(opts) {
+  const base = load(opts.baseline, "baseline");
+  const cur = load(opts.current, "current");
+  if (!base || !cur)
+    process.exit(1);
+  if (!base.length)
+    note(c.yellow(`baseline ${opts.baseline} has no records.`));
+  if (!cur.length)
+    note(c.yellow(`current ${opts.current ?? "(run log)"} has no records.`));
+  const items = diffRuns(base, cur);
+  const regressions = items.filter((i) => i.kind === "regression");
+  if (opts.json) {
+    console.log(JSON.stringify({ regressions: regressions.length, drift: items.length, items }, null, 2));
+    if (regressions.length && !opts.noFail)
+      process.exit(1);
+    return;
+  }
+  note(c.bold(`drift  ${opts.baseline} -> ${opts.current ?? "(current run log)"}`));
+  if (!items.length) {
+    note(c.green("  no drift detected."));
+    return;
+  }
+  const paint = {
+    regression: (s) => c.red(s),
+    improvement: (s) => c.green(s),
+    change: (s) => c.dim(s),
+    added: (s) => c.dim(s),
+    removed: (s) => c.dim(s)
+  };
+  for (const i of items) {
+    note(`  ${paint[i.kind](i.kind.padEnd(11))} ${c.cyan(i.probeId)} — ${i.what}`);
+  }
+  note(regressions.length ? c.red(`
+${regressions.length} regression(s).`) : c.green(`
+no regressions.`));
+  if (regressions.length && !opts.noFail)
+    process.exit(1);
+}
+
+// src/commands/stats.ts
+import { resolve as resolve6 } from "node:path";
+var SPARK = "▁▂▃▄▅▆▇█";
+function sparkline(values) {
+  if (!values.length)
+    return "";
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const v of values) {
+    if (v < min)
+      min = v;
+    if (v > max)
+      max = v;
+  }
+  const range = max - min || 1;
+  return values.map((v) => SPARK[Math.min(SPARK.length - 1, Math.floor((v - min) / range * SPARK.length))]).join("");
+}
+function percentile(sortedAsc, p) {
+  if (!sortedAsc.length)
+    return 0;
+  const idx = Math.min(sortedAsc.length - 1, Math.floor(p / 100 * sortedAsc.length));
+  return sortedAsc[idx] ?? 0;
+}
+var secs = (ms) => `${(ms / 1000).toFixed(1)}s`;
+function latencyStats(records) {
+  const latencies = records.filter((r) => !r.timedOut && r.firstReplyMs !== null && r.firstReplyMs > 0).map((r) => r.firstReplyMs).sort((a, b) => a - b);
+  return {
+    count: latencies.length,
+    min: latencies[0] ?? 0,
+    median: percentile(latencies, 50),
+    p95: percentile(latencies, 95),
+    max: latencies[latencies.length - 1] ?? 0
+  };
+}
+function statsSummary(records) {
+  const replied = records.filter((r) => !r.timedOut);
+  const lat = latencyStats(records);
+  const graded = records.filter((r) => r.assert);
+  const passed = graded.filter((r) => r.assert?.ok);
+  const byCat = new Map;
+  for (const r of records) {
+    const key = r.category ?? "(uncategorized)";
+    const e = byCat.get(key) ?? { total: 0, replied: 0 };
+    e.total += 1;
+    if (!r.timedOut)
+      e.replied += 1;
+    byCat.set(key, e);
+  }
+  return {
+    probes: records.length,
+    replied: replied.length,
+    timedOut: records.length - replied.length,
+    assertions: graded.length ? { graded: graded.length, passed: passed.length } : null,
+    latencyMs: lat.count ? { min: lat.min, median: lat.median, p95: lat.p95, max: lat.max } : null,
+    byCategory: Object.fromEntries([...byCat].map(([k, v]) => [k, v]))
+  };
+}
+function stats(opts = {}) {
+  let records;
+  try {
+    records = loadRunRecords(opts.in, opts.category);
+  } catch (e) {
+    if (e?.code === "ENOENT") {
+      const path = opts.in ? resolve6(process.cwd(), opts.in) : RUNS_FILE;
+      console.error(`no run log at ${path} — run \`mira-harness send\` or \`mira-harness loop\` first.`);
+    } else {
+      console.error(e instanceof Error ? e.message : String(e));
+    }
+    process.exit(1);
+  }
+  if (!records.length) {
+    console.error(opts.category ? `no probes in category "${opts.category}" in the run log.` : "run log is empty — run `mira-harness send` or `mira-harness loop` first.");
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(statsSummary(records), null, 2));
+    return;
+  }
+  const replied = records.filter((r) => !r.timedOut);
+  const timedOut = records.length - replied.length;
+  const lat = latencyStats(records);
+  const graded = records.filter((r) => r.assert);
+  const passed = graded.filter((r) => r.assert?.ok);
+  const byCat = new Map;
+  for (const r of records) {
+    const key = r.category ?? "(uncategorized)";
+    const e = byCat.get(key) ?? { total: 0, replied: 0 };
+    e.total += 1;
+    if (!r.timedOut)
+      e.replied += 1;
+    byCat.set(key, e);
+  }
+  const series = [...records].sort((a, b) => a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0).filter((r) => !r.timedOut && r.firstReplyMs !== null && r.firstReplyMs > 0).map((r) => r.firstReplyMs);
+  const rate = (n, total) => `${total ? Math.round(n / total * 100) : 0}%`;
+  note(c.bold(`\uD83D\uDCCA mira stats${opts.category ? ` [${opts.category}]` : ""}`));
+  note(`  ${c.cyan(String(records.length))} probes · ${c.green(`${replied.length} replied`)} · ` + (timedOut ? c.yellow(`${timedOut} timed out`) : c.dim("0 timed out")) + c.dim(`  (${rate(replied.length, records.length)} reply rate)`));
+  if (graded.length) {
+    const allPass = passed.length === graded.length;
+    note(`  ${(allPass ? c.green : c.yellow)(`${passed.length}/${graded.length}`)} assertions passed` + c.dim(`  (${rate(passed.length, graded.length)})`));
+  }
+  if (lat.count) {
+    note("");
+    note(c.bold("  first-reply latency"));
+    note(`    \uD83C\uDFC6 fastest ${c.green(secs(lat.min))}   median ${c.cyan(secs(lat.median))}   ` + `p95 ${c.cyan(secs(lat.p95))}   slowest ${c.yellow(secs(lat.max))}`);
+    if (series.length > 1)
+      note(`    ${c.magenta(sparkline(series))}  ${c.dim(`(${series.length} replies, oldest→newest)`)}`);
+  } else {
+    note(c.dim("  no first-reply times recorded yet."));
+  }
+  note("");
+  note(c.bold("  by category"));
+  for (const [cat, v] of byCat) {
+    note(`    ${c.cyan(cat.padEnd(16))} ${String(v.total).padStart(3)} probes  ${c.dim(`${rate(v.replied, v.total)} replied`)}`);
+  }
+}
+
 // src/version.ts
 import { readFileSync as readFileSync3 } from "node:fs";
 import { dirname as dirname2, join } from "node:path";
@@ -791,7 +1201,7 @@ server.registerTool("mira_send", {
   if (timeoutMs !== undefined)
     collect.firstReplyTimeoutMs = timeoutMs;
   try {
-    const result = await withClient((c) => sendAndCollect(c, tgEnv.miraPeer, message, collect));
+    const result = await withClient((c2) => sendAndCollect(c2, tgEnv.miraPeer, message, collect));
     await appendRun(result);
     return json(result);
   } catch (e) {
@@ -900,6 +1310,64 @@ server.registerTool("mira_report", {
     return errorText(msg(e));
   }
 });
+server.registerTool("mira_stats", {
+  title: "Summarize the run log",
+  description: "Roll the run log up into totals, reply rate, assertion pass count, first-reply latency (min/median/p95/max) and a per-category breakdown. Read-only — sends nothing.",
+  inputSchema: {
+    inFile: z3.string().optional().describe("input JSONL path (default: the run log)"),
+    category: z3.string().optional().describe("only include probes from this category")
+  }
+}, async ({ inFile, category }) => {
+  let records;
+  try {
+    records = loadRunRecords(inFile, category);
+  } catch (e) {
+    return errorText(msg(e));
+  }
+  if (!records.length) {
+    return errorText(category ? `no probes in category "${category}" in the run log.` : "run log is empty — run mira_send or mira_loop first.");
+  }
+  return json(statsSummary(records));
+});
+server.registerTool("mira_diff", {
+  title: "Diff two run logs for @mira drift",
+  description: "Compare two run logs probe-by-probe and report behavioral drift (regressions, improvements, surface changes). Read-only — sends nothing.",
+  inputSchema: {
+    baseline: z3.string().describe("baseline run-log path to compare against"),
+    current: z3.string().optional().describe("current run-log path (default: the run log)")
+  }
+}, async ({ baseline, current }) => {
+  let base;
+  let cur;
+  try {
+    base = loadRunRecords(baseline);
+    cur = loadRunRecords(current);
+  } catch (e) {
+    return errorText(msg(e));
+  }
+  const items = diffRuns(base, cur);
+  const regressions = items.filter((i) => i.kind === "regression").length;
+  return json({ regressions, drift: items.length, items });
+});
+server.registerTool("mira_assert", {
+  title: "Re-grade a run log offline",
+  description: "Re-apply a catalog's `expect` assertions to a SAVED run log (no network) and return per-probe verdicts plus a pass count. Read-only — sends nothing.",
+  inputSchema: {
+    inFile: z3.string().optional().describe("input JSONL path (default: the run log)"),
+    catalogFile: z3.string().optional().describe("custom catalog JSON file (default: the built-in catalog)"),
+    category: z3.string().optional().describe("only include probes from this category")
+  }
+}, async ({ inFile, catalogFile, category }) => {
+  let records;
+  let source;
+  try {
+    records = loadRunRecords(inFile, category);
+    source = catalogFile ? loadCatalog(catalogFile) : CATALOG;
+  } catch (e) {
+    return errorText(msg(e));
+  }
+  return json(assertSummary(records, source));
+});
 server.registerTool("mira_doctor", {
   title: "Preflight checks",
   description: "Check env, session, connectivity and @mira resolution (read-only — sends nothing)."

package/llms.txt

@@ -35,6 +35,9 @@ A second frontend over the same core, for agents. Tools:
 - `mira_loop` { category?, max?, peer?, gapMs?, settleMs?, timeoutMs?, catalogFile? } — run the catalog, **observe-only** (never clicks / spends credits).
 - `mira_catalog` { category?, catalogFile? } — list the catalog (no network).
 - `mira_report` { inFile?, category? } — run log → Markdown.
+- `mira_stats` { inFile?, category? } — run-log summary: totals, reply rate, latency, by-category (JSON, no network).
+- `mira_diff` { baseline, current? } — drift between two run logs: regressions / changes (JSON, no network).
+- `mira_assert` { inFile?, catalogFile?, category? } — re-grade a saved run log against the catalog's `expect` (JSON, no network).
 - `mira_doctor` — env / session / connectivity check (no arguments).
 Credentials come from the MCP `env` block or a `.env` in the server's cwd.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mira-harness",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "A CLI + MCP dev-tool for communicating with the @mira Telegram bot — capture its full reply (buttons/links/media) and run a self-driving experiment catalog.",
   "type": "module",
   "bin": {