@xhulz/nina 0.28.18 → 0.28.20

package/src/commands/pipeline.mjs

@@ -1,17 +1,19 @@
 /**
  * `nina pipeline` — draws a project's agent chain: the line work moves along, the gates it passes on the
- * way, where each stage sends work back and how many rounds it may, each stage's model, effort and skills,
- * and which chain a task of each shape takes.
+ * way, the stages that run as several agents at once, where each stage sends work back and how many rounds
+ * it may, each stage's model, effort and skills with what it did over the last thirty days, and which chain
+ * a task of each shape takes. `--for` draws one shape's chain alone.
  *
  * Opening a project, the pipeline was a graph, a router, ten specs and a table in CLAUDE.md to read before
  * anyone could say which stage came after which, on which model, with which skills. Every fact here is
- * already composed, and `nina check` already holds it to the graph; this only reads it back and draws it.
+ * already composed, and `nina check` already holds it to the graph, or already measured; this only reads it
+ * back and draws it.
  */
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
-import { PINK, useColor } from '../banner.mjs';
-import { HARNESS } from '../paths.mjs';
+import { dim, pink } from '../look.mjs';
+import { HARNESS, slugFor, snapshotsDir } from '../paths.mjs';
 import { TERMINALS, parseGraph } from '../graph.mjs';
 import { required } from '../tools.mjs';
 import { isLoopBack } from '../transcripts.mjs';
@@ -20,6 +22,9 @@ import { frontmatter } from './pills.mjs';
 /** A stage line under "## Stages": "- `name` — what it does". */
 const STAGE_LINE = /^- `([a-z][a-z-]*)` — (.*)$/;
 
+/** How far back the history beside each stage looks, unless `--since` says. */
+const HISTORY_DAYS = 30;
+
 /**
  * What each stage does, in the graph's own words: shorter than a spec's `description:`, which is written
  * for Claude Code to choose an agent by.
@@ -48,7 +53,8 @@ export function stageWords(text) {
  * - The gates: a stage off the line that a line stage sends work to on a condition, and that hands it on
  *   to the next stage of the line.
  * - The ends: where the line's last stage sends work on a condition, followed forward to a terminal.
- * - The loop-backs: every edge on a verdict that sends work back, to a stage or to the owner.
+ * - The loop-backs: every edge on a verdict that sends work back, to a stage or to the owner, grouped by
+ *   the stage that sends it.
  *
  * @param {{stages: Set<string>, edges: object[]}} graph - A parsed graph.
  * @returns {{line: string[], gates: object[], ends: object[], back: object[]}}
@@ -81,17 +87,18 @@ export function shapeOf(graph) {
       }
       return { path, when: e.when };
     });
-  // Grouped by the stage that sends the work back, in the order the stages are listed.
   const back = graph.edges.filter((e) => isLoopBack(e.token)).sort((a, b) => order.indexOf(a.from) - order.indexOf(b.from));
   return { line, gates, ends, back };
 }
 
 /**
  * The rows of the "Required chain by task shape" table in a composed CLAUDE.md: the shape, and the chain it
- * takes — the part the table sets in bold, where it does.
+ * takes — the part the table sets in bold, where it does. A row whose chain runs stage → stage, or is
+ * "none", is a chain of its own; any other (`+ dba before reviewer`) is an add-on to whichever chain the
+ * task takes.
  *
  * @param {string} text - The composed CLAUDE.md.
- * @returns {{shape: string, chain: string}[]}
+ * @returns {{shape: string, chain: string, addOn: boolean}[]}
  */
 export function chainsByShape(text) {
   const at = text.indexOf('| Task shape |');
@@ -102,34 +109,127 @@ export function chainsByShape(text) {
     const [shape = '', chain = ''] = row.split('|').slice(1).map((c) => c.trim());
     const bold = /\*\*(.+?)\*\*/.exec(chain)?.[1];
     const plain = (s) => s.replace(/\*\*/g, '').replace(/`/g, '').trim();
-    rows.push({ shape: plain(shape), chain: plain(bold ?? chain) });
+    const taken = plain(bold ?? chain);
+    rows.push({ shape: plain(shape), chain: taken, addOn: !taken.includes('→') && !/^none\b/i.test(taken) });
   }
   return rows;
 }
 
+/**
+ * The task shapes a `--for` names: by its number in the list, or by every word it gives.
+ *
+ * @param {{shape: string}[]} shapes - The chain table's rows.
+ * @param {string} query - A number, or words.
+ * @returns {object[]}
+ */
+export function pickShape(shapes, query) {
+  if (/^\d+$/.test(query.trim())) {
+    const row = shapes[Number(query) - 1];
+    return row ? [row] : [];
+  }
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [];
+  return shapes.filter((r) => words.every((w) => r.shape.toLowerCase().includes(w)));
+}
+
+/**
+ * What each stage did since a date, from the measurement store: its runs, the verdicts that could be read,
+ * and how many of those sent work back. A run a hook denied never ran, and is not counted.
+ *
+ * @param {object[]} records - The project's records.
+ * @param {string} since - An ISO date.
+ * @returns {Map<string, {runs: number, read: number, back: number}>}
+ */
+export function historyOf(records, since) {
+  const byRole = new Map();
+  for (const r of records) {
+    if (!r.role || r.status === 'denied' || String(r.ts ?? '') < since) continue;
+    const s = byRole.get(r.role) ?? { runs: 0, read: 0, back: 0 };
+    s.runs += 1;
+    if (r.verdict && r.verdict !== 'UNCLEAR' && r.verdict !== 'NONE') {
+      s.read += 1;
+      if (isLoopBack(r.verdict)) s.back += 1;
+    }
+    byRole.set(r.role, s);
+  }
+  return byRole;
+}
+
+/**
+ * The project's records in the measurement store, under the name Claude Code gives its directory — as
+ * given, or with its links resolved, since either may be the one the sessions ran in.
+ *
+ * @param {string} dir - The project.
+ * @returns {object[]|null} Null when the store has nothing for it.
+ */
+function storedRuns(dir) {
+  const names = new Set([slugFor(dir)]);
+  try {
+    names.add(slugFor(realpathSync(dir)));
+  } catch {
+    // A directory that cannot be resolved is looked up as given.
+  }
+  for (const name of names) {
+    const file = join(snapshotsDir(), `${name}.jsonl`);
+    if (!existsSync(file)) continue;
+    return readFileSync(file, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .flatMap((l) => {
+        try {
+          return [JSON.parse(l)];
+        } catch {
+          return [];
+        }
+      });
+  }
+  return null;
+}
+
 /**
  * Runs the command.
  *
- * @param {string[]} argv - `[--project <dir>]`.
+ * @param {string[]} argv - `[--project <dir>] [--for <number or words>] [--since <YYYY-MM-DD>]`.
  * @returns {Promise<number>} Process exit code.
  */
 export async function pipeline(argv) {
-  const dir = resolve(argv.includes('--project') ? argv[argv.indexOf('--project') + 1] : process.cwd());
+  const arg = (flag) => (argv.includes(flag) ? argv[argv.indexOf(flag) + 1] ?? '' : null);
+  const dir = resolve(arg('--project') ?? process.cwd());
   const graphPath = join(dir, '.claude', 'graph.md');
   if (!existsSync(graphPath)) {
     console.error(`  no .claude/graph.md in ${dir} — this draws a composed pipeline: \`nina compose\` writes one`);
     return 1;
   }
-  const graph = parseGraph(readFileSync(graphPath, 'utf8'));
-  const words = stageWords(readFileSync(graphPath, 'utf8'));
-  const { line, gates, ends, back } = shapeOf(graph);
+  const graphText = readFileSync(graphPath, 'utf8');
+  const graph = parseGraph(graphText);
+  const words = stageWords(graphText);
+  const shape = shapeOf(graph);
+  const claude = join(dir, 'CLAUDE.md');
+  const shapes = existsSync(claude) ? chainsByShape(readFileSync(claude, 'utf8')) : [];
+
+  // `--for`: one shape's chain, and only the stages on it.
+  const query = arg('--for');
+  let chosen = null;
+  if (query !== null) {
+    const picked = pickShape(shapes, query);
+    if (picked.length !== 1) {
+      console.error(picked.length === 0 ? `  no task shape matches "${query}" — by number or by words:` : `  "${query}" matches ${picked.length} task shapes — narrow it, or give the number:`);
+      for (const [i, r] of shapes.entries()) if (picked.length === 0 || picked.includes(r)) console.error(`    ${String(i + 1).padStart(2)}  ${r.shape}`);
+      return 1;
+    }
+    chosen = picked[0];
+  }
 
-  const color = useColor();
-  const name = (s) => (color && !TERMINALS.has(s) ? `\x1b[38;2;${PINK.join(';')}m${s}\x1b[0m` : s);
-  const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
+  const name = (s) => (TERMINALS.has(s) ? s : pink(s));
   const width = Math.max(80, Math.min(process.stdout.columns ?? 110, 140));
   const fit = (s, room) => (s.length > room ? `${s.slice(0, Math.max(room - 1, 1))}…` : s);
   const arrow = ' ─▶ ';
+  const many = graph.many ?? new Map();
+  // A stage that may run as several agents at once carries ×n wherever the line draws it. Alignment is
+  // counted on the plain text, and the names are painted after.
+  const plainStage = (s) => `${s}${many.has(s) ? ' ×n' : ''}`;
+  const shownStage = (s) => `${name(s)}${many.has(s) ? ' ×n' : ''}`;
+  const padName = (s, n) => `${name(s)}${' '.repeat(Math.max(n - s.length, 1))}`;
 
   let profile = {};
   try {
@@ -138,32 +238,54 @@ export async function pipeline(argv) {
     // A pipeline composed by hand draws all the same; only the header has less to say.
   }
   const surfaces = (profile.surfaces ?? []).slice().sort();
-  console.log(`  pipeline · ${basename(dir)}${profile.core ? ` · core ${profile.core}` : ''}${surfaces.length ? ` · surfaces ${surfaces.join(', ')}` : ''}\n`);
+  console.log(`  pipeline · ${basename(dir)}${profile.core ? ` · core ${profile.core}` : ''}${surfaces.length ? ` · surfaces ${surfaces.join(', ')}` : ''}`);
 
-  // Alignment is counted on the plain text, and the names are painted after.
-  const padName = (s, n) => `${name(s)}${' '.repeat(Math.max(n - s.length, 1))}`;
+  // The stages this drawing covers: all of them, or those the chosen shape's chain names.
+  const onChain = chosen ? (chosen.chain.match(/[a-z][a-z-]*/g) ?? []).filter((w) => graph.stages.has(w)) : null;
+  const covered = new Set(onChain ?? graph.stages);
 
-  // The line, and where its last stage sends work.
-  const plainHead = `  ${line.join(arrow)}`;
-  const head = `  ${line.map(name).join(arrow)}`;
-  if (ends.length === 0) console.log(head);
-  const lead = ' '.repeat(plainHead.length + 1);
-  const joint = (i) => (ends.length === 1 ? '──▶ ' : i === 0 ? '─┬─▶ ' : i === ends.length - 1 ? ' └─▶ ' : ' ├─▶ ');
-  const endCol = Math.max(0, ...ends.map((end, i) => `${lead}${joint(i)}${end.path.join(arrow)}`.length)) + 3;
-  ends.forEach((end, i) => {
-    const plain = `${lead}${joint(i)}${end.path.join(arrow)}`;
-    console.log(`${i === 0 ? `${head} ` : lead}${joint(i)}${end.path.map(name).join(arrow)}${' '.repeat(endCol - plain.length)}${dim(fit(end.when, width - endCol))}`);
-  });
+  if (chosen) {
+    console.log(`  for: ${chosen.shape}\n`);
+    if (onChain.length === 0) console.log(`  ${chosen.chain}`);
+    else console.log(`  ${onChain.map(shownStage).join(arrow)}`);
+    const addOns = shapes.filter((r) => r.addOn && r !== chosen);
+    if (addOns.length > 0 && onChain.length > 0) {
+      console.log(`\n  ${dim('and, when the change calls for them')}`);
+      const col = Math.min(Math.max(...addOns.map((r) => r.chain.length)), 44) + 4;
+      for (const r of addOns) console.log(`    ${fit(r.chain, col - 4).padEnd(col)}${dim(fit(r.shape, width - col - 6))}`);
+    }
+  } else {
+    console.log('');
+    // The line, and where its last stage sends work.
+    const plainHead = `  ${shape.line.map(plainStage).join(arrow)}`;
+    const head = `  ${shape.line.map(shownStage).join(arrow)}`;
+    if (shape.ends.length === 0) console.log(head);
+    const lead = ' '.repeat(plainHead.length + 1);
+    const joint = (i) => (shape.ends.length === 1 ? '──▶ ' : i === 0 ? '─┬─▶ ' : i === shape.ends.length - 1 ? ' └─▶ ' : ' ├─▶ ');
+    const endCol = Math.max(0, ...shape.ends.map((end, i) => `${lead}${joint(i)}${end.path.join(arrow)}`.length)) + 3;
+    shape.ends.forEach((end, i) => {
+      const plain = `${lead}${joint(i)}${end.path.join(arrow)}`;
+      console.log(`${i === 0 ? `${head} ` : lead}${joint(i)}${end.path.map(name).join(arrow)}${' '.repeat(endCol - plain.length)}${dim(fit(end.when, width - endCol))}`);
+    });
 
-  if (gates.length > 0) {
-    console.log(`\n  ${dim('gates on the way, when the diff calls for them')}`);
-    const chain = (g) => `${g.from}${arrow}${g.gate}${arrow}${g.to}`;
-    const col = Math.max(...gates.map((g) => chain(g).length)) + 4;
-    for (const g of gates) {
-      console.log(`    ${name(g.from)}${arrow}${name(g.gate)}${arrow}${name(g.to)}${' '.repeat(col - chain(g).length)}${dim(fit(g.when, width - col - 6))}`);
+    if (shape.gates.length > 0) {
+      console.log(`\n  ${dim('gates on the way, when the diff calls for them')}`);
+      const chain = (g) => `${g.from}${arrow}${g.gate}${arrow}${g.to}`;
+      const col = Math.max(...shape.gates.map((g) => chain(g).length)) + 4;
+      for (const g of shape.gates) {
+        console.log(`    ${name(g.from)}${arrow}${name(g.gate)}${arrow}${name(g.to)}${' '.repeat(col - chain(g).length)}${dim(fit(g.when, width - col - 6))}`);
+      }
     }
   }
 
+  const drawnMany = [...many].filter(([s]) => covered.has(s));
+  if (drawnMany.length > 0) {
+    console.log(`\n  ${dim('×n  runs as several agents at once, each on its own share of the work')}`);
+    const col = Math.max(...drawnMany.map(([s]) => s.length)) + 3;
+    for (const [s, { when }] of drawnMany) console.log(`      ${padName(s, col)}${dim(fit(when, width - col - 8))}`);
+  }
+
+  const back = shape.back.filter((e) => covered.has(e.from) && (covered.has(e.to) || TERMINALS.has(e.to)));
   if (back.length > 0) {
     console.log(`\n  ${dim('sent back: to whom, on which verdict, and how many rounds per issue')}`);
     const fromCol = Math.max(...back.map((e) => e.from.length)) + 2;
@@ -180,20 +302,30 @@ export async function pipeline(argv) {
     }
   }
 
-  // Each stage: what it does, on which model and effort, with which skills.
+  // Each stage: what it does, on which model and effort, with which skills, and what it did lately.
   const agentsDir = join(dir, '.claude', 'agents');
   const specs = new Map();
   for (const file of existsSync(agentsDir) ? readdirSync(agentsDir).filter((f) => f.endsWith('.md')).sort() : []) {
     specs.set(file.replace(/\.md$/, ''), readFileSync(join(agentsDir, file), 'utf8'));
   }
-  const stages = [...graph.stages];
+  const since = arg('--since') || new Date(Date.now() - HISTORY_DAYS * 86_400_000).toISOString().slice(0, 10);
+  const runs = storedRuns(dir);
+  const history = runs ? historyOf(runs, since) : null;
+  const stages = [...graph.stages].filter((s) => covered.has(s));
   const col = Math.max(...stages.map((s) => s.length), 10) + 2;
-  console.log(`\n  ${dim('stages')}`);
+  console.log(`\n  ${dim(history ? `stages · what each ran since ${since}, from the measured history` : 'stages · no measured history for this project yet')}`);
   for (const stage of stages) {
     const spec = specs.get(stage) ?? '';
     const front = frontmatter(spec) ?? {};
-    const runs = [front.model, front.effort].filter(Boolean).join(' · ') || 'no spec';
-    console.log(`    ${padName(stage, col)}${runs.padEnd(26)}${dim(fit(words.get(stage) ?? '', width - col - 32))}`);
+    const on = [front.model, front.effort].filter(Boolean).join(' · ') || 'no spec';
+    console.log(`    ${padName(stage, col)}${on.padEnd(26)}${dim(fit(words.get(stage) ?? '', width - col - 32))}`);
+    if (history) {
+      const h = history.get(stage);
+      const said = !h
+        ? 'no run'
+        : `${h.runs} run(s)${h.read === 0 ? ', no verdict read' : `, sent back ${h.back} of ${h.read} (${Math.round((100 * h.back) / h.read)}%)`}`;
+      console.log(`    ${' '.repeat(col)}${dim('ran     ')}${said}`);
+    }
     const skills = [...required(spec).skills].sort();
     if (skills.length > 0) {
       const lines = [];
@@ -210,22 +342,23 @@ export async function pipeline(argv) {
     }
   }
 
-  // An agent the project wrote for itself is not a stage, and the graph does not route to it.
-  const own = [...specs.keys()].filter((role) => !graph.stages.has(role));
-  if (own.length > 0) {
-    console.log(`\n  ${dim("the project's own agents, outside the pipeline")}`);
-    for (const role of own) {
-      const front = frontmatter(specs.get(role)) ?? {};
-      console.log(`    ${role}${' '.repeat(Math.max(col - role.length, 2))}${dim(fit(front.description ?? '', width - col - 6))}`);
+  if (!chosen) {
+    // An agent the project wrote for itself is not a stage, and the graph does not route to it.
+    const own = [...specs.keys()].filter((role) => !graph.stages.has(role));
+    if (own.length > 0) {
+      console.log(`\n  ${dim("the project's own agents, outside the pipeline")}`);
+      for (const role of own) {
+        const front = frontmatter(specs.get(role)) ?? {};
+        console.log(`    ${role}${' '.repeat(Math.max(col - role.length, 2))}${dim(fit(front.description ?? '', width - col - 6))}`);
+      }
+    }
+    if (shapes.length > 0) {
+      console.log(`\n  ${dim('which chain a task takes, by its shape (CLAUDE.md) — `nina pipeline --for <number or words>` draws one')}`);
+      const shapeCol = Math.min(Math.max(...shapes.map((r) => r.shape.length)), 56) + 2;
+      for (const [i, r] of shapes.entries()) {
+        console.log(`    ${String(i + 1).padStart(2)}  ${fit(r.shape, shapeCol - 2).padEnd(shapeCol)}${fit(r.chain, width - shapeCol - 10)}`);
+      }
     }
-  }
-
-  const claude = join(dir, 'CLAUDE.md');
-  const shapes = existsSync(claude) ? chainsByShape(readFileSync(claude, 'utf8')) : [];
-  if (shapes.length > 0) {
-    console.log(`\n  ${dim('which chain a task takes, by its shape (CLAUDE.md)')}`);
-    const shapeCol = Math.min(Math.max(...shapes.map((r) => r.shape.length)), 58) + 2;
-    for (const r of shapes) console.log(`    ${fit(r.shape, shapeCol - 2).padEnd(shapeCol)}${fit(r.chain, width - shapeCol - 6)}`);
   }
   console.log('');
   return 0;

package/src/commands/stats.mjs

@@ -11,6 +11,7 @@
  * loop-backs it was supposed to harvest were being counted right here.
  */
 
+import { amber, bar, bold, dim, heading, note, pink, stacked } from '../look.mjs';
 import { readFile, readdir } from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import { createReadStream, existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
@@ -183,18 +184,21 @@ function costReport(records) {
   // The same convention as the duration column beside it: the upper middle of an even count.
   const median = (xs) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)];
   console.log(
-    `\n  cost — at API list prices of ${PRICES_AS_OF}; ${measured.length} of ${records.length} runs have a token record` +
-      (unpriced > 0 ? `, ${unpriced} on a model the price table does not know` : ''),
+    heading(
+      'cost',
+      `at API list prices of ${PRICES_AS_OF}; ${measured.length} of ${records.length} runs have a token record` +
+        (unpriced > 0 ? `, ${unpriced} on a model the price table does not know` : ''),
+    ),
   );
-  console.log(`    ${'stage'.padEnd(20)}${'runs'.padStart(6)}${'median'.padStart(10)}${'total'.padStart(10)}${'share'.padStart(8)}`);
+  console.log(dim(`    ${'stage'.padEnd(20)}${'runs'.padStart(6)}${'median'.padStart(10)}${'total'.padStart(10)}${'share'.padStart(8)}`));
   for (const [role, costs] of [...byRole].sort((a, b) => b[1].reduce((x, y) => x + y, 0) - a[1].reduce((x, y) => x + y, 0))) {
     const sum = costs.reduce((a, b) => a + b, 0);
     console.log(
-      `    ${role.padEnd(20)}${String(costs.length).padStart(6)}${money(median(costs)).padStart(10)}` +
-        `${money(sum).padStart(10)}${pct(sum, total).padStart(8)}`,
+      `    ${pink(role)}${' '.repeat(Math.max(20 - role.length, 1))}${String(costs.length).padStart(6)}${money(median(costs)).padStart(10)}` +
+        `${bold(money(sum).padStart(10))}${pct(sum, total).padStart(8)}  ${pink(bar(sum / total, 20))}`,
     );
   }
-  console.log(`    ${'all stages'.padEnd(20)}${String([...byRole.values()].flat().length).padStart(6)}${''.padStart(10)}${money(total).padStart(10)}`);
+  console.log(bold(`    ${'all stages'.padEnd(20)}${String([...byRole.values()].flat().length).padStart(6)}${''.padStart(10)}${money(total).padStart(10)}`));
 }
 
 /**
@@ -271,7 +275,7 @@ function modelReport(records) {
       const costs = runs.map((r) => (r.tokens ? costOf(r.tokens, r.usage_model) : null)).filter((c) => c !== null);
       const dates = runs.map((r) => String(r.ts).slice(0, 10)).sort();
       lines.push(
-        `    ${(i === 0 ? role : '').padEnd(20)}${model.padEnd(26)}${String(runs.length).padStart(5)} run(s)  ${dates[0]} → ${dates.at(-1)}` +
+        `    ${i === 0 ? `${pink(role)}${' '.repeat(Math.max(20 - role.length, 1))}` : ''.padEnd(20)}${model.padEnd(26)}${String(runs.length).padStart(5)} run(s)  ${dim(`${dates[0]} → ${dates.at(-1)}`)}` +
           (clear.length ? `  loop-back ${pct(loops, clear.length)} of ${clear.length}` : '  no readable verdict') +
           (costs.length ? `  median ${money(median(costs))}` : ''),
       );
@@ -303,9 +307,9 @@ function modelReport(records) {
   }
 
   if (lines.length === 0 && drift.length === 0) return;
-  console.log('\n  models — a stage that ran on more than one model or effort level, one line each; different weeks, not an experiment');
+  console.log(heading('models', 'a stage that ran on more than one model or effort level, one line each; different weeks, not an experiment'));
   for (const line of lines) console.log(line);
-  for (const line of drift) console.log(line);
+  for (const line of drift) console.log(amber(line));
 }
 
 /** The verdicts that close a pipeline cycle: the change passed its tests, reached preview, or cleared the audit. */
@@ -390,15 +394,19 @@ function proportionReport(records, stepLimit = () => null) {
   }
   if (built === 0) return;
   console.log(
-    `\n  proportion — ${built} cycle(s) that wrote code; a cycle closes at qa PASS, devops DEPLOYED or secops SECURE, or at the next design after code` +
-      (unreadable > 0 ? `; ${unreadable} closed by a run whose verdict could not be read` : '') +
-      (open > 0 ? `; ${open} still open when their session's record ends` : ''),
+    heading(
+      'proportion',
+      `${built} cycle(s) that wrote code; a cycle closes at qa PASS, devops DEPLOYED or secops SECURE, or at the next design after code` +
+        (unreadable > 0 ? `; ${unreadable} closed by a run whose verdict could not be read` : '') +
+        (open > 0 ? `; ${open} still open when their session's record ends` : ''),
+    ),
   );
-  console.log(`    ${'largest write'.padEnd(16)}${'cycles'.padStart(8)}${'with a planner or architect'.padStart(30)}`);
+  console.log(dim(`    ${'largest write'.padEnd(16)}${'cycles'.padStart(8)}${'with a planner or architect'.padStart(30)}`));
   for (const row of rows) {
-    console.log(`    ${row.label.padEnd(16)}${String(row.cycles).padStart(8)}${`${row.designed} (${pct(row.designed, row.cycles)})`.padStart(30)}`);
+    const designed = `${row.designed} (${pct(row.designed, row.cycles)})`.padStart(30);
+    console.log(`    ${row.label.padEnd(16)}${String(row.cycles).padStart(8)}${row.cycles ? designed : dim(designed)}  ${pink(bar(row.cycles ? row.designed / row.cycles : 0, 10))}`);
   }
-  console.log('    A shape, not a verdict: a critical path is gated in full at any size, and one spec may cover sibling steps.');
+  console.log(dim('    A shape, not a verdict: a critical path is gated in full at any size, and one spec may cover sibling steps.'));
 
   // The one size the harness does limit: what one implementer run writes. A run re-reads the context it
   // has built on every turn, so its cost grows faster than its size — measured over two projects, the
@@ -413,7 +421,10 @@ function proportionReport(records, stepLimit = () => null) {
     const largest = over.reduce((a, b) => (b.files_touched > a.files_touched ? b : a));
     const read = typeof largest.tokens?.read === 'number' ? `, ${Math.round(largest.tokens.read / 1e6)}M tokens read from cache` : '';
     console.log(
-      `    ${over.length} implementer run(s) wrote more files than one step may (${stepLimit(largest.project)}); the largest wrote ${largest.files_touched}${read}. The architect splits such a spec into steps.`,
+      note(
+        `${over.length} implementer run(s) wrote more files than one step may (${stepLimit(largest.project)}); the largest wrote ${largest.files_touched}${read}. The architect splits such a spec into steps.`,
+        'warn',
+      ),
     );
   }
 }
@@ -551,34 +562,53 @@ export async function stats(argv, ctx) {
   const span = [records[0]?.ts, records.at(-1)?.ts].map((t) => String(t).slice(0, 10));
   const projectCount = new Set(records.map((r) => r.project)).size;
   console.log(
-    `  ${records.length} dispatches · ${projectCount} project${projectCount === 1 ? '' : 's'} · ` +
+    `  ${projectCount === 1 ? `${bold(pink(projectName(records[0].project)))} · ` : ''}${bold(records.length)} dispatches · ${projectCount} project${projectCount === 1 ? '' : 's'} · ` +
       `${span[0]} → ${span[1]}` +
-      (here ? '  (this project; --all for every project)' : '') +
-      (skipped > 0 ? `  (${skipped} non-harness project${skipped === 1 ? '' : 's'} hidden, --all to include)` : '') +
-      (held > 0 ? `  · ${held} dispatch(es) denied by a hook, not counted as runs` : '') +
-      '\n',
+      (here ? dim('  (this project; --all for every project)') : '') +
+      (skipped > 0 ? dim(`  (${skipped} non-harness project${skipped === 1 ? '' : 's'} hidden, --all to include)`) : '') +
+      (held > 0 ? `  · ${held} dispatch(es) denied by a hook, not counted as runs` : ''),
   );
+  console.log(heading('stages', 'what each ran, and what came of it'));
   console.log(
-    `  ${'stage'.padEnd(20)}${'runs'.padStart(6)}${'verdict'.padStart(9)}${'loop-back'.padStart(11)}` +
-      `${'rate'.padStart(7)}${'declared'.padStart(10)}${'unreadable'.padStart(12)}` +
-      `${'median'.padStart(9)}`,
+    dim(
+      `    ${'stage'.padEnd(20)}${'runs'.padStart(6)}${'verdict'.padStart(9)}${'loop-back'.padStart(11)}` +
+        `${'rate'.padStart(7)}${'declared'.padStart(10)}${'unreadable'.padStart(12)}` +
+        `${'median'.padStart(9)}`,
+    ),
   );
 
   const rows = [...byRole.entries()].sort((a, b) => b[1].n - a[1].n);
+  // Each stage's runs as one bar, as long as its share of the busiest stage's: what went forward, what
+  // was sent back, and what said nothing readable (or is still running).
+  const busiest = Math.max(...rows.map(([, s]) => s.n), 1);
+  const zero = (text, n) => (n === 0 ? dim(text) : text);
   for (const [role, s] of rows) {
+    const runsBar = stacked(
+      [
+        { n: s.clear - s.loop, char: '█', paint: pink },
+        { n: s.loop, char: '▓', paint: amber },
+        { n: s.n - s.clear, char: '░', paint: dim },
+      ],
+      Math.max(1, Math.round((16 * s.n) / busiest)),
+    );
+    const declared = pct(s.declared, s.done).padStart(10);
+    const unread = pct(s.unclear, s.done).padStart(12);
     console.log(
-      `  ${role.padEnd(20)}${String(s.n).padStart(6)}${String(s.clear).padStart(9)}` +
-        `${String(s.loop).padStart(11)}${pct(s.loop, s.clear).padStart(7)}` +
-        `${pct(s.declared, s.done).padStart(10)}${pct(s.unclear, s.done).padStart(12)}` +
-        `${medianMin(s.durations).padStart(9)}`,
+      `    ${pink(role)}${' '.repeat(Math.max(20 - role.length, 1))}${String(s.n).padStart(6)}${String(s.clear).padStart(9)}` +
+        `${zero(String(s.loop).padStart(11), s.loop)}${zero(pct(s.loop, s.clear).padStart(7), s.loop)}` +
+        `${s.declared < s.done ? amber(declared) : dim(declared)}${s.unclear > 0 ? amber(unread) : dim(unread)}` +
+        `${medianMin(s.durations).padStart(9)}  ${runsBar}`,
     );
   }
+  console.log(dim(`    ${' '.repeat(86)}█ forward  ▓ sent back  ░ no verdict read`));
 
   const unreadable = rows.reduce((a, [, s]) => a + s.unclear, 0);
   const done = rows.reduce((a, [, s]) => a + s.done, 0);
+  console.log('');
   console.log(
-    `\n  ${pct(unreadable, done)} of finished runs report no machine-readable verdict.` +
-      ' Those stages need a verdict token on the report\'s first line.',
+    unreadable === 0
+      ? note("every finished run's verdict could be read.", 'ok')
+      : note(`${pct(unreadable, done)} of finished runs report no machine-readable verdict. Those stages need a verdict token on the report's first line.`, 'warn'),
   );
 
   // Whether the stages that send work back say what they send back. Counted only over reports read
@@ -587,8 +617,7 @@ export async function stats(argv, ctx) {
   if (named.length > 0) {
     const withIds = named.filter((r) => r.issues > 0).length;
     console.log(
-      `  ${withIds} of ${named.length} declared loop-back(s) (${pct(withIds, named.length)}) named their issues` +
-        ' on the `ISSUES` line under the verdict.',
+      note(`${withIds} of ${named.length} declared loop-back(s) (${pct(withIds, named.length)}) named their issues on the \`ISSUES\` line under the verdict.`, withIds < named.length ? 'warn' : 'ok'),
     );
   }
 
@@ -600,9 +629,11 @@ export async function stats(argv, ctx) {
     for (const r of withSkills) for (const k of r.skills) tally.set(k, (tally.get(k) ?? 0) + 1);
     const list = [...tally].sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ×${n}`);
     console.log(
-      `  ${withSkills.length} of ${observable} runs with a readable transcript` +
-        ` (${pct(withSkills.length, observable)}) invoked a Skill` +
-        (list.length > 0 ? ` — ${list.join(', ')}` : ' — none at all'),
+      note(
+        `${withSkills.length} of ${observable} runs with a readable transcript (${pct(withSkills.length, observable)}) invoked a Skill` +
+          (list.length > 0 ? ` — ${list.join(', ')}` : ' — none at all'),
+        withSkills.length === 0 ? 'warn' : 'info',
+      ),
     );
   }
 
@@ -617,7 +648,8 @@ export async function stats(argv, ctx) {
       others.reduce((a, [, o]) => a + o.clear, 0),
     );
     console.log(
-      `  ${role}: ${s.loop} loop-back(s) in ${s.clear} readable verdict(s) (${pct(s.loop, s.clear)}),` +
+      note(
+      `${role}: ${s.loop} loop-back(s) in ${s.clear} readable verdict(s) (${pct(s.loop, s.clear)}),` +
         ` against ${elsewhere} across the other gates — check whether it still gates anything.` +
         (s.n - s.clear > 0
           ? ` ${s.n - s.clear} further run(s) produced no readable verdict at all, so the rate may understate it.`
@@ -627,6 +659,8 @@ export async function stats(argv, ctx) {
         (s.declared < s.clear
           ? ` Only ${s.declared} of the ${s.clear} were declared by the stage; the rest were inferred from its report.`
           : ''),
+      'warn',
+      ),
     );
   }
 
@@ -642,30 +676,31 @@ export async function stats(argv, ctx) {
   const newest = pills.dates.at(-1);
   const inWindow = pills.dates.filter((d) => d >= span[0] && d <= span[1]).length;
 
-  console.log('\n  learning');
+  console.log(heading('learning', 'what the loop-backs taught, and what became a rule'));
   if (pills.total === 0) {
-    console.log(
-      `    ${loopBacks} loop-back(s) and not one pill — either nothing was learned, or nothing was written down.`,
-    );
+    console.log(note(`${loopBacks} loop-back(s) and not one pill — either nothing was learned, or nothing was written down.`, loopBacks > 0 ? 'warn' : 'info'));
   } else {
     console.log(
-      // A share over 100% says nothing: the pills were written for something other than these loop-backs.
-      `    ${loopBacks} loop-back(s) in the window → ${inWindow} pill(s) written${inWindow <= loopBacks ? ` (${pct(inWindow, loopBacks)})` : ''}` +
-        ' — every loop-back is looked at for a lesson; `nina learn` shows which roles are owed one.' +
-        (pills.undated > 0 ? ` ${pills.undated} pill(s) carry no date and cannot be placed.` : ''),
+      note(
+        // A share over 100% says nothing: the pills were written for something other than these loop-backs.
+        `${loopBacks} loop-back(s) in the window → ${inWindow} pill(s) written${inWindow <= loopBacks ? ` (${pct(inWindow, loopBacks)})` : ''}` +
+          ' — every loop-back is looked at for a lesson; `nina learn` shows which roles are owed one.' +
+          (pills.undated > 0 ? ` ${pills.undated} pill(s) carry no date and cannot be placed.` : ''),
+      ),
     );
     console.log(
       pills.retired === 0
-        ? `    0 of ${pills.total} pill(s) retired — no correction has ever graduated into a rule.`
-        : `    ${pills.retired} of ${pills.total} pill(s) retired into a rule.`,
+        ? note(`0 of ${pills.total} pill(s) retired — no correction has ever graduated into a rule.`, 'warn')
+        : note(`${pills.retired} of ${pills.total} pill(s) retired into a rule.`, 'ok'),
     );
     if (newest) {
       const since = records.filter((r) => String(r.ts).slice(0, 10) > newest).length;
-      if (since > 0) console.log(`    ${since} dispatch(es) since the newest pill (${newest}).`);
+      if (since > 0) console.log(note(`${since} dispatch(es) since the newest pill (${newest}).`));
     }
   }
   for (const name of pills.unresolved) {
-    console.log(`    ${name} could not be located on disk, so its pills are not counted.`);
+    console.log(note(`${name} could not be located on disk, so its pills are not counted.`, 'warn'));
   }
+  console.log('');
   return 0;
 }