@cortexkit/aft-pi 0.58.0 → 0.58.2

package/dist/index.js

@@ -7935,25 +7935,79 @@ function error(message, meta) {
 function isTerminalStatus(status) {
   return status === "completed" || status === "failed" || status === "killed" || status === "timed_out" || status === "fate_unknown";
 }
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 // ../aft-bridge/dist/bash-hints.js
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 var DEFAULT_PRIMARY_WATCH_TIMEOUT_MS = 30000;
-var WATCH_TIMEOUT_PARAM_DESCRIPTION = "Sync-only timeout in milliseconds. Default 30000 (the configured maximum for delegated sessions); max `bash.watch_sync_max_ms` (120000 by default).";
+var MAX_WATCH_TIMEOUT_MS = 1800000;
+var LONGEST_TIMER_DELAY_MS = 2147483647;
+var WATCH_SYNC_DEFAULTS_DESCRIPTION = "Sync waits default to 30s in a main session (max `bash.watch_sync_max_ms`, 120s by default); in a delegated session a sync wait without a timeout waits until the command finishes";
+var WATCH_TIMEOUT_PARAM_DESCRIPTION = "Sync-only timeout in milliseconds. In a main session: default 30000, max `bash.watch_sync_max_ms` (120000 by default). In a delegated session: omit it to wait until the command finishes; a value you pass is used as given.";
 function resolveWatchTimeoutMs(requestedMs, role, capMs) {
-  const fallback = role === "worker" ? capMs : DEFAULT_PRIMARY_WATCH_TIMEOUT_MS;
-  return Math.min(requestedMs ?? fallback, capMs);
+  if (role === "worker")
+    return requestedMs;
+  return Math.min(requestedMs ?? DEFAULT_PRIMARY_WATCH_TIMEOUT_MS, capMs);
+}
+function maxWatchTimeoutMs(role, capMs) {
+  return role === "worker" ? MAX_WATCH_TIMEOUT_MS : capMs;
+}
+function watchPollDelayMs(elapsedMs) {
+  if (elapsedMs < 5000)
+    return 100;
+  if (elapsedMs < 30000)
+    return 250;
+  if (elapsedMs < 120000)
+    return 500;
+  return 1000;
+}
+var watchClock = {
+  now: () => performance.now(),
+  sleep: abortableSleep
+};
+function abortableSleep(ms, signal) {
+  if (signal?.aborted)
+    return Promise.resolve();
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
 }
-function watchTimeoutSteer(role, capMs, timeoutParam = "timeoutMs") {
+function formatWatchWaited(elapsedMs, limitMs, capMs) {
+  let limit;
+  if (limitMs === undefined)
+    limit = "no limit: waits until the command finishes";
+  else if (capMs !== undefined && limitMs >= capMs)
+    limit = `limit ${limitMs}ms, the bash.watch_sync_max_ms cap`;
+  else
+    limit = `limit ${limitMs}ms`;
+  return `Waited ${Math.round(elapsedMs)}ms (${limit})`;
+}
+function watchTimeoutSteer(role, timeoutParam = "timeoutMs") {
   if (role === "worker") {
-    return `The command is still running; this is not a failure. Watch again (${timeoutParam} up to ${capMs}) and don't report a result until it finishes.`;
+    return `The command is still running; this is not a failure. Watch again and don't report a result until it finishes; a bash_watch without ${timeoutParam} waits until the command finishes.`;
   }
   return "The command is still running; this is not a failure. Watch again, do other work, or end your turn: the completion reminder wakes you.";
 }
+var WATCH_UNAVAILABLE_GIVE_UP_MS = 120000;
+var WORKER_KEEP_WAITING = "Call bash_watch again to keep waiting; don't report a result until the command finishes.";
+function interruptedWatchTail(role, primaryTail) {
+  return role === "worker" ? `The task is still running. ${WORKER_KEEP_WAITING}` : primaryTail;
+}
+function runningTaskStatusHint(role) {
+  return role === "worker" ? "To wait for it, call bash_watch; don't poll." : "A completion reminder will be delivered automatically; don't poll.";
+}
+function watchUnavailableSteer(role) {
+  const unknown = "the bridge was busy, so task state is unknown.";
+  if (role === "worker")
+    return `${unknown} ${WORKER_KEEP_WAITING}`;
+  return `${unknown} Do not poll; let the task's completion notification wake the session, or use one bash_status snapshot on the next normal tool call.`;
+}
 var CONFLICT_HINT = `
 
 [Hint] Use aft_conflicts to see all conflict regions across files in a single call.`;
@@ -8334,7 +8388,7 @@ import { existsSync } from "node:fs";
 import { join as join3 } from "node:path";
 
 // ../aft-bridge/dist/child-process.js
-import { execFileSync as nodeExecFileSync, execSync as nodeExecSync, spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "node:child_process";
+import { execFile as nodeExecFile, execFileSync as nodeExecFileSync, execSync as nodeExecSync, spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "node:child_process";
 var HIDDEN = { windowsHide: true };
 function withWindowsHidden(args, takesArgv) {
   const out = [...args];
@@ -8356,6 +8410,7 @@ function hidden(resolve, takesArgv) {
 }
 var spawn = hidden(() => nodeSpawn, true);
 var spawnSync = hidden(() => nodeSpawnSync, true);
+var execFile = hidden(() => nodeExecFile, true);
 var execFileSync = hidden(() => nodeExecFileSync, true);
 var execSync = hidden(() => nodeExecSync, false);
 
@@ -8811,6 +8866,9 @@ function isPassiveCommand(command) {
   return PASSIVE_COMMANDS.has(command);
 }
 
+// ../aft-bridge/dist/transport.js
+var WORKER_SESSION_FIELD = "worker_session";
+
 // ../aft-bridge/dist/bridge.js
 var DEFAULT_BRIDGE_TIMEOUT_MS = 30000;
 var BRIDGE_HANG_TIMEOUT_THRESHOLD = 2;
@@ -9229,9 +9287,11 @@ class BinaryBridge {
       params.edit_slot_survives = editSlotSurvives;
       this.logHashlineRegistrationCarrier("tool_call", sessionId, editSlotSurvives);
     }
-    const { preview, ...sendOptions } = options ?? {};
+    const { preview, workerSession, ...sendOptions } = options ?? {};
     if (preview === true)
       params.preview = true;
+    if (workerSession === true)
+      params[WORKER_SESSION_FIELD] = true;
     return await this.send("tool_call", params, Object.keys(sendOptions).length > 0 ? sendOptions : undefined);
   }
   async sendWithVersionMismatchRetry(command, params, options, canRetryAfterVersionSwap) {
@@ -9300,7 +9360,7 @@ class BinaryBridge {
       if (command === "cancel_request" || Object.hasOwn(params, "command") || Object.hasOwn(params, "method")) {
         const nested = { ...params };
         const reserved = {};
-        for (const key of ["session_id", "lsp_hints"]) {
+        for (const key of ["session_id", "lsp_hints", WORKER_SESSION_FIELD]) {
           if (Object.hasOwn(nested, key)) {
             reserved[key] = nested[key];
             delete nested[key];
@@ -9682,17 +9742,30 @@ class BinaryBridge {
     }
   }
   onStderrData(data) {
-    this.stderrBuffer += data;
-    let newlineIdx;
-    while ((newlineIdx = this.stderrBuffer.indexOf(`
-`)) !== -1) {
-      const line = this.stderrBuffer.slice(0, newlineIdx).replace(/\r$/, "");
-      this.stderrBuffer = this.stderrBuffer.slice(newlineIdx + 1);
-      if (!line || !shouldSurfaceStderrLine(line))
-        continue;
-      const tagged = tagStderrLine(line);
-      this.logVia(tagged);
-      this.pushStderrLine(tagged);
+    const partialLimit = 64 * 1024;
+    let offset = 0;
+    while (offset < data.length) {
+      const newline = data.indexOf(`
+`, offset);
+      const end = newline < 0 ? data.length : newline;
+      while (offset < end) {
+        const count = Math.min(partialLimit - this.stderrBuffer.length, end - offset);
+        this.stderrBuffer += data.slice(offset, offset + count);
+        offset += count;
+        if (this.stderrBuffer.length === partialLimit) {
+          const last = this.stderrBuffer.charCodeAt(this.stderrBuffer.length - 1);
+          const carry = last >= 55296 && last <= 56319 ? this.stderrBuffer.slice(-1) : "";
+          const fragment = carry ? this.stderrBuffer.slice(0, -1) : this.stderrBuffer;
+          const tagged = tagStderrLine(`${fragment} [stderr record truncated into bounded fragments; ${Buffer.byteLength(fragment)} bytes shown, continuation follows]`);
+          this.stderrBuffer = carry;
+          this.logVia(tagged);
+          this.pushStderrLine(tagged);
+        }
+      }
+      if (newline < 0)
+        break;
+      this.flushStderrBuffer();
+      offset = newline + 1;
     }
   }
   flushStderrBuffer() {
@@ -10070,7 +10143,8 @@ function renderCallersGroupLines(group, theme) {
   const bySymbolProvenance = new Map;
   for (const caller of callers) {
     const symbol = asString(caller.symbol) ?? "(unknown)";
-    const provenanceKey = asString(caller.resolved_by) === "name_match" ? `${symbol}\x00name_match` : `${symbol}\x00exact`;
+    const via = asString(caller.via) ?? "";
+    const provenanceKey = asString(caller.resolved_by) === "name_match" ? `${symbol}\x00${via}\x00name_match` : `${symbol}\x00${via}\x00exact`;
     const line = asNumber(caller.line);
     const bucket = bySymbolProvenance.get(provenanceKey) ?? [];
     if (line !== undefined)
@@ -10079,12 +10153,13 @@ function renderCallersGroupLines(group, theme) {
   }
   const keys = [...bySymbolProvenance.keys()].sort((a, b) => a.localeCompare(b));
   for (const key of keys) {
-    const symbol = key.split("\x00")[0] ?? "(unknown)";
+    const [symbol = "(unknown)", via = ""] = key.split("\x00");
     const isNameMatch = key.endsWith("\x00name_match");
     const lineNums = (bySymbolProvenance.get(key) ?? []).sort((a, b) => a - b);
     const linePart = lineNums.length > 0 ? lineNums.map(String).join(", ") : "?";
     const marker = isNameMatch ? ` ${theme.fg("warning", "~")}` : "";
-    lines.push(`  ↳ ${symbol}:${linePart}${marker}`);
+    const viaPart = via ? ` via ${via}` : "";
+    lines.push(`  ↳ ${symbol}:${linePart}${marker}${viaPart}`);
   }
   return lines;
 }
@@ -10118,6 +10193,9 @@ function formatCallgraphSections(op, response, theme = PLAIN_CALLGRAPH_THEME, op
       sections.push(renderCallersGroupLines(group, theme).join(`
 `));
     });
+    const macroNote = asString(asRecord(record.macro_note)?.message);
+    if (macroNote)
+      sections.push(theme.fg("warning", macroNote));
     return sections;
   }
   if (op === "trace_to_symbol") {
@@ -10331,6 +10409,35 @@ function coerceJsonCollectionParam(value, field) {
   }
   throw new Error(`${field} must be ${shape} (got an invalid type)`);
 }
+function isBlankParam(value) {
+  if (typeof value === "string")
+    return value.trim().length === 0;
+  return isEmptyParam(value);
+}
+function usableZoomTargets(targets) {
+  if (isEmptyParam(targets))
+    return [];
+  const entries = Array.isArray(targets) ? targets : [targets];
+  return entries.filter((entry) => {
+    if (entry === null || entry === undefined)
+      return false;
+    if (typeof entry !== "object")
+      return true;
+    const record = entry;
+    return !(isBlankParam(record.path) && isBlankParam(record.filePath) && isBlankParam(record.symbol));
+  });
+}
+function isFindReplaceOnlyEdit(args) {
+  const absent = (value) => value === undefined || value === null || value === "";
+  const absentLine = (value) => absent(value) || value === 0;
+  const edits = args.edits;
+  return Array.isArray(edits) && edits.length > 0 && absent(args.appendContent) && absent(args.symbol) && absent(args.content) && edits.every((entry) => {
+    if (entry === null || typeof entry !== "object")
+      return false;
+    const item = entry;
+    return typeof item.oldString === "string" && (absent(item.newString) || typeof item.newString === "string") && absentLine(item.startLine) && absentLine(item.endLine) && absent(item.content);
+  });
+}
 // ../aft-bridge/dist/config-error.js
 import { homedir as homedir6 } from "node:os";
 import { isAbsolute as isAbsolute2, join as join6 } from "node:path";
@@ -10438,9 +10545,366 @@ function formatDroppedKeyWarnings(dropped) {
   }
   return dropped.map((item) => `Ignoring ${item.key} from ${item.tier} config (${item.reason})`);
 }
+// ../aft-bridge/dist/config-watch.js
+import { readFileSync as readFileSync3, statSync as statSync3, watch } from "node:fs";
+import { basename, dirname } from "node:path";
+var CONFIG_WATCH_DEBOUNCE_MS = 150;
+var CONFIG_LIVE_KEEP_NOTE = "AFT keeps using the last valid configuration until the file is fixed.";
+function pathKey(name) {
+  const segments = name.split(".");
+  return {
+    name,
+    read(config) {
+      let value = config;
+      for (const segment of segments) {
+        if (value === null || typeof value !== "object")
+          return;
+        value = value[segment];
+      }
+      return value;
+    },
+    write(config, value) {
+      const set = (target, index) => {
+        const copy = target !== null && typeof target === "object" && !Array.isArray(target) ? { ...target } : {};
+        const segment = segments[index];
+        if (index === segments.length - 1) {
+          if (value === undefined)
+            delete copy[segment];
+          else
+            copy[segment] = value;
+        } else {
+          copy[segment] = set(copy[segment], index + 1);
+        }
+        return copy;
+      };
+      return set(config, 0);
+    }
+  };
+}
+function bashKey(name, resolveBash) {
+  return {
+    name: `bash.${name}`,
+    read: (config) => resolveBash(config)[name],
+    write(config, value) {
+      const resolved = { ...resolveBash(config), [name]: value };
+      for (const key of Object.keys(resolved)) {
+        if (resolved[key] === undefined)
+          delete resolved[key];
+      }
+      return { ...config, bash: resolved };
+    }
+  };
+}
+function aftLiveConfigKeys(resolveBash) {
+  return [
+    pathKey("configure_warnings_delivery"),
+    pathKey("restrict_to_project_root"),
+    pathKey("inspect.diagnostics_timeout_ms"),
+    pathKey("inspect.tier2_idle_minutes"),
+    bashKey("foreground_wait_window_ms", resolveBash),
+    bashKey("host_fallback", resolveBash),
+    bashKey("subagent_background", resolveBash),
+    bashKey("watch_sync_max_ms", resolveBash)
+  ];
+}
+function sameValue(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+function flattenLeaves(value, prefix, out) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0 && prefix)
+      out.set(prefix, "{}");
+    for (const [key, child] of entries) {
+      flattenLeaves(child, prefix ? `${prefix}.${key}` : key, out);
+    }
+    return;
+  }
+  if (prefix)
+    out.set(prefix, JSON.stringify(value));
+}
+function applyLiveConfigKeys(current, next, keys, baseline = current) {
+  let config = current;
+  const applied = [];
+  for (const key of keys) {
+    const value = key.read(next);
+    if (sameValue(key.read(current), value))
+      continue;
+    config = key.write(config, value);
+    applied.push(key.name);
+  }
+  const before = new Map;
+  const after = new Map;
+  flattenLeaves(baseline, "", before);
+  flattenLeaves(next, "", after);
+  const liveNames = keys.map((key) => key.name);
+  const isLive = (leaf) => liveNames.some((name) => leaf === name || leaf.startsWith(`${name}.`));
+  const deferred = new Set;
+  for (const leaf of new Set([...before.keys(), ...after.keys()])) {
+    if (before.get(leaf) === after.get(leaf) || isLive(leaf))
+      continue;
+    deferred.add(leaf);
+  }
+  return { config, applied, deferred: [...deferred].sort() };
+}
+function readTextOrNull(path) {
+  try {
+    return readFileSync3(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+var CONFIG_WATCH_REVALIDATE_MS = 2000;
+var CONFIG_WATCH_REJECTED_RETRIES = 3;
+var CONFIG_WATCH_MAX_DELAY_MS = 1000;
+function identityOf(dir) {
+  try {
+    const stat = statSync3(dir, { bigint: true });
+    const base = `${stat.dev}:${stat.ino}`;
+    return process.platform === "win32" ? base : `${base}:${stat.birthtimeNs}`;
+  } catch {
+    return null;
+  }
+}
+function watchDirFor(file) {
+  let dir = dirname(file);
+  while (dir !== dirname(dir) && identityOf(dir) === null)
+    dir = dirname(dir);
+  return dir;
+}
+function watchAftConfigFiles(options) {
+  const debounceMs = options.debounceMs ?? CONFIG_WATCH_DEBOUNCE_MS;
+  const lastSeen = new Map;
+  for (const path of options.paths) {
+    if (options.initialTexts)
+      lastSeen.set(path, options.initialTexts[path] ?? null);
+    else
+      lastSeen.set(path, options.checkAtStart ? undefined : readTextOrNull(path));
+  }
+  let timer = null;
+  let firstPendingAt = null;
+  let stopped = false;
+  const watchers = new Map;
+  const watchImpl = options.watchImpl ?? watch;
+  let rejectedRetries = 0;
+  const check = () => {
+    timer = null;
+    firstPendingAt = null;
+    if (stopped)
+      return;
+    revalidate();
+    const seen = new Map;
+    for (const path of options.paths) {
+      const text = readTextOrNull(path);
+      if (text !== lastSeen.get(path))
+        seen.set(path, text);
+    }
+    if (seen.size === 0)
+      return;
+    const outcome = options.onChange();
+    if (outcome === false) {
+      if (rejectedRetries < CONFIG_WATCH_REJECTED_RETRIES) {
+        rejectedRetries += 1;
+        retryTimer = setTimeout(check, CONFIG_WATCH_MAX_DELAY_MS);
+        retryTimer.unref?.();
+      }
+      return;
+    }
+    rejectedRetries = 0;
+    if (outcome instanceof Map) {
+      for (const path of options.paths)
+        lastSeen.set(path, outcome.get(path) ?? null);
+    } else {
+      for (const [path, text] of seen)
+        lastSeen.set(path, text);
+    }
+  };
+  let retryTimer = null;
+  const schedule = () => {
+    if (stopped)
+      return;
+    const now = Date.now();
+    firstPendingAt ??= now;
+    if (timer)
+      clearTimeout(timer);
+    const delay = Math.max(0, Math.min(debounceMs, firstPendingAt + CONFIG_WATCH_MAX_DELAY_MS - now));
+    timer = setTimeout(check, delay);
+    timer.unref?.();
+  };
+  function revalidate() {
+    const wanted = new Set(options.paths.map(watchDirFor));
+    let moved = false;
+    for (const [dir, entry] of watchers) {
+      if (!wanted.has(dir) || entry.stale || identityOf(dir) !== entry.identity) {
+        entry.watcher.close();
+        watchers.delete(dir);
+        moved = true;
+      }
+    }
+    for (const dir of wanted) {
+      if (watchers.has(dir))
+        continue;
+      try {
+        const identity = identityOf(dir);
+        options.beforeWatchForTest?.(dir);
+        const name = basename(dir);
+        const watcher = watchImpl(dir, { persistent: false }, (event, filename) => {
+          if (event === "rename" && filename === name) {
+            const current = watchers.get(dir);
+            if (current && current.watcher === watcher)
+              current.stale = true;
+          }
+          schedule();
+        });
+        if (identityOf(dir) !== identity) {
+          watcher.close();
+          moved = true;
+          continue;
+        }
+        const entry = { watcher, identity, stale: false };
+        entry.watcher.on("error", () => {
+          entry.watcher.close();
+          if (watchers.get(dir) === entry)
+            watchers.delete(dir);
+          schedule();
+        });
+        watchers.set(dir, entry);
+        moved = true;
+      } catch {}
+    }
+    return moved;
+  }
+  revalidate();
+  if (options.checkAtStart)
+    check();
+  const revalidateTimer = setInterval(() => {
+    if (!stopped && revalidate())
+      schedule();
+  }, CONFIG_WATCH_REVALIDATE_MS);
+  revalidateTimer.unref?.();
+  return () => {
+    stopped = true;
+    if (timer)
+      clearTimeout(timer);
+    if (retryTimer)
+      clearTimeout(retryTimer);
+    clearInterval(revalidateTimer);
+    for (const entry of watchers.values())
+      entry.watcher.close();
+    watchers.clear();
+  };
+}
+function aftLiveSecurityKeys(keys) {
+  const byName = new Map(keys.map((key) => [key.name, key]));
+  const pick = (name) => {
+    const key = byName.get(name);
+    if (!key)
+      throw new Error(`unknown live config key ${name}`);
+    return key;
+  };
+  return [
+    {
+      key: pick("restrict_to_project_root"),
+      loosens: (current, next) => current === true && next !== true
+    },
+    {
+      key: pick("bash.host_fallback"),
+      loosens: (current, next) => current !== true && next === true
+    }
+  ];
+}
+function liveConfigReloadLogLine(applied, deferred) {
+  let line = "config reload";
+  if (applied.length > 0)
+    line += ` applied=[${applied.join(",")}]`;
+  if (deferred.length > 0) {
+    line += ` deferred=[${deferred.join(",")}] (deferred keys apply on next connect/restart)`;
+  }
+  return line;
+}
+function startLiveConfigReload(options) {
+  const baseline = options.getConfig();
+  let lastError = null;
+  let acceptedSources = new Set(options.initialSources);
+  let acceptedProjectText = options.initialProjectText ?? null;
+  let acceptedTexts;
+  const reload = () => {
+    let loaded = options.load();
+    if (loaded.ok) {
+      const read = new Set(loaded.sources);
+      const deleted = [...acceptedSources].find((path) => !read.has(path));
+      if (deleted !== undefined) {
+        loaded = { ok: false, message: `AFT config at ${deleted} was deleted` };
+      } else {
+        acceptedSources = read;
+      }
+    }
+    if (!loaded.ok) {
+      const message = `${loaded.message.trim().replace(/[.!?]?$/, ".")} ${CONFIG_LIVE_KEEP_NOTE}`;
+      if (message !== lastError) {
+        lastError = message;
+        options.reportError(message);
+      }
+      return null;
+    }
+    lastError = null;
+    acceptedTexts = loaded.texts;
+    const current = options.getConfig();
+    let next = loaded.config;
+    const held = [];
+    const projectText = loaded.projectText ?? null;
+    if (loaded.projectText !== undefined && projectText !== acceptedProjectText) {
+      for (const security of options.securityKeys ?? []) {
+        const now = security.key.read(current);
+        if (security.loosens(now, security.key.read(next))) {
+          next = security.key.write(next, now);
+          held.push(security.key.name);
+        }
+      }
+      if (held.length === 0)
+        acceptedProjectText = projectText;
+    }
+    const result = applyLiveConfigKeys(current, next, options.keys, baseline);
+    if (result.applied.length > 0)
+      options.setConfig(result.config);
+    if (result.applied.length > 0 || result.deferred.length > 0 || held.length > 0) {
+      let line = liveConfigReloadLogLine(result.applied, result.deferred);
+      if (held.length > 0) {
+        line += ` held=[${held.join(",")}] (not loosened while the project file differs from the one the published values came from; the next restart applies them)`;
+      }
+      options.log(line);
+    }
+    return { ...result, held };
+  };
+  const safeReload = () => {
+    try {
+      acceptedTexts = undefined;
+      if (reload() === null)
+        return false;
+      const texts = acceptedTexts;
+      if (!texts)
+        return true;
+      return new Map(options.paths.map((path) => [path, texts[path] ?? null]));
+    } catch (err) {
+      options.reportError(`AFT config reload failed: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }
+  };
+  if (options.watch === false) {
+    return { reload, stop: () => {} };
+  }
+  const stop = watchAftConfigFiles({
+    paths: options.paths,
+    debounceMs: options.debounceMs,
+    onChange: safeReload,
+    initialTexts: options.initialTexts,
+    checkAtStart: true
+  });
+  return { reload, stop };
+}
 // ../aft-bridge/dist/downloader.js
 import { createHash as createHash2, randomUUID } from "node:crypto";
-import { chmodSync, closeSync, copyFileSync, createWriteStream, existsSync as existsSync3, mkdirSync, openSync, readdirSync, readFileSync as readFileSync3, renameSync as renameSync2, rmSync, statSync as statSync3, unlinkSync as unlinkSync2, writeSync } from "node:fs";
+import { chmodSync, closeSync, copyFileSync, createWriteStream, existsSync as existsSync3, mkdirSync, openSync, readdirSync, readFileSync as readFileSync4, renameSync as renameSync2, rmSync, statSync as statSync4, unlinkSync as unlinkSync2, writeSync } from "node:fs";
 import { hostname } from "node:os";
 import { join as join7 } from "node:path";
 import { Readable } from "node:stream";
@@ -10792,7 +11256,7 @@ function isReclaimableDownloadLock(owner, ageMs, staleMs) {
 }
 function reclaimDownloadLock(lockPath, expectedOwner) {
   try {
-    if (readFileSync3(lockPath, "utf-8") !== expectedOwner)
+    if (readFileSync4(lockPath, "utf-8") !== expectedOwner)
       return false;
     rmSync(lockPath, { force: true });
     return true;
@@ -10810,7 +11274,7 @@ function sweepStaleDownloadTemps(versionedCacheDir, binaryName) {
         continue;
       }
       const tempPath = join7(versionedCacheDir, entry.name);
-      const ageMs = Date.now() - statSync3(tempPath).mtimeMs;
+      const ageMs = Date.now() - statSync4(tempPath).mtimeMs;
       if (Math.abs(ageMs) > DOWNLOAD_LOCK_STALE_MS)
         unlinkSync2(tempPath);
     }
@@ -10832,7 +11296,7 @@ async function acquireDownloadLock(lockPath, timing = {}) {
       }
       return () => {
         try {
-          if (readFileSync3(lockPath, "utf-8") === owner) {
+          if (readFileSync4(lockPath, "utf-8") === owner) {
             rmSync(lockPath, { force: true });
           }
         } catch {}
@@ -10844,8 +11308,8 @@ async function acquireDownloadLock(lockPath, timing = {}) {
       let existingOwner;
       let ageMs;
       try {
-        existingOwner = readFileSync3(lockPath, "utf-8");
-        ageMs = Date.now() - statSync3(lockPath).mtimeMs;
+        existingOwner = readFileSync4(lockPath, "utf-8");
+        ageMs = Date.now() - statSync4(lockPath).mtimeMs;
       } catch (readErr) {
         if (readErr.code === "ENOENT")
           continue;
@@ -10895,7 +11359,7 @@ async function fetchLatestTag() {
 }
 // ../aft-bridge/dist/durable-log.js
 import { appendFile, chmod, mkdir, rename, rm, stat } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname as dirname2 } from "node:path";
 var DEFAULT_LOG_BYTES = 32 * 1024 * 1024;
 var DEFAULT_LOG_GENERATIONS = 1;
 var LOG_DIR_MODE = 448;
@@ -10908,6 +11372,10 @@ class RotatingLogSink {
   queue = Promise.resolve();
   disabled = false;
   failureReported = false;
+  queuedBytes = 0;
+  queuedRecords = 0;
+  droppedBytes = 0;
+  overflowQueued = false;
   constructor(path, options = {}) {
     this.path = path;
     this.maxBytes = options.maxBytes ?? DEFAULT_LOG_BYTES;
@@ -10916,7 +11384,34 @@ class RotatingLogSink {
   append(data) {
     if (this.disabled || data.length === 0)
       return;
-    this.queue = this.queue.then(() => this.write(data)).catch((error) => {
+    const bytes = Buffer.byteLength(data);
+    const overflow = this.queuedBytes + bytes > 1024 * 1024 || this.queuedRecords >= 4096;
+    if (overflow) {
+      this.droppedBytes += bytes;
+      if (this.overflowQueued)
+        return;
+      this.overflowQueued = true;
+      data = "";
+    } else {
+      this.queuedBytes += bytes;
+      this.queuedRecords += 1;
+    }
+    this.queue = this.queue.then(async () => {
+      if (overflow) {
+        const dropped = this.droppedBytes;
+        this.droppedBytes = 0;
+        this.overflowQueued = false;
+        await this.write(`[aft-plugin] durable log queue overflow: dropped ${dropped} bytes (1MiB/4096-record pending limit); reduce diagnostic volume.
+`);
+      } else {
+        try {
+          await this.write(data);
+        } finally {
+          this.queuedBytes -= bytes;
+          this.queuedRecords -= 1;
+        }
+      }
+    }).catch((error) => {
       this.disabled = true;
       if (!this.failureReported) {
         this.failureReported = true;
@@ -10931,8 +11426,8 @@ class RotatingLogSink {
     await this.queue;
   }
   async write(data) {
-    const dir = dirname(this.path);
-    await mkdir(dirname(dir), { recursive: true });
+    const dir = dirname2(this.path);
+    await mkdir(dirname2(dir), { recursive: true });
     try {
       await mkdir(dir, { mode: LOG_DIR_MODE });
     } catch (error) {
@@ -11038,6 +11533,15 @@ function formatEditSummary(data) {
   let s = `Edited (${detail}).`;
   if (data.formatted)
     s += formatAutoFormattedSuffix(data);
+  const fuzzy = data.fuzzy_matches ?? (data.fuzzy_match ? [data.fuzzy_match] : []);
+  for (const match of fuzzy) {
+    s += `
+Fuzzy match (pass ${match.pass}).`;
+    for (const [index, text] of match.replaced_text.entries()) {
+      s += `
+Replaced text ${index + 1}: ${text}`;
+    }
+  }
   return s;
 }
 function formatAutoFormattedSuffix(data) {
@@ -12766,7 +13270,7 @@ function reverseRequestMethod(body) {
   }
 }
 // ../aft-bridge/dist/subc-transport.js
-import { existsSync as existsSync4, statSync as statSync4 } from "node:fs";
+import { existsSync as existsSync4, statSync as statSync5 } from "node:fs";
 
 // ../aft-bridge/dist/lifecycle-registry.js
 import { lstat } from "node:fs/promises";
@@ -13238,6 +13742,13 @@ class SubcTransportShuttingDownError extends SubcCallError {
     this.name = "SubcTransportShuttingDownError";
   }
 }
+
+class ReconnectKeyChangedError extends Error {
+  constructor() {
+    super("the subc daemon restarted and its connection key changed; the reconnect did not complete within the deadline, retry");
+    this.name = "ReconnectKeyChangedError";
+  }
+}
 function isSubcClientClosedError(error) {
   return error instanceof SubcError && error.message === "client closed";
 }
@@ -13289,6 +13800,7 @@ var RECONNECT_RETRY_FLOOR_MS = 100;
 var RECONNECT_RETRY_CAP_MS = 2000;
 var SUBC_DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 var ROUTE_OPEN_RELOAD_WAIT_CEILING_MS = 45000;
+var CALL_DEADLINE_EXPIRED = Symbol("call deadline expired");
 function reloadWaitExhaustedSuffix(callDeadlineMs) {
   if (callDeadlineMs > ROUTE_OPEN_RELOAD_WAIT_CEILING_MS) {
     const ceilingSeconds = ROUTE_OPEN_RELOAD_WAIT_CEILING_MS / 1000;
@@ -13641,7 +14153,16 @@ function absentRootError(root) {
   return new SubcError(`invalid route project root: project root does not exist: ${root}`, "config_divergence");
 }
 function reloadWindowExhaustedError(error, callDeadlineMs) {
-  const suffix = reloadWaitExhaustedSuffix(callDeadlineMs);
+  return withDeadlineSuffix(error, reloadWaitExhaustedSuffix(callDeadlineMs));
+}
+function callDeadlinePassedError(lastError, callDeadlineMs) {
+  const seconds = Math.round(callDeadlineMs / 100) / 10;
+  const suffix = ` The AFT daemon module did not return within this call's ${seconds}s deadline.`;
+  if (lastError !== undefined)
+    return withDeadlineSuffix(lastError, suffix);
+  return new SubcError(`route to module '${AFT_MODULE_ID}' was not ready before the call ran out of time.${suffix}`, REQUEST_DEADLINE_CODE);
+}
+function withDeadlineSuffix(error, suffix) {
   if (error instanceof Error) {
     try {
       error.message += suffix;
@@ -13730,6 +14251,8 @@ class SubcTransport {
       body.edit_slot_survives = editSlotSurvives;
     if (preview === true)
       body.preview = true;
+    if (options?.workerSession === true)
+      body[WORKER_SESSION_FIELD] = true;
     const reply = await this.pool.routeRequest(this.identityFor(sessionId), body, timeoutMs, onProgress, this.generation, abortSignal);
     return reliftReply(reply);
   }
@@ -13740,7 +14263,10 @@ class SubcTransport {
     }
     const { timeoutMs, onProgress, abortSignal } = this.splitOptions(options);
     const session = typeof params.session_id === "string" ? params.session_id : undefined;
-    const body = { name: command, arguments: params };
+    const { [WORKER_SESSION_FIELD]: workerSession, ...args } = params;
+    const body = { name: command, arguments: args };
+    if (workerSession === true)
+      body[WORKER_SESSION_FIELD] = true;
     const editSlotSurvives = this.pool.getEditSlotSurvives();
     if (editSlotSurvives !== undefined)
       body.edit_slot_survives = editSlotSurvives;
@@ -13777,6 +14303,7 @@ class SubcTransportPool {
   lifecycleRegistration = null;
   outerFacadeEvictor;
   client = null;
+  hadWorkingClient = false;
   connecting = null;
   routeReopenRetryDelayMs = RECONNECT_RETRY_FLOOR_MS;
   routeReopenRetry = null;
@@ -13880,7 +14407,7 @@ class SubcTransportPool {
   rootCanAttach(root) {
     let directoryExists = false;
     try {
-      directoryExists = statSync4(root).isDirectory();
+      directoryExists = statSync5(root).isDirectory();
     } catch {}
     if (directoryExists) {
       this.dormantRoots.delete(root);
@@ -14220,6 +14747,11 @@ class SubcTransportPool {
     return this.rootReapedError(record);
   }
   async routeRequest(identity, body, timeoutMs, onProgress, expectedGeneration, abortSignal) {
+    const callStartedAt = performance.now();
+    const callDeadlineMs = timeoutMs ?? SUBC_DEFAULT_REQUEST_TIMEOUT_MS;
+    let scheduledDelayMs = 0;
+    const spentMs = () => Math.max(performance.now() - callStartedAt, scheduledDelayMs);
+    const remainingMs = () => callDeadlineMs - spentMs();
     const root = asCanonicalRootPath(identity.project_root);
     let generation = expectedGeneration;
     if (this.lifecycleEnabled()) {
@@ -14235,7 +14767,49 @@ class SubcTransportPool {
     try {
       let client;
       try {
-        client = await this.ensureClient();
+        let keyChanged;
+        while (true) {
+          const remaining = remainingMs();
+          if (remaining <= 0)
+            throw keyChanged ?? callDeadlinePassedError(undefined, callDeadlineMs);
+          let timer;
+          try {
+            const acquired = await Promise.race([
+              this.ensureClient(),
+              new Promise((resolve) => {
+                timer = setTimeout(() => resolve(CALL_DEADLINE_EXPIRED), remaining);
+              })
+            ]);
+            if (acquired === CALL_DEADLINE_EXPIRED) {
+              throw keyChanged ?? callDeadlinePassedError(undefined, callDeadlineMs);
+            }
+            client = acquired;
+            break;
+          } catch (error) {
+            if (!(error instanceof ReconnectKeyChangedError))
+              throw error;
+            keyChanged = error;
+            if (spentMs() + this.nextRouteReopenDelayMs() >= callDeadlineMs)
+              throw error;
+          } finally {
+            clearTimeout(timer);
+          }
+          const { delayMs, wait } = this.waitForRouteReopenBackoff();
+          scheduledDelayMs = spentMs() + delayMs;
+          let retryTimer;
+          try {
+            const waited = await Promise.race([
+              wait,
+              new Promise((resolve) => {
+                retryTimer = setTimeout(() => resolve(CALL_DEADLINE_EXPIRED), callDeadlineMs - (performance.now() - callStartedAt));
+              })
+            ]);
+            if (waited === CALL_DEADLINE_EXPIRED)
+              throw keyChanged;
+          } finally {
+            clearTimeout(retryTimer);
+          }
+        }
         this.assertRecordLive(record);
       } catch (error) {
         throw this.annotateReapError(error, record);
@@ -14270,21 +14844,39 @@ class SubcTransportPool {
           throw error;
         }
       };
-      const callDeadlineMs = timeoutMs ?? SUBC_DEFAULT_REQUEST_TIMEOUT_MS;
       const reloadWaitBudgetMs = Math.min(callDeadlineMs, ROUTE_OPEN_RELOAD_WAIT_CEILING_MS);
-      let reloadWaitedMs = 0;
+      let lastRefusal;
+      const openRouteWithinDeadline = async () => {
+        const remaining = remainingMs();
+        if (remaining <= 0)
+          throw callDeadlinePassedError(lastRefusal, callDeadlineMs);
+        let timer;
+        const expired = new Promise((resolve) => {
+          timer = setTimeout(() => resolve(CALL_DEADLINE_EXPIRED), remaining);
+        });
+        try {
+          const opened = await Promise.race([openRoute(), expired]);
+          if (opened === CALL_DEADLINE_EXPIRED) {
+            throw callDeadlinePassedError(lastRefusal, callDeadlineMs);
+          }
+          return opened;
+        } finally {
+          clearTimeout(timer);
+        }
+      };
       const openRouteAfterReloadWindow = async () => {
         while (true) {
           try {
-            return await openRoute();
+            return await openRouteWithinDeadline();
           } catch (error) {
             if (!isRouteOpenReloadWindowError(error))
               throw error;
-            if (reloadWaitedMs + this.nextRouteReopenDelayMs() >= reloadWaitBudgetMs) {
+            lastRefusal = error;
+            if (spentMs() + this.nextRouteReopenDelayMs() >= reloadWaitBudgetMs) {
               throw reloadWindowExhaustedError(error, callDeadlineMs);
             }
             const { delayMs, wait } = this.waitForRouteReopenBackoff();
-            reloadWaitedMs += delayMs;
+            scheduledDelayMs = spentMs() + delayMs;
             await wait;
           }
         }
@@ -14320,7 +14912,7 @@ class SubcTransportPool {
           route: routeLabel(entry.handle)
         });
       };
-      const requestOnRoute = async (route, entry) => {
+      const requestOnRoute = async (route, entry, requestTimeoutMs) => {
         this.assertRecordLive(record);
         if (abortSignal?.aborted) {
           clearRouteEntry(entry);
@@ -14336,8 +14928,10 @@ class SubcTransportPool {
         };
         abortSignal?.addEventListener("abort", onAbort, { once: true });
         try {
-          const requestTimeoutMs = reloadWaitedMs > 0 ? callDeadlineMs - reloadWaitedMs : timeoutMs;
-          const request = client.request(route, body, { timeoutMs: requestTimeoutMs, onProgress });
+          const request = client.request(route, body, {
+            timeoutMs: Math.ceil(requestTimeoutMs),
+            onProgress
+          });
           const reply = abortSignal ? await Promise.race([request, aborted]) : await request;
           if (!this.isCurrentSession(key, record)) {
             if (this.isReapInduced(record))
@@ -14358,8 +14952,11 @@ class SubcTransportPool {
       let reopened = false;
       let retriedAbsentRoute = false;
       while (true) {
+        const requestTimeoutMs = remainingMs();
+        if (requestTimeoutMs <= 0)
+          throw callDeadlinePassedError(lastRefusal, callDeadlineMs);
         try {
-          const reply = await requestOnRoute(routeAndEntry.route, routeAndEntry.entry);
+          const reply = await requestOnRoute(routeAndEntry.route, routeAndEntry.entry, requestTimeoutMs);
           if (reopened)
             this.resetRouteReopenBackoff();
           return reply;
@@ -14369,11 +14966,12 @@ class SubcTransportPool {
           const ownsRoute = this.isCurrentSession(key, record) && this.client === client;
           if (ownsRoute && isRouteRequestReloadRefusal(error)) {
             clearRouteEntry(routeAndEntry.entry);
-            if (reloadWaitedMs + this.nextRouteReopenDelayMs() >= reloadWaitBudgetMs) {
+            lastRefusal = error;
+            if (spentMs() + this.nextRouteReopenDelayMs() >= reloadWaitBudgetMs) {
               throw reloadWindowExhaustedError(error, callDeadlineMs);
             }
             const { delayMs, wait } = this.waitForRouteReopenBackoff();
-            reloadWaitedMs += delayMs;
+            scheduledDelayMs = spentMs() + delayMs;
             await wait;
             routeAndEntry = await openRouteAfterReloadWindow();
             reopened = true;
@@ -14382,7 +14980,12 @@ class SubcTransportPool {
           if (ownsRoute && !retriedAbsentRoute && isRouteProvenAbsentError(error)) {
             retriedAbsentRoute = true;
             clearRouteEntry(routeAndEntry.entry);
-            await this.waitForRouteReopenBackoff().wait;
+            if (spentMs() + this.nextRouteReopenDelayMs() >= callDeadlineMs) {
+              throw callDeadlinePassedError(error, callDeadlineMs);
+            }
+            const { delayMs, wait } = this.waitForRouteReopenBackoff();
+            scheduledDelayMs = spentMs() + delayMs;
+            await wait;
             routeAndEntry = await openRouteAfterReloadWindow();
             reopened = true;
             continue;
@@ -14445,10 +15048,14 @@ class SubcTransportPool {
         throw new SubcTransportShuttingDownError;
       }
       this.client = client;
+      this.hadWorkingClient = true;
       this.transportFailures = 0;
       return client;
     }).catch((error) => {
       this.connecting = null;
+      if (this.hadWorkingClient && error instanceof AuthError) {
+        throw new ReconnectKeyChangedError;
+      }
       throw error;
     });
     return this.connecting;
@@ -16060,14 +16667,14 @@ function shouldInterruptWaitsForMessage(detachOnUserMessage, operatorText) {
   return detachOnUserMessage || containsStandaloneDetachKeyword(operatorText);
 }
 // ../aft-bridge/dist/migration.js
-import { closeSync as closeSync3, existsSync as existsSync8, mkdirSync as mkdirSync3, openSync as openSync3, readFileSync as readFileSync6, renameSync as renameSync4, rmSync as rmSync2, statSync as statSync5, unlinkSync as unlinkSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { closeSync as closeSync3, existsSync as existsSync8, mkdirSync as mkdirSync3, openSync as openSync3, readFileSync as readFileSync7, renameSync as renameSync4, rmSync as rmSync2, statSync as statSync6, unlinkSync as unlinkSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir10, tmpdir as tmpdir2 } from "node:os";
-import { basename, dirname as dirname4, join as join10, resolve as resolve6 } from "node:path";
+import { basename as basename2, dirname as dirname5, join as join10, resolve as resolve6 } from "node:path";
 
 // ../aft-bridge/dist/paths.js
-import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync4, renameSync as renameSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync5, renameSync as renameSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir8 } from "node:os";
-import { dirname as dirname2, isAbsolute as isAbsolute3, join as join8, resolve as resolve5 } from "node:path";
+import { dirname as dirname3, isAbsolute as isAbsolute3, join as join8, resolve as resolve5 } from "node:path";
 function homeDir3() {
   if (process.platform === "win32")
     return process.env.USERPROFILE || process.env.HOME || homedir8();
@@ -16127,7 +16734,7 @@ function repairRootScopedStorageFile(storageRoot, harness, fileName) {
   if (existsSync6(harnessPath) || !existsSync6(rootPath))
     return harnessPath;
   try {
-    mkdirSync2(dirname2(harnessPath), { recursive: true });
+    mkdirSync2(dirname3(harnessPath), { recursive: true });
     renameSync3(rootPath, harnessPath);
   } catch {}
   return harnessPath;
@@ -16139,7 +16746,7 @@ function shouldShowAnnouncement(storageRoot, harness, currentVersion) {
   let lastVersion = "";
   try {
     if (existsSync6(versionFile)) {
-      lastVersion = readFileSync4(versionFile, "utf-8").trim();
+      lastVersion = readFileSync5(versionFile, "utf-8").trim();
     }
   } catch {
     return false;
@@ -16148,7 +16755,7 @@ function shouldShowAnnouncement(storageRoot, harness, currentVersion) {
     return false;
   if (!lastVersion) {
     try {
-      mkdirSync2(dirname2(versionFile), { recursive: true });
+      mkdirSync2(dirname3(versionFile), { recursive: true });
       writeFileSync2(versionFile, currentVersion);
     } catch {}
     return false;
@@ -16160,7 +16767,7 @@ function markAnnouncementSeen(storageRoot, harness, currentVersion) {
     return;
   const versionFile = repairRootScopedStorageFile(storageRoot, harness, "last_announced_version");
   try {
-    mkdirSync2(dirname2(versionFile), { recursive: true });
+    mkdirSync2(dirname3(versionFile), { recursive: true });
     writeFileSync2(versionFile, currentVersion);
   } catch {}
 }
@@ -16209,10 +16816,10 @@ function decodeFileUrl(target) {
 }
 
 // ../aft-bridge/dist/resolver.js
-import { closeSync as closeSync2, existsSync as existsSync7, promises as fsPromises, openSync as openSync2, readFileSync as readFileSync5, readSync } from "node:fs";
+import { closeSync as closeSync2, existsSync as existsSync7, promises as fsPromises, openSync as openSync2, readFileSync as readFileSync6, readSync } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir as homedir9 } from "node:os";
-import { delimiter, dirname as dirname3, isAbsolute as isAbsolute4, join as join9 } from "node:path";
+import { delimiter, dirname as dirname4, isAbsolute as isAbsolute4, join as join9 } from "node:path";
 var ensureBinaryForResolver = ensureBinary;
 var npmPlatformPackageReader = null;
 var cacheCopiesInFlight = new Map;
@@ -16365,8 +16972,8 @@ function npmPlatformPackage(ext) {
   try {
     const req = createRequire(import.meta.url);
     const manifestPath = req.resolve(`@cortexkit/aft-${platformKey()}/package.json`);
-    const manifest = JSON.parse(readFileSync5(manifestPath, "utf8"));
-    const binaryPath = join9(dirname3(manifestPath), "bin", `aft${ext}`);
+    const manifest = JSON.parse(readFileSync6(manifestPath, "utf8"));
+    const binaryPath = join9(dirname4(manifestPath), "bin", `aft${ext}`);
     if (typeof manifest.version !== "string" || !existsSync7(binaryPath))
       return null;
     return { binaryPath, version: normalizeBareVersion(manifest.version) };
@@ -16620,7 +17227,7 @@ function acquireConfigMigrationLock(lockDir) {
       if (code !== "EEXIST")
         throw err;
       try {
-        const ageMs = Date.now() - statSync5(lockDir).mtimeMs;
+        const ageMs = Date.now() - statSync6(lockDir).mtimeMs;
         if (ageMs > 60000) {
           rmSync2(lockDir, { recursive: true, force: true });
           continue;
@@ -16634,12 +17241,12 @@ function acquireConfigMigrationLock(lockDir) {
   }
 }
 function atomicCopyConfigFile(sourcePath, targetPath) {
-  mkdirSync3(dirname4(targetPath), { recursive: true });
-  const tmpPath = join10(dirname4(targetPath), `.${basename(targetPath)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+  mkdirSync3(dirname5(targetPath), { recursive: true });
+  const tmpPath = join10(dirname5(targetPath), `.${basename2(targetPath)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
   let fd = null;
   try {
     fd = openSync3(tmpPath, "wx", 384);
-    writeFileSync3(fd, readFileSync6(sourcePath));
+    writeFileSync3(fd, readFileSync7(sourcePath));
     closeSync3(fd);
     fd = null;
     renameSync4(tmpPath, targetPath);
@@ -16656,8 +17263,8 @@ function atomicCopyConfigFile(sourcePath, targetPath) {
   }
 }
 function atomicWriteConfigFile(targetPath, content) {
-  mkdirSync3(dirname4(targetPath), { recursive: true });
-  const tmpPath = join10(dirname4(targetPath), `.${basename(targetPath)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
+  mkdirSync3(dirname5(targetPath), { recursive: true });
+  const tmpPath = join10(dirname5(targetPath), `.${basename2(targetPath)}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`);
   let fd = null;
   try {
     fd = openSync3(tmpPath, "wx", 384);
@@ -16718,11 +17325,11 @@ function markLegacySourcesMovedAside(sources, targetPath, logger) {
     const desiredMarkerPath = `${source.path}${MOVED_MARKER_SUFFIX}`;
     const markerPath = nonClobberingSidecarPath(desiredMarkerPath);
     try {
-      const original = readFileSync6(source.path, "utf-8");
+      const original = readFileSync7(source.path, "utf-8");
       if (markerPath !== desiredMarkerPath) {
         logger?.warn?.(`Preserving existing legacy AFT marker ${desiredMarkerPath}; writing new marker to ${markerPath}`);
       }
-      atomicWriteConfigFile(markerPath, movedMarkerContent(targetPath, basename(source.path), original));
+      atomicWriteConfigFile(markerPath, movedMarkerContent(targetPath, basename2(source.path), original));
       unlinkSync3(source.path);
       info?.(`Moved legacy AFT config ${source.path} aside to ${markerPath}; AFT now reads ${targetPath}`);
     } catch (err) {
@@ -16782,15 +17389,15 @@ function migrateAftConfigFile(opts) {
   if (existingSources.length === 0) {
     return { migrated: false, conflict: false, targetPath: opts.targetPath, warnings };
   }
-  mkdirSync3(dirname4(opts.targetPath), { recursive: true });
+  mkdirSync3(dirname5(opts.targetPath), { recursive: true });
   const release = acquireConfigMigrationLock(`${opts.targetPath}.lock`);
   try {
     const sources = existingSources.map((source) => ({
       ...source,
-      content: readFileSync6(source.path, "utf-8")
+      content: readFileSync7(source.path, "utf-8")
     }));
     if (existsSync8(opts.targetPath)) {
-      const targetContent = readFileSync6(opts.targetPath, "utf-8");
+      const targetContent = readFileSync7(opts.targetPath, "utf-8");
       for (const source of sources) {
         if (fileSemanticsMatch(source.content, targetContent))
           continue;
@@ -16841,11 +17448,11 @@ function spawnErrorLabel(error) {
 function migrationLogPath(newRoot, harness, logger) {
   const desired = join10(newRoot, "logs", "migration", `${harness}-${Date.now()}.jsonl`);
   try {
-    mkdirSync3(dirname4(desired), { recursive: true });
+    mkdirSync3(dirname5(desired), { recursive: true });
     return desired;
   } catch (err) {
     const fallback = join10(tmpdir2(), `aft-migration-${harness}-${Date.now()}.jsonl`);
-    logger?.warn?.(`Failed to create AFT migration log directory ${dirname4(desired)}: ${err instanceof Error ? err.message : String(err)}. ` + `Using fallback log path ${fallback}.`);
+    logger?.warn?.(`Failed to create AFT migration log directory ${dirname5(desired)}: ${err instanceof Error ? err.message : String(err)}. ` + `Using fallback log path ${fallback}.`);
     return fallback;
   }
 }
@@ -16906,9 +17513,9 @@ async function ensureStorageMigrated(opts) {
   throw new Error(`AFT storage migration failed (${detail}). ` + `Harness: ${opts.harness}. Legacy: ${legacyRoot}. Target: ${newRoot}. ` + `See log: ${logPath}. ` + `Plugin load aborted to prevent legacy/new state divergence.` + (stderrTail ? ` Stderr tail: ${stderrTail}` : "") + (stdoutTail ? ` Stdout tail: ${stdoutTail}` : ""));
 }
 // ../aft-bridge/dist/migration-notices.js
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync7, renameSync as renameSync5, rmdirSync, statSync as statSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync as renameSync5, rmdirSync, statSync as statSync7, writeFileSync as writeFileSync4 } from "node:fs";
 import { homedir as homedir11 } from "node:os";
-import { dirname as dirname5, join as join11, resolve as resolve7 } from "node:path";
+import { dirname as dirname6, join as join11, resolve as resolve7 } from "node:path";
 function migrationNoticeStorePath(env = process.env) {
   const stateHome = env.XDG_STATE_HOME && env.XDG_STATE_HOME.length > 0 ? env.XDG_STATE_HOME : join11(homedir11(), ".local", "state");
   return join11(stateHome, "cortexkit", "aft", "migration-notices.json");
@@ -16918,7 +17525,7 @@ function noticeKey(configPath, digest) {
 }
 function readRecords(storePath) {
   try {
-    const parsed = JSON.parse(readFileSync7(storePath, "utf8"));
+    const parsed = JSON.parse(readFileSync8(storePath, "utf8"));
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};
@@ -16927,7 +17534,7 @@ function readRecords(storePath) {
 var LOCK_STALE_MS = 1e4;
 function withStoreLock(storePath, action) {
   const lockPath = `${storePath}.lock`;
-  mkdirSync4(dirname5(storePath), { recursive: true });
+  mkdirSync4(dirname6(storePath), { recursive: true });
   const deadline = Date.now() + 2000;
   for (;; ) {
     try {
@@ -16937,7 +17544,7 @@ function withStoreLock(storePath, action) {
       if (error.code !== "EEXIST")
         throw error;
       try {
-        if (Date.now() - statSync6(lockPath).mtimeMs > LOCK_STALE_MS)
+        if (Date.now() - statSync7(lockPath).mtimeMs > LOCK_STALE_MS)
           rmdirSync(lockPath);
       } catch {}
       if (Date.now() > deadline)
@@ -16978,9 +17585,9 @@ function deliverMigrationNoticeOnce(options) {
   }
 }
 // ../aft-bridge/dist/npm-resolver.js
-import { readdirSync as readdirSync2, statSync as statSync7 } from "node:fs";
+import { readdirSync as readdirSync2, statSync as statSync8 } from "node:fs";
 import { homedir as homedir12 } from "node:os";
-import { dirname as dirname6, isAbsolute as isAbsolute5, join as join12 } from "node:path";
+import { dirname as dirname7, isAbsolute as isAbsolute5, join as join12 } from "node:path";
 function defaultDeps() {
   return {
     platform: process.platform,
@@ -16994,7 +17601,7 @@ function npmBinaryName(platform) {
 }
 function isFile(p) {
   try {
-    return statSync7(p).isFile();
+    return statSync8(p).isFile();
   } catch {
     return false;
   }
@@ -17015,7 +17622,7 @@ function npmFromPath(deps) {
   return null;
 }
 function npmAdjacentToNode(deps) {
-  const dir = dirname6(deps.execPath);
+  const dir = dirname7(deps.execPath);
   return isFile(join12(dir, npmBinaryName(deps.platform))) ? dir : null;
 }
 function highestVersionedNodeBin(installsDir, name) {
@@ -17400,8 +18007,8 @@ function probeOnnxRuntimeLoadable(libPath, arch = process.arch) {
 }
 // ../aft-bridge/dist/onnx-runtime.js
 import { createHash as createHash4, randomBytes as randomBytes2 } from "node:crypto";
-import { chmodSync as chmodSync2, closeSync as closeSync5, copyFileSync as copyFileSync2, createWriteStream as createWriteStream2, existsSync as existsSync11, lstatSync, mkdirSync as mkdirSync5, openSync as openSync5, readdirSync as readdirSync3, readFileSync as readFileSync8, readlinkSync, realpathSync as realpathSync3, renameSync as renameSync6, rmSync as rmSync3, statSync as statSync8, symlinkSync, unlinkSync as unlinkSync4, writeFileSync as writeFileSync5 } from "node:fs";
-import { basename as basename2, dirname as dirname7, isAbsolute as isAbsolute6, join as join14, relative as relative2, resolve as resolve8, win32 } from "node:path";
+import { chmodSync as chmodSync2, closeSync as closeSync5, copyFileSync as copyFileSync2, createWriteStream as createWriteStream2, existsSync as existsSync11, lstatSync, mkdirSync as mkdirSync5, openSync as openSync5, readdirSync as readdirSync3, readFileSync as readFileSync9, readlinkSync, realpathSync as realpathSync3, renameSync as renameSync6, rmSync as rmSync3, statSync as statSync9, symlinkSync, unlinkSync as unlinkSync4, writeFileSync as writeFileSync5 } from "node:fs";
+import { basename as basename3, dirname as dirname8, isAbsolute as isAbsolute6, join as join14, relative as relative2, resolve as resolve8, win32 } from "node:path";
 import { Readable as Readable2 } from "node:stream";
 import { pipeline as pipeline2 } from "node:stream/promises";
 
@@ -17441,31 +18048,36 @@ var ORT_PLATFORM_MAP = {
     arm64: {
       assetName: `onnxruntime-osx-arm64-${ORT_VERSION}`,
       libName: "libonnxruntime.dylib",
-      archiveType: "tgz"
+      archiveType: "tgz",
+      librarySha256: "872533f130f1839a5bc01788ddb4f75c83a189763441ba1178788ed965449289"
     }
   },
   linux: {
     x64: {
       assetName: `onnxruntime-linux-x64-${ORT_VERSION}`,
       libName: "libonnxruntime.so",
-      archiveType: "tgz"
+      archiveType: "tgz",
+      librarySha256: "d132535d051344ff5c64c9c200004150559049a81ed330eb4422c1962fb6b7e4"
     },
     arm64: {
       assetName: `onnxruntime-linux-aarch64-${ORT_VERSION}`,
       libName: "libonnxruntime.so",
-      archiveType: "tgz"
+      archiveType: "tgz",
+      librarySha256: "52b2a0e75e79468404284fec38ad5ee1a7a996232274f5e1b84f3e793fb07554"
     }
   },
   win32: {
     x64: {
       assetName: `onnxruntime-win-x64-${ORT_VERSION}`,
       libName: "onnxruntime.dll",
-      archiveType: "zip"
+      archiveType: "zip",
+      librarySha256: "b95efb2113b603bbbf3f191061c5516a871ed546893c820e4f3b7b6c358dbf2a"
     },
     arm64: {
       assetName: `onnxruntime-win-arm64-${ORT_VERSION}`,
       libName: "onnxruntime.dll",
-      archiveType: "zip"
+      archiveType: "zip",
+      librarySha256: "724d81ac50b11bfaa01ab3ce01b99fb6734a4b762259a8be4395ca662ce99fe6"
     }
   }
 };
@@ -17605,7 +18217,7 @@ function cleanupAbandonedStagingDirs(onnxBaseDir) {
             abandoned = true;
           } else {
             try {
-              const ageMs = Date.now() - statSync8(stagingDir).mtimeMs;
+              const ageMs = Date.now() - statSync9(stagingDir).mtimeMs;
               abandoned = ageMs > STALE_LOCK_MS;
             } catch {
               abandoned = true;
@@ -17642,7 +18254,7 @@ var REQUIRED_ORT_MAJOR = 1;
 var REQUIRED_ORT_MIN_MINOR = 20;
 var INVALID_ORT_VERSION = "<invalid>";
 function parseOnnxVersionFromPath(value) {
-  const name = basename2(value);
+  const name = basename3(value);
   const semverish = name.match(/(?:^|[._-])(\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)(?:\.(?:dylib|dll))?$/);
   if (semverish)
     return semverish[1].split(/[-+]/, 1)[0];
@@ -17847,7 +18459,7 @@ async function downloadFileWithCap(url, destPath) {
     if (Number.isFinite(advertised) && advertised > MAX_DOWNLOAD_BYTES2) {
       throw new Error(`Content-Length ${advertised} exceeds max ${MAX_DOWNLOAD_BYTES2}`);
     }
-    mkdirSync5(dirname7(destPath), { recursive: true });
+    mkdirSync5(dirname8(destPath), { recursive: true });
     let bytesWritten = 0;
     const guard = new TransformStream({
       transform(chunk, transformController) {
@@ -17881,7 +18493,7 @@ function validateExtractedTree(stagingRoot) {
       const lst = lstatSync(fullPath);
       if (lst.isSymbolicLink()) {
         const linkTarget = readlinkSync(fullPath);
-        const resolvedTarget = resolve8(dirname7(fullPath), linkTarget);
+        const resolvedTarget = resolve8(dirname8(fullPath), linkTarget);
         const rel = relative2(realRoot, resolvedTarget);
         if (rel.startsWith("..") || isAbsolute6(rel) || win32.isAbsolute(rel)) {
           throw new Error(`extracted symlink ${fullPath} points outside staging root: ${linkTarget}`);
@@ -17952,6 +18564,9 @@ async function downloadOnnxRuntime(info, targetDir) {
     copyOnnxLibraries(info, extractedDir, stagedInstallDir, realFiles, symlinks);
     const libPath = join14(stagedInstallDir, info.libName);
     const libHash = sha256File2(libPath);
+    if (libHash !== info.librarySha256) {
+      throw new Error(`onnx runtime library hash mismatch at ${libPath}: sha256 ${libHash}, ` + `expected the pinned ${info.librarySha256} for ${info.assetName}`);
+    }
     writeOnnxInstalledMeta(stagedInstallDir, ORT_VERSION, libHash, archiveSha256);
     publishOnnxRuntime(stagedInstallDir, targetDir);
     rmSync3(tmpDir, { recursive: true, force: true });
@@ -18017,7 +18632,7 @@ function copyOnnxLibraries(info, extractedDir, targetDir, realFiles, symlinks, c
       unlinkSync4(dst);
     } catch {}
     const dstForContainment = join14(targetRoot, link.name);
-    const resolvedTarget = resolve8(dirname7(dstForContainment), link.target);
+    const resolvedTarget = resolve8(dirname8(dstForContainment), link.target);
     if (!isPathInsideRoot(targetRoot, resolvedTarget)) {
       const message = `ONNX Runtime symlink ${link.name} points outside install dir: ${link.target}`;
       if (requiredLibs.has(link.name)) {
@@ -18069,9 +18684,9 @@ function writeOnnxInstalledMeta(installDir, version, sha256, archiveSha256) {
 function readOnnxInstalledMeta(installDir) {
   const path = join14(installDir, ONNX_INSTALLED_META_FILE);
   try {
-    if (!statSync8(path).isFile())
+    if (!statSync9(path).isFile())
       return null;
-    const raw = readFileSync8(path, "utf8");
+    const raw = readFileSync9(path, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.version !== "string" || parsed.version.length === 0)
       return null;
@@ -18087,7 +18702,7 @@ function readOnnxInstalledMeta(installDir) {
 }
 function sha256File2(path) {
   const hash = createHash4("sha256");
-  hash.update(readFileSync8(path));
+  hash.update(readFileSync9(path));
   return hash.digest("hex");
 }
 function acquireLock(lockPath) {
@@ -18115,12 +18730,12 @@ ${new Date().toISOString()}
   let owningPid = null;
   let lockMtimeMs = 0;
   try {
-    const raw = readFileSync8(lockPath, "utf8");
+    const raw = readFileSync9(lockPath, "utf8");
     const firstLine = raw.split(/\r?\n/, 1)[0]?.trim() ?? "";
     const parsed = Number.parseInt(firstLine, 10);
     if (Number.isFinite(parsed) && parsed > 0)
       owningPid = parsed;
-    lockMtimeMs = statSync8(lockPath).mtimeMs;
+    lockMtimeMs = statSync9(lockPath).mtimeMs;
   } catch {
     return tryClaim();
   }
@@ -18140,7 +18755,7 @@ function releaseLock(lockPath) {
   try {
     let owningPid = null;
     try {
-      const raw = readFileSync8(lockPath, "utf8");
+      const raw = readFileSync9(lockPath, "utf8");
       const firstLine = raw.split(/\r?\n/, 1)[0]?.trim() ?? "";
       const parsed = Number.parseInt(firstLine, 10);
       if (Number.isFinite(parsed) && parsed > 0)
@@ -18294,12 +18909,13 @@ function normalizeZoomTargets(record) {
       throw new InvalidRequestError(`'targets[${index}].path' must be a non-empty string`);
     }
     const source = target;
-    const emptyTarget = source.symbol === "" && (hasOwn(source, "path") && source.path === "" || hasOwn(source, "filePath") && source.filePath === "");
+    const blank = (value) => value === undefined || value === null || typeof value === "string" && !value.trim();
+    const emptyTarget = blank(source.symbol) && blank(source.path) && blank(source.filePath);
     if (emptyTarget)
       return { ...source };
     const normalized = { ...source };
     try {
-      normalizeAliasPair(normalized, "path", "filePath", true);
+      normalizeAliasPair(normalized, "path", "filePath", false);
     } catch (error) {
       if (error instanceof InvalidRequestError) {
         throw new InvalidRequestError(error.message.replace("'filePath'", `'targets[${index}].filePath'`).replace("'path'", `'targets[${index}].path'`));
@@ -19880,7 +20496,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.58.0",
+  version: "0.58.2",
   type: "module",
   description: "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   main: "dist/index.js",
@@ -19903,30 +20519,32 @@ var package_default = {
     "test:unit": "bun test src/__tests__ --path-ignore-patterns 'src/__tests__/e2e/**'"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.58.0",
+    "@cortexkit/aft-bridge": "0.58.2",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
-    typebox: "1.1.38",
     zod: "^4.4.3"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.58.0",
-    "@cortexkit/aft-darwin-x64": "0.58.0",
-    "@cortexkit/aft-linux-arm64": "0.58.0",
-    "@cortexkit/aft-linux-x64": "0.58.0",
-    "@cortexkit/aft-win32-arm64": "0.58.0",
-    "@cortexkit/aft-win32-x64": "0.58.0"
+    "@cortexkit/aft-darwin-arm64": "0.58.2",
+    "@cortexkit/aft-darwin-x64": "0.58.2",
+    "@cortexkit/aft-linux-arm64": "0.58.2",
+    "@cortexkit/aft-linux-x64": "0.58.2",
+    "@cortexkit/aft-win32-arm64": "0.58.2",
+    "@cortexkit/aft-win32-x64": "0.58.2"
   },
   devDependencies: {
     "@earendil-works/pi-coding-agent": "^0.80.2",
     "@earendil-works/pi-ai": "^0.80.2",
     "@earendil-works/pi-tui": "^0.80.2",
     "@types/node": "^22.0.0",
+    typebox: "1.1.38",
     typescript: "^5.8.0"
   },
   peerDependencies: {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    typebox: "*"
   },
   exports: {
     ".": {
@@ -20192,6 +20810,24 @@ function appendDegradedStatus(lines, status, markdown) {
 // src/tools/_shared.ts
 import { existsSync as existsSync12 } from "node:fs";
 import { Type } from "typebox";
+
+// src/session-kind.ts
+var MAGIC_CONTEXT_SUBAGENT_ENV = "MAGIC_CONTEXT_PI_SUBAGENT";
+function piWorkerKind(extCtx, env = process.env) {
+  if (env[MAGIC_CONTEXT_SUBAGENT_ENV] === "1")
+    return "delegated";
+  if (extCtx?.hasUI === false)
+    return "headless";
+  return;
+}
+function isPiWorkerSession(extCtx, env = process.env) {
+  return piWorkerKind(extCtx, env) !== undefined;
+}
+function skipsEagerStartup(env = process.env) {
+  return piWorkerKind(undefined, env) === "delegated";
+}
+
+// src/tools/_shared.ts
 var optionalInt = (min, max, description = "(integer)") => Type.Optional(Type.Union([Type.Integer({ minimum: min, maximum: max }), Type.String()], {
   description
 }));
@@ -20277,6 +20913,9 @@ async function callBridge(bridge, command, params = {}, extCtx, options) {
   if (sessionId) {
     merged.session_id = sessionId;
   }
+  if (isPiWorkerSession(extCtx)) {
+    merged[WORKER_SESSION_FIELD] = true;
+  }
   const sendOptions = {
     ...timeoutMs !== undefined ? { timeoutMs } : {},
     configureWarningClient: extCtx,
@@ -20304,6 +20943,7 @@ async function callToolCallForSession(bridge, name, rawArgs, sessionId, extCtx,
   const sendOptions = {
     ...timeoutMs !== undefined ? { timeoutMs } : {},
     configureWarningClient: extCtx,
+    ...isPiWorkerSession(extCtx) ? { workerSession: true } : {},
     ...options
   };
   let response;
@@ -20623,7 +21263,7 @@ function registerStatusCommand(pi, ctx) {
 }
 
 // src/config.ts
-import { existsSync as existsSync13, readFileSync as readFileSync9, renameSync as renameSync7, unlinkSync as unlinkSync5, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync10, renameSync as renameSync7, unlinkSync as unlinkSync5, writeFileSync as writeFileSync6 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import { homedir as homedir13 } from "node:os";
 import { isAbsolute as isAbsolute7 } from "node:path";
@@ -25436,7 +26076,7 @@ var IndexConfigSchema = object({
   roots: array(IndexRootSchema).optional()
 });
 var SemanticConfigSchema = object({
-  backend: _enum(["fastembed", "openai_compatible", "ollama"]).optional(),
+  backend: _enum(["fastembed", "openai_compatible", "ollama", "synapse"]).optional(),
   model: string2().trim().min(1).optional(),
   base_url: string2().trim().min(1).optional(),
   api_key_env: string2().trim().min(1).optional(),
@@ -25447,6 +26087,17 @@ var SemanticConfigSchema = object({
   max_input_tokens: number2().int().positive().optional(),
   max_files: number2().int().positive().optional()
 });
+var RerankConfigSchema = object({
+  backend: _enum(["off", "onnx", "remote", "synapse"]).optional(),
+  model: string2().trim().min(1).optional(),
+  endpoint: string2().trim().min(1).optional(),
+  api_key_env: string2().trim().min(1).optional(),
+  top_n: number2().int().positive().optional(),
+  timeout_ms: number2().int().positive().optional()
+});
+var SearchConfigSchema = object({
+  rerank: RerankConfigSchema.optional()
+});
 var LspExtensionSchema = string2().trim().min(1).refine((value) => value.replace(/^\.+/, "").length > 0, {
   message: "Extension must include characters other than leading dots"
 });
@@ -25510,6 +26161,10 @@ var SubcConfigSchema = object({
 var GhShimConfigSchema = object({
   binary_path: string2().trim().refine(isAbsolute7, "gh_shim.binary_path must be absolute").optional()
 });
+var OpenCodeHostConfigSchema = object({
+  server_url: string2().optional(),
+  server_password_env: string2().optional()
+});
 var GithubConfigSchema = object({
   shim: boolean2().optional(),
   read: boolean2().optional(),
@@ -25582,8 +26237,10 @@ var AftConfigFieldsSchema = object({
   lsp: LspConfigSchema.optional(),
   url_fetch_allow_private: boolean2().optional(),
   semantic: SemanticConfigSchema.optional(),
+  search: SearchConfigSchema.optional(),
   bridge: BridgeConfigSchema.optional(),
   subc: SubcConfigSchema.optional(),
+  opencode: OpenCodeHostConfigSchema.optional(),
   github: GithubConfigSchema.optional(),
   gh_shim: GhShimConfigSchema.optional(),
   git: GitConfigSchema.optional()
@@ -25729,7 +26386,7 @@ function migrateAftConfigFile2(configPath, logger = { log: log2, warn: warn2 })
   let tmpPath = null;
   let oldKeys = [];
   try {
-    const content = readFileSync9(configPath, "utf-8");
+    const content = readFileSync10(configPath, "utf-8");
     const rawConfig = import_comment_json.parse(content);
     if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
       return { migrated: false, oldKeys: [] };
@@ -25764,6 +26421,18 @@ ${serialized}` : serialized;
   }
 }
 var configLoadErrors = [];
+var configValidationErrors = [];
+var configLoadSources = [];
+var configLoadTexts = new Map;
+function getConfigLoadSources() {
+  return configLoadSources;
+}
+function getConfigLoadTexts() {
+  return configLoadTexts;
+}
+function getConfigValidationErrors() {
+  return configValidationErrors;
+}
 function getConfigLoadErrors() {
   return configLoadErrors;
 }
@@ -25808,7 +26477,9 @@ function loadConfigFromPath(configPath, tier) {
   try {
     if (!existsSync13(configPath))
       return null;
-    const content = readFileSync9(configPath, "utf-8");
+    const content = readFileSync10(configPath, "utf-8");
+    configLoadSources.push(configPath);
+    configLoadTexts.set(configPath, content);
     const rawConfig = import_comment_json.parse(content);
     if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
       recordConfigParseFailure(configPath, "root must be an object");
@@ -25858,6 +26529,7 @@ function loadConfigFromPath(configPath, tier) {
   } else {
     const errorMsg = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
     warn2(`Config validation error in ${configPath}: ${errorMsg}`);
+    configValidationErrors.push({ path: configPath, message: errorMsg });
     parsed = parseConfigPartially(cleanConfig);
   }
   if (tier === "user" && parsed.disabled_tools === undefined) {
@@ -26061,6 +26733,8 @@ function getStrippedTopLevelKeys(override) {
     stripped.push("sandbox.write_allow");
   if (override.subc !== undefined)
     stripped.push("subc");
+  if (override.opencode !== undefined)
+    stripped.push("opencode");
   if (override.github !== undefined)
     stripped.push("github");
   if (override.gh_shim !== undefined)
@@ -26068,14 +26742,33 @@ function getStrippedTopLevelKeys(override) {
   for (const tool of partitionProjectDisables(override.disabled_tools).ignored) {
     stripped.push(`disabled_tools.${tool}`);
   }
+  stripped.push(...projectRerankStrippedKeys(override.search?.rerank));
   return stripped;
 }
+function projectRerankStrippedKeys(rerank) {
+  if (rerank === undefined)
+    return [];
+  const stripped = [];
+  if (rerank.backend !== undefined && rerank.backend !== "off")
+    stripped.push("search.rerank.backend");
+  for (const key of ["model", "endpoint", "api_key_env", "top_n", "timeout_ms"]) {
+    if (rerank[key] !== undefined)
+      stripped.push(`search.rerank.${key}`);
+  }
+  return stripped;
+}
+function mergeProjectSearchConfig(base, project) {
+  if (project?.rerank?.backend !== "off")
+    return base;
+  return { ...base, rerank: { ...base?.rerank, backend: "off" } };
+}
 function mergeConfigs(base, override) {
   const disabledTools = unionDisabledTools(base.disabled_tools, partitionProjectDisables(override.disabled_tools).accepted);
   const indexes = mergeIndexes(base.indexes, override.indexes, true);
   const formatter = { ...base.formatter, ...override.formatter };
   const checker = { ...base.checker, ...override.checker };
   const semantic = mergeSemanticConfig(base.semantic, override.semantic);
+  const search = mergeProjectSearchConfig(base.search, override.search);
   const lsp = mergeLspConfig(base.lsp, override.lsp);
   const experimental = mergeExperimentalConfig(base.experimental, override.experimental);
   const bash = mergeBashConfig(base.bash, override.bash);
@@ -26105,6 +26798,7 @@ function mergeConfigs(base, override) {
     ...pi !== undefined ? { pi } : {},
     experimental,
     semantic,
+    search,
     ...bridge !== undefined ? { bridge } : {},
     ...indexes !== undefined ? { indexes } : {},
     ...disabledTools !== undefined ? { disabled_tools: disabledTools } : {}
@@ -26163,6 +26857,9 @@ function buildConfigTierConfigureParams(projectDirectory, processState = {}) {
 }
 function loadAftConfig(projectDirectory) {
   configLoadErrors = [];
+  configValidationErrors = [];
+  configLoadSources = [];
+  configLoadTexts = new Map;
   configLoadNotices = [];
   semanticInputSupplied = false;
   const { userConfigPath, projectConfigPath } = resolveAftConfigPaths(projectDirectory);
@@ -26213,10 +26910,10 @@ import {
   createReadStream as createReadStream2,
   existsSync as existsSync15,
   mkdirSync as mkdirSync7,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   renameSync as renameSync9,
   rmSync as rmSync5,
-  statSync as statSync10,
+  statSync as statSync11,
   writeFileSync as writeFileSync8
 } from "node:fs";
 import { join as join17 } from "node:path";
@@ -26227,10 +26924,10 @@ import {
   closeSync as closeSync6,
   mkdirSync as mkdirSync6,
   openSync as openSync6,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   renameSync as renameSync8,
   rmSync as rmSync4,
-  statSync as statSync9,
+  statSync as statSync10,
   unlinkSync as unlinkSync6,
   writeFileSync as writeFileSync7
 } from "node:fs";
@@ -26253,7 +26950,7 @@ function lspBinDir(npmPackage) {
 function isInstalled(npmPackage, binary) {
   for (const candidate of lspBinaryCandidates(binary)) {
     try {
-      if (statSync9(join15(lspBinDir(npmPackage), candidate)).isFile())
+      if (statSync10(join15(lspBinDir(npmPackage), candidate)).isFile())
         return true;
     } catch {}
   }
@@ -26281,9 +26978,9 @@ function writeInstalledMetaIn(installDir, version, sha256) {
 function readInstalledMetaIn(installDir) {
   const path = join15(installDir, INSTALLED_META_FILE);
   try {
-    if (!statSync9(path).isFile())
+    if (!statSync10(path).isFile())
       return null;
-    const raw = readFileSync10(path, "utf8");
+    const raw = readFileSync11(path, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.version !== "string" || parsed.version.length === 0)
       return null;
@@ -26352,12 +27049,12 @@ ${token}
   let owningPid = null;
   let lockMtimeMs = 0;
   try {
-    const raw = readFileSync10(lock, "utf8");
+    const raw = readFileSync11(lock, "utf8");
     const firstLine = raw.split(/\r?\n/, 1)[0]?.trim() ?? "";
     const parsed = Number.parseInt(firstLine, 10);
     if (Number.isFinite(parsed) && parsed > 0)
       owningPid = parsed;
-    lockMtimeMs = statSync9(lock).mtimeMs;
+    lockMtimeMs = statSync10(lock).mtimeMs;
   } catch {
     return tryClaim();
   }
@@ -26391,7 +27088,7 @@ function releaseInstallLock(lockKey, acquisitionToken) {
     let owningPid = null;
     let owningToken = "";
     try {
-      const raw = readFileSync10(lock, "utf8");
+      const raw = readFileSync11(lock, "utf8");
       const lines = raw.split(/\r?\n/);
       const parsed = Number.parseInt(lines[0]?.trim() ?? "", 10);
       if (Number.isFinite(parsed) && parsed > 0)
@@ -26438,7 +27135,7 @@ function autoInstallStampPath() {
 }
 function hasRecentAutoInstallStamp(path) {
   try {
-    const parsed = JSON.parse(readFileSync10(path, "utf8"));
+    const parsed = JSON.parse(readFileSync11(path, "utf8"));
     return typeof parsed.lastRunMs === "number" && Number.isFinite(parsed.lastRunMs) && Math.abs(Date.now() - parsed.lastRunMs) < AUTO_INSTALL_WINDOW_MS;
   } catch {
     return false;
@@ -26446,7 +27143,7 @@ function hasRecentAutoInstallStamp(path) {
 }
 function readAutoInstallLockOwner(path) {
   try {
-    const parsed = JSON.parse(readFileSync10(path, "utf8"));
+    const parsed = JSON.parse(readFileSync11(path, "utf8"));
     if (typeof parsed.pid !== "number" || typeof parsed.startedMs !== "number" || typeof parsed.token !== "string") {
       return null;
     }
@@ -26459,7 +27156,7 @@ function autoInstallLockIsStale(path) {
   const owner = readAutoInstallLockOwner(path);
   let age = Number.POSITIVE_INFINITY;
   try {
-    age = Math.abs(Date.now() - statSync9(path).mtimeMs);
+    age = Math.abs(Date.now() - statSync10(path).mtimeMs);
   } catch {
     return true;
   }
@@ -26537,7 +27234,7 @@ var VERSION_CHECK_FILE = ".aft-version-check";
 function readVersionCheck(npmPackage) {
   const file = join15(lspPackageDir(npmPackage), VERSION_CHECK_FILE);
   try {
-    const raw = readFileSync10(file, "utf8");
+    const raw = readFileSync11(file, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.last_checked === "string") {
       return {
@@ -26640,6 +27337,14 @@ var NPM_LSP_TABLE = [
     extensions: ["ts", "tsx", "js", "jsx", "mjs", "cjs", "mts", "cts"],
     rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"]
   },
+  {
+    id: "typescript-sdk",
+    npm: "typescript",
+    binary: "tsserver",
+    extensions: ["ts", "tsx", "js", "jsx", "mjs", "cjs", "mts", "cts"],
+    rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
+    supportedMajor: 5
+  },
   {
     id: "python",
     npm: "pyright",
@@ -26712,9 +27417,18 @@ var NPM_LSP_TABLE = [
     rootMarkers: ["biome.json", "biome.jsonc"]
   }
 ];
+function majorVersionOf(version) {
+  const match = /^v?(\d+)(?:\.|$)/.exec(version.trim());
+  return match ? Number(match[1]) : null;
+}
+function isVersionSupported(spec, version) {
+  if (spec.supportedMajor === undefined)
+    return true;
+  return majorVersionOf(version) === spec.supportedMajor;
+}
 
 // src/lsp-project-relevance.ts
-import { existsSync as existsSync14, readdirSync as readdirSync4, readFileSync as readFileSync11 } from "node:fs";
+import { existsSync as existsSync14, readdirSync as readdirSync4, readFileSync as readFileSync12 } from "node:fs";
 import { join as join16 } from "node:path";
 var MAX_WALK_DIRS = 200;
 var MAX_WALK_DEPTH = 4;
@@ -26756,7 +27470,7 @@ function hasPackageJsonDep(projectRoot, depNames) {
 }
 function readPackageJson(projectRoot) {
   try {
-    const raw = readFileSync11(join16(projectRoot, "package.json"), "utf8");
+    const raw = readFileSync12(join16(projectRoot, "package.json"), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null)
       return null;
@@ -26808,10 +27522,11 @@ function extensionOf(fileName) {
 
 // src/lsp-registry-probe.ts
 var NPM_REGISTRY_BASE = "https://registry.npmjs.org";
-function pickEligibleVersion(response, graceDays, now = Date.now()) {
+function pickEligibleVersion(response, graceDays, now = Date.now(), accept = () => true) {
   const times = response.time || {};
   const cutoff = now - graceDays * 24 * 60 * 60 * 1000;
   const candidates = [];
+  let releaseCount = 0;
   for (const [version, publishedAt] of Object.entries(times)) {
     if (version === "created" || version === "modified")
       continue;
@@ -26822,6 +27537,9 @@ function pickEligibleVersion(response, graceDays, now = Date.now()) {
     const ts = Date.parse(publishedAt);
     if (Number.isNaN(ts))
       continue;
+    releaseCount += 1;
+    if (!accept(version))
+      continue;
     candidates.push({ version, publishedAt, ts });
   }
   candidates.sort((a, b) => b.ts - a.ts);
@@ -26830,10 +27548,11 @@ function pickEligibleVersion(response, graceDays, now = Date.now()) {
   return {
     version: eligible[0]?.version ?? null,
     blockedByGrace,
+    outsideSupportedRange: releaseCount > 0 && candidates.length === 0,
     eligible: eligible.map(({ version, publishedAt }) => ({ version, publishedAt }))
   };
 }
-async function probeRegistry(npmPackage, graceDays, fetchImpl = fetch) {
+async function probeRegistry(npmPackage, graceDays, fetchImpl = fetch, accept) {
   const encoded = encodeURIComponent(npmPackage).replace(/^%40/, "@");
   const url = `${NPM_REGISTRY_BASE}/${encoded}`;
   try {
@@ -26846,7 +27565,7 @@ async function probeRegistry(npmPackage, graceDays, fetchImpl = fetch) {
       return null;
     }
     const json = await res.json();
-    return pickEligibleVersion(json, graceDays);
+    return pickEligibleVersion(json, graceDays, Date.now(), accept);
   } catch (err) {
     warn2(`[lsp] registry probe failed for ${npmPackage}: ${err}`);
     return null;
@@ -26897,11 +27616,11 @@ async function resolveTargetVersion(spec, config, fetchImpl = fetch) {
   }
   const cached = readVersionCheck(spec.npm);
   const weeklyMs = config.graceDays * 24 * 60 * 60 * 1000;
-  const cachedSafe = isSafeVersion(cached?.latest_eligible ?? null);
+  const cachedSafe = isSafeVersion(cached?.latest_eligible ?? null) && isVersionSupported(spec, cached?.latest_eligible);
   if (cached && !shouldRecheckVersion(cached, weeklyMs) && cachedSafe) {
     return { version: cached.latest_eligible, pinned: false, probe: null };
   }
-  const probe = await probeRegistry(spec.npm, config.graceDays, fetchImpl);
+  const probe = await probeRegistry(spec.npm, config.graceDays, fetchImpl, (candidate) => isVersionSupported(spec, candidate));
   if (!probe) {
     return {
       version: cachedSafe ? cached?.latest_eligible ?? null : null,
@@ -27036,11 +27755,16 @@ async function ensureServerInstalled(spec, config, fetchImpl, signal) {
     const { version, probe } = await resolveTargetVersion(spec, config, fetchImpl);
     if (!version) {
       const installed = isInstalled(spec.npm, spec.binary);
-      if (installed) {
+      if (installed && installedVersionAllowed(spec, config)) {
         warn2(`[lsp] no eligible version of ${spec.npm} (grace=${config.graceDays}d); keeping existing install`);
         return { started: false, reason: "kept existing install" };
       }
-      const blocked = probe?.blockedByGrace ? `all versions are within ${config.graceDays}-day grace window` : "registry probe failed";
+      const blocked = probe?.blockedByGrace ? `all versions are within ${config.graceDays}-day grace window` : probe?.outsideSupportedRange ? `no ${spec.supportedMajor}.x release on the registry` : "registry probe failed";
+      if (installed) {
+        const reason = `cached ${spec.npm} ${readInstalledMeta(spec.npm)?.version ?? "(unknown version)"} is outside the supported ${spec.supportedMajor}.x line and no replacement is available: ${blocked}`;
+        warn2(`[lsp] ${reason}`);
+        return { started: false, reason };
+      }
       warn2(`[lsp] skipping ${spec.npm}: ${blocked}`);
       return { started: false, reason: blocked };
     }
@@ -27104,7 +27828,7 @@ function hashInstalledBinary(spec) {
     let pathToHash = null;
     for (const p of candidates) {
       try {
-        if (statSync10(p).isFile()) {
+        if (statSync11(p).isFile()) {
           pathToHash = p;
           break;
         }
@@ -27130,14 +27854,14 @@ function installedBinaryPath(spec) {
   ] : [lspBinaryPath(spec.npm, spec.binary)];
   for (const candidate of candidates) {
     try {
-      if (statSync10(candidate).isFile())
+      if (statSync11(candidate).isFile())
         return candidate;
     } catch {}
   }
   return null;
 }
 function sha256OfFileSync(path) {
-  return createHash5("sha256").update(readFileSync12(path)).digest("hex");
+  return createHash5("sha256").update(readFileSync13(path)).digest("hex");
 }
 function quarantineCachedNpmInstall(spec, reason) {
   const packageDir = lspPackageDir(spec.npm);
@@ -27165,6 +27889,15 @@ function validateCachedNpmInstall(spec) {
   }
   return true;
 }
+function installedVersionAllowed(spec, config) {
+  const installed = readInstalledMeta(spec.npm)?.version;
+  if (!installed)
+    return spec.supportedMajor === undefined;
+  return isVersionSupported(spec, installed) || config.versions[spec.npm] === installed;
+}
+function cachedInstallUsable(spec, config) {
+  return isInstalled(spec.npm, spec.binary) && validateCachedNpmInstall(spec) && installedVersionAllowed(spec, config);
+}
 function runAutoInstall(projectRoot, config, fetchImpl = fetch) {
   const cachedBinDirs = [];
   const skipped = [];
@@ -27177,10 +27910,10 @@ function runAutoInstall(projectRoot, config, fetchImpl = fetch) {
     return projectExtensions;
   };
   for (const spec of NPM_LSP_TABLE) {
-    if (isInstalled(spec.npm, spec.binary) && validateCachedNpmInstall(spec)) {
+    if (cachedInstallUsable(spec, config)) {
       cachedBinDirs.push(lspBinDir(spec.npm));
     }
-    if (config.disabled.has(spec.id)) {
+    if (config.disabled.has(spec.id) || spec.id === "typescript-sdk" && config.disabled.has("typescript")) {
       skipped.push({ id: spec.id, reason: "disabled by config" });
       continue;
     }
@@ -27216,7 +27949,7 @@ function runAutoInstall(projectRoot, config, fetchImpl = fetch) {
     },
     skipped,
     installsComplete: Promise.all(installPromises).then(() => {}),
-    getCachedBinDirs: () => NPM_LSP_TABLE.filter((spec) => isInstalled(spec.npm, spec.binary) && validateCachedNpmInstall(spec)).map((spec) => lspBinDir(spec.npm))
+    getCachedBinDirs: () => NPM_LSP_TABLE.filter((spec) => cachedInstallUsable(spec, config)).map((spec) => lspBinDir(spec.npm))
   };
 }
 async function pushLspPathsAfterAutoInstall(pool, projectRoot, cachedBinDirs) {
@@ -27235,16 +27968,16 @@ import {
   lstatSync as lstatSync2,
   mkdirSync as mkdirSync8,
   readdirSync as readdirSync5,
-  readFileSync as readFileSync13,
+  readFileSync as readFileSync14,
   readlinkSync as readlinkSync2,
   realpathSync as realpathSync4,
   renameSync as renameSync10,
   rmSync as rmSync6,
-  statSync as statSync11,
+  statSync as statSync12,
   unlinkSync as unlinkSync7,
   writeFileSync as writeFileSync9
 } from "node:fs";
-import { dirname as dirname8, join as join18, relative as relative3, resolve as resolve9 } from "node:path";
+import { dirname as dirname9, join as join18, relative as relative3, resolve as resolve9 } from "node:path";
 import { Readable as Readable3 } from "node:stream";
 import { pipeline as pipeline3 } from "node:stream/promises";
 
@@ -27353,7 +28086,7 @@ function installFailureMarkerPath(spec) {
 }
 function readInstallFailureMarker(spec) {
   try {
-    const marker = JSON.parse(readFileSync13(installFailureMarkerPath(spec), "utf8"));
+    const marker = JSON.parse(readFileSync14(installFailureMarkerPath(spec), "utf8"));
     if (typeof marker.release !== "string" || typeof marker.sha256 !== "string" || typeof marker.error !== "string" || typeof marker.at !== "string" || !Number.isFinite(Date.parse(marker.at))) {
       return null;
     }
@@ -27367,7 +28100,7 @@ function writeInstallFailureMarker(spec, release, sha256, installError) {
   const markerError = installError.replace(/\s+/g, " ").trim();
   const tempPath = `${path}.tmp-${process.pid}-${randomBytes3(6).toString("hex")}`;
   try {
-    mkdirSync8(dirname8(path), { recursive: true });
+    mkdirSync8(dirname9(path), { recursive: true });
     writeFileSync9(tempPath, `${JSON.stringify({ release, sha256, error: markerError, at: new Date().toISOString() })}
 `, { encoding: "utf8", mode: 384 });
     renameSync10(tempPath, path);
@@ -27396,7 +28129,7 @@ function ghBinaryPath(spec, platform) {
 function isGithubInstalled(spec, platform) {
   for (const candidate of ghBinaryCandidates(spec, platform)) {
     try {
-      if (statSync11(join18(ghBinDir(spec), candidate)).isFile())
+      if (statSync12(join18(ghBinDir(spec), candidate)).isFile())
         return true;
     } catch {}
   }
@@ -27410,9 +28143,9 @@ function ghBinaryCandidates(spec, platform) {
 function readGithubInstalledMetaIn(installDir) {
   try {
     const path = join18(installDir, INSTALLED_META_FILE2);
-    if (!statSync11(path).isFile())
+    if (!statSync12(path).isFile())
       return null;
-    const parsed = JSON.parse(readFileSync13(path, "utf8"));
+    const parsed = JSON.parse(readFileSync14(path, "utf8"));
     if (typeof parsed.version !== "string" || parsed.version.length === 0)
       return null;
     return {
@@ -27453,7 +28186,7 @@ function sha256OfFile(path) {
   });
 }
 function sha256OfFileSync2(path) {
-  return createHash6("sha256").update(readFileSync13(path)).digest("hex");
+  return createHash6("sha256").update(readFileSync14(path)).digest("hex");
 }
 async function fetchReleaseByTag(githubRepo, tag, fetchImpl, signal) {
   const candidates = [];
@@ -27629,7 +28362,7 @@ async function downloadFile(url, destPath, fetchImpl, assetSize, signal) {
     if (Number.isFinite(advertised) && advertised > MAX_DOWNLOAD_BYTES3) {
       throw new Error(`Content-Length ${advertised} exceeds max ${MAX_DOWNLOAD_BYTES3}`);
     }
-    mkdirSync8(dirname8(destPath), { recursive: true });
+    mkdirSync8(dirname9(destPath), { recursive: true });
     let bytesWritten = 0;
     const guard = new TransformStream({
       transform(chunk, controller) {
@@ -27799,7 +28532,7 @@ function quarantineCachedGithubInstall(spec, reason) {
   const dest = join18(ghCacheRoot(), ".quarantine", encodeURIComponent(spec.id), `${Date.now()}`);
   warn2(`[lsp] tofu_mismatch ${spec.id}: ${reason}; quarantining ${packageDir} -> ${dest}`);
   try {
-    mkdirSync8(dirname8(dest), { recursive: true });
+    mkdirSync8(dirname9(dest), { recursive: true });
     rmSync6(dest, { recursive: true, force: true });
     renameSync10(packageDir, dest);
   } catch (err) {
@@ -27811,7 +28544,7 @@ function validateCachedGithubInstall(spec, platform) {
   const meta = readGithubInstalledMetaIn(packageDir);
   const binaryPath = ghBinaryCandidates(spec, platform).map((candidate) => join18(ghBinDir(spec), candidate)).find((candidate) => {
     try {
-      return statSync11(candidate).isFile();
+      return statSync12(candidate).isFile();
     } catch {
       return false;
     }
@@ -27929,7 +28662,7 @@ async function downloadAndInstall(spec, tag, assets, platform, arch, fetchImpl,
     return { ok: false, sha256: archiveSha256, error: message };
   }
   const targetBinary = ghBinaryPath(spec, platform);
-  mkdirSync8(dirname8(targetBinary), { recursive: true });
+  mkdirSync8(dirname9(targetBinary), { recursive: true });
   try {
     copyFileSync3(innerBinaryPath, targetBinary);
     if (platform !== "win32") {
@@ -28347,6 +29080,23 @@ import {
 import { Container as Container2, Spacer as Spacer2, Text as Text2 } from "@earendil-works/pi-tui";
 import { Type as Type2 } from "typebox";
 
+// src/hashline-tag-sources.ts
+function hashlineTagSourceSentence(bashRewritesMintTags, isRegistered = () => true) {
+  const rewrites = bashRewritesMintTags ? " (and accepted AFT `cat`/`head`/`tail` rewrites)" : "";
+  const lookAlikes = [
+    ...["aft_zoom", "aft_outline"].filter(isRegistered),
+    "grep",
+    ...isRegistered("aft_search") ? ["aft_search"] : []
+  ].map((name) => `\`${name}\``);
+  lookAlikes.push("conflict snippets");
+  return `Only \`read\`${rewrites} mint hashline tags. ${joinList(lookAlikes)} do not. After navigation, call \`read\` on every file and range the patch addresses.`;
+}
+function joinList(items) {
+  if (items.length <= 2)
+    return items.join(" and ");
+  return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+
 // src/tools/diff-format.ts
 import { diffLines } from "diff";
 
@@ -28694,7 +29444,7 @@ var ISSUE_AND_PR_READ_DESCRIPTION = "GitHub issues and pull requests can be read
 function whenGhReadEnabled(enabled, description) {
   return enabled ? description : "";
 }
-var READ_DESCRIPTION = "Read file contents with line numbers. Backed by AFT's indexed Rust reader — faster than the built-in `read` on large repos. Images are returned as attachments on vision-capable models; PDFs and non-vision models are not yet supported.";
+var READ_DESCRIPTION = "Read file contents with line numbers or sorted directory entries. Use startLine/endLine or 1-based offset/limit for either. Directory limit defaults to and is capped at 1000; enumeration stops at 10,000 entries and partial listings carry a shown/total trailer. Backed by AFT's indexed Rust reader — faster than the built-in `read` on large repos. Images are returned as attachments on vision-capable models; PDFs and non-vision models are not yet supported.";
 function readDescription(ghReadEnabled) {
   const githubDescription = whenGhReadEnabled(ghReadEnabled, ISSUE_AND_PR_READ_DESCRIPTION);
   return githubDescription ? `${READ_DESCRIPTION} ${githubDescription}` : READ_DESCRIPTION;
@@ -28790,18 +29540,20 @@ async function assertExternalDirectoryPermission(extCtx, target, options = {}) {
 }
 var ReadParams = Type2.Object({
   path: Type2.String({
-    description: "Path to the file to read (absolute or relative to project root)"
+    description: "Path to the file or directory to read (absolute or relative to project root)"
   }),
-  startLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line to start reading from"),
-  endLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line to stop reading at (inclusive)"),
-  limit: optionalInt(1, Number.MAX_SAFE_INTEGER, "Maximum number of lines to return"),
-  offset: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line number to start reading from (use with limit)")
+  startLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line or directory entry to start reading from"),
+  endLine: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line or directory entry to stop reading at (inclusive)"),
+  limit: optionalInt(1, Number.MAX_SAFE_INTEGER, "Max lines (default: 2000) or directory entries (default and cap: 1000) to return"),
+  offset: optionalInt(1, Number.MAX_SAFE_INTEGER, "1-based line or directory entry to start reading from (use with limit). Ignored if startLine is provided")
 });
 var WriteParams = Type2.Object({
   path: Type2.String({
     description: "Path to the file to write (absolute or relative to project root)"
   }),
-  content: Type2.String({ description: "Full file contents to write" })
+  content: Type2.String({
+    description: "Full file contents to write; for issue://N / pr://N, the comment body to post"
+  })
 });
 var BatchEditParams = Type2.Object({
   oldString: Type2.Optional(Type2.String({ description: "Text to find for a batch find/replace edit" })),
@@ -28825,14 +29577,14 @@ var EditParams = Type2.Object({
     description: "Replacement content for symbol mode; only meaningful together with `symbol`. A call carrying one without the other is incomplete. For whole-file writes, use the `write` tool."
   })),
   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, other edit modes are ignored."
+    description: "Append text to the end of the file (creates the file if missing, parent dirs auto-created). Mixing with other edit modes is rejected."
   })),
   edits: Type2.Optional(Type2.Array(BatchEditParams, {
     minItems: 1,
     description: "Batch edits — non-empty array of { oldString, newString }, { oldString, newString, replaceAll: true }, or { startLine, endLine, content } objects applied atomically."
   }))
 });
-var HASHLINE_EDIT_DESCRIPTION = [
+var HASHLINE_EDIT_GRAMMAR = [
   "Apply a hashline patch. Arguments are exactly `{patch}` where `patch` is a non-empty string. Server-owned preview control is outside this schema.",
   "",
   "Quick reference:",
@@ -28840,10 +29592,15 @@ var HASHLINE_EDIT_DESCRIPTION = [
   "- Same canonical path: multiple sections compose in patch order against pre-request coordinates.",
   "- Addresses: `0` (BOF), `N` (one line), `N.=M` (range; `N..=M`/`N..M` also work), `<N`/`>N` (gap before/after), `N*`/`<N*`/`>N*` (block), and `$`/`$-K` (EOF-relative). A plain `N` PUT replaces; use `<N` or `>N` to insert.",
   "- PUT text: `PUT <address>:` followed by one or more `+` body rows (`+` alone is blank). A final patch newline is allowed. PUT without `:` copies `@name` (or the anonymous register) and takes no body; names use `@` plus ASCII letters, digits, `_`, or `-`.",
-  "- CUT: `CUT <address> [@name]`. REM: bare `REM` only, removing the whole file. MV: `MV <destination>` (one whitespace-free path, optional matching quotes), once and after any line operations. `*** Begin Patch`/`*** End Patch` is an optional envelope.",
-  "- Only `read` (and accepted AFT `cat`/`head`/`tail` rewrites) mint hashline tags. `aft_zoom`, `aft_outline`, `grep`, `aft_search`, and conflict snippets do not. After navigation, call `read` on every file and range the patch addresses."
+  "- CUT: `CUT <address> [@name]`. REM: bare `REM` only, removing the whole file. MV: `MV <destination>` (one whitespace-free path, optional matching quotes), once and after any line operations. `*** Begin Patch`/`*** End Patch` is an optional envelope."
 ].join(`
 `);
+function hashlineEditDescription(config) {
+  const bashRewrites = toolEnabled(config, "bash") && resolveBashConfig(config).rewrite;
+  const tagSources = hashlineTagSourceSentence(bashRewrites, (name) => toolEnabled(config, name));
+  return `${HASHLINE_EDIT_GRAMMAR}
+- ${tagSources}`;
+}
 var HashlineEditParams = Type2.Object({
   patch: Type2.String({
     minLength: 1,
@@ -28930,7 +29687,7 @@ function registerHoistedTools(pi, ctx, surface) {
       name: readName,
       label: readName,
       description: readDescription(resolveGithubConfig(ctx.config).read),
-      promptSnippet: "Read file contents (supports offset/limit for large files)",
+      promptSnippet: "Read files or directories (supports offset/limit for either)",
       promptGuidelines: [`Use ${readName} to examine files instead of cat or sed.`],
       parameters: ReadParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
@@ -29057,7 +29814,7 @@ PDFs aren't supported on the Pi harness yet.`, response);
     pi.registerTool({
       name: editName,
       label: editName,
-      description: HASHLINE_EDIT_DESCRIPTION,
+      description: hashlineEditDescription(ctx.config),
       promptSnippet: `Apply a tagged hashline patch through the ${editName} tool`,
       promptGuidelines: [
         "Read a file to obtain its current hashline tag before editing it.",
@@ -29115,8 +29872,7 @@ PDFs aren't supported on the Pi harness yet.`, response);
         }
         if (isGithubResourcePath(filePathArg)) {
           const edits = params.edits;
-          const onlyFindReplace = Array.isArray(edits) && edits.length > 0 && params.appendContent === undefined && params.symbol === undefined && params.content === undefined && edits.every((entry) => typeof entry.oldString === "string" && (entry.newString === undefined || typeof entry.newString === "string") && entry.startLine === undefined && entry.endLine === undefined && entry.content === undefined);
-          if (!onlyFindReplace) {
+          if (!isFindReplaceOnlyEdit(argsRecord)) {
             throw new Error("edit: GitHub resources support only edits[] find/replace entries with oldString and optional newString");
           }
           const bridge = bridgeFor(ctx, extCtx.cwd);
@@ -29644,34 +30400,17 @@ function registerAstTools(pi, ctx, surface) {
 // src/tools/bash.ts
 import { Container as Container3, Spacer as Spacer3, Text as Text3 } from "@earendil-works/pi-tui";
 import { Type as Type4 } from "typebox";
-
-// src/session-kind.ts
-var MAGIC_CONTEXT_SUBAGENT_ENV = "MAGIC_CONTEXT_PI_SUBAGENT";
-function piWorkerKind(extCtx, env = process.env) {
-  if (env[MAGIC_CONTEXT_SUBAGENT_ENV] === "1")
-    return "delegated";
-  if (extCtx?.hasUI === false)
-    return "headless";
-  return;
-}
-function isPiWorkerSession(extCtx, env = process.env) {
-  return piWorkerKind(extCtx, env) !== undefined;
-}
-function skipsEagerStartup(env = process.env) {
-  return piWorkerKind(undefined, env) === "delegated";
-}
-
-// src/tools/bash.ts
-var BASH_WAIT_POLL_INTERVAL_MS = 100;
 var REGEX_WAIT_SCAN_WINDOW_BYTES = 64 * 1024;
 function watchCallerRole(extCtx, env = process.env) {
   return isPiWorkerSession(extCtx, env) ? "worker" : "primary";
 }
-function coerceConfiguredWatchTimeout(value, cap) {
+function coerceConfiguredWatchTimeout(value, role, cap) {
   try {
-    return coerceOptionalInt(value, "timeoutMs", 1, cap);
+    return coerceOptionalInt(value, "timeoutMs", 1, maxWatchTimeoutMs(role, cap));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (role === "worker")
+      throw error;
     throw new Error(`${message} (bash.watch_sync_max_ms)`);
   }
 }
@@ -29687,7 +30426,9 @@ function resolveForegroundWaitMs(configured) {
 var BASH_TRANSPORT_TIMEOUT_MS2 = 30000;
 var DEFAULT_HARD_TIMEOUT_MS = 30 * 60 * 1000;
 var BASH_TRANSPORT_MARGIN_MS = 1e4;
-function orchestratedTransportTimeoutMs(blockToCompletion, wait, effectiveTimeout, foregroundWaitMs) {
+function orchestratedTransportTimeoutMs(blockToCompletion, wait, effectiveTimeout, foregroundWaitMs, noHardKill = false) {
+  if (noHardKill)
+    return LONGEST_TIMER_DELAY_MS;
   const waitBudget = blockToCompletion || wait ? effectiveTimeout ?? DEFAULT_HARD_TIMEOUT_MS : foregroundWaitMs;
   return waitBudget + BASH_TRANSPORT_MARGIN_MS;
 }
@@ -29701,10 +30442,14 @@ var BashBaseParams = {
   })),
   description: Type4.Optional(Type4.String({
     description: "Human-readable description shown in UI logs. Helps users understand what the command does without reading shell syntax."
-  })),
+  }))
+};
+var BashWaitParam = {
   wait: Type4.Optional(Type4.Boolean({
     description: "When true, run in the foreground without auto-promoting and wait until the command finishes or reaches its timeout; any new message detaches by default, while `bash.detach_on_user_message: false` keeps it blocking unless the message contains the literal `&detach`. The token is stripped before delivery; the rest of the message is preserved, and a token-only message becomes `(requested background detach)`. Use only when you know the result is required before doing anything else."
-  })),
+  }))
+};
+var BashSandboxParam = {
   sandbox: Type4.Optional(Type4.Literal("host", {
     description: "Request one-command approval to run unsandboxed on the host; use only when native sandboxing blocks required work, and note that it is a no-op when sandboxing is disabled."
   }))
@@ -29728,16 +30473,65 @@ var BashPtyParams = {
 };
 var BashParams = Type4.Object({
   ...BashBaseParams,
+  ...BashWaitParam,
+  ...BashSandboxParam,
   ...BashBackgroundFlagParam,
   ...BashCompressionParam,
   ...BashPtyParams
 });
-var BashForegroundOnlyParams = Type4.Object({
-  ...BashBaseParams,
-  ...BashCompressionParam
-});
-function bashParamsForConfig(backgroundEnabled) {
-  return backgroundEnabled ? BashParams : BashForegroundOnlyParams;
+function bashParamsForConfig(features, companions) {
+  return Type4.Object({
+    ...BashBaseParams,
+    ...features.background ? BashWaitParam : {},
+    ...features.sandbox ? BashSandboxParam : {},
+    ...features.background ? {
+      background: Type4.Optional(Type4.Boolean({ description: backgroundParamDescription(companions) }))
+    } : {},
+    ...features.compress ? BashCompressionParam : {},
+    ...features.background ? {
+      ...BashPtyParams,
+      pty: Type4.Optional(Type4.Boolean({
+        description: ptyParamDescription(companions, features.subagentBackground)
+      }))
+    } : {}
+  });
+}
+function bashCompanionRegistered(config, companion) {
+  return resolveBashConfig(config).background && toolEnabled(config, companion);
+}
+function registeredCompanions(config) {
+  return {
+    status: bashCompanionRegistered(config, "bash_status"),
+    watch: bashCompanionRegistered(config, "bash_watch"),
+    write: bashCompanionRegistered(config, "bash_write"),
+    kill: bashCompanionRegistered(config, "bash_kill")
+  };
+}
+function backgroundParamDescription(c) {
+  let controls = "";
+  if (c.watch) {
+    controls += ` Use bash_watch to wait for completion or output patterns${c.status ? "; bash_status for a one-shot snapshot only." : "."}`;
+  } else if (c.status) {
+    controls += " Use bash_status for a one-shot snapshot.";
+  }
+  if (c.kill)
+    controls += " Use bash_kill to terminate.";
+  return `Spawn command in background and return immediately with a task_id.${controls} Ideal for long-running tasks like builds or dev servers.`;
+}
+function ptyParamDescription(c, subagentBackground) {
+  let drive = "";
+  if (c.status && c.write) {
+    drive = ' Inspect with bash_status({ task_id, output_mode: "screen" }) and send input with bash_write.';
+  } else if (c.status) {
+    drive = ' Inspect with bash_status({ task_id, output_mode: "screen" }).';
+  } else if (c.write) {
+    drive = " Send input with bash_write.";
+  }
+  const workers = subagentBackground ? "" : " Unavailable in worker sessions because bash.subagent_background is false.";
+  return `Spawn the command in a real PTY for interactive programs. Implies background: true automatically.${workers}${drive}`;
+}
+function nativeSandboxEnabled(config) {
+  return config.sandbox?.enabled === true;
 }
 var BashTaskParams = Type4.Object({
   task_id: Type4.String({
@@ -29869,18 +30663,47 @@ function getBashSpawnHook(pi) {
   }
   return api.hooks?.bashSpawn;
 }
+function backgroundWaitSentence(c) {
+  if (c.watch) {
+    const noPolling = c.status ? ", and never loop `bash_status` to wait" : "";
+    return `then \`bash_watch\` handles only a short remaining wait (in a main session a watch defaults to 30s, max bash.watch_sync_max_ms, 120s by default; in a delegated session a watch without a timeout waits until the command finishes); for anything longer end the turn and let the completion reminder wake you, or use bash({wait:true}) when the result is needed before anything else — never background a command and immediately \`bash_watch\` it (that wastes a turn for what foreground returns in one)${noPolling}.`;
+  }
+  return c.status ? "the task keeps running after the call returns, a completion reminder arrives when it exits, and `bash_status` reports its state and output. Use bash({wait:true}) instead when the result is needed before anything else." : "the task keeps running after the call returns and a completion reminder arrives when it exits. Use bash({wait:true}) instead when the result is needed before anything else.";
+}
+function ptyDriveClause(c) {
+  if (c.status && c.write) {
+    return ', and is driven with `bash_status({ output_mode: "screen" })` plus `bash_write`';
+  }
+  if (c.status)
+    return ', and its screen is read with `bash_status({ output_mode: "screen" })`';
+  if (c.write)
+    return ", and is driven with `bash_write`";
+  return "";
+}
 function registerBashTool(pi, ctx, aftSearchRegistered = false, registeredName = "bash", registerCompanions = true, shell = "bash") {
   const isPowerShell = shell === "powershell";
   const spawnHook = isPowerShell ? undefined : getBashSpawnHook(pi);
   const readToolName = "read";
   const grepToolName = "grep";
   const zoomSteer = toolEnabled(ctx.config, "aft_zoom") ? ", or `aft_zoom`" : "";
-  const searchSteer = aftSearchRegistered ? `use \`aft_search\` (concepts, identifiers, regex, literals), \`${readToolName}\`, \`aft_outline\`${zoomSteer} instead` : `use the \`${grepToolName}\` tool, \`${readToolName}\`, \`aft_outline\`${zoomSteer} instead`;
+  const steerTools = [
+    aftSearchRegistered ? "`aft_search` (concepts, identifiers, regex, literals)" : `the \`${grepToolName}\` tool`,
+    `\`${readToolName}\``,
+    ...toolEnabled(ctx.config, "aft_outline") ? ["`aft_outline`"] : []
+  ].join(", ");
+  const searchSteer = `use ${steerTools}${zoomSteer} instead`;
+  const companions = registeredCompanions(ctx.config);
   const bashCfg = resolveBashConfig(ctx.config);
   let hostFallbackActive = false;
   const compressionSentence = bashCfg.compress ? " Output is compressed by default; pass `compressed: false` for raw output. Piped commands run verbatim and show the pipeline's output; for AFT's test/build summary, run the runner without `| head`, `| tail`, or `| grep`." : "";
+  const supported = bashCfg.background ? [
+    "workdir",
+    "background tasks",
+    ...bashCfg.compress ? ["compressed output"] : [],
+    "PTY mode"
+  ].join(", ") : bashCfg.compress ? "workdir and compressed output" : "workdir";
   const detachSentence = bashCfg.detach_on_user_message ? "Any new message detaches this wait. Set `bash.detach_on_user_message: false` to keep it blocking; even then, a message containing the literal `&detach` forces detachment, and the token is stripped before delivery; the rest of the message is preserved, while a token-only message becomes `(requested background detach)`." : "Because `bash.detach_on_user_message` is false, a new message leaves this wait blocking; include the literal `&detach` anywhere to force detachment, and the token is stripped before delivery; the rest of the message is preserved, while a token-only message becomes `(requested background detach)`.";
-  const tasksSentence = bashCfg.background ? ` Commands run in the foreground and return inline; \`wait: true\` blocks until a long command finishes instead of auto-promoting; ${detachSentence} Use it when you need the result before doing anything else; keep it off otherwise so auto-promote can remind you while you work. Use \`background: true\` yourself ONLY when you have other useful work to do while it runs; then \`bash_watch\` handles only a short remaining wait (default 30s, max bash.watch_sync_max_ms, 120s by default); for anything longer end the turn and let the completion reminder wake you, or use bash({wait:true}) when the result is needed before anything else — never background a command and immediately \`bash_watch\` it (that wastes a turn for what foreground returns in one), and never loop \`bash_status\` to wait. A \`nohup … &\` launch still holds the call if the child keeps stdout/stderr; redirect both or use background:true. \`pty: true\` runs interactive programs (REPLs, TUIs), implies background, and is driven with \`bash_status({ output_mode: "screen" })\` plus \`bash_write\`.` : " Commands run in the foreground to completion; `timeout` is the hard kill cap (default 30 minutes).";
+  const tasksSentence = bashCfg.background ? ` Commands run in the foreground and return inline; \`wait: true\` blocks until a long command finishes instead of auto-promoting; ${detachSentence} Use it when you need the result before doing anything else; keep it off otherwise so auto-promote can remind you while you work. Use \`background: true\` yourself ONLY when you have other useful work to do while it runs; ${backgroundWaitSentence(companions)} A \`nohup … &\` launch still holds the call if the child keeps stdout/stderr; redirect both or use background:true. \`pty: true\` runs interactive programs (REPLs, TUIs), implies background${ptyDriveClause(companions)}.` : " Commands run in the foreground to completion; `timeout` is the hard kill cap (default 30 minutes).";
   pi.registerTool({
     name: registeredName,
     label: registeredName,
@@ -29889,13 +30712,18 @@ function registerBashTool(pi, ctx, aftSearchRegistered = false, registeredName =
 PowerShell syntax is not analyzed as POSIX shell. Each command requires explicit approval so syntax AFT cannot safely interpret is never auto-allowed.` : `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}. When a list is cut, the reply ends with \`shown N of M <unit> (<reason>) · narrow: <knobs>\`; absence of that line means the list is complete.`,
-    promptSnippet: isPowerShell ? "Run PowerShell commands (timeout in milliseconds; supports workdir, background tasks, compressed output, PTY mode)" : bashCfg.background ? "Run shell commands (timeout in milliseconds; supports workdir, background tasks, compressed output, PTY mode)" : "Run shell commands (timeout in milliseconds; supports workdir and compressed output)",
+    promptSnippet: isPowerShell ? `Run PowerShell commands (timeout in milliseconds; supports ${supported})` : `Run shell commands (timeout in milliseconds; supports ${supported})`,
     promptGuidelines: isPowerShell ? ["Use PowerShell syntax. Every command requires explicit approval."] : [
       `DO NOT use bash for code search or exploration — ${searchSteer}.`,
-      "Set compressed: false when you need ANSI color codes in the output.",
+      ...bashCfg.compress ? ["Set compressed: false when you need ANSI color codes in the output."] : [],
       "Piped commands run verbatim and show the pipeline's output; run test/build tools without pipes when you need AFT's summary."
     ],
-    parameters: bashParamsForConfig(bashCfg.background),
+    parameters: bashParamsForConfig({
+      background: bashCfg.background,
+      compress: bashCfg.compress,
+      sandbox: nativeSandboxEnabled(ctx.config),
+      subagentBackground: bashCfg.subagent_background
+    }, companions),
     async execute(_toolCallId, params, signal, onUpdate, extCtx) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const bashCfg = resolveBashConfig(ctx.config);
@@ -29905,7 +30733,7 @@ DO NOT use bash for code search or code exploration. If you are about to run gre
       const ptyRows = backgroundDisabled ? undefined : coerceOptionalInt(params.ptyRows, "ptyRows", 1, 60);
       const ptyCols = backgroundDisabled ? undefined : coerceOptionalInt(params.ptyCols, "ptyCols", 1, 140);
       const compressed = coerceBoolean(params.compressed, true);
-      const requestedWait = coerceBoolean(params.wait);
+      const requestedWait = !backgroundDisabled && coerceBoolean(params.wait);
       const rawRequestedPty = coerceBoolean(params.pty);
       const rawRequestedBackground = coerceBoolean(params.background);
       if (requestedWait && rawRequestedPty) {
@@ -29921,6 +30749,8 @@ DO NOT use bash for code search or code exploration. If you are about to run gre
       }
       const blockToCompletion = backgroundDisabled || requestedWait || workerForcedForeground;
       const effectiveBackground = !blockToCompletion && (rawRequestedBackground || requestedPty);
+      const isWorker = isPiWorkerSession(extCtx);
+      const workerUnboundedWait = isWorker && requestedWait && timeout === undefined;
       let spawnContext = {
         command: params.command,
         cwd: params.workdir
@@ -29955,7 +30785,7 @@ DO NOT use bash for code search or code exploration. If you are about to run gre
           sandbox: params.sandbox,
           ...isPowerShell ? { shell: "powershell" } : {}
         }, extCtx, {
-          transportTimeoutMs: orchestratedTransportTimeoutMs(blockToCompletion, requestedWait, timeout, foregroundWaitMs),
+          transportTimeoutMs: orchestratedTransportTimeoutMs(blockToCompletion, requestedWait, timeout, foregroundWaitMs, workerUnboundedWait),
           onProgress: ({ text }) => {
             streamed += text;
             const displayText = truncateToVisualLines(streamed, 100);
@@ -29966,10 +30796,10 @@ DO NOT use bash for code search or code exploration. If you are about to run gre
         const fallbackCause = classifyBashHostFallbackError(error);
         if (isPowerShell || !bashCfg.host_fallback || fallbackCause === undefined)
           throw error;
-        if (rawRequestedBackground) {
+        if (!backgroundDisabled && rawRequestedBackground) {
           throw new Error(`${BASH_HOST_FALLBACK_REFUSAL}; background:true is unsupported.`);
         }
-        if (rawRequestedPty) {
+        if (requestedPty) {
           throw new Error(`${BASH_HOST_FALLBACK_REFUSAL}; pty:true is unsupported.`);
         }
         if (!extCtx.hasUI || typeof extCtx.ui?.confirm !== "function") {
@@ -30024,6 +30854,8 @@ DO NOT use bash for code search or code exploration. If you are about to run gre
     registerBashCompanionTools(pi, ctx);
 }
 function registerBashCompanionTools(pi, ctx, enabled = { bashStatus: true, bashWatch: true, bashWrite: true, bashKill: true }) {
+  if (!resolveBashConfig(ctx.config).background)
+    return;
   if (enabled.bashStatus) {
     pi.registerTool(createBashStatusTool(ctx));
   }
@@ -30044,7 +30876,7 @@ function createBashStatusTool(ctx) {
   return {
     name: "bash_status",
     label: "bash_status",
-    description: "Read-only snapshot of a background bash task. Returns immediately. Never waits. One look to check on a task is fine — never loop it to wait for completion. To wait, use bash_watch.",
+    description: `Read-only snapshot of a background bash task. Returns immediately. Never waits. One look to check on a task is fine — never loop it to wait for completion.${bashCompanionRegistered(ctx.config, "bash_watch") ? " To wait, use bash_watch." : ""}`,
     promptSnippet: "Inspect a background bash task by task_id",
     parameters: BashStatusParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
@@ -30062,10 +30894,10 @@ function createBashWatchTool(ctx) {
   return {
     name: "bash_watch",
     label: "bash_watch",
-    description: "Watch a background bash task. Sync waits are for a short remaining wait on a task (default 30s, max `bash.watch_sync_max_ms`, 120s by default); for anything longer end the turn on `bash({background:true})` and let the completion reminder wake you, or use `bash({wait:true})` when the result is needed before anything else. The user can interrupt anytime; the wait auto-converts to an async notification. Async (background:true, requires pattern) registers a non-blocking notification and returns immediately — use when you have parallel work or want to end your turn. Never loop bash_status to wait.",
+    description: `Watch a background bash task. ${WATCH_SYNC_DEFAULTS_DESCRIPTION}. In a main session sync waits are for a short remaining wait on a task; for anything longer end the turn on \`bash({background:true})\` and let the completion reminder wake you, or use \`bash({wait:true})\` when the result is needed before anything else. The user can interrupt anytime; the wait auto-converts to an async notification. Async (background:true, requires pattern) registers a non-blocking notification and returns immediately — use when you have parallel work or want to end your turn.${bashCompanionRegistered(ctx.config, "bash_status") ? " Never loop bash_status to wait." : ""}`,
     promptSnippet: "Wait for or watch a background bash task",
     parameters: BashWatchParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
+    async execute(_toolCallId, params, signal, _onUpdate, extCtx) {
       const bridge = bridgeFor(ctx, extCtx.cwd);
       const waitFor = parseWaitPattern(params.pattern);
       const bashCfg = resolveBashConfig(ctx.config);
@@ -30102,10 +30934,10 @@ A notification will fire when the pattern matches or the task exits.`, watchDeta
       }
       const syncWaitCap = bashCfg.watch_sync_max_ms;
       const role = watchCallerRole(extCtx);
-      const effectiveWaitMs = workerForcedSync ? syncWaitCap : resolveWatchTimeoutMs(coerceConfiguredWatchTimeout(params.timeout_ms, syncWaitCap), role, syncWaitCap);
-      const data = await waitForBashStatus(ctx, bridge, extCtx, params.task_id, undefined, waitFor, true, effectiveWaitMs);
+      const effectiveWaitMs = workerForcedSync ? undefined : resolveWatchTimeoutMs(coerceConfiguredWatchTimeout(params.timeout_ms, role, syncWaitCap), role, syncWaitCap);
+      const data = await waitForBashStatus(ctx, bridge, extCtx, params.task_id, undefined, waitFor, true, effectiveWaitMs, signal);
       if (data.waited?.reason === "user_message") {
-        const convertedText = await convertToAsyncWatchOnAbort(bridge, extCtx, params.task_id, waitFor, coerceBoolean(params.once, true));
+        const convertedText = await convertToAsyncWatchOnAbort(bridge, extCtx, params.task_id, waitFor, coerceBoolean(params.once, true), data.waited.elapsed_ms, role);
         return textResult(convertedText, { waited: data.waited });
       }
       const text = await formatBashStatus(extCtx, params.task_id, data, undefined, { role, capMs: syncWaitCap });
@@ -30113,9 +30945,11 @@ A notification will fire when the pattern matches or the task exits.`, watchDeta
     }
   };
 }
-async function convertToAsyncWatchOnAbort(bridge, extCtx, taskId, waitFor, once) {
+async function convertToAsyncWatchOnAbort(bridge, extCtx, taskId, waitFor, once, elapsedMs, role) {
+  const interrupted = `Sync watch for task ${taskId} was interrupted because you sent a message after ${elapsedMs}ms of waiting. `;
+  const reminderFallback = interruptedWatchTail(role, `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits.`);
   if (!waitFor) {
-    return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits; don't poll bash_status.`;
+    return interrupted + interruptedWatchTail(role, `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits; don't poll bash_status.`);
   }
   const notifyParams = {
     task_id: taskId,
@@ -30131,19 +30965,19 @@ async function convertToAsyncWatchOnAbort(bridge, extCtx, taskId, waitFor, once)
     const registered = await callBashBridge(bridge, "bash_notify", notifyParams, extCtx);
     if (registered.success === false) {
       unmarkExplicitControl(sessionId, taskId);
-      return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `Auto-registering an async watch failed (${String(registered.message ?? "unknown error")}). ` + `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits.`;
+      return interrupted + `Auto-registering an async watch failed (${String(registered.message ?? "unknown error")}). ` + reminderFallback;
     }
-    return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `The wait has been converted to an async watch (${registered.watch_id}). ` + `A notification will fire when the pattern matches or the task exits.`;
+    return interrupted + `The wait has been converted to an async watch (${registered.watch_id}). ` + interruptedWatchTail(role, `A notification will fire when the pattern matches or the task exits.`);
   } catch (err) {
     unmarkExplicitControl(sessionId, taskId);
-    return `Sync watch for task ${taskId} was interrupted because you sent a message. ` + `Auto-registering an async watch failed (${err instanceof Error ? err.message : String(err)}). ` + `The task is still running in the background. A completion reminder will be ` + `delivered automatically when the task exits.`;
+    return interrupted + `Auto-registering an async watch failed (${err instanceof Error ? err.message : String(err)}). ` + reminderFallback;
   }
 }
 function createBashWriteTool(ctx) {
   return {
     name: "bash_write",
     label: "bash_write",
-    description: 'Write input bytes to a running PTY bash task. PTY-only; check bash_status reports mode: "pty" first. ' + 'Input is either a string (verbatim bytes) or an array mixing strings and { key: "esc" | "enter" | "up" | "ctrl-c" | ... } objects ' + 'for atomic text+key sequences such as [ "iHello", { key: "esc" }, ":wq", { key: "enter" } ]. ' + "Named keys cover enter/return/tab/space/backspace/esc/escape, arrows, home/end/page-up/page-down/delete/insert, f1..f12, and ctrl-a..ctrl-z. " + "Maximum 1 MiB per call (post-expansion).",
+    description: `Write input bytes to a running PTY bash task. PTY-only${bashCompanionRegistered(ctx.config, "bash_status") ? '; check bash_status reports mode: "pty" first.' : "."} ` + 'Input is either a string (verbatim bytes) or an array mixing strings and { key: "esc" | "enter" | "up" | "ctrl-c" | ... } objects ' + 'for atomic text+key sequences such as [ "iHello", { key: "esc" }, ":wq", { key: "enter" } ]. ' + "Named keys cover enter/return/tab/space/backspace/esc/escape, arrows, home/end/page-up/page-down/delete/insert, f1..f12, and ctrl-a..ctrl-z. " + "Maximum 1 MiB per call (post-expansion).",
     promptSnippet: "Write keystrokes/input to a PTY bash task",
     parameters: BashWriteParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
@@ -30207,9 +31041,17 @@ async function bashStatusSnapshot(bridge, extCtx, taskId, outputMode, options, c
     stderr_offset: cursor?.stderr
   }, extCtx, options);
 }
-async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFor, waitForExit, effectiveWaitMs) {
-  const startedAt = Date.now();
-  const deadline = startedAt + effectiveWaitMs;
+async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFor, waitForExit, effectiveWaitMs, abortSignal) {
+  const startedAt = watchClock.now();
+  const deadline = effectiveWaitMs === undefined ? Number.POSITIVE_INFINITY : startedAt + effectiveWaitMs;
+  const elapsedMs = () => Math.round(watchClock.now() - startedAt);
+  const pause = () => watchClock.sleep(Math.min(watchPollDelayMs(elapsedMs()), Math.max(0, deadline - watchClock.now())), abortSignal);
+  const waited = (reason, extra = {}) => ({
+    reason,
+    elapsed_ms: elapsedMs(),
+    ...effectiveWaitMs === undefined ? {} : { limit_ms: effectiveWaitMs },
+    ...extra
+  });
   let spillCursor = { output: 0, stderr: 0 };
   const scanState = {
     output: { text: "", baseOffset: 0 },
@@ -30228,29 +31070,29 @@ async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFo
     markTaskWaiting(sessionId, taskId);
   let sawTerminal = false;
   let lastData;
+  let busySince;
   try {
     while (true) {
+      if (abortSignal?.aborted) {
+        return withWaited(lastData ?? unavailableSnapshot(), waited("aborted"));
+      }
       let data;
       try {
         data = await bashStatusSnapshot(bridge, extCtx, taskId, outputMode, bridgeOptions, waitFor ? spillCursor : undefined);
       } catch (err) {
         if (!isBridgeTransportTimeout(err))
           throw err;
+        busySince ??= watchClock.now();
         if (isSyncWatchAborted(sessionId)) {
-          return withWaited(lastData ?? unavailableSnapshot(), {
-            reason: "user_message",
-            elapsed_ms: Date.now() - startedAt
-          });
+          return withWaited(lastData ?? unavailableSnapshot(), waited("user_message"));
         }
-        if (Date.now() >= deadline) {
-          return withWaited(lastData ?? unavailableSnapshot(), {
-            reason: "unavailable",
-            elapsed_ms: Date.now() - startedAt
-          });
+        if (watchClock.now() >= deadline || watchClock.now() - busySince >= WATCH_UNAVAILABLE_GIVE_UP_MS) {
+          return withWaited(lastData ?? unavailableSnapshot(), waited("unavailable"));
         }
-        await sleep(Math.min(BASH_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
+        await pause();
         continue;
       }
+      busySince = undefined;
       lastData = data;
       const terminal = isTerminalStatus(data.status);
       if (waitFor) {
@@ -30275,13 +31117,11 @@ async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFo
                 await markBgCompletionDelivered({ ctx, directory: extCtx.cwd, sessionID: sessionId }, taskId);
               }
               const matchStream = data.mode === "pty" ? undefined : chunk.stream === "output" ? "stdout" : "stderr";
-              return withWaited(data, {
-                reason: "matched",
-                elapsed_ms: Date.now() - startedAt,
+              return withWaited(data, waited("matched", {
                 match: match.text,
                 match_offset: state.baseOffset + match.byteOffset,
                 match_stream: matchStream
-              });
+              }));
             }
             if (waitFor.kind === "substring") {
               const trimmed = trimWaitScanBuffer(state.text, state.baseOffset, waitFor);
@@ -30297,15 +31137,15 @@ async function waitForBashStatus(ctx, bridge, extCtx, taskId, outputMode, waitFo
           consumeBgCompletion(sessionId, taskId);
           await markBgCompletionDelivered({ ctx, directory: extCtx.cwd, sessionID: sessionId }, taskId);
         }
-        return withWaited(data, { reason: "exited", elapsed_ms: Date.now() - startedAt });
+        return withWaited(data, waited("exited"));
       }
       if (isSyncWatchAborted(sessionId)) {
-        return withWaited(data, { reason: "user_message", elapsed_ms: Date.now() - startedAt });
+        return withWaited(data, waited("user_message"));
       }
-      if (Date.now() >= deadline) {
-        return withWaited(data, { reason: "timeout", elapsed_ms: Date.now() - startedAt });
+      if (watchClock.now() >= deadline) {
+        return withWaited(data, waited("timeout"));
       }
-      await sleep(Math.min(BASH_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
+      await pause();
     }
   } finally {
     if (waitForExit && !sawTerminal)
@@ -30412,18 +31252,22 @@ function withWaited(data, waited) {
   return { ...data, waited };
 }
 function formatWaitSummary(waited, details, watchRole) {
+  const waitedText = formatWatchWaited(waited.elapsed_ms, waited.limit_ms, watchRole.role === "primary" ? watchRole.capMs : undefined);
   if (waited.reason === "matched") {
     const stream = waited.match_stream ? ` in ${waited.match_stream}` : "";
-    return `Waited ${waited.elapsed_ms}ms; matched ${JSON.stringify(waited.match ?? "")}${stream} at offset ${waited.match_offset ?? 0}.`;
+    return `${waitedText}; matched ${JSON.stringify(waited.match ?? "")}${stream} at offset ${waited.match_offset ?? 0}.`;
   }
   if (waited.reason === "timeout") {
-    return `Waited ${waited.elapsed_ms}ms; timeout reached without match. ${watchTimeoutSteer(watchRole.role, watchRole.capMs, "timeout_ms")}`;
+    return `${waitedText}; timeout reached without match. ${watchTimeoutSteer(watchRole.role, "timeout_ms")}`;
   }
   if (waited.reason === "unavailable") {
-    return `Waited ${waited.elapsed_ms}ms; the bridge was busy, so task state is unknown. Do not poll; let the task's completion notification wake the session, or use one bash_status snapshot on the next normal tool call.`;
+    return `${waitedText}; ${watchUnavailableSteer(watchRole.role)}`;
+  }
+  if (waited.reason === "aborted") {
+    return `${waitedText}; the watch was cancelled. The task keeps running.`;
   }
   const exit = typeof details.exit_code === "number" ? `, exit ${details.exit_code}` : "";
-  return `Waited ${waited.elapsed_ms}ms; task exited (${details.status}${exit}).`;
+  return `${waitedText}; task exited (${details.status}${exit}).`;
 }
 async function formatBashStatus(extCtx, taskId, details, requestedOutputMode, watchRole) {
   const exit = typeof details.exit_code === "number" ? ` (exit ${details.exit_code})` : "";
@@ -30442,10 +31286,10 @@ ${formatWaitSummary(details.waited, details, watchRole)}`;
       text += `
 ${details.output_preview}`;
     }
-    const workerWatchTimeout = watchRole.role === "worker" && details.waited?.reason === "timeout";
-    if (!isTerminalStatus(details.status) && !workerWatchTimeout) {
+    const workerWatchReturned = watchRole.role === "worker" && details.waited !== undefined;
+    if (!isTerminalStatus(details.status) && !workerWatchReturned) {
       text += `
-A completion reminder will be delivered automatically; don't poll.`;
+${runningTaskStatusHint(watchRole.role)}`;
     }
   }
   return text;
@@ -30690,7 +31534,7 @@ function registerFsTools(pi, ctx, surface) {
     pi.registerTool(withPathAliasPreparation({
       name: "aft_delete",
       label: "delete",
-      description: "Delete one or more files (or directories). " + (backupsDisabled ? "Backup capture is disabled by user config, so this tool does not create undo snapshots. " : "Each file is backed up before deletion — use `aft_safety undo` to recover any of them. For directories, every file inside is individually backed up before removal. The deleted file's contents stay in the undo store until its retention expires. A recursive delete whose backup would copy more than 2,000 files or 100 MiB in one call is refused before anything is deleted; delete such a tree in smaller pieces, or use bash `rm -rf` when no undo is needed. ") + "Directory deletion requires recursive: true. " + "Returns { success, complete, deleted, skipped_files }: partial success is allowed; files that fail are reported in skipped_files.",
+      description: "Delete one or more files (or directories). " + (backupsDisabled ? "Backup capture is disabled by user config, so this tool does not create undo snapshots. A directory tree containing a mount point of another filesystem is still refused. " : "Each file is backed up before deletion — use `aft_safety undo` to recover any of them. A recursive delete backs up the whole tree: directories (empty ones too, with their permissions), file contents, hard links (relinked by undo) and symlinks (the link itself, never its target; restored exactly, even when dangling). Sockets are deleted but undo does not restore them, and a file hard-linked to paths outside the tree comes back as an independent copy; both are reported as warnings. Refused before anything is deleted: mount points of another filesystem, named pipes, device nodes, and symlinks undo cannot recreate exactly (non-UTF-8 target, or on Windows). Paths under the system temp directory are never backed up, so only mount points are refused there. The deleted file's contents stay in the undo store until its retention expires. A recursive delete whose backup would record more than 2,000 entries (files, directories and links) or copy 100 MiB in one call is refused before anything is deleted; delete such a tree in smaller pieces, or use bash `rm -rf` when no undo is needed. ") + "Directory deletion requires recursive: true. " + "Returns { success, complete, deleted, skipped_files }: partial success is allowed; files that fail are reported in skipped_files.",
       parameters: DeleteParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const inputs = coerceStringArray(params.files);
@@ -30698,14 +31542,13 @@ function registerFsTools(pi, ctx, surface) {
           throw new Error("delete: `files` must be a non-empty array of paths");
         }
         const files = await Promise.all(inputs.map((file) => resolvePathArg(extCtx.cwd, file)));
+        const restrictToProjectRoot = ctx.config.restrict_to_project_root ?? false;
         const checked = new Set;
         for (const file of files) {
           if (checked.has(file))
             continue;
           checked.add(file);
-          await assertExternalDirectoryPermission(extCtx, file, {
-            restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
-          });
+          await assertExternalDirectoryPermission(extCtx, file, { restrictToProjectRoot });
         }
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const response = await callToolCall(bridge, "delete", {
@@ -30743,10 +31586,9 @@ function registerFsTools(pi, ctx, surface) {
         const filePath = await resolvePathArg(extCtx.cwd, params.path);
         const destination = await resolvePathArg(extCtx.cwd, params.destination);
         const checked = new Set([filePath, destination]);
+        const restrictToProjectRoot = ctx.config.restrict_to_project_root ?? false;
         for (const file of checked) {
-          await assertExternalDirectoryPermission(extCtx, file, {
-            restrictToProjectRoot: ctx.config.restrict_to_project_root ?? false
-          });
+          await assertExternalDirectoryPermission(extCtx, file, { restrictToProjectRoot });
         }
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const response = await callToolCall(bridge, "move", {
@@ -31391,6 +32233,9 @@ function registerNavigateTool(pi, ctx) {
 
 // src/tools/reading.ts
 import { Type as Type10 } from "typebox";
+function isGithubPathArg(value) {
+  return typeof value === "string" && (value.startsWith("issue://") || value.startsWith("pr://"));
+}
 var OutlineParams = Type10.Object({
   target: Type10.Union([Type10.String(), Type10.Array(Type10.String())], {
     description: "What to outline: a file path, directory path, URL (http:// or https://), or array of file paths. The mode is auto-detected: URLs by `http://`/`https://` prefix, directories by stat, arrays as multi-file."
@@ -31415,7 +32260,7 @@ var ZoomParams = Type10.Object({
     description: "Symbol name for code, or heading text for Markdown/HTML. Pass a string or array for batched lookups in the same file/URL."
   })),
   targets: Type10.Optional(Type10.Union([ZoomTarget, Type10.Array(ZoomTarget)], {
-    description: "Cross-file batch: `{ path, symbol }` or an array of them. Mutually exclusive with path/url/symbols."
+    description: "Cross-file batch: `{ path, symbol }` or an array of them. May be combined with path/url + symbols; all lookups are answered in one batch."
   })),
   contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER, "Lines of context before/after (default: 3)"),
   callgraph: Type10.Optional(Type10.Boolean({
@@ -31569,6 +32414,13 @@ function renderZoomResult(result, args, theme, context, options = { expanded: tr
     context
   });
 }
+function outlineFocusSteer(config) {
+  const zoomEnabled = toolEnabled(config, "aft_zoom");
+  const reader = zoomEnabled ? "aft_zoom" : "read";
+  const locate = toolEnabled(config, "aft_search") ? `aft_search + ${reader}` : reader;
+  const callgraph = zoomEnabled ? toolEnabled(config, "aft_callgraph") ? " aft_zoom with `callgraph:true` gives one-level forward calls-out; use aft_callgraph only for reverse callers or multi-level traces." : " aft_zoom with `callgraph:true` gives one-level forward calls-out." : "";
+  return `For understanding a specific feature, prefer ${locate} on named symbols; use aft_outline on a whole directory only for high-level structure mapping.${callgraph}`;
+}
 function registerReadingTools(pi, ctx, surface) {
   const zoomEnabled = toolEnabled(ctx.config, "aft_zoom");
   const ghReadEnabled = resolveGithubConfig(ctx.config).read;
@@ -31580,7 +32432,7 @@ function registerReadingTools(pi, ctx, surface) {
       label: "outline",
       description: `Structural outline of source code, documentation files, or remote URLs. For code, returns symbols (functions, classes, types) with line ranges. For Markdown and HTML, returns heading hierarchy. Use this to explore structure before reading specific sections with ${zoomEnabled ? "aft_zoom" : "read"}. With \`files: true\`, the outline is breadth-first with directory rollups; drill in by outlining a subdirectory. Rows show language, symbol count, and line count.
 
-${zoomEnabled ? "For understanding a specific feature, prefer aft_search + aft_zoom on named symbols; use aft_outline on a whole directory only for high-level structure mapping. aft_zoom with `callgraph:true` gives one-level forward calls-out; use aft_callgraph only for reverse callers or multi-level traces." : "For understanding a specific feature, prefer aft_search + read on named symbols; use aft_outline on a whole directory only for high-level structure mapping."}
+${outlineFocusSteer(ctx.config)}
 
 Pass a single \`target\`:
   • file path → outline that file (with signatures)
@@ -31647,56 +32499,49 @@ When a list is cut, the reply ends with \`shown N of M <unit> (<reason>) · narr
     pi.registerTool(withPathAliasPreparation({
       name: "aft_zoom",
       label: "zoom",
-      description: "Inspect code symbols or documentation sections. For code, returns the full source of a symbol. Pass `callgraph: true` to also include call-graph annotations (calls-out / called-by within the same file). For Markdown and HTML, returns the section content under the given heading.\n\nUse exactly ONE mode: `{ path, symbols }`, `{ url, symbols }`, or `{ targets }`. `symbols` can be a string or array (one or many lookups in the same file/URL). Use `targets` for cross-file batches: `{ path, symbol }` or an array of them." + (githubZoomDescription ? `
+      description: "Inspect code symbols or documentation sections. For code, returns the full source of a symbol. Pass `callgraph: true` to also include call-graph annotations (calls-out / called-by within the same file). For Markdown and HTML, returns the section content under the given heading.\n\nUse `{ path, symbols }` or `{ url, symbols }` for one file/URL. `symbols` can be a string or array (one or many lookups in the same file/URL). Use `targets` for cross-file batches: `{ path, symbol }` or an array of them. Sending both merges them into one batch; a lookup that fails reports its own error line." + (githubZoomDescription ? `
 
 ${githubZoomDescription}` : ""),
       parameters: ZoomParams,
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
-        const hasTargetsProvided = (t) => {
-          if (isEmptyParam(t))
-            return false;
-          const entryEmpty = (entry) => {
-            if (!entry || typeof entry !== "object")
-              return true;
-            const fp = entry.path;
-            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 targetsInput = coerceJsonCollectionParam(params.targets, "targets");
-        const hasPath = !isEmptyParam(params.path);
-        const hasUrl = !isEmptyParam(params.url);
-        const hasTargets = hasTargetsProvided(targetsInput);
-        const hasSymbols = !isEmptyParam(params.symbols);
+        const targetEntries = usableZoomTargets(targetsInput);
+        const hasPath = !isBlankParam(params.path);
+        const hasUrl = !isBlankParam(params.url);
+        const hasTargets = targetEntries.length > 0;
+        const hasSymbols = !isBlankParam(params.symbols);
         const wantCallgraph = coerceBoolean(params.callgraph);
         const contextLines = coerceOptionalInt(params.contextLines, "contextLines", 1, Number.MAX_SAFE_INTEGER);
         if (hasTargets) {
-          if (hasPath || hasUrl || hasSymbols) {
-            throw new Error("'targets' is mutually exclusive with 'path', 'url', and 'symbols'");
+          if (hasPath && hasUrl) {
+            throw new Error("Provide exactly ONE of 'path' or 'url' — not both");
           }
-          const targets = Array.isArray(targetsInput) ? targetsInput : [targetsInput];
-          if (targets.length === 0) {
-            throw new Error("'targets' must be a non-empty object or array");
-          }
-          for (const [i, entry] of targets.entries()) {
-            if (!entry || typeof entry.path !== "string" || entry.path.length === 0) {
+          const targets = targetEntries.map((entry, i) => {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
               throw new Error(`targets[${i}].path must be a non-empty string`);
             }
-            if (typeof entry.symbol !== "string" || entry.symbol.length === 0) {
-              throw new Error(`targets[${i}].symbol must be a non-empty string`);
-            }
-          }
-          const resolvedTargets = await Promise.all(targets.map((t) => resolvePathArg(extCtx.cwd, t.path)));
+            const record = entry;
+            const targetPath = isBlankParam(record.path) ? record.filePath : record.path;
+            return {
+              path: typeof targetPath === "string" ? targetPath : "",
+              symbol: typeof record.symbol === "string" ? record.symbol : ""
+            };
+          });
+          const localPaths = targets.map((target) => target.path).filter((path) => path.trim().length > 0 && !isGithubPathArg(path));
+          if (hasPath && !isGithubPathArg(params.path))
+            localPaths.push(params.path);
+          const resolvedTargets = await Promise.all(localPaths.map((path) => resolvePathArg(extCtx.cwd, path)));
           await assertReadPathPermissions(extCtx, ctx, resolvedTargets);
           const rawArgs = {
             targets: targets.map((target) => ({ filePath: target.path, symbol: target.symbol }))
           };
+          if (hasPath)
+            rawArgs.filePath = params.path;
+          else if (hasUrl)
+            rawArgs.url = params.url;
+          if (hasSymbols)
+            rawArgs.symbols = params.symbols;
           if (contextLines !== undefined)
             rawArgs.contextLines = contextLines;
           if (wantCallgraph)
@@ -31713,7 +32558,7 @@ ${githubZoomDescription}` : ""),
         if (hasPath && hasUrl) {
           throw new Error("Provide exactly ONE of 'path' or 'url' — not both");
         }
-        const githubPath = hasPath && (String(params.path).startsWith("issue://") || String(params.path).startsWith("pr://")) || hasUrl && (String(params.url).startsWith("issue://") || String(params.url).startsWith("pr://"));
+        const githubPath = hasPath && isGithubPathArg(params.path) || hasUrl && isGithubPathArg(params.url);
         if (!hasUrl && !githubPath) {
           const file = await resolvePathArg(extCtx.cwd, params.path);
           await assertReadPathPermissions(extCtx, ctx, file);
@@ -31752,7 +32597,7 @@ var SafetyParams = Type11.Object({
     description: "Safety operation"
   }),
   path: Type11.Optional(Type11.String({
-    description: "File path (required for history, optional for undo, optional for restore — restores only that file). Absolute or relative to project root."
+    description: "File path (required for history, optional for undo, optional for checkpoint — snapshots only that file when files is omitted, optional for restore — restores only that file). Absolute or relative to project root."
   })),
   name: Type11.Optional(Type11.String({ description: "Checkpoint name (required for checkpoint, restore)" })),
   files: Type11.Optional(Type11.Array(Type11.String(), {
@@ -32176,9 +33021,17 @@ function piHashlineDowngrade(config, surface) {
     message: 'edit_mode "hashline" is not in effect because "read" is in disabled_tools (hashline edits need tagged reads); registered tools keep their ordinary behavior.'
   };
 }
+function withLiveRestriction(surface, ctx) {
+  return Object.defineProperty({ ...surface }, "restrictToProjectRoot", {
+    enumerable: true,
+    get: () => ctx.config.restrict_to_project_root ?? false
+  });
+}
 function resolvePiToolSurface(config, pi) {
   const disabled = new Set(resolvedDisabledTools(config));
   const ok = (name) => !disabled.has(name);
+  const background = resolveBashConfig(config).background;
+  const companion = (name) => background && ok(name);
   const powershellEnabled = (pi ? piPowerShellEnabledFromHost(pi) : undefined) ?? resolvePiPowerShellFallback(config);
   return {
     hoistBash: ok("bash"),
@@ -32200,10 +33053,10 @@ function resolvePiToolSurface(config, pi) {
     move: ok("aft_move"),
     astSearch: ok("ast_grep_search"),
     astReplace: ok("ast_grep_replace"),
-    bashStatus: ok("bash_status"),
-    bashWatch: ok("bash_watch"),
-    bashWrite: ok("bash_write"),
-    bashKill: ok("bash_kill")
+    bashStatus: companion("bash_status"),
+    bashWatch: companion("bash_watch"),
+    bashWrite: companion("bash_write"),
+    bashKill: companion("bash_kill")
   };
 }
 var FUNNEL_BOUND = Symbol.for("aft.pi.registration_funnel_bound");
@@ -32228,7 +33081,8 @@ function bindToolRegistrationFunnel(pi, ctx, harness) {
     }
   });
 }
-function registerPiToolSurface(pi, ctx, surface, harness) {
+function registerPiToolSurface(pi, ctx, loadedSurface, harness) {
+  const surface = withLiveRestriction(loadedSurface, ctx);
   const boundPi = bindToolRegistrationFunnel(pi, ctx, harness);
   if (surface.hoistBash)
     registerBashTool(boundPi, ctx, surface.semantic, "bash", false);
@@ -32262,6 +33116,8 @@ var CONFIG_ERROR_STATUS_KEY = "aft";
 var defaultDependencies = {
   loadConfig: loadAftConfig,
   configLoadErrors: getConfigLoadErrors,
+  configLoadSources: getConfigLoadSources,
+  configLoadTexts: getConfigLoadTexts,
   migrateConfigLocations: (directory) => migrateAftConfigLocations(directory, bridgeLogger).flatMap((result) => result.warnings),
   subcConnectionFileError
 };
@@ -32280,6 +33136,8 @@ function parseFailure(dependencies) {
 }
 async function resolvePiBootstrapConfig(directory, notify, dependencies = defaultDependencies) {
   let config;
+  let sources = [];
+  let sourceTexts = {};
   try {
     dependencies.loadConfig(directory);
     const firstFailure = parseFailure(dependencies);
@@ -32291,11 +33149,13 @@ async function resolvePiBootstrapConfig(directory, notify, dependencies = defaul
     const failure = parseFailure(dependencies);
     if (failure)
       return configErrorState(failure, notify);
+    sources = [...dependencies.configLoadSources?.() ?? []];
+    sourceTexts = Object.fromEntries(dependencies.configLoadTexts?.() ?? []);
   } catch (err) {
     return configErrorState(err instanceof Error ? err.message : String(err), notify);
   }
   const missing = await dependencies.subcConnectionFileError(config.subc?.connection_file);
-  return missing === null ? { ok: true, config } : configErrorState(missing, notify, config);
+  return missing === null ? { ok: true, config, sources, sourceTexts } : configErrorState(missing, notify, config);
 }
 function failingRegistrations(pi, message) {
   const registerTool = (tool) => {
@@ -32331,6 +33191,58 @@ function registerPiConfigErrorState(pi, config, message) {
   log2("AFT is in the config error state; every tool call will fail");
 }
 
+// src/config-live-reload.ts
+var PI_LIVE_CONFIG_KEYS = aftLiveConfigKeys((config) => resolveBashConfig(config));
+function projectTextOf(directory) {
+  const { projectConfigPath } = resolveCortexKitConfigPaths(directory);
+  return getConfigLoadTexts().get(projectConfigPath) ?? null;
+}
+function loadPiConfigForLiveReload(directory) {
+  try {
+    const config = loadAftConfig(directory);
+    const [failure] = getConfigLoadErrors();
+    if (failure) {
+      return { ok: false, message: formatConfigParseErrorMessage(failure.path, failure.message) };
+    }
+    const [invalid] = getConfigValidationErrors();
+    if (invalid) {
+      return {
+        ok: false,
+        message: `AFT config at ${invalid.path} has an invalid setting: ${invalid.message}`
+      };
+    }
+    return {
+      ok: true,
+      config,
+      sources: [...getConfigLoadSources()],
+      projectText: projectTextOf(directory),
+      texts: Object.fromEntries(getConfigLoadTexts())
+    };
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+}
+function startPiLiveConfigReload(options) {
+  const { userConfigPath, projectConfigPath } = resolveCortexKitConfigPaths(options.directory);
+  return startLiveConfigReload({
+    paths: [userConfigPath, projectConfigPath],
+    load: () => loadPiConfigForLiveReload(options.directory),
+    initialSources: options.initialSources,
+    initialProjectText: options.initialSourceTexts?.[projectConfigPath] ?? null,
+    initialTexts: options.initialSourceTexts,
+    securityKeys: aftLiveSecurityKeys(PI_LIVE_CONFIG_KEYS),
+    keys: PI_LIVE_CONFIG_KEYS,
+    getConfig: options.getConfig,
+    setConfig: options.setConfig,
+    log: (message) => log2(`${message} (${options.directory})`),
+    reportError: (message) => {
+      error2(message);
+      options.notify(message);
+    },
+    watch: options.watch
+  });
+}
+
 // src/shutdown-hooks.ts
 var GLOBAL_KEY = "__aftPiShutdownHooks__";
 function getState() {
@@ -32414,7 +33326,10 @@ function registerShutdownCleanup(fn) {
 
 // src/workflow-hints.ts
 var HEADING = "## IMPORTANT NOTICE about your tools";
-var HASHLINE_TAG_SOURCE_HINT = "**Hashline edit tags**: Only `read` (and accepted AFT `cat`/`head`/`tail` rewrites) mint hashline tags. `aft_zoom`, `aft_outline`, `grep`, `aft_search`, and conflict snippets do not. After navigation, call `read` on every file and range the patch addresses.";
+function hashlineTagSourceHint(bashRewritesMintTags, isRegistered = () => true) {
+  return `**Hashline edit tags**: ${hashlineTagSourceSentence(bashRewritesMintTags, isRegistered)}`;
+}
+var HASHLINE_TAG_SOURCE_HINT = hashlineTagSourceHint(true);
 function buildWorkflowHints(opts) {
   const sections = [];
   const grepName = "grep";
@@ -32429,6 +33344,8 @@ function buildWorkflowHints(opts) {
   const hasInspect = !opts.absentTools.has("aft_inspect");
   const hasBash = !opts.absentTools.has(bashName);
   const hasBgBash = opts.bashBackgroundEnabled && hasBash && !opts.absentTools.has("bash_status");
+  const hasWatch = !opts.absentTools.has("bash_watch");
+  const hasWrite = !opts.absentTools.has("bash_write");
   if (hasBash && opts.bashCompressionEnabled) {
     sections.push([
       "**Test/build output**: bash output is auto-compressed for non-piped commands. Piped commands run verbatim and show the pipeline's output. For AFT's test/build summary, run the runner without filters:",
@@ -32470,17 +33387,19 @@ function buildWorkflowHints(opts) {
     ].join(`
 `));
   }
-  if (hasBgBash) {
+  if (hasBgBash && hasWatch) {
     sections.push([
       `**Long-running commands** (builds, installs, full test suites): run them in the FOREGROUND — use \`${bashName}({ command, wait: true })\` when you know it is long and need the result before anything else; if you send a new message, the wait detaches to background; otherwise omit \`wait\` so auto-promote can hand you a reminder while you work.`,
       "- `background: true` is ONLY for when you have OTHER useful work to do while it runs: start it, do the other work, and the completion reminder delivers the result (or spawn a subagent for the side work). Do NOT background a command and then immediately `bash_watch` it — that spends a whole extra turn waiting for something foreground returns in one.",
       "- `bash_watch` is for blocking on an ALREADY-backgrounded task once you've run out of parallel work (sync — the user can interrupt), or reacting to a specific early output line (async: background:true + pattern). Never loop `bash_status` to wait — it's a one-shot inspector."
     ].join(`
 `));
+  }
+  if (hasBgBash && hasWrite) {
     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 (opts.hashlineEffective === true) {
-    sections.push(HASHLINE_TAG_SOURCE_HINT);
+    sections.push(hashlineTagSourceHint(hasBash && opts.bashRewriteEnabled !== false, (name) => !opts.absentTools.has(name)));
   }
   if (sections.length === 0) {
     return null;
@@ -32495,14 +33414,18 @@ ${sections.join(`
 `)}`;
 }
 function buildHintsFromConfig(config, absentTools, hashlineEffective = false) {
+  const bashCfg = resolveBashConfig(config);
   return buildWorkflowHints({
-    bashBackgroundEnabled: resolveBashConfig(config).background,
-    bashCompressionEnabled: resolveBashConfig(config).compress,
+    bashBackgroundEnabled: bashCfg.background,
+    bashCompressionEnabled: bashCfg.compress,
+    bashRewriteEnabled: bashCfg.rewrite,
     absentTools,
     hashlineEffective
   });
 }
 function registerWorkflowHints(pi, config, surface) {
+  if (skipsEagerStartup())
+    return;
   const absent = new Set;
   if (!surface.outline)
     absent.add("aft_outline");
@@ -32522,6 +33445,10 @@ function registerWorkflowHints(pi, config, surface) {
     absent.add("bash");
   if (!surface.bashStatus)
     absent.add("bash_status");
+  if (!surface.bashWatch)
+    absent.add("bash_watch");
+  if (!surface.bashWrite)
+    absent.add("bash_write");
   const hintsBlock = buildHintsFromConfig(config, absent, piHashlineEffective(config, surface));
   if (!hintsBlock)
     return;
@@ -32956,6 +33883,16 @@ ${lines}
     hashlineEffective: hashlineEditRegistered,
     storageDir
   };
+  const liveConfigReload = startPiLiveConfigReload({
+    directory: projectRoot,
+    initialSources: bootstrap.sources ?? [],
+    initialSourceTexts: bootstrap.sourceTexts,
+    getConfig: () => ctx.config,
+    setConfig: (next) => {
+      ctx.config = next;
+    },
+    notify: (message) => deliverConfigMigrationWarnings([message])
+  });
   if (onnxRuntimePromise) {
     onnxRuntimePromise.then((ortDylibDir) => {
       if (ortDylibDir) {
@@ -33062,6 +33999,7 @@ Retry with: npx @cortexkit/aft doctor --fix`
   });
   const unregisterShutdownCleanup = registerShutdownCleanup(async () => {
     hostShutdownStarted = true;
+    liveConfigReload.stop();
     try {
       await Promise.allSettled([abortInFlightAutoInstalls(), abortInFlightGithubInstalls()]);
       await pool.shutdown();
@@ -33072,6 +34010,7 @@ Retry with: npx @cortexkit/aft doctor --fix`
   });
   pi.on("session_shutdown", async () => {
     hostShutdownStarted = true;
+    liveConfigReload.stop();
     try {
       await Promise.allSettled([abortInFlightAutoInstalls(), abortInFlightGithubInstalls()]);
       await pool.shutdown();