@hncode/hncode 0.5.2 → 0.5.4

package/src/cache.js

@@ -1,131 +1,176 @@
-// Prompt caching — explicit cache breakpoints for long, stable prefixes.
-//
-// Why this is worth doing: an agent resends the whole conversation every turn,
-// and the prefix (system prompt + tool definitions + early messages) is
-// byte-identical across turns. Providers that support prompt caching bill those
-// tokens at a fraction of the input price and skip the prefill compute. Without
-// explicit breakpoints only the providers that cache automatically benefit.
-//
-// Protocol differences:
-//   * anthropic — explicit: mark up to N breakpoints with
-//     `cache_control: { type: "ephemeral" }`. Anthropic caches everything UP TO
-//     and INCLUDING a marked block, so the LAST breakpoint should sit at the end
-//     of the stable prefix. The minimum cacheable prefix is model-dependent
-//     (~1024 tokens); marking a shorter prefix is a no-op, not an error.
-//   * openai — automatic for prompts over ~1024 tokens on supporting models. A
-//     stable `prompt_cache_key` improves routing; keys must not vary per request.
-//   * everything else — no-op. Unknown providers are left untouched: sending an
-//     unsupported `cache_control` field can 400 some gateways.
-//
-// The cache is only useful when the prefix is STABLE, so the helpers here take
-// care to mark the same positions every turn for the same conversation.
-
-import { estimateTokens } from './term.js';
-
-// Anthropic allows at most 4 cache breakpoints per request.
-export const MAX_BREAKPOINTS = 4;
-// Below this, a breakpoint is pointless: most providers will not cache a prefix
-// this short, and the marker is wasted budget.
-export const MIN_CACHEABLE_TOKENS = 1024;
-
-export function supportsCaching(protocol) {
-  return protocol === 'anthropic' || protocol === 'openai' || protocol === 'responses';
-}
-
-// Index (into `messages`) of the last message that belongs to the STABLE prefix.
-//
-// The prefix is only cacheable while it cannot change between turns. The system
-// prompt and tool list are fixed for a session; the conversation then grows by
-// APPENDING. So the prefix is "everything except the recent tail", and the tail
-// must be excluded because it is what changes next turn.
-//
-// We keep the last `keepTail` messages out of the cached region: a tool result
-// appended this turn is not part of the stable prefix next turn until it is
-// itself superseded. Returns -1 when there is nothing worth marking.
-export function stablePrefixEnd(messages, keepTail = 2) {
-  const n = Array.isArray(messages) ? messages.length : 0;
-  if (n === 0) return -1;
-  // Never mark the very last message: it is the newest content and is the most
-  // likely to be replaced/regenerated.
-  const end = Math.min(n - 1, n - 1 - Math.max(1, keepTail));
-  return end >= 0 ? end : -1;
-}
-
-// Attach Anthropic `cache_control` breakpoints to a request body IN PLACE-safe
-// fashion (returns a new body). Breakpoints are placed:
-//   1. on the LAST tool definition (caches the whole tool block),
-//   2. on the system prompt (caches tools + system together),
-//   3. on the last message of the stable prefix (caches the conversation head).
-// Marking the tail first and working backwards keeps the total <= MAX_BREAKPOINTS.
-export function withAnthropicCache(body, opts = {}) {
-  if (!body || typeof body !== 'object') return body;
-  const minTokens = opts.minTokens || MIN_CACHEABLE_TOKENS;
-  const out = { ...body };
-  const marker = { type: 'ephemeral' };
-
-  // Tools: marking the last one caches the entire tools array.
-  if (Array.isArray(out.tools) && out.tools.length) {
-    const tools = out.tools.slice();
-    tools[tools.length - 1] = { ...tools[tools.length - 1], cache_control: marker };
-    out.tools = tools;
-  }
-
-  // System: a plain string must become a text block to carry cache_control.
-  if (typeof out.system === 'string' && out.system.trim()) {
-    out.system = [{ type: 'text', text: out.system, cache_control: marker }];
-  } else if (Array.isArray(out.system) && out.system.length) {
-    const sys = out.system.slice();
-    const last = sys.length - 1;
-    sys[last] = { ...(typeof sys[last] === 'string' ? { type: 'text', text: sys[last] } : sys[last]), cache_control: marker };
-    out.system = sys;
-  }
-
-  // Conversation head: mark the stable prefix's last message.
-  if (Array.isArray(out.messages) && out.messages.length) {
-    const end = stablePrefixEnd(out.messages, opts.keepTail);
-    if (end >= 0 && end < out.messages.length) {
-      // Only worth a breakpoint once the prefix is long enough to cache.
-      const prefixText = out.messages.slice(0, end + 1)
-        .map((m) => (typeof m.content === 'string' ? m.content
-          : Array.isArray(m.content) ? m.content.map((b) => b.text || '').join('') : ''))
-        .join('\n');
-      if (estimateTokens(prefixText) >= minTokens) {
-        const msgs = out.messages.slice();
-        const msg = { ...msgs[end] };
-        if (typeof msg.content === 'string') {
-          msg.content = [{ type: 'text', text: msg.content }];
-        }
-        if (Array.isArray(msg.content) && msg.content.length) {
-          const c = msg.content.slice();
-          const li = c.length - 1;
-          c[li] = { ...c[li], cache_control: marker };
-          msg.content = c;
-        }
-        msgs[end] = msg;
-        out.messages = msgs;
-      }
-    }
-  }
-  return out;
-}
-
-// OpenAI-compatible: most providers cache automatically. A STABLE
-// `prompt_cache_key` helps routing on the providers that accept it, and must not
-// change between turns of the same conversation or the cache thrashes.
-// `seed` should therefore identify the SESSION, not the request.
-export function withOpenAiCache(body, opts = {}) {
-  if (!body || typeof body !== 'object') return body;
-  const key = opts.sessionKey;
-  if (!key) return body;
-  return { ...body, prompt_cache_key: String(key) };
-}
-
-// Apply the right caching strategy for `protocol`. Returns the body unchanged
-// for protocols with no explicit support.
-export function applyPromptCache(protocol, body, opts = {}) {
-  if (!opts.enabled) return body;
-  if (protocol === 'anthropic') return withAnthropicCache(body, opts);
-  // Responses API accepts the same stable `prompt_cache_key` as chat/completions.
-  if (protocol === 'openai' || protocol === 'responses') return withOpenAiCache(body, opts);
-  return body;
+// Prompt caching — explicit cache breakpoints for long, stable prefixes.
+//
+// Why this is worth doing: an agent resends the whole conversation every turn,
+// and the prefix (system prompt + tool definitions + early messages) is
+// byte-identical across turns. Providers that support prompt caching bill those
+// tokens at a fraction of the input price and skip the prefill compute. Without
+// explicit breakpoints only the providers that cache automatically benefit.
+//
+// Protocol differences:
+//   * anthropic — explicit: mark up to N breakpoints with
+//     `cache_control: { type: "ephemeral" }`. Anthropic caches everything UP TO
+//     and INCLUDING a marked block, so the LAST breakpoint should sit at the end
+//     of the stable prefix. The minimum cacheable prefix is model-dependent
+//     (~1024 tokens); marking a shorter prefix is a no-op, not an error.
+//   * openai — automatic for prompts over ~1024 tokens on supporting models. A
+//     stable `prompt_cache_key` improves routing; keys must not vary per request.
+//   * everything else — no-op. Unknown providers are left untouched: sending an
+//     unsupported `cache_control` field can 400 some gateways.
+//
+// The cache is only useful when the prefix is STABLE, so the helpers here take
+// care to mark the same positions every turn for the same conversation.
+
+import { estimateTokens } from './term.js';
+
+// Anthropic allows at most 4 cache breakpoints per request.
+export const MAX_BREAKPOINTS = 4;
+// Below this, a breakpoint is pointless: most providers will not cache a prefix
+// this short, and the marker is wasted budget.
+export const MIN_CACHEABLE_TOKENS = 1024;
+
+export function supportsCaching(protocol) {
+  return protocol === 'anthropic' || protocol === 'openai' || protocol === 'responses';
+}
+
+// Index (into `messages`) of the last message that belongs to the STABLE prefix.
+// The prefix is only cacheable while it cannot change between turns. The system
+// prompt and tool list are fixed for a session; the conversation then grows by
+// APPENDING. So the prefix is "everything except the recent tail", and the tail
+// must be excluded because it is what changes next turn.
+//
+// We keep the last `keepTail` messages out of the cached region: a tool result
+// appended this turn is not part of the stable prefix next turn until it is
+// itself superseded. Returns -1 when there is nothing worth marking.
+export function stablePrefixEnd(messages, keepTail = 2) {
+  const n = Array.isArray(messages) ? messages.length : 0;
+  if (n === 0) return -1;
+  // Never mark the very last message: it is the newest content and is the most
+  // likely to be replaced/regenerated.
+  const end = Math.min(n - 1, n - 1 - Math.max(1, keepTail));
+  return end >= 0 ? end : -1;
+}
+
+// Attach Anthropic `cache_control` breakpoints to a request body IN PLACE-safe
+// Total character length of the prefix's content. `.length` is O(1) per string,
+// so this is O(#messages) — versus the full-string join plus the per-character
+// token walk the decision below used to make on EVERY request (and on every
+// retry attempt): ~1 MB of building and ~1M loop iterations on a 200k-token
+// history.
+function prefixContentLength(messages, end) {
+  let n = 0;
+  for (let i = 0; i <= end; i++) {
+    const c = messages[i] && messages[i].content;
+    if (typeof c === 'string') n += c.length;
+    else if (Array.isArray(c)) {
+      for (const b of c) if (b && typeof b.text === 'string') n += b.text.length;
+    }
+  }
+  return n;
+}
+
+// Memo of the last decision, keyed by `end:totalLength`. Tool-result trimming
+// rewrites content in place, which changes the length and so invalidates it.
+let _prefixDecision = { key: '', cacheable: false };
+
+// Attach Anthropic `cache_control` breakpoints to a request body IN PLACE-safe
+// fashion (returns a new body). Breakpoints are placed:
+//   1. on the LAST tool definition (caches the whole tool block),
+//   2. on the system prompt (caches tools + system together),
+//   3. on the last message of the stable prefix (caches the conversation head).
+// Marking the tail first and working backwards keeps the total <= MAX_BREAKPOINTS.
+//
+// `cacheEnd` is the index of the last message that belongs to the stable prefix,
+// counted by the CALLER. The agent loop knows it exactly — everything before that
+// index was already sent in an earlier request of this turn — so passing it beats
+// any guess made from the message count here.
+export function withAnthropicCache(body, opts = {}) {
+  if (!body || typeof body !== 'object') return body;
+  const minTokens = opts.minTokens || MIN_CACHEABLE_TOKENS;
+  const out = { ...body };
+  const marker = { type: 'ephemeral' };
+
+  // Tools: marking the last one caches the entire tools array.
+  if (Array.isArray(out.tools) && out.tools.length) {
+    const tools = out.tools.slice();
+    tools[tools.length - 1] = { ...tools[tools.length - 1], cache_control: marker };
+    out.tools = tools;
+  }
+
+  // System: a plain string must become a text block to carry cache_control.
+  if (typeof out.system === 'string' && out.system.trim()) {
+    out.system = [{ type: 'text', text: out.system, cache_control: marker }];
+  } else if (Array.isArray(out.system) && out.system.length) {
+    const sys = out.system.slice();
+    const last = sys.length - 1;
+    sys[last] = { ...(typeof sys[last] === 'string' ? { type: 'text', text: sys[last] } : sys[last]), cache_control: marker };
+    out.system = sys;
+  }
+
+  // Conversation head: mark the stable prefix's last message.
+  if (Array.isArray(out.messages) && out.messages.length) {
+    // The caller's boundary when it has one; otherwise fall back to counting off
+    // the tail. A caller's value ABOVE the last index means the array grew after it
+    // was taken, so it is clamped to the end rather than rejected — the prefix it
+    // describes is still the stable one, it just no longer reaches the tail.
+    const n = out.messages.length;
+    const end = Number.isInteger(opts.cacheEnd)
+      ? Math.min(n - 1, opts.cacheEnd)
+      : stablePrefixEnd(out.messages, opts.keepTail);
+    // An EMPTY prefix is not worth marking. With `cacheEnd === -1` the caller is
+    // saying "nothing has been sent yet", so every message in this request is new.
+    if (end >= 0 && end < n) {
+      // Only worth a breakpoint once the prefix is long enough to cache. Memoized
+      // on the length fingerprint; a cold decision uses ~4 chars/token — exact for
+      // ASCII code and prose, conservative for CJK (whose real token count is
+      // HIGHER than chars/4, so a marked prefix is always truly cacheable). Being
+      // wrong on the other side is a harmless no-op: the provider ignores a
+      // breakpoint on a sub-minimum prefix.
+      const plen = prefixContentLength(out.messages, end);
+      const key = `${end}:${plen}`;
+      let cacheable;
+      if (_prefixDecision.key === key) cacheable = _prefixDecision.cacheable;
+      else {
+        cacheable = plen / 4 >= minTokens;
+        _prefixDecision.key = key;
+        _prefixDecision.cacheable = cacheable;
+      }
+      if (cacheable) {
+        const msgs = out.messages.slice();
+        const msg = { ...msgs[end] };
+        if (typeof msg.content === 'string') {
+          msg.content = [{ type: 'text', text: msg.content }];
+        }
+        if (Array.isArray(msg.content) && msg.content.length) {
+          const c = msg.content.slice();
+          const li = c.length - 1;
+          c[li] = { ...c[li], cache_control: marker };
+          msg.content = c;
+        }
+        msgs[end] = msg;
+        out.messages = msgs;
+      }
+    }
+  }
+  return out;
+}
+
+// OpenAI-compatible: most providers cache automatically. A STABLE
+// `prompt_cache_key` helps routing on the providers that accept it, and must not
+// change between turns of the same conversation or the cache thrashes.
+// `seed` should therefore identify the SESSION, not the request.
+export function withOpenAiCache(body, opts = {}) {
+  if (!body || typeof body !== 'object') return body;
+  const key = opts.sessionKey;
+  if (!key) return body;
+  return { ...body, prompt_cache_key: String(key) };
+}
+
+// Apply the right caching strategy for `protocol`. Returns the body unchanged
+// for protocols with no explicit support.
+export function applyPromptCache(protocol, body, opts = {}) {
+  if (!opts.enabled) return body;
+  if (protocol === 'anthropic') return withAnthropicCache(body, opts);
+  // Responses API accepts the same stable `prompt_cache_key` as chat/completions.
+  if (protocol === 'openai' || protocol === 'responses') return withOpenAiCache(body, opts);
+  return body;
 }

package/src/clipboard.js

@@ -40,6 +40,8 @@ let helperBuf = '';     // stdout accumulated since the last sentinel
 let helperQueue = [];   // pending read() resolvers, ONE per sentinel written
 let helperBusy = false; // one command in flight at a time
 let helperReady = false; // the warm sequence has answered: the shell can take commands
+let keepAliveTimer = null; // a scheduled respawn, after the helper died
+let _shuttingDown = false; // set by the exit handler so a dead shell is not respawned during cleanup
 
 /** How long a read will wait for the helper to finish warming. It is already coming
  *  up, and waiting for a ~10ms answer beats the multi-second cold fallback. */
@@ -135,9 +137,24 @@ function runPowershell(args, opts) {
 // ------------------------------------------------------- PowerShell helper
 export function warmClipboard() {
   if (!win() || helper) return;
+  _shuttingDown = false;   // an explicit warm cancels a shutdown in progress
   startHelper(_psExe);
 }
 
+/**
+ * Stop the keep-alive respawn and let the helper die with the process.
+ *
+ * Called from the exit handler. Without it a helper that exits during shutdown would be respawned by
+ * `dropHelper`, leaving a PowerShell child running after the TUI is gone.
+ */
+export function stopClipboardHelper() {
+  _shuttingDown = true;
+  if (keepAliveTimer) { clearTimeout(keepAliveTimer); keepAliveTimer = null; }
+  const h = helper;
+  dropHelper();
+  if (h) { try { h.stdin.end(); } catch { /* already closed */ } }
+}
+
 /** Spawn the long-lived shell. `exe` is tried first; if that exe does not exist,
  *  the spawn reports ENOENT on its `error` event and this retries with 5.1. */
 function startHelper(exe) {
@@ -189,6 +206,18 @@ function dropHelper() {
   const waiting = helperQueue;
   helperQueue = [];
   for (const w of waiting) w(null);
+  // RESPAWN, unless this is a deliberate shutdown.
+  //
+  // The helper can die without anyone noticing — a shell that exits on its own, a resource hiccup — and
+  // nothing restarted it. The next paste then paid the cold path: a fresh spawn plus the warm-up
+  // sentinel, measured at 1.2 seconds, on a keypress that is supposed to be instant.
+  //
+  // A respawn is scheduled rather than immediate so a crash loop cannot spin: the shell gets a moment to
+  // be gone before a new one is asked for. `_shuttingDown` stops it after cleanup.
+  if (!_shuttingDown) {
+    if (keepAliveTimer) clearTimeout(keepAliveTimer);
+    keepAliveTimer = setTimeout(() => { if (!_shuttingDown) warmClipboard(); }, 200);
+  }
 }
 
 /** Resolve once the shell can take commands, or false when it never got there. */
@@ -278,6 +307,24 @@ export async function readText(timeoutMs = HELPER_CMD_MS) {
 // in use here), so it silently failed everywhere and image paste never worked.
 // `[Windows.Forms.Clipboard]::GetImage()` exists on Windows PowerShell 5.1 AND
 // pwsh 7 — verified on 5.1 — so it is the portable way to read a copied image.
+/**
+ * The TEXT-ONLY probe, run first.
+ *
+ * The full probe below checks three clipboard formats in order — files, text, image — so a plain text
+ * paste pays for two failed checks before the one that answers. Text is overwhelmingly the common case,
+ * and the two other checks are the slow ones: `Get-Clipboard -Format FileDropList` round-trips through
+ * the shell's COM clipboard, and `Clipboard::GetImage()` decodes an image.
+ *
+ * So the text check is split out and run alone. Only when it comes back EMPTY — no text on the clipboard,
+ * so it must be a file or an image — does the caller run the full probe. A text paste now costs one
+ * clipboard call instead of three.
+ */
+const CLIP_PROBE_TEXT = [
+  "$ErrorActionPreference='SilentlyContinue'",
+  "$t=Get-Clipboard -Raw",
+  "if($t){'T::'+[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($t))}",
+].join('; ');
+
 const CLIP_PROBE = [
   "$ErrorActionPreference='SilentlyContinue'",
   "$f=Get-Clipboard -Format FileDropList",
@@ -351,9 +398,29 @@ async function readViaHelper() {
     await new Promise((r) => setTimeout(r, 25));
   }
   if (helperBusy || !helper) return null;
+
+  // TEXT FIRST. One clipboard call instead of the full probe's three, so the common paste answers in a
+  // third of the round-trips.
   helperBusy = true;
-  const out = await helperRun(CLIP_PROBE, HELPER_CMD_MS);
-  return out == null ? null : parseClipResult(out);
+  let out;
+  try {
+    out = await helperRun(CLIP_PROBE_TEXT, HELPER_CMD_MS);
+  } finally {
+    helperBusy = false;
+  }
+  const parsed = out == null ? null : parseClipResult(out);
+  // Text found — done. An EMPTY answer means there is no text, so the clipboard holds a file or an
+  // image and the full probe is worth its cost.
+  if (parsed) return parsed;
+
+  helperBusy = true;
+  let out2;
+  try {
+    out2 = await helperRun(CLIP_PROBE, HELPER_CMD_MS);
+  } finally {
+    helperBusy = false;
+  }
+  return out2 == null ? null : parseClipResult(out2);
 }
 
 export function readClipboardContent() {

package/src/index.js

@@ -5,9 +5,8 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { resolveConfig, effectiveSnapshot, saveConfig, resolveModelArg, readPersonalPrompt } from './config.js';
 import * as sess from './session.js';
-import { Agent, SYSTEM_PROMPT } from './agent.js';
+import { Agent, SYSTEM_PROMPT, canSplitAfter } from './agent.js';
 import { llmTools } from './tools/index.js';
-import { setToolsList } from './llm.js';
 import { localVersion } from './version.js';
 import { EXIT, FORMATS, isValidFormat, buildResult, exitCodeFor, resultLine, createRunTracker, trackEvent, finalReply } from './ci.js';
 
@@ -301,13 +300,31 @@ async function runPrompt({ cfg, prompt, format, session, modelArg, timeoutSecond
     return EXIT.CONFIG;
   }
   const messages = [];
-  if (session && session.messages) for (const m of session.messages.slice(-30)) messages.push(m);
   // Same layering as the TUI: built-in prompt first, then the user's own
   // system_prompt override if any, then the /personal notes, then calm mode.
   let sysText = (cfg.systemPrompt && String(cfg.systemPrompt).trim()) || SYSTEM_PROMPT;
   const personal = readPersonalPrompt(cfg.workspace);
   if (personal) sysText += '\n\n' + personal;
   messages.push({ role: 'system', content: sysText });
+  if (session && session.messages) {
+    // Resume on a TOOL-EXCHANGE BOUNDARY: a cut that separates an assistant
+    // message from its tool results (or leaves orphaned tool results) is a 400
+    // from the provider, not just a shorter history. `canSplitAfter` is the same
+    // rule the compaction logic uses. System messages are dropped — the fresh
+    // one above is authoritative.
+    const hist = session.messages.filter((m) => m && m.role !== 'system');
+    // A session persisted mid-step can end with an assistant message whose tool
+    // results were never appended; sending it before the user message is a 400.
+    while (hist.length && hist[hist.length - 1].role === 'assistant'
+      && Array.isArray(hist[hist.length - 1].toolCalls) && hist[hist.length - 1].toolCalls.length) hist.pop();
+    let start = Math.max(0, hist.length - 30);
+    while (start > 0 && !canSplitAfter(hist, start - 1)) start++;
+    for (let i = start; i < hist.length; i++) messages.push(hist[i]);
+  }
+  // THE PROMPT ITSELF. This used to never be pushed: -p sent only the resumed
+  // history and the system message, so a fresh session answered nothing the
+  // user asked and a resumed one answered nothing new.
+  messages.push({ role: 'user', content: prompt });
   const saved = session || { id: sess.newId(), title: prompt.slice(0, 60), workspace: path.resolve(process.cwd()), model: cfg.model, createdAt: Date.now(), messages: [] };
   const tracker = createRunTracker();
   const startedAt = Date.now();
@@ -355,6 +372,13 @@ async function runPrompt({ cfg, prompt, format, session, modelArg, timeoutSecond
     await agent.run();
   } finally {
     if (timer) clearTimeout(timer);
+    // MCP stdio children were spawned for this run; most die on stdin EOF at
+    // process exit, but one that ignores EOF would linger. Kill them outright —
+    // best-effort, the result has already been produced.
+    try {
+      const mcp = await import('./mcp.js');
+      mcp.disconnectAll(mcp.getLiveConnections());
+    } catch { /* best-effort */ }
   }
   sess.saveSession(saved);
 
@@ -505,14 +529,14 @@ export async function main(argv) {
   //     starts this in the background and reports the result as a notice.
   // Failures are reported but never fatal: an unreachable server must not stop
   // the session from starting.
-  const connectMcp = async () => {
+  const connectMcp = async (mcpOpts = {}) => {
     if (cfg.mcp === false) return { servers: [], toolCount: 0 };
     try {
       const mcp = await import('./mcp.js');
       const { API } = await import('./plugin.js');
       const mcpCfg = mcp.loadMcpConfig(cfg.workspace);
       if (!Object.keys(mcpCfg.servers).length) return { servers: [], toolCount: 0 };
-      const res = await mcp.connectAll(mcpCfg, (spec) => API.registerTool(spec));
+      const res = await mcp.connectAll(mcpCfg, (spec) => API.registerTool(spec), mcpOpts);
       mcp.setLiveConnections(res.servers);
       if (process.env.HNCODE_MCP_VERBOSE === '1') {
         for (const s of res.servers) {

package/src/keybindings.js

@@ -110,13 +110,35 @@ const isCommand = (s) => typeof s === 'string' && s.trim().startsWith('/');
  * Read and validate the bindings file.
 
 /**
- * Read and validate the bindings file.
+ * Read and validate the bindings file, cached by mtime+size.
  *
- * @returns {{bindings: Map<string, {key?:string, command?:string}>, errors: string[], file: string}}
- *   `bindings` maps a NORMALISED source key to exactly one target.
+ * The TUI resolves EVERY special keystroke through this, and a readFileSync per key
+ * (an ENOENT open is still a syscall; with AV scanning on Windows it is milliseconds)
+ * sat directly in the input path. The cache returns the parsed result unchanged while
+ * the file's stat is unchanged, so an edit still takes effect immediately — the stat
+ * is the only thing a keystroke pays for.
  */
+let _kbCache = null;   // { file, mtimeMs, size, out }
 export function loadKeybindings(home) {
   const file = keybindingsFile(home);
+  try {
+    const st = fs.statSync(file);
+    if (_kbCache && _kbCache.file === file && _kbCache.mtimeMs === st.mtimeMs && _kbCache.size === st.size) {
+      return _kbCache.out;
+    }
+    const out = readKeybindingsFile(file);
+    _kbCache = { file, mtimeMs: st.mtimeMs, size: st.size, out };
+    return out;
+  } catch {
+    // Absent/unstatable: parse anyway so the error reporting below still runs,
+    // and drop the cache — the file may have just been deleted.
+    _kbCache = null;
+    return readKeybindingsFile(file);
+  }
+}
+
+/** The uncached parse (the body of the old loadKeybindings). */
+function readKeybindingsFile(file) {
   const out = { bindings: new Map(), errors: [], file };
   let raw;
   try { raw = fs.readFileSync(file, 'utf8'); }