skalpel 4.0.53 → 4.0.55

package/analytics.mjs

@@ -40,6 +40,18 @@ import { emitKeypressEvents } from "node:readline";
 // nothing (their CLI blocks are isMain-guarded).
 import { readLedgerRows, buildLedger, formatDuration } from "./ledger.mjs";
 import { VERIFY_LOG_PATH, extractFailCount } from "./verify-shadow.mjs";
+// Terminal-feel helpers (TTY-only; see termfx.mjs restraint contract). None of this runs on the
+// non-TTY path — pipes/CI still get renderStatic byte-identical to before.
+import {
+  animEnabled,
+  sleep,
+  countUpFrames,
+  trustModel,
+  trustBar,
+  STAGGER_MS,
+  COUNT_MS,
+  COUNT_FRAMES,
+} from "./termfx.mjs";
 
 // ---------- palette (the same vocabulary as ledger.mjs / card.mjs / the statusline) ----------
 const R = "\x1b[38;2;233;38;31m"; // skalpel red
@@ -219,12 +231,14 @@ export function collectData({
 }
 
 // ---------- (2) panel text (shared by the static snapshot and the interactive view) ----------
-function costLine(data) {
+// msShown lets the TTY count-up render intermediate values of the SAME real measurement; every
+// other caller (renderStatic included) uses the default — the exact measured total, unchanged.
+function costLine(data, msShown = data.costMs) {
   if (data.ledger == null) return "no data yet";
   if (data.catches.length === 0) return "0 — nothing to measure";
   if (data.costPairs === 0)
     return `no measured red→green pair yet — ${data.catches.length} caught, none re-passed its own proof later (count only, nothing estimated)`;
-  const dur = formatDuration(data.costMs) || "<1s";
+  const dur = formatDuration(msShown) || "<1s";
   const excl =
     data.unmeasured > 0
       ? ` · ${data.unmeasured} caught without a later PASS — excluded, never estimated`
@@ -366,8 +380,54 @@ function wrapText(text, width) {
   return out.length ? out : [""];
 }
 
-function listLines(data, cols, rows, state) {
+// ---- interactive-only line builders (TTY view; the static snapshot above is untouched) ----
+// The two headline-counter lines take a "shown" value so the opening count-up can render
+// intermediate frames of the SAME real number. Every non-animated caller passes the real value.
+function caughtLiesLine(data, falseShown) {
+  const headline =
+    data.ledger == null
+      ? `${DIM}no data yet${RESET}`
+      : `${R}${BOLD}${falseShown} verified FALSE${RESET} ${DIM}· ${data.ledger.checked} done-claims checked${RESET}`;
+  return `  ${CYAN}${BOLD}CAUGHT LIES${RESET}     ${headline}`;
+}
+
+function measuredCostLine(data, msShown) {
+  return `  ${CYAN}${BOLD}MEASURED COST${RESET}   ${DIM}${costLine(data, msShown)}${RESET}`;
+}
+
+// TRUST — honest gamification, interactive header only (the non-TTY snapshot stays byte-identical).
+// Derived ONLY from real ledger counts via trustModel: held/checked ratio bar at ≥5 checked, counts
+// only below 5, and an honest em-dash zero-state — never a fake full bar, no scores, no streaks.
+export function trustLineFor(data) {
+  const m = trustModel(
+    data.ledger ? data.ledger.checked : 0,
+    data.ledger ? data.ledger.falseCount : 0,
+  );
+  const label = `  ${CYAN}${BOLD}TRUST${RESET}           `;
+  if (m.kind === "none") return `${label}${DIM}— no claims checked yet${RESET}`;
+  const caught = m.caught > 0 ? ` ${R}· ${m.caught} caught${RESET}` : "";
+  const counts = `${CYAN}${m.held}${RESET} ${DIM}of${RESET} ${CYAN}${m.checked}${RESET} ${DIM}done-claim${m.checked === 1 ? "" : "s"} held${RESET}`;
+  if (m.kind === "counts") return `${label}${counts}${caught}`;
+  const bar = `${"▰".repeat(m.filled)}${DIM}${"▱".repeat(m.total - m.filled)}${RESET}`;
+  return `${label}${bar} ${counts}${caught}`;
+}
+
+// listLines(data, cols, rows, state, meta) — the interactive list view. `meta`, when given, is
+// filled with what the ONE-TIME opening reveal needs: section boundaries (groupEnds) and the row
+// indices of the two count-up lines. Passing meta changes NOTHING about the returned lines.
+export function listLines(data, cols, rows, state, meta = null) {
   const L = [];
+  const noteAnim = (key, val) => {
+    if (meta) meta[key] = val;
+  };
+  const endGroup = () => {
+    if (meta) meta.groupEnds.push(L.length - 1);
+  };
+  if (meta) {
+    meta.groupEnds = [];
+    meta.animHead = -1;
+    meta.animCost = -1;
+  }
   L.push(`  ${BOLD}🔬 skalpel analytics${RESET} ${DIM}· local · read-only · your own logs${RESET}`);
   L.push(`  ${DIM}${"─".repeat(Math.max(4, Math.min(74, cols - 4)))}${RESET}`);
   if (data.empty) {
@@ -386,11 +446,10 @@ function listLines(data, cols, rows, state) {
     L.push(`  ${DIM}q quit${RESET}`);
     return L;
   }
-  const headline =
-    data.ledger == null
-      ? `${DIM}no data yet${RESET}`
-      : `${R}${BOLD}${data.ledger.falseCount} verified FALSE${RESET} ${DIM}· ${data.ledger.checked} done-claims checked${RESET}`;
-  L.push(`  ${CYAN}${BOLD}CAUGHT LIES${RESET}     ${headline}`);
+  L.push(trustLineFor(data));
+  endGroup(); // reveal group 1: title + rule + TRUST
+  if (data.ledger != null && data.ledger.falseCount > 0) noteAnim("animHead", L.length);
+  L.push(caughtLiesLine(data, data.ledger ? data.ledger.falseCount : 0));
   // The navigable list — window it so the selection is always visible.
   const fixedBelow = 6; // cost + steers + trend + rule + footer + breathing room
   const capacity = Math.max(0, rows - L.length - fixedBelow);
@@ -414,9 +473,12 @@ function listLines(data, cols, rows, state) {
   } else if (n > 0) {
     L.push(`     ${DIM}${n} caught — terminal too small to list; drill with Enter${RESET}`);
   }
-  L.push(`  ${CYAN}${BOLD}MEASURED COST${RESET}   ${DIM}${costLine(data)}${RESET}`);
+  endGroup(); // reveal group 2: the CAUGHT LIES block
+  if (data.costPairs > 0) noteAnim("animCost", L.length);
+  L.push(measuredCostLine(data, data.costMs));
   L.push(`  ${CYAN}${BOLD}STEERS APPLIED${RESET}  ${DIM}${steersLine(data)}${RESET}`);
   L.push(`  ${CYAN}${BOLD}RE-ASK TREND${RESET}    ${trendLine(data, Math.max(4, cols - 46))}`);
+  endGroup(); // reveal group 3: the three measured panels
   L.push(`  ${DIM}${"─".repeat(Math.max(4, Math.min(74, cols - 4)))}${RESET}`);
   L.push(`  ${DIM}↑/↓ j/k move · Enter details · q quit${RESET}`);
   return L;
@@ -470,6 +532,10 @@ function runInteractive(data) {
   const state = { view: "list", sel: 0, scroll: 0 };
   let cleaned = false;
   let pendingDraw = null;
+  // The ONE-TIME opening reveal (termfx contract: ≤ ~450ms total, once per invocation, ease-out).
+  // Any keypress or resize during it sets `skip` — the reveal aborts at its next beat and hands the
+  // screen to a normal instant draw(), so the user is never made to wait on an animation.
+  const reveal = { active: false, skip: false };
 
   // ONE cleanup, idempotent, never throws — every exit path funnels through it.
   const cleanup = () => {
@@ -560,6 +626,12 @@ function runInteractive(data) {
 
     // Coalesce resize bursts through ONE unref'd immediate — event-driven, never a poll loop.
     const scheduleDraw = () => {
+      if (reveal.active) {
+        // Mid-reveal input/resize: don't interleave a full redraw with the reveal's writes — flag
+        // it; the reveal aborts at its next beat and finishes with ONE instant draw() itself.
+        reveal.skip = true;
+        return;
+      }
       if (pendingDraw) return;
       pendingDraw = setImmediate(() => {
         pendingDraw = null;
@@ -606,7 +678,90 @@ function runInteractive(data) {
     process.stdout.on("resize", scheduleDraw); // node's SIGWINCH surface
     process.on("SIGWINCH", scheduleDraw); // belt-and-suspenders (no-op where unsupported)
 
-    draw();
+    // openingReveal — REVEAL, not decoration, and only ever ONCE, on open:
+    //   • sections land top-to-bottom, one write per section, one ~65ms beat between them
+    //     (write, small sleep, write — no redraws);
+    //   • the two headline counters (caught lies, measured cost) count up 0 → the REAL value in one
+    //     shared ~250ms ease-out pass (9 frames; the final frame is the exact real number — the
+    //     intermediate frames are pacing of the same measured value, never a different number);
+    //   • total time-to-full-render ≈ 445ms; any key/resize aborts straight to an instant draw().
+    // Every later render (selector moves, drill-in, resize) is today's instant full draw().
+    const openingReveal = async () => {
+      reveal.active = true;
+      const finish = () => {
+        reveal.active = false;
+        if (reveal.skip) {
+          reveal.skip = false;
+          draw(); // apply whatever the mid-reveal keypress/resize changed — instantly, exact values
+        }
+      };
+      const cols = Math.max(10, process.stdout.columns || 80);
+      const rowsN = Math.max(3, process.stdout.rows || 24);
+      const meta = { groupEnds: [], animHead: -1, animCost: -1 };
+      const lines = listLines(data, cols, rowsN, state, meta).slice(0, rowsN);
+      const clip = (l) => clipAnsi(l, cols - 1);
+      const lineAt = (i, headV, costV) =>
+        i === meta.animHead
+          ? clip(caughtLiesLine(data, headV))
+          : i === meta.animCost
+            ? clip(measuredCostLine(data, costV))
+            : clip(lines[i]);
+      // Section groups from listLines' own boundaries (header / caught-lies / panels / footer).
+      const ends = meta.groupEnds.filter((e) => e >= 0 && e < lines.length);
+      const groups = [];
+      let g0 = 0;
+      for (const e of ends) {
+        if (e + 1 > g0) {
+          groups.push([g0, e + 1]);
+          g0 = e + 1;
+        }
+      }
+      if (g0 < lines.length) groups.push([g0, lines.length]);
+      process.stdout.write("\x1b[H\x1b[2J");
+      for (let gi = 0; gi < groups.length; gi++) {
+        if (reveal.skip) return finish();
+        const [a, b] = groups[gi];
+        let chunk = "";
+        for (let i = a; i < b; i++) chunk += lineAt(i, 0, 0) + (i < lines.length - 1 ? "\r\n" : "");
+        process.stdout.write(chunk);
+        if (gi < groups.length - 1) await sleep(STAGGER_MS);
+      }
+      // A counter line that fell below a too-short screen (the rowsN slice) must not be addressed —
+      // writing past the last row would scroll/clobber the footer on some terminals.
+      const doHead = meta.animHead >= 0 && meta.animHead < lines.length;
+      const doCost = meta.animCost >= 0 && meta.animCost < lines.length;
+      if (doHead || doCost) {
+        const headSeq = countUpFrames(data.ledger ? data.ledger.falseCount : 0, COUNT_FRAMES);
+        const costSeq = countUpFrames(data.costMs, COUNT_FRAMES);
+        const stepMs = Math.max(1, Math.round(COUNT_MS / (COUNT_FRAMES - 1)));
+        for (let f = 1; f < COUNT_FRAMES; f++) {
+          // frame 0 (both counters at 0) was written by the section reveal itself
+          if (reveal.skip) return finish();
+          await sleep(stepMs);
+          let buf = "";
+          if (doHead)
+            buf += `\x1b[${meta.animHead + 1};1H\x1b[2K` + lineAt(meta.animHead, headSeq[f], 0);
+          if (doCost)
+            buf += `\x1b[${meta.animCost + 1};1H\x1b[2K` + lineAt(meta.animCost, 0, costSeq[f]);
+          process.stdout.write(buf);
+        }
+      }
+      finish();
+    };
+
+    if (animEnabled(process.stdout) && !data.empty && state.view === "list") {
+      openingReveal().catch(() => {
+        // Any reveal hiccup degrades to the plain instant render — never a broken screen.
+        reveal.active = false;
+        try {
+          draw();
+        } catch {
+          die("skalpel analytics — could not render analytics");
+        }
+      });
+    } else {
+      draw();
+    }
   } catch {
     die("skalpel analytics — could not render analytics");
   }

package/catches.mjs

@@ -44,6 +44,9 @@ import {
 // never drift. (This module keeps only the Claude-native loader below.)
 import { loadCodexEntries } from "./codex-normalize.mjs";
 import { recordInsight } from "./insights.mjs";
+// TTY-only presentation of the SAME rendered text (see termfx.mjs restraint contract). The non-TTY
+// path below never touches this — pipes/CI output stays byte-identical.
+import { animEnabled, writeWithHeartbeat } from "./termfx.mjs";
 
 const HOME = homedir();
 const CLAUDE_PROJECTS = path.join(HOME, ".claude", "projects");
@@ -368,7 +371,11 @@ const isMain = (() => {
 if (isMain) {
   try {
     const result = runScan();
-    process.stdout.write(renderReport(result) + "\n");
+    const out = renderReport(result) + "\n";
+    // TTY only: the 🔬 headline lands with one dim→bold beat (~120ms, a single \r rewrite of the
+    // SAME text). Non-TTY — and NO_COLOR / TERM=dumb / SKALPEL_NO_ANIM — write today's exact bytes.
+    if (animEnabled(process.stdout)) await writeWithHeartbeat(process.stdout, out);
+    else process.stdout.write(out);
     // MEASURABLE (local only, no network): record the honest fire-frequency for THIS user — how many
     // recent sessions were scanned and how many genuine catches were found. Never fabricated.
     try {

package/ledger.mjs

@@ -36,6 +36,9 @@ import { cleanText } from "./insights.mjs";
 // READ-ONLY reuse of the shadow's single-sourced log path + its honest fail-count extractor. Importing
 // verify-shadow.mjs runs no side effects (its CLI block is guarded on isMain) and modifies nothing there.
 import { VERIFY_LOG_PATH, extractFailCount } from "./verify-shadow.mjs";
+// TTY-only presentation of the SAME rendered text (see termfx.mjs restraint contract). The non-TTY
+// path below never touches this — pipes/CI output stays byte-identical.
+import { animEnabled, writeWithHeartbeat } from "./termfx.mjs";
 
 // ---------- (1) read the append-only history (verify-shadow.log) ----------
 // One NDJSON row per logged claim:
@@ -336,7 +339,11 @@ if (isMain) {
     const logPath = process.env.SKALPEL_LEDGER_LOG || VERIFY_LOG_PATH;
     const rows = readLedgerRows(logPath);
     const ledger = rows == null ? null : buildLedger(rows);
-    process.stdout.write(renderLedger(ledger, { logPath }) + "\n");
+    const out = renderLedger(ledger, { logPath }) + "\n";
+    // TTY only: the 🔬 headline lands with one dim→bold beat (~120ms, a single \r rewrite of the
+    // SAME text). Non-TTY — and NO_COLOR / TERM=dumb / SKALPEL_NO_ANIM — write today's exact bytes.
+    if (animEnabled(process.stdout)) await writeWithHeartbeat(process.stdout, out);
+    else process.stdout.write(out);
   } catch {
     // READ-ONLY + fail-open: never throw at the user.
     process.stdout.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "4.0.53",
+  "version": "4.0.55",
   "description": "Behavioral graph for AI-assisted coding — learns how you work and steers Claude Code + Codex in real time.",
   "type": "module",
   "bin": {

package/skalpel-statusline.mjs

@@ -345,10 +345,10 @@ function compactMeasured(ms) {
 // This always-on aggregate counter is an EXPLICIT PRODUCT DECISION by the owner: it is skalpel's terminal
 // presence and must never be gated/hidden ("never remove it from the terminal otherwise skalpel is
 // invisible"). Aggregate-only + no fabrication is what keeps that always-on surface honest.
-function measuredCaughtTotalMs() {
+function shadowTally() {
   try {
     const lines = tailLines(VERIFY_LOG_PATH, SHADOW_READ_BYTES);
-    if (!lines.length) return 0;
+    if (!lines.length) return { totalMs: 0, checked: 0, lies: 0 };
     const rows = [];
     for (const l of lines) {
       try {
@@ -362,14 +362,25 @@ function measuredCaughtTotalMs() {
     // O(falseCount × rows) that re-scanned every row for each catch on EVERY bar render.
     const fixDeltaFor = buildFixDeltas(rows);
     let total = 0;
+    // The HEARTBEAT counts (same single pass — zero extra I/O on the bar's hot path):
+    //   checked — claims the shadow got a GENUINE verdict for (its own proof/probe really ran: PASS /
+    //             GENUINE_FAIL / SHIP_OK / SHIP_FAIL). HARNESS_ERROR rows are logged but NOT counted —
+    //             identical to the ledger's "unverifiable" rule: we never claim a check we can't stand
+    //             behind. So a fresh install (or harness-noise-only log) keeps checked = 0.
+    //   lies    — the caught-false subset (mismatch === true), the money metric.
+    const CHECKED = new Set(["PASS", "GENUINE_FAIL", "SHIP_OK", "SHIP_FAIL"]);
+    let checked = 0;
+    let lies = 0;
     for (const r of rows) {
+      if (CHECKED.has(r.outcome)) checked += 1;
       if (r.mismatch !== true) continue; // only a caught false "done" (verify-shadow's money metric)
+      lies += 1;
       const d = fixDeltaFor(r); // exact ledger.mjs logic; null-session rows excluded (Finding 3)
       if (d && Number.isFinite(d.ms) && d.ms > 0) total += d.ms; // real measured delta only; else +0
     }
-    return total;
+    return { totalMs: total, checked, lies };
   } catch {
-    return 0; // any error → no measured total (fail-open: never break or slow the bar)
+    return { totalMs: 0, checked: 0, lies: 0 }; // fail-open: never break or slow the bar
   }
 }
 
@@ -435,10 +446,23 @@ function main() {
   //   • Raahil's `~`-prefixed saved ESTIMATE ("· ~7m saved") — shown only when saved_min > 0 (its data is
   //     the user's own steers.ndjson credit, not the shadow log, so it keeps his always-on #609 behavior).
   const { steers, savedMin } = readState();
+  const tally = SHOW_MEASURED ? shadowTally() : { totalMs: 0, checked: 0, lies: 0 };
   let line = `${BOLD}skalpel${RESET} · ${CYAN}${steers} steers${RESET}`;
   if (SHOW_MEASURED) {
-    const caught = compactMeasured(measuredCaughtTotalMs()); // null when < 1s of real measured catches
+    const caught = compactMeasured(tally.totalMs); // null when < 1s of real measured catches
     if (caught) line += ` · ${CYAN}${caught} caught${RESET}`;
+    // THE HEARTBEAT (founder: "I only see 0 steers — the product is invisible while it works").
+    // Once the armed shadow has genuinely CHECKED at least one claim, the line SHOWS the work:
+    //   clean so far → "· 3 claims verified"    (the earned-silence receipt — real verdicts only)
+    //   lies caught  → "· 31 checked · 2 false" (the honest split; the measured clause carries the time)
+    // Real counts from the same single log pass. A fresh install (checked = 0) emits EXACTLY the
+    // baseline line — byte-identical, nothing invented.
+    if (tally.checked > 0) {
+      line +=
+        tally.lies > 0
+          ? ` · ${CYAN}${tally.checked} checked · ${tally.lies} false${RESET}`
+          : ` · ${CYAN}${tally.checked} claim${tally.checked === 1 ? "" : "s"} verified${RESET}`;
+    }
   }
   if (SHOW_SAVED) {
     const phrase = savedPhrase(savedMin);

package/termfx.mjs

@@ -0,0 +1,103 @@
+// termfx.mjs — terminal-feel helpers for skalpel's USER-INVOKED surfaces (analytics/ledger/catches).
+//
+// RESTRAINT CONTRACT (why every function here is safe):
+//   • REVEAL, NOT DECORATION. Motion runs ONCE per invocation, ease-out, and the sum of it is well
+//     under half a second. No loops, no spinners, nothing that repeats.
+//   • NEVER THE HOT PATH. Nothing in this module is imported by skalpel-hook.mjs,
+//     skalpel-statusline.mjs, or verify-shadow.mjs — it exists only for user-invoked subcommands
+//     spawned from the package dir (skalpel-setup.mjs), so the per-turn cost is exactly zero.
+//   • NEVER A FABRICATED NUMBER. Helpers here only PACE or SHAPE real values computed elsewhere:
+//     countUpFrames ends on the exact real value; trustModel is pure arithmetic over real ledger
+//     counts (and refuses to draw a ratio bar on fewer than 5 checked claims — counts only).
+//   • RESPECT THE TERMINAL. animEnabled() is false for any non-TTY stream (pipes/CI stay
+//     byte-identical to the static render), and for NO_COLOR, TERM=dumb, or SKALPEL_NO_ANIM —
+//     those get today's plain render with zero timing or cursor-movement artifacts.
+//   • NODE CORE ONLY. No dependency, no side effects at import.
+
+export const STAGGER_MS = 65; // one beat between revealed sections (60-80ms band)
+export const COUNT_MS = 250; // total counter run — 0 → real value, ease-out
+export const COUNT_FRAMES = 9; // 8-10 frames; final frame is ALWAYS the exact real number
+export const HEARTBEAT_MS = 120; // dim → bold beat on the 🔬 headline
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// animEnabled(stream, env) — the single gate every animation must pass. TTY only; any of the
+// standard opt-outs (NO_COLOR non-empty, TERM=dumb, SKALPEL_NO_ANIM set) disables motion entirely.
+export function animEnabled(stream = process.stdout, env = process.env) {
+  if (!stream || stream.isTTY !== true) return false;
+  if (env.NO_COLOR != null && env.NO_COLOR !== "") return false;
+  if ((env.TERM || "") === "dumb") return false;
+  const noAnim = env.SKALPEL_NO_ANIM;
+  if (noAnim != null && noAnim !== "" && noAnim !== "0") return false;
+  return true;
+}
+
+// countUpFrames(final, frames) — the integer values a counter shows on its way from 0 to the real
+// value. Cubic ease-out (fast start, gentle landing), monotone non-decreasing, and the LAST frame
+// is the exact real number — an intermediate frame may round, the landing never does.
+export function countUpFrames(final, frames = COUNT_FRAMES) {
+  const n = Math.max(2, Math.floor(frames));
+  const target = Number.isFinite(final) && final > 0 ? final : 0;
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    if (i === n - 1) {
+      out.push(target);
+      continue;
+    }
+    const t = i / (n - 1);
+    const eased = 1 - Math.pow(1 - t, 3);
+    out.push(Math.min(target, Math.round(target * eased)));
+  }
+  return out;
+}
+
+// trustModel(checked, falseCount) — the HONEST trust line, derived ONLY from real ledger counts.
+//   checked    = done-claims that got a genuine re-run verdict (verified PASS or caught FALSE)
+//   falseCount = the caught lies among them
+// Returns one of:
+//   { kind: "none" }                              — zero history: never a fake full bar
+//   { kind: "counts", held, checked, caught }     — fewer than 5 checked: counts only, no ratio bar
+//   { kind: "bar", held, checked, caught, filled, total } — ratio bar; filled === total ONLY when
+//     every checked claim held (a 99% ratio floors to at most total-1 — the bar can never flatter).
+export const TRUST_BAR_SEGMENTS = 8;
+export function trustModel(checked, falseCount) {
+  const c = Number.isFinite(checked) && checked > 0 ? Math.floor(checked) : 0;
+  if (c <= 0) return { kind: "none", checked: 0, held: 0, caught: 0 };
+  const rawCaught = Number.isFinite(falseCount) && falseCount > 0 ? Math.floor(falseCount) : 0;
+  const caught = Math.min(rawCaught, c); // FALSE ⊆ checked — clamp a pathological log, never invent
+  const held = c - caught;
+  if (c < 5) return { kind: "counts", checked: c, held, caught };
+  const total = TRUST_BAR_SEGMENTS;
+  const filled = held === c ? total : Math.min(total - 1, Math.floor((held / c) * total));
+  return { kind: "bar", checked: c, held, caught, filled, total };
+}
+
+// trustBar(model) — the plain glyphs for a { kind: "bar" } model ("▰▰▰▰▰▰▱▱"). Color is the
+// caller's job (the empty tail reads dim in analytics); the shape is shared so tests pin it.
+export function trustBar(model) {
+  if (!model || model.kind !== "bar") return "";
+  return "▰".repeat(model.filled) + "▱".repeat(model.total - model.filled);
+}
+
+// writeWithHeartbeat(stream, text) — the 🔬 headline lands with a single beat: the line prints dim,
+// holds ~120ms, then is re-printed bold over itself with ONE carriage-return rewrite (identical
+// text, identical width — a heartbeat, not a typewriter). Everything before and after the headline
+// is written exactly as-is. No 🔬 line → the text is written unchanged.
+export async function writeWithHeartbeat(
+  stream,
+  text,
+  { ms = HEARTBEAT_MS, sleepFn = sleep } = {},
+) {
+  const s = String(text);
+  const lines = s.split("\n");
+  const idx = lines.findIndex((l) => l.includes("🔬"));
+  if (idx < 0) {
+    stream.write(s);
+    return;
+  }
+  if (idx > 0) stream.write(lines.slice(0, idx).join("\n") + "\n");
+  stream.write(`\x1b[2m${lines[idx]}\x1b[0m`); // dim, no newline — the cursor stays on the line
+  await sleepFn(ms);
+  stream.write(`\r\x1b[1m${lines[idx]}\x1b[0m\n`); // one \r rewrite, bold — the beat
+  stream.write(lines.slice(idx + 1).join("\n"));
+}