@wrongstack/tools 0.250.0 → 0.256.0

package/dist/index.js

@@ -2,11 +2,11 @@ import * as fs4 from 'node:fs/promises';
 import * as path from 'node:path';
 import { resolve, sep, dirname, join } from 'node:path';
 import * as Core from '@wrongstack/core';
-import { atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, expectDefined, buildChildEnv, loadPlan, setPlanItemStatus, savePlan, loadTasks, saveTasks, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, emptyTaskFile, formatTaskList, formatPlan, recordPackageAction, detectPackageEcosystem, mutateTasks, emptyPlan, computeTaskItemProgress, resolveWstackPaths, truncate } from '@wrongstack/core';
+import { atomicWrite, unifiedDiff, detectNewlineStyle, normalizeToLf, toStyle, compileGlob, expectDefined, buildChildEnv, loadPlan, setPlanItemStatus, savePlan, loadTasks, saveTasks, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, emptyTaskFile, formatTaskList, formatPlan, recordPackageAction, detectPackageEcosystem, mutateTasks, emptyPlan, computeTaskItemProgress, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
 import { spawn, execFileSync, spawnSync } from 'node:child_process';
 import * as os from 'node:os';
 import * as fs7 from 'node:fs';
-import { statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { statSync, mkdirSync, createWriteStream, writeFileSync } from 'node:fs';
 import * as dns from 'node:dns/promises';
 import * as net from 'node:net';
 import { Agent } from 'undici';
@@ -18,14 +18,14 @@ import { randomUUID } from 'node:crypto';
 
 // src/read.ts
 async function detectPackageManager(cwd) {
-  const { stat: stat10 } = await import('node:fs/promises');
+  const { stat: stat11 } = await import('node:fs/promises');
   try {
-    await stat10(`${cwd}/pnpm-lock.yaml`);
+    await stat11(`${cwd}/pnpm-lock.yaml`);
     return "pnpm";
   } catch {
   }
   try {
-    await stat10(`${cwd}/yarn.lock`);
+    await stat11(`${cwd}/yarn.lock`);
     return "yarn";
   } catch {
   }
@@ -194,9 +194,9 @@ var readTool = {
   async execute(input, ctx) {
     if (!input?.path) throw new Error("read: path is required");
     const absPath = await safeResolveReal(input.path, ctx);
-    let stat10;
+    let stat11;
     try {
-      stat10 = await fs4.stat(absPath);
+      stat11 = await fs4.stat(absPath);
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") throw new Error(`read: file not found "${input.path}"`);
@@ -204,9 +204,9 @@ var readTool = {
         `read: failed to stat "${input.path}": ${err instanceof Error ? err.message : String(err)}`
       );
     }
-    if (!stat10.isFile()) throw new Error(`read: "${input.path}" is not a regular file`);
-    if (stat10.size > MAX_BYTES) {
-      throw new Error(`read: file too large (${stat10.size} bytes, limit ${MAX_BYTES})`);
+    if (!stat11.isFile()) throw new Error(`read: "${input.path}" is not a regular file`);
+    if (stat11.size > MAX_BYTES) {
+      throw new Error(`read: file too large (${stat11.size} bytes, limit ${MAX_BYTES})`);
     }
     const buf = await fs4.readFile(absPath);
     if (isBinaryBuffer(buf)) {
@@ -218,14 +218,14 @@ var readTool = {
     const offset = Math.max(1, input.offset ?? 1);
     const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
     if (limit === 0) {
-      ctx.recordRead(absPath, stat10.mtimeMs);
+      ctx.recordRead(absPath, stat11.mtimeMs);
       return { text: "", total_lines: total, encoding: "utf8", truncated: total > 0 };
     }
     const slice = allLines.slice(offset - 1, offset - 1 + limit);
     const truncated = offset - 1 + slice.length < total;
     const width = String(offset + slice.length - 1).length;
     const numbered = slice.map((line, i) => `${String(offset + i).padStart(width, " ")}\u2192${line}`).join("\n");
-    ctx.recordRead(absPath, stat10.mtimeMs);
+    ctx.recordRead(absPath, stat11.mtimeMs);
     return {
       text: numbered,
       total_lines: total,
@@ -264,12 +264,12 @@ var writeTool = {
     let existed = false;
     let prev = "";
     try {
-      const stat11 = await fs4.stat(absPath);
-      existed = stat11.isFile();
+      const stat12 = await fs4.stat(absPath);
+      existed = stat12.isFile();
       if (existed) {
         if (!ctx.hasRead(absPath)) {
           prev = await fs4.readFile(absPath, "utf8");
-          ctx.recordRead(absPath, stat11.mtimeMs);
+          ctx.recordRead(absPath, stat12.mtimeMs);
         } else {
           prev = await fs4.readFile(absPath, "utf8");
         }
@@ -282,8 +282,8 @@ 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 fs4.stat(absPath);
-    ctx.recordRead(absPath, stat10.mtimeMs);
+    const stat11 = await fs4.stat(absPath);
+    ctx.recordRead(absPath, stat11.mtimeMs);
     ctx.session.recordFileChange({
       path: absPath,
       action: existed ? "modified" : "created",
@@ -323,13 +323,13 @@ 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 fs4.stat(absPath).catch((err) => {
+    const stat11 = await fs4.stat(absPath).catch((err) => {
       if (err.code === "ENOENT") {
         throw new Error(`edit: file "${input.path}" does not exist. Use \`write\` instead.`);
       }
       throw err;
     });
-    if (!stat10.isFile()) throw new Error(`edit: "${input.path}" is not a regular file`);
+    if (!stat11.isFile()) throw new Error(`edit: "${input.path}" is not a regular file`);
     if (!ctx.hasRead(absPath)) {
       throw new Error(`edit: file "${input.path}" was not read in this session. Read it first.`);
     }
@@ -524,8 +524,8 @@ var replaceTool = {
       }
       const rel = path.relative(realRoot, realPath);
       if (rel.startsWith("..") || path.isAbsolute(rel)) continue;
-      const stat10 = await fs4.stat(realPath).catch(() => null);
-      if (!stat10 || !stat10.isFile()) continue;
+      const stat11 = await fs4.stat(realPath).catch(() => null);
+      if (!stat11 || !stat11.isFile()) continue;
       let content;
       try {
         const buf = await fs4.readFile(realPath);
@@ -550,7 +550,7 @@ var replaceTool = {
       totalReplacements += count;
       if (!dryRun) {
         const newContent = toStyle(newContentLf, style);
-        await atomicWrite(realPath, newContent, { mode: stat10.mode & 511 });
+        await atomicWrite(realPath, newContent, { mode: stat11.mode & 511 });
       }
       const diff = dryRun || matches.length > 0 ? unifiedDiff(content, toStyle(newContentLf, style), {
         fromFile: absPath,
@@ -580,8 +580,8 @@ async function resolveFiles(filesInput, ctx, extraGlob) {
   const resolved = [];
   for (const p of parts) {
     const absPath = safeResolve(p, ctx);
-    const stat10 = await fs4.stat(absPath).catch(() => null);
-    if (stat10?.isFile()) {
+    const stat11 = await fs4.stat(absPath).catch(() => null);
+    if (stat11?.isFile()) {
       resolved.push(absPath);
     }
   }
@@ -644,8 +644,8 @@ async function globNative(pattern, base, extraGlob) {
       if (DEFAULT_IGNORE.includes(e.name)) continue;
       const full = path.join(dir, e.name);
       try {
-        const stat10 = await fs4.lstat(full);
-        if (stat10.isSymbolicLink()) continue;
+        const stat11 = await fs4.lstat(full);
+        if (stat11.isSymbolicLink()) continue;
       } catch {
         continue;
       }
@@ -996,8 +996,8 @@ 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 fs4.stat(full);
-          if (stat10.size > 1e6) continue;
+          const stat11 = await fs4.stat(full);
+          if (stat11.size > 1e6) continue;
           const head = await fs4.readFile(full);
           if (isBinaryBuffer(head)) continue;
           const text = head.toString("utf8");
@@ -1037,6 +1037,107 @@ async function runNative(input, base, mode, limit, signal) {
     used: "native"
   };
 }
+var SPOOL_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
+var SPOOL_WRITE_HWM_BYTES = 4 * 1024 * 1024;
+var sweepStarted = false;
+function toolOutputDir() {
+  return path.join(wstackGlobalRoot(), "tool-output");
+}
+function sweepOldSpoolFiles(dir) {
+  if (sweepStarted) return;
+  sweepStarted = true;
+  void (async () => {
+    try {
+      const now = Date.now();
+      for (const name of await fs4.readdir(dir)) {
+        if (!name.endsWith(".log")) continue;
+        const p = path.join(dir, name);
+        try {
+          const st = await fs4.stat(p);
+          if (now - st.mtimeMs > SPOOL_RETENTION_MS) await fs4.unlink(p);
+        } catch {
+        }
+      }
+    } catch {
+    }
+  })();
+}
+function spoolNote(info) {
+  const dropped = info.droppedBytes > 0 ? `, ~${info.droppedBytes} bytes dropped under backpressure` : "";
+  return `
+[output truncated \u2014 full ${info.bytes} bytes at ${info.path}${dropped}; read/grep that file selectively instead of re-running with more output]`;
+}
+function createOutputSpool(opts) {
+  const threshold = opts.thresholdBytes ?? 32768;
+  const safeTool = opts.tool.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 40) || "tool";
+  let head = "";
+  let headBytes = 0;
+  let totalBytes = 0;
+  let droppedBytes = 0;
+  let stream = null;
+  let filePath = null;
+  let failed = false;
+  let finalized = false;
+  const open = () => {
+    if (stream || failed) return;
+    try {
+      const dir = toolOutputDir();
+      mkdirSync(dir, { recursive: true });
+      sweepOldSpoolFiles(dir);
+      const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+      const rand = Math.random().toString(36).slice(2, 6);
+      filePath = path.join(dir, `${stamp}-${safeTool}-${rand}.log`);
+      stream = createWriteStream(filePath, { flags: "w", encoding: "utf8" });
+      stream.on("error", () => {
+        failed = true;
+        stream = null;
+        filePath = null;
+      });
+      stream.write(head);
+    } catch {
+      failed = true;
+      stream = null;
+      filePath = null;
+    }
+  };
+  return {
+    write(text) {
+      if (finalized || !text) return;
+      totalBytes += Buffer.byteLength(text, "utf8");
+      if (!stream && !failed) {
+        if (headBytes + text.length <= threshold) {
+          head += text;
+          headBytes += text.length;
+          return;
+        }
+        head += text;
+        open();
+        head = "";
+        return;
+      }
+      if (stream) {
+        if (stream.writableLength > SPOOL_WRITE_HWM_BYTES) {
+          droppedBytes += Buffer.byteLength(text, "utf8");
+          return;
+        }
+        stream.write(text);
+      }
+    },
+    finalize() {
+      if (finalized) {
+        return filePath ? { path: filePath, bytes: totalBytes, droppedBytes } : null;
+      }
+      finalized = true;
+      head = "";
+      if (!stream || !filePath) return null;
+      try {
+        stream.end();
+      } catch {
+      }
+      return { path: filePath, bytes: totalBytes, droppedBytes };
+    }
+  };
+}
 
 // src/circuit-breaker.ts
 var DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
@@ -1516,7 +1617,7 @@ var bashTool = {
     })();
     const args = isWin ? ["/c", input.command] : ["-c", input.command];
     const env = buildChildEnv(ctx.session?.id);
-    const detached = isWin ? !!input.background : true;
+    const detached = !isWin;
     const startedAt = Date.now();
     if (input.background) {
       let buf2 = "";
@@ -1525,10 +1626,14 @@ var bashTool = {
         cwd: ctx.projectRoot,
         env,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        // Detached console children on Windows allocate their own VISIBLE
-        // console window (one per background command — test suites flash
-        // dozens). CREATE_NO_WINDOW suppresses it; no-op elsewhere.
+        // win32: CreateProcess IGNORES CREATE_NO_WINDOW (windowsHide) when
+        // DETACHED_PROCESS (detached: true) is set, so the console-less
+        // cmd.exe's grandchildren (node, dev servers) each allocate a fresh
+        // VISIBLE console window. detached: false lets CREATE_NO_WINDOW
+        // apply: the child gets a hidden console that grandchildren inherit.
+        // Windows children survive parent exit either way. POSIX keeps
+        // detached for the process-group kill semantics.
+        detached: !isWin,
         windowsHide: true,
         signal: opts.signal
       });
@@ -1544,24 +1649,22 @@ var bashTool = {
         });
         child2.on("close", () => registry.unregister(pid2));
       }
-      child2.stdout?.on("data", (chunk) => {
-        if (!truncated) {
-          const remain = MAX_OUTPUT - buf2.length;
-          if (remain > 0) {
-            buf2 += chunk.toString().slice(0, remain);
-          }
-          if (buf2.length >= MAX_OUTPUT) truncated = true;
+      const onBgData = (chunk) => {
+        if (truncated) return;
+        const remain = MAX_OUTPUT - buf2.length;
+        if (remain > 0) {
+          buf2 += chunk.toString().slice(0, remain);
         }
-      });
-      child2.stderr?.on("data", (chunk) => {
-        if (!truncated) {
-          const remain = MAX_OUTPUT - buf2.length;
-          if (remain > 0) {
-            buf2 += chunk.toString().slice(0, remain);
-          }
-          if (buf2.length >= MAX_OUTPUT) truncated = true;
+        if (buf2.length >= MAX_OUTPUT) {
+          truncated = true;
+          child2.stdout?.off("data", onBgData);
+          child2.stderr?.off("data", onBgData);
         }
-      });
+      };
+      child2.stdout?.on("data", onBgData);
+      child2.stderr?.on("data", onBgData);
+      child2.stdout?.unref?.();
+      child2.stderr?.unref?.();
       child2.on("close", () => {
         registry.afterCall(Date.now() - startedAt, false, bypassBreaker);
       });
@@ -1600,6 +1703,7 @@ var bashTool = {
     let pending2 = "";
     let timedOut = false;
     const timers = [];
+    const spool = createOutputSpool({ tool: "bash", thresholdBytes: MAX_OUTPUT });
     function killWithTimeout(child2, timeoutMs2) {
       if (isWin) {
         if (typeof child2.pid === "number" && child2.exitCode === null && killWin32Tree(child2.pid)) {
@@ -1705,6 +1809,7 @@ var bashTool = {
       if (buf.length < MAX_OUTPUT) {
         buf += text.slice(0, MAX_OUTPUT - buf.length);
       }
+      spool.write(text);
       pending2 += text;
       push({ kind: "data", text });
       pauseIfFlooded();
@@ -1732,10 +1837,11 @@ var bashTool = {
           if (remainder !== null) {
             yield { type: "partial_output", text: remainder };
           }
+          const spooled = spool.finalize();
           yield {
             type: "final",
             output: {
-              output: normalizeCommandOutput(buf),
+              output: normalizeCommandOutput(buf) + (spooled ? spoolNote(spooled) : ""),
               exit_code: c.code,
               timed_out: timedOut
             }
@@ -1750,6 +1856,7 @@ var bashTool = {
       }
     } finally {
       for (const t of timers) clearTimeout(t);
+      spool.finalize();
       if (isWin) opts.signal.removeEventListener("abort", onAbort);
       child.stdout?.off("data", onData);
       child.stderr?.off("data", onData);
@@ -1990,6 +2097,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     let stderr = "";
     let killed = false;
     const startedAt = Date.now();
+    const spool = createOutputSpool({ tool: `exec-${cmd}`, thresholdBytes: MAX_OUTPUT2 });
     const resolved = resolveWin32Command(cmd);
     const isWin = process.platform === "win32";
     const needsShell = isWin && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
@@ -2022,10 +2130,14 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       else signal.addEventListener("abort", onAbort, { once: true });
     }
     child.stdout?.on("data", (chunk) => {
-      if (stdout.length < MAX_OUTPUT2) stdout += chunk.toString();
+      const text = chunk.toString();
+      if (stdout.length < MAX_OUTPUT2) stdout += text;
+      spool.write(text);
     });
     child.stderr?.on("data", (chunk) => {
-      if (stderr.length < MAX_OUTPUT2) stderr += chunk.toString();
+      const text = chunk.toString();
+      if (stderr.length < MAX_OUTPUT2) stderr += text;
+      spool.write(text);
     });
     child.on("close", (code) => {
       clearTimeout(timer);
@@ -2034,10 +2146,11 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       const durationMs = Date.now() - startedAt;
       const exitCode = killed ? 124 : code ?? 1;
       registry.afterCall(durationMs, exitCode !== 0);
+      const spooled = spool.finalize();
       resolve7({
         command: cmd,
         args,
-        stdout: normalizeCommandOutput(stdout),
+        stdout: normalizeCommandOutput(stdout) + (spooled ? spoolNote(spooled) : ""),
         stderr: normalizeCommandOutput(stderr),
         exitCode,
         truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES || Buffer.byteLength(stderr, "utf8") > COMMAND_OUTPUT_MAX_BYTES,
@@ -2049,6 +2162,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       if (isWin) signal.removeEventListener("abort", onAbort);
       if (typeof pid === "number") registry.unregister(pid);
       registry.afterCall(Date.now() - startedAt, true);
+      spool.finalize();
       resolve7({
         command: cmd,
         args,
@@ -2614,6 +2728,7 @@ var todoTool = {
   mutating: false,
   // mutates only conversation state (ctx.todos), not external state — no confirmation needed
   timeoutMs: 1e3,
+  capabilities: ["session.todo"],
   inputSchema: {
     type: "object",
     properties: {
@@ -3071,8 +3186,8 @@ function findGitDir(cwd, projectRoot) {
   let dir = cwd;
   for (let i = 0; i < 20; i++) {
     try {
-      const stat10 = statSync(`${dir}/.git`);
-      if (stat10.isDirectory() || stat10.isFile()) return dir;
+      const stat11 = statSync(`${dir}/.git`);
+      if (stat11.isDirectory() || stat11.isFile()) return dir;
     } catch {
     }
     if (dir === root) break;
@@ -3311,6 +3426,7 @@ var jsonTool = {
   permission: "auto",
   mutating: false,
   timeoutMs: 5e3,
+  capabilities: ["fs.read"],
   inputSchema: {
     type: "object",
     properties: {
@@ -3375,8 +3491,8 @@ var jsonTool = {
     };
   }
 };
-function query(data, path20) {
-  const parts = path20.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+function query(data, path21) {
+  const parts = path21.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
   let current = data;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;
@@ -3505,8 +3621,8 @@ function findGitDir2(cwd) {
   let dir = cwd;
   for (let i = 0; i < 20; i++) {
     try {
-      const stat10 = statSync(path.join(dir, ".git"));
-      if (stat10.isDirectory()) return dir;
+      const stat11 = statSync(path.join(dir, ".git"));
+      if (stat11.isDirectory()) return dir;
     } catch {
     }
     const parent = path.dirname(dir);
@@ -3550,8 +3666,8 @@ async function fileDiff(input, ctx, _signal) {
   const results = [];
   for (const file of files) {
     const absPath = safeResolve(file, ctx);
-    const stat10 = await fs4.stat(absPath).catch(() => null);
-    if (!stat10?.isFile()) continue;
+    const stat11 = await fs4.stat(absPath).catch(() => null);
+    if (!stat11?.isFile()) continue;
     const content = await fs4.readFile(absPath, "utf8");
     const lines = content.split(/\r?\n/);
     results.push(formatWithLineNumbers(file, lines));
@@ -3754,16 +3870,29 @@ async function* spawnStream(opts) {
   let stderr = "";
   let pending2 = "";
   let error;
+  const spool = createOutputSpool({ tool: opts.cmd, thresholdBytes: max });
   const cmd = resolveWin32Command(opts.cmd);
-  const needsShell = process.platform === "win32" && (cmd.endsWith(".cmd") || cmd.endsWith(".bat"));
+  const isWin = process.platform === "win32";
+  const needsShell = isWin && (cmd.endsWith(".cmd") || cmd.endsWith(".bat"));
   const child = spawn(cmd, opts.args, {
     cwd: opts.cwd,
-    signal: opts.signal,
     env: buildChildEnv(),
     stdio: ["ignore", "pipe", "pipe"],
     windowsHide: true,
+    ...isWin ? {} : { signal: opts.signal },
     ...needsShell ? { shell: true, windowsVerbatimArguments: true } : {}
   });
+  const registry = getProcessRegistry();
+  const pid = child.pid;
+  if (typeof pid === "number") {
+    registry.register({
+      pid,
+      name: opts.cmd,
+      command: redactCommand(`${opts.cmd} ${opts.args.join(" ")}`),
+      startedAt: Date.now(),
+      child
+    });
+  }
   const queue = [];
   let waiter;
   let paused = false;
@@ -3781,9 +3910,10 @@ async function* spawnStream(opts) {
       child.stderr?.resume();
     }
   };
-  child.stdout?.on("data", (c) => {
+  const onOut = (c) => {
     const s = c.toString();
     if (stdout.length < max) stdout += s;
+    spool.write(s);
     queue.push({ kind: "out", data: s });
     wake();
     if (!paused && queue.length >= maxQueue) {
@@ -3791,10 +3921,11 @@ async function* spawnStream(opts) {
       child.stdout?.pause();
       child.stderr?.pause();
     }
-  });
-  child.stderr?.on("data", (c) => {
+  };
+  const onErr = (c) => {
     const s = c.toString();
     if (stderr.length < max) stderr += s;
+    spool.write(s);
     queue.push({ kind: "err", data: s });
     wake();
     if (!paused && queue.length >= maxQueue) {
@@ -3802,51 +3933,92 @@ async function* spawnStream(opts) {
       child.stdout?.pause();
       child.stderr?.pause();
     }
-  });
+  };
+  child.stdout?.on("data", onOut);
+  child.stderr?.on("data", onErr);
   child.on("error", (e) => {
     error = e.message;
     queue.push({ kind: "error", data: e.message });
     wake();
   });
   child.on("close", (code) => {
+    if (typeof pid === "number") registry.unregister(pid);
     queue.push({ kind: "close", data: "", code: code ?? 0 });
     wake();
   });
+  const onAbort = () => {
+    if (typeof pid === "number") {
+      registry.kill(pid, { force: true });
+    } else {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+    }
+    queue.push({ kind: "close", data: "", code: 124 });
+    wake();
+  };
+  if (opts.signal.aborted) onAbort();
+  else opts.signal.addEventListener("abort", onAbort, { once: true });
   let exitCode = 0;
   let spawnFailed = false;
-  for (; ; ) {
-    while (queue.length === 0) {
-      await new Promise((resolve7) => {
-        waiter = resolve7;
-      });
-    }
-    const chunk = queue.shift();
-    resume();
-    if (chunk.kind === "close") {
-      if (!spawnFailed) exitCode = chunk.code ?? 0;
-      break;
-    }
-    if (chunk.kind === "error") {
-      spawnFailed = true;
-      exitCode = 1;
-      continue;
+  try {
+    for (; ; ) {
+      while (queue.length === 0) {
+        await new Promise((resolve7) => {
+          waiter = resolve7;
+        });
+      }
+      const chunk = queue.shift();
+      resume();
+      if (chunk.kind === "close") {
+        if (!spawnFailed) exitCode = chunk.code ?? 0;
+        break;
+      }
+      if (chunk.kind === "error") {
+        spawnFailed = true;
+        exitCode = 1;
+        continue;
+      }
+      pending2 += chunk.data;
+      if (pending2.length >= flushAt) {
+        yield { type: "partial_output", text: pending2 };
+        pending2 = "";
+      }
     }
-    pending2 += chunk.data;
-    if (pending2.length >= flushAt) {
+    if (pending2.length > 0) {
       yield { type: "partial_output", text: pending2 };
-      pending2 = "";
+    }
+    const spooled = spool.finalize();
+    return {
+      // The marker rides on stdout's tail so every consumer's head+tail
+      // normalization keeps it without per-tool changes.
+      stdout: spooled ? stdout + spoolNote(spooled) : stdout,
+      stderr,
+      exitCode,
+      truncated: stdout.length >= max || stderr.length >= max,
+      error,
+      spoolPath: spooled?.path,
+      spoolBytes: spooled?.bytes
+    };
+  } finally {
+    spool.finalize();
+    opts.signal.removeEventListener("abort", onAbort);
+    child.stdout?.off("data", onOut);
+    child.stderr?.off("data", onErr);
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+    if (child.exitCode === null && !child.killed) {
+      if (typeof pid === "number") {
+        registry.kill(pid, { force: true });
+      } else {
+        try {
+          child.kill("SIGKILL");
+        } catch {
+        }
+      }
     }
   }
-  if (pending2.length > 0) {
-    yield { type: "partial_output", text: pending2 };
-  }
-  return {
-    stdout,
-    stderr,
-    exitCode,
-    truncated: stdout.length >= max || stderr.length >= max,
-    error
-  };
 }
 
 // src/lint.ts
@@ -3858,6 +4030,7 @@ var lintTool = {
   permission: "confirm",
   mutating: false,
   timeoutMs: 6e4,
+  capabilities: ["shell.restricted"],
   inputSchema: {
     type: "object",
     properties: {
@@ -3929,11 +4102,11 @@ var lintTool = {
   }
 };
 async function detectLinter(cwd) {
-  const { stat: stat10 } = await import('node:fs/promises');
+  const { stat: stat11 } = await import('node:fs/promises');
   const checks = ["biome.json", ".eslintrc.json", "tslint.json", ".eslintrc.js", "tsconfig.json"];
   for (const f of checks) {
     try {
-      await stat10(`${cwd}/${f}`);
+      await stat11(`${cwd}/${f}`);
       if (f.includes("biome")) return "biome";
       if (f.includes("eslint")) return "eslint";
       if (f.includes("tslint")) return "tslint";
@@ -4031,13 +4204,13 @@ var formatTool = {
   }
 };
 async function detectFixer(cwd) {
-  const { stat: stat10 } = await import('node:fs/promises');
+  const { stat: stat11 } = await import('node:fs/promises');
   try {
-    await stat10(`${cwd}/biome.json`);
+    await stat11(`${cwd}/biome.json`);
     return "biome";
   } catch {
     try {
-      await stat10(`${cwd}/.prettierrc`);
+      await stat11(`${cwd}/.prettierrc`);
       return "prettier";
     } catch {
       return "biome";
@@ -4052,6 +4225,7 @@ var typecheckTool = {
   permission: "confirm",
   mutating: false,
   timeoutMs: 12e4,
+  capabilities: ["shell.restricted"],
   inputSchema: {
     type: "object",
     properties: {
@@ -4115,11 +4289,11 @@ var typecheckTool = {
   }
 };
 async function findTsConfig(cwd) {
-  const { stat: stat10 } = await import('node:fs/promises');
+  const { stat: stat11 } = await import('node:fs/promises');
   const candidates = ["tsconfig.json", "tsconfig.base.json"];
   for (const f of candidates) {
     try {
-      const s = await stat10(path.join(cwd, f));
+      const s = await stat11(path.join(cwd, f));
       if (s.isFile()) return path.join(cwd, f);
     } catch {
     }
@@ -4134,6 +4308,7 @@ var testTool = {
   permission: "confirm",
   mutating: false,
   timeoutMs: 12e4,
+  capabilities: ["shell.restricted"],
   inputSchema: {
     type: "object",
     properties: {
@@ -4150,7 +4325,11 @@ var testTool = {
       coverage: { type: "boolean", description: "Generate coverage report (default: false)" },
       cwd: { type: "string", description: "Working directory (default: cwd)" },
       grep: { type: "string", description: "Filter tests by name pattern (default: none)" },
-      timeout: { type: "integer", description: "Test timeout in ms (default: 30000)" }
+      timeout: { type: "integer", description: "Test timeout in ms (default: 30000)" },
+      verbose: {
+        type: "boolean",
+        description: "Per-test verbose reporter output (default: false \u2014 the summary reporter is used; full output is always saved to a log file referenced in the result)"
+      }
     }
   },
   async execute(input, ctx, opts) {
@@ -4198,11 +4377,11 @@ var testTool = {
   }
 };
 async function detectRunner(cwd) {
-  const { stat: stat10 } = await import('node:fs/promises');
+  const { stat: stat11 } = await import('node:fs/promises');
   const candidates = ["vitest.config.ts", "jest.config.js", ".mocharc.json"];
   for (const f of candidates) {
     try {
-      await stat10(path.join(cwd, f));
+      await stat11(path.join(cwd, f));
       if (f.includes("vitest")) return "vitest";
       if (f.includes("jest")) return "jest";
       if (f.includes("mocha")) return "mocha";
@@ -4216,17 +4395,14 @@ function buildArgs2(runner, input) {
   const timeout = input.timeout ?? 3e4;
   switch (runner) {
     case "vitest":
-      args.push("run", "--reporter=verbose");
-      if (input.watch) {
-        args[1] = "";
-        args.push("watch");
-      }
+      args.push(input.watch ? "watch" : "run");
+      if (input.verbose) args.push("--reporter=verbose");
       if (input.coverage) args.push("--coverage");
       if (input.grep) args.push("--testNamePattern", input.grep);
       args.push("--testTimeout", String(timeout));
       break;
     case "jest":
-      args.push("--verbose");
+      if (input.verbose) args.push("--verbose");
       if (input.watch) args.push("--watch");
       if (input.coverage) args.push("--coverage");
       if (input.grep) args.push("--testPathPattern", input.grep);
@@ -4270,7 +4446,13 @@ function parseResult(runner, result, duration) {
     passed,
     failed,
     duration_ms: duration,
-    output: normalizeCommandOutput(result.stdout || result.error || ""),
+    // A passing run only needs the tail summary in chat history — counts are
+    // already parsed above and the FULL log is on disk (spool marker rides
+    // the stdout tail). Failures keep the standard command-output cap so
+    // the agent sees the failure details inline.
+    output: normalizeCommandOutput(result.stdout || result.error || "", {
+      maxBytes: result.exitCode === 0 ? 4096 : void 0
+    }),
     truncated: result.truncated
   };
 }
@@ -4419,6 +4601,7 @@ var auditTool = {
   usageHint: "CRITICAL SECURITY TOOL:\n\n- Run regularly and especially before any release.\n- Use `level` to focus on high/critical issues.\n- `fix` can attempt automatic remediation for some vulnerabilities.\nThis is one of the most important tools for supply chain security.",
   permission: "confirm",
   mutating: false,
+  capabilities: ["shell.restricted"],
   timeoutMs: 6e4,
   inputSchema: {
     type: "object",
@@ -4512,9 +4695,23 @@ var outdatedTool = {
   name: "outdated",
   category: "Package Management",
   description: "Check for outdated dependencies in the project. Reports current, wanted (semver range), and latest versions available.",
-  usageHint: "MAINTENANCE & SECURITY TOOL:\n\n- Run periodically or before dependency-related work.\n- Helps surface packages that may need updates for security or features.\n- Safe, read-only operation.\nUse the output to decide on upgrades. Prefer this over manual shell commands for dependency hygiene.",
-  permission: "auto",
-  mutating: false,
+  usageHint: "MAINTENANCE & SECURITY TOOL:\n\n- Run periodically or before dependency-related work.\n- Helps surface packages that may need updates for security or features.\n- Hits the package registry over HTTP, so it is NOT purely local \u2014 flagged as mutating for the confirmation gate.\nUse the output to decide on upgrades. Prefer this over manual shell commands for dependency hygiene.",
+  permission: "confirm",
+  // Network side-effecting (registry HTTP). Pairs with `mutating: true`
+  // so the H7 invariant test (`no auto-permission tool declares
+  // mutating: true`) passes — a tool claiming `'auto'` must be purely
+  // read-only, but `outdated` makes outbound HTTP calls to the
+  // registry. The 'confirm' permission routes the call through the
+  // tool.confirm_needed flow on every invocation. M-1 originally
+  // fixed four sibling tools (mcp_control, shellcheck, shellcheck_scan,
+  // web_search) but missed this one; applying the same contract here.
+  mutating: true,
+  // Capability is just "network" — the tool only hits the package
+  // registry over HTTP, never touches the filesystem or runs shell.
+  // The H7 invariant test requires this array to be non-empty for
+  // any mutating:true tool (meta-tools whitelisted). See
+  // tests/permission-mutating-invariant.test.ts:92.
+  capabilities: ["network"],
   timeoutMs: 6e4,
   inputSchema: {
     type: "object",
@@ -4615,6 +4812,7 @@ var logsTool = {
   permission: "confirm",
   mutating: false,
   timeoutMs: 3e4,
+  capabilities: ["shell.restricted"],
   inputSchema: {
     type: "object",
     properties: {
@@ -4736,7 +4934,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
 }
 var DOCKER_LOGS_TIMEOUT_MS = 3e3;
 var MAX_TAIL_LINES = 1e5;
-async function fileLogs(path20, lines, filterRe, stream) {
+async function fileLogs(path21, lines, filterRe, stream) {
   const { createInterface } = await import('node:readline');
   const { createReadStream } = await import('node:fs');
   const entries = [];
@@ -4745,7 +4943,7 @@ async function fileLogs(path20, lines, filterRe, stream) {
   let writeIdx = 0;
   let totalLines = 0;
   const rl = createInterface({
-    input: createReadStream(path20),
+    input: createReadStream(path21),
     crlfDelay: Number.POSITIVE_INFINITY
   });
   for await (const line of rl) {
@@ -4766,7 +4964,7 @@ async function fileLogs(path20, lines, filterRe, stream) {
     if (parsed) entries.push(parsed);
   }
   return {
-    source: path20,
+    source: path21,
     entries,
     total: entries.length,
     truncated: totalLines > effLines,
@@ -4816,6 +5014,7 @@ var documentTool = {
   permission: "auto",
   mutating: false,
   timeoutMs: 3e4,
+  capabilities: ["fs.read"],
   inputSchema: {
     type: "object",
     properties: {
@@ -4889,8 +5088,8 @@ async function resolveFiles2(filesInput, cwd) {
   for (const f of files) {
     const absPath = f.trim().startsWith("/") ? f.trim() : `${cwd}/${f.trim()}`;
     try {
-      const stat10 = await fs4.stat(absPath);
-      if (stat10.isFile()) resolved.push(absPath);
+      const stat11 = await fs4.stat(absPath);
+      if (stat11.isFile()) resolved.push(absPath);
     } catch {
     }
   }
@@ -5149,6 +5348,7 @@ var toolSearchTool = {
   permission: "auto",
   mutating: false,
   timeoutMs: 1e3,
+  capabilities: ["tool.meta"],
   inputSchema: {
     type: "object",
     properties: {
@@ -5227,6 +5427,7 @@ var toolUseTool = {
   permission: "confirm",
   mutating: true,
   timeoutMs: 6e4,
+  capabilities: ["tool.mutate.any"],
   inputSchema: {
     type: "object",
     properties: {
@@ -5296,6 +5497,7 @@ var batchToolUseTool = {
   permission: "confirm",
   mutating: true,
   timeoutMs: 12e4,
+  capabilities: ["tool.mutate.any"],
   inputSchema: {
     type: "object",
     properties: {
@@ -5400,6 +5602,7 @@ var toolHelpTool = {
   permission: "auto",
   mutating: false,
   timeoutMs: 5e3,
+  capabilities: ["tool.meta"],
   inputSchema: {
     type: "object",
     properties: {
@@ -5523,6 +5726,7 @@ function rememberTool(memory) {
     permission: "auto",
     mutating: true,
     timeoutMs: 2e3,
+    capabilities: ["memory.write"],
     inputSchema: {
       type: "object",
       properties: {
@@ -5574,6 +5778,7 @@ function forgetTool(memory) {
     permission: "confirm",
     mutating: true,
     timeoutMs: 2e3,
+    capabilities: ["memory.delete"],
     inputSchema: {
       type: "object",
       properties: {
@@ -5599,6 +5804,7 @@ function searchMemoryTool(memory) {
     permission: "auto",
     mutating: false,
     timeoutMs: 2e3,
+    capabilities: ["memory.read"],
     inputSchema: {
       type: "object",
       properties: {
@@ -5645,6 +5851,7 @@ function relatedMemoryTool(memory) {
     permission: "auto",
     mutating: false,
     timeoutMs: 2e3,
+    capabilities: ["memory.read"],
     inputSchema: {
       type: "object",
       properties: {
@@ -5693,6 +5900,7 @@ function createModeTool(modeStore) {
     permission: "confirm",
     mutating: true,
     timeoutMs: 5e3,
+    capabilities: ["session.mode"],
     inputSchema: {
       type: "object",
       properties: {
@@ -7902,20 +8110,20 @@ async function runIndexerWithStore(store, opts) {
       await yieldEventLoop();
       throwIfAborted(signal);
     }
-    let stat10;
+    let stat11;
     try {
       const statOpts = signal ? { signal } : {};
-      stat10 = await fs4.stat(file, statOpts);
+      stat11 = await fs4.stat(file, statOpts);
     } catch (e) {
       if (isAbortError(e)) throw e;
       store.deleteFile(file);
       continue;
     }
-    if (!stat10.isFile()) continue;
+    if (!stat11.isFile()) continue;
     const lang = detectLang(file);
     if (!lang) continue;
     const meta = existingMeta.get(file);
-    if (!force && meta && meta.mtimeMs === Math.floor(stat10.mtimeMs)) {
+    if (!force && meta && meta.mtimeMs === Math.floor(stat11.mtimeMs)) {
       langStats[lang] = (langStats[lang] ?? 0) + meta.symbolCount;
       symbolsIndexed += meta.symbolCount;
       filesIndexed++;
@@ -7942,7 +8150,7 @@ async function runIndexerWithStore(store, opts) {
       store.upsertFile({
         file,
         lang,
-        mtimeMs: Math.floor(stat10.mtimeMs),
+        mtimeMs: Math.floor(stat11.mtimeMs),
         symbolCount: 0,
         lastIndexed: Date.now()
       });
@@ -7968,7 +8176,7 @@ async function runIndexerWithStore(store, opts) {
     store.upsertFile({
       file,
       lang,
-      mtimeMs: Math.floor(stat10.mtimeMs),
+      mtimeMs: Math.floor(stat11.mtimeMs),
       symbolCount: count,
       lastIndexed: Date.now()
     });
@@ -8249,6 +8457,13 @@ function debounceKey(indexDir, file) {
 function isIndexableFile(filePath) {
   return detectLang(filePath) !== null;
 }
+function isUniqueConstraintError(err) {
+  if (err instanceof Error) {
+    const msg = err.message.toLowerCase();
+    return msg.includes("unique constraint") || msg.includes("UNIQUE constraint");
+  }
+  return false;
+}
 async function runStartupIndex(opts) {
   if (!indexCircuitBreaker.allowRequest()) throw circuitOpenError();
   _indexing = true;
@@ -8278,6 +8493,15 @@ async function runStartupIndex(opts) {
     return result;
   } catch (err) {
     _lastError = err instanceof Error ? err.message : String(err);
+    if (isUniqueConstraintError(err) && !opts.force) {
+      _lastError = null;
+      const rebuildResult = await runStartupIndex({
+        ...opts,
+        force: true
+      });
+      _ready = true;
+      return rebuildResult;
+    }
     _ready = true;
     if (!opts.signal?.aborted) indexCircuitBreaker.recordFailure(err);
     throw err;
@@ -8884,6 +9108,34 @@ ${formatTaskList(file.tasks)}` : file.tasks.length > 0 ? formatTaskList(file.tas
 };
 
 // src/builtin.ts
+var OPTIONAL_TOOLS = [
+  installTool,
+  auditTool,
+  outdatedTool,
+  logsTool,
+  documentTool,
+  scaffoldTool,
+  toolSearchTool,
+  toolUseTool,
+  batchToolUseTool,
+  toolHelpTool,
+  codebaseIndexTool,
+  codebaseSearchTool,
+  codebaseStatsTool,
+  setWorkingDirTool
+];
+var TIER1_TOOLS = [
+  readTool,
+  writeTool,
+  editTool,
+  bashTool,
+  grepTool,
+  globTool,
+  diffTool,
+  patchTool,
+  jsonTool,
+  searchTool
+];
 var builtinTools = [
   readTool,
   writeTool,
@@ -8930,6 +9182,6 @@ var builtinToolsPack = {
   tools: builtinTools
 };
 
-export { CircuitBreaker, CircuitOpenError, IndexCircuitBreaker, IndexTimeoutError, _resetProcessRegistry, auditTool, bashTool, batchToolUseTool, builtinTools, builtinToolsPack, cancelPendingReindexes, codebaseIndexStats, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, createModeTool, diffTool, documentTool, editTool, enqueueReindex, execTool, fetchTool, forgetTool, formatTool, getIndexState, getProcessRegistry, gitTool, globTool, grepTool, indexCircuitBreaker, installTool, isIndexReady, isIndexableFile, isIndexing, jsonTool, lintTool, logsTool, onIndexStateChange, outdatedTool, patchTool, planTool, readTool, relatedMemoryTool, rememberTool, replaceTool, resetIndexCircuitBreaker, runStartupIndex, scaffoldTool, searchCodebaseIndex, searchMemoryTool, searchTool, shutdownCodebaseIndexHost, testTool, todoTool, toolHelpTool, toolSearchTool, toolUseTool, treeTool, typecheckTool, writeTool };
+export { CircuitBreaker, CircuitOpenError, IndexCircuitBreaker, IndexTimeoutError, OPTIONAL_TOOLS, TIER1_TOOLS, _resetProcessRegistry, auditTool, bashTool, batchToolUseTool, builtinTools, builtinToolsPack, cancelPendingReindexes, codebaseIndexStats, codebaseIndexTool, codebaseSearchTool, codebaseStatsTool, createModeTool, diffTool, documentTool, editTool, enqueueReindex, execTool, fetchTool, forgetTool, formatTool, getIndexState, getProcessRegistry, gitTool, globTool, grepTool, indexCircuitBreaker, installTool, isIndexReady, isIndexableFile, isIndexing, jsonTool, lintTool, logsTool, onIndexStateChange, outdatedTool, patchTool, planTool, readTool, relatedMemoryTool, rememberTool, replaceTool, resetIndexCircuitBreaker, runStartupIndex, scaffoldTool, searchCodebaseIndex, searchMemoryTool, searchTool, shutdownCodebaseIndexHost, testTool, todoTool, toolHelpTool, toolSearchTool, toolUseTool, treeTool, typecheckTool, writeTool };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map