mira-harness 0.2.3 → 0.2.5

package/README.md

@@ -101,12 +101,14 @@ a "typing…" fallback for a slow bot — replies run 5–62s) and capture, per
 | `login` | One-time interactive login → prints `TG_SESSION` |
 | `doctor` | Check `.env` / session / connectivity / @mira resolution (read-only) |
 | `send [message...]` | One probe → full reply as JSON (message via arg or stdin). `--quiet --settle --timeout --no-log` |
-| `loop` | Run the catalog paced; grades `expect` probes (exit 1 on failure). `--category --max --confirm --peer --gap --settle --timeout --list --catalog --no-fail --quiet` |
+| `loop` | Run the catalog paced; grades `expect` probes (exit 1 on failure). `--category --max --confirm --peer --gap --settle --timeout --list --catalog --grep --no-fail --quiet` |
 | `catalog` | List the catalog (no sends). `--category --catalog --json` |
 | `watch` | Live-tail @mira's messages (observe-only). `--peer` |
 | `report` | Distill the run log into Markdown. `--in --out --category` |
 | `stats` | At-a-glance dashboard: totals, latency records, sparkline. `--in --category --json` |
 | `diff` | Compare two run logs for @mira behavioral drift (exit 1 on a regression). `--json --no-fail` |
+| `assert` | Re-grade a saved run log against a catalog's `expect`, offline (exit 1 on failure). `--in --catalog --category --json --no-fail` |
+| `schema` | Print the JSON Schema for a custom catalog file (editor autocomplete / validation). `--out` |
 
 Run `mira-harness --help` (or `<command> --help`) for full options.
 
@@ -160,6 +162,11 @@ Give a probe an optional `expect` block and `loop` grades it ✓/✗. The checks
 Probes without `expect` stay observe-only (informational). `loop` **exits non-zero** if any
 graded probe fails — so it drops straight into CI. Add `--no-fail` to report without failing.
 
+`assert` re-grades a **saved** run log against the catalog's `expect` (offline, no @mira) — the
+fast loop for *developing* assertions (capture once, then tune `expect` and re-grade instantly),
+and a way to gate a committed run-log fixture in CI **without a Telegram session**. Run a subset
+of probes by id with `loop --grep <regex>`; emit a catalog JSON Schema for your editor with `schema`.
+
 ### Drift detection
 
 `diff` compares two run logs and flags how @mira's behavior **changed** (structural, not

package/dist/catalog.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { type Expect } from "./assert.js";
 /** Built-in categories. Custom catalogs may use any category string. */
 export type ProbeCategory = "core" | "skills" | "generation" | "wallet";
@@ -20,6 +21,59 @@ export interface Probe {
     expect?: Expect;
 }
 export declare const CATEGORIES: ProbeCategory[];
+export declare const ProbeSchema: z.ZodObject<{
+    id: z.ZodString;
+    category: z.ZodDefault<z.ZodString>;
+    hypothesis: z.ZodDefault<z.ZodString>;
+    send: z.ZodString;
+    slow: z.ZodOptional<z.ZodBoolean>;
+    confirm: z.ZodOptional<z.ZodBoolean>;
+    note: z.ZodOptional<z.ZodString>;
+    expect: z.ZodOptional<z.ZodObject<{
+        replies: z.ZodOptional<z.ZodBoolean>;
+        textMatches: z.ZodOptional<z.ZodString>;
+        minButtons: z.ZodOptional<z.ZodNumber>;
+        minLinks: z.ZodOptional<z.ZodNumber>;
+        hasWebApp: z.ZodOptional<z.ZodBoolean>;
+        media: z.ZodOptional<z.ZodEnum<{
+            photo: "photo";
+            video: "video";
+            audio: "audio";
+            document: "document";
+            webpage: "webpage";
+            other: "other";
+        }>>;
+        maxFirstReplyMs: z.ZodOptional<z.ZodNumber>;
+        json: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** A whole catalog file = an array of probes. */
+export declare const CatalogSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    category: z.ZodDefault<z.ZodString>;
+    hypothesis: z.ZodDefault<z.ZodString>;
+    send: z.ZodString;
+    slow: z.ZodOptional<z.ZodBoolean>;
+    confirm: z.ZodOptional<z.ZodBoolean>;
+    note: z.ZodOptional<z.ZodString>;
+    expect: z.ZodOptional<z.ZodObject<{
+        replies: z.ZodOptional<z.ZodBoolean>;
+        textMatches: z.ZodOptional<z.ZodString>;
+        minButtons: z.ZodOptional<z.ZodNumber>;
+        minLinks: z.ZodOptional<z.ZodNumber>;
+        hasWebApp: z.ZodOptional<z.ZodBoolean>;
+        media: z.ZodOptional<z.ZodEnum<{
+            photo: "photo";
+            video: "video";
+            audio: "audio";
+            document: "document";
+            webpage: "webpage";
+            other: "other";
+        }>>;
+        maxFirstReplyMs: z.ZodOptional<z.ZodNumber>;
+        json: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
 /**
  * Load a custom probe catalog from a JSON file (an array of probe objects).
  * Throws a clear error on a missing file or an entry that fails validation.
@@ -28,3 +82,6 @@ export declare function loadCatalog(file: string): Probe[];
 export declare const CATALOG: Probe[];
 /** Filter probes by category. `source` defaults to the built-in CATALOG. */
 export declare function probesFor(category?: string, source?: Probe[]): Probe[];
+/** Keep probes whose `id` matches the pattern (regex, case-insensitive; falls
+ *  back to substring on an invalid regex). Used by `loop --grep` to run a subset. */
+export declare function grepProbes(probes: Probe[], pattern: string): Probe[];

package/dist/cli.js

@@ -88,6 +88,7 @@ var ProbeSchema = z2.object({
   note: z2.string().optional(),
   expect: ExpectSchema.optional()
 });
+var CatalogSchema = z2.array(ProbeSchema);
 function loadCatalog(file) {
   const path = resolve(process.cwd(), file);
   const raw = readFileSync(path, "utf8");
@@ -293,6 +294,33 @@ function probesFor(category, source = CATALOG) {
     return source;
   return source.filter((p) => p.category === category);
 }
+function grepProbes(probes, pattern) {
+  let compiled;
+  try {
+    compiled = new RegExp(pattern, "i");
+  } catch {
+    compiled = undefined;
+  }
+  const rx = compiled;
+  if (rx)
+    return probes.filter((p) => rx.test(p.id));
+  const needle = pattern.toLowerCase();
+  return probes.filter((p) => p.id.toLowerCase().includes(needle));
+}
+
+// src/commands/assert.ts
+import { resolve as resolve4 } from "node:path";
+
+// src/log.ts
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname, resolve as resolve2 } from "node:path";
+var RUNS_FILE = resolve2(process.cwd(), process.env.MIRA_RUNS_FILE ?? "mira-runs.jsonl");
+async function appendRun(result, meta = {}) {
+  await mkdir(dirname(RUNS_FILE), { recursive: true });
+  const record = { ...meta, ...result };
+  await appendFile(RUNS_FILE, `${JSON.stringify(record)}
+`, "utf8");
+}
 
 // src/ui.ts
 import pc from "picocolors";
@@ -334,7 +362,7 @@ var TIPS = [
   "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)
+  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 = [
@@ -401,49 +429,6 @@ function clearTitle() {
   process.stderr.write("\x1B]0;\x07");
 }
 
-// src/commands/catalog.ts
-function listCatalog(opts = {}) {
-  const source = opts.catalog ? loadCatalog(opts.catalog) : CATALOG;
-  if (!opts.catalog && opts.category && !CATEGORIES.includes(opts.category)) {
-    note(c.red(`unknown category "${opts.category}" (one of: ${CATEGORIES.join(", ")})`));
-    process.exit(1);
-  }
-  let probes = probesFor(opts.category, source);
-  if (opts.max !== undefined)
-    probes = probes.slice(0, opts.max);
-  if (opts.json) {
-    console.log(JSON.stringify(probes.map((p) => ({
-      id: p.id,
-      category: p.category,
-      hypothesis: p.hypothesis,
-      send: p.send,
-      slow: Boolean(p.slow),
-      confirm: Boolean(p.confirm),
-      expect: p.expect ?? null
-    })), null, 2));
-    return;
-  }
-  note(c.bold(`${probes.length} probe(s)${opts.category ? ` [${opts.category}]` : ""}`));
-  for (const p of probes) {
-    const tags = [p.slow ? c.yellow("slow") : "", p.confirm ? c.magenta("confirm") : ""].filter(Boolean).join(" ");
-    note(`  ${c.cyan(p.id.padEnd(16))} ${c.dim(p.category.padEnd(11))} ${p.hypothesis} ${tags}`);
-  }
-}
-
-// src/commands/diff.ts
-import { resolve as resolve4 } from "node:path";
-
-// src/log.ts
-import { appendFile, mkdir } from "node:fs/promises";
-import { dirname, resolve as resolve2 } from "node:path";
-var RUNS_FILE = resolve2(process.cwd(), process.env.MIRA_RUNS_FILE ?? "mira-runs.jsonl");
-async function appendRun(result, meta = {}) {
-  await mkdir(dirname(RUNS_FILE), { recursive: true });
-  const record = { ...meta, ...result };
-  await appendFile(RUNS_FILE, `${JSON.stringify(record)}
-`, "utf8");
-}
-
 // src/commands/report.ts
 import { readFileSync as readFileSync2, writeFileSync } from "node:fs";
 import { resolve as resolve3 } from "node:path";
@@ -568,7 +553,89 @@ function report(opts) {
   }
 }
 
+// src/commands/assert.ts
+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 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);
+  if (opts.json) {
+    console.log(JSON.stringify({ graded: graded.length, passed: graded.length - failed.length, results: graded }, 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) {
+    note(c.dim("  no records matched a probe with `expect` — nothing to grade."));
+    return;
+  }
+  for (const g of graded) {
+    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)(`
+${graded.length - failed.length}/${graded.length} assertions passed.`));
+  if (failed.length && !opts.noFail)
+    process.exit(1);
+}
+
+// src/commands/catalog.ts
+function listCatalog(opts = {}) {
+  const source = opts.catalog ? loadCatalog(opts.catalog) : CATALOG;
+  if (!opts.catalog && opts.category && !CATEGORIES.includes(opts.category)) {
+    note(c.red(`unknown category "${opts.category}" (one of: ${CATEGORIES.join(", ")})`));
+    process.exit(1);
+  }
+  let probes = probesFor(opts.category, source);
+  if (opts.grep)
+    probes = grepProbes(probes, opts.grep);
+  if (opts.max !== undefined)
+    probes = probes.slice(0, opts.max);
+  if (opts.json) {
+    console.log(JSON.stringify(probes.map((p) => ({
+      id: p.id,
+      category: p.category,
+      hypothesis: p.hypothesis,
+      send: p.send,
+      slow: Boolean(p.slow),
+      confirm: Boolean(p.confirm),
+      expect: p.expect ?? null
+    })), null, 2));
+    return;
+  }
+  note(c.bold(`${probes.length} probe(s)${opts.category ? ` [${opts.category}]` : ""}`));
+  for (const p of probes) {
+    const tags = [p.slow ? c.yellow("slow") : "", p.confirm ? c.magenta("confirm") : ""].filter(Boolean).join(" ");
+    note(`  ${c.cyan(p.id.padEnd(16))} ${c.dim(p.category.padEnd(11))} ${p.hypothesis} ${tags}`);
+  }
+}
+
 // src/commands/diff.ts
+import { resolve as resolve5 } from "node:path";
 function lastByProbe(records) {
   const m = new Map;
   for (const r of records) {
@@ -640,7 +707,7 @@ function load(path, label) {
   try {
     return loadRunRecords(path);
   } catch (e) {
-    const shown = path ? resolve4(process.cwd(), path) : RUNS_FILE;
+    const shown = path ? resolve5(process.cwd(), path) : RUNS_FILE;
     if (e?.code === "ENOENT")
       console.error(`${label}: no run log at ${shown}`);
     else
@@ -859,7 +926,7 @@ function buildCollector(peer, client, t, sent, opts) {
   const collected = new Map;
   const start = Date.now();
   let firstReplyMs = null;
-  return new Promise((resolve5) => {
+  return new Promise((resolve6) => {
     let settleTimer;
     let firstTimer;
     let hardTimer;
@@ -889,7 +956,7 @@ function buildCollector(peer, client, t, sent, opts) {
     const finish = () => {
       cleanup();
       const messages = [...collected.values()].sort((a, b) => a.msg.id - b.msg.id).map(({ msg, editCount }) => extractMessage(msg, editCount));
-      resolve5({
+      resolve6({
         peer,
         sent,
         messages,
@@ -1106,7 +1173,7 @@ async function loop(opts) {
     process.exit(1);
   }
   if (opts.list) {
-    listCatalog({ category: opts.category, max: opts.max, catalog: opts.catalog });
+    listCatalog({ category: opts.category, max: opts.max, catalog: opts.catalog, grep: opts.grep });
     return;
   }
   const source = opts.catalog ? loadCatalog(opts.catalog) : CATALOG;
@@ -1125,9 +1192,10 @@ async function loop(opts) {
     console.error("TG_SESSION is empty — run `mira-harness login` first, then put it in .env.");
     process.exit(1);
   }
-  const probes = probesFor(opts.category, source).slice(0, opts.max);
+  const matched = opts.grep ? grepProbes(probesFor(opts.category, source), opts.grep) : probesFor(opts.category, source);
+  const probes = matched.slice(0, opts.max);
   if (!probes.length) {
-    console.error("no probes selected.");
+    console.error(opts.grep ? `no probes match --grep "${opts.grep}".` : "no probes selected.");
     process.exit(1);
   }
   const gap = opts.gap ?? DEFAULT_GAP_MS;
@@ -1196,6 +1264,22 @@ async function loop(opts) {
   }
 }
 
+// src/commands/schema.ts
+import { writeFileSync as writeFileSync2 } from "node:fs";
+import { resolve as resolve6 } from "node:path";
+import { z as z3 } from "zod";
+function schema(opts = {}) {
+  const json = JSON.stringify(z3.toJSONSchema(CatalogSchema), null, 2);
+  if (opts.out) {
+    const dest = resolve6(process.cwd(), opts.out);
+    writeFileSync2(dest, `${json}
+`, "utf8");
+    console.error(`wrote catalog JSON Schema to ${opts.out}`);
+  } else {
+    console.log(json);
+  }
+}
+
 // src/commands/send.ts
 import { existsSync as existsSync2 } from "node:fs";
 var STOP_FILE2 = "STOP_MIRA";
@@ -1243,7 +1327,7 @@ async function send(rawMessage, opts = {}) {
 }
 
 // src/commands/stats.ts
-import { resolve as resolve5 } from "node:path";
+import { resolve as resolve7 } from "node:path";
 var SPARK = "▁▂▃▄▅▆▇█";
 function sparkline(values) {
   if (!values.length)
@@ -1282,7 +1366,7 @@ function stats(opts = {}) {
     records = loadRunRecords(opts.in, opts.category);
   } catch (e) {
     if (e?.code === "ENOENT") {
-      const path = opts.in ? resolve5(process.cwd(), opts.in) : RUNS_FILE;
+      const path = opts.in ? resolve7(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));
@@ -1373,11 +1457,11 @@ async function watch(opts = {}) {
   const client = await connect(session);
   const unsubscribe = await subscribe(client, peer, (m, kind) => note(line(peer, m, kind)));
   note(c.bold(`watching @${peer} — Ctrl-C to stop`));
-  await new Promise((resolve6) => {
+  await new Promise((resolve8) => {
     process.once("SIGINT", () => {
       note(c.dim(`
 stopping…`));
-      resolve6();
+      resolve8();
     });
   });
   unsubscribe();
@@ -1433,7 +1517,7 @@ program.command("send").description("Send one probe to @mira and print the full
     noLog: opts.log === false
   });
 });
-program.command("loop").description("Run the experiment catalog against @mira at a human pace").option("-c, --category <category>", `only this category (${CATEGORIES.join(" | ")})`).option("-m, --max <n>", "max probes this run", "6").option("--confirm", "press a safe ✅ Confirm on generation probes (spends credits)", false).option("--peer <peer>", "'experiment'|'group' for TG_EXPERIMENT_CHAT, or a literal allowlisted peer").option("--gap <ms>", "delay between sends").option("--settle <ms>", "quiet window before concluding a reply").option("--timeout <ms>", "give up if no reply by this many ms").option("--list", "list the probes that would run, then exit (no sends)", false).option("--catalog <file>", "custom catalog JSON file (instead of the built-in catalog)").option("--no-fail", "report failed assertions but still exit 0 (default: exit 1 on failure)").option("-q, --quiet", "suppress progress spinners", false).action(async (opts) => {
+program.command("loop").description("Run the experiment catalog against @mira at a human pace").option("-c, --category <category>", `only this category (${CATEGORIES.join(" | ")})`).option("-m, --max <n>", "max probes this run", "6").option("--confirm", "press a safe ✅ Confirm on generation probes (spends credits)", false).option("--peer <peer>", "'experiment'|'group' for TG_EXPERIMENT_CHAT, or a literal allowlisted peer").option("--gap <ms>", "delay between sends").option("--settle <ms>", "quiet window before concluding a reply").option("--timeout <ms>", "give up if no reply by this many ms").option("--list", "list the probes that would run, then exit (no sends)", false).option("--catalog <file>", "custom catalog JSON file (instead of the built-in catalog)").option("--grep <pattern>", "run only probes whose id matches this regex (case-insensitive)").option("--no-fail", "report failed assertions but still exit 0 (default: exit 1 on failure)").option("-q, --quiet", "suppress progress spinners", false).action(async (opts) => {
   await loop({
     category: opts.category,
     max: posInt("max", opts.max),
@@ -1444,6 +1528,7 @@ program.command("loop").description("Run the experiment catalog against @mira at
     timeout: ms("timeout", opts.timeout),
     list: opts.list,
     catalog: opts.catalog,
+    grep: opts.grep,
     noFail: opts.fail === false,
     quiet: opts.quiet
   });
@@ -1461,6 +1546,12 @@ program.command("stats").description("At-a-glance run-log dashboard: totals, lat
 program.command("diff").description("Compare two run logs for @mira behavioral drift (exit 1 on a regression)").argument("<baseline>", "baseline run log (JSONL)").argument("[current]", "current run log (JSONL); defaults to the run log").option("--json", "output the drift as JSON", false).option("--no-fail", "report regressions but still exit 0").action((baseline, current, opts) => {
   diff({ baseline, current, json: opts.json, noFail: !opts.fail });
 });
+program.command("assert").description("Re-grade a saved run log against a catalog's `expect` (offline; exit 1 on failure)").option("--in <file>", "input JSONL (default: the run log)").option("--catalog <file>", "catalog with expectations (default: the built-in catalog)").option("-c, --category <category>", "only include probes from this category").option("--json", "output the results as JSON", false).option("--no-fail", "report failures but still exit 0").action((opts) => {
+  assertLog({ in: opts.in, catalog: opts.catalog, category: opts.category, json: opts.json, noFail: !opts.fail });
+});
+program.command("schema").description("Print the JSON Schema for a custom catalog file (editor autocomplete / validation)").option("--out <file>", "write to a file instead of stdout").action((opts) => {
+  schema({ out: opts.out });
+});
 program.addHelpText("after", `
 Examples:
   $ mira-harness login
@@ -1476,6 +1567,9 @@ Examples:
   $ mira-harness report --category core --out report.md
   $ mira-harness stats
   $ mira-harness diff baseline.jsonl
+  $ mira-harness loop --grep core-json
+  $ mira-harness assert
+  $ mira-harness schema > catalog.schema.json
 `);
 if (process.argv.length <= 2) {
   banner(version);

package/dist/index.js

@@ -174,6 +174,7 @@ var ProbeSchema = z2.object({
   note: z2.string().optional(),
   expect: ExpectSchema.optional()
 });
+var CatalogSchema = z2.array(ProbeSchema);
 function loadCatalog(file) {
   const path = resolve(process.cwd(), file);
   const raw = readFileSync(path, "utf8");
@@ -379,6 +380,19 @@ function probesFor(category, source = CATALOG) {
     return source;
   return source.filter((p) => p.category === category);
 }
+function grepProbes(probes, pattern) {
+  let compiled;
+  try {
+    compiled = new RegExp(pattern, "i");
+  } catch {
+    compiled = undefined;
+  }
+  const rx = compiled;
+  if (rx)
+    return probes.filter((p) => rx.test(p.id));
+  const needle = pattern.toLowerCase();
+  return probes.filter((p) => p.id.toLowerCase().includes(needle));
+}
 // src/client.ts
 import { Api, TelegramClient } from "telegram";
 import { EditedMessage } from "telegram/events/EditedMessage.js";

package/dist/mcp.js

@@ -91,6 +91,7 @@ var ProbeSchema = z2.object({
   note: z2.string().optional(),
   expect: ExpectSchema.optional()
 });
+var CatalogSchema = z2.array(ProbeSchema);
 function loadCatalog(file) {
   const path = resolve(process.cwd(), file);
   const raw = readFileSync(path, "utf8");
@@ -296,6 +297,19 @@ function probesFor(category, source = CATALOG) {
     return source;
   return source.filter((p) => p.category === category);
 }
+function grepProbes(probes, pattern) {
+  let compiled;
+  try {
+    compiled = new RegExp(pattern, "i");
+  } catch {
+    compiled = undefined;
+  }
+  const rx = compiled;
+  if (rx)
+    return probes.filter((p) => rx.test(p.id));
+  const needle = pattern.toLowerCase();
+  return probes.filter((p) => p.id.toLowerCase().includes(needle));
+}
 
 // src/client.ts
 import { Api, TelegramClient } from "telegram";

package/llms.txt

@@ -19,12 +19,14 @@ so the only programmatic path is a userbot (a real user account over MTProto / G
 ## CLI commands
 - `doctor` — env / session / connectivity / @mira resolution check (read-only). Run this first.
 - `send [message...]` — one probe → full reply as JSON. Message via arg or stdin. Flags: `--settle <ms> --timeout <ms> --quiet --no-log`.
-- `loop` — run the catalog, paced. Flags: `--category <core|skills|generation|wallet> --max <n> --peer <experiment> --gap <ms> --settle <ms> --timeout <ms> --list --catalog <file.json> --no-fail --quiet`. Observe-only unless `--confirm`. Grades probes that declare `expect` (PASS/FAIL) and **exits non-zero** if any graded probe fails (`--no-fail` to report without failing) — drops straight into CI.
+- `loop` — run the catalog, paced. Flags: `--category <core|skills|generation|wallet> --max <n> --peer <experiment> --gap <ms> --settle <ms> --timeout <ms> --list --catalog <file.json> --grep <regex> --no-fail --quiet`. Observe-only unless `--confirm`. Grades probes that declare `expect` (PASS/FAIL) and **exits non-zero** if any graded probe fails (`--no-fail` to report without failing) — drops straight into CI. `--grep <regex>` runs only probes whose id matches.
 - `catalog` — list the catalog, no network. Flags: `--category --catalog <file.json> --json`.
 - `watch` — live-tail @mira's messages, observe-only. Flag: `--peer`.
 - `report` — distill the JSONL run log into Markdown. Flags: `--in <file> --out <file> --category`.
 - `stats` — at-a-glance run-log dashboard: totals, first-reply latency records (fastest / median / p95 / slowest), an ASCII sparkline, and a per-category breakdown. Flags: `--in <file> --category --json`.
 - `diff <baseline> [current]` — compare two run logs for @mira behavioral drift (matches probes by id; structural, not exact-text). Regressions (assertion ✓→✗, new timeout, >2x latency) **exit non-zero**; surface changes / improvements are reported. `current` defaults to the run log. Flags: `--json --no-fail`.
+- `assert` — re-grade a SAVED run log against a catalog's `expect`, offline (no network). The fast loop for developing assertions, and CI-able **without a Telegram session** (grade a committed run-log fixture). **Exits non-zero** on failure. Flags: `--in <file> --catalog <file.json> --category --json --no-fail`.
+- `schema` — print the JSON Schema for a custom catalog file (an array of probes), derived from the loader's zod schema. Wire into an editor for autocomplete/validation. Flag: `--out <file>`.
 - Help: `mira-harness --help` or `<command> --help`.
 
 ## MCP server (bin: mira-harness-mcp, entry dist/mcp.js)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mira-harness",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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": {