@librechat/agents 3.6.13 → 3.6.14

package/dist/esm/tools/local/syntaxCheck.mjs

@@ -1,14 +1,8 @@
 import { isWorkspaceClientTimeoutError } from "./workspaceFS.mjs";
-import { getSpawn, getWorkspaceFS, spawnLocalProcess } from "./LocalExecutionEngine.mjs";
+import { commandAvailabilityEnvCacheKey, getSpawn, getWorkspaceFS, probeLocalCommandAvailability, setCommandAvailabilityCacheEntry, spawnLocalProcess } from "./LocalExecutionEngine.mjs";
 import { extname } from "path";
 //#region src/tools/local/syntaxCheck.ts
 let probeCacheByBackend = /* @__PURE__ */ new WeakMap();
-function envCacheKey(env) {
-	if (env == null) return "";
-	const sorted = {};
-	for (const k of Object.keys(env).sort()) sorted[k] = env[k];
-	return JSON.stringify(sorted);
-}
 function cacheFor(config) {
 	const backend = getSpawn(config);
 	let envMap = probeCacheByBackend.get(backend);
@@ -16,11 +10,11 @@ function cacheFor(config) {
 		envMap = /* @__PURE__ */ new Map();
 		probeCacheByBackend.set(backend, envMap);
 	}
-	const envKey = envCacheKey(config.env);
+	const envKey = commandAvailabilityEnvCacheKey(config.env);
 	let entry = envMap.get(envKey);
 	if (entry == null) {
 		entry = {};
-		envMap.set(envKey, entry);
+		setCommandAvailabilityCacheEntry(envMap, envKey, entry);
 	}
 	return entry;
 }
@@ -28,14 +22,16 @@ async function probe(command, args, cached, config) {
 	const entry = cacheFor(config);
 	let probePromise = entry[cached];
 	if (probePromise == null) {
-		probePromise = spawnLocalProcess(command, args, {
-			...config,
-			timeoutMs: 5e3,
-			sandbox: { enabled: false }
-		}, { internal: true }).then((result) => result != null && result.exitCode === 0).catch(() => false);
+		probePromise = probeLocalCommandAvailability(command, args, config);
 		entry[cached] = probePromise;
 	}
-	return probePromise;
+	const result = await probePromise;
+	if (!result.cacheable && entry[cached] === probePromise) delete entry[cached];
+	if (result.cacheUntil != null && result.cacheUntil <= Date.now()) {
+		if (entry[cached] === probePromise) delete entry[cached];
+		return probe(command, args, cached, config);
+	}
+	return result.available;
 }
 function _resetSyntaxCheckProbeCacheForTests() {
 	probeCacheByBackend = /* @__PURE__ */ new WeakMap();

package/dist/esm/tools/local/syntaxCheck.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"syntaxCheck.mjs","names":[],"sources":["../../../../src/tools/local/syntaxCheck.ts"],"mappings":"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"}
+{"version":3,"file":"syntaxCheck.mjs","names":[],"sources":["../../../../src/tools/local/syntaxCheck.ts"],"mappings":"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"}

package/dist/esm/tools/local/workspaceFS.mjs

@@ -10,7 +10,7 @@ var WorkspaceClientTimeoutError = class extends Error {
 function isWorkspaceClientTimeoutError(error) {
 	return error instanceof WorkspaceClientTimeoutError || typeof error === "object" && error !== null && error.code === "WORKSPACE_CLIENT_TIMEOUT";
 }
-const nodeWorkspaceFS = {
+const nodeWorkspaceFS = Object.freeze({
 	readFile: ((path, encoding) => encoding != null ? readFile(path, encoding) : readFile(path)),
 	writeFile: (path, content, options) => writeFile(path, content, options ?? "utf8"),
 	stat: (path) => stat(path),
@@ -21,7 +21,7 @@ const nodeWorkspaceFS = {
 	realpath: (path) => realpath(path),
 	unlink: (path) => unlink(path),
 	open: (path, flags) => open(path, flags)
-};
+});
 //#endregion
 export { WorkspaceClientTimeoutError, isWorkspaceClientTimeoutError, nodeWorkspaceFS };
 

package/dist/esm/tools/local/workspaceFS.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"workspaceFS.mjs","names":["fsReadFile","fsWriteFile","fsStat","fsReaddir","fsMkdir","fsRealpath","fsUnlink","fsOpen"],"sources":["../../../../src/tools/local/workspaceFS.ts"],"mappings":";;AAiDA,IAAa,8BAAb,cAAiD,MAAM;CACrD,OAAgB;CAChB,YAAY,SAAiB;EAC3B,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;AAEA,SAAgB,8BACd,OACsC;CACtC,OACE,iBAAiB,+BAChB,OAAO,UAAU,YAChB,UAAU,QACT,MAA6B,SAAS;AAE7C;AA4BA,MAAa,kBAA+B;CAI1C,YAAY,MAAc,aACxB,YAAY,OACRA,SAAW,MAAM,QAAQ,IACzBA,SAAW,IAAI;CACrB,YAAY,MAAM,SAAS,YACzBC,UAAY,MAAM,SAAS,WAAW,MAAM;CAC9C,OAAO,SAASC,KAAO,IAAI;CAC3B,WAAW,MAAc,YACvB,SAAS,kBAAkB,OACvBC,QAAU,MAAM,EAAE,eAAe,KAAK,CAAC,IACvCA,QAAU,IAAI;CACpB,OAAO,OAAO,MAAM,YAAY;EAC9B,MAAMC,MAAQ,MAAM,OAAO;CAC7B;CACA,WAAW,SAASC,SAAW,IAAI;CACnC,SAAS,SAASC,OAAS,IAAI;CAC/B,OAAO,MAAM,UAAUC,KAAO,MAAM,KAAK;AAC3C"}
+{"version":3,"file":"workspaceFS.mjs","names":["fsReadFile","fsWriteFile","fsStat","fsReaddir","fsMkdir","fsRealpath","fsUnlink","fsOpen"],"sources":["../../../../src/tools/local/workspaceFS.ts"],"mappings":";;AAiDA,IAAa,8BAAb,cAAiD,MAAM;CACrD,OAAgB;CAChB,YAAY,SAAiB;EAC3B,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF;AAEA,SAAgB,8BACd,OACsC;CACtC,OACE,iBAAiB,+BAChB,OAAO,UAAU,YAChB,UAAU,QACT,MAA6B,SAAS;AAE7C;AA4BA,MAAa,kBAAkB,OAAO,OAAoB;CAGxD,YAAY,MAAc,aACxB,YAAY,OACRA,SAAW,MAAM,QAAQ,IACzBA,SAAW,IAAI;CACrB,YAAY,MAAM,SAAS,YACzBC,UAAY,MAAM,SAAS,WAAW,MAAM;CAC9C,OAAO,SAASC,KAAO,IAAI;CAC3B,WAAW,MAAc,YACvB,SAAS,kBAAkB,OACvBC,QAAU,MAAM,EAAE,eAAe,KAAK,CAAC,IACvCA,QAAU,IAAI;CACpB,OAAO,OAAO,MAAM,YAAY;EAC9B,MAAMC,MAAQ,MAAM,OAAO;CAC7B;CACA,WAAW,SAASC,SAAW,IAAI;CACnC,SAAS,SAASC,OAAS,IAAI;CAC/B,OAAO,MAAM,UAAUC,KAAO,MAAM,KAAK;AAC3C,CAAC"}

package/dist/types/tools/cloudflare/CloudflareSandboxExecutionEngine.d.ts

@@ -62,6 +62,12 @@ export declare function execWithClientTimeout(sandbox: t.CloudflareSandboxRuntim
     unref?: boolean;
 }): Promise<t.CloudflareSandboxExecResult>;
 export declare function createCloudflareWorkspaceFS(config: t.CloudflareSandboxExecutionConfig): WorkspaceFS;
+/**
+ * Returns one stable filesystem/process world for a Cloudflare configuration.
+ * Probe caches key on the spawn identity, so retaining it avoids repeating
+ * remote capability checks whenever an agent binding rebuilds its tools.
+ */
+export declare function createCloudflareExecutionWorld(config: t.CloudflareSandboxExecutionConfig): t.ExecutionWorld;
 export declare function createCloudflareLocalExecutionConfig(config: t.CloudflareSandboxExecutionConfig): t.LocalExecutionConfig;
 export declare function validateCloudflareBashCommand(command: string, args: readonly string[], config: t.CloudflareSandboxExecutionConfig): Promise<void>;
 export declare function executeCloudflareBash(command: string, config: t.CloudflareSandboxExecutionConfig, args?: readonly string[]): Promise<SpawnResult>;

package/dist/types/tools/local/LocalExecutionEngine.d.ts

@@ -1,5 +1,9 @@
 import type { WorkspaceFS } from './workspaceFS';
 import type * as t from '@/types';
+/** Produces a stable, non-plaintext key for environment-sensitive probes. */
+export declare function commandAvailabilityEnvCacheKey(env: NodeJS.ProcessEnv | undefined): string;
+/** Adds a probe entry while bounding retained environment variants. */
+export declare function setCommandAvailabilityCacheEntry<T>(cache: Map<string, T>, key: string, value: T): void;
 type SpawnResult = {
     stdout: string;
     stderr: string;
@@ -45,6 +49,10 @@ export declare function getLocalCwd(config?: t.LocalExecutionConfig): string;
  * need realpath equality (see `resolveWorkspacePathSafe`).
  */
 export declare function getWorkspaceRoots(config?: t.LocalExecutionConfig): string[];
+/** Node-host execution world used when no backend override is configured. */
+export declare const nodeExecutionWorld: t.ExecutionWorld;
+/** Resolves filesystem and subprocess capabilities as one execution world. */
+export declare function getExecutionWorld(config?: t.LocalExecutionConfig): t.ExecutionWorld;
 /**
  * Pluggable spawn resolver. Honours `local.exec.spawn` first, falls
  * back to the legacy top-level `local.spawn`, then to Node's
@@ -130,6 +138,20 @@ export interface SpawnLocalProcessOptions {
 }
 export declare const LOCAL_SPAWN_TIMEOUT_MS: unique symbol;
 export declare function spawnLocalProcess(command: string, args: string[], config?: t.LocalExecutionConfig, options?: SpawnLocalProcessOptions): Promise<SpawnResult>;
+/** Result of a command-availability probe and whether its verdict is stable. */
+export type CommandAvailabilityProbe = {
+    available: boolean;
+    cacheable: boolean;
+    cacheUntil?: number;
+};
+/**
+ * Probes one executable without turning transient backend failures into
+ * permanent capability facts. Exit 126/127 is a definite unusable/missing
+ * executable. A native ENOENT is stable only when the current working
+ * directory exists; timeouts, transport failures, and ambiguous lookup
+ * failures are retried.
+ */
+export declare function probeLocalCommandAvailability(command: string, args: string[], config: t.LocalExecutionConfig): Promise<CommandAvailabilityProbe>;
 export declare function executeLocalBash(command: string, config?: t.LocalExecutionConfig): Promise<SpawnResult>;
 export declare function executeLocalBashWithArgs(command: string, args: readonly string[], config?: t.LocalExecutionConfig): Promise<SpawnResult>;
 export declare function executeLocalCode(input: {

package/dist/types/tools/local/workspaceFS.d.ts

@@ -59,4 +59,4 @@ export interface WorkspaceFS {
  * Returned by `getWorkspaceFS(config)` when the host hasn't supplied
  * an override on `local.exec.fs`.
  */
-export declare const nodeWorkspaceFS: WorkspaceFS;
+export declare const nodeWorkspaceFS: Readonly<WorkspaceFS>;

package/dist/types/types/tools.d.ts

@@ -759,47 +759,32 @@ export type LocalWorkspaceConfig = {
     allowWriteOutside?: boolean;
 };
 /**
- * Engine-agnostic execution seam. Default uses Node's
- * `child_process.spawn` and `fs/promises`. A future engine (e.g.
- * stateful remote sandbox) supplies its own `spawn` and `fs` and
- * inherits every tool factory unchanged.
+ * One execution world shared by filesystem and subprocess operations.
+ * Backend identity is stable so capability probes remain warm when tool
+ * bundles are rebuilt for later agent bindings.
+ */
+export interface ExecutionWorld {
+    /** Launches a process inside this world's filesystem namespace. */
+    readonly spawn: LocalSpawn;
+    /** Reads and writes the same namespace observed by `spawn`. */
+    readonly fs: Readonly<import('@/tools/local/workspaceFS').WorkspaceFS>;
+    /** Whether the world already enforces a sandbox boundary. */
+    readonly sandboxed: boolean;
+}
+/**
+ * Backward-compatible partial execution-world override. Omitted fields use
+ * the Node host world; remote backends should provide the complete trio.
  *
- * **Important — pair `spawn` and `fs` together.** Most file-touching
- * surfaces in the local engine route through `getWorkspaceFS(config)`
- * so a host can transparently swap in a remote/in-memory FS. A small
- * set of helpers — currently the `execute_code` non-bash temp-file
- * write (Codex P2 [48]) — still uses host `fs/promises` directly to
- * stage source on disk before invoking the spawn. If you override
- * `spawn` to point at a remote runtime (SSH, container, etc.) you
- * MUST also override `fs` with the corresponding remote
- * implementation; otherwise temp source files written to the host
- * `/tmp` won't be visible to the remote interpreter and `py`/`js`/
- * `ts`/etc. executions will fail. (Bash-style executions go through
- * `executeLocalBash` which doesn't stage temp files, so they're
- * unaffected.)
+ * Non-bash `execute_code` still stages source through the host temporary
+ * directory. Remote runtimes should use their dedicated execution engine for
+ * that tool until temporary lifecycle operations join this seam.
  *
- * Threat-model note: the regex-based command validators
- * (`dangerousCommandPatterns`, `quotedDestructivePatterns`, etc.) and
- * the workspace policy hook are documented as best-effort tripwires.
- * The hard security boundary is `local.sandbox.enabled: true` (which
- * wraps execution in `@anthropic-ai/sandbox-runtime`); for adversarial-
- * model threat models, do NOT rely on the regex layer alone.
+ * Command validators and workspace policies are best-effort tripwires. For an
+ * adversarial-model threat model, use a backend sandbox boundary rather than
+ * relying on validation alone.
  */
 export type LocalExecConfig = {
-    /** Pluggable spawn (for SSH, container, remote workers, etc.). */
-    spawn?: LocalSpawn;
-    /**
-     * Pluggable filesystem (for remote-workspace engines). Pair with
-     * `spawn` — see the type-level note above on why both should be
-     * overridden together for non-host engines.
-     */
-    fs?: import('@/tools/local/workspaceFS').WorkspaceFS;
-    /**
-     * Set by custom execution backends that already provide their own
-     * sandbox boundary. Suppresses the local host-sandbox warning while
-     * preserving the warning for plain host `child_process` execution.
-     */
-    sandboxed?: boolean;
+    -readonly [Key in keyof ExecutionWorld]?: Key extends 'fs' ? import('@/tools/local/workspaceFS').WorkspaceFS : ExecutionWorld[Key];
 };
 export type LocalExecutionConfig = {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.6.13",
+  "version": "3.6.14",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -154,6 +154,7 @@
     "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
     "bench:cache": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-prompt-cache.ts",
     "bench:context-pressure": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-context-pressure-cache.ts",
+    "bench:execution-world": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-execution-world.ts",
     "probe:overflow": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/context-overflow-probe.ts",
     "subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
     "subagent:events": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-event-driven-debug.ts",

package/src/tools/cloudflare/CloudflareSandboxExecutionEngine.ts

@@ -5,11 +5,11 @@ import type { WriteFileOptions, MakeDirectoryOptions, Stats } from 'fs';
 import type { ChildProcessWithoutNullStreams } from 'child_process';
 import type { FileHandle } from 'fs/promises';
 import type { WorkspaceFS, ReaddirEntry } from '@/tools/local/workspaceFS';
+import type * as t from '@/types';
 import {
   WorkspaceClientTimeoutError,
   isWorkspaceClientTimeoutError,
 } from '@/tools/local/workspaceFS';
-import type * as t from '@/types';
 import {
   LOCAL_SPAWN_TIMEOUT_MS,
   validateBashCommand,
@@ -44,9 +44,28 @@ type SandboxRuntimeContext = {
   shell: string;
 };
 
+type ExecutionWorldCacheEntry = {
+  world: t.ExecutionWorld;
+  workspaceRoot: string;
+  timeoutMs: number;
+  sandbox: t.CloudflareSandboxExecutionConfig['sandbox'];
+};
+
+const executionWorldCache = new WeakMap<
+  t.CloudflareSandboxExecutionConfig,
+  ExecutionWorldCacheEntry
+>();
+
+type SandboxFactoryCacheEntry = {
+  sandbox: () =>
+    | t.CloudflareSandboxRuntime
+    | Promise<t.CloudflareSandboxRuntime>;
+  promise: Promise<t.CloudflareSandboxRuntime>;
+};
+
 const sandboxFactoryCache = new WeakMap<
   t.CloudflareSandboxExecutionConfig,
-  Promise<t.CloudflareSandboxRuntime>
+  SandboxFactoryCacheEntry
 >();
 
 function normalizeWorkspaceRoot(workspaceRoot: string): string {
@@ -69,17 +88,20 @@ export async function resolveCloudflareSandbox(
   if (typeof sandbox !== 'function') {
     return sandbox;
   }
-  let cached = sandboxFactoryCache.get(config);
-  if (cached == null) {
-    cached = Promise.resolve()
-      .then(() => sandbox())
-      .catch((error: unknown) => {
-        sandboxFactoryCache.delete(config);
-        throw error;
-      });
-    sandboxFactoryCache.set(config, cached);
+  const cached = sandboxFactoryCache.get(config);
+  if (cached?.sandbox === sandbox) {
+    return cached.promise;
   }
-  return cached;
+  const promise = Promise.resolve()
+    .then(() => sandbox())
+    .catch((error: unknown) => {
+      if (sandboxFactoryCache.get(config)?.promise === promise) {
+        sandboxFactoryCache.delete(config);
+      }
+      throw error;
+    });
+  sandboxFactoryCache.set(config, { sandbox, promise });
+  return promise;
 }
 
 async function getRuntimeContext(
@@ -687,6 +709,39 @@ function createCloudflareSpawn(
   };
 }
 
+/**
+ * Returns one stable filesystem/process world for a Cloudflare configuration.
+ * Probe caches key on the spawn identity, so retaining it avoids repeating
+ * remote capability checks whenever an agent binding rebuilds its tools.
+ */
+export function createCloudflareExecutionWorld(
+  config: t.CloudflareSandboxExecutionConfig
+): t.ExecutionWorld {
+  const workspaceRoot = getCloudflareWorkspaceRoot(config);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const cached = executionWorldCache.get(config);
+  if (
+    cached?.workspaceRoot === workspaceRoot &&
+    Object.is(cached.timeoutMs, timeoutMs) &&
+    cached.sandbox === config.sandbox
+  ) {
+    return cached.world;
+  }
+  const fs = Object.freeze(createCloudflareWorkspaceFS(config));
+  const world = Object.freeze({
+    spawn: createCloudflareSpawn(config),
+    fs,
+    sandboxed: true,
+  });
+  executionWorldCache.set(config, {
+    world,
+    workspaceRoot,
+    timeoutMs,
+    sandbox: config.sandbox,
+  });
+  return world;
+}
+
 export function createCloudflareLocalExecutionConfig(
   config: t.CloudflareSandboxExecutionConfig
 ): t.LocalExecutionConfig {
@@ -694,11 +749,7 @@ export function createCloudflareLocalExecutionConfig(
   return {
     cwd: workspaceRoot,
     workspace: { root: workspaceRoot },
-    exec: {
-      spawn: createCloudflareSpawn(config),
-      fs: createCloudflareWorkspaceFS(config),
-      sandboxed: true,
-    },
+    exec: createCloudflareExecutionWorld(config),
     shell: config.shell ?? 'bash',
     timeoutMs: config.timeoutMs,
     maxOutputChars: config.maxOutputChars,

package/src/tools/cloudflare/CloudflareSandboxTools.ts

@@ -2,8 +2,8 @@ import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import {
+  createCloudflareExecutionWorld,
   createCloudflareLocalExecutionConfig,
-  createCloudflareWorkspaceFS,
   executeCloudflareBash,
   executeCloudflareCode,
   formatCloudflareOutput,
@@ -161,7 +161,7 @@ export function createCloudflareCodingTools(
     options.checkpointer ??
     (config.fileCheckpointing === true
       ? createLocalFileCheckpointer({
-        fs: createCloudflareWorkspaceFS(config),
+        fs: createCloudflareExecutionWorld(config).fs,
       })
       : undefined);
   const tools = [
@@ -193,11 +193,12 @@ export function createCloudflareCodingToolBundle(
   config: t.CloudflareSandboxExecutionConfig,
   options: { checkpointer?: t.LocalFileCheckpointer } = {}
 ): CloudflareCodingToolBundle {
+  const world = createCloudflareExecutionWorld(config);
   const checkpointer =
     options.checkpointer ??
     (config.fileCheckpointing === true
       ? createLocalFileCheckpointer({
-        fs: createCloudflareWorkspaceFS(config),
+        fs: world.fs,
       })
       : undefined);
   return {

package/src/tools/local/LocalCodingTools.ts

@@ -4,16 +4,19 @@ import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import {
-  createLocalBashProgrammaticToolCallingTool,
-  createLocalProgrammaticToolCallingTool,
-} from './LocalProgrammaticToolCalling';
-import {
+  commandAvailabilityEnvCacheKey,
   getSpawn,
   getWorkspaceFS,
+  probeLocalCommandAvailability,
   resolveWorkspacePathSafe,
+  setCommandAvailabilityCacheEntry,
   spawnLocalProcess,
   truncateLocalOutput,
 } from './LocalExecutionEngine';
+import {
+  createLocalBashProgrammaticToolCallingTool,
+  createLocalProgrammaticToolCallingTool,
+} from './LocalProgrammaticToolCalling';
 import {
   createLocalBashExecutionTool,
   createLocalCodeExecutionTool,
@@ -736,30 +739,14 @@ export function createLocalEditFileTool(
  * spawn-per-search.
  */
 // Per-backend × per-env cache. Codex P1 #34 — keying by spawn
-// backend alone misses the case where two Runs share a backend but
-// vary `local.env` (especially PATH). Stale cache then claims `rg`
-// is available, the rg path runs, and the spawn fails with ENOENT
-// instead of falling back to the Node walker. The inner Map is
-// keyed by a stable JSON hash of the effective env so each unique
-// env gets its own probe.
+// backend alone misses the case where two Runs share a backend but vary
+// `local.env`. The inner map uses non-plaintext environment hashes and is
+// bounded so stable worlds do not retain unbounded variants or raw secrets.
 let ripgrepAvailabilityByBackend = new WeakMap<
   t.LocalSpawn,
-  Map<string, Promise<boolean>>
+  Map<string, ReturnType<typeof probeLocalCommandAvailability>>
 >();
 
-function envCacheKey(env: NodeJS.ProcessEnv | undefined): string {
-  // PATH is the only env entry that affects command lookup, but
-  // hashing the whole env keeps the key correct for hosts that
-  // vary anything else relevant. Stable JSON via sorted keys so
-  // {A:1,B:2} and {B:2,A:1} produce the same hash.
-  if (env == null) return '';
-  const sorted: Record<string, string | undefined> = {};
-  for (const k of Object.keys(env).sort()) {
-    sorted[k] = env[k];
-  }
-  return JSON.stringify(sorted);
-}
-
 async function isRipgrepAvailable(
   config: t.LocalExecutionConfig
 ): Promise<boolean> {
@@ -769,20 +756,23 @@ async function isRipgrepAvailable(
     envMap = new Map();
     ripgrepAvailabilityByBackend.set(backend, envMap);
   }
-  const envKey = envCacheKey(config.env);
+  const envKey = commandAvailabilityEnvCacheKey(config.env);
   let probePromise = envMap.get(envKey);
   if (probePromise == null) {
-    probePromise = spawnLocalProcess(
-      'rg',
-      ['--version'],
-      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
-      { internal: true }
-    )
-      .then((probe) => probe.exitCode === 0)
-      .catch(() => false);
-    envMap.set(envKey, probePromise);
+    probePromise = probeLocalCommandAvailability('rg', ['--version'], config);
+    setCommandAvailabilityCacheEntry(envMap, envKey, probePromise);
+  }
+  const result = await probePromise;
+  if (!result.cacheable && envMap.get(envKey) === probePromise) {
+    envMap.delete(envKey);
+  }
+  if (result.cacheUntil != null && result.cacheUntil <= Date.now()) {
+    if (envMap.get(envKey) === probePromise) {
+      envMap.delete(envKey);
+    }
+    return isRipgrepAvailable(config);
   }
-  return probePromise;
+  return result.available;
 }
 
 /**

package/src/tools/local/LocalExecutionEngine.ts

@@ -21,6 +21,36 @@ const DEFAULT_MAX_OUTPUT_CHARS = 200000;
 const DEFAULT_MAX_SPAWNED_BYTES = 50 * 1024 * 1024;
 const DEFAULT_LOCAL_SESSION_ID = 'local';
 const DEFAULT_SHELL = process.platform === 'win32' ? 'bash.exe' : 'bash';
+const MAX_COMMAND_AVAILABILITY_ENVIRONMENTS = 16;
+const NEGATIVE_COMMAND_AVAILABILITY_TTL_MS = 5000;
+
+/** Produces a stable, non-plaintext key for environment-sensitive probes. */
+export function commandAvailabilityEnvCacheKey(
+  env: NodeJS.ProcessEnv | undefined
+): string {
+  if (env == null) {
+    return '';
+  }
+  const sorted = Object.keys(env)
+    .sort()
+    .map((key): [string, string | null] => [key, env[key] ?? null]);
+  return createHash('sha256').update(JSON.stringify(sorted)).digest('hex');
+}
+
+/** Adds a probe entry while bounding retained environment variants. */
+export function setCommandAvailabilityCacheEntry<T>(
+  cache: Map<string, T>,
+  key: string,
+  value: T
+): void {
+  if (!cache.has(key) && cache.size >= MAX_COMMAND_AVAILABILITY_ENVIRONMENTS) {
+    const oldestKey = cache.keys().next().value;
+    if (oldestKey !== undefined) {
+      cache.delete(oldestKey);
+    }
+  }
+  cache.set(key, value);
+}
 
 // `(?:--\s+)?` before each destructive-target alternation: GNU/BSD
 // utilities accept `--` as an end-of-options marker, so `rm -rf -- /`
@@ -259,13 +289,34 @@ export function getWorkspaceRoots(config?: t.LocalExecutionConfig): string[] {
   return out;
 }
 
+/** Node-host execution world used when no backend override is configured. */
+export const nodeExecutionWorld: t.ExecutionWorld = Object.freeze({
+  spawn: spawn as t.LocalSpawn,
+  fs: nodeWorkspaceFS,
+  sandboxed: false,
+});
+
+/** Resolves filesystem and subprocess capabilities as one execution world. */
+export function getExecutionWorld(
+  config?: t.LocalExecutionConfig
+): t.ExecutionWorld {
+  if (config?.exec == null && config?.spawn == null) {
+    return nodeExecutionWorld;
+  }
+  return {
+    spawn: config.exec?.spawn ?? config.spawn ?? nodeExecutionWorld.spawn,
+    fs: config.exec?.fs ?? nodeExecutionWorld.fs,
+    sandboxed: config.exec?.sandboxed ?? false,
+  };
+}
+
 /**
  * Pluggable spawn resolver. Honours `local.exec.spawn` first, falls
  * back to the legacy top-level `local.spawn`, then to Node's
  * `child_process.spawn`. Centralised so engine swapping is one knob.
  */
 export function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn {
-  return (config?.exec?.spawn ?? config?.spawn ?? spawn) as t.LocalSpawn;
+  return getExecutionWorld(config).spawn;
 }
 
 /**
@@ -274,7 +325,7 @@ export function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn {
  * its own implementation here and inherits every file-touching tool.
  */
 export function getWorkspaceFS(config?: t.LocalExecutionConfig): WorkspaceFS {
-  return config?.exec?.fs ?? nodeWorkspaceFS;
+  return getExecutionWorld(config).fs;
 }
 
 /**
@@ -345,7 +396,7 @@ function maybeWarnSandboxOff(config: t.LocalExecutionConfig): void {
   if (
     sandboxOffWarned ||
     shouldUseLocalSandbox(config) ||
-    config.exec?.sandboxed === true
+    getExecutionWorld(config).sandboxed
   ) {
     return;
   }
@@ -904,6 +955,72 @@ export async function spawnLocalProcess(
   });
 }
 
+/** Result of a command-availability probe and whether its verdict is stable. */
+export type CommandAvailabilityProbe = {
+  available: boolean;
+  cacheable: boolean;
+  cacheUntil?: number;
+};
+
+async function isDurableCommandLookupError(
+  error: object,
+  config: t.LocalExecutionConfig
+): Promise<boolean> {
+  if (!('code' in error) || error.code !== 'ENOENT') {
+    return false;
+  }
+  try {
+    const cwd = getLocalCwd(config);
+    return (await getWorkspaceFS(config).stat(cwd)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Probes one executable without turning transient backend failures into
+ * permanent capability facts. Exit 126/127 is a definite unusable/missing
+ * executable. A native ENOENT is stable only when the current working
+ * directory exists; timeouts, transport failures, and ambiguous lookup
+ * failures are retried.
+ */
+export async function probeLocalCommandAvailability(
+  command: string,
+  args: string[],
+  config: t.LocalExecutionConfig
+): Promise<CommandAvailabilityProbe> {
+  try {
+    const result = await spawnLocalProcess(
+      command,
+      args,
+      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
+      { internal: true }
+    );
+    const available = result.exitCode === 0;
+    const durableNegative =
+      result.exitCode === 126 || result.exitCode === 127;
+    return {
+      available,
+      cacheable: available || durableNegative,
+      ...(durableNegative
+        ? { cacheUntil: Date.now() + NEGATIVE_COMMAND_AVAILABILITY_TTL_MS }
+        : {}),
+    };
+  } catch (error) {
+    const cacheable =
+      typeof error === 'object' &&
+      error != null &&
+      (await isDurableCommandLookupError(error, config));
+    return {
+      available: false,
+      cacheable,
+      ...(cacheable
+        ? { cacheUntil: Date.now() + NEGATIVE_COMMAND_AVAILABILITY_TTL_MS }
+        : {}),
+    };
+  }
+}
+
 export async function executeLocalBash(
   command: string,
   config: t.LocalExecutionConfig = {}