@cortexkit/aft-pi 0.61.0 → 0.62.0

package/dist/index.js

@@ -8783,7 +8783,7 @@ function resolvePluginLogPath(context = {}) {
 var BASH_HOST_FALLBACK_BANNER = "[AFT host fallback - module transport down; no rewrites/compression/background]";
 var BASH_HOST_FALLBACK_MAX_OUTPUT_BYTES = 100 * 1024;
 var BASH_HOST_FALLBACK_MAX_TIMEOUT_MS = 10 * 60 * 1000;
-var BASH_HOST_FALLBACK_REFUSAL = "AFT transport is down; only foreground execution is available in host fallback";
+var BASH_HOST_FALLBACK_REFUSAL = "AFT module connection is down";
 var BASH_RUNON_DESCRIPTION = 'Run on a remote build server: `linux` (2 vCPUs), or `linux,Nc` for N vCPUs such as `linux,8c`; add ",net" for outbound internet (offline by default). `windows` runs the command in Git Bash on a Windows build machine (no vCPU or network options).';
 var BASH_RUNON_GUIDANCE = 'When remote runs are available, put `runon: "linux"` on build and test lines (cargo, bun test), including chains and pipes. Keep git, gh, interactive and file-editing commands local, and keep a line local if it needs macOS (Seatbelt, codesign, launchd, TCC, AppKit) or runs binaries built on this machine: a remote build leaves no binaries or target/ output in the local worktree. Add `,Nc` to request N vCPUs (`linux,4c`); without it the job gets 2 vCPUs. The job sees exactly the CPUs it gets, so ask for what the command uses: 2c (the default) for a single test binary or script, 4c for `cargo check`/clippy on one crate, 8c for a workspace test suite, and 16c for a large release build.';
 function pathKeyForPlatform(env, platform) {
@@ -10877,7 +10877,7 @@ function isEmptyParam(value) {
   return false;
 }
 function coerceJsonCollectionParam(value, field) {
-  const shape = field === "targets" ? "an array of {path, symbol}" : "a string or array of strings";
+  const shape = field !== "sections" ? "an array of {target, symbols}" : "a string or array of strings";
   if (typeof value === "string") {
     const trimmed = value.trim();
     if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
@@ -10886,13 +10886,13 @@ function coerceJsonCollectionParam(value, field) {
       } catch {
         throw new Error(`${field} must be ${shape} (got a string that is not valid JSON)`);
       }
-    } else if (field === "targets") {
+    } else if (field !== "sections") {
       throw new Error(`${field} must be ${shape} (got a string that is not valid JSON)`);
     }
   }
   if (value === undefined || value === null)
     return value;
-  if (field === "targets") {
+  if (field !== "sections") {
     if (Array.isArray(value) || typeof value === "object")
       return value;
   } else if (typeof value === "string" || Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
@@ -10915,7 +10915,7 @@ function usableZoomTargets(targets) {
     if (typeof entry !== "object")
       return true;
     const record = entry;
-    return !(isBlankParam(record.path) && isBlankParam(record.filePath) && isBlankParam(record.symbol));
+    return !(isBlankParam(record.target) && isBlankParam(record.url) && isBlankParam(record.symbols) && isBlankParam(record.path) && isBlankParam(record.filePath) && isBlankParam(record.symbol));
   });
 }
 function isFindReplaceOnlyEdit(args) {
@@ -11090,6 +11090,7 @@ function aftLiveConfigKeys(resolveBash) {
   return [
     pathKey("configure_warnings_delivery"),
     pathKey("restrict_to_project_root"),
+    pathKey("revision_reads"),
     pathKey("inspect.diagnostics_timeout_ms"),
     pathKey("inspect.tier2_idle_minutes"),
     pathKey("lsp.idle_minutes"),
@@ -11107,7 +11108,8 @@ function aftLiveConfigKeys(resolveBash) {
     bashKey("runon_enabled", resolveBash),
     bashKey("subagent_background", resolveBash),
     bashKey("watch_sync_max_ms", resolveBash),
-    bashKey("worker_wait_max_ms", resolveBash)
+    bashKey("worker_wait_max_ms", resolveBash),
+    bashKey("env", resolveBash)
   ];
 }
 function sameValue(a, b) {
@@ -15035,6 +15037,47 @@ function isSocketDeathError(error, depth = 0) {
   }
   return isConsumerReconnectTransient(error) || isSubcClientClosedError(error);
 }
+var REQUEST_CONNECTION_LOSS_CODES = new Set(["ECONNABORTED", "ECONNRESET", "EPIPE"]);
+function hasRequestConnectionLossCode(error) {
+  if (typeof error !== "object" || error === null || !("code" in error))
+    return false;
+  return typeof error.code === "string" && REQUEST_CONNECTION_LOSS_CODES.has(error.code);
+}
+function hasRequestConnectionLossEvidence(error, depth = 0) {
+  if (error instanceof SocketClosedError)
+    return true;
+  if (error instanceof SubcError && error.closeReason === "connection_lost")
+    return true;
+  if (hasRequestConnectionLossCode(error))
+    return true;
+  if (!(error instanceof SubcCallError) || error.kind !== "outcome_unknown" || depth >= 4 || error.cause === undefined || error.cause === error) {
+    return false;
+  }
+  return hasRequestConnectionLossEvidence(error.cause, depth + 1);
+}
+function connectionClosedAfterDispatch(error) {
+  if (error instanceof SubcCallError && error.kind === "not_sent")
+    return error;
+  if (typeof error === "object" && error !== null && "kind" in error && error.kind === "not_sent") {
+    return error;
+  }
+  if (!hasRequestConnectionLossEvidence(error))
+    return error;
+  if (error instanceof SubcCallError)
+    return error;
+  if (!(error instanceof Error))
+    return error;
+  return Object.assign(error, { kind: "outcome_unknown" });
+}
+var dispatchedRequestDeadlines = new WeakSet;
+function noteDispatchedRequestDeadline(error) {
+  if (error instanceof SubcError && error.code === REQUEST_DEADLINE_CODE) {
+    dispatchedRequestDeadlines.add(error);
+  }
+}
+function isDispatchedRequestDeadlineError(error) {
+  return typeof error === "object" && error !== null && dispatchedRequestDeadlines.has(error);
+}
 function isUnansweredCallError(error) {
   if (isSocketDeathError(error))
     return false;
@@ -15641,7 +15684,24 @@ class SubcTransport {
       return {};
     const preview = options.preview;
     const timeoutMs = options.transportTimeoutMs ?? options.timeoutMs;
-    const onProgress = options.onProgress;
+    const callback = options.onProgress;
+    const onProgress = callback ? (body) => {
+      let frame;
+      try {
+        frame = JSON.parse(new TextDecoder().decode(body));
+      } catch {
+        return;
+      }
+      if (typeof frame !== "object" || frame === null)
+        return;
+      const progress = frame;
+      if (progress.type !== "progress" || typeof progress.chunk !== "string")
+        return;
+      callback({
+        kind: progress.kind === "stderr" ? "stderr" : "stdout",
+        text: progress.chunk
+      });
+    } : undefined;
     return { preview, timeoutMs, onProgress, abortSignal: options.abortSignal };
   }
 }
@@ -15653,7 +15713,7 @@ class SubcTransportPool {
   consumerIdentity;
   hostScopes;
   hostScopeCache = new Map;
-  hostScopeRefusals = new Set;
+  hostScopeRefusals = new Map;
   hostScopeOutcomes = new Map;
   connectFn;
   onBgEventsNudge;
@@ -16540,7 +16600,7 @@ class SubcTransportPool {
             this.resetRouteReopenBackoff();
           return reply;
         } catch (requestError) {
-          const error = frameReadTimeoutError(routeClosedMidCallError(requestError, routeAndEntry.entry, record));
+          const error = frameReadTimeoutError(routeClosedMidCallError(connectionClosedAfterDispatch(requestError), routeAndEntry.entry, record));
           if (this.isReapInduced(record))
             throw this.annotateReapError(error, record);
           const ownsRoute = this.isCurrentSession(key, record) && this.client === client;
@@ -16574,6 +16634,7 @@ class SubcTransportPool {
             continue;
           }
           handleRequestFailure(error, routeAndEntry.entry);
+          noteDispatchedRequestDeadline(error);
           throw error;
         }
       }
@@ -16707,20 +16768,38 @@ class SubcTransportPool {
     return { route: await opening, entry };
   }
   hostScope(client, identity) {
-    if (this.hostScopeRefusals.has(identity.session))
-      return Promise.resolve(undefined);
+    let lookupReason = "cache_miss";
+    const refused = this.hostScopeRefusals.get(identity.session);
+    if (refused) {
+      const previous = this.hostScopeCache.get(identity.session);
+      if (previous)
+        this.cancelHostScopeRetry(previous);
+      this.hostScopeCache.delete(identity.session);
+      this.hostScopeRefusals.delete(identity.session);
+      lookupReason = `previous_bind_refusal code=${refused}`;
+    }
     let state = this.hostScopeCache.get(identity.session);
     if (!state) {
       state = { retryAt: 0, retryMs: HOST_SCOPE_RETRY_FLOOR_MS };
       this.hostScopeCache.set(identity.session, state);
     }
     if (state.answer) {
-      return Promise.resolve(state.answer.result === "scope" && !state.scopeBindPending ? state.answer.scope : undefined);
+      const reason = state.scopeBindPending ? "scope_sync_pending" : `cached_${state.answer.result}`;
+      log(`subc head scope: session=${identity.session} lookup=skipped reason=${reason}`);
+      return Promise.resolve({
+        scope: state.answer.result === "scope" && !state.scopeBindPending ? state.answer.scope : undefined,
+        reason
+      });
     }
-    if (state.pending)
+    if (state.pending) {
+      log(`subc head scope: session=${identity.session} lookup=skipped reason=inflight_lookup`);
       return state.pending;
-    if (Date.now() < state.retryAt)
-      return Promise.resolve(undefined);
+    }
+    if (Date.now() < state.retryAt) {
+      log(`subc head scope: session=${identity.session} lookup=skipped reason=backoff retry_in=${state.retryAt - Date.now()}ms`);
+      return Promise.resolve({ reason: state.unscopedReason ?? "lookup_backoff" });
+    }
+    log(`subc head scope: session=${identity.session} lookup=started reason=${lookupReason}`);
     const current = state;
     clearTimeout(current.retryTimer);
     current.retryTimer = undefined;
@@ -16728,24 +16807,32 @@ class SubcTransportPool {
     current.lookupAbort = abort;
     const lookup = this.readHostScope(client, identity, abort.signal).then((outcome) => {
       if (this.hostScopeCache.get(identity.session) !== current)
-        return;
+        return { reason: "lookup_invalidated" };
       current.pending = undefined;
       current.lookupAbort = undefined;
       if (abort.signal.aborted)
-        return;
+        return { reason: "lookup_cancelled" };
       this.logHostScopeOutcome(identity.session, outcome);
+      const reason = outcome.result === "error" ? `lookup_error code=${outcome.code}` : `lookup_${outcome.result}`;
       if (outcome.result === "scope" || outcome.result === "no_scope") {
         current.answer = outcome;
         current.retryAt = 0;
         current.retryMs = HOST_SCOPE_RETRY_FLOOR_MS;
-        if (outcome.result === "scope")
-          this.promoteHostScope(identity.session);
+        if (outcome.result === "scope") {
+          current.promoteAfterBind = Boolean(refused);
+          if (!current.promoteAfterBind)
+            this.promoteHostScope(identity.session);
+        }
       } else {
+        current.unscopedReason = reason;
         current.retryAt = Date.now() + current.retryMs;
         current.retryMs = Math.min(current.retryMs * 2, HOST_SCOPE_RETRY_CAP_MS);
         this.scheduleHostScopeRetry(identity.session, current);
       }
-      return outcome.result === "scope" ? outcome.scope : undefined;
+      return {
+        scope: outcome.result === "scope" ? outcome.scope : undefined,
+        reason
+      };
     });
     current.pending = lookup;
     return lookup;
@@ -16792,7 +16879,7 @@ class SubcTransportPool {
         retry = this.hostScope(client, record.identity);
       }
       retry.catch((error) => {
-        warn(`subc head scope: background retry failed code=${error instanceof Error ? error.name : "Error"}`);
+        warn(`subc head scope: session=${session} background retry failed code=${error instanceof Error ? error.name : "Error"}`);
       });
     }, Math.max(0, state.retryAt - Date.now()));
     state.retryTimer.unref();
@@ -16808,8 +16895,8 @@ class SubcTransportPool {
   }
   refuseHostScopeBind(session, state, code) {
     if (!this.hostScopeRefusals.has(session)) {
-      this.hostScopeRefusals.add(session);
-      warn(`subc head scope: session=${session} scoped bind refused code=${code}; binding unscoped; retry stopped`);
+      this.hostScopeRefusals.set(session, code);
+      warn(`subc head scope: session=${session} scoped bind refused code=${code}; retry stopped until next bind lookup`);
     }
     if (state) {
       state.scopeBindPending = false;
@@ -16818,11 +16905,12 @@ class SubcTransportPool {
   }
   async retryHostScopeBind(client, identity, state, scope) {
     try {
-      const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, { consumerIdentity: this.consumerIdentity, scope });
+      const route = await this.bindHostToolRoute(client, identity, "scope_probe", "scope_sync_retry", scope);
       safeCloseRoute(client, route);
       if (this.hostScopeCache.get(identity.session) !== state || !state.scopeBindPending || this.shuttingDown || client !== this.client || !this.unscopedHostRecord(identity.session))
         return;
       state.scopeBindPending = false;
+      state.promoteAfterBind = false;
       state.retryAt = 0;
       state.retryMs = HOST_SCOPE_RETRY_FLOOR_MS;
       log(`subc head scope: session=${identity.session} scoped bind recovered ref=${scope.ref.slice(0, 8)} epoch=${scope.scopeEpoch}`);
@@ -16948,24 +17036,39 @@ class SubcTransportPool {
       signal.removeEventListener("abort", cancel);
     }
   }
-  openHostToolRoute(client, identity, record, entry) {
+  openHostToolRoute(client, identity, record, entry, channel = "tool") {
     if (!this.hostScopes || !["opencode", "pi"].includes(identity.harness) || identity.session === DEFAULT_SESSION_ID) {
-      return client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
-        consumerIdentity: this.consumerIdentity
-      });
+      const reason = !this.hostScopes ? "host_scopes_disabled" : identity.session === DEFAULT_SESSION_ID ? "default_session" : "unsupported_harness";
+      log(`subc head scope: session=${identity.session} lookup=skipped reason=${reason}`);
+      return this.bindHostToolRoute(client, identity, channel, reason);
     }
-    return this.openScopedHostToolRoute(client, identity, record, entry);
+    return this.openScopedHostToolRoute(client, identity, record, entry, channel);
   }
-  async openScopedHostToolRoute(client, identity, record, entry) {
-    const scope = await this.hostScope(client, identity);
+  bindHostToolRoute(client, identity, channel, reason, scope) {
+    log(`subc head scope: session=${identity.session} bind=${scope ? "scoped" : "unscoped"} channel=${channel} root=${identity.project_root} reason=${reason}` + (scope ? ` ref=${scope.ref.slice(0, 8)} epoch=${scope.scopeEpoch}` : ""));
+    return client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
+      consumerIdentity: this.consumerIdentity,
+      ...scope ? { scope } : {}
+    });
+  }
+  async openScopedHostToolRoute(client, identity, record, entry, channel = "tool") {
+    const decision = await this.hostScope(client, identity);
+    const scope = decision.scope;
+    let reason = decision.reason;
     this.assertRecordLive(record);
     if (scope) {
       try {
-        const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, { consumerIdentity: this.consumerIdentity, scope });
+        const route = await this.bindHostToolRoute(client, identity, channel, reason, scope);
         if (entry)
           entry.hostScope = scope;
+        const state = this.hostScopeCache.get(identity.session);
+        if (state?.promoteAfterBind && state.answer?.result === "scope" && state.answer.scope === scope) {
+          state.promoteAfterBind = false;
+          this.promoteHostScope(identity.session);
+        }
         return route;
       } catch (error) {
+        log(`subc head scope: session=${identity.session} bind=failed channel=${channel} reason=scoped_open_error code=${error instanceof SubcError ? error.code ?? error.name : "Error"}`);
         if (!(error instanceof SubcError) || !error.code || isSocketDeathError(error))
           throw error;
         if (isRouteOpenReloadWindowError(error))
@@ -16974,18 +17077,21 @@ class SubcTransportPool {
         const state = this.hostScopeCache.get(identity.session);
         if (state && isHostScopeSyncRefusal(error.code)) {
           this.deferHostScopeBind(identity.session, state, error.code);
+          reason = `scope_sync_pending code=${error.code}`;
         } else {
           this.refuseHostScopeBind(identity.session, state, error.code);
+          if (decision.reason === "cached_scope") {
+            return this.openScopedHostToolRoute(client, identity, record, entry, channel);
+          }
+          reason = `scoped_bind_refused code=${error.code}`;
         }
       }
     }
     this.assertRecordLive(record);
-    const route = await client.routeOpen({ kind: "tool_provider", module_id: AFT_MODULE_ID }, identity, {
-      consumerIdentity: this.consumerIdentity
-    });
+    const route = await this.bindHostToolRoute(client, identity, channel, reason);
     if (this.hostScopeCache.get(identity.session)?.answer?.result === "scope" && !this.hostScopeCache.get(identity.session)?.scopeBindPending && !this.hostScopeRefusals.has(identity.session)) {
       safeCloseRoute(client, route);
-      return this.openScopedHostToolRoute(client, identity, record, entry);
+      return this.openScopedHostToolRoute(client, identity, record, entry, channel);
     }
     return route;
   }
@@ -17082,7 +17188,7 @@ class SubcTransportPool {
     };
     sub = new BgSubscription(identity, () => this.ensureClient(), (client, cause) => this.dropClient(client, cause), (client) => {
       binding.hostScope = undefined;
-      return this.openHostToolRoute(client, identity, record, binding);
+      return this.openHostToolRoute(client, identity, record, binding, "bg_events");
     }, onNudge, this.bgBackoffSleep, () => this.rootCanAttach(record.canonicalRoot), (error) => {
       if (!isAbsentRootRouteError(error))
         return false;
@@ -17375,11 +17481,54 @@ function shellTimeoutDisposition(outcome) {
 var SUBC_MODULE_RESTART_DISPOSITION = "The AFT daemon module restarted while this call was in flight, so its outcome is UNKNOWN: it may or may not have executed. Verify actual state before re-running, and never blind-retry a mutation.";
 var BRIDGE_TRANSPORT_UNKNOWN_OUTCOME_DISPOSITION = "The standalone AFT transport failed after this call may have been sent, so its outcome is UNKNOWN: it may or may not have executed. Verify actual state before re-running, and never blind-retry a mutation.";
 var SUBC_ROUTE_CLOSED_MID_CALL_DISPOSITION = "The plugin closed this call's route while the call was in flight, so its outcome is UNKNOWN: it may or may not have executed. Verify actual state before re-running, and never blind-retry a mutation.";
+var SUBC_CONNECTION_CLOSED_MID_CALL_DISPOSITION = "The AFT module connection closed while this request was in flight, so its outcome is UNKNOWN: it may or may not have executed. Verify actual state before retrying, and never blindly retry a mutation.";
+function bashConnectionClosedDisposition(taskId) {
+  const taskFollowup = taskId ? `Use bash_status or bash_watch with task ID ${taskId} to check it.` : "If a task ID is available, use it with bash_status or bash_watch; otherwise wait for the completion notice.";
+  return `The command may have run or may still be running. AFT keeps commands running when the connection drops; a completion notice will follow if it ran. ${taskFollowup} Do not rerun it.`;
+}
+
+class AftModuleUnavailableError extends SubcCallError {
+  constructor(message, cause) {
+    super("not_sent", message, "aft_module_unavailable", cause);
+    this.name = "AftModuleUnavailableError";
+  }
+}
+function refuseAftModuleOptionWithoutFallback(error, option, refusalPrefix) {
+  return new AftModuleUnavailableError(`${refusalPrefix}; ${option} has no host fallback. Nothing was started, so it is safe to retry after the AFT module connection is restored.`, error);
+}
 var BASH_FRAME_READ_TIMEOUT_DISPOSITION = "The command's state is UNKNOWN: the transport timed out while reading the response frame, so it may or may not have executed. Check bash_status if a task ID could have been assigned, and do not re-run side-effecting commands blindly.";
 var SUBC_FRAME_READ_TIMEOUT_DISPOSITION = "The transport timed out while reading the response frame for this call, so its outcome is UNKNOWN: it may or may not have executed. Verify actual state before re-running, and never blind-retry a mutation.";
 function isRouteClosedMidCallError(error) {
   return error instanceof SubcRouteClosedMidCallError || isLocalRouteCloseRejection(error);
 }
+function isSubcConnectionClosedMidCallError(error) {
+  if (!(error instanceof Error))
+    return false;
+  const fields = error;
+  if (fields.kind !== "outcome_unknown")
+    return false;
+  if (error instanceof SocketClosedError)
+    return true;
+  if (error instanceof SubcError)
+    return error.closeReason === "connection_lost";
+  if (error instanceof SubcCallError) {
+    return error.closeReason === "connection_lost" || hasConnectionLossCause(error);
+  }
+  return hasConnectionLossCause(error);
+}
+var CONNECTION_LOSS_ERROR_CODES = new Set(["ECONNABORTED", "ECONNRESET", "EPIPE"]);
+function hasConnectionLossCause(error, depth = 0) {
+  if (error instanceof SocketClosedError)
+    return true;
+  if (error instanceof SubcError && error.closeReason === "connection_lost")
+    return true;
+  if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && CONNECTION_LOSS_ERROR_CODES.has(error.code)) {
+    return true;
+  }
+  if (!(error instanceof Error) || depth >= 4 || error.cause === undefined)
+    return false;
+  return hasConnectionLossCause(error.cause, depth + 1);
+}
 function isRouteGoodbyeError(error) {
   if (!(error instanceof SubcError))
     return false;
@@ -17434,6 +17583,8 @@ function classifyBashHostFallbackError(error) {
   if (!(error instanceof Error) || hasEngineResponse(error) || isRouteGoodbyeError(error)) {
     return;
   }
+  if (isSubcConnectionClosedMidCallError(error))
+    return;
   if (error instanceof BridgeTransportUnknownOutcomeError)
     return;
   if (isRouteClosedMidCallError(error))
@@ -17460,6 +17611,8 @@ function isBashTransportDeadError(error) {
 function adaptToolError(command, error) {
   if (!(error instanceof Error))
     return error;
+  if (error instanceof AftModuleUnavailableError)
+    return error;
   if (isSubcFrameReadTimeoutError(error)) {
     const typedError = error instanceof SubcFrameReadTimeoutError ? error : new SubcFrameReadTimeoutError(error);
     const disposition = command === "bash" ? BASH_FRAME_READ_TIMEOUT_DISPOSITION : SUBC_FRAME_READ_TIMEOUT_DISPOSITION;
@@ -17474,6 +17627,13 @@ function adaptToolError(command, error) {
     error.message = error.message ? `${error.message} ${BRIDGE_TRANSPORT_UNKNOWN_OUTCOME_DISPOSITION}` : BRIDGE_TRANSPORT_UNKNOWN_OUTCOME_DISPOSITION;
     return error;
   }
+  if (isSubcConnectionClosedMidCallError(error)) {
+    const disposition = command === "bash" ? bashConnectionClosedDisposition(taskIdFromError(error)) : SUBC_CONNECTION_CLOSED_MID_CALL_DISPOSITION;
+    if (error.message.includes(disposition))
+      return error;
+    error.message = error.message ? `${error.message} ${disposition}` : disposition;
+    return error;
+  }
   if (isRouteGoodbyeError(error)) {
     if (error.message.includes(SUBC_MODULE_RESTART_DISPOSITION))
       return error;
@@ -17486,6 +17646,13 @@ function adaptToolError(command, error) {
     error.message = error.message ? `${error.message} ${SUBC_ROUTE_CLOSED_MID_CALL_DISPOSITION}` : SUBC_ROUTE_CLOSED_MID_CALL_DISPOSITION;
     return error;
   }
+  if (command === "bash" && isDispatchedRequestDeadlineError(error)) {
+    const disposition = bashConnectionClosedDisposition(taskIdFromError(error));
+    if (error.message.includes(disposition))
+      return error;
+    error.message = error.message ? `${error.message} ${disposition}` : disposition;
+    return error;
+  }
   if ((command === "bash" || command === "powershell") && isBridgeTransportTimeout(error)) {
     const outcome = error.shellOutcome;
     const disposition = shellTimeoutDisposition(outcome);
@@ -17494,6 +17661,9 @@ function adaptToolError(command, error) {
     error.message = error.message ? `${error.message} ${disposition}` : disposition;
     return error;
   }
+  if (command !== "bash" && isBashTransportDeadError(error)) {
+    return new AftModuleUnavailableError("The AFT module connection is down or unavailable; this AFT-backed option has no host fallback. Nothing was started, so it is safe to retry after the connection is restored.", error);
+  }
   if (command !== "bash" || !isBashTransportDeadError(error))
     return error;
   if (error.message.includes(BASH_TRANSPORT_DISPOSITION))
@@ -17501,6 +17671,15 @@ function adaptToolError(command, error) {
   error.message = error.message ? `${error.message} ${BASH_TRANSPORT_DISPOSITION}` : BASH_TRANSPORT_DISPOSITION;
   return error;
 }
+function taskIdFromError(error) {
+  for (let current = error, depth = 0;current instanceof Error && depth < 5; current = current.cause, depth += 1) {
+    const fields = current;
+    const taskId = fields.taskId ?? fields.task_id;
+    if (typeof taskId === "string" && taskId.length > 0)
+      return taskId;
+  }
+  return;
+}
 // ../aft-bridge/dist/feature-config.js
 import { createHash as createHash3 } from "node:crypto";
 var CANONICAL_TOOLS = [
@@ -22521,39 +22700,70 @@ function validateOptionalCanonicalPath(record, property) {
   }
   pathValue(record, property);
 }
-function normalizeZoomTargets(record) {
-  if (!hasOwn(record, "targets"))
-    return;
-  const targets = record.targets;
-  const normalizeTarget = (target, index) => {
-    if (!target || typeof target !== "object" || Array.isArray(target)) {
-      throw new InvalidRequestError(`'targets[${index}].path' must be a non-empty string`);
-    }
-    const source = target;
-    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", false);
-    } catch (error) {
-      if (error instanceof InvalidRequestError) {
-        throw new InvalidRequestError(error.message.replace("'filePath'", `'targets[${index}].filePath'`).replace("'path'", `'targets[${index}].path'`));
-      }
-      throw error;
+function normalizeZoomLocation(record, prefix = "") {
+  let first;
+  for (const key of ["target", "path", "filePath", "url"]) {
+    const value = record[key];
+    if (value === undefined || value === null || typeof value === "string" && !value.trim()) {
+      delete record[key];
+      continue;
     }
-    return normalized;
-  };
-  if (Array.isArray(targets)) {
-    if (targets.length === 0)
-      return;
-    record.targets = targets.map(normalizeTarget);
-    return;
-  }
-  if (targets && typeof targets === "object") {
-    record.targets = normalizeTarget(targets, 0);
+    const location = pathValue(record, key);
+    if (first && first.value !== location) {
+      throw new InvalidRequestError(`Conflicting '${prefix}${first.key}' location '${first.value}' and '${prefix}${key}' '${location}': provide the same location or only one target`);
+    }
+    first ??= { key, value: location };
   }
+  for (const alias of ["path", "filePath", "url"])
+    delete record[alias];
+  if (first)
+    record.target = first.value;
+}
+function normalizeZoomTargets(record) {
+  const normalizeEntry = (value, prefix) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new InvalidRequestError(`'${prefix}target' must be a non-empty string`);
+    }
+    const entry = { ...value };
+    normalizeZoomLocation(entry, prefix);
+    if (hasOwn(entry, "symbol")) {
+      if (!isBlankParam(entry.symbols) && JSON.stringify(entry.symbols) !== JSON.stringify(entry.symbol)) {
+        throw new InvalidRequestError(`Conflicting '${prefix}symbols' and '${prefix}symbol': provide the same symbols or only one spelling`);
+      }
+      if (isBlankParam(entry.symbols))
+        entry.symbols = entry.symbol;
+      delete entry.symbol;
+    }
+    entry.target ??= "";
+    entry.symbols ??= "";
+    return entry;
+  };
+  const batch = [];
+  if (hasOwn(record, "batch")) {
+    const entries = coerceJsonCollectionParam(record.batch, "batch");
+    if (!Array.isArray(entries) || entries.length === 0) {
+      throw new InvalidRequestError("'batch' must be a non-empty array of {target, symbols}");
+    }
+    batch.push(...entries.map((entry, index) => normalizeEntry(entry, `batch[${index}].`)));
+  }
+  normalizeZoomLocation(record);
+  if (!isBlankParam(record.target) || !isBlankParam(record.symbols)) {
+    const entry = {};
+    if (record.target !== undefined)
+      entry.target = record.target;
+    if (record.symbols !== undefined)
+      entry.symbols = record.symbols;
+    batch.unshift(normalizeEntry(entry, ""));
+  }
+  if (hasOwn(record, "targets")) {
+    const targets = coerceJsonCollectionParam(record.targets, "targets");
+    batch.push(...usableZoomTargets(targets).map((entry, index) => normalizeEntry(entry, `targets[${index}].`)));
+  }
+  for (const key of ["target", "symbols", "targets"])
+    delete record[key];
+  if (!batch.length)
+    throw new InvalidRequestError("'batch' must be a non-empty array of {target, symbols}");
+  record.batch = batch;
 }
 function bareToolName(toolName) {
   const bare = toolName.startsWith("aft_") ? toolName.slice(4) : toolName;
@@ -22580,7 +22790,6 @@ function prepareCanonicalPathArguments(toolName, rawArguments) {
       normalizeAliasPair(record, "path", "filePath", true);
       break;
     case "zoom":
-      normalizeAliasPair(record, "path", "filePath", false);
       normalizeZoomTargets(record);
       break;
     case "callgraph":
@@ -23001,6 +23210,19 @@ function copyOwnProperties(source) {
     copy[key] = source[key];
   return copy;
 }
+// ../aft-bridge/dist/revision-reads.js
+var REVISION_REF_DESCRIPTION = "Git revision to read the file at instead of the working tree: a branch, tag, full or short commit SHA, or a form like HEAD~2. Content comes from git's object store; the working tree, index and HEAD are not touched.";
+var REVISION_REF_TOOL_NOTE = "Pass `ref` to read the file as it is at a git revision (branch, tag, SHA, HEAD~2); the reply's first line names the commit it resolved to.";
+function revisionReadsOffered(config) {
+  return config.revision_reads === true;
+}
+function revisionRefArg(value) {
+  if (value === undefined || value === null)
+    return;
+  if (typeof value === "string" && value.trim().length === 0)
+    return;
+  return value;
+}
 // ../aft-bridge/dist/semantic-status.js
 var MISSING_ONNX_RUNTIME_MARKER = "ONNX Runtime not found.";
 var MISSING_ONNX_RUNTIME_LABEL = "unavailable — ONNX Runtime missing (npx @cortexkit/aft doctor --fix)";
@@ -24142,7 +24364,7 @@ import {
 // package.json
 var package_default = {
   name: "@cortexkit/aft-pi",
-  version: "0.61.0",
+  version: "0.62.0",
   type: "module",
   description: "Pi coding agent extension for Agent File Tools (AFT) — tree-sitter and LSP-powered code analysis",
   main: "dist/index.js",
@@ -24166,18 +24388,18 @@ var package_default = {
     "test:e2e": "bun test src/__tests__/e2e/"
   },
   dependencies: {
-    "@cortexkit/aft-bridge": "0.61.0",
+    "@cortexkit/aft-bridge": "0.62.0",
     "comment-json": "^5.0.0",
     diff: "^8.0.4",
     zod: "^4.4.3"
   },
   optionalDependencies: {
-    "@cortexkit/aft-darwin-arm64": "0.61.0",
-    "@cortexkit/aft-darwin-x64": "0.61.0",
-    "@cortexkit/aft-linux-arm64": "0.61.0",
-    "@cortexkit/aft-linux-x64": "0.61.0",
-    "@cortexkit/aft-win32-arm64": "0.61.0",
-    "@cortexkit/aft-win32-x64": "0.61.0"
+    "@cortexkit/aft-darwin-arm64": "0.62.0",
+    "@cortexkit/aft-darwin-x64": "0.62.0",
+    "@cortexkit/aft-linux-arm64": "0.62.0",
+    "@cortexkit/aft-linux-x64": "0.62.0",
+    "@cortexkit/aft-win32-arm64": "0.62.0",
+    "@cortexkit/aft-win32-x64": "0.62.0"
   },
   devDependencies: {
     "@earendil-works/pi-coding-agent": "^0.80.2",
@@ -29280,7 +29502,8 @@ function resolveBashConfig(config) {
     foreground_wait_window_ms: foregroundWaitWindowMs,
     watch_sync_max_ms: watchSyncMaxMs,
     worker_wait_max_ms: (typeof top === "object" && top !== null ? top.worker_wait_max_ms : undefined) ?? DEFAULT_WORKER_WAIT_MAX_MS,
-    powershell_tool: typeof top === "object" && top !== null ? top.powershell_tool ?? false : false
+    powershell_tool: typeof top === "object" && top !== null ? top.powershell_tool ?? false : false,
+    env: typeof top === "object" && top !== null ? { ...top.env ?? {} } : {}
   };
   if (top === false)
     return base;
@@ -29417,6 +29640,41 @@ var ExperimentalConfigSchema = object({
   }).optional(),
   lsp_ty: boolean2().optional()
 });
+var BLOCKED_BASH_ENV_NAMES = new Set([
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "LD_AUDIT",
+  "DYLD_INSERT_LIBRARIES",
+  "DYLD_LIBRARY_PATH",
+  "DYLD_FALLBACK_LIBRARY_PATH",
+  "BASH_ENV",
+  "ENV",
+  "IFS",
+  "PATH",
+  "SHELLOPTS",
+  "BASHOPTS",
+  "PROMPT_COMMAND",
+  "PS4",
+  "PYTHONSTARTUP",
+  "PYTHONPATH",
+  "PYTHONHOME",
+  "PERL5OPT",
+  "PERL5LIB",
+  "PERLLIB",
+  "PERL5DB",
+  "RUBYOPT",
+  "RUBYLIB",
+  "NODE_OPTIONS",
+  "GCONV_PATH",
+  "LOCPATH",
+  "NLSPATH",
+  "HOSTALIASES",
+  "RESOLV_HOST_CONF"
+]);
+function isBlockedBashEnvKey(key) {
+  const normalized = process.platform === "win32" ? key.toUpperCase() : key;
+  return BLOCKED_BASH_ENV_NAMES.has(normalized) || normalized.startsWith("LD_") || normalized.startsWith("DYLD_") || normalized.startsWith("BASH_FUNC_");
+}
 var BashFeaturesSchema = object({
   enabled: boolean2().optional(),
   rewrite: boolean2().optional(),
@@ -29436,7 +29694,18 @@ var BashFeaturesSchema = object({
   }).optional(),
   linux_scope: boolean2().optional(),
   disclaim_privacy: boolean2().optional(),
-  powershell_tool: boolean2().optional()
+  powershell_tool: boolean2().optional(),
+  env: record(string2(), string2()).superRefine((env, context) => {
+    for (const key of Object.keys(env)) {
+      if (isBlockedBashEnvKey(key)) {
+        context.addIssue({
+          code: "custom",
+          path: [key],
+          message: `bash.env key ${key} is blocked because it can alter startup or protected process state`
+        });
+      }
+    }
+  }).optional()
 });
 var BashConfigSchema = union([boolean2(), BashFeaturesSchema]);
 var SandboxConfigSchema = object({
@@ -29515,6 +29784,7 @@ var AftConfigFieldsSchema = object({
   $schema: string2().optional(),
   edit_mode: _enum(["default", "hashline"]).optional(),
   format_on_edit: boolean2().optional(),
+  revision_reads: boolean2().optional(),
   formatter_timeout_secs: number2().int().min(1).max(600).optional(),
   validate_on_edit: _enum(["syntax", "full"]).optional(),
   formatter: record(string2(), FormatterEnum).optional(),
@@ -29858,6 +30128,7 @@ function getProjectLspStrippedKeys(lsp) {
 var PROJECT_SAFE_TOP_LEVEL_FIELDS = new Set([
   "edit_mode",
   "format_on_edit",
+  "revision_reads",
   "validate_on_edit",
   "configure_warnings_delivery",
   "views",
@@ -29910,6 +30181,8 @@ function getStrippedTopLevelKeys(override, base) {
   }
   if (typeof override.bash === "object" && override.bash.disclaim_privacy === false)
     stripped.push("bash.disclaim_privacy");
+  if (typeof override.bash === "object" && override.bash.env !== undefined)
+    stripped.push("bash.env");
   if (override.sandbox?.write_allow !== undefined)
     stripped.push("sandbox.write_allow");
   if (override.subc !== undefined)
@@ -29957,8 +30230,10 @@ function mergeConfigs(base, override) {
   const projectBash = typeof override.bash === "object" ? { ...override.bash } : override.bash;
   if (typeof projectBash === "object" && projectBash.disclaim_privacy !== true)
     delete projectBash.disclaim_privacy;
-  if (typeof projectBash === "object")
+  if (typeof projectBash === "object") {
     delete projectBash.runon_enabled;
+    delete projectBash.env;
+  }
   const bash = mergeBashConfig(base.bash, projectBash);
   const inspect = mergeInspectConfig(base.inspect, override.inspect);
   const worktree = mergeWorktreeConfig(base.worktree, override.worktree);
@@ -30424,6 +30699,10 @@ async function callToolCallForSession(bridge, name, rawArgs, sessionId, extCtx,
       await forwardPendingBashWaitDetach(pool, bridge, sessionId, name === "bash");
     response = await bridge.toolCall(sessionId, name, rawArgs, Object.keys(sendOptions).length > 0 ? sendOptions : undefined);
   } catch (error) {
+    const noFallbackOption = name === "bash" ? rawArgs.runon !== undefined ? "runon" : rawArgs.pty === true ? "pty:true" : rawArgs.background === true ? "background:true" : undefined : undefined;
+    if (noFallbackOption && isBashTransportDeadError(error)) {
+      throw refuseAftModuleOptionWithoutFallback(error, noFallbackOption, BASH_HOST_FALLBACK_REFUSAL);
+    }
     throw adaptToolError(name, error);
   }
   ingestBgCompletions(sessionId, response.bg_completions);
@@ -32605,6 +32884,22 @@ async function assertExternalReadPermission(ctx, extCtx, target, restrictToProje
   } catch {}
   await assertExternalDirectoryPermission(extCtx, absoluteTarget, { restrictToProjectRoot });
 }
+var RevisionRefParam = {
+  ref: Type3.Optional(Type3.String({ description: REVISION_REF_DESCRIPTION }))
+};
+function withRevisionRefParam(params, config) {
+  if (!revisionReadsOffered(config))
+    return params;
+  return Type3.Object({ ...params.properties, ...RevisionRefParam });
+}
+function withRevisionRefNote(description, config, extra = "") {
+  if (!revisionReadsOffered(config))
+    return description;
+  const note = `${REVISION_REF_TOOL_NOTE}${extra ? ` ${extra}` : ""}`;
+  return `${description}
+
+${note}`;
+}
 var ReadParams = Type3.Object({
   path: Type3.String({
     description: "Path to the file or directory to read (absolute or relative to project root)"
@@ -32753,10 +33048,14 @@ function registerHoistedTools(pi, ctx, surface) {
     pi.registerTool(withPathAliasPreparation({
       name: readName,
       label: readName,
-      description: readDescription(resolveGithubConfig(ctx.config).read),
+      get description() {
+        return withRevisionRefNote(readDescription(resolveGithubConfig(ctx.config).read), ctx.config);
+      },
       promptSnippet: "Read files or directories (supports offset/limit for either)",
       promptGuidelines: [`Use ${readName} to examine files instead of cat or sed.`],
-      parameters: ReadParams,
+      get parameters() {
+        return withRevisionRefParam(ReadParams, ctx.config);
+      },
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const pathArg = readPathArg(params);
@@ -32778,6 +33077,9 @@ function registerHoistedTools(pi, ctx, surface) {
           rawArgs.offset = offset;
         if (limit !== undefined)
           rawArgs.limit = limit;
+        const ref = revisionRefArg(params.ref);
+        if (ref !== undefined)
+          rawArgs.ref = ref;
         const visionCapability = visionCapabilityForPiModel(extCtx);
         if (visionCapability !== undefined)
           rawArgs.vision_capability = visionCapability;
@@ -33885,17 +34187,22 @@ DO NOT use bash for code search or code exploration. If you are about to run gre
         }, isPowerShell ? "powershell" : "bash");
       } catch (error) {
         const fallbackCause = classifyBashHostFallbackError(error);
-        if (isPowerShell || !bashCfg.host_fallback || fallbackCause === undefined)
+        if (fallbackCause === undefined)
           throw error;
+        if (isPowerShell) {
+          throw refuseAftModuleOptionWithoutFallback(error, "PowerShell", BASH_HOST_FALLBACK_REFUSAL);
+        }
         if (!backgroundDisabled && rawRequestedBackground) {
-          throw new Error(`${BASH_HOST_FALLBACK_REFUSAL}; background:true is unsupported.`);
+          throw refuseAftModuleOptionWithoutFallback(error, "background:true", BASH_HOST_FALLBACK_REFUSAL);
         }
         if (requestedPty) {
-          throw new Error(`${BASH_HOST_FALLBACK_REFUSAL}; pty:true is unsupported.`);
+          throw refuseAftModuleOptionWithoutFallback(error, "pty:true", BASH_HOST_FALLBACK_REFUSAL);
         }
         if (params.runon !== undefined) {
-          throw new Error(`${BASH_HOST_FALLBACK_REFUSAL}; runon is unsupported, and the command was not run locally.`);
+          throw refuseAftModuleOptionWithoutFallback(error, "runon", BASH_HOST_FALLBACK_REFUSAL);
         }
+        if (!bashCfg.host_fallback)
+          throw error;
         if (!extCtx.hasUI || typeof extCtx.ui?.confirm !== "function") {
           throw new BridgeError("Permission denied: host fallback execution requires an interactive UI.", "permission_denied");
         }
@@ -35418,24 +35725,22 @@ var OutlineParams = Type11.Object({
     description: "Directory outline only: include test files. Defaults to false; tests are hidden."
   }))
 });
-var ZoomTarget = Type11.Object({
-  path: Type11.String({ description: "Path to file (absolute or project-relative)" }),
-  symbol: Type11.String({ description: "Symbol name in that file" })
+var ZoomEntry = Type11.Object({
+  target: Type11.String({
+    description: "File path (absolute or project-relative) or HTTP/HTTPS URL, auto-detected; issue://N or pr://N when GitHub reads are enabled"
+  }),
+  symbols: Type11.Union([Type11.String(), Type11.Array(Type11.String())], {
+    description: "Symbol name for code or heading text for Markdown/HTML; a string or array of strings"
+  })
 });
 var ZoomParams = Type11.Object({
-  path: Type11.Optional(Type11.String({ description: "Path to file (absolute or project-relative)" })),
-  url: Type11.Optional(Type11.String({
-    description: "HTTP/HTTPS URL of an HTML or Markdown document to fetch and zoom into"
-  })),
-  symbols: Type11.Optional(Type11.Union([Type11.String(), Type11.Array(Type11.String())], {
-    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: Type11.Optional(Type11.Union([ZoomTarget, Type11.Array(ZoomTarget)], {
-    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)"),
+  batch: Type11.Array(ZoomEntry, {
+    minItems: 1,
+    description: "One or more lookups; entries may mix file paths and URLs"
+  }),
+  contextLines: optionalInt(1, Number.MAX_SAFE_INTEGER, "Lines of context before/after each symbol (default: 3)"),
   callgraph: Type11.Optional(Type11.Boolean({
-    description: "Include call-graph annotations (calls-out / called-by within the same file). Default false; off keeps zoom output minimal."
+    description: "Include call-graph annotations for every entry (default: false)"
   }))
 });
 function isUrl(s) {
@@ -35453,12 +35758,27 @@ async function assertReadPathPermissions(extCtx, ctx, paths) {
 }
 function zoomTargetLabel(args) {
   const safeArgs = asRecordOrEmpty(args);
-  return asString2(safeArgs.path) ?? asString2(safeArgs.url) ?? "(no target)";
+  if (Array.isArray(safeArgs.batch)) {
+    if (safeArgs.batch.length > 1)
+      return `${safeArgs.batch.length} locations`;
+    return asString2(asRecord3(safeArgs.batch[0])?.target) ?? "(no target)";
+  }
+  return asString2(safeArgs.target) ?? asString2(safeArgs.path) ?? asString2(safeArgs.url) ?? "(no target)";
 }
 function zoomExtraCallSites(call) {
   const extraCount = call.extra_count;
   return typeof extraCount === "number" && Number.isInteger(extraCount) && extraCount > 0 ? ` +${extraCount}` : "";
 }
+var ZOOM_CALL_ANNOTATION_LIMIT = 15;
+function renderZoomAnnotationSection(label, calls, theme) {
+  const rendered = calls.slice(0, ZOOM_CALL_ANNOTATION_LIMIT).map((call) => `  ↳ ${asString2(call.name) ?? "(unknown)"}${typeof call.line === "number" ? `:${call.line}` : ""}${zoomExtraCallSites(call)}`);
+  if (calls.length > ZOOM_CALL_ANNOTATION_LIMIT) {
+    rendered.push(`  +${calls.length - ZOOM_CALL_ANNOTATION_LIMIT} more`);
+  }
+  return `${theme.fg("muted", label)}
+${rendered.join(`
+`)}`;
+}
 function buildOutlineSections(text, theme) {
   const trimmed = text.trim();
   if (!trimmed)
@@ -35488,12 +35808,10 @@ function renderZoomRecord(record, targetLabel, theme) {
   const callsOut = annotations ? asRecords2(annotations.calls_out) : [];
   const calledBy = annotations ? asRecords2(annotations.called_by) : [];
   if (callsOut.length > 0) {
-    lines.push(`${theme.fg("muted", "calls out")}`, callsOut.map((call) => `  ↳ ${asString2(call.name) ?? "(unknown)"}${typeof call.line === "number" ? `:${call.line}` : ""}${zoomExtraCallSites(call)}`).join(`
-`));
+    lines.push(renderZoomAnnotationSection("calls out", callsOut, theme));
   }
   if (calledBy.length > 0) {
-    lines.push(`${theme.fg("muted", "called by")}`, calledBy.map((call) => `  ↳ ${asString2(call.name) ?? "(unknown)"}${typeof call.line === "number" ? `:${call.line}` : ""}${zoomExtraCallSites(call)}`).join(`
-`));
+    lines.push(renderZoomAnnotationSection("called_by (this file)", calledBy, theme));
   }
   return lines.join(`
 `);
@@ -35562,9 +35880,10 @@ function renderOutlineResult(result, theme, context, options = { expanded: true
 }
 function renderZoomCall(args, theme, context) {
   const safeArgs = asRecordOrEmpty(args);
-  const hasExplicitTarget = typeof safeArgs.path === "string" || typeof safeArgs.url === "string";
-  const symbols = safeArgs.symbols;
-  const targets = safeArgs.targets;
+  const entries = Array.isArray(safeArgs.batch) ? safeArgs.batch : [];
+  const hasExplicitTarget = entries.length > 0 || typeof safeArgs.target === "string" || typeof safeArgs.path === "string" || typeof safeArgs.url === "string";
+  const symbols = entries.length === 1 ? asRecord3(entries[0])?.symbols : safeArgs.symbols;
+  const targets = entries.length > 1 ? entries : safeArgs.targets;
   let summary;
   if (typeof symbols === "string") {
     summary = theme.fg("toolOutput", symbols);
@@ -35608,12 +35927,8 @@ function registerReadingTools(pi, ctx, surface) {
   const zoomEnabled = toolEnabled(ctx.config, "aft_zoom");
   const ghReadEnabled = resolveGithubConfig(ctx.config).read;
   const githubOutlineDescription = whenGhReadEnabled(ghReadEnabled, "GitHub issues and pull requests can be outlined with `issue://NUMBER` or `pr://NUMBER` (including `OWNER/REPO` forms).");
-  const githubZoomDescription = whenGhReadEnabled(ghReadEnabled, "GitHub issue and pull-request discussion ordinals can be zoomed with `path: issue://…` or `path: pr://…` and `symbols`.");
-  if (surface.outline) {
-    const outlineTool = withPathAliasPreparation({
-      name: "aft_outline",
-      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.
+  const githubZoomDescription = whenGhReadEnabled(ghReadEnabled, "Batch targets may use `issue://NUMBER` or `pr://NUMBER` (including `OWNER/REPO` forms) to inspect GitHub discussion ordinals.");
+  const outlineDescription = `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.
 
 ${outlineFocusSteer(ctx.config)}
 
@@ -35625,18 +35940,32 @@ Pass a single \`target\`:
 
 ${githubOutlineDescription}` : ""}
 
-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.`,
-      parameters: OutlineParams,
+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.`;
+  const zoomDescription = 'Inspect code symbols or documentation sections. Pass lookups in `batch: [{ target, symbols }]`; a single lookup is a one-entry batch. Mix files and URLs in one batch, for example `batch: [{ target: "src/app.ts", symbols: "run" }, { target: "https://example.com/docs", symbols: "Overview" }]`. Each target is auto-detected as a file path or an HTTP/HTTPS URL. `symbols` is a string or string array. Markdown and HTML lookups return the section under the heading. Top-level `contextLines` and `callgraph` apply to every entry; callgraph adds calls-out and called-by annotations. Each failed lookup reports its own error line.' + (githubZoomDescription ? `
+
+${githubZoomDescription}` : "");
+  if (surface.outline) {
+    const outlineTool = withPathAliasPreparation({
+      name: "aft_outline",
+      label: "outline",
+      get description() {
+        return withRevisionRefNote(outlineDescription, ctx.config, "Only a single file can be outlined at a revision.");
+      },
+      get parameters() {
+        return withRevisionRefParam(OutlineParams, ctx.config);
+      },
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
         const target = coerceTargetParam(params.target);
         const filesMode = coerceBoolean(params.files);
         const hasIncludeTests = !isEmptyParam(params.includeTests);
         const includeTests = coerceBoolean(params.includeTests);
+        const ref = revisionRefArg(params.ref);
         const rawArgs = {
           target,
           ...filesMode ? { files: true } : {},
-          ...hasIncludeTests ? { includeTests } : {}
+          ...hasIncludeTests ? { includeTests } : {},
+          ...ref !== undefined ? { ref } : {}
         };
         if (Array.isArray(target)) {
           if (target.length === 0) {
@@ -35682,81 +36011,33 @@ 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 `{ 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,
+      get description() {
+        return withRevisionRefNote(zoomDescription, ctx.config, "Every file of the call is read at that revision; URLs do not have revisions.");
+      },
+      get parameters() {
+        return withRevisionRefParam(ZoomParams, ctx.config);
+      },
       async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
         const bridge = bridgeFor(ctx, extCtx.cwd);
-        const targetsInput = coerceJsonCollectionParam(params.targets, "targets");
-        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);
+        if (!Array.isArray(params.batch) || params.batch.length === 0)
+          throw new Error("'batch' must be a non-empty array of {target, symbols}");
+        const ref = revisionRefArg(params.ref);
+        if (ref !== undefined && params.batch.some((entry) => isUrl(entry.target)))
+          throw new Error("'ref' cannot be used with a URL target: a URL has no revision");
+        const paths = params.batch.map((entry) => entry.target).filter((target) => target && !isGithubPathArg(target) && !isUrl(target));
+        const resolved = await Promise.all(paths.map((target) => resolvePathArg(extCtx.cwd, target)));
+        await assertReadPathPermissions(extCtx, ctx, resolved);
+        const rawArgs = { batch: params.batch };
         const contextLines = coerceOptionalInt(params.contextLines, "contextLines", 1, Number.MAX_SAFE_INTEGER);
-        if (hasTargets) {
-          if (hasPath && hasUrl) {
-            throw new Error("Provide exactly ONE of 'path' or 'url' — not both");
-          }
-          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`);
-            }
-            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)
-            rawArgs.callgraph = true;
-          const response = await callToolCall(bridge, "zoom", rawArgs, extCtx);
-          if (response.success === false) {
-            throw new Error(response.text || response.message || "zoom failed");
-          }
-          return textResult(response.text, response);
-        }
-        if (!hasPath && !hasUrl) {
-          throw new Error("Provide exactly one of 'path', 'url', or 'targets'");
-        }
-        if (hasPath && hasUrl) {
-          throw new Error("Provide exactly ONE of 'path' or 'url' — not both");
-        }
-        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);
-        }
-        const rawArgs = hasUrl ? { url: params.url } : { filePath: params.path };
-        if (hasSymbols)
-          rawArgs.symbols = params.symbols;
         if (contextLines !== undefined)
           rawArgs.contextLines = contextLines;
-        if (wantCallgraph)
+        if (coerceBoolean(params.callgraph))
           rawArgs.callgraph = true;
+        if (ref !== undefined)
+          rawArgs.ref = ref;
         const response = await callToolCall(bridge, "zoom", rawArgs, extCtx);
-        if (response.success === false) {
+        if (response.success === false)
           throw new Error(response.text || response.message || "zoom failed");
-        }
         return textResult(response.text, response);
       },
       renderCall(args, theme, context) {
@@ -35776,11 +36057,11 @@ function responsePaths(response) {
   return Array.isArray(response.paths) ? response.paths.filter((path) => typeof path === "string" && path.length > 0) : [];
 }
 var SafetyParams = Type12.Object({
-  op: StringEnum4(["undo", "history", "checkpoint", "restore", "list"], {
+  op: StringEnum4(["undo", "history", "checkpoint", "restore", "list", "purge"], {
     description: "Safety operation"
   }),
   path: Type12.Optional(Type12.String({
-    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."
+    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, required for purge — a file or directory). Absolute or relative to project root."
   })),
   name: Type12.Optional(Type12.String({ description: "Checkpoint name (required for checkpoint, restore)" })),
   files: Type12.Optional(Type12.Array(Type12.String(), {
@@ -35866,6 +36147,21 @@ ${skipped.map((entry) => `  ↳ ${shortenHomePath(asString2(entry.file) ?? "(fil
       sections.push(theme.fg("muted", durability));
     return sections;
   }
+  if (op === "purge") {
+    const pruned = asRecords2(response.checkpoints_pruned).map((entry) => asString2(entry.name)).filter((name) => Boolean(name));
+    const dropped = Array.isArray(response.checkpoints_dropped) ? response.checkpoints_dropped.filter((name) => typeof name === "string") : [];
+    const failures = asRecords2(response.failures);
+    return [
+      `${theme.fg("success", "purged")} ${theme.fg("accent", shortenHomePath(asString2(response.path) ?? path ?? "(path)"))}`,
+      `${theme.fg("muted", "undo backups removed")} ${asNumber2(response.undo_entries_removed) ?? 0}`,
+      pruned.length > 0 ? `${theme.fg("muted", "checkpoints pruned")} ${pruned.join(", ")}` : "",
+      dropped.length > 0 ? `${theme.fg("muted", "checkpoints dropped")} ${dropped.join(", ")}` : "",
+      failures.length > 0 ? `${theme.fg("warning", "not removed")}
+${failures.map((entry) => `  ↳ ${asString2(entry.target) ?? "(unknown)"}: ${asString2(entry.error) ?? "unknown error"}`).join(`
+`)}` : "",
+      theme.fg("warning", "This cannot be undone.")
+    ].filter((section) => section.length > 0);
+  }
   const knownDetails = [path, name].filter((value) => Boolean(value));
   return [theme.fg("muted", "Safety result available."), ...knownDetails];
 }
@@ -35895,10 +36191,10 @@ function registerSafetyTool(pi, ctx) {
   pi.registerTool(withPathAliasPreparation({
     name: "aft_safety",
     label: "safety",
-    description: "File safety and recovery operations. Ops: `undo` (omit path to undo the entire last tool call; pass path to pop latest snapshot for one file — irreversible), `history` (list snapshots for a file), `checkpoint` (save named snapshot), `restore` (restore named checkpoint; optional path/files scopes it), `list` (list checkpoints). Per-file undo stack is capped at 20.",
+    description: "`undo` reverts a tool call (omit path) or latest file snapshot (irreversible); `history` lists snapshots; `checkpoint` saves named snapshots on disk across restarts, expiring after 14 days (contents may include secrets); `restore` restores a checkpoint, optionally scoped by path/files; `list` lists checkpoints; `purge` permanently deletes this session's undo backups and checkpoint copies of a file or directory `path` (cannot be undone). Undo keeps 20 snapshots/file (oldest evicted).",
     parameters: SafetyParams,
     async execute(_toolCallId, params, _signal, _onUpdate, extCtx) {
-      if (params.op === "history" && !params.path) {
+      if ((params.op === "history" || params.op === "purge") && !params.path) {
         throw new Error(`op='${params.op}' requires 'path'`);
       }
       if ((params.op === "checkpoint" || params.op === "restore") && !params.name) {
@@ -35942,6 +36238,16 @@ function registerSafetyTool(pi, ctx) {
           });
         }
       }
+      if (params.op === "purge" && params.path) {
+        const purgeTarget = await resolvePathArg(extCtx.cwd, params.path);
+        await assertExternalDirectoryPermission(extCtx, purgeTarget, { restrictToProjectRoot });
+        const preview = await callBridge(bridge, "safety_purge_paths", { file: purgeTarget }, extCtx);
+        for (const file of new Set(responsePaths(preview))) {
+          await assertExternalDirectoryPermission(extCtx, file, {
+            restrictToProjectRoot
+          });
+        }
+      }
       const rawArgs = { op: params.op };
       if (filePath)
         rawArgs.filePath = filePath;
@@ -36043,7 +36349,7 @@ var SearchParams2 = Type13.Object({
     description: "Include test files (*.test.*, *_test.rs, __tests__/, …) plus test-support, fixture, mock, snapshot, and corpus files. Defaults to false."
   })),
   path: Type13.Optional(Type13.String({
-    description: "Only set this to search a different Git project (absolute or ~ path). Omit it for the current configured workspace, including non-Git workspace roots; this is not a subdirectory filter. Unindexed external projects use a bounded lexical fallback."
+    description: "Only set this to search a different project or plain folder (absolute or ~ path). Omit it for the current configured workspace, including non-Git workspace roots; this is not a subdirectory filter. Unindexed external folders use a bounded lexical fallback; filesystem roots, home and its ancestors are refused."
   }))
 });
 function buildSemanticSections(args, payload, theme) {
@@ -36335,6 +36641,17 @@ function registerPiToolSurface(pi, ctx, loadedSurface, harness) {
   if (surface.delete || surface.move)
     registerFsTools(boundPi, ctx, surface);
 }
+function refreshPiRevisionReadTools(pi, ctx, loadedSurface) {
+  const surface = withLiveRestriction({
+    ...loadedSurface,
+    hoistWrite: false,
+    hoistEdit: false,
+    hoistGrep: false
+  }, ctx);
+  const boundPi = bindToolRegistrationFunnel(pi, ctx);
+  registerHoistedTools(boundPi, ctx, surface);
+  registerReadingTools(boundPi, ctx, surface);
+}
 
 // src/config-error-state.ts
 var CONFIG_ERROR_STATUS_KEY = "aft";
@@ -36459,7 +36776,12 @@ function startPiLiveConfigReload(options) {
     securityKeys: aftLiveSecurityKeys(PI_LIVE_CONFIG_KEYS),
     keys: PI_LIVE_CONFIG_KEYS,
     getConfig: options.getConfig,
-    setConfig: options.setConfig,
+    setConfig: (next) => {
+      const revisionReadsChanged = options.getConfig().revision_reads !== next.revision_reads;
+      options.setConfig(next);
+      if (revisionReadsChanged)
+        options.refreshRevisionReadTools?.();
+    },
     log: (message) => log2(`${message} (${options.directory})`),
     reportError: (message) => {
       error2(message);
@@ -36582,7 +36904,7 @@ function buildWorkflowHints(opts) {
 `));
   }
   if (hasOutline && hasZoom) {
-    sections.push(`**Web/URL access**: \`aft_outline({ target: "<url>" })\` first for structure, then \`aft_zoom({ url: "<url>", symbols: "<heading>" })\` for the specific section.`);
+    sections.push(`**Web/URL access**: \`aft_outline({ target: "<url>" })\` first for structure, then \`aft_zoom({ batch: [{ target: "<url>", symbols: "<heading>" }] })\` for the specific section.`);
   }
   if (hasOutline && (hasGrep || hasSearch) && (hasZoom || hasRead)) {
     const searchName = hasSearch ? "aft_search" : grepName;
@@ -36748,12 +37070,12 @@ var PLUGIN_VERSION = (() => {
     return "0.0.0";
   }
 })();
-var ANNOUNCEMENT_VERSION = "0.61.0";
+var ANNOUNCEMENT_VERSION = "0.62.0";
 var ANNOUNCEMENT_FEATURES = [
-  "Shell sandboxing has per-role profiles: `sandbox.profile` (`off`, `relaxed`, `strict`) replaces `sandbox.enabled`, and `npx @cortexkit/aft doctor --fix` migrates your config.",
-  "Edits keep files' permissions and ownership, replacing them atomically when that is safe, and `apply_patch` rejects malformed or ambiguous patches before writing anything.",
-  "Much lighter background work: less CPU, disk and memory use, and no indexing of your home folder or drive roots.",
-  "Long shell waits keep their replies, remote `runon` jobs survive build-server restarts, and many reported issues are fixed."
+  "Linux dev containers work again: a project at a bind-mount target such as `/workspace` is no longer refused as too broad.",
+  "Read a file as it is at any git revision with the opt-in `ref` argument on `read`, `aft_outline` and `aft_zoom` (set `revision_reads: true`).",
+  "`aft_safety` has a `purge` op that permanently removes a file from this session's undo backups and checkpoints, such as a secret written by mistake.",
+  "`aft_zoom` takes one `batch` of lookups mixing files and URLs, and many reported issues are fixed."
 ];
 var ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/DSa65w8wuf";
 var pendingEagerWarnings = new Map;
@@ -37025,7 +37347,8 @@ async function src_default(pi) {
         registerBashTool(pi, ctx, surface.semantic, "bash", false, "bash");
       }
     },
-    notify: (message) => deliverConfigMigrationWarnings([message])
+    notify: (message) => deliverConfigMigrationWarnings([message]),
+    refreshRevisionReadTools: () => refreshPiRevisionReadTools(pi, ctx, surface)
   });
   const startLspDiscovery = () => {
     try {