@hncode/hncode 0.4.1 → 0.5.0

package/src/context-bar.js

@@ -0,0 +1,237 @@
+// The segmented context bar: used tokens by content type, then the remainder as one free
+// segment whose right edge carries the usage readout.
+//
+// WHY A BAR AND NOT A NUMBER
+// -------------------------
+// `context: 12% (1.2k/97.7k)` says how full the window is and nothing about what filled
+// it. The bar answers the question people actually have — "why is this getting full" — by
+// making the composition readable: a session that grew from tool output looks different
+// from one that grew from long answers, without reading a single figure.
+//
+// THE SHAPE OF THE ALLOCATION
+// --------------------------
+// Two passes, because plain rounding is wrong in both directions:
+//
+//   1. Every non-zero segment is guaranteed ONE column. Without this, a segment holding
+//      0.3% of the window rounds to zero columns and disappears — and "thinking is a small
+//      share" is exactly the fact a user is looking for.
+//   2. The remaining columns are shared proportionally by LARGEST REMAINDER. Rounding each
+//      share independently gives a total that is off by one or two, so the bar either falls
+//      short of the row or overruns it.
+//
+// THE THREE-STEP LABEL
+// -------------------
+// Each segment says as much about itself as fits, because the segments are often only a
+// few columns wide and there are three different things it could say:
+//
+//   1. `name + value` when the segment is wide enough for both — `ast 4.4k`
+//   2. the name alone when only that fits — `ast`
+//   3. nothing at all when not even the abbreviation does
+//
+// Steps 2 and 3 are not dead ends: every segment's columns are returned as a hit span, so
+// pointing at one prints its full name and value in the row below the bar. That is why step
+// 3 is acceptable — the information stays one pointer away.
+
+import { C } from './colors.js';
+
+/** The segments, in the order they are drawn. Order is part of the reading: the session
+ *  grows from left to right in the same sequence the context does. */
+export const SEGMENTS = [
+  { key: 'system', name: 'system prompt', fill: C.ctxSystem },
+  { key: 'prompt', name: 'user messages', fill: C.ctxPrompt },
+  { key: 'assistant', name: 'assistant', fill: C.ctxAssistant },
+  { key: 'thinking', name: 'thinking', fill: C.ctxThinking },
+  { key: 'tools', name: 'tool results', fill: C.ctxTools },
+];
+
+// `labelFor` closes over `compactTokens`, which is declared below — hoisted function
+// declarations make that safe, and keeping the forms next to the metadata is what stops the
+// on-bar label and the hover caption from drifting apart.
+//
+// There is no abbreviation: `ast` says nothing to somebody who does not already know what
+// the bar is, and a full word that does not fit is handled by DROPPING it, not by
+// shortening it into a private code. The three-step degradation in `paintBar` is what makes
+// that affordable — a wide segment gets `assistant 4.4k`, a narrow one gets `assistant`, and
+// a very narrow one gets nothing and relies on the hover caption instead.
+for (const seg of SEGMENTS) {
+  seg.labelFor = (tokens) => {
+    const v = compactTokens(tokens);
+    return { name: seg.name, full: `${seg.name} ${v}`, value: v, title: seg.name };
+  };
+}
+/** The caption a hovered segment produces: `assistant 4.4k`. */
+/** The caption a hovered segment produces: `assistant 4.4k`. */
+export function segmentCaption(key, tokens) {
+  const seg = SEGMENTS.find((s) => s.key === key);
+  if (!seg) return '';
+  return `${seg.name} ${compactTokens(tokens)}`;
+}
+
+/**
+ * Give every non-zero segment at least one column, then share the rest proportionally.
+ *
+ * @param {readonly number[]} values one per segment, plus the free segment last.
+ * @param {number} width columns available.
+ * @returns {number[]} columns per entry, summing to at most `width`.
+ */
+export function allocateBarColumns(values, width) {
+  const used = SEGMENTS
+    .map((_, i) => i)
+    .filter((i) => (values[i] || 0) > 0);
+  if (used.length === 0 || used.length >= width) return shareLargestRemainder(values, width);
+
+  const minimum = values.map(() => 0);
+  for (const i of used) minimum[i] = 1;
+  const rest = shareLargestRemainder(values, width - used.length);
+  return minimum.map((m, i) => m + (rest[i] || 0));
+}
+
+/**
+ * Proportional split by LARGEST REMAINDER: floor each share, then hand the columns left
+ * over to the biggest fractional parts, largest first. This is what makes the parts sum to
+ * exactly `width`; rounding each independently does not.
+ */
+function shareLargestRemainder(values, width) {
+  const total = values.reduce((a, b) => a + (b || 0), 0);
+  if (!(total > 0) || !(width > 0)) return values.map(() => 0);
+
+  const exact = values.map((v) => ((v || 0) / total) * width);
+  const floors = exact.map((x) => Math.floor(x));
+  let left = width - floors.reduce((a, b) => a + b, 0);
+
+  const order = exact
+    .map((x, i) => ({ i, frac: x - Math.floor(x) }))
+    .sort((a, b) => b.frac - a.frac || a.i - b.i);   // stable on index for equal fractions
+  for (let k = 0; left > 0; k++, left--) floors[order[k % order.length].i]++;
+  return floors;
+}
+
+/**
+ * The bar and its readout, filling exactly `width` columns together.
+ *
+ * THE READOUT GETS ITS SPACE FIRST, AND THE BAR IS WHAT GIVES UP. Laying it out the other
+ * way round — bar across the full row, readout painted on top of the free segment — means
+ * the readout disappears the moment the window fills, because a full window has no free
+ * segment at all. That is the one moment the figure matters most, and it was the one moment
+ * it could not be seen.
+ *
+ * So the row is split: the readout claims the columns it needs (one gap before it, so the
+ * figures do not read as part of a segment), and the bar takes whatever is left. The bar can
+ * therefore never reach the readout, at any fill level, and the readout is never truncated
+ * into nonsense like `11.7k/97`.
+ *
+ * @param {Record<string, number>} segments tokens per content type.
+ * @param {number} usedTokens total used, driving the readout.
+ * @param {number} window the context window, or 0 when unknown.
+ * @param {number} width columns to fill.
+ * @param {string} [readout] the caller's own wording, e.g. `context: 12% (11.7k/97.7k)`.
+ *   Preferred over the derived one because it is what the status line already said; when the
+ *   row is too narrow for it, the derived form takes over, and failing that just the
+ *   percentage — a readout that is always SOMETHING beats one that is sometimes absent.
+ * @returns {{ text: string, hits: Array<{col0: number, col1: number, data: string}> }}
+ *   `text` occupies exactly `width` columns; `hits` cover the bar's segments only.
+ */
+export function renderContextBar(segments, usedTokens, window, width, readout) {
+  if (!(width > 0) || !(window > 0)) return { text: '', hits: [] };
+  // Widest form first, then the derived ones, so the row always carries SOMETHING. A
+  // half-printed `11.7k/97` is worse than a bare percentage, so each step is a complete
+  // alternative rather than a truncation.
+  const pct = `${((usedTokens / window) * 100).toFixed(1)}%`;
+  const figures = `${compactTokens(usedTokens)}/${compactTokens(window)}`;
+  const own = typeof readout === 'string' ? readout : '';
+  const forms = [...new Set([own, `${figures} ${pct}`, pct].filter(Boolean))];
+  const text = forms.find((f) => f.length + 1 <= width) || '';
+  const barWidth = Math.max(0, width - text.length - 1);
+
+  if (barWidth <= 0) {
+    // Too narrow for a bar AND a gap: the readout has the row to itself. Padded to exactly
+    // `width` because every row of the frame is, and a short one shifts everything below it.
+    return { text: text ? C.white + text.padEnd(width) : ' '.repeat(width), hits: [] };
+  }
+
+  const free = Math.max(0, window - usedTokens);
+  const values = [...SEGMENTS.map((s) => segments[s.key] || 0), free];
+  const cols = allocateBarColumns(values, barWidth);
+  return paintBar(cols, cols[cols.length - 1] || 0, '', values, text, width);
+}
+
+/**
+ * Paint the allocated columns, then the readout.
+ *
+ * Each segment carries as much of its own label as fits, measured against the segment's OWN
+ * width, so a label can never spill into its neighbour and shift every segment to the right
+ * of it.
+ *
+ * @param {number[]} cols columns per entry, the last being the free segment.
+ * @param {number} freeCols the free segment's width, already included in `cols`.
+ * @param {string} _unused kept for call-shape stability; the readout no longer lives inside
+ *   the free segment, so nothing is painted into it here.
+ * @param {number[]} values tokens per segment, driving each label.
+ * @param {string} readout the text set after the bar, on the page background rather than on
+ *   any fill — so it is legible at every fill level, including a completely full bar.
+ * @param {number} width the whole row, bar plus readout.
+ */
+function paintBar(cols, freeCols, _unused, values, readout, width) {
+  let out = '';
+  let at = 0;                       // visible column the next segment starts at
+  const hits = [];
+
+  for (let i = 0; i < SEGMENTS.length; i++) {
+    const n = cols[i] || 0;
+    if (!n) continue;
+    const seg = SEGMENTS[i];
+    const label = seg.labelFor(values[i]);
+    // One blank column on EACH side of the label. The right one keeps two adjacent short
+    // labels from running together (`thinkingtool results`) and making the boundary between
+    // them invisible; the left one stops the text from sitting hard against the edge of its
+    // own fill, which reads as if the label belonged to the segment before it. The first
+    // segment's left column is the row's own margin, so both cost the same.
+    const room = n - 2;
+    const inner = room >= label.full.length
+      ? label.full
+      : (room >= label.name.length ? label.name : '');
+    // `room` columns of label, a blank on the left and one on the right: `n`.
+    out += seg.fill + (inner ? ' ' + C.white + inner.padEnd(room, ' ') + ' ' : ' '.repeat(n));
+    hits.push({ col0: at, col1: at + n - 1, data: seg.key });
+    at += n;
+  }
+  // The free segment needs SPACES, not just its fill colour: a background colour on its own
+  // paints nothing, so the "how much room is left" band vanished the moment the readout moved
+  // out of it. It was only ever visible because the readout used to sit on those cells.
+  if (freeCols) { out += C.ctxFree + ' '.repeat(freeCols); at += freeCols; }
+
+  // The readout goes AFTER the bar, on the page background, in the columns the caller
+  // reserved for it. `C.reset` first: the last thing the bar emitted was a fill, and a
+  // background colour behind the figures would be a band nobody asked for.
+  //
+  // `at` is the bar's visible width and the row is `width` wide, so the gap is whatever is
+  // left minus the figures — at least one column, which is what keeps `11.7k/97` from reading
+  // as a continuation of a segment's fill.
+  const gap = Math.max(1, width - at - readout.length);
+  out += C.reset + ' '.repeat(gap) + C.white + readout;
+
+  return { text: out + C.reset, hits };
+}
+
+/**
+ * The right-hand readout, stepped down as its segment narrows: the full form, then the
+ * percentage alone, then nothing. A half-printed `11.7k/97` is worse than no number.
+ */
+export function formatReadout(used, window, freeCols) {
+  const pct = `${((used / window) * 100).toFixed(1)}%`;
+  const full = `${compactTokens(used)}/${compactTokens(window)} ${pct}`;
+  // The thresholds match the renderer's own condition exactly (`freeCols >= length`). They
+  // used to ask for one more, which is how the bar came up a column short: the readout was
+  // accepted HERE and then not written THERE.
+  if (freeCols >= full.length) return full;
+  if (freeCols >= pct.length) return pct;
+  return '';
+}
+
+/** 1200 -> `1.2k`, 97000 -> `97.0k`, 3_400_000 -> `3.4M`. */
+export function compactTokens(n) {
+  const v = Number(n) || 0;
+  if (v >= 1e6) return `${(v / 1e6).toFixed(1)}M`;
+  if (v >= 1e3) return `${(v / 1e3).toFixed(1)}k`;
+  return String(Math.round(v));
+}

package/src/doctor.js

@@ -0,0 +1,320 @@
+// /doctor — report the environment this session is running in, and flag the things that
+// break it. Modelled on Claude Code's and cline's `doctor` commands.
+//
+// WHY THIS EXISTS
+// ---------------
+// Every failure this project has hit in practice was visible in the environment BEFORE
+// it bit, and none of it was visible from the TUI:
+//
+//   * a session file grew past the V8 string limit, so saving silently stopped working
+//     for an hour and a half (only a line in ~/.hncode/session-errors.log);
+//   * three intact conversations became unlistable because their transcript pushed the
+//     metadata key out of the head reader's reach;
+//   * an MCP server that never connected, so its tools simply were not there;
+//   * an API key that was absent or a base URL that was malformed, which surfaces as a
+//     provider error on the first real turn and looks like a model problem.
+//
+// A diagnosis is a LIST OF CHECKS, each with a severity, so it can be tested: the checks
+// that read the filesystem take their paths from this module's own resolution functions
+// (the same ones the rest of the program uses), which is what makes a report trustworthy
+// rather than a second, divergent opinion about where things live.
+//
+// READ-ONLY BY CONSTRUCTION. Nothing here writes, repairs or deletes: a diagnostic that
+// "fixes" something is a diagnostic nobody can run on a machine they care about. The
+// only outbound work is an optional reachability probe, which the caller opts into.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** Severities, worst first. `ok` is the only one that means "nothing to do". */
+export const SEVERITY_ORDER = ['error', 'warn', 'ok', 'info'];
+
+const MARK = { error: '✖', warn: '!', ok: '✔', info: '·' };
+
+/** One check's outcome. `fix` is the actionable half — a finding with no remedy is noise. */
+function check(name, severity, detail, fix) {
+  return { name, severity, detail: String(detail == null ? '' : detail), fix: fix || '' };
+}
+
+// ---- individual checks -----------------------------------------------------
+
+/** The config file is where every provider and key lives; a malformed one is fatal. */
+function checkConfig(cfg, files) {
+  const file = files.config;
+  if (!fs.existsSync(file)) {
+    return [check('config file', 'warn', `${file} does not exist`,
+      'Run hncode once to create it, or /model to pick a provider.')];
+  }
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch (e) {
+    return [check('config file', 'error', `unreadable: ${e.message}`, `Check permissions on ${file}`)];
+  }
+  const out = [check('config file', 'ok', file)];
+  // A TOML file the parser rejects would have failed before this point, so the useful
+  // signal here is the SHAPE: a config with no provider cannot make a request.
+  if (!cfg.provider) {
+    out.push(check('provider', 'error', 'no provider configured',
+      'Run /model to choose one, or /provider add <name> <base-url>.'));
+  }
+  if (!cfg.model) {
+    out.push(check('model', 'error', 'no model selected', 'Run /model.'));
+  }
+  if (!cfg.apiKey) {
+    // A local endpoint (ollama, llama.cpp, lmstudio) legitimately has no key.
+    const local = /localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\]/.test(String(cfg.endpoint || ''));
+    out.push(local
+      ? check('api key', 'info', 'none set, and the endpoint is local', '')
+      : check('api key', 'error', 'not set', 'Set it in config.toml, or via /provider.'));
+  }
+  if (cfg.endpoint && !/^https?:\/\//i.test(String(cfg.endpoint))) {
+    out.push(check('endpoint', 'error', `does not look like a URL: ${cfg.endpoint}`,
+      'It must start with http:// or https://.'));
+  }
+  if (!text.includes('[' ) && !text.includes('=')) {
+    out.push(check('config shape', 'warn', 'the file has no keys in it', `Open ${file} and check it.`));
+  }
+  return out;
+}
+
+/** The session directory. A store that cannot be listed is a store whose work is invisible. */
+function checkSessions(files, sessionsDir, limit = 4) {
+  const out = [];
+  if (!fs.existsSync(sessionsDir)) {
+    return [check('session store', 'warn', `${sessionsDir} does not exist yet`,
+      'It is created on the first save.')];
+  }
+  let names;
+  try {
+    names = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.json'));
+  } catch (e) {
+    return [check('session store', 'error', `cannot list ${sessionsDir}: ${e.message}`,
+      'Check that the directory exists and is readable.')];
+  }
+  out.push(check('session store', 'ok', `${names.length} session file(s) in ${sessionsDir}`));
+
+  // Writability is the property that matters: a read-only store loses every turn while
+  // the TUI looks completely normal. Tested with a create-and-remove, not a mode bit,
+  // because the mode bit lies on Windows and on a mounted volume.
+  const probe = path.join(sessionsDir, `.doctor-${process.pid}.tmp`);
+  try {
+    fs.writeFileSync(probe, 'x');
+    fs.rmSync(probe, { force: true });
+    out.push(check('session store writable', 'ok', 'yes'));
+  } catch (e) {
+    out.push(check('session store writable', 'error', `no: ${e.message}`,
+      'Every turn will fail to save. Fix permissions, or point HNCODE_SESSIONS_DIR somewhere writable.'));
+  }
+
+  // A file big enough to approach the V8 string limit. This is the failure this project
+  // 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 = [];
+  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 */ }
+  }
+  big.sort((a, b) => b.size - a.size);
+  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';
+    out.push(check('oversized session', sev, `${mb} MB  ${b.f}`,
+      b.size > V8_LIMIT * 0.75
+        ? 'Approaching the ~512 MB string limit, past which saving FAILS. Trim the reasoning transcript — see tools/repair-transcripts.mjs.'
+        : 'Large; loading and saving this session will be slow.'));
+  }
+
+  // Leftover temp files from an interrupted save.
+  let tmp = [];
+  try { tmp = fs.readdirSync(sessionsDir).filter((f) => f.endsWith('.tmp')); } catch { /* listed above */ }
+  if (tmp.length) {
+    out.push(check('interrupted save', 'warn', `${tmp.length} .tmp file(s) left behind`,
+      `The write did not finish; the session itself is fine. Delete ${sessionsDir}\\*.tmp`));
+  }
+  return out;
+}
+
+/** The error log. Its very existence usually means something failed silently. */
+function checkErrorLog(files) {
+  if (!fs.existsSync(files.errorLog)) return [];
+  let text = '';
+  try { text = fs.readFileSync(files.errorLog, 'utf8'); } catch { return []; }
+  const lines = text.split(/\r?\n/).filter(Boolean);
+  if (!lines.length) return [];
+  const tail = lines.slice(-3);
+  const sev = lines.length > 20 ? 'warn' : 'info';
+  return [check('error log', sev, `${lines.length} entr(ies), latest: ${tail[tail.length - 1].slice(0, 90)}`,
+    `Read ${files.errorLog}. A repeated message there is a bug worth reporting.`)];
+}
+
+/** MCP servers: configured but not connected is the silent case. */
+function checkMcp(servers, connections) {
+  const names = Object.keys(servers || {});
+  if (!names.length) return [check('MCP servers', 'info', 'none configured', '')];
+  const byName = new Map((connections || []).map((c) => [c.name, c]));
+  const out = [];
+  for (const n of names) {
+    const conn = byName.get(n);
+    if (!conn) out.push(check(`MCP ${n}`, 'warn', 'configured but not started', 'Restart, or check the server command.'));
+    else if (!conn.ok) out.push(check(`MCP ${n}`, 'error', `failed: ${conn.error}`, 'Fix the command/URL in /mcp-config.'));
+    else out.push(check(`MCP ${n}`, 'ok', `${conn.toolCount} tool(s)`));
+  }
+  return out;
+}
+
+/** Hooks: a malformed hooks.json silently never fires. */
+function checkHooks(files, workspace) {
+  const candidates = [files.hooks, path.join(workspace || process.cwd(), '.hncode', 'hooks.json')];
+  const out = [];
+  for (const f of candidates) {
+    if (!fs.existsSync(f)) continue;
+    try {
+      const doc = JSON.parse(fs.readFileSync(f, 'utf8'));
+      const events = Object.keys(doc.hooks || {});
+      out.push(check('hooks', 'ok', `${events.length} event(s) configured in ${f}`));
+    } catch (e) {
+      out.push(check('hooks', 'error', `${f} is not valid JSON: ${e.message}`,
+        'A malformed hooks file makes every hook in it silently never run.'));
+    }
+  }
+  return out;
+}
+
+/** The workspace: tools resolve paths against it, so it has to exist and be writable. */
+function checkWorkspace(workspace) {
+  if (!workspace) return [check('workspace', 'error', 'not set', 'Run /move, or start hncode in a directory.')];
+  if (!fs.existsSync(workspace)) {
+    return [check('workspace', 'error', `${workspace} does not exist`,
+      'Every file tool will fail. /move to a directory that exists.')];
+  }
+  const probe = path.join(workspace, `.doctor-${process.pid}.tmp`);
+  try {
+    fs.writeFileSync(probe, 'x');
+    fs.rmSync(probe, { force: true });
+    return [check('workspace', 'ok', `${workspace} (writable)`)];
+  } catch {
+    return [check('workspace', 'warn', `${workspace} (NOT writable)`,
+      'Reads work; Edit, Write and a background command that writes will fail.')];
+  }
+}
+
+/** Skills and plugins: a directory that exists but holds nothing is worth knowing about. */
+function checkExtensions(files) {
+  const out = [];
+  for (const [label, dir] of [['skills', files.skills], ['plugins', files.plugins]]) {
+    if (!fs.existsSync(dir)) continue;
+    let n = 0;
+    try { n = fs.readdirSync(dir).length; } catch { /* unreadable */ }
+    out.push(check(label, 'info', `${n} entr(ies) in ${dir}`, ''));
+  }
+  return out;
+}
+
+/** The terminal. An unknown size or a dumb TERM explains a broken-looking UI. */
+function checkTerminal(env, dims) {
+  const out = [];
+  const term = env.TERM || '';
+  if (env.NO_COLOR) out.push(check('colour', 'info', 'NO_COLOR is set', ''));
+  else if (!term || term === 'dumb') {
+    out.push(check('TERM', 'warn', term ? `"${term}"` : 'not set',
+      'Colour and cursor control may not work. Set TERM=xterm-256color.'));
+  } else {
+    out.push(check('TERM', 'ok', `${term}${env.COLORTERM ? ` / ${env.COLORTERM}` : ''}`));
+  }
+  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.'));
+  }
+  return out;
+}
+
+/** Runtime facts, so a bug report carries them. */
+function checkRuntime(node, platform, dirs) {
+  return [
+    check('node', 'ok', node),
+    check('platform', 'ok', platform),
+    check('hncode home', 'info', dirs.home, ''),
+    check('cwd', 'info', dirs.cwd, ''),
+  ];
+}
+
+// ---- the report ------------------------------------------------------------
+
+/**
+ * Run every check and return the results.
+ *
+ * @param {object} input
+ * @param {object} input.cfg          resolved config (provider/model/endpoint/apiKey)
+ * @param {object} [input.files]      path overrides, for tests
+ * @param {string} [input.workspace]
+ * @param {object} [input.mcpServers] config.servers
+ * @param {Array}  [input.mcpConnections]
+ * @param {object} [input.env]
+ * @param {object} [input.dims]       { cols, rows }
+ * @param {string} [input.node]       process.version, for tests
+ * @returns {Array<{name:string,severity:string,detail:string,fix:string}>}
+ */
+export function runDoctor(input = {}) {
+  const cfg = input.cfg || {};
+  const env = input.env || process.env;
+  const workspace = input.workspace || cfg.workspace || process.cwd();
+  const sessionsDir = input.sessionsDir || path.join(env.HOME || os.homedir(), '.hncode', 'sessions');
+  const files = {
+    config: path.join(env.HOME || os.homedir(), '.hncode', 'config.toml'),
+    errorLog: path.join(env.HOME || os.homedir(), '.hncode', 'session-errors.log'),
+    hooks: path.join(env.HOME || os.homedir(), '.hncode', 'hooks.json'),
+    skills: path.join(env.HOME || os.homedir(), '.hncode', 'skills'),
+    plugins: path.join(env.HOME || os.homedir(), '.hncode', 'plugins'),
+    ...(input.files || {}),
+  };
+
+  const results = [
+    ...checkRuntime(input.node || process.version, input.platform || process.platform, {
+      home: path.join(env.HOME || os.homedir(), '.hncode'),
+      cwd: process.cwd(),
+    }),
+    ...checkConfig(cfg, files),
+    ...checkWorkspace(workspace),
+    ...checkSessions(files, sessionsDir),
+    ...checkErrorLog(files),
+    ...checkMcp(input.mcpServers, input.mcpConnections),
+    ...checkHooks(files, workspace),
+    ...checkExtensions(files),
+    ...checkTerminal(env, input.dims),
+  ];
+  return results;
+}
+
+/** Counts by severity, for a one-line summary. */
+export function summarize(results) {
+  const n = { error: 0, warn: 0, ok: 0, info: 0 };
+  for (const r of results || []) if (n[r.severity] != null) n[r.severity] += 1;
+  return n;
+}
+
+/** Render the report as a list of lines, worst first. Pure, so a test can assert on it. */
+export function formatDoctor(results, opts = {}) {
+  const list = Array.isArray(results) ? results : [];
+  const showOk = opts.showOk !== false;
+  const rank = (s) => { const i = SEVERITY_ORDER.indexOf(s); return i < 0 ? 99 : i; };
+  const sorted = list.slice().sort((a, b) => rank(a.severity) - rank(b.severity));
+  const n = summarize(list);
+  const head = `Doctor — ${n.error} error(s), ${n.warn} warning(s)`
+    + (opts.version ? `   hncode v${opts.version}` : '');
+  const lines = [head, ''];
+  for (const r of sorted) {
+    if (!showOk && (r.severity === 'ok' || r.severity === 'info')) continue;
+    const mark = MARK[r.severity] || '·';
+    lines.push(`${mark} ${r.name.padEnd(24)} ${r.detail}`);
+    if (r.fix && (r.severity === 'error' || r.severity === 'warn')) lines.push(`  ${' '.repeat(24)} → ${r.fix}`);
+  }
+  if (!n.error && !n.warn) {
+    lines.push('', 'No problems found.');
+  } else {
+    lines.push('', 'Run /doctor --all to include the passing checks.');
+  }
+  return lines;
+}

package/src/experiments.js

@@ -0,0 +1,122 @@
+// Feature flags for work that is not finished enough to be on for everyone.
+//
+// Why this exists instead of "just leave it off in the code": an unfinished feature
+// needs to be EXERCISED, by the person building it and by anyone willing to help,
+// against real sessions. Commenting it out means it is only ever tested on the
+// branch where it was written. A named flag also makes the risk legible — `/experiments`
+// lists what is on, and `hncode.experiments` records it, so a bug report can say
+// which combination produced it.
+//
+// Scope rules:
+//   * OFF unless turned on. A flag whose default is "on" is not an experiment, it
+//     is a release.
+//   * A flag that no code reads is a bug, not a no-op: `pruneUnknown()` exists so
+//     the list cannot silently rot, and the test asserts every declared flag is
+//     referenced somewhere in src/.
+//   * Turning a flag off must leave no residue. `applyExperiments()` is therefore
+//     called on every reload and is idempotent.
+
+/**
+ * The registry. Each entry is a flag with a one-line reason it exists — a flag with
+ * no explanation is indistinguishable from a mistake, and this list is what
+ * `/experiments` shows.
+ */
+export const EXPERIMENTS = {
+  'parallel-tools': {
+    default: false,
+    desc: 'Run independent tool calls from one model turn concurrently',
+    since: '0.5.0',
+  },
+  'prompt-cache-hints': {
+    default: false,
+    desc: 'Send cache_control breakpoints on long stable prefixes (Anthropic)',
+    since: '0.5.0',
+  },
+  'shell-parser-strict': {
+    default: false,
+    desc: 'Refuse to run a shell command the classifier cannot fully parse',
+    since: '0.5.0',
+  },
+};
+
+/** Is `name` a declared flag? */
+export function isExperiment(name) {
+  return Object.prototype.hasOwnProperty.call(EXPERIMENTS, String(name == null ? '' : name).trim());
+}
+
+/**
+ * The flag state from config plus the environment.
+ *
+ * `HNCODE_EXPERIMENTS=a,b` enables without touching config.toml — the escape hatch a
+ * test or a one-off run needs. Config wins when both are present, because config is
+ * the thing the user edited deliberately.
+ */
+export function experimentState(cfg, env = process.env) {
+  const out = {};
+  for (const [name, spec] of Object.entries(EXPERIMENTS)) out[name] = !!spec.default;
+  const fromEnv = String(env.HNCODE_EXPERIMENTS || '')
+    .split(',').map((s) => s.trim()).filter(Boolean);
+  for (const name of fromEnv) if (isExperiment(name)) out[name] = true;
+  const raw = (cfg && ((cfg.raw && cfg.raw.experiments) ?? cfg.experiments)) || {};
+  if (raw && typeof raw === 'object') {
+    for (const [name, v] of Object.entries(raw)) {
+      if (isExperiment(name)) out[name] = v === true || v === 'true' || v === 'on';
+    }
+  }
+  return out;
+}
+
+/** Just the enabled names, sorted — what a panel or a log line shows. */
+export function enabledExperiments(cfg, env) {
+  const st = experimentState(cfg, env);
+  return Object.keys(st).filter((k) => st[k]).sort();
+}
+
+/**
+ * Merge new flag values into a config's raw table, returning the table to persist.
+ *
+ * Written as a pure function of (current, changes) so the caller does not have to
+ * know how the config is shaped, and so the "turn one off" direction is testable:
+ * an explicit `false` is KEPT (it records a deliberate choice), while an unknown
+ * name is dropped rather than written into the file.
+ */
+export function mergeExperiments(current, changes) {
+  const out = { ...(current && typeof current === 'object' ? current : {}) };
+  for (const [name, v] of Object.entries(changes || {})) {
+    if (!isExperiment(name)) continue;
+    if (v === undefined) delete out[name];
+    else out[name] = v === true || v === 'true' || v === 'on';
+  }
+  return out;
+}
+
+/**
+ * Drop names that are no longer flags, so a config does not accumulate entries for
+ * features that were removed or renamed. Returns { kept, dropped }.
+ */
+export function pruneUnknown(current) {
+  const kept = {};
+  const dropped = [];
+  for (const [name, v] of Object.entries(current && typeof current === 'object' ? current : {})) {
+    if (isExperiment(name)) kept[name] = v;
+    else dropped.push(name);
+  }
+  return { kept, dropped };
+}
+
+/** Panel lines for `/experiments`. */
+export function describeExperiments(state) {
+  const rows = [];
+  for (const [name, spec] of Object.entries(EXPERIMENTS)) {
+    rows.push({
+      name,
+      on: !!(state && state[name]),
+      desc: spec.desc,
+      since: spec.since,
+      defaultOn: !!spec.default,
+    });
+  }
+  return rows;
+}
+
+export default { EXPERIMENTS, experimentState, enabledExperiments, mergeExperiments, pruneUnknown, describeExperiments, isExperiment };