@wrongstack/tools 0.283.1 → 0.284.0

package/dist/builtin.js

@@ -1,12 +1,13 @@
 import { spawn, execFileSync } from 'node:child_process';
 import * as Core from '@wrongstack/core';
-import { buildChildEnv, getDesignKitLoader, isDesignStack, loadActiveKit, applyTokenOverrides, setActiveKit, recordKitChoice, recordOverrides, setDesignOverrides, materializeTokens, runDesignVerify, ToolValidationError, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, ToolError, FetchError, isPrivateIPv4, isPrivateIPv6, assessCommitSafety, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, deepMerge, addLinkToTask, addNoteToTask, updateCheckOnTask, addCheckToTask, updateGoalMetricOnTask, addGoalMetricToTask, addDependency, getKanbanQueueHealth, listKanbanEvents, recoverStaleTaskAssignments, heartbeatTaskAssignment, updateTaskAssignment, assignTask, releaseTaskClaim, claimReadyTask, getTaskChain, setTaskChain, removeTask, moveTask, updateTask, getTask, transferTaskToBoard, copyTaskToBoard, mergeTasks, splitTask, addTask, removeColumn, updateColumn, addColumn, getKanbanOrchestrationSnapshot, listReadyTasks, searchKanban, deserializeTaskGraph, syncBoardFromTaskGraph, exportBoardToTaskGraph, serializeTaskGraph, exportBoardAsMarkdown, generateBoardFromDescription, createBoard, parseLinesIntoTasks, getBoard, removeBoard, duplicateBoard, updateBoard, listBoards, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, FsError, toErrorMessage as toErrorMessage$2, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
+import { buildChildEnv, getDesignKitLoader, isDesignStack, loadActiveKit, applyTokenOverrides, setActiveKit, recordKitChoice, recordOverrides, setDesignOverrides, materializeTokens, runDesignVerify, ToolValidationError, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, ToolError, FetchError, isPrivateIPv4, isPrivateIPv6, assessCommitSafety, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, deepMerge, deserializeTaskGraph, serializeTaskGraph, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, FsError, toErrorMessage as toErrorMessage$2, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
 import * as fs from 'node:fs';
 import { statSync, mkdirSync, createWriteStream } from 'node:fs';
 import * as fs2 from 'node:fs/promises';
-import * as path3 from 'node:path';
+import * as path12 from 'node:path';
 import { resolve, sep, dirname, join } from 'node:path';
 import * as os2 from 'node:os';
+import { randomUUID, createHash } from 'node:crypto';
 import { toErrorMessage as toErrorMessage$3 } from '@wrongstack/core/utils';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
@@ -17,14 +18,14 @@ import * as dns from 'node:dns/promises';
 import * as net from 'node:net';
 import { Agent, fetch } from 'undici';
 import TurndownService from 'turndown';
-import { randomUUID } from 'node:crypto';
+import { addLinkToTask, addNoteToTask, updateCheckOnTask, addCheckToTask, updateGoalMetricOnTask, addGoalMetricToTask, addDependency, getKanbanQueueHealth, listKanbanEvents, recoverStaleTaskAssignments, heartbeatTaskAssignment, updateTaskAssignment, assignTask, releaseTaskClaim, claimReadyTask, getTaskChain, setTaskChain, removeTask, moveTask, updateTask, getTask, transferTaskToBoard, copyTaskToBoard, mergeTasks, splitTask, addTask, removeColumn, updateColumn, addColumn, getKanbanOrchestrationSnapshot, listReadyTasks, searchKanban, syncBoardFromTaskGraph, exportBoardToTaskGraph, exportBoardAsMarkdown, generateBoardFromDescription, createBoard, parseLinesIntoTasks, getBoard, removeBoard, duplicateBoard, updateBoard, listBoards } from '@wrongstack/kanban';
 
 // src/_spawn-stream.ts
 var SPOOL_RETENTION_MS = 7 * 24 * 60 * 60 * 1e3;
 var SPOOL_WRITE_HWM_BYTES = 4 * 1024 * 1024;
 var sweepStarted = false;
 function toolOutputDir() {
-  return path3.join(wstackGlobalRoot(), "tool-output");
+  return path12.join(wstackGlobalRoot(), "tool-output");
 }
 function sweepOldSpoolFiles(dir) {
   if (sweepStarted) return;
@@ -34,7 +35,7 @@ function sweepOldSpoolFiles(dir) {
       const now = Date.now();
       for (const name of await fs2.readdir(dir)) {
         if (!name.endsWith(".log")) continue;
-        const p = path3.join(dir, name);
+        const p = path12.join(dir, name);
         try {
           const st = await fs2.stat(p);
           if (now - st.mtimeMs > SPOOL_RETENTION_MS) await fs2.unlink(p);
@@ -69,7 +70,7 @@ function createOutputSpool(opts) {
       sweepOldSpoolFiles(dir);
       const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
       const rand = Math.random().toString(36).slice(2, 6);
-      filePath = path3.join(dir, `${stamp}-${safeTool}-${rand}.log`);
+      filePath = path12.join(dir, `${stamp}-${safeTool}-${rand}.log`);
       stream = createWriteStream(filePath, { flags: "w", encoding: "utf8" });
       stream.on("error", () => {
         failed = true;
@@ -702,13 +703,13 @@ function getProcessRegistry() {
 }
 function resolveWin32Command(cmd) {
   if (process.platform !== "win32") return cmd;
-  if (cmd.includes("/") || cmd.includes("\\") || path3.extname(cmd.replace(/\//g, "\\"))) {
+  if (cmd.includes("/") || cmd.includes("\\") || path12.extname(cmd.replace(/\//g, "\\"))) {
     return cmd;
   }
   const pathext = (process.env["PATHEXT"] ?? ".COM;.EXE;.BAT;.CMD;.VBS;.JS;.WS;.MSC").toLowerCase().split(";");
-  const pathDirs = (process.env["PATH"] ?? "").split(path3.delimiter);
+  const pathDirs = (process.env["PATH"] ?? "").split(path12.delimiter);
   for (const dir of pathDirs) {
-    const base = path3.join(dir, cmd);
+    const base = path12.join(dir, cmd);
     for (const ext of pathext) {
       const full = `${base}${ext}`;
       try {
@@ -922,37 +923,40 @@ async function* spawnStream(opts) {
     }
   }
 }
+function sha256hex(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
 async function detectPackageManager(cwd) {
-  const { stat: stat11 } = await import('node:fs/promises');
+  const { stat: stat12 } = await import('node:fs/promises');
   try {
-    await stat11(`${cwd}/pnpm-lock.yaml`);
+    await stat12(`${cwd}/pnpm-lock.yaml`);
     return "pnpm";
   } catch {
   }
   try {
-    await stat11(`${cwd}/yarn.lock`);
+    await stat12(`${cwd}/yarn.lock`);
     return "yarn";
   } catch {
   }
   return "npm";
 }
 function resolvePath(input, ctx) {
-  return path3.isAbsolute(input) ? path3.normalize(input) : path3.resolve(ctx.workingDir ?? ctx.cwd, input);
+  return path12.isAbsolute(input) ? path12.normalize(input) : path12.resolve(ctx.workingDir ?? ctx.cwd, input);
 }
 function allowedRoots(ctx) {
-  return [path3.resolve(ctx.projectRoot), path3.resolve(Core.wstackGlobalRoot())];
+  return [path12.resolve(ctx.projectRoot), path12.resolve(Core.wstackGlobalRoot())];
 }
 function isInsideAny(target, roots) {
   return roots.some((root) => {
-    const rel = path3.relative(root, target);
-    return rel === "" || !rel.startsWith("..") && !path3.isAbsolute(rel);
+    const rel = path12.relative(root, target);
+    return rel === "" || !rel.startsWith("..") && !path12.isAbsolute(rel);
   });
 }
 function ensureInsideRoot(absPath, ctx) {
-  const target = path3.resolve(absPath);
+  const target = path12.resolve(absPath);
   if (ctx.allowOutsideProjectRoot) return target;
   if (isInsideAny(target, allowedRoots(ctx))) return target;
-  throw new Error(`Path "${absPath}" is outside project root "${path3.resolve(ctx.projectRoot)}"`);
+  throw new Error(`Path "${absPath}" is outside project root "${path12.resolve(ctx.projectRoot)}"`);
 }
 function safeResolve(input, ctx) {
   return ensureInsideRoot(resolvePath(input, ctx), ctx);
@@ -960,7 +964,7 @@ function safeResolve(input, ctx) {
 async function assertRealInsideRoot(absPath, ctx) {
   if (ctx.allowOutsideProjectRoot) return;
   const realRoots = await Promise.all(
-    allowedRoots(ctx).map((r) => fs2.realpath(r).catch(() => path3.resolve(r)))
+    allowedRoots(ctx).map((r) => fs2.realpath(r).catch(() => path12.resolve(r)))
   );
   let probe = absPath;
   for (; ; ) {
@@ -969,7 +973,7 @@ async function assertRealInsideRoot(absPath, ctx) {
       real = await fs2.realpath(probe);
     } catch (err) {
       if (err.code === "ENOENT") {
-        const parent = path3.dirname(probe);
+        const parent = path12.dirname(probe);
         if (parent === probe) return;
         probe = parent;
         continue;
@@ -1282,15 +1286,15 @@ var PersistentProcessRegistry = class {
   constructor(baseRegistry) {
     this.instanceId = generateInstanceId();
     const homeDir = os2.homedir();
-    this.registryPath = path3.join(homeDir, REGISTRY_FILE);
-    this.lockPath = path3.join(homeDir, LOCKFILE);
+    this.registryPath = path12.join(homeDir, REGISTRY_FILE);
+    this.lockPath = path12.join(homeDir, LOCKFILE);
     this.baseRegistry = baseRegistry ?? getProcessRegistry();
     this.ensureDirectory().catch((err) => {
       emitStructuredLog("warn", "process_registry.dir_create_failed", "PersistentProcessRegistry: failed to create .wrongstack directory", err);
     });
   }
   async ensureDirectory() {
-    const dir = path3.dirname(this.registryPath);
+    const dir = path12.dirname(this.registryPath);
     try {
       await fs2.mkdir(dir, { recursive: true });
     } catch (err) {
@@ -1870,6 +1874,10 @@ var bashTool = {
   category: "Shell",
   description: "Execute an arbitrary command in the user's default shell (bash/zsh/pwsh/cmd). stdout and stderr are merged into one stream. This is the most powerful and dangerous tool \u2014 it gives the model full access to the developer's machine. Prefer specialized tools whenever possible.",
   usageHint: "SECURITY WARNING: This tool runs with the full privileges of the current user.\n\nBest practices for the model:\n- Strongly prefer `exec` for known safe commands (node, npm, pnpm, tsc, git, etc.).\n- Use bash only when you genuinely need shell features (pipes, redirection, complex one-liners).\n- Prefer single focused commands over huge `&&` chains.\n- Use `background: true` only for long-running processes (dev servers, watchers).\n- The working directory is the project root.\n- Output may be truncated in the middle for very large results.",
+  selection: {
+    doNotUseWhen: "the command is allowlisted and does not require pipes, redirection, or shell expansion.",
+    useInstead: ["exec"]
+  },
   permission: "confirm",
   mutating: true,
   riskTier: "destructive",
@@ -2731,7 +2739,7 @@ var IndexStore = class {
     this.indexDir = resolveIndexDir(projectRoot, opts.indexDir);
     fs.mkdirSync(this.indexDir, { recursive: true });
     const Database = loadDatabaseSync();
-    this.db = new Database(path3.join(this.indexDir, DB_FILE));
+    this.db = new Database(path12.join(this.indexDir, DB_FILE));
     try {
       this.db.exec("PRAGMA journal_mode = WAL");
       this.db.exec("PRAGMA busy_timeout = 5000");
@@ -3310,7 +3318,7 @@ var IndexStore = class {
     }));
   }
   sizeBytes() {
-    const dbPath = path3.join(this.indexDir, DB_FILE);
+    const dbPath = path12.join(this.indexDir, DB_FILE);
     try {
       return fs.statSync(dbPath).size;
     } catch {
@@ -3809,9 +3817,9 @@ func formatType(t ast.Expr) string {
 }
 `;
 async function syncGoParse(filePath, content, lang) {
-  const tmpDir = await fs2.mkdtemp(path3.join(os2.tmpdir(), "ws-go-parse-"));
+  const tmpDir = await fs2.mkdtemp(path12.join(os2.tmpdir(), "ws-go-parse-"));
   try {
-    const scriptPath = path3.join(tmpDir, "parse.go");
+    const scriptPath = path12.join(tmpDir, "parse.go");
     await fs2.writeFile(scriptPath, GO_PARSE_SCRIPT, "utf8");
     const proc = spawn("go", ["run", scriptPath], {
       stdio: ["pipe", "pipe", "pipe"],
@@ -4073,9 +4081,9 @@ var _cachedScriptPath = null;
 async function syncPyParse(filePath, content, lang) {
   try {
     if (!_cachedScriptPath) {
-      const tmpDir = path3.join(os2.tmpdir(), "ws-py-parse");
+      const tmpDir = path12.join(os2.tmpdir(), "ws-py-parse");
       await fs2.mkdir(tmpDir, { recursive: true });
-      _cachedScriptPath = path3.join(tmpDir, "parse.py");
+      _cachedScriptPath = path12.join(tmpDir, "parse.py");
       await fs2.writeFile(_cachedScriptPath, PY_PARSE_SCRIPT, "utf8");
     }
     const proc = spawn("python", [_cachedScriptPath, filePath], {
@@ -4133,7 +4141,7 @@ async function parseSymbols4(opts) {
 function checkNativeParser() {
   try {
     execFileSync("rustc", ["--version"], { stdio: "pipe", windowsHide: true });
-    const toolsDir = path3.join(process.cwd(), "tools");
+    const toolsDir = path12.join(process.cwd(), "tools");
     try {
       execFileSync(
         "cargo",
@@ -4143,7 +4151,7 @@ function checkNativeParser() {
           "--format-version",
           "1",
           "--manifest-path",
-          path3.join(toolsDir, "Cargo.toml")
+          path12.join(toolsDir, "Cargo.toml")
         ],
         { stdio: "pipe", windowsHide: true }
       );
@@ -4157,13 +4165,13 @@ function checkNativeParser() {
 }
 async function tryNativeParse(file, content) {
   try {
-    const toolsDir = path3.join(process.cwd(), "tools");
-    const crateDir = path3.join(toolsDir, "syn-parser");
-    const tmpFile = path3.join(crateDir, "src", "input.rs");
+    const toolsDir = path12.join(process.cwd(), "tools");
+    const crateDir = path12.join(toolsDir, "syn-parser");
+    const tmpFile = path12.join(crateDir, "src", "input.rs");
     await fs2.writeFile(tmpFile, content, "utf8");
     const proc = spawn(
       "cargo",
-      ["run", "--manifest-path", path3.join(toolsDir, "Cargo.toml")],
+      ["run", "--manifest-path", path12.join(toolsDir, "Cargo.toml")],
       {
         cwd: process.cwd(),
         stdio: ["pipe", "pipe", "pipe"],
@@ -4213,16 +4221,16 @@ function regexParse(opts) {
   const { file, content, lang } = opts;
   const symbols = [];
   const lines = content.split("\n");
-  const lineOffsets = [0];
+  const lineOffsets2 = [0];
   for (let i = 0; i < lines.length; i++) {
-    lineOffsets.push((lineOffsets[i] ?? 0) + (lines[i]?.length ?? 0) + 1);
+    lineOffsets2.push((lineOffsets2[i] ?? 0) + (lines[i]?.length ?? 0) + 1);
   }
   function lineFromOffset(offset) {
     let lo = 0;
-    let hi = lineOffsets.length - 1;
+    let hi = lineOffsets2.length - 1;
     while (lo < hi) {
       const mid = lo + hi + 1 >>> 1;
-      if (expectDefined(lineOffsets[mid]) <= offset) lo = mid;
+      if (expectDefined(lineOffsets2[mid]) <= offset) lo = mid;
       else hi = mid - 1;
     }
     return lo + 1;
@@ -4237,7 +4245,7 @@ function regexParse(opts) {
       const name = expectDefined(match[1]);
       const offset = match.index ?? 0;
       const line = lineFromOffset(offset);
-      const col = offset - (lineOffsets[line - 1] ?? 0);
+      const col = offset - (lineOffsets2[line - 1] ?? 0);
       const lineIdx = line - 1;
       const signature = extractDeclaration(lineIdx);
       symbols.push({
@@ -4275,22 +4283,22 @@ function parseSymbols5(opts) {
 function regexParse2(opts) {
   const { file, content, lang } = opts;
   const symbols = [];
-  const basename2 = path3.basename(file).toLowerCase();
-  const isPackageJson = basename2 === "package.json";
-  const isTsconfig = basename2 === "tsconfig.json" || basename2 === "tsconfig.build.json";
+  const basename4 = path12.basename(file).toLowerCase();
+  const isPackageJson = basename4 === "package.json";
+  const isTsconfig = basename4 === "tsconfig.json" || basename4 === "tsconfig.build.json";
   const isJsonSchema = content.includes("$schema") || content.includes("$id") || content.includes("$ref");
   const isOpenApi = content.includes("openapi") || content.includes("swagger");
   const lines = content.split("\n");
-  const lineOffsets = [0];
+  const lineOffsets2 = [0];
   for (let i = 0; i < lines.length; i++) {
-    lineOffsets.push((lineOffsets[i] ?? 0) + (lines[i]?.length ?? 0) + 1);
+    lineOffsets2.push((lineOffsets2[i] ?? 0) + (lines[i]?.length ?? 0) + 1);
   }
   function lineFromOffset(offset) {
     let lo = 0;
-    let hi = lineOffsets.length - 1;
+    let hi = lineOffsets2.length - 1;
     while (lo < hi) {
       const mid = lo + hi + 1 >>> 1;
-      if (expectDefined(lineOffsets[mid]) <= offset) lo = mid;
+      if (expectDefined(lineOffsets2[mid]) <= offset) lo = mid;
       else hi = mid - 1;
     }
     return lo + 1;
@@ -4301,11 +4309,11 @@ function regexParse2(opts) {
     const line = lineFromOffset(offset);
     symbols.push(
       makeSymbol({
-        name: path3.basename(file),
+        name: path12.basename(file),
         kind: "object",
         line,
         col: 0,
-        signature: `"${path3.basename(file)}" = { ... }`,
+        signature: `"${path12.basename(file)}" = { ... }`,
         file,
         lang
       })
@@ -4316,7 +4324,7 @@ function regexParse2(opts) {
     const key = expectDefined(match[1]);
     const offset = match.index ?? 0;
     const line = lineFromOffset(offset);
-    const col = offset - (lineOffsets[line - 1] ?? 0);
+    const col = offset - (lineOffsets2[line - 1] ?? 0);
     let kind = "property";
     let signature = `"${key}": ..."`;
     if (isPackageJson) {
@@ -4351,10 +4359,10 @@ function regexParse2(opts) {
       })
     );
     if (isPackageJson && key === "scripts") {
-      extractPackageScripts(content, symbols, file, lang, lineOffsets, lineFromOffset);
+      extractPackageScripts(content, symbols, file, lang, lineOffsets2, lineFromOffset);
     }
     if (isTsconfig && key === "compilerOptions") {
-      extractCompilerOptions(content, symbols, file, lang, lineOffsets, line, lineFromOffset);
+      extractCompilerOptions(content, symbols, file, lang, lineOffsets2, line, lineFromOffset);
     }
   }
   const defsRegex = /"\$defs"\s*:|"\$defs"\s*:/g;
@@ -4367,7 +4375,7 @@ function regexParse2(opts) {
         name: "$defs",
         kind: "property",
         line,
-        col: offset - (lineOffsets[line - 1] ?? 0),
+        col: offset - (lineOffsets2[line - 1] ?? 0),
         signature: '"$defs": { ... }',
         file,
         lang
@@ -4391,7 +4399,7 @@ function regexParse2(opts) {
           name: key,
           kind: "property",
           line,
-          col: offset - (lineOffsets[line - 1] ?? 0),
+          col: offset - (lineOffsets2[line - 1] ?? 0),
           signature: `"${key}": { ... }`,
           file,
           lang
@@ -4401,7 +4409,7 @@ function regexParse2(opts) {
   }
   return { file, lang, symbols, mtimeMs: Date.now() };
 }
-function extractPackageScripts(content, symbols, file, lang, lineOffsets, lineFromOffset) {
+function extractPackageScripts(content, symbols, file, lang, lineOffsets2, lineFromOffset) {
   const scriptsBlockRegex = /"scripts"\s*:\s*\{([^}]+)\}/g;
   for (let match = scriptsBlockRegex.exec(content); match !== null; match = scriptsBlockRegex.exec(content)) {
     const blockContent = expectDefined(match[0]);
@@ -4416,7 +4424,7 @@ function extractPackageScripts(content, symbols, file, lang, lineOffsets, lineFr
           name: key,
           kind: "function",
           line,
-          col: keyOffset - (lineOffsets[line - 1] ?? 0),
+          col: keyOffset - (lineOffsets2[line - 1] ?? 0),
           signature: `"${key}": "..."`,
           file,
           lang
@@ -4425,7 +4433,7 @@ function extractPackageScripts(content, symbols, file, lang, lineOffsets, lineFr
     }
   }
 }
-function extractCompilerOptions(content, symbols, file, lang, lineOffsets, parentLine, lineFromOffset) {
+function extractCompilerOptions(content, symbols, file, lang, lineOffsets2, parentLine, lineFromOffset) {
   const optsBlockRegex = /"compilerOptions"\s*:\s*\{([^}]+)\}/g;
   for (let match = optsBlockRegex.exec(content); match !== null; match = optsBlockRegex.exec(content)) {
     const blockContent = expectDefined(match[0]);
@@ -4441,7 +4449,7 @@ function extractCompilerOptions(content, symbols, file, lang, lineOffsets, paren
           name: key,
           kind: "property",
           line,
-          col: keyOffset - (lineOffsets[line - 1] ?? 0),
+          col: keyOffset - (lineOffsets2[line - 1] ?? 0),
           signature: `"${key}": ...`,
           file,
           lang
@@ -4477,16 +4485,16 @@ function regexParse3(opts) {
   const { file, content, lang } = opts;
   const symbols = [];
   const lines = content.split("\n");
-  const lineOffsets = [0];
+  const lineOffsets2 = [0];
   for (let i = 0; i < lines.length; i++) {
-    lineOffsets.push((lineOffsets[i] ?? 0) + (lines[i]?.length ?? 0) + 1);
+    lineOffsets2.push((lineOffsets2[i] ?? 0) + (lines[i]?.length ?? 0) + 1);
   }
   function lineFromOffset(offset) {
     let lo = 0;
-    let hi = lineOffsets.length - 1;
+    let hi = lineOffsets2.length - 1;
     while (lo < hi) {
       const mid = lo + hi + 1 >>> 1;
-      if (expectDefined(lineOffsets[mid]) <= offset) lo = mid;
+      if (expectDefined(lineOffsets2[mid]) <= offset) lo = mid;
       else hi = mid - 1;
     }
     return lo + 1;
@@ -4496,7 +4504,7 @@ function regexParse3(opts) {
     const name = expectDefined(match[1]);
     const offset = match.index ?? 0;
     const line = lineFromOffset(offset);
-    const col = offset - (lineOffsets[line - 1] ?? 0);
+    const col = offset - (lineOffsets2[line - 1] ?? 0);
     symbols.push(
       makeSymbol2({
         name,
@@ -4514,7 +4522,7 @@ function regexParse3(opts) {
     const name = expectDefined(match[1]);
     const offset = match.index ?? 0;
     const line = lineFromOffset(offset);
-    const col = offset - (lineOffsets[line - 1] ?? 0);
+    const col = offset - (lineOffsets2[line - 1] ?? 0);
     symbols.push(
       makeSymbol2({
         name,
@@ -4534,7 +4542,7 @@ function regexParse3(opts) {
     if (!key) continue;
     const offset = match.index ?? 0;
     const line = lineFromOffset(offset);
-    const col = offset - (lineOffsets[line - 1] ?? 0);
+    const col = offset - (lineOffsets2[line - 1] ?? 0);
     const lineContent = lines[line - 1] ?? "";
     if (/^[|&>]/.test(lineContent.trim())) continue;
     if (key === "---" || key === "...") continue;
@@ -4549,7 +4557,7 @@ function regexParse3(opts) {
     const key = expectDefined(match[2]);
     const offset = match.index ?? 0;
     const line = lineFromOffset(offset);
-    const col = offset - (lineOffsets[line - 1] ?? 0);
+    const col = offset - (lineOffsets2[line - 1] ?? 0);
     const value = extractValue(content, offset + match[0]?.length);
     const kind = isScalar(value) ? "literal" : "property";
     symbols.push(
@@ -4569,7 +4577,7 @@ function regexParse3(opts) {
     const key = expectDefined(match[2]);
     const offset = match.index ?? 0;
     const line = lineFromOffset(offset);
-    const col = offset - (lineOffsets[line - 1] ?? 0);
+    const col = offset - (lineOffsets2[line - 1] ?? 0);
     symbols.push(
       makeSymbol2({
         name: key,
@@ -4655,7 +4663,7 @@ function compileGitignore(lines) {
 async function loadGitignoreMatcher(projectRoot) {
   let lines = [];
   try {
-    const raw = await fs2.readFile(path3.join(projectRoot, ".gitignore"), "utf8");
+    const raw = await fs2.readFile(path12.join(projectRoot, ".gitignore"), "utf8");
     lines = raw.split("\n");
   } catch {
   }
@@ -4720,14 +4728,14 @@ async function findSourceFiles(projectRoot, ignore, isGitIgnored, signal) {
     dirCount++;
     for (const e of entries) {
       if (ignoreSet.has(e.name)) continue;
-      const full = path3.join(dir, e.name);
-      const rel = path3.relative(projectRoot, full).replace(/\\/g, "/");
+      const full = path12.join(dir, e.name);
+      const rel = path12.relative(projectRoot, full).replace(/\\/g, "/");
       if (e.isDirectory()) {
         if (isGitIgnored(rel, true)) continue;
         await walk(full);
       } else if (e.isFile()) {
         if (isGitIgnored(rel, false)) continue;
-        const ext = path3.extname(e.name);
+        const ext = path12.extname(e.name);
         for (const { ext: extName, pat } of globs) {
           if (ext === extName && (pat.test(rel) || pat.test(e.name))) {
             results.push(full);
@@ -4783,7 +4791,7 @@ async function runIndexerWithStore(store, opts) {
   let files;
   let discoveredFiles = null;
   if (opts.files && opts.files.length > 0) {
-    files = opts.files.map((f) => path3.resolve(projectRoot, f)).filter((f) => !isGitIgnored(path3.relative(projectRoot, f).replace(/\\/g, "/"), false));
+    files = opts.files.map((f) => path12.resolve(projectRoot, f)).filter((f) => !isGitIgnored(path12.relative(projectRoot, f).replace(/\\/g, "/"), false));
   } else {
     files = await findSourceFiles(projectRoot, ignore, isGitIgnored, signal);
     discoveredFiles = new Set(files);
@@ -4811,34 +4819,34 @@ async function runIndexerWithStore(store, opts) {
     const statOpts = signal ? { signal } : {};
     const statReadParse = await Promise.allSettled(
       batchFiles.map(async (file) => {
-        let stat11;
+        let stat12;
         try {
-          stat11 = await fs2.stat(file, statOpts);
+          stat12 = await fs2.stat(file, statOpts);
         } catch (e) {
           if (isAbortError(e)) throw e;
           return { file, stat: null, lang: "", parsed: null, error: `stat error: ${e instanceof Error ? e.message : String(e)}` };
         }
-        if (!stat11.isFile()) return { file, stat: stat11, lang: "", parsed: null };
+        if (!stat12.isFile()) return { file, stat: stat12, lang: "", parsed: null };
         const lang = detectLang(file);
-        if (!lang) return { file, stat: stat11, lang: "", parsed: null };
+        if (!lang) return { file, stat: stat12, lang: "", parsed: null };
         const meta = existingMeta.get(file);
-        if (!force && meta && meta.mtimeMs === Math.floor(stat11.mtimeMs)) {
-          return { file, stat: stat11, lang, parsed: null, skippedMeta: meta };
+        if (!force && meta && meta.mtimeMs === Math.floor(stat12.mtimeMs)) {
+          return { file, stat: stat12, lang, parsed: null, skippedMeta: meta };
         }
         let content;
         try {
           content = await fs2.readFile(file, { encoding: "utf8", signal });
         } catch (e) {
           if (isAbortError(e)) throw e;
-          return { file, stat: stat11, lang, parsed: null, error: `read error: ${e instanceof Error ? e.message : String(e)}` };
+          return { file, stat: stat12, lang, parsed: null, error: `read error: ${e instanceof Error ? e.message : String(e)}` };
         }
         let parsed;
         try {
           parsed = await parseFile(file, content, lang);
         } catch (e) {
-          return { file, stat: stat11, lang, parsed: null, error: `parse error: ${e instanceof Error ? e.message : String(e)}` };
+          return { file, stat: stat12, lang, parsed: null, error: `parse error: ${e instanceof Error ? e.message : String(e)}` };
         }
-        return { file, stat: stat11, lang, parsed, content };
+        return { file, stat: stat12, lang, parsed, content };
       })
     );
     const batchEntries = [];
@@ -4858,7 +4866,7 @@ async function runIndexerWithStore(store, opts) {
         if (result.error.includes("error:")) errors.push(result.error);
         continue;
       }
-      const { stat: stat11, lang, parsed } = result;
+      const { stat: stat12, lang, parsed } = result;
       if (result.skippedMeta) {
         langStats[lang] = (langStats[lang] ?? 0) + result.skippedMeta.symbolCount;
         symbolsIndexed += result.skippedMeta.symbolCount;
@@ -4870,7 +4878,7 @@ async function runIndexerWithStore(store, opts) {
           store.upsertFile({
             file,
             lang,
-            mtimeMs: Math.floor(stat11.mtimeMs),
+            mtimeMs: Math.floor(stat12.mtimeMs),
             symbolCount: 0,
             lastIndexed: Date.now()
           });
@@ -4882,7 +4890,7 @@ async function runIndexerWithStore(store, opts) {
         store.upsertFile({
           file,
           lang,
-          mtimeMs: Math.floor(stat11.mtimeMs),
+          mtimeMs: Math.floor(stat12.mtimeMs),
           symbolCount: 0,
           lastIndexed: Date.now()
         });
@@ -4898,7 +4906,7 @@ async function runIndexerWithStore(store, opts) {
         lang,
         symbols: parsed.symbols,
         refs,
-        mtimeMs: Math.floor(stat11.mtimeMs),
+        mtimeMs: Math.floor(stat12.mtimeMs),
         symbolCount: parsed.symbols.length
       });
       deleteForFiles.push(file);
@@ -5047,7 +5055,7 @@ function statsService(args) {
 }
 
 // src/codebase-index/background-indexer.ts
-var DEFAULT_FULL_INDEX_TIMEOUT_MS = 12e4;
+var DEFAULT_FULL_INDEX_TIMEOUT_MS = 24e4;
 var DEFAULT_QUERY_TIMEOUT_MS = 8e3;
 var _ready = false;
 var _indexing = false;
@@ -5504,6 +5512,25 @@ var codebaseStatsTool = {
     };
   }
 };
+async function resolveReal(p) {
+  const resolved = path12.resolve(p);
+  let probe = resolved;
+  const missing = [];
+  for (; ; ) {
+    try {
+      return path12.resolve(await fs2.realpath(probe), ...missing);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        const parent = path12.dirname(probe);
+        if (parent === probe) return resolved;
+        missing.unshift(path12.basename(probe));
+        probe = parent;
+        continue;
+      }
+      return resolved;
+    }
+  }
+}
 function normalizeOverrides(set) {
   const out = {};
   if (set && typeof set === "object") {
@@ -5661,10 +5688,12 @@ These win over kit tokens. Run \`design {action:"materialize"}\` to write them t
         kitId: active.kit,
         outPath: input.out
       });
-      const root = path3.resolve(ctx.projectRoot);
-      const abs = path3.resolve(path3.join(ctx.projectRoot, result.path));
-      const rel = path3.relative(root, abs);
-      if (rel.startsWith("..") || path3.isAbsolute(rel)) {
+      const root = await resolveReal(ctx.projectRoot);
+      const absResolved = path12.isAbsolute(result.path) ? path12.resolve(result.path) : path12.resolve(path12.join(ctx.projectRoot, result.path));
+      const absParent = await resolveReal(path12.dirname(absResolved));
+      const abs = path12.join(absParent, path12.basename(absResolved));
+      const rel = path12.relative(root, abs);
+      if (rel.startsWith("..") || path12.isAbsolute(rel)) {
         throw new Error(
           `design: materialize path "${result.path}" would escape the project root`
         );
@@ -5688,7 +5717,7 @@ ${result.content}
 \`\`\``
         };
       }
-      await fs2.mkdir(path3.dirname(abs), { recursive: true });
+      await fs2.mkdir(path12.dirname(abs), { recursive: true });
       await fs2.writeFile(abs, result.content);
       return {
         action,
@@ -5816,11 +5845,11 @@ function findGitDir(cwd) {
   let dir = cwd;
   for (let i = 0; i < 20; i++) {
     try {
-      const stat11 = statSync(path3.join(dir, ".git"));
-      if (stat11.isDirectory()) return dir;
+      const stat12 = statSync(path12.join(dir, ".git"));
+      if (stat12.isDirectory()) return dir;
     } catch {
     }
-    const parent = path3.dirname(dir);
+    const parent = path12.dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
@@ -5861,8 +5890,8 @@ async function fileDiff(input, ctx, _signal) {
   const results = [];
   for (const file of files) {
     const absPath = safeResolve(file, ctx);
-    const stat11 = await fs2.stat(absPath).catch(() => null);
-    if (!stat11?.isFile()) continue;
+    const stat12 = await fs2.stat(absPath).catch(() => null);
+    if (!stat12?.isFile()) continue;
     const content = await fs2.readFile(absPath, "utf8");
     const lines = content.split(/\r?\n/);
     results.push(formatWithLineNumbers(file, lines));
@@ -5959,8 +5988,8 @@ async function resolveFiles(filesInput, cwd) {
   for (const f of files) {
     const absPath = f.trim().startsWith("/") ? f.trim() : `${cwd}/${f.trim()}`;
     try {
-      const stat11 = await fs2.stat(absPath);
-      if (stat11.isFile()) resolved.push(absPath);
+      const stat12 = await fs2.stat(absPath);
+      if (stat12.isFile()) resolved.push(absPath);
     } catch {
     }
   }
@@ -6026,11 +6055,303 @@ function processFile(content, absPath, _style, _overwrite, target) {
   }
   return results;
 }
+
+// src/_edit-match.ts
+var TIER_LABEL = {
+  exact: "exact match",
+  "trailing-whitespace": "whitespace-normalized match (trailing whitespace ignored)",
+  "whitespace-normalized": "whitespace-normalized match (indentation ignored, replacement re-indented)",
+  fuzzy: "fuzzy match (block anchors exact, interior \u226590% similar)"
+};
+var TIER_CONFIDENCE = {
+  exact: "exact",
+  "trailing-whitespace": "high",
+  "whitespace-normalized": "medium",
+  fuzzy: "low"
+};
+var MIN_NORMALIZED_NEEDLE_CHARS = 16;
+var FUZZY_MIN_SIMILARITY = 0.9;
+var FUZZY_AMBIGUITY_MARGIN = 0.05;
+var FUZZY_MAX_INTERIOR_CHARS = 2e3;
+function findLadderMatches(fileLf, oldLf) {
+  const exact = [];
+  let idx = fileLf.indexOf(oldLf);
+  while (idx !== -1) {
+    exact.push({ start: idx, end: idx + oldLf.length, startLine: lineAt(fileLf, idx) });
+    idx = fileLf.indexOf(oldLf, idx + 1);
+  }
+  if (exact.length > 0) return { tier: "exact", matches: exact };
+  const fileLines = fileLf.split("\n");
+  const needleLines = oldLf.split("\n");
+  if (needleLines.length > fileLines.length) return void 0;
+  const offsets = lineOffsets(fileLines);
+  const trailing = windowScan(
+    fileLines,
+    needleLines,
+    offsets,
+    (a, b) => a.trimEnd() === b.trimEnd()
+  );
+  if (trailing.length > 0) return { tier: "trailing-whitespace", matches: trailing };
+  const normalizedLen = needleLines.reduce((n, l) => n + l.trim().length, 0);
+  if (normalizedLen < MIN_NORMALIZED_NEEDLE_CHARS) return void 0;
+  const normalized = windowScan(fileLines, needleLines, offsets, (a, b) => a.trim() === b.trim());
+  if (normalized.length > 0) return { tier: "whitespace-normalized", matches: normalized };
+  return fuzzyScan(fileLines, needleLines, offsets);
+}
+function lineAt(text, pos) {
+  let line = 1;
+  for (let i = 0; i < pos; i++) {
+    if (text.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+function lineOffsets(lines) {
+  const out = new Array(lines.length);
+  let pos = 0;
+  for (let i = 0; i < lines.length; i++) {
+    out[i] = pos;
+    pos += lines[i].length + 1;
+  }
+  return out;
+}
+function windowToMatch(fileLines, offsets, start, windowLen) {
+  const lastLine = start + windowLen - 1;
+  return {
+    start: offsets[start],
+    end: offsets[lastLine] + fileLines[lastLine].length,
+    startLine: start + 1
+  };
+}
+function windowScan(fileLines, needleLines, offsets, eq) {
+  const n = needleLines.length;
+  const out = [];
+  for (let i = 0; i + n <= fileLines.length; i++) {
+    let all = true;
+    for (let j = 0; j < n; j++) {
+      if (!eq(fileLines[i + j], needleLines[j])) {
+        all = false;
+        break;
+      }
+    }
+    if (all) {
+      out.push(windowToMatch(fileLines, offsets, i, n));
+      i += n - 1;
+    }
+  }
+  return out;
+}
+function fuzzyScan(fileLines, needleLines, offsets) {
+  const n = needleLines.length;
+  if (n < 3) return void 0;
+  const firstNeedle = needleLines[0].trim();
+  const lastNeedle = needleLines[n - 1].trim();
+  const needleInterior = needleLines.slice(1, -1).map((l) => l.trim()).join("\n");
+  if (needleInterior.length > FUZZY_MAX_INTERIOR_CHARS) return void 0;
+  const candidates = [];
+  for (let i = 0; i + n <= fileLines.length; i++) {
+    if (fileLines[i].trim() !== firstNeedle) continue;
+    if (fileLines[i + n - 1].trim() !== lastNeedle) continue;
+    const windowInterior = fileLines.slice(i + 1, i + n - 1).map((l) => l.trim()).join("\n");
+    if (windowInterior.length > FUZZY_MAX_INTERIOR_CHARS) continue;
+    const score = similarity(needleInterior, windowInterior);
+    if (score >= FUZZY_MIN_SIMILARITY) {
+      candidates.push({ match: windowToMatch(fileLines, offsets, i, n), score });
+    }
+  }
+  if (candidates.length === 0) return void 0;
+  candidates.sort((a, b) => b.score - a.score);
+  const best = candidates[0];
+  const runnerUp = candidates[1];
+  if (runnerUp && best.score - runnerUp.score < FUZZY_AMBIGUITY_MARGIN) {
+    return {
+      tier: "fuzzy",
+      matches: candidates.map((c) => c.match),
+      score: best.score,
+      ambiguous: true
+    };
+  }
+  return { tier: "fuzzy", matches: [best.match], score: best.score };
+}
+function similarity(a, b) {
+  if (a === b) return 1;
+  const max = Math.max(a.length, b.length);
+  if (max === 0) return 1;
+  if (Math.abs(a.length - b.length) / max > 1 - FUZZY_MIN_SIMILARITY + 0.05) {
+    return 1 - Math.abs(a.length - b.length) / max;
+  }
+  return 1 - levenshtein(a, b) / max;
+}
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array(b.length + 1);
+  let cur = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    cur[0] = i;
+    const ca = a.charCodeAt(i - 1);
+    for (let j = 1; j <= b.length; j++) {
+      const cost = ca === b.charCodeAt(j - 1) ? 0 : 1;
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + cost
+      );
+    }
+    [prev, cur] = [cur, prev];
+  }
+  return prev[b.length];
+}
+function firstLineIndent(text) {
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    return /^[ \t]*/.exec(line)[0];
+  }
+  return "";
+}
+function adjustIndent(newLf, fromIndent, toIndent) {
+  if (fromIndent === toIndent) return { text: newLf, adjusted: false };
+  const lines = newLf.split("\n");
+  if (toIndent.startsWith(fromIndent)) {
+    const extra = toIndent.slice(fromIndent.length);
+    return {
+      text: lines.map((l) => l.trim() === "" ? l : extra + l).join("\n"),
+      adjusted: true
+    };
+  }
+  if (fromIndent.startsWith(toIndent)) {
+    const remove = fromIndent.slice(toIndent.length);
+    return {
+      text: lines.map((l) => l.startsWith(remove) ? l.slice(remove.length) : l).join("\n"),
+      adjusted: true
+    };
+  }
+  return { text: newLf, adjusted: false };
+}
+function nearestMatchHint(fileLf, oldLf) {
+  const fileLines = fileLf.split("\n");
+  const needleLines = oldLf.split("\n");
+  if (needleLines.length > fileLines.length) return void 0;
+  const needleTrimmed = needleLines.map((l) => l.trim());
+  let bestScore = 0;
+  let bestStart = -1;
+  for (let i = 0; i + needleLines.length <= fileLines.length; i++) {
+    let sum = 0;
+    for (let j = 0; j < needleLines.length; j++) {
+      sum += prefixSimilarity(needleTrimmed[j], fileLines[i + j].trim());
+    }
+    const score = sum / needleLines.length;
+    if (score > bestScore) {
+      bestScore = score;
+      bestStart = i;
+    }
+  }
+  if (bestStart === -1 || bestScore < 0.5) return void 0;
+  const snippet = fileLines.slice(bestStart, bestStart + Math.min(3, needleLines.length)).map((l) => l.length > 120 ? `${l.slice(0, 120)}\u2026` : l).join("\n");
+  return { line: bestStart + 1, snippet };
+}
+function prefixSimilarity(a, b) {
+  if (a === b) return 1;
+  const max = Math.max(a.length, b.length);
+  if (max === 0) return 1;
+  let p = 0;
+  const lim = Math.min(a.length, b.length);
+  while (p < lim && a.charCodeAt(p) === b.charCodeAt(p)) p++;
+  return p / max;
+}
+var TS_LIKE = /* @__PURE__ */ new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+var MAX_CHECK_CHARS = 15e5;
+var MAX_ERRORS = 5;
+var tsLoad = null;
+function loadTypescript() {
+  tsLoad ??= import('typescript').then(
+    (m) => m.default ?? m,
+    () => null
+  );
+  return tsLoad;
+}
+async function checkSyntax(filePath, content, previousContent) {
+  const errors = await parseErrors(filePath, content);
+  if (errors === void 0) return void 0;
+  if (errors.length === 0) return { errors, preExisting: false };
+  let preExisting = false;
+  if (previousContent !== void 0) {
+    const prevErrors = await parseErrors(filePath, previousContent);
+    preExisting = prevErrors !== void 0 && prevErrors.length > 0;
+  }
+  return { errors, preExisting };
+}
+function isJsoncFile(filePath) {
+  const base = path12.basename(filePath).toLowerCase();
+  if (base.endsWith(".jsonc")) return true;
+  if (/^(tsconfig|jsconfig)([.-].*)?\.json$/.test(base)) return true;
+  const dir = path12.basename(path12.dirname(filePath)).toLowerCase();
+  return dir === ".vscode";
+}
+async function parseErrors(filePath, content) {
+  if (content.length > MAX_CHECK_CHARS) return void 0;
+  const ext = path12.extname(filePath).toLowerCase();
+  if (ext === ".json" || ext === ".jsonc") {
+    try {
+      JSON.parse(content);
+      return [];
+    } catch (err) {
+      if (isJsoncFile(filePath)) {
+        const ts3 = await loadTypescript();
+        if (ts3) {
+          const jsonc = ts3.parseConfigFileTextToJson(filePath, content);
+          if (!jsonc.error) return [];
+          return [formatDiag(ts3, jsonc.error, content)];
+        }
+      }
+      return [`JSON parse error: ${err.message}`];
+    }
+  }
+  if (!TS_LIKE.has(ext)) return void 0;
+  const ts2 = await loadTypescript();
+  if (!ts2) return void 0;
+  const scriptKind = ext === ".tsx" ? ts2.ScriptKind.TSX : ext === ".ts" || ext === ".mts" || ext === ".cts" ? ts2.ScriptKind.TS : (
+    // Plain JS may legitimately contain JSX; the JSX grammar is a
+    // superset for untyped code, so parsing .js/.jsx as JSX avoids
+    // false positives on React files.
+    ts2.ScriptKind.JSX
+  );
+  const sourceFile = ts2.createSourceFile(
+    path12.basename(filePath),
+    content,
+    ts2.ScriptTarget.Latest,
+    /* setParentNodes */
+    false,
+    scriptKind
+  );
+  const diags = sourceFile.parseDiagnostics ?? [];
+  return diags.slice(0, MAX_ERRORS).map((d) => formatDiag(ts2, d, content, sourceFile));
+}
+function formatDiag(ts2, diag, content, sourceFile) {
+  const message = ts2.flattenDiagnosticMessageText(diag.messageText, " ");
+  if (diag.start === void 0) return message;
+  let line;
+  if (sourceFile) {
+    line = sourceFile.getLineAndCharacterOfPosition(diag.start).line + 1;
+  } else {
+    line = 1;
+    for (let i = 0; i < diag.start && i < content.length; i++) {
+      if (content.charCodeAt(i) === 10) line++;
+    }
+  }
+  return `line ${line}: ${message}`;
+}
+
+// src/edit.ts
 var editTool = {
   name: "edit",
   category: "Filesystem",
   description: "Perform a precise, surgical text replacement in a file. This is the preferred tool for modifying existing code. It works best after a prior `read`, but can auto-read the current file when the replacement is still unambiguous. Fails safely if the `old_string` appears more than once unless `replace_all` is set.",
-  usageHint: "RECOMMENDED WORKFLOW:\n1. Prefer calling `read` on the target file first when planning an edit.\n2. Use a sufficiently unique `old_string` (include surrounding lines/context if needed).\n3. If the string appears multiple times and you want to change all of them, set `replace_all: true`.\n4. `new_string` must be the exact replacement text.\n\nIf no prior read is recorded, the tool auto-reads the current file and only applies the edit after the same ambiguity checks pass.",
+  usageHint: "RECOMMENDED WORKFLOW:\n1. Prefer calling `read` on the target file first when planning an edit.\n2. Use a sufficiently unique `old_string` (include surrounding lines/context if needed).\n3. If the string appears multiple times and you want to change all of them, set `replace_all: true`.\n4. `new_string` must be the exact replacement text.\n\nIf no prior read is recorded, the tool auto-reads the current file and only applies the edit after the same ambiguity checks pass.\nIf `old_string` differs from the file only in whitespace (trailing spaces, indentation), a lower-confidence fallback match is applied and reported in `matched_by`/`note` \u2014 always verify the diff when this happens.\nAfter the edit, TS/JS/JSON files are syntax-checked; if `syntax_errors` is present in the output, fix those errors immediately with a follow-up edit.",
+  selection: {
+    doNotUseWhen: "creating a new file, replacing the whole file, or applying an existing unified diff.",
+    useInstead: ["write", "patch"]
+  },
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
@@ -6046,7 +6367,7 @@ var editTool = {
     },
     required: ["path", "old_string", "new_string"]
   },
-  async execute(input, ctx) {
+  async execute(input, ctx, opts) {
     if (!input?.path) {
       throw new ToolValidationError({ message: "edit: path is required", field: "path" });
     }
@@ -6069,7 +6390,7 @@ var editTool = {
       });
     }
     const absPath = await safeResolveReal(input.path, ctx);
-    const stat11 = await fs2.stat(absPath).catch((err) => {
+    const stat12 = await fs2.stat(absPath).catch((err) => {
       if (err.code === "ENOENT") {
         throw new ToolValidationError({
           message: `edit: file "${input.path}" does not exist. Use \`write\` instead.`,
@@ -6079,7 +6400,7 @@ var editTool = {
       }
       throw err;
     });
-    if (!stat11.isFile()) {
+    if (!stat12.isFile()) {
       throw new ToolValidationError({
         message: `edit: "${input.path}" is not a regular file`,
         field: "path"
@@ -6089,15 +6410,27 @@ var editTool = {
     const original = await fs2.readFile(absPath, "utf8");
     const updated = await fs2.stat(absPath);
     const mtimeTolerance = process.platform === "win32" ? 2e3 : 1;
-    const lastReadMtime = ctx.lastReadMtime(absPath);
-    if (lastReadMtime !== void 0 && updated.mtimeMs > lastReadMtime + mtimeTolerance) {
-      throw new ToolValidationError({
-        message: `edit: file "${input.path}" was modified externally. Re-read it first.`,
-        field: "path",
-        context: { reason: "external_modification" }
-      });
+    const originalHash = sha256hex(original);
+    const lastReadHash = ctx.lastReadHash?.(absPath);
+    if (lastReadHash !== void 0) {
+      if (lastReadHash !== originalHash) {
+        throw new ToolValidationError({
+          message: `edit: file "${input.path}" was modified externally. Re-read it first.`,
+          field: "path",
+          context: { reason: "external_modification" }
+        });
+      }
+    } else {
+      const lastReadMtime = ctx.lastReadMtime(absPath);
+      if (lastReadMtime !== void 0 && updated.mtimeMs > lastReadMtime + mtimeTolerance) {
+        throw new ToolValidationError({
+          message: `edit: file "${input.path}" was modified externally. Re-read it first.`,
+          field: "path",
+          context: { reason: "external_modification" }
+        });
+      }
     }
-    if (autoRead && updated.mtimeMs > stat11.mtimeMs + mtimeTolerance) {
+    if (autoRead && updated.mtimeMs > stat12.mtimeMs + mtimeTolerance) {
       throw new ToolValidationError({
         message: `edit: file "${input.path}" changed while being auto-read. Retry the edit.`,
         field: "path",
@@ -6110,42 +6443,78 @@ var editTool = {
     const oldLf = normalizeToLf(input.old_string);
     const newLf = normalizeToLf(input.new_string);
     if (oldLf === newLf) {
-      if (autoRead) ctx.recordRead(absPath, updated.mtimeMs);
+      if (autoRead) ctx.recordRead(absPath, updated.mtimeMs, "user", originalHash);
       return {
         path: absPath,
         replacements: 0,
         diff: "(no-op: old and new are identical)",
+        matched_by: "exact",
         note: autoReadNote
       };
     }
-    let count = 0;
-    let idx = fileLf.indexOf(oldLf);
-    const matches = [];
-    while (idx !== -1) {
-      matches.push(idx);
-      count++;
-      idx = fileLf.indexOf(oldLf, idx + 1);
-    }
-    if (count === 0) {
-      const hint = findSimilarity(fileLf, oldLf);
+    const ladder = findLadderMatches(fileLf, oldLf);
+    if (!ladder) {
+      const hint = nearestMatchHint(fileLf, oldLf);
       throw new ToolValidationError({
-        message: `edit: no match for old_string in "${input.path}".${hint ? ` Nearest match near line ${hint}.` : ""}`,
+        message: `edit: no match for old_string in "${input.path}".${hint ? ` Nearest match near line ${hint.line}:
+${hint.snippet}
+Compare this against your old_string and retry with the file's actual text.` : ""}`,
         field: "old_string"
       });
     }
+    const { tier, matches } = ladder;
+    const count = matches.length;
+    if (ladder.ambiguous) {
+      const lines = matches.map((m) => m.startLine);
+      throw new ToolValidationError({
+        message: `edit: old_string only matched fuzzily and ${count} candidate blocks scored too close to distinguish (lines: ${lines.join(", ")}) in "${input.path}". Re-read the file and use the exact text of the intended block.`,
+        field: "old_string",
+        context: { occurrences: count, matchTier: tier }
+      });
+    }
+    if (input.replace_all && tier !== "exact" && tier !== "trailing-whitespace") {
+      throw new ToolValidationError({
+        message: `edit: old_string only matched via ${TIER_LABEL[tier]} in "${input.path}", but replace_all requires an exact (or trailing-whitespace) match. Re-read the file and use its exact text.`,
+        field: "old_string",
+        context: { matchTier: tier }
+      });
+    }
     if (count > 1 && !input.replace_all) {
-      const lines = lineNumbersFor(fileLf, matches);
+      const lines = matches.map((m) => m.startLine);
       throw new ToolValidationError({
-        message: `edit: old_string matched ${count} times in "${input.path}" (lines: ${lines.join(", ")}). Add more context to make it unique, or set replace_all: true.`,
+        message: `edit: old_string matched ${count} times in "${input.path}" (lines: ${lines.join(", ")})${tier === "exact" ? "" : ` via ${TIER_LABEL[tier]}`}. Add more context to make it unique, or set replace_all: true.`,
         field: "old_string",
-        context: { occurrences: count }
+        context: { occurrences: count, matchTier: tier }
       });
     }
-    const newFileLf = input.replace_all ? fileLf.split(oldLf).join(newLf) : fileLf.replace(oldLf, newLf);
+    let newFileLf;
+    let tierNote;
+    if (tier === "exact") {
+      newFileLf = input.replace_all ? fileLf.split(oldLf).join(newLf) : fileLf.replace(oldLf, newLf);
+    } else {
+      let replacement = newLf;
+      let indentSuffix = "";
+      if (tier === "whitespace-normalized" || tier === "fuzzy") {
+        const first = matches[0];
+        const matchedText = fileLf.slice(first.start, first.end);
+        const adjusted = adjustIndent(newLf, firstLineIndent(oldLf), firstLineIndent(matchedText));
+        replacement = adjusted.text;
+        if (adjusted.adjusted) indentSuffix = "; replacement re-indented to match the file";
+      }
+      newFileLf = fileLf;
+      const applied = input.replace_all ? matches : matches.slice(0, 1);
+      for (let i = applied.length - 1; i >= 0; i--) {
+        const m = applied[i];
+        newFileLf = newFileLf.slice(0, m.start) + replacement + newFileLf.slice(m.end);
+      }
+      const scoreSuffix = ladder.score !== void 0 ? `, similarity ${(ladder.score * 100).toFixed(1)}%` : "";
+      tierNote = `old_string did not match exactly; applied via ${TIER_LABEL[tier]} at line ${matches[0].startLine} (confidence: ${TIER_CONFIDENCE[tier]}${scoreSuffix}${indentSuffix}). Review the diff to confirm the intended target was edited.`;
+    }
     const newFile = toStyle(newFileLf, style);
+    opts?.signal?.throwIfAborted();
     await atomicWrite(absPath, newFile, { mode: updated.mode & 511 });
     const written = await fs2.stat(absPath);
-    ctx.recordRead(absPath, written.mtimeMs, "write");
+    ctx.recordRead(absPath, written.mtimeMs, "write", sha256hex(newFile));
     ctx.session.recordFileChange({
       path: absPath,
       action: "modified",
@@ -6156,38 +6525,22 @@ var editTool = {
       fromFile: input.path,
       toFile: input.path
     });
+    const syntax = await checkSyntax(absPath, newFile, original).catch(() => void 0);
+    let syntaxNote;
+    if (syntax && syntax.errors.length > 0) {
+      syntaxNote = syntax.preExisting ? `Syntax check: the file still has parse errors (they pre-date this edit) \u2014 see syntax_errors.` : `Syntax check: this edit introduced ${syntax.errors.length} parse error(s) \u2014 fix them now, see syntax_errors.`;
+    }
+    const notes = [autoReadNote, tierNote, syntaxNote].filter(Boolean);
     return {
       path: absPath,
       replacements: input.replace_all ? count : 1,
       diff,
-      note: autoReadNote
+      matched_by: tier,
+      syntax_errors: syntax && syntax.errors.length > 0 ? syntax.errors : void 0,
+      note: notes.length > 0 ? notes.join("\n") : void 0
     };
   }
 };
-function lineNumbersFor(text, indices) {
-  const out = [];
-  let pos = 0;
-  let line = 1;
-  for (const target of indices) {
-    while (pos < target) {
-      if (text.charCodeAt(pos) === 10) line++;
-      pos++;
-    }
-    out.push(line);
-  }
-  return out;
-}
-function findSimilarity(haystack, needle) {
-  if (needle.length < 20) return void 0;
-  const probe = needle.slice(0, Math.min(40, needle.length));
-  const idx = haystack.indexOf(probe);
-  if (idx === -1) return void 0;
-  let line = 1;
-  for (let i = 0; i < idx; i++) {
-    if (haystack.charCodeAt(i) === 10) line++;
-  }
-  return line;
-}
 
 // src/_danger-detect.ts
 var argHas = (args, value) => args.includes(value);
@@ -6400,23 +6753,18 @@ var RULES = [
     },
     reason: "inline script evaluation (-c / -e / --eval)"
   },
-  // ----- pipe-to-shell (caution — well-known exfil pattern) -----
+  // ----- pipe-to-shell (destructive — download-and-run pattern) -----
   // The classic `curl https://... | sh` download-and-run vector. Detected by
-  // looking for a known fetcher followed by a shell sink. We use a simple
-  // substring scan; false positives are limited because both tokens must
-  // appear in the same argv.
+  // looking for a known fetcher piped into a shell or expression evaluator.
+  // A shell command passed through `bash -c` / `pwsh -Command` arrives as one
+  // argv string, so scan the reconstructed argv text rather than individual
+  // tokens only.
   {
     id: "pipe-to-shell",
-    level: "caution",
-    test: (_cmd, args) => {
-      const hasFetcher = args.some(
-        (a) => /^(curl|wget|fetch|httpie|http)$/i.test(a) || a.startsWith("curl") || a.startsWith("wget")
-      );
-      const hasShellSink = args.some(
-        (a) => a === "sh" || a === "bash" || a === "zsh" || a === "fish" || a === "pwsh" || a === "powershell" || a.endsWith("/sh") || a.endsWith("/bash") || a.endsWith("/zsh") || a.endsWith("/pwsh")
-      );
-      return hasFetcher && hasShellSink;
-    },
+    level: "destructive",
+    test: (cmd, args) => /\b(?:curl|wget|fetch|httpie|http|irm|iwr|Invoke-WebRequest|Invoke-RestMethod)\b[\s\S]{0,300}\|\s*(?:sudo\s+)?(?:sh|bash|zsh|fish|pwsh|powershell|iex|Invoke-Expression)\b/i.test(
+      [cmd, ...args].join(" ")
+    ),
     reason: "network fetch piped to a shell (download-and-run pattern)"
   },
   // ----- privilege escalation (caution) -----
@@ -7178,6 +7526,10 @@ var execTool = {
   category: "Shell",
   description: "Execute a **whitelisted, restricted set of commands** with strict argument validation. This is the **preferred and safer** alternative to the `bash` tool for running development tools (node, npm, pnpm, tsc, git, tests, linters, etc.). It prevents arbitrary command injection and limits what the model can do.",
   usageHint: "PREFERRED SHELL TOOL for most cases.\n\nUse this instead of `bash` whenever possible.\n- `command` must be in the allowlist. Defaults cover JS (node/npm/pnpm/yarn/bun/deno/tsc/vitest/eslint/biome), Go (`go build`/`go test`), Rust (cargo), Python (python/pip), Ruby (gem/bundle), JVM (java/mvn/gradle), .NET (dotnet), native (make/cmake), and git. Users can extend it via `tools.exec.allow` in config.\n- Arguments are passed as a clean array (no shell interpretation).\n- `cwd` is validated to stay inside the project.\n- If a command is not allowlisted, the error explains how to add it; for one-off arbitrary commands, fall back to `bash` (with strong justification).\nThis tool significantly reduces the risk compared to full shell access.",
+  selection: {
+    doNotUseWhen: "the operation requires pipes, redirection, shell expansion, or a non-allowlisted command.",
+    useInstead: ["bash"]
+  },
   permission: "confirm",
   mutating: true,
   riskTier: "standard",
@@ -7841,13 +8193,13 @@ var formatTool = {
   }
 };
 async function detectFixer(cwd) {
-  const { stat: stat11 } = await import('node:fs/promises');
+  const { stat: stat12 } = await import('node:fs/promises');
   try {
-    await stat11(`${cwd}/biome.json`);
+    await stat12(`${cwd}/biome.json`);
     return "biome";
   } catch {
     try {
-      await stat11(`${cwd}/.prettierrc`);
+      await stat12(`${cwd}/.prettierrc`);
       return "prettier";
     } catch {
       return "biome";
@@ -8008,8 +8360,8 @@ function findGitDir2(cwd, projectRoot) {
   let dir = cwd;
   for (let i = 0; i < 20; i++) {
     try {
-      const stat11 = statSync(`${dir}/.git`);
-      if (stat11.isDirectory() || stat11.isFile()) return dir;
+      const stat12 = statSync(`${dir}/.git`);
+      if (stat12.isDirectory() || stat12.isFile()) return dir;
     } catch {
     }
     if (dir === root) break;
@@ -8156,6 +8508,10 @@ var globTool = {
   category: "Filesystem",
   description: "Find files matching a glob pattern. Fast way to discover relevant files before reading, grepping, or editing them.",
   usageHint: "RECOMMENDED FOR SCOPING SEARCHES:\n\n- Use early to get a list of files you actually care about.\n- Combine with `path` and `limit`.\n- Default ignores common build/dependency directories.\nMuch more efficient than shell `find` for most use cases inside the agent.",
+  selection: {
+    doNotUseWhen: "you need to search inside file contents.",
+    useInstead: ["grep"]
+  },
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -8180,8 +8536,9 @@ var globTool = {
     },
     required: ["pattern"]
   },
-  async execute(input, ctx) {
+  async execute(input, ctx, opts) {
     if (!input?.pattern) throw new Error("glob: pattern is required");
+    const signal = opts?.signal;
     const base = input.path ? await safeResolveReal(input.path, ctx) : ctx.cwd;
     const limit = Math.max(1, Math.min(input.limit ?? 1e3, 5e3));
     const ignored = await readGitignore(base);
@@ -8205,6 +8562,10 @@ var globTool = {
       }
     };
     const walk = async (dir, relPrefix) => {
+      if (signal?.aborted) {
+        truncated = true;
+        return;
+      }
       if (results.length >= limit) {
         truncated = true;
         return;
@@ -8222,7 +8583,7 @@ var globTool = {
         if (DEFAULT_IGNORE2.includes(name)) continue;
         if (ignored.includes(name)) continue;
         const rel = relPrefix ? `${relPrefix}/${name}` : name;
-        const full = path3.join(dir, name);
+        const full = path12.join(dir, name);
         if (e.isDirectory()) {
           subdirs.push({ full, rel });
         } else if (e.isFile()) {
@@ -8266,7 +8627,7 @@ var globTool = {
 };
 async function readGitignore(dir) {
   try {
-    const raw = await fs2.readFile(path3.join(dir, ".gitignore"), "utf8");
+    const raw = await fs2.readFile(path12.join(dir, ".gitignore"), "utf8");
     return raw.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
   } catch {
     return [];
@@ -8328,6 +8689,10 @@ var grepTool = {
   category: "Search",
   description: "Search across files using a regular expression. This is one of the primary code search tools. Prefers ripgrep for speed and features when available.",
   usageHint: 'POWERFUL CODE SEARCH TOOL:\n\n- `pattern` is a regular expression.\n- Use `output_mode: "content"` (default) to get matching lines with context.\n- Use `"files_with_matches"` when you only need the list of files.\n- Use `"count"` for quick statistics.\n- `glob` and `path` let you narrow the search scope significantly.\n- Always prefer this over `bash grep` when searching code.',
+  selection: {
+    doNotUseWhen: "you only need to locate files by name or path pattern.",
+    useInstead: ["glob"]
+  },
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -8567,8 +8932,8 @@ async function runNative(input, base, mode, limit, signal) {
     if (globRe && !globRe.test(name) && !globRe.test(full)) return;
     if (globRe) globRe.lastIndex = 0;
     try {
-      const stat11 = await fs2.stat(full);
-      if (!stat11.isFile() || stat11.size > maxBytes || stopped || signal.aborted) return;
+      const stat12 = await fs2.stat(full);
+      if (!stat12.isFile() || stat12.size > maxBytes || stopped || signal.aborted) return;
       const file = await fs2.open(full, "r");
       try {
         let bytesReadTotal = 0;
@@ -8658,7 +9023,7 @@ async function runNative(input, base, mode, limit, signal) {
       if (stopped) return;
       if (DEFAULT_IGNORE3.includes(e.name)) continue;
       if (e.isSymbolicLink()) continue;
-      const full = path3.join(dir, e.name);
+      const full = path12.join(dir, e.name);
       if (e.isDirectory()) {
         subdirs.push(full);
       } else if (e.isFile()) {
@@ -9205,56 +9570,56 @@ function jmespathSearch(data, query) {
 }
 function validateJsonSchema(data, schema) {
   const errors = [];
-  function check(value, s, path22) {
+  function check(value, s, path23) {
     if (s["type"]) {
       const expectedType = s["type"];
       const actualType = Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
       if (expectedType === "integer") {
-        if (!Number.isInteger(value)) errors.push(`${path22}: expected integer, got ${actualType}`);
+        if (!Number.isInteger(value)) errors.push(`${path23}: expected integer, got ${actualType}`);
       } else if (expectedType !== actualType) {
-        errors.push(`${path22}: expected ${expectedType}, got ${actualType}`);
+        errors.push(`${path23}: expected ${expectedType}, got ${actualType}`);
       }
     }
     if (typeof value === "string" && s["format"] === "uri" && value) {
       try {
         new URL(value);
       } catch {
-        errors.push(`${path22}: not a valid URI`);
+        errors.push(`${path23}: not a valid URI`);
       }
     }
     if (typeof value === "string" && s["pattern"]) {
       const re = new RegExp(s["pattern"]);
-      if (!re.test(value)) errors.push(`${path22}: does not match pattern ${s["pattern"]}`);
+      if (!re.test(value)) errors.push(`${path23}: does not match pattern ${s["pattern"]}`);
     }
     if (typeof value === "string" && s["minLength"] !== void 0 && value.length < s["minLength"]) {
-      errors.push(`${path22}: string too short (min ${s["minLength"]})`);
+      errors.push(`${path23}: string too short (min ${s["minLength"]})`);
     }
     if (typeof value === "string" && s["maxLength"] !== void 0 && value.length > s["maxLength"]) {
-      errors.push(`${path22}: string too long (max ${s["maxLength"]})`);
+      errors.push(`${path23}: string too long (max ${s["maxLength"]})`);
     }
     if (typeof value === "number" && s["minimum"] !== void 0 && value < s["minimum"]) {
-      errors.push(`${path22}: below minimum ${s["minimum"]}`);
+      errors.push(`${path23}: below minimum ${s["minimum"]}`);
     }
     if (typeof value === "number" && s["maximum"] !== void 0 && value > s["maximum"]) {
-      errors.push(`${path22}: above maximum ${s["maximum"]}`);
+      errors.push(`${path23}: above maximum ${s["maximum"]}`);
     }
     if (Array.isArray(value) && s["items"] && Array.isArray(s["items"])) {
       for (let i = 0; i < value.length; i++) {
-        check(value[i], s["items"], `${path22}[${i}]`);
+        check(value[i], s["items"], `${path23}[${i}]`);
       }
     }
     if (typeof value === "object" && value !== null && !Array.isArray(value) && s["properties"]) {
       const props = s["properties"];
       for (const [k, propSchema] of Object.entries(props)) {
-        check(value[k], propSchema, `${path22}.${k}`);
+        check(value[k], propSchema, `${path23}.${k}`);
       }
     }
   }
   check(data, schema, "$");
   return { valid: errors.length === 0, errors };
 }
-function simpleQuery(data, path22) {
-  const parts = path22.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+function simpleQuery(data, path23) {
+  const parts = path23.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
   let current = data;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;
@@ -10179,11 +10544,11 @@ var lintTool = {
   }
 };
 async function detectLinter(cwd) {
-  const { stat: stat11 } = await import('node:fs/promises');
+  const { stat: stat12 } = await import('node:fs/promises');
   const checks = ["biome.json", ".eslintrc.json", "tslint.json", ".eslintrc.js", "tsconfig.json"];
   for (const f of checks) {
     try {
-      await stat11(`${cwd}/${f}`);
+      await stat12(`${cwd}/${f}`);
       if (f.includes("biome")) return "biome";
       if (f.includes("eslint")) return "eslint";
       if (f.includes("tslint")) return "tslint";
@@ -10325,7 +10690,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
 }
 var DOCKER_LOGS_TIMEOUT_MS = 3e3;
 var MAX_TAIL_LINES = 1e5;
-async function fileLogs(path22, lines, filterRe, stream) {
+async function fileLogs(path23, lines, filterRe, stream) {
   const { createInterface } = await import('node:readline');
   const { createReadStream } = await import('node:fs');
   const entries = [];
@@ -10334,7 +10699,7 @@ async function fileLogs(path22, lines, filterRe, stream) {
   let writeIdx = 0;
   let totalLines = 0;
   const rl = createInterface({
-    input: createReadStream(path22),
+    input: createReadStream(path23),
     crlfDelay: Number.POSITIVE_INFINITY
   });
   for await (const line of rl) {
@@ -10355,7 +10720,7 @@ async function fileLogs(path22, lines, filterRe, stream) {
     if (parsed) entries.push(parsed);
   }
   return {
-    source: path22,
+    source: path23,
     entries,
     total: entries.length,
     truncated: totalLines > effLines,
@@ -10522,6 +10887,10 @@ var patchTool = {
   category: "Filesystem",
   description: "Apply a unified diff (patch) to the project. This is the correct tool when you have a diff that needs to be applied precisely, including handling of rejects.",
   usageHint: "Best used when you already have a diff (from generation, external source, or previous step).\n- Use `dry_run: true` to see what would happen without modifying files.\n- On failure it creates .rej and .orig files for manual review.\nOften cleaner than many small `edit` operations for larger changes.",
+  selection: {
+    doNotUseWhen: "you do not already have a unified diff or only need one precise replacement.",
+    useInstead: ["edit"]
+  },
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
@@ -10543,12 +10912,13 @@ var patchTool = {
     const strip = Math.max(1, input.strip ?? 1);
     const dryRun = input.dry_run ?? false;
     const targets = extractDiffTargets(input.patch);
+    const resolvedTargets = [];
     for (const t of targets) {
       const stripped = stripPathComponents(t, strip);
       if (!stripped) continue;
-      const candidate = path3.resolve(dir, stripped);
-      const rel = path3.relative(ctx.projectRoot, candidate);
-      if (rel.startsWith("..") || path3.isAbsolute(rel)) {
+      const candidate = path12.resolve(dir, stripped);
+      const rel = path12.relative(ctx.projectRoot, candidate);
+      if (rel.startsWith("..") || path12.isAbsolute(rel)) {
         return {
           applied: 0,
           rejected: 1,
@@ -10557,12 +10927,19 @@ var patchTool = {
           message: `patch refused: target "${t}" resolves outside project root`
         };
       }
+      resolvedTargets.push(candidate);
     }
-    const tmpDir = await fs2.mkdtemp(path3.join(os2.tmpdir(), ".wstack_patch_"));
+    const beforeContents = /* @__PURE__ */ new Map();
+    if (!dryRun) {
+      for (const target of resolvedTargets) {
+        beforeContents.set(target, await readTextForTracking(target));
+      }
+    }
+    const tmpDir = await fs2.mkdtemp(path12.join(os2.tmpdir(), ".wstack_patch_"));
     try {
       await fs2.chmod(tmpDir, 448).catch(() => {
       });
-      const patchFile = path3.join(tmpDir, "in.diff");
+      const patchFile = path12.join(tmpDir, "in.diff");
       await fs2.writeFile(patchFile, input.patch, { mode: 384 });
       const args = [`-p${strip}`, "--merge", ...dryRun ? ["--dry-run"] : [], "-i", patchFile];
       const result = await runPatch(args, dir, opts.signal);
@@ -10576,6 +10953,21 @@ var patchTool = {
         };
       }
       const patched = extractPatchedFiles(result.stdout);
+      if (!dryRun) {
+        for (const target of resolvedTargets) {
+          const before = beforeContents.get(target) ?? null;
+          const after = await readTextForTracking(target);
+          if (after === null || after === before) continue;
+          const stat12 = await fs2.stat(target).catch(() => null);
+          if (stat12) ctx.recordRead?.(target, stat12.mtimeMs, "write", sha256hex(after));
+          ctx.session?.recordFileChange?.({
+            path: target,
+            action: before === null ? "created" : "modified",
+            before,
+            after
+          });
+        }
+      }
       return {
         applied: patched.length,
         rejected: 0,
@@ -10589,6 +10981,18 @@ var patchTool = {
     }
   }
 };
+var MAX_TRACKING_BYTES = 5 * 1024 * 1024;
+async function readTextForTracking(absPath) {
+  try {
+    const stat12 = await fs2.stat(absPath);
+    if (!stat12.isFile() || stat12.size > MAX_TRACKING_BYTES) return null;
+    const buf = await fs2.readFile(absPath);
+    if (buf.includes(0)) return null;
+    return buf.toString("utf8");
+  } catch {
+    return null;
+  }
+}
 function extractDiffTargets(patch) {
   const out = [];
   const re = /^\+\+\+\s+([^\t\r\n]+)/gm;
@@ -10896,6 +11300,10 @@ var readTool = {
   category: "Filesystem",
   description: "Read the contents of a file with line numbers. This is the primary way to inspect source code, configuration, or any text file before making changes. Lines are returned 1-indexed with a `   N| ` prefix for easy reference in edits.",
   usageHint: "FOUNDATIONAL TOOL \u2014 call this before almost any edit operation.\n\nBest practices:\n- Always read a file before using `edit`, `replace`, or `write` on it (the system often requires it for safety).\n- Use `offset` + `limit` for very large files instead of reading everything at once.\n- Default limit is generous (2000 lines) but can be increased.\n- The output format is designed to be directly usable as context for `edit` operations.",
+  selection: {
+    doNotUseWhen: "you need to search many files for matching content.",
+    useInstead: ["grep"]
+  },
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
@@ -10933,9 +11341,9 @@ var readTool = {
       });
     }
     const absPath = await safeResolveReal(input.path, ctx);
-    let stat11;
+    let stat12;
     try {
-      stat11 = await fs2.stat(absPath);
+      stat12 = await fs2.stat(absPath);
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") {
@@ -10954,7 +11362,7 @@ var readTool = {
         cause: err
       });
     }
-    if (!stat11.isFile()) {
+    if (!stat12.isFile()) {
       throw new FsError({
         message: `read: "${input.path}" is not a regular file`,
         code: "FS_READ_FAILED",
@@ -10962,22 +11370,22 @@ var readTool = {
         context: { reason: "not-a-regular-file" }
       });
     }
-    if (stat11.size > MAX_BYTES2) {
+    if (stat12.size > MAX_BYTES2) {
       throw new FsError({
-        message: `read: file too large (${stat11.size} bytes, limit ${MAX_BYTES2})`,
+        message: `read: file too large (${stat12.size} bytes, limit ${MAX_BYTES2})`,
         code: "FS_READ_FAILED",
         path: absPath,
-        context: { size: stat11.size, limit: MAX_BYTES2, reason: "too-large" }
+        context: { size: stat12.size, limit: MAX_BYTES2, reason: "too-large" }
       });
     }
     const offset = Math.max(1, input.offset ?? 1);
     const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
     const prior = getReadRangeRecord(ctx, absPath);
     const requestedEnd = prior ? Math.min(offset + limit - 1, prior.totalLines) : offset + limit - 1;
-    if (input.mode !== "summary" && limit > 0 && prior && coversRange(prior, stat11.mtimeMs, offset, requestedEnd)) {
-      ctx.recordRead(absPath, stat11.mtimeMs);
+    if (input.mode !== "summary" && limit > 0 && prior && coversRange(prior, stat12.mtimeMs, offset, requestedEnd)) {
+      ctx.recordRead(absPath, stat12.mtimeMs);
       return {
-        text: `[unchanged since previous read: "${input.path}" mtime=${Math.round(stat11.mtimeMs)}; requested lines ${offset}-${requestedEnd} were already shown. Use offset/limit for a new range if needed.]`,
+        text: `[unchanged since previous read: "${input.path}" mtime=${Math.round(stat12.mtimeMs)}; requested lines ${offset}-${requestedEnd} were already shown. Use offset/limit for a new range if needed.]`,
         total_lines: prior.totalLines,
         encoding: "utf8",
         truncated: requestedEnd < prior.totalLines,
@@ -10990,13 +11398,14 @@ var readTool = {
       throw new Error(`read: "${input.path}" appears to be binary`);
     }
     const text = buf.toString("utf8");
+    const contentHash = sha256hex(text);
     const allLines = text.split(/\r\n|\r|\n/);
     const total = allLines.length;
     if (input.mode === "summary") {
-      ctx.recordRead(absPath, stat11.mtimeMs);
-      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, 1, Math.min(total, 200));
+      ctx.recordRead(absPath, stat12.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat12.mtimeMs, total, 1, Math.min(total, 200));
       return {
-        text: summarizeFile(input.path, stat11.size, allLines),
+        text: summarizeFile(input.path, stat12.size, allLines),
         total_lines: total,
         encoding: "utf8",
         truncated: total > 200,
@@ -11004,13 +11413,13 @@ var readTool = {
       };
     }
     if (limit === 0) {
-      ctx.recordRead(absPath, stat11.mtimeMs);
-      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, 1, 0);
+      ctx.recordRead(absPath, stat12.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat12.mtimeMs, total, 1, 0);
       return { text: "", total_lines: total, encoding: "utf8", truncated: total > 0 };
     }
     if (offset > total) {
-      ctx.recordRead(absPath, stat11.mtimeMs);
-      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, total + 1, total + 1);
+      ctx.recordRead(absPath, stat12.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat12.mtimeMs, total, total + 1, total + 1);
       return {
         text: `[offset ${offset} is past end of file "${input.path}" \u2014 file has ${total} line(s). Do not retry this offset.]`,
         total_lines: total,
@@ -11022,8 +11431,8 @@ var readTool = {
     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, stat11.mtimeMs);
-    rememberReadRange(ctx, absPath, stat11.mtimeMs, total, offset, offset + slice.length - 1);
+    ctx.recordRead(absPath, stat12.mtimeMs, "user", contentHash);
+    rememberReadRange(ctx, absPath, stat12.mtimeMs, total, offset, offset + slice.length - 1);
     return {
       text: numbered,
       total_lines: total,
@@ -11165,10 +11574,10 @@ var replaceTool = {
       } catch {
         continue;
       }
-      const rel = path3.relative(realRoot, realPath);
-      if (rel.startsWith("..") || path3.isAbsolute(rel)) continue;
-      const stat11 = await fs2.stat(realPath).catch(() => null);
-      if (!stat11?.isFile()) continue;
+      const rel = path12.relative(realRoot, realPath);
+      if (rel.startsWith("..") || path12.isAbsolute(rel)) continue;
+      const stat12 = await fs2.stat(realPath).catch(() => null);
+      if (!stat12?.isFile()) continue;
       let content;
       try {
         const buf = await fs2.readFile(realPath);
@@ -11193,7 +11602,17 @@ var replaceTool = {
       totalReplacements += count;
       if (!dryRun) {
         const newContent = toStyle(newContentLf, style);
-        await atomicWrite(realPath, newContent, { mode: stat11.mode & 511 });
+        await atomicWrite(realPath, newContent, { mode: stat12.mode & 511 });
+        const written = await fs2.stat(realPath).catch(() => null);
+        if (written) {
+          ctx.recordRead?.(realPath, written.mtimeMs, "write", sha256hex(newContent));
+        }
+        ctx.session?.recordFileChange?.({
+          path: realPath,
+          action: "modified",
+          before: content,
+          after: newContent
+        });
       }
       const diff = dryRun || matches.length > 0 ? unifiedDiff(content, toStyle(newContentLf, style), {
         fromFile: absPath,
@@ -11223,8 +11642,8 @@ async function resolveFiles2(filesInput, ctx, extraGlob) {
   const resolved = [];
   for (const p of parts) {
     const absPath = safeResolve(p, ctx);
-    const stat11 = await fs2.stat(absPath).catch(() => null);
-    if (stat11?.isFile()) {
+    const stat12 = await fs2.stat(absPath).catch(() => null);
+    if (stat12?.isFile()) {
       resolved.push(absPath);
     }
   }
@@ -11285,10 +11704,10 @@ async function globNative(pattern, base, extraGlob) {
     }
     for (const e of entries) {
       if (DEFAULT_IGNORE4.includes(e.name)) continue;
-      const full = path3.join(dir, e.name);
+      const full = path12.join(dir, e.name);
       try {
-        const stat11 = await fs2.lstat(full);
-        if (stat11.isSymbolicLink()) continue;
+        const stat12 = await fs2.lstat(full);
+        if (stat12.isSymbolicLink()) continue;
       } catch {
         continue;
       }
@@ -11456,16 +11875,16 @@ async function handleBuiltIn(name, templateFiles, cwd, ctx, dryRun, vars) {
   let filesCreated = 0;
   for (const [filePath, content] of Object.entries(templateFiles)) {
     const resolvedPath = substituteVars(filePath, name, vars);
-    const joinedPath = path3.join(cwd, resolvedPath);
-    const root = path3.resolve(ctx.projectRoot);
-    const target = path3.resolve(joinedPath);
-    const rel = path3.relative(root, target);
-    if (rel.startsWith("..") || path3.isAbsolute(rel)) {
+    const joinedPath = path12.join(cwd, resolvedPath);
+    const root = path12.resolve(ctx.projectRoot);
+    const target = path12.resolve(joinedPath);
+    const rel = path12.relative(root, target);
+    if (rel.startsWith("..") || path12.isAbsolute(rel)) {
       throw new Error(`scaffold: generated path "${resolvedPath}" would escape project root`);
     }
     const fullPath = target;
     if (!dryRun) {
-      await fs2.mkdir(path3.dirname(fullPath), { recursive: true });
+      await fs2.mkdir(path12.dirname(fullPath), { recursive: true });
       await atomicWrite(fullPath, substituteVars(content, name, vars));
     }
     files.push(resolvedPath);
@@ -12365,11 +12784,11 @@ var testTool = {
   }
 };
 async function detectRunner(cwd) {
-  const { stat: stat11 } = await import('node:fs/promises');
+  const { stat: stat12 } = await import('node:fs/promises');
   const candidates = ["vitest.config.ts", "jest.config.js", ".mocharc.json"];
   for (const f of candidates) {
     try {
-      await stat11(path3.join(cwd, f));
+      await stat12(path12.join(cwd, f));
       if (f.includes("vitest")) return "vitest";
       if (f.includes("jest")) return "jest";
       if (f.includes("mocha")) return "mocha";
@@ -12997,7 +13416,7 @@ async function walkDir(dir, depth, opts) {
     opts.lines.push(opts.prefix + branch + displayName);
     if (entry.isDirectory() && (opts.maxDepth === 0 || depth < opts.maxDepth)) {
       const childPrefix = opts.prefix + connector;
-      await walkDir(path3.join(dir, entry.name), depth + 1, {
+      await walkDir(path12.join(dir, entry.name), depth + 1, {
         ...opts,
         prefix: childPrefix,
         isLast
@@ -13083,12 +13502,12 @@ var typecheckTool = {
   }
 };
 async function findTsConfig(cwd) {
-  const { stat: stat11 } = await import('node:fs/promises');
+  const { stat: stat12 } = await import('node:fs/promises');
   const candidates = ["tsconfig.json", "tsconfig.base.json"];
   for (const f of candidates) {
     try {
-      const s = await stat11(path3.join(cwd, f));
-      if (s.isFile()) return path3.join(cwd, f);
+      const s = await stat12(path12.join(cwd, f));
+      if (s.isFile()) return path12.join(cwd, f);
     } catch {
     }
   }
@@ -13099,6 +13518,10 @@ var writeTool = {
   category: "Filesystem",
   description: "Write or completely overwrite a file on disk. This is a high-privilege operation. For modifying existing files, you should almost always prefer the `edit` tool instead, because `edit` is safer and works on the last-read version of the file.",
   usageHint: "RULES FOR CORRECT USAGE:\n- Use `write` primarily for **new files** or when you want to replace the entire content.\n- For any existing file, strongly prefer `edit` (it requires a prior `read` in the same session and is more precise).\n- You MUST have called `read` on the file earlier in the conversation before using `write` on an existing path (the system enforces this for safety).\n- The path is resolved relative to the project root and protected against escaping the workspace.",
+  selection: {
+    doNotUseWhen: "making a precise change to part of an existing file.",
+    useInstead: ["edit"]
+  },
   permission: "confirm",
   mutating: true,
   timeoutMs: 5e3,
@@ -13118,10 +13541,10 @@ var writeTool = {
     },
     required: ["path", "content"]
   },
-  async execute(input, ctx) {
-    return writeFile7(input, ctx);
+  async execute(input, ctx, opts) {
+    return writeFile7(input, ctx, opts?.signal);
   },
-  async *executeStream(input, ctx) {
+  async *executeStream(input, ctx, opts) {
     const prepared = await prepareWrite(input, ctx);
     if (!prepared.existed) {
       for (const line of input.content.split("\n")) {
@@ -13129,11 +13552,11 @@ var writeTool = {
 `, data: { livePreview: true } };
       }
     }
-    yield { type: "final", output: await finishWrite(input, ctx, prepared) };
+    yield { type: "final", output: await finishWrite(input, ctx, prepared, opts?.signal) };
   }
 };
-async function writeFile7(input, ctx) {
-  return finishWrite(input, ctx, await prepareWrite(input, ctx));
+async function writeFile7(input, ctx, signal) {
+  return finishWrite(input, ctx, await prepareWrite(input, ctx), signal);
 }
 async function prepareWrite(input, ctx) {
   if (!input?.path) {
@@ -13152,12 +13575,12 @@ async function prepareWrite(input, ctx) {
   let existed = false;
   let prev = "";
   try {
-    const stat11 = await fs2.stat(absPath);
-    existed = stat11.isFile();
+    const stat12 = await fs2.stat(absPath);
+    existed = stat12.isFile();
     if (existed) {
       if (!ctx.hasRead(absPath)) {
         prev = await fs2.readFile(absPath, "utf8");
-        ctx.recordRead(absPath, stat11.mtimeMs, "write");
+        ctx.recordRead(absPath, stat12.mtimeMs, "write", sha256hex(prev));
       } else {
         prev = await fs2.readFile(absPath, "utf8");
       }
@@ -13169,23 +13592,32 @@ async function prepareWrite(input, ctx) {
   }
   return { absPath, existed, prev };
 }
-async function finishWrite(input, ctx, prepared) {
+async function finishWrite(input, ctx, prepared, signal) {
+  signal?.throwIfAborted();
   await atomicWrite(prepared.absPath, input.content);
   const diff = prepared.existed ? unifiedDiff(prepared.prev, input.content, { fromFile: input.path, toFile: input.path }) : `+++ ${input.path}
 + (new file, ${input.content.split("\n").length} lines)`;
-  const stat11 = await fs2.stat(prepared.absPath);
-  ctx.recordRead(prepared.absPath, stat11.mtimeMs, "write");
+  const stat12 = await fs2.stat(prepared.absPath);
+  ctx.recordRead(prepared.absPath, stat12.mtimeMs, "write", sha256hex(input.content));
   ctx.session.recordFileChange({
     path: prepared.absPath,
     action: prepared.existed ? "modified" : "created",
     before: prepared.existed ? prepared.prev : null,
     after: input.content
   });
+  const syntax = await checkSyntax(
+    prepared.absPath,
+    input.content,
+    prepared.existed ? prepared.prev : void 0
+  ).catch(() => void 0);
+  const hasSyntaxErrors = syntax !== void 0 && syntax.errors.length > 0;
   return {
     path: prepared.absPath,
     bytes_written: Buffer.byteLength(input.content, "utf8"),
     created: !prepared.existed,
-    diff
+    diff,
+    syntax_errors: hasSyntaxErrors ? syntax.errors : void 0,
+    note: hasSyntaxErrors ? syntax.preExisting ? "Syntax check: the file still has parse errors (they pre-date this write) \u2014 see syntax_errors." : `Syntax check: the written content has ${syntax.errors.length} parse error(s) \u2014 fix them now, see syntax_errors.` : void 0
   };
 }