@cortexkit/aft-pi 0.36.0 → 0.37.0

package/dist/index.js

@@ -11678,6 +11678,9 @@ function error(message, meta) {
 var CONFLICT_HINT = `
 
 [Hint] Use aft_conflicts to see all conflict regions across files in a single call.`;
+var GREP_SEARCH_AFT_SEARCH_HINT = "DO NOT search code by running grep/rg in bash — it is unindexed, unranked, and serial. Use the `aft_search` tool instead (it auto-routes concepts, identifiers, regex, and literals).";
+var GREP_SEARCH_GREP_HINT = "DO NOT search code by running grep/rg in bash — it is unindexed, unranked, and serial. Use the `grep` tool instead (indexed and ranked).";
+var GREP_SEARCH_HINT_PREFIX = "DO NOT search code by running grep/rg in bash —";
 function maybeAppendConflictsHint(output) {
   if (!output.includes("Automatic merge failed; fix conflicts"))
     return output;
@@ -11685,6 +11688,146 @@ function maybeAppendConflictsHint(output) {
     return output;
   return output + CONFLICT_HINT;
 }
+function commandLeadsWithCodeSearch(command) {
+  const trimmed = command.trim();
+  if (!trimmed)
+    return false;
+  const afterCd = peelLeadingCdAnd(trimmed);
+  if (afterCd === null)
+    return false;
+  const firstStage = firstPipelineStage(afterCd);
+  if (firstStage === null)
+    return false;
+  const firstToken = readShellToken(firstStage, skipSpaces(firstStage, 0));
+  if (firstToken === null)
+    return false;
+  return firstToken.token === "grep" || firstToken.token === "rg";
+}
+function maybeAppendGrepSearchHint(output, command, aftSearchRegistered) {
+  if (output === "")
+    return output;
+  if (!commandLeadsWithCodeSearch(command))
+    return output;
+  if (output.includes(GREP_SEARCH_HINT_PREFIX))
+    return output;
+  const hint = aftSearchRegistered ? GREP_SEARCH_AFT_SEARCH_HINT : GREP_SEARCH_GREP_HINT;
+  return `${output}
+
+${hint}`;
+}
+function peelLeadingCdAnd(command) {
+  const first = readShellToken(command, skipSpaces(command, 0));
+  if (first === null)
+    return null;
+  if (first.token !== "cd")
+    return command;
+  const dir = readShellToken(command, skipSpaces(command, first.end));
+  if (dir === null)
+    return null;
+  if (!dir.token)
+    return command;
+  const afterDir = skipSpaces(command, dir.end);
+  if (!command.startsWith("&&", afterDir))
+    return command;
+  return command.slice(afterDir + 2).trim();
+}
+function firstPipelineStage(command) {
+  let quote = "none";
+  let firstPipeIndex;
+  for (let index = 0;index < command.length; index++) {
+    const ch = command[index];
+    if (quote === "single") {
+      if (ch === "'")
+        quote = "none";
+      continue;
+    }
+    if (quote === "double") {
+      if (ch === '"') {
+        quote = "none";
+      } else if (ch === "\\") {
+        index++;
+      } else if (ch === "`") {
+        return null;
+      }
+      continue;
+    }
+    if (ch === "'") {
+      quote = "single";
+    } else if (ch === '"') {
+      quote = "double";
+    } else if (ch === "\\") {
+      index++;
+    } else if (ch === "`") {
+      return null;
+    } else if (ch === "|") {
+      if (command[index + 1] === "|") {
+        index++;
+      } else if (firstPipeIndex === undefined) {
+        firstPipeIndex = index;
+      }
+    }
+  }
+  if (quote !== "none")
+    return null;
+  return command.slice(0, firstPipeIndex ?? command.length).trim();
+}
+function readShellToken(command, start) {
+  let quote = "none";
+  let token = "";
+  let index = start;
+  for (;index < command.length; index++) {
+    const ch = command[index];
+    if (quote === "single") {
+      if (ch === "'") {
+        quote = "none";
+      } else {
+        token += ch;
+      }
+      continue;
+    }
+    if (quote === "double") {
+      if (ch === '"') {
+        quote = "none";
+      } else if (ch === "\\") {
+        index++;
+        token += command[index] ?? "\\";
+      } else if (ch === "`") {
+        return null;
+      } else {
+        token += ch;
+      }
+      continue;
+    }
+    if (/\s/.test(ch))
+      break;
+    if (isTokenBoundary(ch))
+      break;
+    if (ch === "'") {
+      quote = "single";
+    } else if (ch === '"') {
+      quote = "double";
+    } else if (ch === "\\") {
+      index++;
+      token += command[index] ?? "\\";
+    } else if (ch === "`") {
+      return null;
+    } else {
+      token += ch;
+    }
+  }
+  if (quote !== "none")
+    return null;
+  return { token, end: index };
+}
+function isTokenBoundary(ch) {
+  return ch === "|" || ch === ";" || ch === "&" || ch === "<" || ch === ">";
+}
+function skipSpaces(input, start) {
+  let index = start;
+  while (index < input.length && /\s/.test(input[index]))
+    index++;
+  return index;
+}
 // ../aft-bridge/dist/bash-timeout.js
 function resolveBashKillTimeout(modelTimeout, foregroundWaitMs) {
   if (modelTimeout !== undefined && modelTimeout >= foregroundWaitMs) {
@@ -11698,6 +11841,21 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 
+// ../aft-bridge/dist/command-timeouts.js
+var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
+  callers: 60000,
+  trace_to: 60000,
+  trace_to_symbol: 60000,
+  trace_data: 60000,
+  impact: 60000,
+  grep: 60000,
+  glob: 60000,
+  semantic_search: 60000
+};
+function timeoutForCommand(command) {
+  return LONG_RUNNING_COMMAND_TIMEOUT_MS[command];
+}
+
 // ../aft-bridge/dist/status-bar.js
 var STATUS_BAR_HEARTBEAT_CALLS = 15;
 function createStatusBarEmitState() {
@@ -11745,6 +11903,27 @@ 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;
+var STDOUT_BUFFER_COMPACT_THRESHOLD = 64 * 1024;
+var TERMINAL_BASH_STATUSES = new Set([
+  "completed",
+  "failed",
+  "killed",
+  "timed_out",
+  "cancelled",
+  "timeout"
+]);
+function isTerminalBashStatus(status) {
+  return typeof status === "string" && TERMINAL_BASH_STATUSES.has(status);
+}
+function bashTaskIdFrom(response) {
+  const snakeCase = response.task_id;
+  if (typeof snakeCase === "string" && snakeCase.length > 0)
+    return snakeCase;
+  const camelCase = response.taskId;
+  if (typeof camelCase === "string" && camelCase.length > 0)
+    return camelCase;
+  return;
+}
 function tagStderrLine(line) {
   return /^\[aft(-\w+)?\] /.test(line) ? line : `[aft] ${line}`;
 }
@@ -11799,11 +11978,12 @@ function clampSemanticTimeout(configOverrides, bridgeTimeoutMs) {
   if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
     return configOverrides;
   }
-  const maxSemanticTimeoutMs = bridgeTimeoutMs > SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS ? bridgeTimeoutMs - SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS : Math.max(1, bridgeTimeoutMs - 1);
+  const semanticTransportBudgetMs = Math.max(bridgeTimeoutMs, LONG_RUNNING_COMMAND_TIMEOUT_MS.semantic_search ?? 0);
+  const maxSemanticTimeoutMs = semanticTransportBudgetMs > SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS ? semanticTransportBudgetMs - SEMANTIC_TIMEOUT_SAFETY_MARGIN_MS : Math.max(1, semanticTransportBudgetMs - 1);
   if (timeoutMs <= maxSemanticTimeoutMs) {
     return configOverrides;
   }
-  warn(`semantic.timeout_ms=${timeoutMs} exceeds bridge timeout budget; clamping to ${maxSemanticTimeoutMs}ms (bridge timeout: ${bridgeTimeoutMs}ms)`);
+  warn(`semantic.timeout_ms=${timeoutMs} exceeds the semantic transport budget; clamping to ${maxSemanticTimeoutMs}ms (budget: ${semanticTransportBudgetMs}ms)`);
   return {
     ...configOverrides,
     semantic: {
@@ -11829,8 +12009,10 @@ class BinaryBridge {
   cwd;
   process = null;
   pending = new Map;
+  outstandingBackgroundTaskIds = new Set;
   nextId = 1;
   stdoutBuffer = "";
+  stdoutReadOffset = 0;
   stderrBuffer = "";
   stderrTail = [];
   _restartCount = 0;
@@ -11940,6 +12122,9 @@ class BinaryBridge {
   hasPendingRequests() {
     return this.pending.size > 0;
   }
+  hasOutstandingBackgroundTasks() {
+    return this.outstandingBackgroundTaskIds.size > 0;
+  }
   getCwd() {
     return this.cwd;
   }
@@ -12061,7 +12246,7 @@ class BinaryBridge {
           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 });
+        this.pending.set(id, { resolve, reject, timer, onProgress: options?.onProgress, command });
         if (!this.process?.stdin?.writable) {
           this.pending.delete(id);
           clearTimeout(timer);
@@ -12322,6 +12507,7 @@ class BinaryBridge {
     });
     this.process = child;
     this.stdoutBuffer = "";
+    this.stdoutReadOffset = 0;
     this.stderrBuffer = "";
     this.lastChildActivityAt = 0;
     this.consecutiveRequestTimeouts = 0;
@@ -12366,24 +12552,41 @@ class BinaryBridge {
   ${tail}`;
   }
   onStdoutData(data) {
+    if (this.stdoutReadOffset > STDOUT_BUFFER_COMPACT_THRESHOLD) {
+      this.compactStdoutBuffer();
+    }
     this.stdoutBuffer += data;
-    if (this.stdoutBuffer.length > MAX_STDOUT_BUFFER) {
+    if (this.stdoutBuffer.length - this.stdoutReadOffset > MAX_STDOUT_BUFFER) {
       this.handleCrash(new Error(`aft bridge stdout buffer exceeded ${MAX_STDOUT_BUFFER} bytes — killing bridge`));
       return;
     }
     let newlineIdx;
     while ((newlineIdx = this.stdoutBuffer.indexOf(`
-`)) !== -1) {
-      const line = this.stdoutBuffer.slice(0, newlineIdx).trim();
-      this.stdoutBuffer = this.stdoutBuffer.slice(newlineIdx + 1);
-      if (!line)
-        continue;
-      this.processStdoutLine(line);
+`, this.stdoutReadOffset)) !== -1) {
+      const line = this.stdoutBuffer.slice(this.stdoutReadOffset, newlineIdx).trim();
+      this.stdoutReadOffset = newlineIdx + 1;
+      if (line) {
+        this.processStdoutLine(line);
+      }
+      if (this.stdoutReadOffset > STDOUT_BUFFER_COMPACT_THRESHOLD && this.stdoutReadOffset > this.stdoutBuffer.length / 2) {
+        this.compactStdoutBuffer();
+      }
+    }
+    if (this.stdoutReadOffset === this.stdoutBuffer.length) {
+      this.stdoutBuffer = "";
+      this.stdoutReadOffset = 0;
     }
   }
+  compactStdoutBuffer() {
+    if (this.stdoutReadOffset === 0)
+      return;
+    this.stdoutBuffer = this.stdoutBuffer.slice(this.stdoutReadOffset);
+    this.stdoutReadOffset = 0;
+  }
   flushStdoutBuffer() {
-    const line = this.stdoutBuffer.trim();
+    const line = this.stdoutBuffer.slice(this.stdoutReadOffset).trim();
     this.stdoutBuffer = "";
+    this.stdoutReadOffset = 0;
     if (!line)
       return;
     this.processStdoutLine(line);
@@ -12416,6 +12619,9 @@ class BinaryBridge {
         return;
       }
       if (response.type === "bash_completed") {
+        const taskId = bashTaskIdFrom(response);
+        if (taskId)
+          this.outstandingBackgroundTaskIds.delete(taskId);
         this.onBashCompletion?.(response, this);
         return;
       }
@@ -12446,6 +12652,7 @@ class BinaryBridge {
         clearTimeout(entry.timer);
         this.consecutiveRequestTimeouts = 0;
         this.scheduleRestartCountReset();
+        this.accountForBashTaskResponse(entry.command, response);
         this.captureStatusBar(response);
         entry.resolve(response);
       } else if (typeof response.type === "string") {
@@ -12455,6 +12662,18 @@ class BinaryBridge {
       this.warnVia(`Failed to parse stdout line: ${line}`);
     }
   }
+  accountForBashTaskResponse(command, response) {
+    const taskId = bashTaskIdFrom(response);
+    if (!taskId)
+      return;
+    if (isTerminalBashStatus(response.status)) {
+      this.outstandingBackgroundTaskIds.delete(taskId);
+      return;
+    }
+    if (command === "bash" && response.success !== false) {
+      this.outstandingBackgroundTaskIds.add(taskId);
+    }
+  }
   captureStatusBar(response) {
     const parsed = parseStatusBarCounts(response.status_bar);
     if (parsed)
@@ -12466,6 +12685,7 @@ class BinaryBridge {
   handleTimeout(triggeringSessionId) {
     this.consecutiveRequestTimeouts = 0;
     this.rejectAllPending(new Error(`${this.errorPrefix} bridge killed during sibling timeout — request aborted`));
+    this.outstandingBackgroundTaskIds.clear();
     if (this.process) {
       this.process.kill("SIGKILL");
       this.process = null;
@@ -12495,6 +12715,7 @@ class BinaryBridge {
     }
     this.clearRestartResetTimer();
     this.configured = false;
+    this.outstandingBackgroundTaskIds.clear();
     const tail = this.formatStderrTail();
     if (tail) {
       this.errorVia(`Binary crashed (restarts: ${this._restartCount})${cause ? `: ${cause.message}` : ""}.${tail}`);
@@ -12857,6 +13078,11 @@ function formatEditSummary(data) {
     const n = data.files_modified;
     return `Applied edits to ${n} file${n === 1 ? "" : "s"}.`;
   }
+  if (typeof data.total_files === "number") {
+    const files = data.total_files;
+    const reps = data.total_replacements ?? 0;
+    return `Edited ${files} file${files === 1 ? "" : "s"} (${reps} replacement${reps === 1 ? "" : "s"}).`;
+  }
   const additions = data.diff?.additions ?? 0;
   const deletions = data.diff?.deletions ?? 0;
   const counts = `+${additions}/-${deletions}`;
@@ -14071,7 +14297,23 @@ function isProcessAlive(pid) {
   }
 }
 // ../aft-bridge/dist/pipe-strip.js
-var NOISE_FILTERS = new Set(["grep", "rg", "head", "tail", "cat", "less", "more"]);
+var NOISE_FILTERS = new Set([
+  "grep",
+  "rg",
+  "head",
+  "tail",
+  "cat",
+  "less",
+  "more",
+  "sed",
+  "awk",
+  "cut",
+  "sort",
+  "uniq",
+  "tr",
+  "column",
+  "fold"
+]);
 var GREP_GUARD_FLAGS = new Set([
   "c",
   "count",
@@ -14085,6 +14327,8 @@ var GREP_GUARD_FLAGS = new Set([
 function maybeStripCompressorPipe(command, compressionEnabled) {
   if (!compressionEnabled)
     return { command, stripped: false };
+  if (containsUnsplittableConstruct(command))
+    return { command, stripped: false };
   const chain = splitTopLevelAndChain(command);
   if (chain === null)
     return { command, stripped: false };
@@ -14098,7 +14342,7 @@ function maybeStripCompressorPipe(command, compressionEnabled) {
     return { command, stripped: false };
   const filterStages = stages.slice(1).map((stage) => stage.trim());
   for (const stage of filterStages) {
-    if (!isPlainNoiseFilter(stage))
+    if (!filterStageIsSafeToDrop(stage))
       return { command, stripped: false };
   }
   const filters = filterStages.join(" | ");
@@ -14144,6 +14388,14 @@ function splitTopLevelAndChain(command) {
       return null;
     if (char === ";")
       return null;
+    if (char === `
+` || char === "\r")
+      return null;
+    if (char === "&") {
+      const prev = command[index - 1];
+      if (prev !== ">" && next !== ">")
+        return null;
+    }
   }
   segments.push(command.slice(start));
   return segments;
@@ -14186,45 +14438,262 @@ function isCompressorHandledRunner(stage) {
   const tokens = tokenizeStage(stage);
   if (tokens.length === 0)
     return false;
-  const [first, second, third] = tokens;
-  if (!first)
-    return false;
   if (tokens.some((token) => token === "&&" || token === "||" || token.includes(";"))) {
     return false;
   }
+  const first = runnerName(tokens[0]);
+  const second = tokens[1];
+  const third = tokens[2];
+  const rest = tokens.slice(1);
+  if (!first)
+    return false;
   if (first === "bun")
     return second === "test" || second === "run" && startsWithTest(third);
-  if (first === "cargo")
-    return ["test", "build", "check", "clippy"].includes(second ?? "");
-  if (first === "go")
-    return second === "test" || second === "build";
-  if (["npm", "pnpm"].includes(first)) {
+  if (first === "npm" || first === "pnpm") {
     return second === "test" || second === "run" && startsWithTest(third);
   }
-  if (first === "yarn")
-    return second === "test";
+  if (first === "yarn") {
+    return startsWithTest(second) || second === "run" && startsWithTest(third);
+  }
+  if (first === "deno")
+    return ["test", "lint", "check", "bench"].includes(second ?? "");
+  if (first === "npx") {
+    return ["tsc", "eslint", "vitest", "jest", "playwright", "biome"].includes(second ?? "");
+  }
   if (first === "playwright")
     return second === "test";
-  if (first === "npx")
-    return ["tsc", "eslint", "vitest", "jest"].includes(second ?? "");
-  return ["vitest", "jest", "pytest", "tsc", "eslint", "biome", "ruff", "mypy"].includes(first);
+  if (first === "cargo") {
+    return ["test", "build", "check", "clippy", "nextest"].includes(second ?? "");
+  }
+  if (first === "go")
+    return ["test", "build", "vet"].includes(second ?? "");
+  if (first === "gradle" || first === "gradlew") {
+    return hasBuildTask(rest, ["test", "check", "build", "assemble", "clean"]);
+  }
+  if (first === "mvn" || first === "mvnw") {
+    return hasBuildTask(rest, ["test", "verify", "package", "install"]);
+  }
+  if (first === "dotnet")
+    return ["test", "build"].includes(second ?? "");
+  if (first === "rspec")
+    return true;
+  if (first === "rake")
+    return second === "test" || second === "spec";
+  if (first === "phpunit" || first === "pest")
+    return true;
+  if (first === "xcodebuild")
+    return xcodebuildHasBuildAction(rest);
+  if (first === "swift")
+    return second === "test" || second === "build";
+  if (first === "make" || first === "gmake") {
+    return hasBuildTask(rest, ["test", "check", "lint", "clean"]);
+  }
+  return [
+    "vitest",
+    "jest",
+    "pytest",
+    "tsc",
+    "eslint",
+    "biome",
+    "ruff",
+    "mypy",
+    "tox",
+    "nox"
+  ].includes(first);
+}
+function runnerName(token) {
+  if (!token)
+    return "";
+  const slash = token.lastIndexOf("/");
+  return slash === -1 ? token : token.slice(slash + 1);
+}
+function hasBuildTask(args, tasks) {
+  const isAllowedTask = (arg) => tasks.some((task) => arg === task || arg.endsWith(`:${task}`));
+  const isFlagOrProperty = (arg) => arg.startsWith("-") || arg.includes("=");
+  let sawAllowed = false;
+  for (const arg of args) {
+    if (isFlagOrProperty(arg))
+      continue;
+    if (!isAllowedTask(arg))
+      return false;
+    sawAllowed = true;
+  }
+  return sawAllowed;
 }
 function startsWithTest(token) {
   return token?.startsWith("test") === true;
 }
-function isPlainNoiseFilter(stage) {
-  const tokens = tokenizeStage(stage);
-  const head = tokens[0];
+var XCODEBUILD_VALUE_FLAGS = new Set([
+  "-scheme",
+  "-target",
+  "-project",
+  "-workspace",
+  "-configuration",
+  "-sdk",
+  "-destination",
+  "-arch",
+  "-derivedDataPath",
+  "-resultBundlePath",
+  "-xcconfig",
+  "-toolchain"
+]);
+var XCODEBUILD_BUILD_ACTIONS = new Set([
+  "build",
+  "test",
+  "build-for-testing",
+  "test-without-building",
+  "analyze"
+]);
+function xcodebuildHasBuildAction(args) {
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("-")) {
+      if (XCODEBUILD_VALUE_FLAGS.has(arg))
+        i++;
+      continue;
+    }
+    if (XCODEBUILD_BUILD_ACTIONS.has(arg))
+      return true;
+  }
+  return false;
+}
+function containsUnsplittableConstruct(command) {
+  let quote = null;
+  let escaped = false;
+  for (let i = 0;i < command.length; i++) {
+    const char = command[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if (quote === "'") {
+      if (char === "'")
+        quote = null;
+      continue;
+    }
+    if (quote === '"') {
+      if (char === '"')
+        quote = null;
+      else if (char === "`")
+        return true;
+      else if (char === "$" && command[i + 1] === "(")
+        return true;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+    if (char === "`")
+      return true;
+    if (char === "(" || char === ")")
+      return true;
+  }
+  return false;
+}
+var READS_FILE_OPERAND = new Set(["cat", "tac", "nl", "less", "more"]);
+function filterStageIsSafeToDrop(stage) {
+  const head = tokenizeStage(stage)[0];
   if (!head)
     return false;
   if (head === "wc")
     return false;
   if (!NOISE_FILTERS.has(head))
     return false;
-  if ((head === "grep" || head === "rg") && hasIntentChangingGrepFlag(tokens.slice(1)))
+  if (/[<>]/.test(stage))
+    return false;
+  if (hasUnquotedBackground(stage))
+    return false;
+  const args = tokenizeStage(stage).slice(1);
+  const hasFlag = (...names) => args.some((a) => names.some((n) => a === n || a.startsWith(`${n}=`)));
+  if (head === "grep" || head === "rg") {
+    if (hasIntentChangingGrepFlag(args))
+      return false;
+    if (countBareOperands(args) > 1)
+      return false;
+    return true;
+  }
+  if (head === "head" || head === "tail") {
+    if (bareOperands(args).some((op) => !/^\d+$/.test(op)))
+      return false;
+    return true;
+  }
+  if (READS_FILE_OPERAND.has(head)) {
+    if (countBareOperands(args) > 0)
+      return false;
+    return true;
+  }
+  if (head === "sed") {
+    if (hasFlag("-i", "--in-place"))
+      return false;
+    if (countBareOperands(args) > 1)
+      return false;
+    return true;
+  }
+  if (head === "awk") {
+    if (countBareOperands(args) > 1)
+      return false;
+    return true;
+  }
+  if (head === "sort" && hasFlag("-o", "--output"))
+    return false;
+  if (bareOperands(args).some((op) => op.includes("/") || op.includes(".")))
     return false;
   return true;
 }
+function bareOperands(args) {
+  const out = [];
+  let afterDoubleDash = false;
+  for (const arg of args) {
+    if (!afterDoubleDash && arg === "--") {
+      afterDoubleDash = true;
+      continue;
+    }
+    if (!afterDoubleDash && arg.startsWith("-") && arg !== "-")
+      continue;
+    out.push(arg);
+  }
+  return out;
+}
+function countBareOperands(args) {
+  return bareOperands(args).length;
+}
+function hasUnquotedBackground(stage) {
+  let quote = null;
+  let escaped = false;
+  for (let i = 0;i < stage.length; i++) {
+    const char = stage[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote)
+        quote = null;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+    if (char === "&") {
+      const prev = stage[i - 1];
+      const next = stage[i + 1];
+      if (prev === "&" || next === "&" || prev === ">" || next === ">")
+        continue;
+      return true;
+    }
+  }
+  return false;
+}
 function hasIntentChangingGrepFlag(args) {
   for (const arg of args) {
     if (arg === "--")
@@ -14288,7 +14757,7 @@ function tokenizeStage(stage) {
 // ../aft-bridge/dist/pool.js
 import { realpathSync as realpathSync2 } from "node:fs";
 import { homedir as homedir6 } from "node:os";
-var DEFAULT_IDLE_TIMEOUT_MS = Infinity;
+var DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 var DEFAULT_MAX_POOL_SIZE = 8;
 var CLEANUP_INTERVAL_MS = 60 * 1000;
 function canonicalHomeDir() {
@@ -14383,7 +14852,7 @@ class BridgePool {
   cleanup() {
     const now = Date.now();
     for (const [dir, entry] of this.bridges) {
-      if (entry.bridge.hasPendingRequests())
+      if (entry.bridge.hasPendingRequests() || entry.bridge.hasOutstandingBackgroundTasks())
         continue;
       if (now - entry.lastUsed > this.idleTimeoutMs) {
         entry.bridge.shutdown().catch((err) => this.error("cleanup shutdown failed:", err));
@@ -14391,7 +14860,7 @@ class BridgePool {
       }
     }
     for (const bridge of this.staleBridges) {
-      if (bridge.hasPendingRequests())
+      if (bridge.hasPendingRequests() || bridge.hasOutstandingBackgroundTasks())
         continue;
       bridge.shutdown().catch((err) => this.error("stale cleanup shutdown failed:", err));
       this.staleBridges.delete(bridge);
@@ -14401,7 +14870,7 @@ class BridgePool {
     let oldestDir = null;
     let oldestTime = Infinity;
     for (const [dir, entry] of this.bridges) {
-      if (entry.bridge.hasPendingRequests())
+      if (entry.bridge.hasPendingRequests() || entry.bridge.hasOutstandingBackgroundTasks())
         continue;
       if (entry.lastUsed < oldestTime) {
         oldestTime = entry.lastUsed;
@@ -15207,7 +15676,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.36.0",
+  version: "0.37.0",
   type: "module",
   description: "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   main: "dist/index.js",
@@ -15230,7 +15699,7 @@ var package_default = {
     "test:unit": "bun test src/__tests__ --path-ignore-patterns 'src/__tests__/e2e/**'"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.36.0",
+    "@cortexkit/aft-bridge": "0.37.0",
     "@xterm/headless": "^5.5.0",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
@@ -15238,12 +15707,12 @@ var package_default = {
     zod: "^4.1.8"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.36.0",
-    "@cortexkit/aft-darwin-x64": "0.36.0",
-    "@cortexkit/aft-linux-arm64": "0.36.0",
-    "@cortexkit/aft-linux-x64": "0.36.0",
-    "@cortexkit/aft-win32-arm64": "0.36.0",
-    "@cortexkit/aft-win32-x64": "0.36.0"
+    "@cortexkit/aft-darwin-arm64": "0.37.0",
+    "@cortexkit/aft-darwin-x64": "0.37.0",
+    "@cortexkit/aft-linux-arm64": "0.37.0",
+    "@cortexkit/aft-linux-x64": "0.37.0",
+    "@cortexkit/aft-win32-arm64": "0.37.0",
+    "@cortexkit/aft-win32-x64": "0.37.0"
   },
   devDependencies: {
     "@earendil-works/pi-coding-agent": "*",
@@ -15501,19 +15970,6 @@ function isEmptyParam(value) {
     return Object.keys(value).length === 0;
   return false;
 }
-var LONG_RUNNING_COMMAND_TIMEOUT_MS = {
-  callers: 60000,
-  trace_to: 60000,
-  trace_to_symbol: 60000,
-  trace_data: 60000,
-  impact: 60000,
-  grep: 60000,
-  glob: 60000,
-  semantic_search: 60000
-};
-function timeoutForCommand(command) {
-  return LONG_RUNNING_COMMAND_TIMEOUT_MS[command];
-}
 function asPlainObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return;
@@ -31881,7 +32337,7 @@ function sendFeatureAnnouncement(version2, features, footer, storageDir) {
 // src/status-bar-inject.ts
 var DEFAULT_SESSION = "__default__";
 var emitStateBySession = new Map;
-function statusBarBlockForSession(sessionID, counts) {
+function statusBarBlockForSession(sessionID, counts, force = false) {
   if (!counts)
     return;
   const key = sessionID ?? DEFAULT_SESSION;
@@ -31890,6 +32346,11 @@ function statusBarBlockForSession(sessionID, counts) {
     state = createStatusBarEmitState();
     emitStateBySession.set(key, state);
   }
+  if (force) {
+    state.last = counts;
+    state.callsSinceEmit = 0;
+    return formatStatusBar(counts);
+  }
   return shouldEmitStatusBar(state, counts) ? formatStatusBar(counts) : undefined;
 }
 
@@ -32146,7 +32607,6 @@ 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;
 }
@@ -32216,8 +32676,7 @@ var WriteParams = Type2.Object({
   filePath: Type2.String({
     description: "Path to the file to write (absolute or relative to project root)"
   }),
-  content: Type2.String({ description: "Full file contents to write" }),
-  diagnostics: Type2.Optional(Type2.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
+  content: Type2.String({ description: "Full file contents to write" })
 });
 var EditParams = Type2.Object({
   filePath: Type2.String({
@@ -32229,8 +32688,7 @@ var EditParams = Type2.Object({
   occurrence: optionalInt(0, Number.MAX_SAFE_INTEGER),
   appendContent: Type2.Optional(Type2.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: Type2.Optional(Type2.Boolean({ description: DIAGNOSTICS_PARAM_DESCRIPTION }))
+  }))
 });
 var GrepParams = Type2.Object({
   pattern: Type2.String({ description: "Regex pattern to search for" }),
@@ -32238,8 +32696,7 @@ var GrepParams = Type2.Object({
     description: "Path scope (file or directory; absolute or relative to project root)"
   })),
   include: Type2.Optional(Type2.String({ description: "Glob filter for included files (e.g. '*.ts,*.tsx')" })),
-  caseSensitive: Type2.Optional(Type2.Boolean({ description: "Case-sensitive matching" })),
-  contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER)
+  caseSensitive: Type2.Optional(Type2.Boolean({ description: "Case-sensitive matching" }))
 });
 function registerHoistedTools(pi, ctx, surface) {
   if (surface.hoistRead) {
@@ -32254,7 +32711,9 @@ function registerHoistedTools(pi, ctx, surface) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const offset = coerceOptionalInt(params.offset, "offset", 1, Number.MAX_SAFE_INTEGER);
         const limit = coerceOptionalInt(params.limit, "limit", 1, Number.MAX_SAFE_INTEGER);
-        const req = { file: params.path };
+        const req = {
+          file: await resolvePathArg(extCtx.cwd, params.path)
+        };
         if (offset !== undefined) {
           req.start_line = offset;
           if (limit !== undefined) {
@@ -32281,19 +32740,20 @@ function registerHoistedTools(pi, ctx, surface) {
     pi.registerTool({
       name: "write",
       label: "write",
-      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)",
+      description: "Write content to a file, creating it and parent directories automatically. Existing files are backed up before overwriting (undo via aft_safety) and auto-formatted when the project has a formatter configured. Uses `filePath` (not `path`). For partial edits, use the `edit` tool.",
+      promptSnippet: "Create or overwrite files (uses filePath; auto-formats)",
       promptGuidelines: ["Use write only for new files or complete rewrites."],
       parameters: WriteParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-        await assertExternalDirectoryPermission(extCtx, params.filePath, "modify", {
+        const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+        await assertExternalDirectoryPermission(extCtx, filePath, "modify", {
           restrictToProjectRoot: surface.restrictToProjectRoot
         });
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const response = await callBridge(bridge, "write", {
-          file: params.filePath,
+          file: filePath,
           content: params.content,
-          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          diagnostics: diagnosticsOnEditDefault(ctx),
           include_diff_content: true
         }, extCtx);
         return buildMutationResult(response);
@@ -32310,8 +32770,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`. 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.",
+      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`.",
+      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).",
       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.",
@@ -32319,26 +32779,27 @@ function registerHoistedTools(pi, ctx, surface) {
       ],
       parameters: EditParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-        await assertExternalDirectoryPermission(extCtx, params.filePath, "modify", {
+        const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
+        await assertExternalDirectoryPermission(extCtx, filePath, "modify", {
           restrictToProjectRoot: surface.restrictToProjectRoot
         });
         const bridge = bridgeFor(ctx, extCtx.cwd);
         if (typeof params.appendContent === "string") {
           const req2 = {
             op: "append",
-            file: params.filePath,
+            file: filePath,
             append_content: params.appendContent,
-            diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+            diagnostics: diagnosticsOnEditDefault(ctx),
             include_diff_content: true
           };
           const response2 = await callBridge(bridge, "edit_match", req2, extCtx);
           return buildMutationResult(response2);
         }
         const req = {
-          file: params.filePath,
+          file: filePath,
           match: params.oldString ?? "",
           replacement: params.newString ?? "",
-          diagnostics: params.diagnostics ?? diagnosticsOnEditDefault(ctx),
+          diagnostics: diagnosticsOnEditDefault(ctx),
           include_diff_content: true
         };
         if (params.replaceAll === true)
@@ -32378,9 +32839,6 @@ function registerHoistedTools(pi, ctx, surface) {
           req.include = splitIncludeGlobs(params.include);
         if (params.caseSensitive !== undefined)
           req.case_sensitive = params.caseSensitive;
-        const contextLines = coerceOptionalInt(params.contextLines, "contextLines", 1, Number.MAX_SAFE_INTEGER);
-        if (contextLines !== undefined)
-          req.context_lines = contextLines;
         const response = await callBridge(bridge, "grep", req, extCtx);
         const text = response.text ?? "";
         return textResult(text);
@@ -32941,7 +33399,7 @@ function registerAstTools(pi, ctx, surface) {
         if (!isEmptyParam(params.globs))
           req.globs = params.globs;
         if (params.contextLines !== undefined)
-          req.context_lines = params.contextLines;
+          req.context = params.contextLines;
         const response = await callBridge(bridge, "ast_search", req, extCtx);
         return textResult(response.text ?? JSON.stringify(response));
       },
@@ -33095,22 +33553,28 @@ function getBashSpawnHook(pi) {
   }
   return api2.hooks?.bashSpawn;
 }
-function registerBashTool(pi, ctx) {
+function registerBashTool(pi, ctx, aftSearchRegistered = false) {
   const spawnHook = getBashSpawnHook(pi);
+  const searchSteer = aftSearchRegistered ? "use `aft_search` (concepts, identifiers, regex, literals), `read`, `aft_outline`, or `aft_zoom` instead" : "use the `grep` tool, `read`, `aft_outline`, or `aft_zoom` instead";
+  const bashCfg = resolveBashConfig(ctx.config);
+  const compressionSentence = bashCfg.compress ? " Output is compressed by default; pass `compressed: false` for raw output." : "";
+  const tasksSentence = bashCfg.background ? ' Pass `background: true` to run in the background and get a task_id for `bash_status`/`bash_kill`. Pass `pty: true` for interactive programs (REPLs, TUIs) and drive them with `bash_status({ output_mode: "screen" })` plus `bash_write`.' : " Commands that outlive the foreground wait window are promoted to background tasks; inspect them with `bash_status({ task_id })` or terminate with `bash_kill`.";
   pi.registerTool({
     name: "bash",
     label: "bash",
-    description: 'Execute shell commands through AFT\'s Rust bash handler. By default, output is compressed. Pass `compressed: false` for raw output. Pass `background: true` to spawn in the background and get a task_id for `bash_status`/`bash_kill`. Pass `pty: true` with `background: true` for interactive programs and drive them with `bash_status({ output_mode: "screen" })` plus `bash_write`.',
+    description: `Execute shell commands.${compressionSentence}${tasksSentence}
+
+DO NOT use bash for code search or code exploration. If you are about to run grep, rg, sed, awk, find, or cat through bash to locate or read code: STOP — ${searchSteer}.`,
     promptSnippet: "Run shell commands (timeout in milliseconds; supports workdir, background tasks, compressed output, PTY mode)",
     promptGuidelines: [
-      "Use bash only when a dedicated AFT tool is not a better fit.",
+      `DO NOT use bash for code search or exploration — ${searchSteer}.`,
       "Set compressed: false when you need ANSI color codes in the output."
     ],
     parameters: BashParams,
     async execute(_toolCallId, params, _signal, onUpdate, extCtx) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
-      const bashCfg = resolveBashConfig(ctx.config);
-      const foregroundWaitMs = resolveForegroundWaitMs(bashCfg.foreground_wait_window_ms);
+      const bashCfg2 = resolveBashConfig(ctx.config);
+      const foregroundWaitMs = resolveForegroundWaitMs(bashCfg2.foreground_wait_window_ms);
       const timeout = coerceOptionalInt(params.timeout, "timeout", 1, Number.MAX_SAFE_INTEGER);
       const ptyRows = coerceOptionalInt(params.ptyRows, "ptyRows", 1, 60);
       const ptyCols = coerceOptionalInt(params.ptyCols, "ptyCols", 1, 140);
@@ -33127,7 +33591,7 @@ function registerBashTool(pi, ctx) {
           throw new Error(`BashSpawnHook failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
         }
       }
-      const compressionEnabled = bashCfg.compress && params.compressed !== false;
+      const compressionEnabled = bashCfg2.compress && params.compressed !== false;
       const pipeStrip = maybeStripCompressorPipe(spawnContext.command, compressionEnabled);
       const bridgeCommand = pipeStrip.command;
       let streamed = "";
@@ -33162,9 +33626,7 @@ function registerBashTool(pi, ctx) {
       if (response.status === "running" && taskId) {
         if (effectiveBackground) {
           trackBgTask(resolveSessionId(extCtx), taskId);
-          return bashResult(formatBackgroundLaunch(taskId, params.pty === true), {
-            task_id: taskId
-          });
+          return bashResult(appendPipeStripNote(formatBackgroundLaunch(taskId, params.pty === true), pipeStrip.note), { task_id: taskId });
         }
         const waitTimeoutMs = effectiveTimeout !== undefined ? Math.min(effectiveTimeout, foregroundWaitMs) : foregroundWaitMs;
         const startedAt = Date.now();
@@ -33174,7 +33636,7 @@ function registerBashTool(pi, ctx) {
             throw new Error(status.message ?? "bash_status failed");
           }
           if (isTerminalStatus(status.status)) {
-            return bashResult(appendPipeStripNote(withBashHints(formatForegroundResult(status)), pipeStrip.note), {
+            return bashResult(appendPipeStripNote(withBashHints(formatForegroundResult(status), bridgeCommand, aftSearchRegistered), pipeStrip.note), {
               exit_code: status.exit_code,
               duration_ms: status.duration_ms,
               truncated: status.output_truncated,
@@ -33188,9 +33650,7 @@ function registerBashTool(pi, ctx) {
               throw new Error(promoted.message ?? "bash_promote failed");
             }
             trackBgTask(resolveSessionId(extCtx), taskId);
-            return bashResult(formatPromotionMessage(taskId, effectiveTimeout, foregroundWaitMs), {
-              task_id: taskId
-            });
+            return bashResult(appendPipeStripNote(formatPromotionMessage(taskId, effectiveTimeout, foregroundWaitMs), pipeStrip.note), { task_id: taskId });
           }
           await sleep(FOREGROUND_POLL_INTERVAL_MS);
         }
@@ -33203,7 +33663,7 @@ function registerBashTool(pi, ctx) {
         task_id: taskId
       };
       const output = response.output ?? "";
-      return bashResult(appendPipeStripNote(withBashHints(output), pipeStrip.note), details);
+      return bashResult(appendPipeStripNote(withBashHints(output, bridgeCommand, aftSearchRegistered), pipeStrip.note), details);
     },
     renderCall(args, theme, context) {
       return renderBashCall(args?.command, args?.description, theme, context);
@@ -33235,8 +33695,8 @@ function formatPromotionMessage(taskId, timeout, waitWindowMs) {
 function formatSeconds(ms) {
   return `${Number((ms / 1000).toFixed(1))}s`;
 }
-function withBashHints(output) {
-  return maybeAppendConflictsHint(output);
+function withBashHints(output, command, aftSearchRegistered) {
+  return maybeAppendGrepSearchHint(maybeAppendConflictsHint(output), command, aftSearchRegistered);
 }
 function formatForegroundResult(data) {
   const output = data.output_preview ?? "";
@@ -33704,8 +34164,12 @@ function registerConflictsTool(pi, ctx) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const reqParams = {};
       const path2 = params?.path;
-      if (typeof path2 === "string" && path2.trim() !== "")
-        reqParams.path = path2;
+      if (typeof path2 === "string" && path2.trim() !== "") {
+        await assertExternalDirectoryPermission(extCtx, path2, "inspect", {
+          restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
+        });
+        reqParams.path = await resolvePathArg(extCtx.cwd, path2);
+      }
       const response = await callBridge(bridge, "git_conflicts", reqParams, extCtx);
       return textResult(response.text ?? JSON.stringify(response, null, 2));
     },
@@ -34251,7 +34715,15 @@ function registerInspectTool(pi, ctx) {
       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);
+      const body = response.text;
+      if (typeof body === "string") {
+        const diagnostics = diagnosticsSummaryPart(asRecord2(response.summary));
+        const text = diagnostics ? body ? `${body}
+
+${diagnostics}` : diagnostics : body;
+        return textResult(text, response);
+      }
+      return textResult(JSON.stringify(response, null, 2), response);
     },
     renderCall(args, theme, context) {
       return renderInspectCall(args, theme, context);
@@ -34990,7 +35462,7 @@ function registerRefactorTool(pi, ctx) {
   pi.registerTool({
     name: "aft_refactor",
     label: "refactor",
-    description: "Workspace-wide refactoring that updates imports and references across files. `move` relocates a top-level symbol; `extract` pulls a line range into a new function; `inline` replaces a call site. Use aft_safety checkpoint/undo before risky refactors.",
+    description: "Workspace-wide refactoring that updates imports and references across files. `move` relocates a top-level symbol (not nested functions or class methods) to another file, rewriting imports workspace-wide; a checkpoint is created first. To move/rename a whole file, use aft_move. `extract` pulls a line range into a new function (TS/JS/TSX, Python). `inline` replaces a call with the function's body.",
     parameters: RefactorParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
       const commandMap = {
@@ -35369,21 +35841,9 @@ function registerSemanticTool(pi, ctx) {
     name: "aft_search",
     label: "search",
     description: [
-      "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'",
-      "- 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",
+      "Search code with one tool: concepts, identifiers, error strings, regex, literals, and filenames are auto-routed to the right engine and returned ranked. Use it for any code search — including when you only know what the code does, not what it's named ('where is rate limiting handled', 'retry logic', '^export', 'Cargo.lock').",
       "",
-      "When NOT to use:",
-      "- 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_callgraph",
-      "",
-      "Set hint to 'regex', 'literal', 'semantic', or 'auto' to override or document routing intent."
+      "Set hint to 'regex', 'literal', or 'semantic' to force a lane."
     ].join(`
 `),
     parameters: SearchParams2,
@@ -35414,138 +35874,8 @@ ${extra}`;
   });
 }
 
-// src/tools/structure.ts
-import { StringEnum as StringEnum6 } from "@earendil-works/pi-ai";
-import { Type as Type14 } from "typebox";
-var TransformParams = Type14.Object({
-  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)"
-  }),
-  container: Type14.Optional(Type14.String({ description: "Class/struct/impl name for add_member" })),
-  code: Type14.Optional(Type14.String({ description: "Member code to insert (add_member)" })),
-  target: Type14.Optional(Type14.String({ description: "Target symbol name" })),
-  derives: Type14.Optional(Type14.Array(Type14.String(), { description: "Derive macro names (add_derive)" })),
-  catchBody: Type14.Optional(Type14.String({ description: "Catch block body (wrap_try_catch, default: 'throw error;')" })),
-  decorator: Type14.Optional(Type14.String({ description: "Decorator text without @ (add_decorator)" })),
-  field: Type14.Optional(Type14.String({ description: "Struct field name (add_struct_tags)" })),
-  tag: Type14.Optional(Type14.String({ description: "Tag key (add_struct_tags)" })),
-  value: Type14.Optional(Type14.String({ description: "Tag value (add_struct_tags)" })),
-  position: Type14.Optional(Type14.String({
-    description: "Position hint: 'first', 'last' (default), 'before:name', 'after:name' for add_member"
-  })),
-  validate: Type14.Optional(StringEnum6(["syntax", "full"], {
-    description: "Validation level (default: syntax)"
-  }))
-});
-function buildTransformSections(args, payload, theme) {
-  const response = asRecord2(payload);
-  if (!response)
-    return [theme.fg("muted", "No transform result.")];
-  const target = asString(response.target) ?? asString(response.scope) ?? args.target ?? args.container ?? args.field ?? args.filePath;
-  return [
-    `${theme.fg("success", "transformed")} ${theme.fg("accent", args.op)}`,
-    `${theme.fg("muted", "file")} ${theme.fg("accent", asString(response.file) ?? args.filePath)}`,
-    target ? `${theme.fg("muted", "target")} ${target}` : theme.fg("muted", "No target metadata.")
-  ];
-}
-function renderTransformCall(args, theme, context) {
-  const target = args.target ?? args.container ?? args.field;
-  const summary = [
-    theme.fg("accent", args.op),
-    accentPath(theme, args.filePath),
-    target ? theme.fg("toolOutput", target) : undefined
-  ].filter(Boolean).join(" ");
-  return renderToolCall("transform", summary, theme, context);
-}
-function renderTransformResult(result, args, theme, context) {
-  if (context.isError)
-    return renderErrorResult(result, "transform failed", theme, context);
-  return renderSections(buildTransformSections(args, extractStructuredPayload(result), theme), context);
-}
-function registerStructureTool(pi, ctx) {
-  pi.registerTool({
-    name: "aft_transform",
-    label: "transform",
-    description: "Scope-aware structural code transformations with correct indentation. Use aft_safety checkpoint/undo before risky transforms.",
-    parameters: TransformParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      validateTransformParams(params);
-      const filePath = await resolvePathArg(extCtx.cwd, params.filePath);
-      await assertExternalDirectoryPermission(extCtx, filePath, "modify", {
-        restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
-      });
-      const bridge = bridgeFor(ctx, extCtx.cwd);
-      const req = { file: filePath };
-      if (params.container !== undefined)
-        req.scope = params.container;
-      if (params.code !== undefined)
-        req.code = params.code;
-      if (params.target !== undefined)
-        req.target = params.target;
-      if (params.derives !== undefined)
-        req.derives = params.derives;
-      if (params.catchBody !== undefined)
-        req.catch_body = params.catchBody;
-      if (params.decorator !== undefined)
-        req.decorator = params.decorator;
-      if (params.field !== undefined)
-        req.field = params.field;
-      if (params.tag !== undefined)
-        req.tag = params.tag;
-      if (params.value !== undefined)
-        req.value = params.value;
-      if (params.position !== undefined)
-        req.position = params.position;
-      if (params.validate !== undefined)
-        req.validate = params.validate;
-      const response = await callBridge(bridge, params.op, req, extCtx);
-      return textResult(JSON.stringify(response, null, 2));
-    },
-    renderCall(args, theme, context) {
-      return renderTransformCall(args, theme, context);
-    },
-    renderResult(result, _options, theme, context) {
-      return renderTransformResult(result, context.args, theme, context);
-    }
-  });
-}
-function validateTransformParams(params) {
-  const op = params.op;
-  if (op === "add_member") {
-    if (isEmptyParam(params.container)) {
-      throw new Error("'container' is required for 'add_member' op");
-    }
-    if (isEmptyParam(params.code)) {
-      throw new Error("'code' is required for 'add_member' op");
-    }
-  }
-  if (op === "add_derive" || op === "wrap_try_catch" || op === "add_decorator" || op === "add_struct_tags") {
-    if (isEmptyParam(params.target)) {
-      throw new Error(`'target' is required for '${op}' op`);
-    }
-  }
-  if (op === "add_derive" && isEmptyParam(params.derives)) {
-    throw new Error("'derives' array is required for 'add_derive' op");
-  }
-  if (op === "add_decorator" && isEmptyParam(params.decorator)) {
-    throw new Error("'decorator' is required for 'add_decorator' op");
-  }
-  if (op === "add_struct_tags") {
-    if (isEmptyParam(params.field)) {
-      throw new Error("'field' is required for 'add_struct_tags' op");
-    }
-    if (isEmptyParam(params.tag)) {
-      throw new Error("'tag' is required for 'add_struct_tags' op");
-    }
-    if (isEmptyParam(params.value)) {
-      throw new Error("'value' is required for 'add_struct_tags' op");
-    }
-  }
-}
-
 // src/workflow-hints.ts
-var HEADING = "## Prefer AFT tools for token efficiency";
+var HEADING = "## IMPORTANT NOTICE about your tools";
 function buildWorkflowHints(opts) {
   const sections = [];
   const grepName = opts.hoistBuiltins ? "grep" : "aft_grep";
@@ -35559,14 +35889,28 @@ function buildWorkflowHints(opts) {
   const hasBash = !opts.absentTools.has(bashName);
   const hasBgBash = opts.bashBackgroundEnabled && hasBash && !opts.absentTools.has("bash_status");
   if (hasBash && opts.bashCompressionEnabled) {
-    sections.push("When AFT bash output compression is on, do NOT pipe test/build commands through grep/head/tail (e.g. `bun test | grep fail`) to summarize. The compressor already keeps failures and the summary; piping hides failures. Run the command bare.");
+    sections.push([
+      "**Test/build output**: bash output is auto-compressed — failures and the summary are always kept. DO NOT pipe test/build commands through filters to summarize; that hides failures:",
+      "- `bun test | grep fail` → run `bun test`",
+      "- `cargo test 2>&1 | tail -20` → run `cargo test`",
+      "- `npm run build | head -50` → run `npm run build`"
+    ].join(`
+`));
   }
   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 searchName = hasSearch ? "aft_search" : grepName;
     const locate = hasSearch ? '`aft_search` is the primary code-search tool: one call auto-routes concepts, identifiers, regex, error strings, and literals (pass `hint: "regex"`/`"literal"`/`"semantic"` to force a lane).' : `\`${grepName}\` (the tool — indexed and ranked) locates code.`;
-    sections.push(`**Code exploration**: fire independent lookups in ONE parallel tool-call wave — do NOT serialize them. ${locate} Then \`aft_outline\` for structure → \`aft_zoom\` for symbol(s). DO NOT run \`grep\`/\`rg\`/\`find\` through \`bash\` to locate code — the bash path is unindexed, unranked, serial, and routinely surfaces the wrong hit. Keep \`bash\` for shell facts (git state, file metadata, processes).`);
+    const readName = opts.hoistBuiltins ? "read" : "aft_read";
+    sections.push([
+      `**Code exploration**: ${locate} Then \`aft_outline\` for structure → \`aft_zoom\` for symbol(s). DO NOT run \`grep\`/\`rg\`/\`find\`/\`sed\`/\`cat\` through \`bash\` to locate or read code — the bash path is unindexed, unranked, serial, and routinely surfaces the wrong hit. Keep \`bash\` for shell facts (git state, file metadata, processes). Reflex translations:`,
+      `- \`grep -rn "handleAuth" src/\` in bash → \`${searchName}({ query: "handleAuth" })\``,
+      `- \`find . -name "*.ts" | xargs grep watcher\` in bash → \`${searchName}({ query: "watcher invalidation" })\` (concepts work too)`,
+      `- \`sed -n '100,160p' app.ts\` / \`cat app.ts\` in bash → \`${readName}({ filePath: "app.ts", startLine: 100, endLine: 160 })\``
+    ].join(`
+`));
   }
   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.");
@@ -35584,13 +35928,22 @@ function buildWorkflowHints(opts) {
 `));
   }
   if (hasBgBash) {
-    sections.push(`**Long-running commands** (builds, installs, full test suites): \`${bashName}({ background: true })\` returns immediately with a \`task_id\`, then **end your turn** — a completion reminder arrives automatically when it finishes. Do not poll \`bash_status({ task_id })\`, and do not sync-wait with \`bash_watch\` for a long task: blocking freezes your turn and locks the user out until it ends. For an early non-blocking ping on a specific output line, register an async watch \`bash_watch({ task_id, pattern, background: true })\`. \`bash_watch\` synchronous mode is only for short bounded waits (seconds, e.g. a dev server printing a readiness line), never for multi-minute jobs.`);
+    sections.push([
+      `**Long-running commands** (builds, installs, full test suites): \`${bashName}({ background: true })\` returns a \`task_id\` immediately. Then do ONE of these:`,
+      "1. Keep working on something independent of the result.",
+      "2. End your turn — a completion reminder with the result arrives automatically.",
+      `3. Need to react to a specific output line early? Register \`bash_watch({ task_id, pattern, background: true })\`, then end your turn — it pings you the moment the pattern appears.`,
+      `\`bash_status({ task_id })\` is for inspecting output AFTER the reminder arrives, or one quick look at a live task — never call it repeatedly to wait: the reminder already delivers the result, and each poll wastes a turn. Sync \`bash_watch\` (without \`background: true\`) blocks your turn and locks the user out — reserve it for waits of a few seconds (a dev server printing its ready line), never for builds or test suites.`
+    ].join(`
+`));
     sections.push(`**PTY / interactive commands**: PTY mode is for interactive REPLs and terminal apps (python, node, bash itself, vim). Start with \`${bashName}({ command: "python", pty: true, background: true })\`, read the screen with \`bash_status({ task_id, output_mode: "screen" })\`, and send input with \`bash_write({ task_id, input: "..." })\`.`);
   }
   if (sections.length === 0) {
     return null;
   }
-  sections.unshift("**Parallel tool calls**: when several read-only operations are independent, emit them in ONE response instead of serializing — file reads, structure and symbol lookups, code search, diagnostics, and git status/diff/log. Sequence only when a call depends on a prior result or when a command mutates state.");
+  sections.unshift(`You are equipped with a non-standard tool set: indexed code search, symbol-level reading, structural editing, and code analysis that are faster, more precise, and far cheaper in tokens than stitching together command-line utilities in bash. Always reach for these tools first.
+
+**Parallel tool calls**: when several read-only operations are independent, emit them in ONE response instead of serializing — file reads, structure and symbol lookups, code search, diagnostics, and git status/diff/log. Sequence only when a call depends on a prior result or when a command mutates state.`);
   return `${HEADING}
 
 ${sections.join(`
@@ -35682,21 +36035,15 @@ var PLUGIN_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var ANNOUNCEMENT_VERSION = "0.36.0";
+var ANNOUNCEMENT_VERSION = "0.37.0";
 var ANNOUNCEMENT_FEATURES = [
-  "Persisted call graph: dead-code analysis runs on large repositories again (the file-count cap is gone), `aft_callgraph` queries resolve from disk, and method-call edges are more accurate across more languages.",
-  "Bash output stops hiding failures: piping a test/build through `grep`/`head` with compression on now keeps the failures and summary instead of stripping them.",
-  "Code search steering: guidance and hints now point to `aft_search` and parallel `aft_*` tools instead of `grep`/`find` in bash.",
-  "Fixes: a small `timeout` no longer kills a foreground `bash` command (#102), and `aft_delete`/`aft_safety checkpoint` no longer crash on a mistyped `files` argument."
+  "Much lower background CPU: idle bridges shut down after 30 minutes, deleted project roots stop the watcher instead of spinning it, and background scans reuse warm caches on a bounded thread pool.",
+  "`aft_transform` removed: usage data showed agents never called it — `edit` covers everything it did, and every request now carries a smaller tool surface.",
+  "Leaner tools: `bash`, `write`, `edit`, `apply_patch`, `aft_search`, and `aft_refactor` descriptions trimmed and config-aware; system-prompt guidance rewritten around what to do instead of what to avoid.",
+  "Background bash reminders are right-sized: failures keep head + tail context, successes show a short tail, and compressors never print a success summary for a non-zero exit."
 ];
 var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/DSa65w8wuf";
-var ALL_ONLY_TOOLS = new Set([
-  "aft_callgraph",
-  "aft_delete",
-  "aft_move",
-  "aft_transform",
-  "aft_refactor"
-]);
+var ALL_ONLY_TOOLS = new Set(["aft_callgraph", "aft_delete", "aft_move", "aft_refactor"]);
 var pendingEagerWarnings = new Map;
 function isConfigureWarning(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
@@ -35774,7 +36121,6 @@ function resolveToolSurface(config2) {
       move: false,
       astSearch: false,
       astReplace: false,
-      structure: false,
       refactor: false
     };
   }
@@ -35797,7 +36143,6 @@ function resolveToolSurface(config2) {
     move: false,
     astSearch: ok("ast_grep_search"),
     astReplace: ok("ast_grep_replace"),
-    structure: false,
     refactor: false
   };
   if (surface === "all") {
@@ -35806,7 +36151,6 @@ function resolveToolSurface(config2) {
       navigate: allOnly("aft_callgraph"),
       delete: allOnly("aft_delete"),
       move: allOnly("aft_move"),
-      structure: allOnly("aft_transform"),
       refactor: allOnly("aft_refactor")
     };
   }
@@ -36012,7 +36356,7 @@ ${lines}
   }
   const surface = resolveToolSurface(config2);
   if (surface.hoistBash && resolveBashConfig(config2).enabled) {
-    registerBashTool(pi, ctx);
+    registerBashTool(pi, ctx, surface.semantic);
   }
   registerHoistedTools(pi, ctx, surface);
   if (surface.outline || surface.zoom) {
@@ -36042,9 +36386,6 @@ ${lines}
   if (surface.delete || surface.move) {
     registerFsTools(pi, ctx, surface);
   }
-  if (surface.structure) {
-    registerStructureTool(pi, ctx);
-  }
   if (surface.refactor) {
     registerRefactorTool(pi, ctx);
   }
@@ -36054,8 +36395,9 @@ ${lines}
     const sessionID = resolveSessionId(extCtx);
     const bgContent = await appendToolResultBgCompletions({ ctx, directory: extCtx.cwd, sessionID }, event.content);
     let content = bgContent ?? event.content;
+    const isInspect = typeof event.details === "object" && event.details !== null && "scanner_state" in event.details;
     const activeBridge = pool.getActiveBridgeForRoot(extCtx.cwd);
-    const bar = statusBarBlockForSession(sessionID, activeBridge?.getStatusBar());
+    const bar = statusBarBlockForSession(sessionID, activeBridge?.getStatusBar(), isInspect);
     if (bar)
       content = [...content, { type: "text", text: bar }];
     if (content === event.content)