@hncode/hncode 0.5.0 → 0.5.1

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

package/src/session-hub.js

@@ -168,6 +168,7 @@ export class SessionHub {
       dispatch: null,      // async (cmd, arg) => void      — slash commands
       interrupt: null,     // async () => void
       approve: null,       // async (id, ok) => void        — answer an approval
+      answerPlan: null,    // async (id, outcome) => void   — answer a Plan-mode review
       answerQuestion: null,// async (id, answers) => void   — AskUserQuestion
       stopTask: null,      // async (taskId) => void
       setMode: null,       // async (mode) => void

package/src/settings-schema.js

@@ -0,0 +1,301 @@
+// The settings schema — one declaration per setting, projected onto every surface.
+//
+// WHY A TABLE
+// -----------
+// Settings were spread across two dozen `/xxx` commands, each with its own argument
+// parsing, validation and persistence. Adding one meant writing a command; finding one
+// meant knowing what it was called; and the surfaces disagreed — the TUI had a
+// `/calm` toggle, the web's `setConfig` action accepted eight keys, and `config.toml`
+// accepted everything. CodeWhale's `settings_schema.rs` solves this with a single
+// declarative table that the UI renders from, the setter validates against, and the
+// defaults come from, so this mirrors that shape:
+//
+//     SETTINGS_SCHEMA = [ { key, kind, default, ui: { tab, group, label, hint } | null } ]
+//
+// `ui: null` means DECLARED BUT NOT SHOWN — settable through `/set <key> <value>` and
+// persisted, but with no row. That is how a value stays reachable without cluttering the
+// screen (CodeWhale hides 28 of its 87 this way).
+//
+// WHAT `kind` BUYS
+// ----------------
+// `bool` renders a toggle, `enum` a picker over `values`, `int` a number prompt, `string`
+// and `text` an editor. The surface never guesses, and a new setting needs no new UI code.
+//
+// THE DEFAULTS LIVE HERE TOO. A default written in the schema and nowhere else means
+// `/settings` can always show what a value WOULD be, even before it is set — which is the
+// difference between a settings screen and a list of the points you have already changed.
+
+import { THEME_NAMES } from './colors.js';
+
+/** Where a group appears in the rail, in display order. */
+export const SETTINGS_TABS = [
+  { id: 'appearance', label: 'Appearance', hint: 'Theme, density, motion, transcript' },
+  { id: 'prompt', label: 'Prompt', hint: 'System prompt and per-mode instructions' },
+  { id: 'model', label: 'Model', hint: 'Provider, model, thinking effort' },
+  { id: 'context', label: 'Context', hint: 'Compaction and tool-result trimming' },
+  { id: 'tools', label: 'Tools', hint: 'Permissions, delegation, shell' },
+  { id: 'advanced', label: 'Advanced', hint: 'Update, telemetry, experiments' },
+];
+
+/** Kind -> a one-word name for the value, used by the value prompt. */
+export const KIND_LABEL = {
+  bool: 'on/off',
+  int: 'number',
+  enum: 'choice',
+  string: 'text',
+  text: 'multi-line text',
+};
+
+// Defaults are STRINGS, matching what config.toml holds and what `setConfigString`
+// writes. `bool(false)` used to expand to `default: false` — a JS boolean — and every
+// comparison against `'true'` then failed, so every toggle rendered as "off" regardless of
+// its default. The kind says how a value is EDITED; the default says how it is STORED, and
+// storing is a string.
+const bool = (d) => ({ kind: 'bool', default: d ? 'true' : 'false' });
+const int = (d, min, max) => ({ kind: 'int', default: String(d), min, max });
+const en = (d, values) => ({ kind: 'enum', default: d, values });
+const str = (d) => ({ kind: 'string', default: d });
+const text = (d) => ({ kind: 'text', default: d });
+
+/**
+ * Every setting the program reads or can persist.
+ *
+ * `key` is the config.toml key verbatim — there is no rename layer, so what is written to
+ * the file is what the code reads and what `/set` accepts.
+ */
+export const SETTINGS_SCHEMA = [
+  // ---- appearance ---------------------------------------------------------
+  // The default is `dark`, NOT `auto`. Setting it to `auto` silently switched every existing
+  // setup to whatever the terminal background implies — on a light terminal, a completely
+  // different palette. A default that rearranges the user's screen is not a default.
+  // `auto` stays in the list for anyone who wants to follow the terminal.
+  //
+  // The accepted values come from `THEME_NAMES` rather than being written out here: a
+  // hardcoded list meant adding a theme needed a second edit in a different file, and
+  // forgetting it left /settings offering fewer themes than /theme did.
+  { key: 'theme', ...en('dark', THEME_NAMES),
+    ui: { tab: 'appearance', group: 'Display', label: 'Theme', hint: 'Colour scheme. `auto` follows the terminal background' } },
+  { key: 'calm_mode', ...bool(false),
+    ui: { tab: 'appearance', group: 'Display', label: 'Calm mode', hint: 'Fewer decorative flourishes; keeps the information, drops the animation' } },
+  { key: 'reduced_motion', ...bool(false),
+    ui: { tab: 'appearance', group: 'Motion', label: 'Reduced motion', hint: 'No sweeps or pulses — for a terminal over a slow link, or a preference' } },
+  { key: 'shimmer_edge', ...bool(true),
+    ui: { tab: 'appearance', group: 'Motion', label: 'Shimmer edge', hint: 'The travelling highlight on a running tool name' } },
+  { key: 'show_tool_details', ...bool(true),
+    ui: { tab: 'appearance', group: 'Transcript', label: 'Tool details', hint: 'Show arguments and output previews on tool rows' } },
+  { key: 'save_history', ...bool(true),
+    ui: { tab: 'appearance', group: 'Transcript', label: 'Save display transcript', hint: 'Keep notices, warnings, plan cards and reasoning in the saved session' } },
+  { key: 'save_thinking', ...bool(true),
+    ui: { tab: 'appearance', group: 'Transcript', label: 'Save reasoning', hint: 'Persist thinking blocks, not only the visible answer' } },
+  { key: 'cost_currency', ...en('usd', ['usd', 'cny']),
+    ui: { tab: 'appearance', group: 'Display', label: 'Cost currency', hint: 'Which unit /cost reports in' } },
+  { key: 'cny_per_usd', ...int(0, 0, 100000),
+    ui: { tab: 'appearance', group: 'Display', label: 'CNY per USD', hint: 'Exchange rate used when reporting cost in CNY; 0 means fetch it' } },
+
+  // ---- prompt -------------------------------------------------------------
+  // A text setting rather than a command: the system prompt is the largest thing a user
+  // can meaningfully tune, and it needed an editor, not a one-line argument.
+  { key: 'system_prompt', ...text(''),
+    ui: { tab: 'prompt', group: 'System', label: 'System prompt', hint: 'Replaces the built-in prompt entirely when set' } },
+  { key: 'append_system_prompt', ...text(''),
+    ui: { tab: 'prompt', group: 'System', label: 'Append to system prompt', hint: 'Added after the built-in prompt — the safer of the two' } },
+  { key: 'plan_instructions', ...text(''),
+    ui: { tab: 'prompt', group: 'Modes', label: 'Plan mode instructions', hint: 'Extra guidance while Plan mode is on' } },
+  { key: 'focus_instructions', ...text(''),
+    ui: { tab: 'prompt', group: 'Modes', label: 'Focus mode instructions', hint: 'Extra guidance while Focus mode is on' } },
+  { key: 'swarm_instructions', ...text(''),
+    ui: { tab: 'prompt', group: 'Modes', label: 'Swarm mode instructions', hint: 'Extra guidance while swarm mode is on' } },
+
+  // ---- model --------------------------------------------------------------
+  { key: 'provider', ...str(''),
+    ui: { tab: 'model', group: 'Provider', label: 'Provider', hint: 'Which provider serves requests' } },
+  { key: 'model', ...str(''),
+    ui: { tab: 'model', group: 'Provider', label: 'Model', hint: 'provider/model, as written in config.toml' } },
+  { key: 'default_model', ...str(''),
+    ui: { tab: 'model', group: 'Provider', label: 'Default model', hint: 'Used when a session does not name one' } },
+  { key: 'secondary_model', ...str(''),
+    ui: { tab: 'model', group: 'Delegation', label: 'Secondary model', hint: 'For side tasks: titles, compaction summaries' } },
+  { key: 'subagent_model', ...str(''),
+    ui: { tab: 'model', group: 'Delegation', label: 'Subagent model', hint: 'What the Agent tool uses; empty means the main model' } },
+  { key: 'effort', ...en('off', ['off', 'on', 'low', 'medium', 'high', 'max']),
+    ui: { tab: 'model', group: 'Thinking', label: 'Thinking effort', hint: 'Only the levels the current model declares are offered' } },
+  { key: 'max_context_tokens', ...int(0, 0, 10000000),
+    ui: { tab: 'model', group: 'Thinking', label: 'Context window', hint: 'Override the model window when the catalog is wrong; 0 means use it' } },
+  { key: 'prompt_cache', ...bool(true),
+    ui: { tab: 'model', group: 'Provider', label: 'Prompt caching', hint: 'Ask the provider to cache the request prefix' } },
+
+  // ---- context ------------------------------------------------------------
+  { key: 'auto_compact', ...bool(true),
+    ui: { tab: 'context', group: 'Compaction', label: 'Auto-compact', hint: 'Summarize older history when the window fills' } },
+  { key: 'compact_threshold', ...int(85, 1, 99),
+    ui: { tab: 'context', group: 'Compaction', label: 'Compact at %', hint: 'Share of the window at which compaction fires' } },
+  { key: 'compact_keep_ratio', ...int(20, 1, 99),
+    ui: { tab: 'context', group: 'Compaction', label: 'Keep %', hint: 'Share of the CURRENT usage kept after compaction' } },
+  { key: 'auto_trim', ...bool(true),
+    ui: { tab: 'context', group: 'Tool results', label: 'Auto-trim', hint: 'Elide old tool output from the request' } },
+  { key: 'trim_threshold', ...int(50, 1, 99),
+    ui: { tab: 'context', group: 'Tool results', label: 'Trim at %', hint: 'Share of the WINDOW that triggers a trim' } },
+  { key: 'trim_keep_ratio', ...int(30, 1, 99),
+    ui: { tab: 'context', group: 'Tool results', label: 'Keep %', hint: 'Share of the TOOL-RESULT TEXT kept after a trim — a different scale from the trigger' } },
+  { key: 'tool_result_max_bytes', ...int(51200, 1024, 10485760),
+    ui: { tab: 'context', group: 'Tool results', label: 'Max result bytes', hint: 'Larger output is written to disk and replaced with a pointer' } },
+  { key: 'tool_result_preview_bytes', ...int(2048, 128, 1048576),
+    ui: { tab: 'context', group: 'Tool results', label: 'Preview bytes', hint: 'How much of a spilled result stays inline' } },
+
+  // ---- tools --------------------------------------------------------------
+  { key: 'tool_allow_external_paths', ...bool(false),
+    ui: { tab: 'tools', group: 'Files', label: 'Allow external paths', hint: 'Let file tools read and write outside the workspace' } },
+  { key: 'swarm_mode', ...bool(false),
+    ui: { tab: 'tools', group: 'Delegation', label: 'Swarm mode', hint: 'Expose AgentSwarm for fanning work across subagents' } },
+  { key: 'output_style', ...str(''),
+    ui: { tab: 'tools', group: 'Output', label: 'Output style', hint: 'Named style overriding how replies are written' } },
+  { key: 'auto_trim_aggressive', ...bool(false), ui: null },
+  { key: 'no_delegation', ...bool(false), ui: null },
+
+  // ---- advanced -----------------------------------------------------------
+  { key: 'auto_update', ...bool(true),
+    ui: { tab: 'advanced', group: 'Updates', label: 'Auto-update', hint: 'Check npm at startup and every 30 minutes' } },
+  { key: 'experiments', ...str(''),
+    ui: { tab: 'advanced', group: 'Features', label: 'Experiments', hint: 'Comma-separated feature flags to enable' } },
+  { key: 'telemetry', ...bool(false),
+    ui: { tab: 'advanced', group: 'Features', label: 'Telemetry', hint: 'Send anonymous usage counts' } },
+  { key: 'vim_mode', ...bool(false),
+    ui: { tab: 'advanced', group: 'Editor', label: 'Vim mode', hint: 'Modal keys in the composer' } },
+  { key: 'shell', ...str(''),
+    ui: { tab: 'advanced', group: 'Editor', label: 'Shell', hint: 'Program used by the Bash tool; empty means auto-detect' } },
+  { key: 'mcp_config_path', ...str(''),
+    ui: { tab: 'advanced', group: 'MCP', label: 'MCP config path', hint: 'Defaults to ~/.hncode/mcp.json' } },
+  { key: 'checkpoints_max', ...int(500, 1, 100000),
+    ui: { tab: 'advanced', group: 'Editor', label: 'Max checkpoints', hint: 'Per-session cap on file-history entries' } },
+  { key: 'log_level', ...en('warn', ['error', 'warn', 'info', 'debug']),
+    ui: { tab: 'advanced', group: 'Diagnostics', label: 'Log level', hint: 'How much reaches session-errors.log' } },
+  { key: 'probe_timeout_ms', ...int(20000, 1000, 600000),
+    ui: { tab: 'advanced', group: 'Diagnostics', label: 'Probe timeout (ms)', hint: 'How long /doctor --probe waits for a reply' } },
+
+  // ---- the startup defaults, which had no row anywhere --------------------
+  // These already worked from config.toml but were reachable only by hand-editing it: a
+  // user could change the model from /model but not the base URL those models are reached
+  // at, and the protocol had no surface at all.
+  { key: 'base_url', ...str(''),
+    ui: { tab: 'model', group: 'Provider', label: 'Base URL', hint: 'Endpoint used when a provider does not name one' } },
+  { key: 'protocol', ...en('', ['', 'openai', 'anthropic', 'responses']),
+    ui: { tab: 'model', group: 'Provider', label: 'Protocol', hint: 'Wire format; empty detects from the provider' } },
+  { key: 'max_context_size', ...int(0, 0, 10000000),
+    ui: { tab: 'model', group: 'Thinking', label: 'Max context size', hint: 'Startup default when the catalog has no window; 0 means fall back again' } },
+  { key: 'max_output_size', ...int(0, 0, 10000000),
+    ui: { tab: 'model', group: 'Thinking', label: 'Max output size', hint: 'Startup default for the reply length; 0 means fall back' } },
+  { key: 'reasoning', ...bool(false),
+    ui: { tab: 'model', group: 'Thinking', label: 'Reasoning by default', hint: 'Whether new sessions start with thinking on' } },
+  { key: 'plugins_dir', ...str(''),
+    ui: { tab: 'advanced', group: 'MCP', label: 'Plugins directory', hint: 'Where plugins load from; defaults to ~/.hncode/plugins' } },
+  { key: 'web_host', ...str('127.0.0.1'),
+    ui: { tab: 'advanced', group: 'Web', label: 'Web host', hint: 'Address the /web daemon binds to' } },
+  { key: 'web_port', ...int(8765, 1, 65535),
+    ui: { tab: 'advanced', group: 'Web', label: 'Web port', hint: 'Fixed port for the single global daemon' } },
+];
+
+/** key -> definition, for the setter and for validation. */
+export const SETTING_BY_KEY = new Map(SETTINGS_SCHEMA.map((d) => [d.key, d]));
+
+/** The settings that get a row, grouped by tab, in schema order. */
+export function settingsForTab(tab) {
+  return SETTINGS_SCHEMA.filter((d) => d.ui && d.ui.tab === tab);
+}
+
+/** Tabs that actually have at least one row, so the rail never shows an empty section. */
+export function populatedTabs() {
+  return SETTINGS_TABS.filter((t) => settingsForTab(t.id).length > 0);
+}
+
+/** Every key `/set` accepts — including the ones with no row. */
+export function settableKeys() {
+  return SETTINGS_SCHEMA.map((d) => d.key);
+}
+
+/**
+ * Coerce a typed value to what the setting stores, or report why it cannot.
+ *
+ * The single validation point: `/settings`, `/set` and the web's `setConfig` all come
+ * through here, so they cannot disagree about what a value means.
+ *
+ * @returns {{ok: true, value: string} | {ok: false, error: string}}
+ */
+export function coerceSetting(key, input) {
+  const def = SETTING_BY_KEY.get(key);
+  if (!def) return { ok: false, error: `unknown setting: ${key}` };
+  const raw = String(input == null ? '' : input).trim();
+
+  if (def.kind === 'bool') {
+    const v = raw.toLowerCase();
+    if (['1', 'true', 'on', 'yes'].includes(v)) return { ok: true, value: 'true' };
+    if (['0', 'false', 'off', 'no', ''].includes(v)) return { ok: true, value: 'false' };
+    return { ok: false, error: `${key} is on/off; got ${JSON.stringify(input)}` };
+  }
+  if (def.kind === 'int') {
+    // Accept `85` and `85%` — the percentage settings read naturally with a sign, and
+    // the schema stores a plain number.
+    const n = Number(String(raw).replace(/%$/, ''));
+    if (!Number.isFinite(n) || !Number.isInteger(n)) return { ok: false, error: `${key} needs a whole number; got ${JSON.stringify(input)}` };
+    if (def.min != null && n < def.min) return { ok: false, error: `${key} must be at least ${def.min}` };
+    if (def.max != null && n > def.max) return { ok: false, error: `${key} must be at most ${def.max}` };
+    return { ok: true, value: String(n) };
+  }
+  if (def.kind === 'enum') {
+    if (def.values.includes(raw)) return { ok: true, value: raw };
+    // A case-insensitive hit is accepted; anything else is refused rather than coerced,
+    // because silently picking a near-miss is how a setting ends up not meaning what it
+    // says.
+    const lower = def.values.find((v) => v.toLowerCase() === raw.toLowerCase());
+    if (lower) return { ok: true, value: lower };
+    return { ok: false, error: `${key} must be one of ${def.values.join(', ')}; got ${JSON.stringify(input)}` };
+  }
+  // string / text: anything goes, including empty (which means "unset").
+  return { ok: true, value: raw };
+}
+
+/**
+ * The value in force: what is configured, else the schema default.
+ *
+ * `cfg.raw` holds what config.toml said. A value there wins even when it equals the
+ * default, so `/settings` can tell "set to X" from "unset, so X applies".
+ */
+export function effectiveValue(cfg, key) {
+  const def = SETTING_BY_KEY.get(key);
+  const raw = cfg && cfg.raw ? cfg.raw[key] : undefined;
+  if (raw === undefined || raw === null || raw === '') return def ? def.default : '';
+  return String(raw);
+}
+
+/** True when the value came from config rather than from the schema default. */
+export function isSet(cfg, key) {
+  const raw = cfg && cfg.raw ? cfg.raw[key] : undefined;
+  return raw !== undefined && raw !== null && raw !== '';
+}
+
+/** How a value reads on a row: `on`, `dark`, `85%`, or `(unset)`. */
+export function displayValue(cfg, key) {
+  const def = SETTING_BY_KEY.get(key);
+  if (!def) return '';
+  const v = effectiveValue(cfg, key);
+  if (def.kind === 'bool') return v === 'true' ? 'on' : 'off';
+  if (def.kind === 'text') {
+    if (!v) return '(unset)';
+    const first = v.split('\n')[0];
+    return v.includes('\n') || first.length > 40 ? `${first.slice(0, 40)}…` : first;
+  }
+  // An empty value reads as `(unset)` for EVERY kind, not only `string`. `protocol` is an
+  // enum whose default is the empty string, so its row rendered with a blank value column —
+  // indistinguishable from a row whose value failed to render.
+  if (!v) return '(unset)';
+  return v;
+}
+
+
+/**
+ * Which settings differ from their default, newest-first by schema order.
+ * `/settings` marks these; it is how a user sees what they have actually changed.
+ */
+export function changedSettings(cfg) {
+  return SETTINGS_SCHEMA.filter((d) => isSet(cfg, d.key)
+    && effectiveValue(cfg, d.key) !== d.default);
+}