@hncode/hncode 0.5.0 → 0.5.2

package/src/memory-profile.js

@@ -0,0 +1,247 @@
+// Session memory profiler — where the bytes actually go.
+//
+// WHY THIS EXISTS
+// ---------------
+// Two questions came up that nothing here could answer: "why is the process using so much
+// memory", and "did the transcript-amplification fix actually save anything". Both are
+// unanswerable without knowing WHICH content is large, because "the session" is not one
+// thing — the same conversation exists in several forms at once:
+//
+//   * `session.messages`   what gets sent to the model (text + tool args + tool results)
+//   * `state.chat`         what the renderer draws (a DIFFERENT array of rows)
+//   * `session.transcript` the display-only record that is written to disk
+//
+// and within `messages` the bytes are not where a count of rows suggests. Measured on a
+// real 2.6 MB session: text was 0.28 MB, tool RESULTS 0.34 MB, and tool-call ARGUMENTS
+// 0.66 MB — the arguments, which no row count hints at, were more than everything else
+// combined. On that same session the serialised JSON was 2.29 MB while the sum of its
+// parts was 1.27 MB, so roughly as much again is STRUCTURE: keys, role tags, escaped
+// strings.
+//
+// Modelled on jcode's `jcode-base/src/session/memory_profile.rs`, which records the same
+// split plus the extremes (largest single block), because a profile without a maximum
+// hides the one item that actually caused the problem.
+//
+// Pure and read-only: it measures, it never trims, loads or rewrites anything.
+
+/** Content larger than this is counted separately — a single 16 KB block is the shape of
+ *  a runaway, while 16 KB spread evenly is nothing. */
+const LARGE_BLOB_BYTES = 16 * 1024;
+
+/** Byte size of a value as it would sit in memory: strings as-is, everything else as JSON. */
+function bytes(v) {
+  if (v == null) return 0;
+  if (typeof v === 'string') return Buffer.byteLength(v, 'utf8');
+  if (typeof v === 'number' || typeof v === 'boolean') return 8;
+  try { return Buffer.byteLength(JSON.stringify(v), 'utf8'); } catch { return 0; }
+}
+
+/** One accumulating bucket. Every measurement lands in exactly one category. */
+function bucket() {
+  return { bytes: 0, count: 0, max: 0 };
+}
+
+function add(b, n) {
+  b.bytes += n;
+  b.count += 1;
+  if (n > b.max) b.max = n;
+}
+
+const mb = (n) => (n / 1048576).toFixed(2);
+
+/**
+ * Profile the memory a session occupies, broken down by content type.
+ *
+ * @param {object} input
+ * @param {object} [input.session]   a loaded session ({ messages, transcript })
+ * @param {Array}  [input.chat]      `state.chat` — the renderer's rows, if present
+ * @param {object} [input.state]     the live TUI state, to measure chat and caches
+ * @returns {object} a plain report; see `renderMemoryProfile` for the human form
+ */
+export function profileMemory(input = {}) {
+  const session = input.session || {};
+  const messages = Array.isArray(session.messages) ? session.messages : [];
+  const transcript = Array.isArray(session.transcript) ? session.transcript : [];
+
+  // ---- session.messages, split by what the bytes are --------------------
+  const text = bucket();
+  const toolResults = bucket();
+  const toolArgs = bucket();
+  const images = bucket();
+  const argsByTool = new Map();
+
+  for (const m of messages) {
+    if (!m || typeof m !== 'object') continue;
+    const isResult = m.role === 'tool';
+    add(isResult ? toolResults : text, bytes(m.content));
+    // An image rides as a data: URL or a base64 field rather than in `content`, so it is
+    // measured separately — base64 inflates 4/3, and that is worth knowing.
+    const img = m.image || m.images || m.media;
+    if (img) add(images, bytes(img));
+    for (const tc of Array.isArray(m.toolCalls) ? m.toolCalls : []) {
+      if (!tc || typeof tc !== 'object') continue;
+      const n = bytes(tc.args);
+      add(toolArgs, n);
+      const name = String(tc.name || '?');
+      if (!argsByTool.has(name)) argsByTool.set(name, bucket());
+      add(argsByTool.get(name), n);
+    }
+  }
+
+  // ---- session.transcript, which is display-only and can dwarf everything
+  const transcriptByRole = new Map();
+  let transcriptBytes = 0;
+  let transcriptLarge = 0;
+  let transcriptMax = 0;
+  for (const e of transcript) {
+    const row = e && e.row;
+    if (!row) continue;
+    const n = bytes(row.text);
+    transcriptBytes += n;
+    if (n > transcriptMax) transcriptMax = n;
+    if (n >= LARGE_BLOB_BYTES) transcriptLarge += n;
+    const role = String(row.role || '?');
+    if (!transcriptByRole.has(role)) transcriptByRole.set(role, bucket());
+    add(transcriptByRole.get(role), n);
+  }
+
+  // ---- the renderer's copy ----------------------------------------------
+  // Derived from `messages` when the caller does not supply the live `state.chat`, so a
+  // profile of a session loaded off disk still accounts for what the renderer would build.
+  // `convRowFor` maps ONE message to rows, so it has to be applied per message — handing it
+  // the array returns a single empty row and the copy silently measured as zero, which is
+  // exactly what the first run of this printed.
+  let chat = Array.isArray(input.chat) ? input.chat : null;
+  if (!chat && input.state && Array.isArray(input.state.chat)) chat = input.state.chat;
+  if (!chat && messages.length && typeof input.convRowFor === 'function') {
+    chat = [];
+    for (const m of messages) {
+      const rows = input.convRowFor(m);
+      if (Array.isArray(rows)) chat.push(...rows);
+    }
+  }
+  chat = chat || [];
+  const chatBytes = chat.reduce((a, r) => a + bytes(r && r.text), 0);
+
+  // ---- what it costs as one JSON document -------------------------------
+  // Reported because it is usually the biggest single number and nobody expects it: the
+  // serialised form carries every key and escape, which no content sum shows.
+  let jsonBytes = 0;
+  try { jsonBytes = Buffer.byteLength(JSON.stringify({ messages, transcript }), 'utf8'); } catch { /* */ }
+
+  const contentBytes = text.bytes + toolResults.bytes + toolArgs.bytes + images.bytes;
+  const measured = contentBytes + transcriptBytes;
+
+  return {
+    messages: {
+      count: messages.length,
+      text,
+      toolResults,
+      toolArgs,
+      images,
+      argsByTool,
+      contentBytes,
+      // The gap between the parts and the document: keys, role tags, escapes, and the
+    // array/record overhead of 3000 messages each carrying a role and a shape.
+    structuralBytes: Math.max(0, jsonBytes - measured),
+    jsonBytes,
+  },
+    transcript: {
+      count: transcript.length,
+      bytes: transcriptBytes,
+      largeBytes: transcriptLarge,
+      maxRowBytes: transcriptMax,
+      byRole: transcriptByRole,
+    },
+    chat: { count: chat.length, bytes: chatBytes },
+    // The three forms coexist, so the process holds roughly all of them at once.
+    totalBytes: measured + chatBytes,
+    totals: { messages: contentBytes, transcript: transcriptBytes, chat: chatBytes },
+  };
+}
+
+/**
+ * The profile as lines for a panel or a tool result.
+ *
+ * @param {object} p      from profileMemory
+ * @param {object} [opts]
+ * @param {number} [opts.top]  how many rows of the per-tool table to show
+ * @param {boolean} [opts.verbose]  include the per-tool breakdown
+ */
+export function renderMemoryProfile(p, opts = {}) {
+  const lines = [];
+  const total = p.totalBytes || 0;
+  // The document size is reported in the same table, so it must NOT join the percentage
+  // base — it is a different measure of the same data (serialised vs in-memory), and
+  // including it produced totals over 100%.
+  const contentBase = (p.messages.contentBytes || 0) + (p.transcript.bytes || 0) + (p.chat.bytes || 0);
+  // Rounding to 2 places on a few HUNDRED bytes made "5 bytes / 5 bytes" print as
+  // 100.0% but a document row print 1280.0% — a percentage over 100 is never a real
+  // share, so it is clamped rather than trusted.
+  const pct = (n) => {
+    if (!contentBase || !n) return '';
+    const v = Math.min(100, (100 * n) / contentBase);
+    return ` ${v.toFixed(1)}%`.padStart(7);
+  };
+  const row = (label, b, n, share = true) => {
+    lines.push(`  ${label.padEnd(18)} ${mb(b).padStart(9)} MB${n != null ? `  x${n}` : ''}${share ? pct(b) : ''}`);
+  };
+
+  lines.push(`Memory profile — ${mb(total)} MB across the forms a session holds`);
+  lines.push('');
+  lines.push('  content (session.messages)');
+  row('text', p.messages.text.bytes, p.messages.text.count);
+  row('tool results', p.messages.toolResults.bytes, p.messages.toolResults.count);
+  row('tool arguments', p.messages.toolArgs.bytes, p.messages.toolArgs.count);
+  if (p.messages.images.bytes) row('images', p.messages.images.bytes, p.messages.images.count);
+
+  if (p.transcript.count) {
+    lines.push('');
+    lines.push('  transcript (display-only, on disk)');
+    row('all rows', p.transcript.bytes, p.transcript.count);
+    if (p.transcript.largeBytes) {
+      lines.push(`    of which >=16 KB:  ${mb(p.transcript.largeBytes).padStart(9)} MB`);
+    }
+    lines.push(`    largest row:     ${mb(p.transcript.maxRowBytes).padStart(9)} MB`);
+    if (opts.verbose) {
+      for (const [role, b] of [...p.transcript.byRole].sort((a, c) => c[1].bytes - a[1].bytes)) {
+        row(`    ${role}`, b.bytes, b.count);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('  other copies held at the same time');
+  row('state.chat (render)', p.chat.bytes, p.chat.count);
+
+  lines.push('');
+  lines.push('  as one JSON document (a different measure of the same data)');
+  // Measured against the CONTENT, not the content-plus-content the base holds, so these
+  // two rows carry no share: they re-measure what the rows above already report.
+  row('serialised size', p.messages.jsonBytes, null, false);
+  row('structure + escapes', p.messages.structuralBytes, null, false);
+  if (p.messages.structuralBytes > p.messages.contentBytes) {
+    lines.push('    (structure is larger than the content — that is normal for many short messages)');
+  }
+
+  if (opts.verbose && p.messages.argsByTool.size) {
+    lines.push('');
+    lines.push('  tool arguments by tool');
+    const rows = [...p.messages.argsByTool].sort((a, b) => b[1].bytes - a[1].bytes);
+    for (const [name, b] of (opts.top ? rows.slice(0, opts.top) : rows)) {
+      row(name, b.bytes, b.count);
+    }
+  }
+  return lines;
+}
+
+/**
+ * A short verdict, for a place that wants one line rather than a table.
+ * @returns {string}
+ */
+export function memoryHeadline(p) {
+  const total = mb(p.totalBytes);
+  const args = mb(p.messages.toolArgs.bytes);
+  const tr = p.transcript.count ? mb(p.transcript.bytes) : '0';
+  return `${total} MB total · text ${mb(p.messages.text.bytes)} · tool results ${mb(p.messages.toolResults.bytes)} · tool args ${args} · transcript ${tr}`;
+}

package/src/permissions.js

@@ -6,6 +6,10 @@
 // and loses the prompt for genuinely dangerous commands too. A rule set lets the
 // routine work through while the rest keeps asking.
 //
+// A `Bash(...)` prefix rule is matched against every segment of the line, not the
+// line as a whole, so allowing one command cannot smuggle in a second one.
+import { splitSegments } from './shell-safety.js';
+
 // Rule syntax (a subset of Claude Code's, chosen to stay readable):
 //   Bash                 — every Bash call
 //   Bash(npm run test)   — that exact command
@@ -76,17 +80,35 @@ export function ruleMatches(parsed, toolName, args) {
   const a = args || {};
   // Bash: the rule names a command. A trailing `*` means "starts with"; otherwise the
   // command must match exactly, so `Bash(rm -rf /)` cannot be widened by an argument.
+  //
+  // A prefix rule applies to EVERY segment, not just the line as a whole. Comparing
+  // the whole string made `Bash(npm test *)` allow `npm test && rm -rf /build`,
+  // because the line does start with the prefix — the second command was never
+  // looked at. `splitSegments` is the same splitter the destructive-command check
+  // uses, so `;`, `|`, `&`, `&&` and `||` all separate here too.
   if (toolName === 'Bash') {
-    const cmd = String(a.command || a.cmd || '').trim();
-    if (parsed.arg.endsWith('*')) {
-      const prefix = parsed.arg.slice(0, -1).trim();
-      return cmd === prefix || cmd.startsWith(prefix + ' ');
+    // A rule compares WORDS, so runs of whitespace collapse before comparing. Shell words are
+    // separated by one or more blanks and the count means nothing, so `git  status` and
+    // `git status` are the same command — but a raw string comparison treated them as different
+    // and silently skipped a rule the user had written, which is the "it still prompts even
+    // though I allowed it" report.
+    const squash = (s) => String(s).replace(/\s+/g, ' ').trim();
+    const cmd = squash(a.command || a.cmd || '');
+    const rule = squash(parsed.arg);
+    if (rule.endsWith('*')) {
+      const prefix = squash(rule.slice(0, -1));
+      const { segments } = splitSegments(cmd);
+      const parts = (segments.length ? segments : [cmd]).map(squash).filter(Boolean);
+      // Every segment must be covered. An empty command still falls back to the whole-string
+      // comparison rather than matching anything.
+      if (!parts.length) return cmd === prefix;
+      return parts.every((p) => p === prefix || p.startsWith(prefix + ' '));
     }
-    return cmd === parsed.arg;
+    return cmd === rule;
   }
 
-  // Path-taking tools: match any of the tool's path-ish arguments against the glob,
-  // so `Read(./src/**)` works whether the model sent `path` or `file_path`.
+  // Path-taking tools: match any of the tool's path-ish arguments against the glob, so
+  // `Read(./src/**)` works whether the model sent `path` or `file_path`.
   const names = PATH_ARGS[toolName] || ['path', 'file_path', 'pattern'];
   for (const n of names) {
     const v = a[n];

package/src/registry-browser.js

@@ -126,15 +126,30 @@ export function rowsForTab(state, tabId) {
     }));
   }
   if (tabId === 'ondisk') {
-    const loadedNames = new Set((d.loaded || []).map((p) => p.name));
+    // Match on the DIRECTORY a plugin was loaded from, not on the name it reports.
+    //
+    // A plugin declares its own `name`, and it need not match the directory it sits in. Comparing
+    // names meant any plugin where the two differed showed "Need Restart" forever: the name it
+    // reported could never equal the directory it was found under, so restarting never helped.
+    // `computer-use/` declaring `hncode-cu` is the ordinary case, not an oddity.
+    //
+    // `loaded` records each plugin with an `id` of `<dirname>/<entry>` while `onDisk` reports only a
+    // bare `name` (the directory, or the filename for a single-file plugin). The first segment of
+    // the id is therefore the thing to compare, and it covers both layouts: a directory's id starts
+    // with its directory name, and a single file's id IS its filename.
+    const loadedDirs = new Set();
+    const loadedNames = new Set();
+    for (const p of d.loaded || []) {
+      if (p.id) loadedDirs.add(String(p.id).split('/')[0]);
+      if (p.name) loadedNames.add(String(p.name));
+    }
+    const isLoaded = (p) => loadedDirs.has(String(p.name)) || loadedNames.has(String(p.name));
     return (d.onDisk || []).map((p) => ({
       name: p.name,
       label: p.name + (p.kind === 'dir' ? '/' : ''),
-      description: loadedNames.has(p.name)
-        ? 'loaded in this session'
-        : 'not loaded — Need Restart',
-      status: loadedNames.has(p.name) ? 'loaded' : 'Need Restart',
-      statusTone: loadedNames.has(p.name) ? 'ok' : 'warn',
+      description: isLoaded(p) ? 'loaded in this session' : 'not loaded — Need Restart',
+      status: isLoaded(p) ? 'loaded' : 'Need Restart',
+      statusTone: isLoaded(p) ? 'ok' : 'warn',
       action: 'remove-plugin',
     }));
   }

package/src/row-cache.js

@@ -1,143 +1,148 @@
-// A shared, bounded cache of rendered transcript rows.
-//
-// WHY THIS EXISTS
-// ---------------
-// Wrapping and markdown-rendering a message is the expensive half of every frame, and the
-// result depends only on (message text, width, colours) — so it is cacheable. The TUI
-// already cached it, but on the message object itself, which makes the cache a property of
-// the TRANSCRIPT rather than of the renderer:
-//
-//   * It was dropped by position, not by size. `CACHE_KEEP` counted messages from the
-//     tail, so a 4000-message session threw away the caches of the 3700 oldest messages
-//     while keeping the caches of 300 tiny ones — the window tracked message COUNT, not
-//     memory. Scrolling back into a long session re-rendered from scratch every time.
-//   * It could not survive a session switch, because it lived on messages that
-//     `reconstructChat` throws away and rebuilds from the log. Every `--continue` and
-//     every `/sessions` resume started with a cold cache, re-wrapping the whole
-//     transcript before the first frame.
-//   * It had two independent mechanisms — `m._cache` for the row list, `m._mdCache` for
-//     the markdown blocks — with separate lifetimes and no bound between them.
-//
-// A `Map` keyed by a string, with entries ordered by use, fixes all three: the bound is
-// real, the key survives any rebuild of the transcript, and both caches share one budget.
-//
-// THE KEY IS THE WHOLE POINT
-// --------------------------
-// A key that omitted a component of the layout would serve a row rendered for a different
-// width or colour — which is not a stale cache, it is a MISDRAWN frame. So the key spells
-// out everything the render depends on, and `makeRowKey` is the single place that decides
-// what "the same" means. `evictIfStale` is the second half of the same contract: a streamed
-// message's text grows every frame, so an entry whose text no longer matches is not a
-// reuse, and the cache has to notice rather than serve it.
-
-/** How many messages keep their rows. Chosen by measurement, not by feel: the rows for a
- *  typical assistant message are a few hundred bytes each, so 1500 covers a long session's
- *  visible history while staying in the low megabytes. */
-export const ROW_CACHE_LIMIT = 1500;
-
-/**
- * A cache key that identifies a rendered message.
- *
- * Every input the render reads goes in, so "the same key" means "the same rows":
- *   `id`  a stable identity for the message. Index-based ids break the moment a message
- *         is inserted or removed, which is exactly what compaction and /undo do.
- *   `text`  the content. Compared by VALUE, not by reference: a streamed message's
- *         `text` is replaced on every delta, and a reference check would miss every
- *         reuse after the first frame.
- *   `w`  the wrap width, `fg`/`codeFg` the colours, `expanded` the plugin-log toggle,
- *   `raw` the raw-mode flag, `pending`/`failed` the live-state flags, and `spin` the
- *   spinner key.
- */
-export function makeRowKey(parts) {
-  return [
-    parts.id,
-    parts.text == null ? '' : parts.text,
-    parts.w,
-    parts.fg,
-    parts.codeFg,
-    parts.expanded ? 1 : 0,
-    parts.raw ? 1 : 0,
-    parts.pending ? 1 : 0,
-    parts.failed ? 1 : 0,
-    parts.spin,
-  ].join('\x1f');
-}
-
-/**
- * The shared store.
- *
- * A single `Map` with insertion order: `Map` iterates in insertion order and `set` on an
- * existing key does NOT move it, so "touch on every read" has to be an explicit
- * delete-then-set. That is what makes it an LRU rather than a FIFO — and the difference
- * matters here, because the entries worth keeping are the ones being read, not the ones
- * written most recently.
- */
-const store = new Map();
-
-/** Hits and misses, so a caller can tell "the cache is not helping" from "there is
- *  nothing to cache" without instrumenting the renderer. */
-const stats = { hits: 0, misses: 0, evictions: 0 };
-
-export function cacheStats() {
-  return { ...stats, size: store.size };
-}
-
-/** For tests: a clean slate. */
-export function resetRowCache() {
-  store.clear();
-  stats.hits = 0;
-  stats.misses = 0;
-  stats.evictions = 0;
-}
-
-/**
- * Look up `key`, marking it as recently used.
- *
- * @returns the cached value, or undefined on a miss. Callers treat `undefined` as "render
- *   it" — a cache that cannot say "no" is not a cache.
- */
-export function rowCacheGet(key) {
-  if (!store.has(key)) { stats.misses++; return undefined; }
-  const v = store.get(key);
-  // Touch: re-insert so this key moves to the young end of the Map's iteration order.
-  store.delete(key);
-  store.set(key, v);
-  stats.hits++;
-  return v;
-}
-
-/**
- * Store `value` under `key` and enforce the bound.
- *
- * Eviction is oldest-first, and it is done HERE rather than by the caller counting
- * messages: the caller cannot know what the entries cost, and a message-count window
- * keeps a lot of large messages while discarding a lot of small ones.
- */
-export function rowCacheSet(key, value) {
-  // Re-inserting an existing key would leave the old entry in place, so drop it first —
-  // otherwise the bound could be evictions short of what it looks like.
-  store.delete(key);
-  store.set(key, value);
-  while (store.size > ROW_CACHE_LIMIT) {
-    // Map iteration is insertion order, so the first key is the least recently used.
-    const oldest = store.keys().next();
-    if (oldest.done) break;
-    store.delete(oldest.value);
-    stats.evictions++;
-  }
-  return value;
-}
-
-/**
- * Is `cached` still valid for `key`'s message?
- *
- * A separate question from `rowCacheGet`, because a message can change without its key
- * changing: a streamed reply's text is the key's own `text` component, so its key DOES
- * change — but the row COUNT memo does not carry the text, and that one has to be asked
- * whether the content moved. Kept as a function so the check is named at the call site
- * rather than being an open-coded `===` someone later widens by accident.
- */
-export function evictIfStale(entry, key) {
-  if (!entry) return true;
-  return entry.key !== key;
+// A shared, bounded cache of rendered transcript rows.
+//
+// WHY THIS EXISTS
+// ---------------
+// Wrapping and markdown-rendering a message is the expensive half of every frame, and the
+// result depends only on (message text, width, colours) — so it is cacheable. The TUI
+// already cached it, but on the message object itself, which makes the cache a property of
+// the TRANSCRIPT rather than of the renderer:
+//
+//   * It was dropped by position, not by size. `CACHE_KEEP` counted messages from the
+//     tail, so a 4000-message session threw away the caches of the 3700 oldest messages
+//     while keeping the caches of 300 tiny ones — the window tracked message COUNT, not
+//     memory. Scrolling back into a long session re-rendered from scratch every time.
+//   * It could not survive a session switch, because it lived on messages that
+//     `reconstructChat` throws away and rebuilds from the log. Every `--continue` and
+//     every `/sessions` resume started with a cold cache, re-wrapping the whole
+//     transcript before the first frame.
+//   * It had two independent mechanisms — `m._cache` for the row list, `m._mdCache` for
+//     the markdown blocks — with separate lifetimes and no bound between them.
+//
+// A `Map` keyed by a string, with entries ordered by use, fixes all three: the bound is
+// real, the key survives any rebuild of the transcript, and both caches share one budget.
+//
+// THE KEY IS THE WHOLE POINT
+// --------------------------
+// A key that omitted a component of the layout would serve a row rendered for a different
+// width or colour — which is not a stale cache, it is a MISDRAWN frame. So the key spells
+// out everything the render depends on, and `makeRowKey` is the single place that decides
+// what "the same" means. `evictIfStale` is the second half of the same contract: a streamed
+// message's text grows every frame, so an entry whose text no longer matches is not a
+// reuse, and the cache has to notice rather than serve it.
+
+/** How many messages keep their rows. Chosen by measurement, not by feel: the rows for a
+ *  typical assistant message are a few hundred bytes each, so 1500 covers a long session's
+ *  visible history while staying in the low megabytes. */
+export const ROW_CACHE_LIMIT = 1500;
+
+/**
+ * A cache key that identifies a rendered message.
+ *
+ * Every input the render reads goes in, so "the same key" means "the same rows":
+ *   `id`  a stable identity for the message. Index-based ids break the moment a message
+ *         is inserted or removed, which is exactly what compaction and /undo do.
+ *   `text`  the content. Compared by VALUE, not by reference: a streamed message's
+ *         `text` is replaced on every delta, and a reference check would miss every
+ *         reuse after the first frame.
+ *   `w`  the wrap width, `fg`/`codeFg` the colours, `expanded` the plugin-log toggle,
+ *   `raw` the raw-mode flag, `pending`/`failed` the live-state flags, and `spin` the
+ *   spinner key.
+ */
+export function makeRowKey(parts) {
+  return [
+    parts.id,
+    parts.text == null ? '' : parts.text,
+    parts.w,
+    parts.fg,
+    parts.codeFg,
+    parts.expanded ? 1 : 0,
+    parts.raw ? 1 : 0,
+    parts.pending ? 1 : 0,
+    parts.failed ? 1 : 0,
+    parts.spin,
+    // The palette. Cached rows are finished strings with their escapes already applied, so
+    // a theme switch has to miss every entry or the old colours come back. Without this a
+    // switched theme repainted the chrome (composed per frame) and left the transcript's
+    // own text in the previous palette — white words sitting in a gruvbox.
+    parts.theme || '',
+  ].join('\x1f');
+}
+
+/**
+ * The shared store.
+ *
+ * A single `Map` with insertion order: `Map` iterates in insertion order and `set` on an
+ * existing key does NOT move it, so "touch on every read" has to be an explicit
+ * delete-then-set. That is what makes it an LRU rather than a FIFO — and the difference
+ * matters here, because the entries worth keeping are the ones being read, not the ones
+ * written most recently.
+ */
+const store = new Map();
+
+/** Hits and misses, so a caller can tell "the cache is not helping" from "there is
+ *  nothing to cache" without instrumenting the renderer. */
+const stats = { hits: 0, misses: 0, evictions: 0 };
+
+export function cacheStats() {
+  return { ...stats, size: store.size };
+}
+
+/** For tests: a clean slate. */
+export function resetRowCache() {
+  store.clear();
+  stats.hits = 0;
+  stats.misses = 0;
+  stats.evictions = 0;
+}
+
+/**
+ * Look up `key`, marking it as recently used.
+ *
+ * @returns the cached value, or undefined on a miss. Callers treat `undefined` as "render
+ *   it" — a cache that cannot say "no" is not a cache.
+ */
+export function rowCacheGet(key) {
+  if (!store.has(key)) { stats.misses++; return undefined; }
+  const v = store.get(key);
+  // Touch: re-insert so this key moves to the young end of the Map's iteration order.
+  store.delete(key);
+  store.set(key, v);
+  stats.hits++;
+  return v;
+}
+
+/**
+ * Store `value` under `key` and enforce the bound.
+ *
+ * Eviction is oldest-first, and it is done HERE rather than by the caller counting
+ * messages: the caller cannot know what the entries cost, and a message-count window
+ * keeps a lot of large messages while discarding a lot of small ones.
+ */
+export function rowCacheSet(key, value) {
+  // Re-inserting an existing key would leave the old entry in place, so drop it first —
+  // otherwise the bound could be evictions short of what it looks like.
+  store.delete(key);
+  store.set(key, value);
+  while (store.size > ROW_CACHE_LIMIT) {
+    // Map iteration is insertion order, so the first key is the least recently used.
+    const oldest = store.keys().next();
+    if (oldest.done) break;
+    store.delete(oldest.value);
+    stats.evictions++;
+  }
+  return value;
+}
+
+/**
+ * Is `cached` still valid for `key`'s message?
+ *
+ * A separate question from `rowCacheGet`, because a message can change without its key
+ * changing: a streamed reply's text is the key's own `text` component, so its key DOES
+ * change — but the row COUNT memo does not carry the text, and that one has to be asked
+ * whether the content moved. Kept as a function so the check is named at the call site
+ * rather than being an open-coded `===` someone later widens by accident.
+ */
+export function evictIfStale(entry, key) {
+  if (!entry) return true;
+  return entry.key !== key;
 }