@hncode/hncode 0.4.2 → 0.5.0

package/src/tools/diagnostics.js

@@ -0,0 +1,175 @@
+// LSP tool — real compiler diagnostics and symbol lookup, from the project's own language
+// server.
+//
+// WHY THIS IS WORTH A TOOL
+// -----------------------
+// Every other check hncode can make about an edit is textual: does the string match, does
+// the file parse as JSON, does grep find the symbol elsewhere. None of them can say "this
+// does not compile", which is the one thing a developer most wants to know after an edit.
+// A language server can, and it is already installed on many machines.
+//
+// DIAGNOSTICS ARE PUSHED, NOT PULLED
+// ----------------------------------
+// LSP has no "give me the problems in this file" request. A server sends
+// `publishDiagnostics` when it has computed them, which for a cold server is after it has
+// indexed the project — seconds, not milliseconds. So `diagnostics` waits for that
+// notification, and reports whether it ARRIVED. An empty list from a settled server means
+// the file is clean; an empty list from a timeout means "not known yet", and the two must
+// not be reported the same way, or the tool becomes a source of false confidence.
+//
+// NO SERVER IS NOT A FAILURE
+// --------------------------
+// Most machines have no server for most languages. The tool says which one it wanted and
+// what to install, and the turn carries on — a missing language server must never fail an
+// edit.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  findServer, availableServers, startClient, openDocument, waitForDiagnostics,
+  formatDiagnostic, languageFor, fileUri,
+} from '../lsp.js';
+import { resolvePath } from './utils.js';
+
+// One client per (server, root), reused across calls in a turn. Starting rust-analyzer is
+// seconds of indexing; doing it per call would make the tool useless.
+const clients = new Map();
+const clientKey = (serverId, root) => `${serverId}\u0000${root}`;
+
+async function clientFor(server, root) {
+  const key = clientKey(server.id, root);
+  const existing = clients.get(key);
+  if (existing && !existing.dead()) return existing;
+  if (existing) clients.delete(key);
+  const started = await startClient(server, root, {});
+  if (!started.ok) return { error: started.error };
+  clients.set(key, started.client);
+  return started.client;
+}
+
+/** Stop every running server. Called on exit so no orphan process is left behind. */
+export async function stopLspClients() {
+  const all = [...clients.values()];
+  clients.clear();
+  for (const c of all) { try { await c.stop(); } catch { /* going away anyway */ } }
+}
+
+/** For tests and for the TUI: which servers are live right now. */
+export function liveLspClients() {
+  return [...clients.entries()].map(([k, c]) => ({ key: k, serverId: c.serverId, root: c.root }));
+}
+
+export const spec = {
+  name: 'Diagnostics',
+  description: `Ask the project's language server for the REAL compiler errors in a file — the answer a build would give, without running one.
+
+Use it after a change that could break the build (a rename, a signature change, a new import), instead of guessing from reading the code. The file is opened in the server, so results include errors the server only knows about AFTER indexing, which can take a moment on a cold project.
+
+Supported when the matching server is installed: rust-analyzer (.rs), typescript-language-server (.ts/.js), pyright-langserver (.py), gopls (.go), clangd (.c/.cpp). If none is installed the tool says which one it wanted.
+
+The result distinguishes "no problems" from "the server did not answer in time" — never treat the second as clean.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File to check.' },
+      wait_seconds: { type: 'integer', minimum: 1, maximum: 120, description: 'How long to wait for the server to report. Default 20. A cold project needs longer.' },
+    },
+    required: ['path'],
+  },
+
+  async execute(args, ctx) {
+    if (typeof args.path !== 'string' || !args.path.trim()) return 'Error: `path` is required.';
+    let abs;
+    try { abs = resolvePath(args.path, ctx); } catch (e) { return e.message; }
+    if (!fs.existsSync(abs)) return `Error: ${args.path} does not exist.`;
+
+    const server = findServer(abs);
+    if (!server) {
+      const installed = availableServers();
+      const ext = path.extname(abs) || '(no extension)';
+      return `No language server for ${ext}. `
+        + (installed.length
+          ? `Installed here: ${installed.map((s) => `${s.id} (${s.command})`).join(', ')}.`
+          : 'None of rust-analyzer, typescript-language-server, pyright-langserver, gopls or clangd is installed.')
+        + ' Install one to get diagnostics; nothing else is affected.';
+    }
+
+    const root = ctx.workspace || ctx.cwd || process.cwd();
+    const client = await clientFor(server, root);
+    if (client.error) return `Error: could not start ${server.command}: ${client.error}`;
+
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); }
+    catch (e) { return `Error reading ${args.path}: ${e.message}`; }
+
+    // Clear the previous answer for THIS file first, so a fresh didOpen result cannot be
+    // confused with a stale one from the same server. The URI comes from `fileUri`, the
+    // same function `openDocument` uses — building it by hand here drifted on Windows,
+    // where a backslash path and a `file://` URI are not interchangeable.
+    const uri = fileUri(abs);
+    for (let i = client.notifications.length - 1; i >= 0; i--) {
+      const n = client.notifications[i];
+      if (n.method === 'textDocument/publishDiagnostics' && n.params && n.params.uri === uri) {
+        client.notifications.splice(i, 1);
+      }
+    }
+    openDocument(client, abs, text, languageFor(abs));
+
+    const waitMs = Math.min(120, Math.max(1, Number(args.wait_seconds) || 20)) * 1000;
+    const { diagnostics, settled } = await waitForDiagnostics(client, abs, waitMs);
+
+    if (!settled) {
+      return `The ${server.id} server did not report on ${args.path} within ${waitMs / 1000}s.`
+        + `\nThis is NOT a clean result — it means the answer is unknown. A large project can take`
+        + `\nlonger to index the first time; retry with a larger wait_seconds.`
+        + (client.stderrTail() ? `\n\nServer output:\n${client.stderrTail().slice(-600)}` : '');
+    }
+
+    if (!diagnostics.length) return `${args.path}: no problems reported by ${server.id}.`;
+
+    // Worst first: an error is what blocks a build, ahead of a warning or a hint.
+    const order = { error: 0, warning: 1, information: 2, hint: 3 };
+    const sorted = diagnostics.slice().sort((a, b) => {
+      const sa = order[(['', 'error', 'warning', 'information', 'hint'][a.severity || 1])] ?? 9;
+      const sb = order[(['', 'error', 'warning', 'information', 'hint'][b.severity || 1])] ?? 9;
+      if (sa !== sb) return sa - sb;
+      const la = a.range && a.range.start ? a.range.start.line : 0;
+      const lb = b.range && b.range.start ? b.range.start.line : 0;
+      return la - lb;
+    });
+    for (const d of sorted) {
+      d._file = abs;
+      // A diagnostic can point at ANOTHER file; report that file rather than this one, or
+      // an error about a type defined elsewhere reads as if it were in the file asked about.
+      if (d.relatedInformation) {
+        for (const ri of d.relatedInformation) {
+          if (ri.location && ri.location.uri) d._file = abs;
+        }
+      }
+    }
+
+    const counts = { error: 0, warning: 0, other: 0 };
+    for (const d of sorted) {
+      const name = ['', 'error', 'warning', 'information', 'hint'][d.severity || 1] || 'info';
+      if (name === 'error') counts.error += 1;
+      else if (name === 'warning') counts.warning += 1;
+      else counts.other += 1;
+    }
+    const summary = [
+      counts.error ? `${counts.error} error(s)` : '',
+      counts.warning ? `${counts.warning} warning(s)` : '',
+      counts.other ? `${counts.other} more` : '',
+    ].filter(Boolean).join(', ');
+
+    const shown = sorted.slice(0, 50);
+    const header = `${args.path}: ${summary} — from ${server.id}`;
+    const body = shown.map((d) => formatDiagnostic(d, root)).join('\n');
+    const more = sorted.length > shown.length
+      ? `\n… and ${sorted.length - shown.length} more`
+      : '';
+    return `${header}\n\n${body}${more}`;
+  },
+};
+
+/** Exported for tests. */
+export { fileUri };

package/src/tools/edit.js

@@ -28,13 +28,14 @@ import { hashRegion as hashLines } from './read.js';
 
 export const spec = {
   name: 'Edit',
-  description: 'Edit a file. THE TWO MODES ARE MUTUALLY EXCLUSIVE — NEVER combine them:\n  - LINE-RANGE mode: path + start_line + end_line + new_string. Replaces lines [start_line, end_line] with new_string. new_string is written VERBATIM: nothing is re-indented or auto-indented, so EVERY line you send — including the FIRST one — must already carry the exact leading spaces/tabs it should have. Copy that whitespace straight from the Read output, after its `N\\t` line-number prefix (Read prints `12\\t    return x`, so you send `    return x`). PREFERRED — use it whenever you have Read the file and know the line numbers.\n  - EXACT-SUBSTRING mode: path + old_string + new_string. Replaces text exactly matching old_string. Use ONLY when the exact text is known and a line range is not convenient.\nDo NOT pass start_line/end_line together with old_string/new_string in one call, and do NOT pass any of these four keys when you are not using that mode. Omitting new_string is an error, not an empty replacement (in line-range mode pass new_string; in substring mode pass old_string + new_string).',
+  description: 'Edit a file. THE TWO MODES ARE MUTUALLY EXCLUSIVE — NEVER combine them:\n- LINE-RANGE mode: path + start_line + end_line + new_string. Replaces lines [start_line, end_line] with new_string.\nPREFERRED — use it whenever you have Read the file and know the line numbers.\n- EXACT-SUBSTRING mode: path + old_string + new_string. Replaces text exactly matching old_string. Use ONLY when the exact text is known and a line range is not convenient.\nLEADING WHITESPACE — SPELL IT OUT ON EVERY LINE, INCLUDING THE FIRST. new_string is written VERBATIM in both modes: nothing is re-indented, auto-indented, or trimmed, and there is no tolerance for a missing first-line indent. Reproduce the indentation the code SHOULD have; it need not match the surrounding block. Copy it from the Read output, after its `N\\t` line-number prefix (Read prints `12\\t    return x`, so you send `    return x`).\nWRONG — the first line has no indentation, so it lands at column 0 inside an indented block:\nnew_string: "return total;\\n    total += 1;"\nRIGHT — every line carries the indentation it needs:\nnew_string: "    return total;\\n    total += 1;"\nThose are the same call; only the leading spaces on the FIRST line differ. The same applies to tabs, and to a line whose indentation changes partway through.\nRANGE HYGIENE — WRITE ONLY THE LINES YOU ARE REPLACING. Lines [start_line, end_line] are deleted and new_string is inserted in their place, so a line you leave OUTSIDE that range survives — and if you also restated it inside new_string you get TWO copies. Check what sits on end_line + 1 before deciding where the range ends.\nWRONG — end_line: 3 deletes lines 2-3, but line 4 is repeated because its content was also written into new_string:\nnew_string: "const a = 1;\\nconst b = 20;\\nconst c = 3;"\nRIGHT — the range covers exactly what is being replaced, and nothing beyond it is restated:\nnew_string: "const a = 1;\\nconst b = 20;"\nTo touch line 4 as well, set end_line: 4 and include its new content in new_string.\nIn SUBSTRING mode old_string is matched EXACTLY, including the indentation of its own first line.\nDo NOT pass start_line/end_line together with old_string/new_string in one call, and do NOT pass any of these four keys when you are not using that mode. Omitting new_string is an error, not an empty replacement (in line-range mode pass new_string; in substring mode pass old_string + new_string).\nMis-indented lines often still parse, so a green test run is not proof that an edit landed correctly — re-Read the region before editing it again.\',',
   parameters: {
     type: 'object',
     properties: {
       path: { type: 'string', description: 'Path to the file to edit.' },
       old_string: { type: 'string', description: 'Exact text to replace, including whitespace and newlines. Omit when using start_line/end_line.' },
-      new_string: { type: 'string', description: 'Replacement text, written VERBATIM. In SUBSTRING mode it replaces old_string. In LINE-RANGE mode it replaces lines [start_line, end_line], and its leading whitespace is used exactly as sent — no indentation is added, and the FIRST line needs its own. Copy it from the Read output after the `N\\t` line-number prefix (Read prints `12\\t    return x`, so you send `    return x`).' },
+      new_string: { type: 'string', description: 'Replacement text, written VERBATIM in BOTH modes — no indentation is added, removed, or re-derived. Write the leading spaces on EVERY line yourself, including the FIRST one, copying them from the Read output after its `N\\t` line-number prefix (Read prints `12\\t    return x`, so you send `    return x`). In LINE-RANGE mode it must contain EXACTLY the lines being replaced: a line that sits outside [start_line, end_line] is not deleted, so restating it here leaves a duplicate. In SUBSTRING mode it replaces old_string, which is itself matched exactly including its own indentation.' },
+
       replace_all: { type: 'boolean', default: false, description: 'Replace all occurrences of old_string.' },
       start_line: { type: 'integer', minimum: 1, description: 'PREFERRED MODE. 1-based first line to replace (requires end_line and new_string). Use this line-range mode first.' },
       end_line: { type: 'integer', minimum: 1, description: 'PREFERRED MODE. 1-based last line to replace (inclusive; requires start_line).' },
@@ -62,9 +63,9 @@ export const spec = {
     let p;
     try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
     // A Jupyter notebook is JSON, not text: a snippet edit corrupts it. Point the
-    // model at the notebook-aware path instead (mirrors Claude Code errorCode 5).
+    // model at the notebook-aware tool instead (mirrors Claude Code errorCode 5).
     if (String(p).toLowerCase().endsWith('.ipynb')) {
-      return `Error: ${args.path} is a Jupyter notebook. Its .ipynb is JSON — edit the cells through a notebook-aware tool (or edit the JSON carefully), not a plain text Edit.`;
+      return `Error: ${args.path} is a Jupyter notebook, and its .ipynb is JSON — a text replacement would corrupt it. Use NotebookEdit instead: \`{ path: ${JSON.stringify(args.path)}, action: "list" }\` to see the cells, then action "replace" with the cell index.`;
     }
     let content;
     try {
@@ -388,12 +389,26 @@ function checkStaleRange(p, curLines, start, end, ctx) {
   const normContent = curLines.join('\n');
   const curFileHash = hashStr(normContent);
 
-  // A region covers the range when it fully contains it AND still hashes the
-  // same as when it was Read.
-  const covered = entry.regions.some(
-    (r) => start >= r.start && end <= r.end && hashLines(curLines, r.start, r.end) === r.hash,
-  );
-  if (covered) return null;
+  // A range is "read" when the regions the model has SEEN cover it — not only when
+  // a single region spans it. A file read in two passes (5-10 then 11-16) must
+  // allow editing 5-16: the two slices are contiguous, both still intact, so the
+  // written range is fully known. Requiring one enclosing region rejected that
+  // perfectly safe edit and forced a third Read.
+  //
+  // Only regions whose hash STILL matches count: a region whose text changed is no
+  // longer what the model saw, so it cannot vouch for anything. The cover must also
+  // be SEAMLESS — a gap (5-10 and 12-16 with 11 unread) leaves 11 unknown, so it
+  // does NOT count, and the edit is correctly refused.
+  const intact = entry.regions
+    .filter((r) => hashLines(curLines, r.start, r.end) === r.hash)
+    .sort((a, b) => a.start - b.start);
+  let reach = start - 1;                       // highest line known to be covered
+  for (const r of intact) {
+    if (r.end < start) continue;               // entirely before the target
+    if (r.start > reach + 1) break;            // a gap opens before this region: stop
+    if (r.end > reach) reach = r.end;
+    if (reach >= end) return null;             // reached the end: fully covered
+  }
 
   if (curFileHash === entry.fileHash) {
     // No "(read so far: …)" listing: the range is what the model must act on, and

package/src/tools/grep.js

@@ -36,20 +36,25 @@ export const spec = {
     const p = normalizeInput(args.path || '.');
     const base = path.resolve(ctx.cwd || ctx.workspace, p);
     if (!fs.existsSync(base)) return `Error: path does not exist: ${args.path}`;
-    if (!args.multiline && hasRg()) return grepRg(args, base, ctx);
+    if (!args.multiline && hasRg()) return await grepRg(args, base, ctx);
     return grepJs(args, base, ctx);
   },
 };
 
+// Is ripgrep on PATH? Probed once and memoised: the probe itself is a spawn, and
+// running it on every Grep call was a pointless synchronous stall.
+let _hasRg = null;
 function hasRg() {
+  if (_hasRg !== null) return _hasRg;
   try {
     // spawnSync does NOT throw when the binary is missing — it returns
     // { error: ENOENT, status: null }. The old try/catch therefore always
     // reported "rg available", and grepRg() then returned an empty stdout as
     // "No matches found" instead of falling back to the JS walker.
     const r = cp.spawnSync('rg', ['--version'], { stdio: 'ignore' });
-    return !r.error && r.status === 0;
-  } catch { return false; }
+    _hasRg = !r.error && r.status === 0;
+  } catch { _hasRg = false; }
+  return _hasRg;
 }
 
 function buildRgArgs(args, base) {
@@ -68,23 +73,41 @@ function buildRgArgs(args, base) {
   return a;
 }
 
+// Run ripgrep ASYNCHRONOUSLY. `spawnSync` blocked the event loop for the whole
+// search — on a large repo that froze the TUI (the spinner stopped, input lagged)
+// for as long as rg ran, which is exactly the "working indicator stalls" symptom.
+// Streaming the output with an async spawn keeps the UI responsive.
 function grepRg(args, base, ctx) {
-  let out;
-  try {
-    const r = cp.spawnSync('rg', buildRgArgs(args, base), {
-      cwd: ctx.cwd || ctx.workspace,
-      maxBuffer: 64 * 1024 * 1024,
-      encoding: 'utf8',
-    });
-    // spawn failure: `r.error` set, status null. Must fall back to JS, not
-    // return an empty result as "No matches found".
-    if (r.error) return grepJs(args, base, ctx);
-    out = r.stdout || '';
-    if (r.status > 1 && r.stderr) return `rg error: ${r.stderr.trim()}`;
-  } catch (e) {
-    return grepJs(args, base, ctx);
-  }
-  return paginate(out, args);
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = cp.spawn('rg', buildRgArgs(args, base), { cwd: ctx.cwd || ctx.workspace });
+    } catch {
+      resolve(grepJs(args, base, ctx));
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const done = (fn) => { if (!settled) { settled = true; fn(); } };
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    // spawn failure (ENOENT, etc.): fall back to the JS walker rather than
+    // reporting an empty result as "No matches found".
+    child.on('error', () => done(() => resolve(grepJs(args, base, ctx))));
+    child.on('close', (code) => done(() => {
+      if (code > 1 && stderr) resolve(`rg error: ${stderr.trim()}`);
+      else resolve(paginate(stdout, args));
+    }));
+    // Honour an aborted turn (Esc): kill rg instead of leaving it running.
+    if (ctx && ctx.signal) {
+      const onAbort = () => { try { child.kill(); } catch { /* already gone */ } done(() => resolve(paginate(stdout, args))); };
+      if (ctx.signal.aborted) onAbort();
+      else ctx.signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
 }
 
 function grepJs(args, base, ctx) {
@@ -109,14 +132,33 @@ function grepJs(args, base, ctx) {
     try {
       const buf = fs.readFileSync(abs);
       if (!isProbablyTextFile(buf)) continue;
-      txt = truncateBuf(buf);
+      // The WHOLE file, not `truncateBuf(buf)`. That helper caps a tool RESULT at
+      // 128 KB, which is right for what is handed back to the model and wrong as the
+      // haystack: on this repo it cut src/tui.js (878 KB) to its first 15%, so any
+      // pattern appearing later in the file reported "No matches found" — a silent
+      // false negative on the biggest, most-edited file there is. Real ripgrep
+      // searches everything and caps only its OUTPUT, which is what happens here now:
+      // the rows are collected in full and `paginate` + `head_limit` bound the result.
+      txt = buf.toString('utf8');
     } catch { continue; }
     const mode = args.output_mode;
 
+    // Normalise CRLF -> LF BEFORE anything else. Splitting on '\n' alone left a
+    // '\r' at the end of every line in a CRLF file (which every file in this repo
+    // is), and a '\r' is a real character to a regex:
+    //   * `foo$` and `^foo$` matched NOTHING, because the line really ends "\r";
+    //   * every returned match line carried a stray '\r', cleaned up by paginate()
+    //     only for the final output — after the matching had already gone wrong.
+    // One normalisation here is what `rg` does internally, and it makes the JS
+    // path agree with it.
+    const normalized = txt.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    txt = normalized;
+
     if (args.multiline) {
       const ms = Array.from(txt.matchAll(re));
       if (ms.length === 0) continue;
       if (mode === 'files_with_matches') { out.push(abs); continue; }
+      if (mode === 'files_with_matches') { out.push(abs); continue; }
       if (mode === 'count_matches') { out.push(`${abs}:${ms.length}`); continue; }
       const lines = txt.split('\n');
       for (const mm of ms) {

package/src/tools/ignore.js

@@ -38,8 +38,20 @@ export function ignorePatternsFor(dir) {
   return arr;
 }
 
+// Compiled glob → RegExp, memoised. `matchPattern` runs for EVERY entry against
+// EVERY accumulated ignore pattern, so building a fresh RegExp each time was the
+// single largest cost of a directory walk (measured: 73ms of a 228ms walk on a
+// 354-file repo, purely in `new RegExp`). Patterns are immutable strings, so a
+// process-lifetime cache is safe.
+const reCache = new Map();
 function globToRegex(pattern) {
-  return new RegExp(globToRegexSource(pattern));
+  let re = reCache.get(pattern);
+  if (re === undefined) {
+    re = new RegExp(globToRegexSource(pattern));
+    if (reCache.size >= 4096) reCache.clear();   // bounded; patterns are few in practice
+    reCache.set(pattern, re);
+  }
+  return re;
 }
 
 export function matchPattern(pat, relPath, isDir) {
@@ -56,21 +68,27 @@ export function matchPattern(pat, relPath, isDir) {
 
 // Walk dir applying ignore patterns from root..leaf. Returns list of absolute files
 // (and dirs if includeDirs), honoring ignore unless includeIgnored.
+// Walk dir applying ignore patterns from root..leaf. Returns list of absolute files
+// (and dirs if includeDirs), honoring ignore unless includeIgnored.
+//
+// mtime and "is a file" are captured DURING the walk. The previous version stat'ed
+// every result TWICE more afterwards (once per comparison in the sort, once in the
+// file filter), which on a 354-file repo cost ~24ms of a 228ms walk — pure
+// duplication, since the information was already available as each entry was
+// visited. One stat per file now, reused for both.
 export function walkFiles(base, opts = {}) {
-  const results = [];
   const { includeIgnored = false, includeDirs = false } = opts;
   const baseAbs = path.resolve(base);
-  _walk(baseAbs, '', [], results, { includeIgnored, includeDirs });
-  // sort by mtime desc for a "most recent first" feel
-  results.sort((a, b) => {
-    try { return fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs; } catch { return b < a ? 1 : -1; }
-  });
-  if (results.length > 1000) results.length = 1000;
-  try { if (!includeDirs) return results.filter(p => { try { return fs.statSync(p).isFile(); } catch { return false; } }); } catch { return results; }
-  return results;
+  /** @type {{path:string, mtime:number, isFile:boolean}[]} */
+  const found = [];
+  _walk(baseAbs, '', [], found, { includeIgnored, includeDirs });
+  // Newest first. Sort before truncating so the newest 1000 survive the cap.
+  found.sort((a, b) => b.mtime - a.mtime);
+  if (found.length > 1000) found.length = 1000;
+  return found.filter((e) => includeDirs || e.isFile).map((e) => e.path);
 }
 
-function _walk(dir, relPrefix, parentPatterns, results, opts) {
+function _walk(dir, relPrefix, parentPatterns, found, opts) {
   const { includeIgnored, includeDirs } = opts;
   let entries;
   try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
@@ -90,10 +108,16 @@ function _walk(dir, relPrefix, parentPatterns, results, opts) {
       continue;
     }
     if (isDir) {
-      if (includeDirs) results.push(abs);
-      _walk(abs, rel, acc, results, opts);
+      if (includeDirs) {
+        let mtime = 0;
+        try { mtime = fs.statSync(abs).mtimeMs; } catch { /* keep 0 */ }
+        found.push({ path: abs, mtime, isFile: false });
+      }
+      _walk(abs, rel, acc, found, opts);
     } else {
-      results.push(abs);
+      let mtime = 0;
+      try { mtime = fs.statSync(abs).mtimeMs; } catch { /* keep 0 */ }
+      found.push({ path: abs, mtime, isFile: ent.isFile() });
     }
   }
 }

package/src/tools/index.js

@@ -17,10 +17,14 @@ import * as askUserQuestionMod from './ask-user-question.js';
 import { spec as agentSpec } from './agent.js';
 import { spec as agentSwarmSpec } from './agent-swarm.js';
 import { TaskListSpec, TaskOutputSpec, TaskStopSpec, TaskWaitSpec } from './tasks.js';
+import { AgentListSpec, AgentMessageSpec, AgentInterruptSpec, AgentCloseSpec } from './agent-control.js';
+import { spec as notebookSpec } from './notebook.js';
+import { spec as diagnosticsSpec } from './diagnostics.js';
 import * as memoryMod from './memory.js';
 import { pluginTools } from '../plugin.js';
 
 
+
 // Built-in tools.
 const builtinTools = [
   readMod.spec,
@@ -42,6 +46,12 @@ const builtinTools = [
   TaskOutputSpec,
   TaskStopSpec,
   TaskWaitSpec,
+  AgentListSpec,
+  AgentMessageSpec,
+  AgentInterruptSpec,
+  AgentCloseSpec,
+  notebookSpec,
+  diagnosticsSpec,
   memoryMod.spec,
 ];
 

package/src/tools/notebook.js

@@ -0,0 +1,113 @@
+// NotebookEdit — read and edit a Jupyter notebook by CELL.
+//
+// WHY A TOOL AND NOT A BRANCH IN `Edit`
+// ------------------------------------
+// `Edit`'s contract is "replace this text with that text", and a notebook has no text to
+// match: the source lives inside a JSON array, so a `old_string` would match in one place in
+// the .ipynb and mean something different in the cell. Expressing the operation as CELL
+// indices removes the ambiguity entirely — there is nothing to match, so nothing to match
+// wrongly.
+//
+// `tools/edit.js` still refuses a .ipynb, and now says to use THIS instead. That refusal is
+// the safety property: a notebook can only be changed through an operation that knows its
+// structure, so the corruption the refusal prevented remains impossible.
+//
+// Everything outside the edited `source` is preserved: outputs, metadata, cell ids, the
+// top-level metadata. See src/notebook.js for why that is an invariant rather than a nicety.
+
+import {
+  loadNotebook, listCells, describeCells, replaceSource, insertCell,
+  deleteCell, checkIndex, cellSource, saveNotebook,
+} from '../notebook.js';
+import { resolvePath } from './utils.js';
+import { checkpointBeforeWrite } from './utils.js';
+
+export const spec = {
+  name: 'NotebookEdit',
+  description: `Read and change a Jupyter notebook (.ipynb) by CELL. Plain Edit refuses .ipynb because a notebook is JSON — use this instead.
+
+Actions:
+- \`list\`: every cell with its index, type, line count and a one-line preview. Do this FIRST unless you already know the indices.
+- \`read\`: one cell's source in full.
+- \`replace\`: replace one cell's source. Everything else about the cell (its outputs, metadata, id) is preserved.
+- \`insert\`: add a cell BEFORE an index; use index = cell count to append.
+- \`delete\`: remove one cell.
+
+Indices are 0-based and refer to the list \`list\` prints. Recent output is kept when a cell's source is replaced, exactly as Jupyter does when you edit without re-running.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the .ipynb file.' },
+      action: { type: 'string', enum: ['list', 'read', 'replace', 'insert', 'delete'], description: 'What to do.' },
+      index: { type: 'integer', description: '0-based cell index. Required for read/replace/insert/delete. For insert, the new cell goes BEFORE this index (cell count to append).' },
+      source: { type: 'string', description: 'The cell source. Required for replace and insert.' },
+      cell_type: { type: 'string', enum: ['code', 'markdown', 'raw'], description: 'Type for an inserted cell; defaults to code.' },
+    },
+    required: ['path', 'action'],
+  },
+
+  async execute(args, ctx) {
+    if (typeof args.path !== 'string' || !args.path.trim()) return 'Error: `path` is required.';
+    const action = String(args.action || '').toLowerCase();
+    if (!['list', 'read', 'replace', 'insert', 'delete'].includes(action)) {
+      return `Error: \`action\` must be one of list, read, replace, insert, delete (got ${JSON.stringify(args.action)}).`;
+    }
+    let abs;
+    try { abs = resolvePath(args.path, ctx); } catch (e) { return e.message; }
+    if (!String(abs).toLowerCase().endsWith('.ipynb')) {
+      return `Error: ${args.path} is not a .ipynb file. Use Edit for ordinary text files.`;
+    }
+    const loaded = loadNotebook(abs);
+    if (!loaded.ok) return `Error: ${loaded.error}`;
+
+    if (action === 'list') {
+      return describeCells(loaded.doc, args.path).join('\n');
+    }
+
+    const idx = checkIndex(loaded.doc, args.index);
+    if (!idx.ok) return `Error: ${idx.error}`;
+
+    if (action === 'read') {
+      const cell = loaded.doc.cells[args.index];
+      const type = cell.cell_type || 'unknown';
+      const src = cellSource(cell);
+      return `cell ${args.index} (${type}, ${src ? src.split('\n').length : 0} line(s)):\n\n${src}`;
+    }
+
+    if (action === 'replace') {
+      if (typeof args.source !== 'string') return 'Error: `source` is required for replace.';
+      const before = cellSource(loaded.doc.cells[args.index]);
+      const r = replaceSource(loaded.doc, args.index, args.source);
+      if (!r.ok) return `Error: ${r.error}`;
+      // A checkpoint BEFORE the write, like Edit does, so /checkpoints and /undo can put
+      // the previous cell content back.
+      try { checkpointBeforeWrite(abs, ctx); } catch { /* best effort */ }
+      const saved = saveNotebook(abs, loaded.doc, loaded.indent);
+      if (!saved.ok) return `Error: saving ${args.path}: ${saved.error}`;
+      const beforeLines = before ? before.split('\n').length : 0;
+      const afterLines = args.source ? args.source.split('\n').length : 0;
+      return `Replaced the source of ${args.path} cell ${args.index} (${beforeLines} -> ${afterLines} line(s)). The cell's outputs and metadata are unchanged.`;
+    }
+
+    if (action === 'insert') {
+      if (typeof args.source !== 'string') return 'Error: `source` is required for insert.';
+      const r = insertCell(loaded.doc, args.index, args.source, args.cell_type);
+      if (!r.ok) return `Error: ${r.error}`;
+      try { checkpointBeforeWrite(abs, ctx); } catch { /* best effort */ }
+      const saved = saveNotebook(abs, loaded.doc, loaded.indent);
+      if (!saved.ok) return `Error: saving ${args.path}: ${saved.error}`;
+      return `Inserted a ${r.cell.cell_type} cell at index ${args.index} in ${args.path}. The notebook now has ${loaded.doc.cells.length} cell(s).`;
+    }
+
+    // delete
+    const r = deleteCell(loaded.doc, args.index);
+    if (!r.ok) return `Error: ${r.error}`;
+    try { checkpointBeforeWrite(abs, ctx); } catch { /* best effort */ }
+    const saved = saveNotebook(abs, loaded.doc, loaded.indent);
+    if (!saved.ok) return `Error: saving ${args.path}: ${saved.error}`;
+    return `Deleted cell ${args.index} from ${args.path}. The notebook now has ${loaded.doc.cells.length} cell(s).`;
+  },
+};
+
+/** Exported for tests: the cell list without touching the filesystem. */
+export { listCells };

package/src/tools/read-media-file.js

@@ -52,8 +52,12 @@ export const spec = {
     let p;
     try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
 
-    if (!fs.existsSync(p)) return `Error: file not found: ${args.path}`;
-    const stat = fs.statSync(p);
+    // Async fs throughout. These calls used to be sync, and an image may be tens
+    // of MB — reading it (plus the base64 encode) blocked the event loop long
+    // enough to freeze the TUI while the Working spinner was animating.
+    let stat;
+    try { stat = await fs.promises.stat(p); }
+    catch { return `Error: file not found: ${args.path}`; }
     if (!stat.isFile()) return `Error: not a file: ${args.path}`;
 
     const ext = path.extname(p).toLowerCase();
@@ -67,7 +71,10 @@ export const spec = {
           + 'Resize it, or raise the limit with HNCODE_MEDIA_MAX_BYTES.';
       }
       const mimeType = IMAGE_MIME[ext];
-      const data = fs.readFileSync(p).toString('base64');
+      let buf;
+      try { buf = await fs.promises.readFile(p); }
+      catch (e) { return `Error: could not read ${args.path}: ${e.message}`; }
+      const data = buf.toString('base64');
       const approxKB = Math.round(data.length / 1024);
       return {
         text: `[image] ${args.path} (${sizeKB}KB, ${mimeType})`,