@cortexkit/aft-pi 0.58.1 → 0.58.2

package/dist/index.js

@@ -7935,32 +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));
-}
-function monotonicNowMs() {
-  return performance.now();
-}
 // ../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 formatWatchWaited(elapsedMs, limitMs, capMs) {
-  const limit = limitMs >= capMs ? `limit ${limitMs}ms, the bash.watch_sync_max_ms cap` : `limit ${limitMs}ms`;
+  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, capMs, timeoutParam = "timeoutMs") {
+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.`;
@@ -8819,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;
@@ -9237,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) {
@@ -9308,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];
@@ -10091,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)
@@ -10100,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;
 }
@@ -10139,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") {
@@ -10352,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";
@@ -13656,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";
 }
@@ -14158,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);
   }
@@ -14168,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;
@@ -14205,6 +14303,7 @@ class SubcTransportPool {
   lifecycleRegistration = null;
   outerFacadeEvictor;
   client = null;
+  hadWorkingClient = false;
   connecting = null;
   routeReopenRetryDelayMs = RECONNECT_RETRY_FLOOR_MS;
   routeReopenRetry = null;
@@ -14649,6 +14748,10 @@ class SubcTransportPool {
   }
   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()) {
@@ -14664,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);
@@ -14699,12 +14844,8 @@ class SubcTransportPool {
           throw error;
         }
       };
-      const callDeadlineMs = timeoutMs ?? SUBC_DEFAULT_REQUEST_TIMEOUT_MS;
       const reloadWaitBudgetMs = Math.min(callDeadlineMs, ROUTE_OPEN_RELOAD_WAIT_CEILING_MS);
-      let scheduledDelayMs = 0;
       let lastRefusal;
-      const spentMs = () => Math.max(performance.now() - callStartedAt, scheduledDelayMs);
-      const remainingMs = () => callDeadlineMs - spentMs();
       const openRouteWithinDeadline = async () => {
         const remaining = remainingMs();
         if (remaining <= 0)
@@ -14907,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;
@@ -17903,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"
     }
   }
 };
@@ -18414,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 });
@@ -18756,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'`));
@@ -20342,7 +20496,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.58.1",
+  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",
@@ -20365,18 +20519,18 @@ var package_default = {
     "test:unit": "bun test src/__tests__ --path-ignore-patterns 'src/__tests__/e2e/**'"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.58.1",
+    "@cortexkit/aft-bridge": "0.58.2",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
     zod: "^4.4.3"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.58.1",
-    "@cortexkit/aft-darwin-x64": "0.58.1",
-    "@cortexkit/aft-linux-arm64": "0.58.1",
-    "@cortexkit/aft-linux-x64": "0.58.1",
-    "@cortexkit/aft-win32-arm64": "0.58.1",
-    "@cortexkit/aft-win32-x64": "0.58.1"
+    "@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",
@@ -20656,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
 }));
@@ -20741,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,
@@ -20768,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;
@@ -25985,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(),
@@ -26060,6 +26240,7 @@ var AftConfigFieldsSchema = object({
   search: SearchConfigSchema.optional(),
   bridge: BridgeConfigSchema.optional(),
   subc: SubcConfigSchema.optional(),
+  opencode: OpenCodeHostConfigSchema.optional(),
   github: GithubConfigSchema.optional(),
   gh_shim: GhShimConfigSchema.optional(),
   git: GitConfigSchema.optional()
@@ -26552,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)
@@ -27159,7 +27342,8 @@ var NPM_LSP_TABLE = [
     npm: "typescript",
     binary: "tsserver",
     extensions: ["ts", "tsx", "js", "jsx", "mjs", "cjs", "mts", "cts"],
-    rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"]
+    rootMarkers: ["tsconfig.json", "jsconfig.json", "package.json"],
+    supportedMajor: 5
   },
   {
     id: "python",
@@ -27233,6 +27417,15 @@ 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 readFileSync12 } from "node:fs";
@@ -27329,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;
@@ -27343,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);
@@ -27351,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 {
@@ -27367,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;
@@ -27418,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,
@@ -27557,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 };
     }
@@ -27686,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 = [];
@@ -27698,7 +27910,7 @@ 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) || spec.id === "typescript-sdk" && config.disabled.has("typescript")) {
@@ -27737,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) {
@@ -28868,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";
 
@@ -29322,7 +29551,9 @@ 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" })),
@@ -29346,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:",
@@ -29361,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,
@@ -29578,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.",
@@ -29636,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);
@@ -30165,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)`);
   }
 }
@@ -30208,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;
 }
@@ -30222,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."
   }))
@@ -30249,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({
@@ -30390,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,
@@ -30410,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);
@@ -30426,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) {
@@ -30442,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
@@ -30476,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);
@@ -30487,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") {
@@ -30545,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));
   }
@@ -30565,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) {
@@ -30583,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);
@@ -30623,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), data.waited.elapsed_ms);
+        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 });
@@ -30634,10 +30945,11 @@ A notification will fire when the pattern matches or the task exits.`, watchDeta
     }
   };
 }
-async function convertToAsyncWatchOnAbort(bridge, extCtx, taskId, waitFor, once, elapsedMs) {
+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 interrupted + `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,
@@ -30653,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 interrupted + `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 interrupted + `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 interrupted + `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) {
@@ -30729,10 +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 = monotonicNowMs();
-  const deadline = startedAt + effectiveWaitMs;
-  const elapsedMs = () => Math.round(monotonicNowMs() - startedAt);
+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 },
@@ -30751,31 +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: elapsedMs(),
-            limit_ms: effectiveWaitMs
-          });
+          return withWaited(lastData ?? unavailableSnapshot(), waited("user_message"));
         }
-        if (monotonicNowMs() >= deadline) {
-          return withWaited(lastData ?? unavailableSnapshot(), {
-            reason: "unavailable",
-            elapsed_ms: elapsedMs(),
-            limit_ms: effectiveWaitMs
-          });
+        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 - monotonicNowMs())));
+        await pause();
         continue;
       }
+      busySince = undefined;
       lastData = data;
       const terminal = isTerminalStatus(data.status);
       if (waitFor) {
@@ -30800,14 +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: elapsedMs(),
-                limit_ms: effectiveWaitMs,
+              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);
@@ -30823,27 +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: elapsedMs(),
-          limit_ms: effectiveWaitMs
-        });
+        return withWaited(data, waited("exited"));
       }
       if (isSyncWatchAborted(sessionId)) {
-        return withWaited(data, {
-          reason: "user_message",
-          elapsed_ms: elapsedMs(),
-          limit_ms: effectiveWaitMs
-        });
+        return withWaited(data, waited("user_message"));
       }
-      if (monotonicNowMs() >= deadline) {
-        return withWaited(data, {
-          reason: "timeout",
-          elapsed_ms: elapsedMs(),
-          limit_ms: effectiveWaitMs
-        });
+      if (watchClock.now() >= deadline) {
+        return withWaited(data, waited("timeout"));
       }
-      await sleep(Math.min(BASH_WAIT_POLL_INTERVAL_MS, Math.max(0, deadline - monotonicNowMs())));
+      await pause();
     }
   } finally {
     if (waitForExit && !sawTerminal)
@@ -30950,16 +31252,19 @@ function withWaited(data, waited) {
   return { ...data, waited };
 }
 function formatWaitSummary(waited, details, watchRole) {
-  const waitedText = formatWatchWaited(waited.elapsed_ms, waited.limit_ms, watchRole.capMs);
+  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 `${waitedText}; matched ${JSON.stringify(waited.match ?? "")}${stream} at offset ${waited.match_offset ?? 0}.`;
   }
   if (waited.reason === "timeout") {
-    return `${waitedText}; 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 `${waitedText}; 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 `${waitedText}; task exited (${details.status}${exit}).`;
@@ -30981,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;
@@ -31928,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."
@@ -31952,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({
@@ -32106,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;
@@ -32117,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)
@@ -32184,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)
@@ -32250,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);
@@ -32289,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(), {
@@ -32722,6 +33030,8 @@ function withLiveRestriction(surface, ctx) {
 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"),
@@ -32743,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");
@@ -33016,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";
@@ -33031,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:",
@@ -33072,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;
@@ -33097,9 +33414,11 @@ ${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
   });
@@ -33126,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;