@cortexkit/aft-pi 0.31.1 → 0.33.0

package/dist/index.js

@@ -11680,6 +11680,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 var DEFAULT_BRIDGE_TIMEOUT_MS = 30000;
+var BRIDGE_HANG_TIMEOUT_THRESHOLD = 2;
 var SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS = 5000;
 var MAX_STDOUT_BUFFER = 64 * 1024 * 1024;
 function tagStderrLine(line) {
@@ -11787,8 +11788,11 @@ class BinaryBridge {
   statusListeners = new Set;
   configureWarningClients = new Map;
   restartResetTimer = null;
+  lastChildActivityAt = 0;
+  consecutiveRequestTimeouts = 0;
   errorPrefix;
   logger;
+  childEnv;
   constructor(binaryPath, cwd, options, configOverrides) {
     this.binaryPath = binaryPath;
     this.cwd = cwd;
@@ -11803,6 +11807,7 @@ class BinaryBridge {
     this.onBashPatternMatch = options?.onBashPatternMatch;
     this.errorPrefix = options?.errorPrefix ?? "[aft-bridge]";
     this.logger = options?.logger;
+    this.childEnv = options?.childEnv;
   }
   logVia(message, meta) {
     const logger = this.logger ?? getActiveLogger();
@@ -11954,20 +11959,41 @@ class BinaryBridge {
       const line = `${JSON.stringify(request)}
 `;
       const keepBridgeOnTimeout = options?.keepBridgeOnTimeout === true;
+      let requestSentAt = Date.now();
       const response = await new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
+          const entry = this.pending.get(id);
+          if (!entry)
+            return;
           this.pending.delete(id);
-          const restartSuffix = keepBridgeOnTimeout ? "" : " — restarting bridge";
+          clearTimeout(entry.timer);
+          if (keepBridgeOnTimeout) {
+            const timeoutMsg2 = `Request "${command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms`;
+            if (requestSessionId) {
+              this.sessionWarnVia(requestSessionId, timeoutMsg2);
+            } else {
+              this.warnVia(timeoutMsg2);
+            }
+            entry.reject(new Error(`${this.errorPrefix} Request "${command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms`));
+            return;
+          }
+          const childActiveSinceRequest = this.lastChildActivityAt > requestSentAt;
+          const consecutiveTimeouts = this.consecutiveRequestTimeouts + 1;
+          this.consecutiveRequestTimeouts = consecutiveTimeouts;
+          const keepWarm = childActiveSinceRequest || consecutiveTimeouts < BRIDGE_HANG_TIMEOUT_THRESHOLD;
+          const restartSuffix = keepWarm ? " — bridge kept warm" : " — restarting bridge";
           const timeoutMsg = `Request "${command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms${restartSuffix}`;
           if (requestSessionId) {
             this.sessionWarnVia(requestSessionId, timeoutMsg);
           } else {
             this.warnVia(timeoutMsg);
           }
-          reject(new Error(`${this.errorPrefix} Request "${command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms`));
-          if (!keepBridgeOnTimeout) {
-            this.handleTimeout(requestSessionId);
+          if (keepWarm) {
+            entry.reject(new Error(`${this.errorPrefix} request "${command}" timed out after ${effectiveTimeoutMs}ms (bridge busy/under load); bridge kept warm — retry`));
+            return;
           }
+          entry.reject(new Error(`${this.errorPrefix} Request "${command}" (id=${id}) timed out after ${effectiveTimeoutMs}ms`));
+          this.handleTimeout(requestSessionId);
         }, effectiveTimeoutMs);
         this.pending.set(id, { resolve, reject, timer, onProgress: options?.onProgress });
         if (!this.process?.stdin?.writable) {
@@ -11976,6 +12002,7 @@ class BinaryBridge {
           reject(new Error(`${this.errorPrefix} stdin not writable for command "${command}"`));
           return;
         }
+        requestSentAt = Date.now();
         this.process.stdin.write(line, (err) => {
           if (err) {
             const entry = this.pending.get(id);
@@ -12170,6 +12197,15 @@ class BinaryBridge {
         this.logVia(`ORT_DYLIB_PATH set from managed ONNX Runtime: ${ortLibraryPath}`);
       }
     }
+    if (this.childEnv) {
+      for (const [key, value] of Object.entries(this.childEnv)) {
+        if (value === undefined) {
+          delete env[key];
+        } else {
+          env[key] = value;
+        }
+      }
+    }
     const child = spawn(this.binaryPath, [], {
       cwd: this.cwd,
       stdio: ["pipe", "pipe", "pipe"],
@@ -12219,6 +12255,8 @@ class BinaryBridge {
     this.process = child;
     this.stdoutBuffer = "";
     this.stderrBuffer = "";
+    this.lastChildActivityAt = 0;
+    this.consecutiveRequestTimeouts = 0;
     this.stderrTail = [];
   }
   pushStderrLine(line) {
@@ -12274,6 +12312,7 @@ class BinaryBridge {
         continue;
       try {
         const response = JSON.parse(line);
+        this.lastChildActivityAt = Date.now();
         if (response.type === "progress") {
           const requestId = response.request_id;
           const entry = requestId ? this.pending.get(requestId) : undefined;
@@ -12326,6 +12365,7 @@ class BinaryBridge {
             continue;
           this.pending.delete(id);
           clearTimeout(entry.timer);
+          this.consecutiveRequestTimeouts = 0;
           this.scheduleRestartCountReset();
           entry.resolve(response);
         } else if (typeof response.type === "string") {
@@ -12337,6 +12377,7 @@ class BinaryBridge {
     }
   }
   handleTimeout(triggeringSessionId) {
+    this.consecutiveRequestTimeouts = 0;
     this.rejectAllPending(new Error(`${this.errorPrefix} bridge killed during sibling timeout — request aborted`));
     if (this.process) {
       this.process.kill("SIGKILL");
@@ -12415,7 +12456,7 @@ class BinaryBridge {
 // ../aft-bridge/dist/downloader.js
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { chmodSync, closeSync, copyFileSync, createWriteStream, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join as join2 } from "node:path";
 import { Readable } from "node:stream";
@@ -12582,10 +12623,18 @@ async function downloadBinary(version) {
       throw new Error(`Checksum mismatch for ${assetName}: expected ${expectedHash}, got ${actualHash}. ` + "The binary may have been tampered with.");
     }
     log(`Checksum verified (SHA-256: ${actualHash.slice(0, 16)}...)`);
-    if (process.platform !== "win32") {
+    if (process.platform === "win32") {
+      copyFileSync(tmpPath, binaryPath);
+    } else {
       chmodSync(tmpPath, 493);
+      renameSync(tmpPath, binaryPath);
+    }
+    try {
+      if (existsSync(tmpPath))
+        unlinkSync(tmpPath);
+    } catch {
+      warn(`Could not clean up temporary download file ${tmpPath} — it can be removed manually.`);
     }
-    renameSync(tmpPath, binaryPath);
     log(`AFT binary ready at ${binaryPath}`);
     return binaryPath;
   } catch (err) {
@@ -12756,7 +12805,7 @@ function markAnnouncementSeen(storageRoot, harness, currentVersion) {
 
 // ../aft-bridge/dist/resolver.js
 import { execSync } from "node:child_process";
-import { chmodSync as chmodSync2, copyFileSync, existsSync as existsSync3, mkdirSync as mkdirSync3, renameSync as renameSync3 } from "node:fs";
+import { chmodSync as chmodSync2, copyFileSync as copyFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync3, renameSync as renameSync3, unlinkSync as unlinkSync2 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import { homedir as homedir3 } from "node:os";
 import { join as join4 } from "node:path";
@@ -12779,10 +12828,15 @@ function copyToVersionedCache(npmBinaryPath, knownVersion) {
     }
     mkdirSync3(versionedDir, { recursive: true });
     const tmpPath = `${cachedPath}.${process.pid}.${Date.now()}.tmp`;
-    copyFileSync(npmBinaryPath, tmpPath);
+    copyFileSync2(npmBinaryPath, tmpPath);
     if (process.platform !== "win32") {
       chmodSync2(tmpPath, 493);
     }
+    if (process.platform === "win32" && existsSync3(cachedPath)) {
+      try {
+        unlinkSync2(cachedPath);
+      } catch {}
+    }
     renameSync3(tmpPath, cachedPath);
     log(`Copied npm binary to versioned cache: ${cachedPath}`);
     return cachedPath;
@@ -13034,7 +13088,7 @@ async function ensureStorageMigrated(opts) {
 // ../aft-bridge/dist/onnx-runtime.js
 import { execFileSync } from "node:child_process";
 import { createHash as createHash2 } from "node:crypto";
-import { chmodSync as chmodSync3, closeSync as closeSync2, copyFileSync as copyFileSync2, createWriteStream as createWriteStream2, existsSync as existsSync5, lstatSync, mkdirSync as mkdirSync5, openSync as openSync2, readdirSync, readFileSync as readFileSync3, readlinkSync, realpathSync, rmSync as rmSync2, statSync as statSync2, symlinkSync, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { chmodSync as chmodSync3, closeSync as closeSync2, copyFileSync as copyFileSync3, createWriteStream as createWriteStream2, existsSync as existsSync5, lstatSync, mkdirSync as mkdirSync5, openSync as openSync2, readdirSync, readFileSync as readFileSync3, readlinkSync, realpathSync, rmSync as rmSync2, statSync as statSync2, symlinkSync, unlinkSync as unlinkSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { basename, dirname as dirname3, isAbsolute, join as join6, relative, resolve, win32 } from "node:path";
 import { Readable as Readable2 } from "node:stream";
 import { pipeline as pipeline2 } from "node:stream/promises";
@@ -13270,20 +13324,64 @@ function findSystemOnnxRuntime(libName) {
   } else if (process.platform === "linux") {
     searchPaths.push("/usr/lib", "/usr/lib/x86_64-linux-gnu", "/usr/lib/aarch64-linux-gnu", "/usr/local/lib");
   } else if (process.platform === "win32") {
+    const programFiles = process.env.ProgramFiles ?? "C:\\Program Files";
+    const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    searchPaths.push(join6(programFiles, "onnxruntime", "lib"), join6(programFiles, "Microsoft ONNX Runtime", "lib"), join6(programFiles, "Microsoft Machine Learning", "lib"), join6(programFilesX86, "onnxruntime", "lib"), ...(() => {
+      const nugetPaths = [];
+      const userProfile = process.env.USERPROFILE ?? "";
+      if (!userProfile)
+        return nugetPaths;
+      const nugetPackageDir = join6(userProfile, ".nuget", "packages", "microsoft.ml.onnxruntime");
+      if (!existsSync5(nugetPackageDir))
+        return nugetPaths;
+      try {
+        for (const entry of readdirSync(nugetPackageDir, { withFileTypes: true })) {
+          if (!entry.isDirectory())
+            continue;
+          if (entry.name === "__globalPackagesFolder" || entry.name.startsWith("."))
+            continue;
+          nugetPaths.push(join6(nugetPackageDir, entry.name, "runtimes", "win-x64", "native"), join6(nugetPackageDir, entry.name, "runtimes", "win-arm64", "native"));
+        }
+      } catch (err) {
+        warn(`Failed to scan NuGet ONNX Runtime cache ${nugetPackageDir}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      return nugetPaths;
+    })());
     searchPaths.push(...pathEntriesForPlatform());
   }
+  const normalizeCase = process.platform === "win32" || process.platform === "darwin";
   const seen = new Set;
-  for (const dir of searchPaths) {
-    if (seen.has(dir))
-      continue;
-    seen.add(dir);
-    if (!directoryContainsLibrary(dir, libName))
-      continue;
-    const version = detectOnnxVersion(dir, libName);
-    if (version && !isOnnxVersionCompatible(version)) {
-      warn(`Skipping system ONNX Runtime at ${dir} (v${version}); AFT requires ` + `v${REQUIRED_ORT_MAJOR}.${REQUIRED_ORT_MIN_MINOR}+. Falling through to AFT-managed download.`);
+  const uniquePaths = searchPaths.filter((p) => {
+    let key = resolve(p).replace(/[/\\]+$/, "");
+    if (normalizeCase)
+      key = key.toLowerCase();
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
+  for (const dir of uniquePaths) {
+    const libPath = join6(dir, libName);
+    if (process.platform === "win32") {
+      if (!directoryContainsLibrary(dir, libName))
+        continue;
+    } else if (!existsSync5(libPath)) {
       continue;
     }
+    let skipVersionCheck = false;
+    if (process.platform === "win32") {
+      const dirLower = dir.toLowerCase();
+      const isCommonPath = dirLower.includes("program files") || dirLower.includes("onnxruntime");
+      if (!isCommonPath)
+        skipVersionCheck = true;
+    }
+    if (!skipVersionCheck) {
+      const version = detectOnnxVersion(dir, libName);
+      if (version && !isOnnxVersionCompatible(version)) {
+        warn(`Skipping system ONNX Runtime at ${dir} (v${version}); AFT requires ` + `v${REQUIRED_ORT_MAJOR}.${REQUIRED_ORT_MIN_MINOR}+. Falling through to AFT-managed download.`);
+        continue;
+      }
+    }
     return dir;
   }
   return null;
@@ -13321,7 +13419,7 @@ async function downloadFileWithCap(url, destPath) {
     await pipeline2(nodeStream, createWriteStream2(destPath), { signal: controller.signal });
   } catch (err) {
     try {
-      unlinkSync2(destPath);
+      unlinkSync3(destPath);
     } catch {}
     throw err;
   } finally {
@@ -13382,7 +13480,7 @@ async function downloadOnnxRuntime(info, targetDir) {
       await extractZipArchive(archivePath, tmpDir);
     }
     try {
-      unlinkSync2(archivePath);
+      unlinkSync3(archivePath);
     } catch {}
     validateExtractedTree(tmpDir);
     const extractedDir = join6(tmpDir, info.assetName, "lib");
@@ -13431,7 +13529,7 @@ async function downloadOnnxRuntime(info, targetDir) {
     return null;
   }
 }
-function copyOnnxLibraries(info, extractedDir, targetDir, realFiles, symlinks, copyFile = copyFileSync2) {
+function copyOnnxLibraries(info, extractedDir, targetDir, realFiles, symlinks, copyFile = copyFileSync3) {
   const requiredLibs = new Set([info.libName]);
   for (const libFile of realFiles) {
     const src = join6(extractedDir, libFile);
@@ -13452,7 +13550,7 @@ function copyOnnxLibraries(info, extractedDir, targetDir, realFiles, symlinks, c
   for (const link of symlinks) {
     const dst = join6(targetDir, link.name);
     try {
-      unlinkSync2(dst);
+      unlinkSync3(dst);
     } catch {}
     try {
       symlinkSync(link.target, dst);
@@ -13563,7 +13661,7 @@ ${new Date().toISOString()}
   }
   log(`[onnx] reclaiming install lock (owner_pid=${owningPid ?? "unknown"}, alive=${ownerAlive}, age_ms=${age})`);
   try {
-    unlinkSync2(lockPath);
+    unlinkSync3(lockPath);
   } catch {}
   return tryClaim();
 }
@@ -13588,7 +13686,7 @@ function releaseLock(lockPath) {
       return;
     }
     try {
-      unlinkSync2(lockPath);
+      unlinkSync3(lockPath);
     } catch (unlinkErr) {
       const code = unlinkErr.code;
       if (code !== "ENOENT") {
@@ -14534,7 +14632,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.31.1",
+  version: "0.33.0",
   type: "module",
   description: "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   main: "dist/index.js",
@@ -14542,7 +14640,7 @@ var package_default = {
   license: "MIT",
   repository: {
     type: "git",
-    url: "https://github.com/cortexkit/aft"
+    url: "git+https://github.com/cortexkit/aft.git"
   },
   files: [
     "dist",
@@ -14556,7 +14654,7 @@ var package_default = {
     prepublishOnly: "bun run build"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.31.1",
+    "@cortexkit/aft-bridge": "0.33.0",
     "@xterm/headless": "^5.5.0",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
@@ -14564,12 +14662,12 @@ var package_default = {
     zod: "^4.1.8"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.31.1",
-    "@cortexkit/aft-darwin-x64": "0.31.1",
-    "@cortexkit/aft-linux-arm64": "0.31.1",
-    "@cortexkit/aft-linux-x64": "0.31.1",
-    "@cortexkit/aft-win32-arm64": "0.31.1",
-    "@cortexkit/aft-win32-x64": "0.31.1"
+    "@cortexkit/aft-darwin-arm64": "0.33.0",
+    "@cortexkit/aft-darwin-x64": "0.33.0",
+    "@cortexkit/aft-linux-arm64": "0.33.0",
+    "@cortexkit/aft-linux-x64": "0.33.0",
+    "@cortexkit/aft-win32-arm64": "0.33.0",
+    "@cortexkit/aft-win32-x64": "0.33.0"
   },
   devDependencies: {
     "@earendil-works/pi-coding-agent": "*",
@@ -14638,6 +14736,19 @@ function formatFlag(enabled) {
 function formatCount(value) {
   return value == null ? "—" : value.toLocaleString("en-US");
 }
+function formatSemanticIndexStatus(status, stage) {
+  if ((status === "loading" || status === "building") && stage === "fingerprint_change") {
+    return "Rebuilding (model changed)";
+  }
+  return status;
+}
+function formatSemanticRefreshing(refreshingCount) {
+  if (!Number.isFinite(refreshingCount) || refreshingCount <= 0)
+    return null;
+  if (refreshingCount > 20)
+    return "Ready (many files refreshing)";
+  return `Ready (${refreshingCount} file(s) refreshing)`;
+}
 function formatBytes(bytes) {
   if (!Number.isFinite(bytes) || bytes <= 0)
     return "0 B";
@@ -14688,6 +14799,7 @@ function coerceAftStatus(response) {
       files: readOptionalNumber(semanticIndex.files),
       entries_done: readOptionalNumber(semanticIndex.entries_done),
       entries_total: readOptionalNumber(semanticIndex.entries_total),
+      refreshing_count: readNumber(semanticIndex.refreshing_count),
       entries: readOptionalNumber(semanticIndex.entries),
       dimension: readOptionalNumber(semanticIndex.dimension),
       error: readNullableString(semanticIndex.error)
@@ -14730,9 +14842,13 @@ function formatStatusDialogMessage(status) {
     `- trigrams: ${formatCount(status.search_index.trigrams)}`,
     "",
     "Semantic index",
-    `- status: ${status.semantic_index.status}`,
-    `- entries: ${formatCount(status.semantic_index.entries)}`
+    `- status: ${formatSemanticIndexStatus(status.semantic_index.status, status.semantic_index.stage)}`
   ];
+  const refreshing = formatSemanticRefreshing(status.semantic_index.refreshing_count);
+  if (refreshing) {
+    lines.push(`- ${refreshing}`);
+  }
+  lines.push(`- entries: ${formatCount(status.semantic_index.entries)}`);
   if (status.semantic_index.backend) {
     lines.push(`- backend: ${status.semantic_index.backend}`);
   }
@@ -14779,6 +14895,17 @@ function coerceOptionalInt(v, paramName, min, max) {
   }
   return n;
 }
+function isEmptyParam(value) {
+  if (value === undefined || value === null)
+    return true;
+  if (typeof value === "string")
+    return value.length === 0;
+  if (Array.isArray(value))
+    return value.length === 0;
+  if (typeof value === "object")
+    return Object.keys(value).length === 0;
+  return false;
+}
 var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
   callers: 60000,
   trace_to: 60000,
@@ -14787,7 +14914,7 @@ var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
   impact: 60000,
   grep: 60000,
   glob: 60000,
-  semantic_search: 45000
+  semantic_search: 60000
 };
 function timeoutForCommand(command) {
   return LONG_RUNNING_COMMAND_TIMEOUT_MS[command];
@@ -15000,7 +15127,10 @@ function renderInner(s, error3, theme, innerWidth) {
   left.push(kv("trigrams", formatCountShort(s.search_index.trigrams), theme));
   left.push(kv("disk", formatBytes(s.disk.trigram_disk_bytes), theme));
   right.push(theme.fg("muted", "Semantic index"));
-  right.push(kv("status", colorStatus(s.semantic_index.status, theme), theme));
+  right.push(kv("status", colorStatus(s.semantic_index.status, theme, formatSemanticIndexStatus(s.semantic_index.status, s.semantic_index.stage)), theme));
+  const semanticRefreshing = formatSemanticRefreshing(s.semantic_index.refreshing_count);
+  if (semanticRefreshing)
+    right.push(theme.fg("muted", `  ${semanticRefreshing}`));
   right.push(kv("entries", formatCountShort(s.semantic_index.entries), theme));
   if (s.semantic_index.backend)
     right.push(kv("backend", s.semantic_index.backend, theme));
@@ -15074,24 +15204,24 @@ function formatCompressionStatusRows(compression) {
   appendCompressionScope(rows, "Project", compression.project);
   return rows;
 }
-function colorStatus(status, theme) {
+function colorStatus(status, theme, label = status) {
   switch (status) {
     case "ready":
       try {
-        return theme.fg("success", status);
+        return theme.fg("success", label);
       } catch {
-        return theme.fg("accent", status);
+        return theme.fg("accent", label);
       }
     case "loading":
     case "building":
-      return theme.fg("warning", status);
+      return theme.fg("warning", label);
     case "failed":
     case "error":
-      return theme.fg("error", status);
+      return theme.fg("error", label);
     case "disabled":
-      return theme.fg("muted", status);
+      return theme.fg("muted", label);
     default:
-      return status;
+      return label;
   }
 }
 function featureBadge(name, enabled, theme) {
@@ -15184,7 +15314,7 @@ function registerStatusCommand(pi, ctx) {
 
 // src/config.ts
 var import_comment_json = __toESM(require_src2(), 1);
-import { existsSync as existsSync6, readFileSync as readFileSync4, renameSync as renameSync4, unlinkSync as unlinkSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync4, renameSync as renameSync4, unlinkSync as unlinkSync4, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir6 } from "node:os";
 import { join as join8 } from "node:path";
 
@@ -28815,6 +28945,7 @@ var LspConfigSchema = exports_external.object({
   servers: exports_external.record(exports_external.string().trim().min(1), LspServerEntrySchema).optional(),
   disabled: exports_external.array(exports_external.string().trim().min(1)).optional(),
   python: exports_external.enum(["pyright", "ty", "auto"]).optional(),
+  diagnostics_on_edit: exports_external.boolean().optional(),
   auto_install: exports_external.boolean().optional(),
   grace_days: exports_external.number().int().positive().optional(),
   versions: exports_external.record(exports_external.string().trim().min(1), exports_external.string().trim().min(1)).optional()
@@ -28837,6 +28968,24 @@ var BashFeaturesSchema = exports_external.object({
   long_running_reminder_interval_ms: exports_external.number().int().positive().optional()
 });
 var BashConfigSchema = exports_external.union([exports_external.boolean(), BashFeaturesSchema]);
+var InspectConfigSchema = exports_external.object({
+  enabled: exports_external.boolean().optional(),
+  tier2_idle_minutes: exports_external.number().min(0).optional(),
+  categories: exports_external.record(exports_external.string(), exports_external.boolean()).optional(),
+  tier2_soft_deadline_ms: exports_external.number().int().positive().optional(),
+  max_drill_down_items: exports_external.number().int().positive().max(100).optional(),
+  duplicates: exports_external.object({
+    lower_bound: exports_external.number().int().positive().optional(),
+    discard_cost: exports_external.number().int().min(0).optional(),
+    anonymize: exports_external.object({
+      variables: exports_external.boolean().optional(),
+      fields: exports_external.boolean().optional(),
+      methods: exports_external.boolean().optional(),
+      types: exports_external.boolean().optional(),
+      literals: exports_external.boolean().optional()
+    }).optional()
+  }).optional()
+});
 var AftConfigSchema = exports_external.object({
   $schema: exports_external.string().optional(),
   format_on_edit: exports_external.boolean().optional(),
@@ -28849,6 +28998,7 @@ var AftConfigSchema = exports_external.object({
   restrict_to_project_root: exports_external.boolean().optional(),
   search_index: exports_external.boolean().optional(),
   semantic_search: exports_external.boolean().optional(),
+  inspect: InspectConfigSchema.optional(),
   bash: BashConfigSchema.optional(),
   experimental: ExperimentalConfigSchema.optional(),
   lsp: LspConfigSchema.optional(),
@@ -29059,7 +29209,7 @@ ${serialized}` : serialized;
   } catch (err) {
     if (tmpPath) {
       try {
-        unlinkSync3(tmpPath);
+        unlinkSync4(tmpPath);
       } catch {}
     }
     if (isWritableMigrationError(err)) {
@@ -29143,6 +29293,9 @@ function mergeLspConfig(base, override) {
   const projectSafe = {};
   if (override?.python !== undefined)
     projectSafe.python = override.python;
+  if (override?.diagnostics_on_edit !== undefined) {
+    projectSafe.diagnostics_on_edit = override.diagnostics_on_edit;
+  }
   const userDisabled = base?.disabled ?? [];
   const lsp = {
     ...base,
@@ -29153,6 +29306,27 @@ function mergeLspConfig(base, override) {
     return;
   return Object.fromEntries(Object.entries(lsp).filter(([, v]) => v !== undefined));
 }
+function mergeInspectConfig(baseInspect, overrideInspect) {
+  const inspect = {
+    ...baseInspect,
+    ...overrideInspect,
+    duplicates: baseInspect?.duplicates || overrideInspect?.duplicates ? {
+      ...baseInspect?.duplicates,
+      ...overrideInspect?.duplicates,
+      anonymize: baseInspect?.duplicates?.anonymize || overrideInspect?.duplicates?.anonymize ? {
+        ...baseInspect?.duplicates?.anonymize,
+        ...overrideInspect?.duplicates?.anonymize
+      } : undefined
+    } : undefined
+  };
+  if (inspect.duplicates && inspect.duplicates.anonymize === undefined) {
+    delete inspect.duplicates.anonymize;
+  }
+  if (Object.values(inspect).every((value) => value === undefined)) {
+    return;
+  }
+  return Object.fromEntries(Object.entries(inspect).filter(([, value]) => value !== undefined));
+}
 function mergeBashConfig(baseBash, overrideBash) {
   if (baseBash === undefined && overrideBash === undefined)
     return;
@@ -29209,6 +29383,7 @@ var PROJECT_SAFE_TOP_LEVEL_FIELDS = new Set([
   "validate_on_edit",
   "search_index",
   "semantic_search",
+  "inspect",
   "experimental",
   "bash"
 ]);
@@ -29239,8 +29414,10 @@ function mergeConfigs(base, override) {
   const lsp = mergeLspConfig(base.lsp, override.lsp);
   const experimental = mergeExperimentalConfig(base.experimental, override.experimental);
   const bash = mergeBashConfig(base.bash, override.bash);
+  const inspect = mergeInspectConfig(base.inspect, override.inspect);
   const safeOverride = pickProjectSafeFields(override);
   delete safeOverride.bash;
+  delete safeOverride.inspect;
   return {
     ...base,
     ...safeOverride,
@@ -29248,6 +29425,7 @@ function mergeConfigs(base, override) {
     ...Object.keys(checker).length > 0 ? { checker } : {},
     ...lsp ? { lsp } : {},
     ...bash !== undefined ? { bash } : {},
+    ...inspect !== undefined ? { inspect } : {},
     experimental,
     semantic,
     ...disabledTools.length > 0 ? { disabled_tools: [...new Set(disabledTools)] } : {}
@@ -29299,7 +29477,7 @@ import {
   openSync as openSync3,
   readFileSync as readFileSync5,
   statSync as statSync3,
-  unlinkSync as unlinkSync4,
+  unlinkSync as unlinkSync5,
   writeFileSync as writeFileSync4
 } from "node:fs";
 import { homedir as homedir7 } from "node:os";
@@ -29429,7 +29607,7 @@ ${new Date().toISOString()}
   }
   log2(`[lsp] reclaiming install lock for ${lockKey} (owner_pid=${owningPid ?? "unknown"}, alive=${ownerAlive}, age_ms=${age})`);
   try {
-    unlinkSync4(lock);
+    unlinkSync5(lock);
   } catch {}
   return tryClaim();
 }
@@ -29466,7 +29644,7 @@ function releaseInstallLock(lockKey) {
       return;
     }
     try {
-      unlinkSync4(lock);
+      unlinkSync5(lock);
     } catch (unlinkErr) {
       const code = unlinkErr.code;
       if (code !== "ENOENT") {
@@ -30122,7 +30300,7 @@ function runAutoInstall(projectRoot, config2, fetchImpl = fetch) {
 import { execFileSync as execFileSync2 } from "node:child_process";
 import { createHash as createHash4, randomBytes } from "node:crypto";
 import {
-  copyFileSync as copyFileSync3,
+  copyFileSync as copyFileSync4,
   createReadStream as createReadStream2,
   createWriteStream as createWriteStream3,
   existsSync as existsSync8,
@@ -30135,7 +30313,7 @@ import {
   renameSync as renameSync6,
   rmSync as rmSync4,
   statSync as statSync5,
-  unlinkSync as unlinkSync5,
+  unlinkSync as unlinkSync6,
   writeFileSync as writeFileSync5
 } from "node:fs";
 import { dirname as dirname4, join as join12, relative as relative2, resolve as resolve2 } from "node:path";
@@ -30497,7 +30675,7 @@ async function downloadFile(url2, destPath, fetchImpl, assetSize, signal) {
     await pipeline3(nodeStream, createWriteStream3(destPath), { signal: timeout.signal });
   } catch (err) {
     try {
-      unlinkSync5(destPath);
+      unlinkSync6(destPath);
     } catch {}
     throw err;
   } finally {
@@ -30729,7 +30907,7 @@ async function downloadAndInstall(spec, tag, assets, platform, arch, fetchImpl,
   } catch (err) {
     error2(`[lsp] hash ${spec.id} failed: ${err}`);
     try {
-      unlinkSync5(archivePath);
+      unlinkSync6(archivePath);
     } catch {}
     return null;
   }
@@ -30740,7 +30918,7 @@ async function downloadAndInstall(spec, tag, assets, platform, arch, fetchImpl,
     if (previousArchiveSha256 !== archiveSha256) {
       error2(`[lsp] ${spec.id} ${tag}: TOFU sha256 mismatch — refusing install. ` + `Previously installed archive sha256=${previousArchiveSha256}, downloaded sha256=${archiveSha256}. ` + `This means the published release for tag ${tag} changed. Investigate before proceeding.`);
       try {
-        unlinkSync5(archivePath);
+        unlinkSync6(archivePath);
       } catch {}
       return null;
     }
@@ -30752,7 +30930,7 @@ async function downloadAndInstall(spec, tag, assets, platform, arch, fetchImpl,
     return null;
   } finally {
     try {
-      unlinkSync5(archivePath);
+      unlinkSync6(archivePath);
     } catch {}
   }
   const innerBinaryPath = join12(extractDir, spec.binaryPathInArchive(platform, arch, version2));
@@ -30763,7 +30941,7 @@ async function downloadAndInstall(spec, tag, assets, platform, arch, fetchImpl,
   const targetBinary = ghBinaryPath(spec, platform);
   mkdirSync8(dirname4(targetBinary), { recursive: true });
   try {
-    copyFileSync3(innerBinaryPath, targetBinary);
+    copyFileSync4(innerBinaryPath, targetBinary);
     if (platform !== "win32") {
       const { chmodSync: chmodSync4 } = await import("node:fs");
       chmodSync4(targetBinary, 493);
@@ -30952,13 +31130,18 @@ function sendIgnoredMessage(client, sessionId, text) {
   }
 }
 async function readWarnedTools(bridge) {
+  let resp;
+  try {
+    resp = await bridge.send("db_get_state", { key: "warned_tools" });
+  } catch {
+    return null;
+  }
+  if (resp.success === false)
+    return null;
+  const value = resp.data?.value;
+  if (typeof value !== "string")
+    return {};
   try {
-    const resp = await bridge.send("db_get_state", { key: "warned_tools" });
-    if (resp.success === false)
-      return {};
-    const value = resp.data?.value;
-    if (typeof value !== "string")
-      return {};
     const parsed = JSON.parse(value);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
       return {};
@@ -30967,12 +31150,16 @@ async function readWarnedTools(bridge) {
     return {};
   }
 }
-async function hasWarnedFor(bridge, key) {
+async function warnedStatus(bridge, key) {
   const warned = await readWarnedTools(bridge);
-  return warned[key] === true || typeof warned[key] === "string";
+  if (warned === null)
+    return "unknown";
+  return warned[key] === true || typeof warned[key] === "string" ? "warned" : "fresh";
 }
 async function recordWarning(bridge, key) {
   const warned = await readWarnedTools(bridge);
+  if (warned === null)
+    return;
   warned[key] = true;
   try {
     await bridge.send("db_set_state", {
@@ -31021,7 +31208,7 @@ async function deliverConfigureWarnings(opts, warnings) {
     return;
   for (const warning of warnings) {
     const key = warningKey(warning, opts.projectRoot);
-    if (await hasWarnedFor(opts.bridge, key))
+    if (await warnedStatus(opts.bridge, key) !== "fresh")
       continue;
     if (!sendIgnoredMessage(opts.client, opts.sessionId, formatConfigureWarning(warning)))
       continue;
@@ -31289,24 +31476,6 @@ function groupByFile(items, getFile) {
   });
   return groups;
 }
-function distinctCount(values) {
-  return new Set(values.filter((value) => Boolean(value))).size;
-}
-function severityBadge(theme, severity) {
-  const label = severity === "information" ? "info" : severity;
-  switch (severity) {
-    case "error":
-      return theme.fg("error", `[${label}]`);
-    case "warning":
-      return theme.fg("warning", `[${label}]`);
-    case "information":
-      return theme.fg("accent", `[${label}]`);
-    case "hint":
-      return theme.fg("muted", `[${label}]`);
-    default:
-      return theme.fg("muted", `[${label}]`);
-  }
-}
 function formatTimestamp(value) {
   if (typeof value === "string" && value.length > 0)
     return value;
@@ -31531,9 +31700,9 @@ function registerAstTools(pi, ctx, surface) {
           pattern: params.pattern,
           lang: params.lang
         };
-        if (params.paths !== undefined)
+        if (!isEmptyParam(params.paths))
           req.paths = params.paths;
-        if (params.globs !== undefined)
+        if (!isEmptyParam(params.globs))
           req.globs = params.globs;
         if (params.contextLines !== undefined)
           req.context_lines = params.contextLines;
@@ -31561,9 +31730,9 @@ function registerAstTools(pi, ctx, surface) {
           rewrite: params.rewrite,
           lang: params.lang
         };
-        if (params.paths !== undefined)
+        if (!isEmptyParam(params.paths))
           req.paths = params.paths;
-        if (params.globs !== undefined)
+        if (!isEmptyParam(params.globs))
           req.globs = params.globs;
         req.dry_run = params.dryRun === true;
         const response = await callBridge(bridge, "ast_replace", req, extCtx);
@@ -32509,6 +32678,10 @@ function formatDiffForPi(oldContent, newContent, contextLines = DEFAULT_CONTEXT_
 }
 
 // src/tools/hoisted.ts
+var DIAGNOSTICS_PARAM_DESCRIPTION = "When true, wait up to 3 seconds for fresh LSP diagnostics on the edited file and include them in the result. Defaults to the configured `lsp.diagnostics_on_edit` value (false unless configured); per-call true/false overrides. Use aft_inspect to check diagnostics across a batch of edits or before tests/commits.";
+function diagnosticsOnEditDefault(ctx) {
+  return ctx.config.lsp?.diagnostics_on_edit ?? false;
+}
 function containsPath(parent, child) {
   const rel = relative3(parent, child);
   return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
@@ -32575,7 +32748,8 @@ var WriteParams = Type6.Object({
   filePath: Type6.String({
     description: "Path to the file to write (absolute or relative to project root)"
   }),
-  content: Type6.String({ description: "Full file contents to write" })
+  content: Type6.String({ description: "Full file contents to write" }),
+  diagnostics: Type6.Optional(Type6.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
 });
 var EditParams = Type6.Object({
   filePath: Type6.String({
@@ -32587,7 +32761,8 @@ var EditParams = Type6.Object({
   occurrence: optionalInt(0, Number.MAX_SAFE_INTEGER),
   appendContent: Type6.Optional(Type6.String({
     description: "Append text to the end of the file (creates the file if missing, parent dirs auto-created). When set, oldString/newString are ignored."
-  }))
+  })),
+  diagnostics: Type6.Optional(Type6.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
 });
 var GrepParams = Type6.Object({
   pattern: Type6.String({ description: "Regex pattern to search for" }),
@@ -32638,8 +32813,8 @@ function registerHoistedTools(pi, ctx, surface) {
     pi.registerTool({
       name: "write",
       label: "write",
-      description: "Write a file atomically with per-file backup, optional auto-format, and inline LSP diagnostics. Parent directories are created automatically. Overwrites existing files. Uses `filePath` (not `path`).",
-      promptSnippet: "Create or overwrite files (uses filePath; auto-formats; returns LSP diagnostics inline)",
+      description: "Write a file atomically with per-file backup and optional auto-format. Parent directories are created automatically. Overwrites existing files. Uses `filePath` (not `path`). Edits return as soon as the write completes unless `lsp.diagnostics_on_edit` or a per-call `diagnostics: true` requests legacy sync-wait behavior. Call `aft_inspect` afterward to check diagnostics across a batch of edits.",
+      promptSnippet: "Create or overwrite files (uses filePath; auto-formats; diagnostics follow lsp.diagnostics_on_edit unless overridden)",
       promptGuidelines: ["Use write only for new files or complete rewrites."],
       parameters: WriteParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
@@ -32650,8 +32825,8 @@ function registerHoistedTools(pi, ctx, surface) {
         const response = await callBridge(bridge, "write", {
           file: params.filePath,
           content: params.content,
-          diagnostics: true,
-          include_diff: true
+          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          include_diff_content: true
         }, extCtx);
         return buildMutationResult(params.filePath, response);
       },
@@ -32667,8 +32842,8 @@ function registerHoistedTools(pi, ctx, surface) {
     pi.registerTool({
       name: "edit",
       label: "edit",
-      description: "Find-and-replace edit with progressive fuzzy matching (handles whitespace and Unicode drift). Uses `filePath`, `oldString`, `newString`. Errors on multiple matches — use `occurrence` to pick one, or `replaceAll: true`. Always returns LSP diagnostics inline.",
-      promptSnippet: "Targeted find-and-replace (uses filePath/oldString/newString; occurrence or replaceAll for disambiguation; fuzzy whitespace matching). Pass appendContent to append to a file (creates if missing).",
+      description: "Find-and-replace edit with progressive fuzzy matching (handles whitespace and Unicode drift). Uses `filePath`, `oldString`, `newString`. Errors on multiple matches — use `occurrence` to pick one, or `replaceAll: true`. Edits return as soon as the write completes unless `lsp.diagnostics_on_edit` or a per-call `diagnostics: true` requests legacy sync-wait behavior. Call `aft_inspect` afterward to check diagnostics across a batch of edits.",
+      promptSnippet: "Targeted find-and-replace (uses filePath/oldString/newString; occurrence or replaceAll for disambiguation; fuzzy whitespace matching). Pass appendContent to append to a file (creates if missing). Diagnostics follow lsp.diagnostics_on_edit unless overridden.",
       promptGuidelines: [
         "Prefer edit over write when changing part of an existing file.",
         "Include enough surrounding context in oldString to make the match unique, or set replaceAll/occurrence explicitly.",
@@ -32685,8 +32860,8 @@ function registerHoistedTools(pi, ctx, surface) {
             op: "append",
             file: params.filePath,
             append_content: params.appendContent,
-            diagnostics: true,
-            include_diff: true
+            diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+            include_diff_content: true
           };
           const response2 = await callBridge(bridge, "edit_match", req2, extCtx);
           return buildMutationResult(params.filePath, response2);
@@ -32695,8 +32870,8 @@ function registerHoistedTools(pi, ctx, surface) {
           file: params.filePath,
           match: params.oldString ?? "",
           replacement: params.newString ?? "",
-          diagnostics: true,
-          include_diff: true
+          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          include_diff_content: true
         };
         if (params.replaceAll === true)
           req.replace_all = true;
@@ -32765,15 +32940,6 @@ function buildMutationResult(filePath, response) {
   }
   const summaryHeader = replacements !== undefined ? `Edited ${filePath} (+${additions}/-${deletions}, ${replacements} replacement${replacements === 1 ? "" : "s"})` : `Wrote ${filePath} (+${additions}/-${deletions})`;
   let text = summaryHeader;
-  if (diffText)
-    text += `
-
-${diffText}`;
-  if (truncated) {
-    text += `
-
-(diff truncated — file too large to include before/after content)`;
-  }
   if (noOp) {
     text += `
 
@@ -33053,106 +33219,234 @@ function registerImportTools(pi, ctx) {
   });
 }
 
-// src/tools/lsp.ts
-import { StringEnum as StringEnum3 } from "@earendil-works/pi-ai";
+// src/tools/inspect.ts
 import { Type as Type8 } from "typebox";
-var LspDiagnosticsParams = Type8.Object({
-  filePath: Type8.Optional(Type8.String({ description: "File to get diagnostics for (mutually exclusive with directory)" })),
-  directory: Type8.Optional(Type8.String({
-    description: "Directory to get diagnostics for (mutually exclusive with filePath)"
+var InspectParams = Type8.Object({
+  sections: Type8.Optional(Type8.Union([Type8.String(), Type8.Array(Type8.String())], {
+    description: "Categories to include in detailed drill-down (e.g. 'todos' or ['todos', 'dead_code']). Use 'all' for every active category. Omit for summary-only mode."
   })),
-  severity: Type8.Optional(StringEnum3(["error", "warning", "information", "hint", "all"], {
-    description: "Filter by severity (default: all)"
+  scope: Type8.Optional(Type8.Union([Type8.String(), Type8.Array(Type8.String())], {
+    description: "Restrict scan/results to paths under this scope (file or directory, absolute or relative to project root). Tier 1 scopes the scan; Tier 2 scans project-wide and applies scope as a result filter."
   })),
-  waitMs: Type8.Optional(Type8.Number({
-    description: "Wait N ms for fresh diagnostics (max 10000, default: 0)"
+  topK: Type8.Optional(Type8.Integer({
+    minimum: 1,
+    maximum: 100,
+    default: 20,
+    description: "Max drill-down items per category. Default 20, max 100."
   }))
 });
-function buildDiagnosticsSections(payload, theme) {
-  const response = asRecord2(payload);
-  if (!response)
-    return [theme.fg("muted", "No diagnostics available.")];
-  const diagnostics = asRecords(response.diagnostics);
-  const total = asNumber(response.total) ?? diagnostics.length;
-  const filesWithErrors = asNumber(response.files_with_errors) ?? distinctCount(diagnostics.filter((diag) => asString(diag.severity) === "error").map((diag) => asString(diag.file)));
-  const filesCount = distinctCount(diagnostics.map((diag) => asString(diag.file)));
-  const sections = [
-    `${theme.fg(total > 0 ? "warning" : "success", `${total} diagnostic${total === 1 ? "" : "s"}`)} ${theme.fg("muted", `across ${filesCount} file${filesCount === 1 ? "" : "s"}, ${filesWithErrors} error file${filesWithErrors === 1 ? "" : "s"}`)}`
-  ];
-  if (diagnostics.length === 0) {
-    sections.push(theme.fg("muted", "No diagnostics found."));
-    return sections;
+var TIER2_INSPECT_CATEGORIES = new Set(["dead_code", "unused_exports", "duplicates"]);
+var INSPECT_TIER2_RUN_TIMEOUT_MS = 5 * 60000;
+var INSPECT_TIER2_MIN_TRIGGER_INTERVAL_MS = 4 * 60000;
+var runningTier2Categories = new WeakMap;
+var lastTier2TriggerAtByBridge = new WeakMap;
+function normalizeStringOrArray(value) {
+  return isEmptyParam(value) ? undefined : value;
+}
+function validateOptionalTopK(value) {
+  if (value === undefined || value === null || value === "")
+    return;
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new Error("topK must be an integer between 1 and 100");
   }
-  const grouped = groupByFile(diagnostics, (diag) => asString(diag.file));
-  for (const [file2, fileDiagnostics] of grouped.entries()) {
-    const lines = [theme.fg("accent", shortenPath(file2))];
-    fileDiagnostics.forEach((diagnostic) => {
-      const severity = asString(diagnostic.severity) ?? "information";
-      const line = asNumber(diagnostic.line) ?? 0;
-      const column = asNumber(diagnostic.column) ?? 0;
-      const code = asString(diagnostic.code);
-      const message = asString(diagnostic.message) ?? "(no message)";
-      const location = `${line}:${column}`;
-      lines.push(`  ${severityBadge(theme, severity)} ${location}${code ? ` ${theme.fg("muted", code)}` : ""} ${message}`);
-    });
-    sections.push(lines.join(`
-`));
+  if (value < 1 || value > 100) {
+    throw new Error("topK must be between 1 and 100");
+  }
+  return value;
+}
+function diagnosticsServerSummary(section) {
+  const pending = Array.isArray(section.servers_pending) ? section.servers_pending.filter((item) => typeof item === "string") : [];
+  const notInstalled = Array.isArray(section.servers_not_installed) ? section.servers_not_installed.filter((item) => typeof item === "string") : [];
+  const parts = [];
+  if (pending.length > 0)
+    parts.push(`pending: ${pending.join(", ")}`);
+  if (notInstalled.length > 0)
+    parts.push(`not installed: ${notInstalled.join(", ")}`);
+  return parts.length > 0 ? parts.join("; ") : "none reported";
+}
+function diagnosticsSummaryPart(summary) {
+  const section = asRecord2(summary?.diagnostics);
+  if (!section)
+    return;
+  const errors3 = asNumber(section.errors);
+  const warnings = asNumber(section.warnings);
+  const info = asNumber(section.info);
+  const hints = asNumber(section.hints);
+  const hasCounts = [errors3, warnings, info, hints].some((value) => value !== undefined);
+  const counts = `${errors3 ?? 0} errors/${warnings ?? 0} warnings/${info ?? 0} info/${hints ?? 0} hints`;
+  const status = asString(section.status);
+  if (status === "pending") {
+    return hasCounts ? `diagnostics ${counts} so far — still pending (servers: ${diagnosticsServerSummary(section)})` : `diagnostics pending (servers: ${diagnosticsServerSummary(section)})`;
+  }
+  if (status === "incomplete") {
+    return hasCounts ? `diagnostics ${counts} (incomplete — servers: ${diagnosticsServerSummary(section)})` : `diagnostics unavailable (status incomplete; servers: ${diagnosticsServerSummary(section)})`;
+  }
+  if (hasCounts) {
+    return `diagnostics ${counts}`;
+  }
+  return;
+}
+function diagnosticLocation(diagnostic) {
+  const file2 = asString(diagnostic.file) ?? "(unknown file)";
+  const line = asNumber(diagnostic.line);
+  const column = asNumber(diagnostic.column);
+  if (line === undefined)
+    return file2;
+  if (column === undefined)
+    return `${file2}:${line}`;
+  return `${file2}:${line}:${column}`;
+}
+function diagnosticsDetailSection(details) {
+  const diagnostics = asRecords(details?.diagnostics);
+  if (diagnostics.length === 0)
+    return;
+  const lines = ["diagnostics"];
+  for (const diagnostic of diagnostics) {
+    const severity = asString(diagnostic.severity) ?? "information";
+    const message = asString(diagnostic.message) ?? "(no message)";
+    const source = asString(diagnostic.source);
+    const suffix = source ? ` [${source}]` : "";
+    lines.push(`- ${diagnosticLocation(diagnostic)} ${severity} ${message}${suffix}`);
+  }
+  return lines.join(`
+`);
+}
+function countFrom(summary, key) {
+  const section = asRecord2(summary?.[key]);
+  return asNumber(section?.count);
+}
+function tier2SummaryPart(summary, key, label) {
+  const section = asRecord2(summary?.[key]);
+  const count = asNumber(section?.count);
+  if (count !== undefined)
+    return `${label} ${count}`;
+  const status = asString(section?.status);
+  return `${label} ${status ?? "unavailable"}`;
+}
+function tier2RefreshCategories(response) {
+  const scannerState = asRecord2(response.scanner_state);
+  const categories = new Set;
+  for (const key of ["pending_categories", "stale_categories"]) {
+    const values = scannerState?.[key];
+    if (!Array.isArray(values))
+      continue;
+    for (const category of values) {
+      if (typeof category === "string" && TIER2_INSPECT_CATEGORIES.has(category)) {
+        categories.add(category);
+      }
+    }
   }
+  return [...categories];
+}
+function runPendingTier2Categories(bridge, categories, extCtx) {
+  const now = Date.now();
+  const running = runningTier2Categories.get(bridge) ?? new Set;
+  const lastTriggerAt = lastTier2TriggerAtByBridge.get(bridge) ?? new Map;
+  const toRun = categories.filter((category) => {
+    if (running.has(category))
+      return false;
+    const previousTriggerAt = lastTriggerAt.get(category);
+    return previousTriggerAt === undefined || previousTriggerAt + INSPECT_TIER2_MIN_TRIGGER_INTERVAL_MS <= now;
+  });
+  if (toRun.length === 0)
+    return;
+  for (const category of toRun) {
+    running.add(category);
+    lastTriggerAt.set(category, now);
+  }
+  runningTier2Categories.set(bridge, running);
+  lastTier2TriggerAtByBridge.set(bridge, lastTriggerAt);
+  callBridge(bridge, "inspect_tier2_run", { categories: toRun }, extCtx, {
+    transportTimeoutMs: INSPECT_TIER2_RUN_TIMEOUT_MS
+  }).catch(() => {}).finally(() => {
+    const active = runningTier2Categories.get(bridge);
+    if (!active)
+      return;
+    for (const category of toRun) {
+      active.delete(category);
+    }
+    if (active.size === 0) {
+      runningTier2Categories.delete(bridge);
+    }
+  });
+}
+function buildInspectSections(payload, theme) {
+  const response = asRecord2(payload);
+  if (!response)
+    return [theme.fg("muted", "No inspect snapshot available.")];
+  const summary = asRecord2(response.summary);
+  const metrics = asRecord2(summary?.metrics);
+  const scannerState = asRecord2(response.scanner_state);
+  const stale = Array.isArray(scannerState?.stale_categories) ? scannerState.stale_categories.length : 0;
+  const pending = Array.isArray(scannerState?.pending_categories) ? scannerState.pending_categories.length : 0;
+  const parts = [
+    `todos ${countFrom(summary, "todos") ?? 0}`,
+    diagnosticsSummaryPart(summary),
+    `metrics ${asNumber(metrics?.files) ?? 0} files/${asNumber(metrics?.symbols) ?? 0} symbols`,
+    tier2SummaryPart(summary, "dead_code", "dead code"),
+    tier2SummaryPart(summary, "unused_exports", "unused exports"),
+    tier2SummaryPart(summary, "duplicates", "duplicates")
+  ].filter((part) => Boolean(part));
+  const sections = [theme.fg("accent", parts.join(" · "))];
+  if (stale > 0 || pending > 0) {
+    sections.push(theme.fg("warning", `scanner state: ${stale} stale · ${pending} pending`));
+  }
+  const details = asRecord2(response.details);
+  if (details) {
+    const names = Object.keys(details);
+    sections.push(names.length > 0 ? `details: ${names.join(", ")}` : theme.fg("muted", "No drill-down details returned."));
+    const diagnosticsDetails = diagnosticsDetailSection(details);
+    if (diagnosticsDetails)
+      sections.push(diagnosticsDetails);
+  }
+  const text = asString(response.text);
+  if (text)
+    sections.push(text);
   return sections;
 }
-function renderDiagnosticsCall(args, theme, context) {
-  const target = args.filePath ?? args.directory;
-  const summary = [
-    target ? accentPath(theme, target) : undefined,
-    args.severity ? theme.fg("toolOutput", args.severity) : undefined
-  ].filter(Boolean).join(" ");
-  return renderToolCall("lsp diagnostics", summary, theme, context);
+function renderInspectCall(args, theme, context) {
+  const sections = Array.isArray(args.sections) ? `${args.sections.length} sections` : args.sections;
+  const scope = Array.isArray(args.scope) ? `${args.scope.length} scopes` : args.scope;
+  const summary = [sections, scope, args.topK ? `topK=${args.topK}` : undefined].filter(Boolean).join(" ");
+  return renderToolCall("inspect", summary ? theme.fg("toolOutput", summary) : undefined, theme, context);
 }
-function renderDiagnosticsResult(result, theme, context) {
+function renderInspectResult(result, theme, context) {
   if (context.isError)
-    return renderErrorResult(result, "lsp diagnostics failed", theme, context);
-  return renderSections(buildDiagnosticsSections(extractStructuredPayload(result), theme), context);
+    return renderErrorResult(result, "inspect failed", theme, context);
+  return renderSections(buildInspectSections(extractStructuredPayload(result), theme), context);
 }
-function registerLspTools(pi, ctx) {
+function registerInspectTool(pi, ctx) {
   pi.registerTool({
-    name: "lsp_diagnostics",
-    label: "lsp diagnostics",
-    description: "On-demand LSP file/scope check. NOT a project-wide type checker — use `tsc --noEmit`, `cargo check`, `pyright` etc. for full coverage.\n\nHonesty: `total: 0` is only clean when `complete: true` AND `lsp_servers_used[].status` includes `pull_ok`. Empty `lsp_servers_used`, or any `binary_not_installed`/`spawn_failed`/`no_root_marker`/`push_only` without diagnostics means the file wasn't actually checked — say so, don't report 'clean'. For per-server breakdown run `npx @cortexkit/aft doctor lsp <filePath>`.",
-    parameters: LspDiagnosticsParams,
+    name: "aft_inspect",
+    label: "inspect",
+    description: "Codebase health snapshot. One call returns summary stats for: TODOs, diagnostics, file/symbol metrics, dead code, unused exports, code duplicates. Pass `sections` for per-category drill-down details.\n\n" + "Categories run in tiers — Tier 1 (todos, metrics) return synchronously from cache. Tier 2 (dead_code, unused_exports, duplicates) run asynchronously on demand: when a call sees cold `pending_categories: [...]` or stale `stale_categories: [...]`, Pi quietly starts a background Tier 2 warmup (deduped while in-flight and rate-limited per category to at most once every 4 minutes, matching OpenCode's default idle window). The current call may still return pending results while the cache warms; a later call can use cached data.\n\n" + `Use when: starting work on unfamiliar code, after multi-edit batches to check diagnostics, before a refactor, before review, or to verify cleanup completeness.
+
+` + "Treat `dead_code` as a hint, not proof: reachability is call-based, so symbols reached only via method dispatch or referenced only in type position may be false positives — verify before deleting.",
+    parameters: InspectParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      const hasFile = typeof params.filePath === "string" && params.filePath.length > 0;
-      const hasDir = typeof params.directory === "string" && params.directory.length > 0;
-      if (hasFile && hasDir) {
-        throw new Error("'filePath' and 'directory' are mutually exclusive — provide one or neither");
-      }
       const bridge = bridgeFor(ctx, extCtx.cwd);
-      const req = {};
-      if (hasFile)
-        req.file = params.filePath;
-      if (hasDir)
-        req.directory = params.directory;
-      if (params.severity !== undefined)
-        req.severity = params.severity;
-      if (params.waitMs !== undefined)
-        req.wait_ms = params.waitMs;
-      const response = await callBridge(bridge, "lsp_diagnostics", req, extCtx);
-      return textResult(JSON.stringify(response, null, 2));
+      const sections = normalizeStringOrArray(params.sections);
+      const scope = normalizeStringOrArray(params.scope);
+      const topK = validateOptionalTopK(params.topK);
+      const response = await callBridge(bridge, "inspect", { sections, scope, topK }, extCtx);
+      runPendingTier2Categories(bridge, tier2RefreshCategories(response), extCtx);
+      return textResult(response.text ?? JSON.stringify(response, null, 2), response);
     },
     renderCall(args, theme, context) {
-      return renderDiagnosticsCall(args, theme, context);
+      return renderInspectCall(args, theme, context);
     },
     renderResult(result, _options, theme, context) {
-      return renderDiagnosticsResult(result, theme, context);
+      return renderInspectResult(result, theme, context);
     }
   });
 }
 
 // src/tools/navigate.ts
-import { StringEnum as StringEnum4 } from "@earendil-works/pi-ai";
+import { StringEnum as StringEnum3 } from "@earendil-works/pi-ai";
 import { Type as Type9 } from "typebox";
 function navigateParamsSchema() {
   return Type9.Object({
-    op: StringEnum4(["call_tree", "callers", "trace_to", "trace_to_symbol", "impact", "trace_data"], {
+    op: StringEnum3(["call_tree", "callers", "trace_to", "trace_to_symbol", "impact", "trace_data"], {
       description: "Navigation operation"
     }),
     filePath: Type9.String({
@@ -33309,7 +33603,7 @@ function renderNavigateCall(args, theme, context) {
     theme.fg("toolOutput", args.symbol),
     args.toSymbol ? theme.fg("toolOutput", `→ ${args.toSymbol}`) : undefined
   ].filter(Boolean).join(" ");
-  return renderToolCall("navigate", summary, theme, context);
+  return renderToolCall("callgraph", summary, theme, context);
 }
 function renderNavigateResult(result, args, theme, context) {
   if (context.isError)
@@ -33318,9 +33612,9 @@ function renderNavigateResult(result, args, theme, context) {
 }
 function registerNavigateTool(pi, ctx) {
   pi.registerTool({
-    name: "aft_navigate",
-    label: "navigate",
-    description: "Navigate code structure across files using call graph analysis. All ops require both `filePath` and `symbol`. Use `call_tree` for what a function calls, `callers` for call sites, `trace_to` for entry points, `trace_to_symbol` for a path from one symbol to another (requires `toSymbol`; if ambiguous, the error returns candidate files — retry with `toFile`), `impact` for blast radius, `trace_data` to follow a value.",
+    name: "aft_callgraph",
+    label: "callgraph",
+    description: "Answer code-relationship questions from a real call graph — instead of grep + read chains. Reach for this whenever the question is about how symbols connect. All ops require both `filePath` and `symbol`. Use `callers` for call sites (before renaming/signature changes), `impact` for blast radius (what breaks if a symbol changes), `call_tree` for what a function calls, `trace_to` for how execution reaches a symbol from entry points, `trace_to_symbol` for the shortest path from one symbol to another (requires `toSymbol`; if ambiguous, the error returns candidate files — retry with `toFile`), `trace_data` to follow a value across assignments/params.",
     parameters: navigateParamsSchema(),
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
       if (params.op === "trace_data" && !params.expression) {
@@ -33582,10 +33876,26 @@ Pass a single \`target\`:
       parameters: ZoomParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
-        const hasFilePath = typeof params.filePath === "string" && params.filePath.length > 0;
-        const hasUrl = typeof params.url === "string" && params.url.length > 0;
-        const hasTargets = params.targets !== undefined && params.targets !== null;
-        const hasSymbols = params.symbols !== undefined && params.symbols !== null && (typeof params.symbols === "string" ? params.symbols.length > 0 : Array.isArray(params.symbols) && params.symbols.length > 0);
+        const hasTargetsProvided = (t) => {
+          if (isEmptyParam(t))
+            return false;
+          const entryEmpty = (entry) => {
+            if (!entry || typeof entry !== "object")
+              return true;
+            const fp = entry.filePath;
+            const sym = entry.symbol;
+            const fpEmpty = typeof fp !== "string" || fp.length === 0;
+            const symEmpty = typeof sym !== "string" || sym.length === 0;
+            return fpEmpty && symEmpty;
+          };
+          if (Array.isArray(t))
+            return !t.every(entryEmpty);
+          return !entryEmpty(t);
+        };
+        const hasFilePath = !isEmptyParam(params.filePath);
+        const hasUrl = !isEmptyParam(params.url);
+        const hasTargets = hasTargetsProvided(params.targets);
+        const hasSymbols = !isEmptyParam(params.symbols);
         if (hasTargets) {
           if (hasFilePath || hasUrl || hasSymbols) {
             throw new Error("'targets' is mutually exclusive with 'filePath', 'url', and 'symbols'");
@@ -33738,10 +34048,10 @@ function formatOutlineFilesText(response) {
 }
 
 // src/tools/refactor.ts
-import { StringEnum as StringEnum5 } from "@earendil-works/pi-ai";
+import { StringEnum as StringEnum4 } from "@earendil-works/pi-ai";
 import { Type as Type11 } from "typebox";
 var RefactorParams = Type11.Object({
-  op: StringEnum5(["move", "extract", "inline"], { description: "Refactoring operation" }),
+  op: StringEnum4(["move", "extract", "inline"], { description: "Refactoring operation" }),
   filePath: Type11.String({
     description: "Source file (absolute or relative to project root)"
   }),
@@ -33808,14 +34118,23 @@ function registerRefactorTool(pi, ctx) {
         extract: "extract_function",
         inline: "inline_symbol"
       };
+      if ((params.op === "move" || params.op === "inline") && isEmptyParam(params.symbol)) {
+        throw new Error(`'symbol' is required for '${params.op}' op`);
+      }
+      if (params.op === "move" && isEmptyParam(params.destination)) {
+        throw new Error("'destination' is required for 'move' op");
+      }
+      if (params.op === "extract" && isEmptyParam(params.name)) {
+        throw new Error("'name' is required for 'extract' op");
+      }
       const req = { file: params.filePath };
-      if (params.symbol !== undefined)
+      if (!isEmptyParam(params.symbol))
         req.symbol = params.symbol;
-      if (params.destination !== undefined)
+      if (!isEmptyParam(params.destination))
         req.destination = params.destination;
-      if (params.scope !== undefined)
+      if (!isEmptyParam(params.scope))
         req.scope = params.scope;
-      if (params.name !== undefined)
+      if (!isEmptyParam(params.name))
         req.name = params.name;
       const startLine = coerceOptionalInt(params.startLine, "startLine", 1, Number.MAX_SAFE_INTEGER);
       const endLine = coerceOptionalInt(params.endLine, "endLine", 1, Number.MAX_SAFE_INTEGER);
@@ -33840,10 +34159,10 @@ function registerRefactorTool(pi, ctx) {
 }
 
 // src/tools/safety.ts
-import { StringEnum as StringEnum6 } from "@earendil-works/pi-ai";
+import { StringEnum as StringEnum5 } from "@earendil-works/pi-ai";
 import { Type as Type12 } from "typebox";
 var SafetyParams = Type12.Object({
-  op: StringEnum6(["undo", "history", "checkpoint", "restore", "list"], {
+  op: StringEnum5(["undo", "history", "checkpoint", "restore", "list"], {
     description: "Safety operation"
   }),
   filePath: Type12.Optional(Type12.String({
@@ -33982,35 +34301,81 @@ function registerSafetyTool(pi, ctx) {
 
 // src/tools/semantic.ts
 import { Type as Type13 } from "typebox";
+function semanticHonestyNote(response, theme) {
+  const notes = [];
+  if (response.more_available === true)
+    notes.push("more results available");
+  if (response.engine_capped === true)
+    notes.push("enumeration capped");
+  if (response.fully_degraded === true)
+    notes.push("fully degraded");
+  if (response.complete === false)
+    notes.push("partial/incomplete");
+  return notes.length > 0 ? theme.fg("warning", `Search status: ${notes.join("; ")}.`) : undefined;
+}
 var SearchParams2 = Type13.Object({
   query: Type13.String({
-    description: "Concept or capability to find, phrased as a programmer would describe the code. Examples: 'fuzzy match with whitespace tolerance', 'undo backup before edit', 'retry failed network request'."
+    description: "Concept, regex, literal text, filename, or capability to find. Examples: 'fuzzy match with whitespace tolerance', '^export', 'Cargo.lock'."
   }),
-  topK: Type13.Optional(Type13.Number({ description: "Maximum number of results (default: 10, max: 100)" }))
+  topK: Type13.Optional(Type13.Integer({
+    minimum: 1,
+    maximum: 100,
+    default: 10,
+    description: "Maximum number of results (default: 10, max: 100)"
+  })),
+  hint: Type13.Optional(Type13.Union([
+    Type13.Literal("regex"),
+    Type13.Literal("literal"),
+    Type13.Literal("semantic"),
+    Type13.Literal("auto")
+  ], {
+    description: "Optional routing hint. Defaults to 'auto'."
+  }))
 });
 function buildSemanticSections(args, payload, theme) {
   const response = asRecord2(payload);
   if (!response)
-    return [theme.fg("muted", "No semantic search result.")];
+    return [theme.fg("muted", "No search result.")];
   const status = asString(response.status) ?? "unknown";
+  const semanticStatus = asString(response.semantic_status) ?? status;
+  const interpretedAs = asString(response.interpreted_as) ?? "unknown";
+  const queryKind = asString(response.query_kind);
   const sections = [
-    `${theme.fg(status === "ready" ? "success" : "warning", `index: ${status}`)} ${theme.fg("muted", `query=${JSON.stringify(args.query)} topK=${args.topK ?? 10}`)}`
+    `${theme.fg(semanticStatus === "ready" ? "success" : "warning", `semantic: ${semanticStatus}`)} ${theme.fg("muted", `mode=${interpretedAs}${queryKind ? ` kind=${queryKind}` : ""} query=${JSON.stringify(args.query)} topK=${args.topK ?? 10}`)}`
   ];
-  if (status !== "ready") {
+  const warnings = Array.isArray(response.warnings) ? response.warnings.filter((warning) => typeof warning === "string") : [];
+  if (warnings.length > 0) {
+    sections.push(warnings.map((warning) => theme.fg("warning", `⚠ ${warning}`)).join(`
+`));
+  }
+  const honestyNote = semanticHonestyNote(response, theme);
+  if (honestyNote)
+    sections.push(honestyNote);
+  const results = asRecords(response.results);
+  if (status !== "ready" && results.length === 0) {
     sections.push(asString(response.text) ?? theme.fg("muted", "Semantic index is not ready."));
     return sections;
   }
-  const results = asRecords(response.results);
   if (results.length === 0) {
-    sections.push(theme.fg("muted", "No semantic matches found."));
+    sections.push(theme.fg("muted", "No matches found."));
     return sections;
   }
   const grouped = groupByFile(results, (result) => asString(result.file));
   for (const [file2, fileResults] of grouped.entries()) {
     const lines = [theme.fg("accent", shortenPath(file2))];
     fileResults.forEach((result) => {
+      if (asString(result.kind) === "GrepLine") {
+        const line = asNumber(result.line);
+        const column = asNumber(result.column);
+        const lineText = asString(result.line_text) ?? "";
+        const location2 = line !== undefined ? `${line}${column !== undefined ? `:${column}` : ""}` : "?";
+        lines.push(`  ↳ ${theme.fg("muted", `line ${location2}`)} ${lineText}`);
+        return;
+      }
       const score = asNumber(result.score);
       const source = asString(result.source);
+      const kind = asString(result.kind) ?? "symbol";
+      const location = asString(result.location);
       if (source === "lexical") {
         lines.push(`  ↳ ${theme.fg("muted", `[lexical match${score !== undefined ? ` — score ${score.toFixed(3)}` : ""}]`)}`);
         const snippet2 = asString(result.snippet);
@@ -34020,10 +34385,14 @@ function buildSemanticSections(args, payload, theme) {
         }
         return;
       }
+      if (kind === "file_summary" || location === "[file summary]") {
+        const summary = asString(result.snippet) ?? asString(result.name) ?? "(no summary)";
+        lines.push(`  ↳ ${summary} ${theme.fg("muted", `[file summary${score !== undefined ? ` score ${score.toFixed(3)}` : ""}]`)}`);
+        return;
+      }
       const startLine = asNumber(result.start_line);
       const endLine = asNumber(result.end_line);
       const range = startLine !== undefined ? `${startLine}${endLine && endLine !== startLine ? `-${endLine}` : ""}` : "?";
-      const kind = asString(result.kind) ?? "symbol";
       const name = asString(result.name) ?? "(unknown)";
       lines.push(`  ↳ ${name} ${theme.fg("muted", `[${kind}] lines ${range}${score !== undefined ? ` score ${score.toFixed(3)}` : ""}`)}`);
       const snippet = asString(result.snippet);
@@ -34038,43 +34407,48 @@ function buildSemanticSections(args, payload, theme) {
   return sections;
 }
 function renderSemanticCall(args, theme, context) {
-  return renderToolCall("semantic search", theme.fg("toolOutput", args.query), theme, context);
+  return renderToolCall("search", theme.fg("toolOutput", args.query), theme, context);
 }
 function renderSemanticResult(result, args, theme, context) {
   if (context.isError)
-    return renderErrorResult(result, "semantic search failed", theme, context);
+    return renderErrorResult(result, "search failed", theme, context);
   return renderSections(buildSemanticSections(args, extractStructuredPayload(result), theme), context);
 }
 function registerSemanticTool(pi, ctx) {
   pi.registerTool({
     name: "aft_search",
-    label: "semantic search",
+    label: "search",
     description: [
-      "Find symbols by concept using hybrid semantic + lexical search. Returns ranked code matches with similarity scores and provenance tags.",
+      "Find code with unified semantic, lexical, literal, and regex search. Returns ranked symbol/file results or exact matching lines, with routing metadata.",
       "",
       "When to reach for it:",
       "- Exploring an unfamiliar area: 'where is rate limiting handled', 'how does auth flow work'",
       "- Concept doesn't appear as a literal string: 'retry logic', 'cache invalidation', 'graceful shutdown'",
       "- Filename-shaped concepts: 'the bridge spawn helper', 'the session detection module'",
-      "- After 2+ grep attempts that came back empty or noisy",
+      "- Regex-shaped or exact text queries when you want AFT to classify and route automatically",
       "- You know roughly what the function does but not what it's named",
       "",
       "When NOT to use:",
-      "- You have an error message or stack trace → use grep",
+      "- You need exhaustive literal enumeration → use grep directly",
       "- You want the file/module structure → use aft_outline",
-      "- You're following a call chain → use aft_navigate",
+      "- You're following a call chain → use aft_callgraph",
       "",
-      "Each result tags `source` as one of: 'semantic' (embedding match only), 'lexical' (trigram exact-token match the embedding lane missed), or 'hybrid' (both lanes agreed — strongest signal)."
+      "Set hint to 'regex', 'literal', 'semantic', or 'auto' to override or document routing intent."
     ].join(`
 `),
     parameters: SearchParams2,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+      if (isEmptyParam(params.query) || typeof params.query !== "string" || params.query.trim().length === 0) {
+        throw new Error("semantic_search: invalid params: `query` must be a non-empty string");
+      }
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const req = { query: params.query };
       if (params.topK !== undefined)
         req.top_k = params.topK;
+      if (params.hint !== undefined)
+        req.hint = params.hint;
       const response = await callBridge(bridge, "semantic_search", req, extCtx);
-      return textResult(response.text ?? JSON.stringify(response, null, 2));
+      return textResult(response.text ?? JSON.stringify(response, null, 2), response);
     },
     renderCall(args, theme, context) {
       return renderSemanticCall(args, theme, context);
@@ -34086,10 +34460,10 @@ function registerSemanticTool(pi, ctx) {
 }
 
 // src/tools/structure.ts
-import { StringEnum as StringEnum7 } from "@earendil-works/pi-ai";
+import { StringEnum as StringEnum6 } from "@earendil-works/pi-ai";
 import { Type as Type14 } from "typebox";
 var TransformParams = Type14.Object({
-  op: StringEnum7(["add_member", "add_derive", "wrap_try_catch", "add_decorator", "add_struct_tags"], { description: "Transformation operation" }),
+  op: StringEnum6(["add_member", "add_derive", "wrap_try_catch", "add_decorator", "add_struct_tags"], { description: "Transformation operation" }),
   filePath: Type14.String({
     description: "Path to the source file (absolute or relative to project root)"
   }),
@@ -34105,7 +34479,7 @@ var TransformParams = Type14.Object({
   position: Type14.Optional(Type14.String({
     description: "Position hint: 'first', 'last' (default), 'before:name', 'after:name' for add_member"
   })),
-  validate: Type14.Optional(StringEnum7(["syntax", "full"], {
+  validate: Type14.Optional(StringEnum6(["syntax", "full"], {
     description: "Validation level (default: syntax)"
   }))
 });
@@ -34221,18 +34595,26 @@ function buildWorkflowHints(opts) {
   const hasZoom = !opts.absentTools.has("aft_zoom");
   const hasGrep = opts.toolSurface !== "minimal" && !opts.absentTools.has(grepName);
   const hasSearch = opts.toolSurface !== "minimal" && opts.semanticEnabled && !opts.absentTools.has("aft_search");
-  const hasNavigate = opts.toolSurface === "all" && !opts.absentTools.has("aft_navigate");
+  const hasNavigate = opts.toolSurface === "all" && !opts.absentTools.has("aft_callgraph");
+  const hasInspect = opts.toolSurface !== "minimal" && !opts.absentTools.has("aft_inspect");
   const hasBgBash = opts.bashBackgroundEnabled && !opts.absentTools.has(bashName) && !opts.absentTools.has("bash_status");
   if (hasOutline && hasZoom) {
     sections.push(`**Web/URL access**: \`aft_outline({ target: "<url>" })\` first for structure, then \`aft_zoom({ url: "<url>", symbols: "<heading>" })\` for the specific section.`);
   }
   if (hasOutline && hasZoom && (hasGrep || hasSearch)) {
-    const locator = hasGrep ? `\`${grepName}\`` : "`aft_search`";
-    sections.push(hasGrep && hasSearch ? `**Code exploration**: For exact identifiers (\`useState\`, function names, env vars), error messages, or path-shaped queries → \`${grepName}\` first. For broad concepts ('where is X handled', 'how does Y work') → \`aft_search\`. Then use \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).` : `**Code exploration**: ${locator} to locate → \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).`);
+    if (hasSearch) {
+      const grepFallback = hasGrep ? ` Use \`${grepName}\` directly only when you need exhaustive enumeration of literal text (every TODO, every import of X) without ranking.` : "";
+      sections.push(`**Code exploration**: \`aft_search\` is the primary code-search tool. It auto-routes by query shape — exact identifiers, regex, error messages, natural language all use the same call. Very short queries fall back to literal scans; pass \`hint: "regex"\` / \`hint: "literal"\` / \`hint: "semantic"\` to override routing if needed. Then \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).${grepFallback}`);
+    } else {
+      sections.push(`**Code exploration**: \`${grepName}\` to locate → \`aft_outline\` for structure → \`aft_zoom\` for symbol(s).`);
+    }
+  }
+  if (hasInspect) {
+    sections.push("**Codebase health & diagnostics**: AFT does not surface compile/type errors automatically after edits — pull them with `aft_inspect`. Run it after a batch of edits and before you run tests or commit, when starting in unfamiliar code, or before a refactor/review. One call summarizes diagnostics (compile/type errors), TODOs, metrics, dead code, unused exports, and duplicates; pass `sections` for focused drill-down and `scope` to actively pull diagnostics for a specific file or directory. Its diagnostics are a fast checkpoint, not the authority — a clean `tsc` / `cargo check` / `pyright` run is the real gate. Treat `stale_categories` as a genuine stale-cache signal while an async Tier 2 refresh catches up.");
   }
   if (hasNavigate) {
     sections.push([
-      "Use `aft_navigate` instead of grep + read chains for relationship questions:",
+      "Use `aft_callgraph` for code-relationship questions instead of grep + read chains:",
       "- `callers` — find all call sites before changing a function signature",
       "- `impact` — blast radius (which functions/files will need updates)",
       "- `trace_to` — how execution reaches this code from entry points (routes, exports, main)",
@@ -34272,7 +34654,9 @@ function registerWorkflowHints(pi, config2, surface) {
   if (!surface.semantic)
     absent.add("aft_search");
   if (!surface.navigate)
-    absent.add("aft_navigate");
+    absent.add("aft_callgraph");
+  if (!surface.inspect)
+    absent.add("aft_inspect");
   if (!surface.hoistGrep)
     absent.add("grep");
   if (!surface.hoistBash) {
@@ -34336,17 +34720,17 @@ var PLUGIN_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var ANNOUNCEMENT_VERSION = "0.31.0";
+var ANNOUNCEMENT_VERSION = "0.33.0";
 var ANNOUNCEMENT_FEATURES = [
-  "`aft_navigate` has a new `trace_to_symbol` op for path-between-symbols queries. One call returns the shortest call path from one function to another with file + line for every hop. Honest errors for ambiguous, missing, or unreachable targets — including a candidate list to disambiguate.",
-  '`aft_outline target: "<dir>", files: true` returns an indexed file tree with language, symbol count, and byte size per file. Lets agents pick which files to actually open without first reading symbol bodies. Honest truncation (`complete: false` + `walk_truncated`/`unchecked_files`) when the directory exceeds the walk cap.',
-  '`aft_zoom` adds `targets` for cross-file batches — pull bodies from different files in one call. Schema breaking change: `symbol` is removed; pass `symbols: "name"` (string) or `symbols: ["a", "b"]` (array). Same shape works for `url` mode so you can grab multiple sections from one URL fetch.',
-  "Pi `grep`/`write`/`edit` no longer hang on external paths. The plugin used to nag with an `Allow external directory access?` prompt even under the Pi default (`restrict_to_project_root: false`) which explicitly opts into no restriction. The plugin now defers to Rust without prompting in that case, expands `~/...` paths correctly, and bounds the prompt with a 30s timeout when strict mode is enabled.",
-  "Tool descriptions trimmed: ~1.2K agent-facing tokens removed by dropping redundant `Returns:` blocks and compressing `lsp_diagnostics` while preserving its load-bearing honesty guidance."
+  "New `aft_inspect` — one call for codebase health: diagnostics, metrics, TODOs, dead code, unused exports, and duplicates.",
+  "Diagnostics now flow through `aft_inspect` (run it after a batch of edits) instead of arriving automatically on every edit.",
+  "`aft_navigate` is renamed to `aft_callgraph`; the Rust call graph now resolves cross-file callers.",
+  "Edits no longer echo the whole file back to the agent — much lower token cost per edit.",
+  "Batch of `aft_search` correctness fixes and undo-history/SSRF/Windows hardening."
 ];
 var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/F2uWxjGnU";
 var ALL_ONLY_TOOLS = new Set([
-  "aft_navigate",
+  "aft_callgraph",
   "aft_delete",
   "aft_move",
   "aft_transform",
@@ -34420,6 +34804,7 @@ function resolveToolSurface(config2) {
       outline: ok("aft_outline"),
       zoom: ok("aft_zoom"),
       semantic: false,
+      inspect: false,
       navigate: false,
       conflicts: false,
       importTool: false,
@@ -34428,7 +34813,6 @@ function resolveToolSurface(config2) {
       move: false,
       astSearch: false,
       astReplace: false,
-      lspDiagnostics: false,
       structure: false,
       refactor: false
     };
@@ -34443,6 +34827,7 @@ function resolveToolSurface(config2) {
     outline: ok("aft_outline"),
     zoom: ok("aft_zoom"),
     semantic: ok("aft_search") && config2.semantic_search === true,
+    inspect: ok("aft_inspect") && config2.inspect?.enabled !== false,
     navigate: false,
     conflicts: ok("aft_conflicts"),
     importTool: ok("aft_import"),
@@ -34451,14 +34836,13 @@ function resolveToolSurface(config2) {
     move: false,
     astSearch: ok("ast_grep_search"),
     astReplace: ok("ast_grep_replace"),
-    lspDiagnostics: ok("lsp_diagnostics"),
     structure: false,
     refactor: false
   };
   if (surface === "all") {
     return {
       ...base,
-      navigate: allOnly("aft_navigate"),
+      navigate: allOnly("aft_callgraph"),
       delete: allOnly("aft_delete"),
       move: allOnly("aft_move"),
       structure: allOnly("aft_transform"),
@@ -34506,6 +34890,8 @@ async function src_default(pi) {
   Object.assign(configOverrides, resolveLspConfigForConfigure(config2));
   if (config2.semantic !== undefined)
     configOverrides.semantic = config2.semantic;
+  if (config2.inspect !== undefined)
+    configOverrides.inspect = config2.inspect;
   if (config2.max_callgraph_files !== undefined)
     configOverrides.max_callgraph_files = config2.max_callgraph_files;
   if (config2.url_fetch_allow_private !== undefined)
@@ -34673,6 +35059,9 @@ ${lines}
   if (surface.semantic) {
     registerSemanticTool(pi, ctx);
   }
+  if (surface.inspect) {
+    registerInspectTool(pi, ctx);
+  }
   if (surface.navigate) {
     registerNavigateTool(pi, ctx);
   }
@@ -34691,9 +35080,6 @@ ${lines}
   if (surface.delete || surface.move) {
     registerFsTools(pi, ctx, surface);
   }
-  if (surface.lspDiagnostics) {
-    registerLspTools(pi, ctx);
-  }
   if (surface.structure) {
     registerStructureTool(pi, ctx);
   }