@hncode/hncode 0.5.0 → 0.5.1

package/src/config.js

@@ -388,6 +388,14 @@ const b = baseUrl.replace(/\/+$/, '');
     // "use the built-in SYSTEM_PROMPT". Read from config.toml so it persists
     // across restarts.
     systemPrompt: process.env.HNCODE_SYSTEM_PROMPT || root.system_prompt || '',
+    // The prompt knobs added alongside it, all editable from /settings › Prompt. Separate
+    // keys rather than one blob, because they mean different things: `append` keeps the
+    // built-in prompt and adds to it, `personal` is the user's own standing note, and the
+    // per-mode ones only apply while that mode is on.
+    appendSystemPrompt: process.env.HNCODE_APPEND_SYSTEM_PROMPT || root.append_system_prompt || '',
+    planInstructions: root.plan_instructions || '',
+    focusInstructions: root.focus_instructions || '',
+    swarmInstructions: root.swarm_instructions || '',
     // ---- Web UI daemon -------------------------------------------------------
     // One daemon serves EVERY hncode session on this machine: it holds the fixed
     // port, proxies each session's requests to that session's own loopback
@@ -1146,24 +1154,43 @@ export function effortOptions(cfg, modelKeyName) {
   return ['off', 'on'];
 }
 
+// Token budget for a NAMED grade, on a protocol that wants a number rather than a word.
+//
+// The grades the catalog declares are low/medium/high, and a user may also write their own
+// in config.toml (`efforts = ["xhigh"]`). A grade with no entry here has no honest budget to
+// send, so the field is omitted — the previous code fell back to 8000, which silently gave
+// every unknown grade the same strength as `on` and `medium`.
+const EFFORT_BUDGETS = { low: 2000, medium: 8000, high: 16000, max: 32000 };
+
 // Map a chosen effort to the wire value for the active protocol.
+//
+// `on` means "thinking on", NOT "medium". The two are different requests: a model may
+// support a plain toggle without any graded control, in which case there is no grade to
+// send and inventing one (`medium`) can be rejected outright by the provider. `on` therefore
+// sends the protocol's plain enable, or nothing at all.
 export function effortWire(cfg, effort) {
   if (!effort || effort === 'off') return null;
+  const named = Object.prototype.hasOwnProperty.call(EFFORT_BUDGETS, effort);
+
   if (cfg.protocol === 'anthropic') {
-    const budget = { on: 8000, low: 2000, medium: 8000, high: 16000, max: 32000 }[effort] || 8000;
-    return { thinking: { type: 'enabled', budget_tokens: budget } };
+    // `thinking: { type: 'enabled' }` IS the plain toggle; `budget_tokens` is optional and
+    // only meaningful for a named grade. Omitting it lets the provider pick its own budget,
+    // which is what "on" asked for.
+    return named
+      ? { thinking: { type: 'enabled', budget_tokens: EFFORT_BUDGETS[effort] } }
+      : { thinking: { type: 'enabled' } };
   }
-  // Responses API nests the grade: `reasoning: { effort }`.
-  if (cfg.protocol === 'responses') {
-    const grade = effort === 'on' ? 'medium' : effort;
-    return { reasoning: { effort: grade } };
-  }
-  // OpenAI-compatible: `reasoning_effort`. "on" is not a valid grade, so map it
-  // to "medium"; concrete grades pass through.
-  const grade = effort === 'on' ? 'medium' : effort;
-  return { reasoning_effort: grade };
+
+  // Responses API and the OpenAI-compatible shape both take a GRADE word, and neither has
+  // a value meaning "on". So a named grade passes through, and `on` sends nothing — the
+  // request carries whatever the provider does by default for that model, rather than a
+  // grade the model may not accept.
+  if (!named) return {};
+  if (cfg.protocol === 'responses') return { reasoning: { effort } };
+  return { reasoning_effort: effort };
 }
 
+
 function toTomlLine(k, v) {
   if (typeof v === 'string') return `${k} = "${v.replace(/"/g, '\\"')}"`;
   if (typeof v === 'boolean') return `${k} = ${v}`;

package/src/doctor.js

@@ -77,8 +77,10 @@ function checkConfig(cfg, files) {
   return out;
 }
 
-/** The session directory. A store that cannot be listed is a store whose work is invisible. */
-function checkSessions(files, sessionsDir, limit = 4) {
+/** The session directory. A store that cannot be listed is a store whose work is invisible.
+ *
+ *  Async because it profiles the largest session — see the memory breakdown below. */
+async function checkSessions(files, sessionsDir, limit = 4) {
   const out = [];
   if (!fs.existsSync(sessionsDir)) {
     return [check('session store', 'warn', `${sessionsDir} does not exist yet`,
@@ -110,14 +112,17 @@ function checkSessions(files, sessionsDir, limit = 4) {
   // actually hit: past ~512 MB `JSON.stringify` throws, and every save of that session
   // then fails until the transcript is trimmed.
   const V8_LIMIT = 512 * 1024 * 1024;
-  const big = [];
+  // Sizes of every session, so the memory profile can pick the largest regardless of how
+  // large it is. The `big` list below is filtered to the ones worth WARNING about; the
+  // profiler wants the largest whatever its size, because "this session holds 0.66 MB of
+  // tool arguments" is useful at 4 MB and not only at 500.
+  const sizes = [];
   for (const f of names) {
-    try {
-      const size = fs.statSync(path.join(sessionsDir, f)).size;
-      if (size > 8 * 1024 * 1024) big.push({ f, size });
-    } catch { /* raced away */ }
+    try { sizes.push({ f, size: fs.statSync(path.join(sessionsDir, f)).size }); } catch { /* raced away */ }
   }
-  big.sort((a, b) => b.size - a.size);
+  sizes.sort((a, b) => b.size - a.size);
+  const big = sizes.filter((x) => x.size > 8 * 1024 * 1024);
+
   for (const b of big.slice(0, limit)) {
     const mb = (b.size / 1048576).toFixed(1);
     const sev = b.size > V8_LIMIT * 0.75 ? 'error' : 'warn';
@@ -127,6 +132,38 @@ function checkSessions(files, sessionsDir, limit = 4) {
         : 'Large; loading and saving this session will be slow.'));
   }
 
+  // WHERE THE BYTES ARE in the biggest session, as opposed to how big the file is.
+  //
+  // A file size says nothing actionable: the same 2.5 MB can be a conversation or a
+  // runaway transcript, and only one of those is worth fixing. The breakdown also explains
+  // the file being LARGER than the content it holds — measured on a real session, the
+  // serialised JSON was 2.29 MB while text + tool results + tool arguments summed to
+  // 1.27 MB, so structure and escaping are as expensive as the text.
+  //
+  // Skipped below 1 MB: loading and measuring a session to learn it is small is itself
+  // work, and the finding would be "nothing to see". Deliberately NOT gated on `big` —
+  // that list only holds sessions big enough to warn about, and the breakdown is most
+  // useful on an ordinary one: it is where "half your memory is tool arguments" shows up.
+  if (sizes.length && sizes[0].size > 1024 * 1024) {
+    const top = sizes[0];
+    try {
+      const { loadSession } = await import('./session.js');
+      const { profileMemory, memoryHeadline } = await import('./memory-profile.js');
+      const loaded = loadSession(top.f.replace(/\.json$/, ''));
+      if (loaded) {
+        const profile = profileMemory({ session: loaded });
+        out.push(check('largest session memory', 'info',
+          `${memoryHeadline(profile)}  (${top.f})`,
+          'Text, tool results and tool ARGUMENTS are counted separately; run /memory-profile for the full breakdown.'));
+      }
+    } catch (e) {
+      out.push(check('largest session memory', 'warn', `could not profile ${top.f}: ${e.message}`,
+        'The file was readable by size but would not parse.'));
+    }
+  }
+
+  // Leftover temp files from an interrupted save.
+
   // Leftover temp files from an interrupted save.
   let tmp = [];
   try { tmp = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.tmp')); } catch { /* listed above */ }
@@ -213,6 +250,160 @@ function checkExtensions(files) {
   return out;
 }
 
+/**
+ * Free space where the sessions live.
+ *
+ * A store that fills up is a store that loses work, and the failure is not obviously about
+ * disk: the write fails, the turn is lost, and the error text says ENOENT or EACCES. The
+ * session directory held 608 MB on this machine at one point, which is the shape that walks
+ * a disk to full without anyone noticing.
+ *
+ * `statfs` is used where the platform has it (Node 18.15+). Where it does not, the check is
+ * SKIPPED rather than guessed — a wrong number here is worse than no number.
+ */
+function checkDisk(dir) {
+  if (typeof fs.statfsSync !== 'function') {
+    return [check('disk space', 'info', 'not measurable on this Node/platform', '')];
+  }
+  try {
+    const st = fs.statfsSync(dir);
+    const freeBytes = Number(st.bavail) * Number(st.bsize);
+    const totalBytes = Number(st.blocks) * Number(st.bsize);
+    const freeGb = freeBytes / 1024 ** 3;
+    const totalGb = totalBytes / 1024 ** 3;
+    // Thresholds are deliberately far apart: below 1 GB is an error (a long session can
+    // write hundreds of megabytes), below 5 GB is a warning.
+    const sev = freeGb < 1 ? 'error' : freeGb < 5 ? 'warn' : 'ok';
+    return [check('disk space', sev, `${freeGb.toFixed(1)} GB free of ${totalGb.toFixed(0)} GB`,
+      sev === 'ok' ? ''
+        : 'Saving a session writes the whole transcript, which has reached hundreds of MB. Free space, or point HNCODE_SESSIONS_DIR at another volume.')];
+  } catch (e) {
+    return [check('disk space', 'info', `could not measure: ${e.message}`, '')];
+  }
+}
+
+/**
+ * The workspace's git state.
+ *
+ * Two things here actually break work: a missing `user.name`/`user.email` makes every
+ * commit fail, and an unfinished merge or rebase means the tree is not what the agent
+ * thinks it is. Both are cheap to check and neither surfaced anywhere before.
+ */
+function checkGit(workspace, cp) {
+  if (!workspace) return [];
+  if (!cp) return [check('git', 'info', 'the git module is unavailable', '')];
+  const run = (args) => {
+    try {
+      const r = cp.spawnSync('git', args, { cwd: workspace, encoding: 'utf8', timeout: 5000, windowsHide: true });
+      return r.status === 0 ? String(r.stdout || '').trim() : null;
+    } catch { return null; }
+  };
+  // A workspace that is not a repo is normal, and says nothing about health.
+  const top = run(['rev-parse', '--show-toplevel']);
+  if (!top) return [check('git', 'info', 'not a git repository', '')];
+
+  const out = [];
+  const branch = run(['rev-parse', '--abbrev-ref', 'HEAD']);
+  out.push(check('git', 'ok', `${branch || '(detached)'} in ${top}`));
+
+  for (const key of ['user.name', 'user.email']) {
+    if (!run(['config', '--get', key])) {
+      out.push(check(`git ${key}`, 'warn', 'not set',
+        `Every commit fails without it. Run: git config --global ${key} "…"`));
+    }
+  }
+  // A half-finished operation changes what the agent is looking at.
+  const gitDir = run(['rev-parse', '--git-dir']);
+  if (gitDir) {
+    const abs = path.isAbsolute(gitDir) ? gitDir : path.join(workspace, gitDir);
+    for (const [file, what] of [['MERGE_HEAD', 'a merge'], ['REBASE_HEAD', 'a rebase'], ['CHERRY_PICK_HEAD', 'a cherry-pick']]) {
+      if (fs.existsSync(path.join(abs, file))) {
+        out.push(check('git in progress', 'warn', `${what} is unfinished`,
+          'The working tree is mid-operation; resolve it before trusting a diff.'));
+      }
+    }
+  }
+  return out;
+  return out;
+}
+
+/**
+ * A LIVE end-to-end probe: can this configuration actually complete a turn?
+ *
+ * This is the check a static report cannot make. Everything above reads files; a key that
+ * exists and an endpoint that parses still say nothing about whether a request SUCCEEDS, and
+ * the failures that matter — a revoked key, a wrong base URL, a model the account cannot
+ * reach, a provider that rejects `reasoning_effort` — are all invisible until a real request
+ * is made.
+ *
+ * It costs one request and a handful of tokens, so it is OPT-IN (`/doctor --probe`) and never
+ * part of a plain run. Modelled on jcode's provider-doctor, whose AUTH_CREDENTIAL_LOADED,
+ * NON_STREAMING_CHAT_COMPLETION and STREAMING_CHAT_COMPLETION checks do the same thing.
+ *
+ * The steps are reported as they happen, so a failure names the step that broke rather than
+ * only saying the whole thing did not work.
+ */
+async function probeProvider(cfg, input = {}) {
+  const out = [];
+  const send = input.probeRequest;      // injected by a test; see the note below
+  if (!cfg.provider || !cfg.model) {
+    return [check('probe', 'info', 'skipped: no provider/model configured', '')];
+  }
+  if (!cfg.endpoint) {
+    return [check('probe', 'info', 'skipped: no endpoint', '')];
+  }
+  // A test supplies its own transport. Without one, the real LLM class is used — lazily, so
+  // a plain /doctor never pays to import the provider stack.
+  const doRequest = send || (async () => {
+    const { LLM } = await import('./llm.js');
+    const llm = new LLM(cfg);
+    let text = '';
+    let sawError = null;
+    let usage = null;
+    await llm.request(
+      [{ role: 'user', content: 'Reply with the single word: ok' }],
+      (e) => {
+        if (e.type === 'data') text += e.text;
+        else if (e.type === 'error') sawError = e.error;
+        else if (e.type === 'usage') usage = e.usage;
+      },
+      // One turn, no tools, no streaming: the smallest request that proves the pipeline.
+      { noTools: true, streaming: false },
+    );
+    return { text, error: sawError, usage };
+  });
+
+  const t0 = Date.now();
+  let res;
+  try {
+    res = await doRequest();
+  } catch (e) {
+    return [check('probe', 'error', `request threw: ${(e && e.message) || e}`,
+      'The configuration parses but a request does not complete. Check the key, the endpoint and the network.')];
+  }
+  const ms = Date.now() - t0;
+
+  if (res && res.error) {
+    return [check('probe', 'error', `provider error: ${String(res.error).slice(0, 160)}`,
+      'The key may be revoked, the model unavailable, or the provider rejecting a field in the request.')];
+  }
+  const text = String((res && res.text) || '').trim();
+  if (!text) {
+    // A 200 with no text is the failure mode that looks like success: a reasoning model can
+    // spend its whole budget on `reasoning_content` and return an empty `content`.
+    return [check('probe', 'error', `empty reply in ${ms} ms`,
+      'The request completed but returned no text. If this model always reasons, it may be spending the whole output budget on reasoning.')];
+  }
+  // `usage` comes off the RESULT, not out of the closure that built it — reading the local
+  // inside `doRequest` from here was a ReferenceError on every successful probe.
+  const usage = res && res.usage;
+  out.push(check('probe', 'ok', `replied "${text.slice(0, 20)}" in ${ms} ms`,
+    usage ? `provider reported ${JSON.stringify(usage)}` : ''));
+  return out;
+  return out;
+}
+
+
 /** The terminal. An unknown size or a dumb TERM explains a broken-looking UI. */
 function checkTerminal(env, dims) {
   const out = [];
@@ -224,6 +415,8 @@ function checkTerminal(env, dims) {
   } else {
     out.push(check('TERM', 'ok', `${term}${env.COLORTERM ? ` / ${env.COLORTERM}` : ''}`));
   }
+  // Named distinctly from the TERM check: both used to be called "TERM", so a report with a
+  // small terminal showed the same name twice and read as a duplicated finding.
   if (dims && (dims.cols < 60 || dims.rows < 15)) {
     out.push(check('terminal size', 'warn', `${dims.cols}x${dims.rows}`,
       'Below 60x15 the layout cannot fit; widen the window.'));
@@ -257,7 +450,7 @@ function checkRuntime(node, platform, dirs) {
  * @param {string} [input.node]       process.version, for tests
  * @returns {Array<{name:string,severity:string,detail:string,fix:string}>}
  */
-export function runDoctor(input = {}) {
+export async function runDoctor(input = {}) {
   const cfg = input.cfg || {};
   const env = input.env || process.env;
   const workspace = input.workspace || cfg.workspace || process.cwd();
@@ -278,13 +471,18 @@ export function runDoctor(input = {}) {
     }),
     ...checkConfig(cfg, files),
     ...checkWorkspace(workspace),
-    ...checkSessions(files, sessionsDir),
+    ...(await checkSessions(files, sessionsDir)),
     ...checkErrorLog(files),
     ...checkMcp(input.mcpServers, input.mcpConnections),
     ...checkHooks(files, workspace),
     ...checkExtensions(files),
-    ...checkTerminal(env, input.dims),
+    ...checkDisk(sessionsDir),
+    ...checkGit(workspace, input.childProcess),
+...checkTerminal(env, input.dims),
   ];
+  // The live probe is OPT-IN: it spends a request and a few tokens, so it must never run
+  // as part of a plain /doctor.
+  if (input.probe) results.push(...await probeProvider(cfg, input));
   return results;
 }
 

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}`;
+}