@wrongstack/tools 0.68.0 → 0.77.0

package/dist/builtin.js

@@ -1,7 +1,7 @@
 import { spawn, execFileSync, spawnSync } from 'node:child_process';
 import * as Core from '@wrongstack/core';
 import { buildChildEnv, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, compileGlob, loadPlan, emptyPlan, clearPlan, savePlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, formatPlan, resolveWstackPaths } from '@wrongstack/core';
-import * as fs11 from 'node:fs/promises';
+import * as fs12 from 'node:fs/promises';
 import * as path from 'node:path';
 import { resolve, sep, dirname } from 'node:path';
 import * as os from 'node:os';
@@ -127,12 +127,12 @@ function safeResolve(input, ctx) {
   return ensureInsideRoot(resolvePath(input, ctx), ctx);
 }
 async function assertRealInsideRoot(absPath, ctx) {
-  const realRoot = await fs11.realpath(ctx.projectRoot).catch(() => path.resolve(ctx.projectRoot));
+  const realRoot = await fs12.realpath(ctx.projectRoot).catch(() => path.resolve(ctx.projectRoot));
   let probe = absPath;
   for (; ; ) {
     let real;
     try {
-      real = await fs11.realpath(probe);
+      real = await fs12.realpath(probe);
     } catch (err) {
       if (err.code === "ENOENT") {
         const parent = path.dirname(probe);
@@ -1296,6 +1296,17 @@ var IndexStore = class {
       ({ id, text }) => ({ id, text })
     );
   }
+  /**
+   * Largest symbol id currently in the table (0 when empty). New ids must be
+   * allocated from this, NOT from `COUNT(*)`: incremental reindexes delete a
+   * changed file's rows, so the row count drops below the max id and a
+   * count-based id would collide with a surviving row (UNIQUE constraint on
+   * `symbols.id`). Ids may have gaps — that is fine.
+   */
+  getMaxSymbolId() {
+    const rows = this.db.prepare("SELECT MAX(id) AS m FROM symbols").all();
+    return rows[0]?.m ?? 0;
+  }
   // ─── Stats ───────────────────────────────────────────────────────────────────
   getStats() {
     const sizeBytes = this.sizeBytes();
@@ -2614,8 +2625,92 @@ function makeSymbol2(opts) {
     text: `${opts.name} ${opts.signature}`.trim()
   };
 }
+function globBody(glob) {
+  return compileGlob(glob).source.replace(/^\^/, "").replace(/\$$/, "");
+}
+function compileGitignore(lines) {
+  const rules = [];
+  for (const raw of lines) {
+    let line = raw.replace(/\r$/, "");
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    line = line.trim();
+    let negated = false;
+    if (line.startsWith("!")) {
+      negated = true;
+      line = line.slice(1);
+    }
+    let dirOnly = false;
+    if (line.endsWith("/")) {
+      dirOnly = true;
+      line = line.slice(0, -1);
+    }
+    if (!line) continue;
+    const anchored = line.startsWith("/") || line.includes("/");
+    if (line.startsWith("/")) line = line.slice(1);
+    const body = globBody(line);
+    const prefix = anchored ? "^" : "(?:^|.*/)";
+    rules.push({
+      eqOrUnder: new RegExp(`${prefix}${body}(?:/.*)?$`),
+      under: new RegExp(`${prefix}${body}/.*$`),
+      negated,
+      dirOnly
+    });
+  }
+  return (relPath, isDir) => {
+    const p = relPath.replace(/\\/g, "/").replace(/^\/+/, "");
+    let ignored = false;
+    for (const r of rules) {
+      const re = r.dirOnly && !isDir ? r.under : r.eqOrUnder;
+      if (re.test(p)) ignored = !r.negated;
+    }
+    return ignored;
+  };
+}
+async function loadGitignoreMatcher(projectRoot) {
+  let lines = [];
+  try {
+    const raw = await fs12.readFile(path.join(projectRoot, ".gitignore"), "utf8");
+    lines = raw.split("\n");
+  } catch {
+  }
+  return compileGitignore(lines);
+}
+
+// src/codebase-index/background-indexer.ts
+var _ready = false;
+var _indexing = false;
+var _currentFile = 0;
+var _totalFiles = 0;
+var _lastError = null;
+function setIndexReady() {
+  _ready = true;
+}
+function getIndexState() {
+  return {
+    ready: _ready,
+    indexing: _indexing,
+    currentFile: _currentFile,
+    totalFiles: _totalFiles,
+    lastError: _lastError
+  };
+}
+var _listeners = [];
+function emitState() {
+  const state = getIndexState();
+  for (const l of _listeners) l(state);
+}
+function _setIndexProgress(current, total) {
+  _currentFile = current;
+  _totalFiles = total;
+  emitState();
+}
+Promise.resolve();
 
 // src/codebase-index/indexer.ts
+var YIELD_EVERY_N = 50;
+function yieldEventLoop() {
+  return new Promise((resolve7) => setImmediate(resolve7));
+}
 var DEFAULT_IGNORE = [
   "node_modules",
   ".git",
@@ -2627,7 +2722,7 @@ var DEFAULT_IGNORE = [
   "__snapshots__",
   ".nyc_output"
 ];
-async function findSourceFiles(projectRoot, ignore) {
+async function findSourceFiles(projectRoot, ignore, isGitIgnored) {
   const results = [];
   const ignoreSet = /* @__PURE__ */ new Set([...DEFAULT_IGNORE, ...ignore]);
   const globs = [
@@ -2645,17 +2740,19 @@ async function findSourceFiles(projectRoot, ignore) {
   const walk = async (dir) => {
     let entries;
     try {
-      entries = await fs11.readdir(dir, { withFileTypes: true });
+      entries = await fs12.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const e of entries) {
       if (ignoreSet.has(e.name)) continue;
       const full = path.join(dir, e.name);
+      const rel = path.relative(projectRoot, full).replace(/\\/g, "/");
       if (e.isDirectory()) {
+        if (isGitIgnored(rel, true)) continue;
         await walk(full);
       } else if (e.isFile()) {
-        const rel = path.relative(projectRoot, full).replace(/\\/g, "/");
+        if (isGitIgnored(rel, false)) continue;
         const ext = path.extname(e.name);
         for (const { ext: extName, pat } of globs) {
           if (ext === extName && (pat.test(rel) || pat.test(e.name))) {
@@ -2698,11 +2795,12 @@ async function runIndexer(_ctx, opts) {
   const langStats = {};
   let filesIndexed = 0;
   let symbolsIndexed = 0;
+  const isGitIgnored = await loadGitignoreMatcher(projectRoot);
   let files;
   if (opts.files && opts.files.length > 0) {
-    files = opts.files.map((f) => path.resolve(projectRoot, f));
+    files = opts.files.map((f) => path.resolve(projectRoot, f)).filter((f) => !isGitIgnored(path.relative(projectRoot, f).replace(/\\/g, "/"), false));
   } else {
-    files = await findSourceFiles(projectRoot, ignore);
+    files = await findSourceFiles(projectRoot, ignore, isGitIgnored);
   }
   if (langs && langs.length > 0) {
     const langSet = new Set(langs);
@@ -2716,10 +2814,15 @@ async function runIndexer(_ctx, opts) {
   if (!force) {
     for (const meta of store.getAllFileMetas()) existingMeta.set(meta.file, meta);
   }
-  for (const file of files) {
+  for (let fi = 0; fi < files.length; fi++) {
+    const file = files[fi];
+    _setIndexProgress(fi + 1, files.length);
+    if (fi > 0 && fi % YIELD_EVERY_N === 0) {
+      await yieldEventLoop();
+    }
     let stat10;
     try {
-      stat10 = await fs11.stat(file);
+      stat10 = await fs12.stat(file);
     } catch {
       store.deleteFile(file);
       continue;
@@ -2734,11 +2837,11 @@ async function runIndexer(_ctx, opts) {
       filesIndexed++;
       continue;
     }
-    store.deleteSymbolsForFile(file);
     store.deleteRefsForFile(file);
+    store.deleteSymbolsForFile(file);
     let content;
     try {
-      content = await fs11.readFile(file, "utf8");
+      content = await fs12.readFile(file, "utf8");
     } catch (e) {
       errors.push(`read error: ${file}: ${e instanceof Error ? e.message : String(e)}`);
       continue;
@@ -2761,7 +2864,7 @@ async function runIndexer(_ctx, opts) {
       filesIndexed++;
       continue;
     }
-    const nextId = store.getStats().totalSymbols + 1;
+    const nextId = store.getMaxSymbolId() + 1;
     const symbolsWithIds = parsed.symbols.map((s, i) => ({ ...s, id: nextId + i }));
     store.insertSymbols(symbolsWithIds, nextId);
     const count = symbolsWithIds.length;
@@ -2788,7 +2891,7 @@ async function runIndexer(_ctx, opts) {
   }
   for (const [file_] of existingMeta) {
     try {
-      await fs11.stat(file_);
+      await fs12.stat(file_);
     } catch {
       store.deleteFile(file_);
     }
@@ -2836,6 +2939,7 @@ var codebaseIndexTool = {
       langs: input.langs,
       indexDir: codebaseIndexDirOverride(ctx)
     });
+    setIndexReady();
     return result;
   }
 };
@@ -2971,6 +3075,31 @@ var codebaseSearchTool = {
     required: ["query"]
   },
   async execute(input, ctx) {
+    const state = getIndexState();
+    if (!state.ready) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: state.indexing ? `Indexing in progress (${state.currentFile}/${state.totalFiles} files) \u2014 retry in a moment.` : "Index not yet built. The codebase is being indexed at startup \u2014 search will be available shortly."
+      };
+    }
+    if (state.indexing) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index refresh in progress (${state.currentFile}/${state.totalFiles} files). Results may be incomplete.`
+      };
+    }
+    if (state.lastError) {
+      return {
+        results: [],
+        total: 0,
+        query: input.query,
+        indexStatus: `Index build failed: ${state.lastError}. Try /codebase-reindex.`
+      };
+    }
     const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const limit = Math.min(input.limit ?? 20, 100);
@@ -3028,6 +3157,32 @@ var codebaseStatsTool = {
     additionalProperties: false
   },
   async execute(_input, ctx) {
+    const idxState = getIndexState();
+    if (!idxState.ready) {
+      return {
+        totalSymbols: 0,
+        totalFiles: 0,
+        byLang: {},
+        byKind: {},
+        lastIndexed: null,
+        sizeBytes: 0,
+        indexPath: "",
+        version: SCHEMA_VERSION,
+        indexStatus: idxState.indexing ? `Indexing in progress (${idxState.currentFile}/${idxState.totalFiles} files).` : "Index not yet built."
+      };
+    }
+    if (idxState.indexing) {
+      const store2 = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
+      try {
+        const stats = store2.getStats();
+        return {
+          ...stats,
+          indexStatus: `Index refresh in progress (${idxState.currentFile}/${idxState.totalFiles} files). Stats may be incomplete.`
+        };
+      } finally {
+        store2.close();
+      }
+    }
     const store = new IndexStore(ctx.projectRoot, { indexDir: codebaseIndexDirOverride(ctx) });
     try {
       const stats = store.getStats();
@@ -3171,9 +3326,9 @@ async function fileDiff(input, ctx, _signal) {
   const results = [];
   for (const file of files) {
     const absPath = safeResolve(file, ctx);
-    const stat10 = await fs11.stat(absPath).catch(() => null);
+    const stat10 = await fs12.stat(absPath).catch(() => null);
     if (!stat10?.isFile()) continue;
-    const content = await fs11.readFile(absPath, "utf8");
+    const content = await fs12.readFile(absPath, "utf8");
     const lines = content.split(/\r?\n/);
     results.push(formatWithLineNumbers(file, lines));
   }
@@ -3235,7 +3390,7 @@ var documentTool = {
     const fileList = input.files ? await resolveFiles(Array.isArray(input.files) ? input.files.join(",") : input.files, cwd) : input.path ? [safeResolve(input.path, ctx)] : [];
     for (const absPath of fileList) {
       try {
-        const content = await fs11.readFile(absPath, "utf8");
+        const content = await fs12.readFile(absPath, "utf8");
         filesProcessed++;
         const processed = processFile(
           content,
@@ -3271,7 +3426,7 @@ async function resolveFiles(filesInput, cwd) {
   for (const f of files) {
     const absPath = f.trim().startsWith("/") ? f.trim() : `${cwd}/${f.trim()}`;
     try {
-      const stat10 = await fs11.stat(absPath);
+      const stat10 = await fs12.stat(absPath);
       if (stat10.isFile()) resolved.push(absPath);
     } catch {
     }
@@ -3363,7 +3518,7 @@ var editTool = {
     if (input.new_string === void 0) throw new Error("edit: new_string is required");
     if (input.old_string === "") throw new Error("edit: old_string cannot be empty");
     const absPath = await safeResolveReal(input.path, ctx);
-    const stat10 = await fs11.stat(absPath).catch((err) => {
+    const stat10 = await fs12.stat(absPath).catch((err) => {
       if (err.code === "ENOENT") {
         throw new Error(`edit: file "${input.path}" does not exist. Use \`write\` instead.`);
       }
@@ -3373,8 +3528,8 @@ var editTool = {
     if (!ctx.hasRead(absPath)) {
       throw new Error(`edit: file "${input.path}" was not read in this session. Read it first.`);
     }
-    const original = await fs11.readFile(absPath, "utf8");
-    const updated = await fs11.stat(absPath);
+    const original = await fs12.readFile(absPath, "utf8");
+    const updated = await fs12.stat(absPath);
     const mtimeTolerance = process.platform === "win32" ? 2e3 : 1;
     const lastReadMtime = ctx.lastReadMtime(absPath);
     if (lastReadMtime !== void 0 && updated.mtimeMs > lastReadMtime + mtimeTolerance) {
@@ -3414,7 +3569,7 @@ var editTool = {
     const newFileLf = input.replace_all ? fileLf.split(oldLf).join(newLf) : fileLf.replace(oldLf, newLf);
     const newFile = toStyle(newFileLf, style);
     await atomicWrite(absPath, newFile, { mode: updated.mode & 511 });
-    const written = await fs11.stat(absPath);
+    const written = await fs12.stat(absPath);
     ctx.recordRead(absPath, written.mtimeMs);
     ctx.session.recordFileChange({
       path: absPath,
@@ -4446,7 +4601,7 @@ var globTool = {
       }
       let entries;
       try {
-        entries = await fs11.readdir(dir, { withFileTypes: true });
+        entries = await fs12.readdir(dir, { withFileTypes: true });
       } catch {
         return;
       }
@@ -4462,7 +4617,7 @@ var globTool = {
         } else if (e.isFile()) {
           if (re.test(rel) || re.test(name)) {
             try {
-              const st = await fs11.stat(full);
+              const st = await fs12.stat(full);
               results.push({ rel: full, mtime: st.mtimeMs });
               if (results.length >= limit) {
                 truncated = true;
@@ -4481,7 +4636,7 @@ var globTool = {
 };
 async function readGitignore(dir) {
   try {
-    const raw = await fs11.readFile(path.join(dir, ".gitignore"), "utf8");
+    const raw = await fs12.readFile(path.join(dir, ".gitignore"), "utf8");
     return raw.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
   } catch {
     return [];
@@ -4763,7 +4918,7 @@ async function runNative(input, base, mode, limit, signal) {
     if (stopped || signal.aborted) return;
     let entries;
     try {
-      entries = await fs11.readdir(dir, { withFileTypes: true });
+      entries = await fs12.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -4778,9 +4933,9 @@ async function runNative(input, base, mode, limit, signal) {
         if (globRe && !globRe.test(e.name) && !globRe.test(full)) continue;
         if (globRe) globRe.lastIndex = 0;
         try {
-          const stat10 = await fs11.stat(full);
+          const stat10 = await fs12.stat(full);
           if (stat10.size > 1e6) continue;
-          const head = await fs11.readFile(full);
+          const head = await fs12.readFile(full);
           if (isBinaryBuffer(head)) continue;
           const text = head.toString("utf8");
           const lines = text.split(/\r?\n/);
@@ -4959,7 +5114,7 @@ var jsonTool = {
     let raw;
     if (input.file) {
       try {
-        raw = await fs11.readFile(input.file, "utf8");
+        raw = await fs12.readFile(input.file, "utf8");
       } catch {
         return { data: null, formatted: "", type: "unknown", error: `Could not read file` };
       }
@@ -4997,8 +5152,8 @@ var jsonTool = {
     };
   }
 };
-function query(data, path18) {
-  const parts = path18.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+function query(data, path19) {
+  const parts = path19.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
   let current = data;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;
@@ -5267,7 +5422,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
 }
 var DOCKER_LOGS_TIMEOUT_MS = 3e3;
 var MAX_TAIL_LINES = 1e5;
-async function fileLogs(path18, lines, filterRe, stream) {
+async function fileLogs(path19, lines, filterRe, stream) {
   const { createInterface } = await import('node:readline');
   const { createReadStream } = await import('node:fs');
   const entries = [];
@@ -5276,7 +5431,7 @@ async function fileLogs(path18, lines, filterRe, stream) {
   let writeIdx = 0;
   let totalLines = 0;
   const rl = createInterface({
-    input: createReadStream(path18),
+    input: createReadStream(path19),
     crlfDelay: Number.POSITIVE_INFINITY
   });
   for await (const line of rl) {
@@ -5297,7 +5452,7 @@ async function fileLogs(path18, lines, filterRe, stream) {
     if (parsed) entries.push(parsed);
   }
   return {
-    source: path18,
+    source: path19,
     entries,
     total: entries.length,
     truncated: totalLines > effLines,
@@ -5476,12 +5631,12 @@ var patchTool = {
         };
       }
     }
-    const tmpDir = await fs11.mkdtemp(path.join(os.tmpdir(), ".wstack_patch_"));
+    const tmpDir = await fs12.mkdtemp(path.join(os.tmpdir(), ".wstack_patch_"));
     try {
-      await fs11.chmod(tmpDir, 448).catch(() => {
+      await fs12.chmod(tmpDir, 448).catch(() => {
       });
       const patchFile = path.join(tmpDir, "in.diff");
-      await fs11.writeFile(patchFile, input.patch, { mode: 384 });
+      await fs12.writeFile(patchFile, input.patch, { mode: 384 });
       const args = [`-p${strip}`, "--merge", ...dryRun ? ["--dry-run"] : [], "-i", patchFile];
       const result = await runPatch(args, dir, opts.signal);
       if (result.exitCode !== 0 && !dryRun) {
@@ -5502,7 +5657,7 @@ var patchTool = {
         message: result.stdout || "patch applied"
       };
     } finally {
-      await fs11.rm(tmpDir, { recursive: true, force: true }).catch(() => {
+      await fs12.rm(tmpDir, { recursive: true, force: true }).catch(() => {
       });
     }
   }
@@ -5744,7 +5899,7 @@ var readTool = {
     const absPath = await safeResolveReal(input.path, ctx);
     let stat10;
     try {
-      stat10 = await fs11.stat(absPath);
+      stat10 = await fs12.stat(absPath);
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") throw new Error(`read: file not found "${input.path}"`);
@@ -5756,7 +5911,7 @@ var readTool = {
     if (stat10.size > MAX_BYTES2) {
       throw new Error(`read: file too large (${stat10.size} bytes, limit ${MAX_BYTES2})`);
     }
-    const buf = await fs11.readFile(absPath);
+    const buf = await fs12.readFile(absPath);
     if (isBinaryBuffer(buf)) {
       throw new Error(`read: "${input.path}" appears to be binary`);
     }
@@ -5824,11 +5979,11 @@ var replaceTool = {
     const dryRun = input.dry_run ?? false;
     const filesInput = Array.isArray(input.files) ? input.files.join(",") : input.files;
     const fileList = await resolveFiles2(filesInput, ctx, globRe);
-    const realRoot = await fs11.realpath(ctx.projectRoot).catch(() => ctx.projectRoot);
+    const realRoot = await fs12.realpath(ctx.projectRoot).catch(() => ctx.projectRoot);
     const results = [];
     let totalReplacements = 0;
     for (const absPath of fileList) {
-      const lstat2 = await fs11.lstat(absPath).catch((err) => {
+      const lstat2 = await fs12.lstat(absPath).catch((err) => {
         if (err.code === "ENOENT") return null;
         throw err;
       });
@@ -5836,17 +5991,17 @@ var replaceTool = {
       if (lstat2.isSymbolicLink()) continue;
       let realPath;
       try {
-        realPath = await fs11.realpath(absPath);
+        realPath = await fs12.realpath(absPath);
       } catch {
         continue;
       }
       const rel = path.relative(realRoot, realPath);
       if (rel.startsWith("..") || path.isAbsolute(rel)) continue;
-      const stat10 = await fs11.stat(realPath).catch(() => null);
+      const stat10 = await fs12.stat(realPath).catch(() => null);
       if (!stat10 || !stat10.isFile()) continue;
       let content;
       try {
-        const buf = await fs11.readFile(realPath);
+        const buf = await fs12.readFile(realPath);
         if (isBinaryBuffer(buf)) continue;
         content = buf.toString("utf8");
       } catch {
@@ -5898,7 +6053,7 @@ async function resolveFiles2(filesInput, ctx, extraGlob) {
   const resolved = [];
   for (const p of parts) {
     const absPath = safeResolve(p, ctx);
-    const stat10 = await fs11.stat(absPath).catch(() => null);
+    const stat10 = await fs12.stat(absPath).catch(() => null);
     if (stat10?.isFile()) {
       resolved.push(absPath);
     }
@@ -5949,7 +6104,7 @@ async function globNative(pattern, base, extraGlob) {
   const walk = async (dir) => {
     let entries;
     try {
-      entries = await fs11.readdir(dir, { withFileTypes: true });
+      entries = await fs12.readdir(dir, { withFileTypes: true });
     } catch {
       return;
     }
@@ -5957,7 +6112,7 @@ async function globNative(pattern, base, extraGlob) {
       if (DEFAULT_IGNORE4.includes(e.name)) continue;
       const full = path.join(dir, e.name);
       try {
-        const stat10 = await fs11.lstat(full);
+        const stat10 = await fs12.lstat(full);
         if (stat10.isSymbolicLink()) continue;
       } catch {
         continue;
@@ -6134,7 +6289,7 @@ async function handleBuiltIn(name, templateFiles, cwd, ctx, dryRun, vars) {
     }
     const fullPath = target;
     if (!dryRun) {
-      await fs11.mkdir(path.dirname(fullPath), { recursive: true });
+      await fs12.mkdir(path.dirname(fullPath), { recursive: true });
       await atomicWrite(fullPath, substituteVars(content, name, vars));
     }
     files.push(resolvedPath);
@@ -6525,9 +6680,10 @@ var todoTool = {
   name: "todo",
   category: "Session",
   description: "Manage the session-level todo list. This is the primary mechanism for tracking multi-step work. The list is fully replaced on every call (not appended).",
-  usageHint: "BEST PRACTICE for complex tasks:\n- At the beginning of a non-trivial task, create a clear todo list with specific, actionable items.\n- Only **one** item should be `in_progress` at any time.\n- Update the list frequently as work progresses (mark items done, add new ones, change status).\n- The system and user can see this list, so keep it honest and up-to-date.\nThis tool is extremely valuable for maintaining focus and giving the user visibility into your plan.",
+  usageHint: "BEST PRACTICE for complex tasks:\n- At the beginning of a non-trivial task, create a clear todo list with specific, actionable items.\n- Only **one** item should be `in_progress` at any time.\n- Update the list frequently as work progresses (mark items done, add new ones, change status).\n- **Re-order items** to reflect current priorities \u2014 the full list is replaced each call, so item order is entirely under your control.\n- When all items are completed the board auto-clears \u2014 you do NOT need to send an empty list.\n- The system and user can see this list, so keep it honest and up-to-date.\nThis tool is extremely valuable for maintaining focus and giving the user visibility into your plan.",
   permission: "auto",
   mutating: false,
+  // mutates only conversation state (ctx.todos), not external state — no confirmation needed
   timeoutMs: 1e3,
   inputSchema: {
     type: "object",
@@ -6773,10 +6929,14 @@ var toolSearchTool = {
       permission: t.permission,
       mutating: t.mutating
     }));
+    const totalAvailable = tools.length;
+    const hint = results.length === 0 && query2 ? `No tools matched "${input.query}". Use tool-help (without arguments) to see all ${totalAvailable} available tools.` : void 0;
     return {
       tools: results,
       total: filtered.length,
-      truncated: filtered.length > limit
+      truncated: filtered.length > limit,
+      ...hint ? { hint } : {},
+      _available: totalAvailable
     };
   }
 };
@@ -6986,7 +7146,7 @@ var treeTool = {
   }
 };
 async function walkDir(dir, depth, opts) {
-  const entries = await fs11.readdir(dir, { withFileTypes: true }).catch(() => []);
+  const entries = await fs12.readdir(dir, { withFileTypes: true }).catch(() => []);
   const filtered = entries.filter((e) => {
     if (!opts.showHidden && e.name.startsWith(".")) return false;
     if (opts.exclude.has(e.name)) return false;
@@ -7134,14 +7294,14 @@ var writeTool = {
     let existed = false;
     let prev = "";
     try {
-      const stat11 = await fs11.stat(absPath);
+      const stat11 = await fs12.stat(absPath);
       existed = stat11.isFile();
       if (existed) {
         if (!ctx.hasRead(absPath)) {
-          prev = await fs11.readFile(absPath, "utf8");
+          prev = await fs12.readFile(absPath, "utf8");
           ctx.recordRead(absPath, stat11.mtimeMs);
         } else {
-          prev = await fs11.readFile(absPath, "utf8");
+          prev = await fs12.readFile(absPath, "utf8");
         }
       }
     } catch (err) {
@@ -7152,7 +7312,7 @@ var writeTool = {
     await atomicWrite(absPath, input.content);
     const diff = existed ? unifiedDiff(prev, input.content, { fromFile: input.path, toFile: input.path }) : `+++ ${input.path}
 + (new file, ${input.content.split("\n").length} lines)`;
-    const stat10 = await fs11.stat(absPath);
+    const stat10 = await fs12.stat(absPath);
     ctx.recordRead(absPath, stat10.mtimeMs);
     ctx.session.recordFileChange({
       path: absPath,