jeo-code 0.12.16 → 0.12.18

package/src/agent/sandbox/supervisor.ts

@@ -162,20 +162,29 @@ export function createSandboxSupervisor(options: { policy: SandboxPolicy; backen
     return effect.result.promise;
   }
 
+  /** A Windows host path that matches no mount is not "relative" to the Linux guest; it must never be forwarded. */
   function guestPath(value: string): string {
-    if (!path.isAbsolute(value)) return value;
-    const mount = [...policy.mounts].sort((a, b) => b.host.length - a.host.length).find(item => sandboxPathContains(item.host, value));
-    if (!mount) return value;
-    const relative = path.relative(mount.host, value).split(path.sep).join("/");
-    return relative ? `${mount.guest}/${relative}` : mount.guest;
+    const mount = path.isAbsolute(value) ? [...policy.mounts].sort((a, b) => b.host.length - a.host.length).find(item => sandboxPathContains(item.host, value)) : undefined;
+    if (mount) {
+      const relative = path.relative(mount.host, value).split(path.sep).join("/");
+      return relative ? `${mount.guest}/${relative}` : mount.guest;
+    }
+    if (process.platform === "win32" && /^(?:[A-Za-z]:|[\\/]{2}|\\)/.test(value)) throw new Error("SANDBOX_POLICY: host path is outside approved mounts");
+    return value;
   }
 
   function call(tool: string, args: Record<string, unknown>, callOptions?: SandboxCallOptions): Promise<ToolResult> {
     const mapped = { ...args };
-    for (const key of ["filePath", "path", "dirPath", "dir", "targetPath", "cwd", "subdir"]) {
-      if (typeof mapped[key] === "string") mapped[key] = guestPath(mapped[key]);
+    let cwd: string | undefined;
+    try {
+      for (const key of ["filePath", "path", "dirPath", "dir", "targetPath", "cwd", "subdir"]) {
+        if (typeof mapped[key] === "string") mapped[key] = guestPath(mapped[key]);
+      }
+      if (callOptions?.cwd) cwd = guestPath(callOptions.cwd);
+    } catch (error) {
+      return Promise.resolve({ success: false, output: "", error: error instanceof Error ? error.message : String(error) });
     }
-    return enqueue({ id: crypto.randomUUID(), type: "tool", tool: tool === "approve" ? "__plan_approve" : tool, args: mapped, ...(callOptions?.cwd ? { cwd: guestPath(callOptions.cwd) } : {}) }, callOptions);
+    return enqueue({ id: crypto.randomUUID(), type: "tool", tool: tool === "approve" ? "__plan_approve" : tool, args: mapped, ...(cwd ? { cwd } : {}) }, callOptions);
   }
 
   return {
@@ -184,7 +193,10 @@ export function createSandboxSupervisor(options: { policy: SandboxPolicy; backen
       return Object.fromEntries(names.map(name => [name, (args: Record<string, unknown>, cwd: string, onProgress?: (text: string) => void) => call(name, args, { cwd, onProgress })]));
     },
     exec(argv: readonly string[], execOptions: SandboxExecOptions = {}): Promise<SandboxExecResult> {
-      return enqueue({ id: crypto.randomUUID(), type: "exec", argv: [...argv], ...(execOptions.cwd ? { cwd: guestPath(execOptions.cwd) } : {}), ...(execOptions.env ? { env: execOptions.env } : {}), ...(execOptions.stdin !== undefined ? { stdin: execOptions.stdin } : {}) }, { signal: execOptions.signal });
+      let cwd: string | undefined;
+      try { if (execOptions.cwd) cwd = guestPath(execOptions.cwd); }
+      catch (error) { return Promise.resolve({ success: false, output: "", error: error instanceof Error ? error.message : String(error) }); }
+      return enqueue({ id: crypto.randomUUID(), type: "exec", argv: [...argv], ...(cwd ? { cwd } : {}), ...(execOptions.env ? { env: execOptions.env } : {}), ...(execOptions.stdin !== undefined ? { stdin: execOptions.stdin } : {}) }, { signal: execOptions.signal });
     },
     async replacePolicy(next): Promise<void> {
       if (state === "closed" || state === "changing" || next.sessionKey !== policy.sessionKey || next.revision <= policy.revision) throw new Error("SANDBOX_POLICY: closed, changing or invalid policy revision");

package/src/agent/session-model.ts

@@ -0,0 +1,84 @@
+/**
+ * Session-start model resolution against the models jeo is actually logged in to.
+ *
+ * A session opens on the configured default model. That default is honored only
+ * when the stored login can serve it; otherwise the first turn would fail with
+ * "No credential for provider …" even though another logged-in model works. In that
+ * case the session starts on the first authenticated candidate (recents, then role
+ * tiers) and says so. The saved config is never rewritten here: the fallback is
+ * session-local, so the configured default is untouched.
+ *
+ * Fail-open: a probe that throws keeps the configured default.
+ */
+import { describeModel, modelServableWithConfig } from "../ai/model-manager";
+import { describeProvider } from "../ai/provider-status";
+import { customProviderDef } from "../ai/providers/custom-providers";
+import type { Config } from "./state";
+
+export type ModelAuthCheck = (model: string, cfg: Config) => Promise<boolean>;
+
+export interface StartupModel {
+  /** The model the session should treat as its default. */
+  model: string;
+  /** The configured default this replaced, when no login could serve it. */
+  fellBackFrom?: string;
+  /** One-line explanation for the user, present only when a fallback happened. */
+  notice?: string;
+}
+
+/**
+ * Whether jeo's stored credentials can serve `model` right now. Same two gates
+ * routing uses: the provider has a live credential, and, for built-in providers,
+ * that credential serves this specific model (ChatGPT OAuth serves only Codex ids).
+ * agy runs as an external CLI session and custom providers resolve their own key,
+ * so for those only provider readiness applies. Local providers are keyless.
+ */
+export const isModelAuthenticated: ModelAuthCheck = async (model, cfg) => {
+  const { resolved, provider } = await describeModel(model, cfg);
+  const status = await describeProvider(provider, cfg);
+  if (!status.ready) return false;
+  if (provider === "agy" || customProviderDef(provider)) return true;
+  return modelServableWithConfig(provider, resolved, cfg);
+};
+
+const FALLBACK_ROLES = ["medium", "high", "smol", "xhigh", "slow", "plan"] as const;
+
+/** Fallback order: the user's recently picked models, then their configured role tiers. */
+function fallbackCandidates(cfg: Config): string[] {
+  const ordered = [...(cfg.recentModels ?? []), ...FALLBACK_ROLES.map(role => cfg.roles?.[role])];
+  const seen = new Set<string>([cfg.defaultModel]);
+  const out: string[] = [];
+  for (const model of ordered) {
+    if (typeof model !== "string" || !model.trim() || seen.has(model)) continue;
+    seen.add(model);
+    out.push(model);
+  }
+  return out;
+}
+
+/**
+ * Resolve the model a new session should open on: the configured default when the
+ * login serves it, else the first authenticated fallback, else the configured
+ * default unchanged (the first turn then reports the real credential error).
+ */
+export async function resolveStartupDefaultModel(cfg: Config, check: ModelAuthCheck = isModelAuthenticated): Promise<StartupModel> {
+  const configured = cfg.defaultModel;
+  try {
+    if (await check(configured, cfg)) return { model: configured };
+  } catch {
+    return { model: configured };
+  }
+  for (const candidate of fallbackCandidates(cfg)) {
+    let ok = false;
+    try { ok = await check(candidate, cfg); } catch { ok = false; }
+    if (!ok) continue;
+    let provider = "its provider";
+    try { provider = (await describeModel(configured, cfg)).provider; } catch { /* keep the generic wording */ }
+    return {
+      model: candidate,
+      fellBackFrom: configured,
+      notice: `[model] default '${configured}' has no usable ${provider} login; this session starts on authenticated '${candidate}'. Run 'jeo auth login ${provider}' to restore it, or /model to pick another.`,
+    };
+  }
+  return { model: configured };
+}

package/src/agent/shell-lease.ts

@@ -33,6 +33,7 @@
  */
 import * as cp from "node:child_process";
 import * as fs from "node:fs";
+import { resolvePosixTool } from "../util/posix-tools";
 import * as os from "node:os";
 import * as path from "node:path";
 import { Readable } from "node:stream";
@@ -96,7 +97,7 @@ export function spawnLeasedShell(command: string, cwd: string): LeasedShell {
 }
 
 function spawnDirect(command: string, cwd: string): LeasedShell {
-  const proc = Bun.spawn(["bash", "-c", command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  const proc = Bun.spawn([resolvePosixTool("bash"), "-c", command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
   const stdout = proc.stdout.getReader();
   const stderr = proc.stderr.getReader();
   const reaped = proc.exited.then(() => undefined);

package/src/agent/task-tool.ts

@@ -467,6 +467,7 @@ export async function runSubagentOnce(
   const failoverEnabled = !!opts.config.routing?.enabled;
   let activeModel = initialModel;
   emit({ role: role.id, kind: "start", detail: taskText, maxSteps, model: activeModel });
+  let contractCorrections = 0;
   const runOnce = () => {
     return runAgentLoop(history, {
       cwd,
@@ -474,14 +475,27 @@ export async function runSubagentOnce(
       maxSteps,
       maxTokens: resolveMaxOutputTokens(activeModel, thinking),
       sessionKey,
-      // Bounded delegation: a subagent's step contract stays exact — the parent
-      // owns any retry/extension decision, so the gjc retry flow is disabled here.
-      budget: { maxExtensions: 0 },
+      // Allow bounded step-budget extensions when a subagent is actively making
+      // progress so multi-file edits + test verification do not get cut off mid-run.
+      budget: { maxExtensions: role.readOnly ? 1 : 2 },
       signal,
       steer,
       tools: subagentToolset(role),
       ...(failoverEnabled ? { rateLimitFallbackAvailable, safetyFallbackAvailable } : {}),
       events: {
+        onBeforeDone: reason => {
+          const hasToolActivity = fileMutations > 0 || bashRuns > 0 || readOnlyEvidenceCalls > 0;
+          if (!hasToolActivity || contractCorrections >= 1) return null;
+          const check = validateSubagentDoneReason(role, reason);
+          if (!check.ok) {
+            contractCorrections++;
+            return (
+              `Your done.reason is missing required section(s) for ${role.title}: ${check.missing?.join(", ")}. ` +
+              `Call done again with non-empty content under every required section header.`
+            );
+          }
+          return null;
+        },
         onEvidence: evidence => {
           if (evidence.sawMutation) mutationMayHaveOccurred = true;
         },

package/src/agent/tools.ts

@@ -1,4 +1,5 @@
 import { applyBashFixups } from "./bash-fixups";
+import { resolvePosixTool } from "../util/posix-tools";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { readWorkflowStateStrict, type WorkflowState } from "./state";
@@ -727,7 +728,7 @@ export async function bashTool(
     const reapBackground = isBackgroundReapEnabled();
     const grouped = reapBackground && process.platform !== "win32";
     if (grouped) ensureBackgroundSweeper();
-    const proc = Bun.spawn(["bash", "-c", command], {
+    const proc = Bun.spawn([resolvePosixTool("bash"), "-c", command], {
       cwd: runCwd,
       // Detach stdin (no inherited TTY): a command that reads stdin (`cat`, `read`,
       // a REPL, an interactive prompt) then gets immediate EOF and exits instead of

package/src/commands/launch/input.ts

@@ -439,7 +439,7 @@ export function captureLivePromptInputChunk(
       const plain = start === -1 ? rest : rest.slice(0, start);
       if (start !== -1) state.inPaste = true;
       rest = start === -1 ? "" : rest.slice(start + PASTE_START.length);
-      if (feedLivePromptSegment(state, plain)) accepted = true;
+      if (feedLivePromptSegment(state, decodeExtendedKeys(stripMouseReports(plain)))) accepted = true;
     }
   }
   return accepted;
@@ -506,10 +506,17 @@ export function createInFlightAbortHarness(opts: AbortHarnessOptions = {}): InFl
       opts.onBufferedInput?.(raw);
       return;
     }
+    // Strip mouse reports and terminal capability replies (OSC/CSI device attributes)
+    // first so terminal responses arriving mid-turn never leak into the live draft.
+    const stripped = stripMouseReports(raw);
+    if (!stripped && raw.length > 0) {
+      opts.onNoise?.();
+      return;
+    }
     // Kitty/modifyOtherKeys re-encodings → legacy bytes FIRST, so Esc (`CSI 27u`) and
     // Ctrl+C (`CSI 99;5u` / `CSI 27;5;99~`) cancel a live turn on every terminal —
     // previously they fell into the "noise" branch and did NOTHING mid-turn.
-    const text = decodeExtendedKeys(raw);
+    const text = decodeExtendedKeys(stripped);
     if (text === "\u000f") {
       opts.onDetailKey?.();
       return;
@@ -579,7 +586,22 @@ export function classifyMidTurnLine(line: string): "command" | "steer" | "empty"
   // A lone sigil ("/" or "$") has no command name — ignore it instead of aborting the
   // running turn to dispatch an empty command (a stray slash should not interrupt work).
   if (t === "/" || t === "$") return "empty";
-  return /^[/$]/.test(t) ? "command" : "steer";
+  const firstToken = t.split(/\s+/, 1)[0] ?? "";
+  if (firstToken.startsWith("/")) {
+    // A slash command is a single leading token (/model, /help, /?); a token containing
+    // additional slashes (/Users/foo/bar, /tmp/a.ts, //comment) is a path or comment,
+    // never a REPL command that should abort the running turn.
+    const name = firstToken.slice(1);
+    if (!name || name.includes("/")) return "steer";
+    return /^[a-zA-Z?][a-zA-Z0-9_-]*$/.test(name) ? "command" : "steer";
+  }
+  if (firstToken.startsWith("$")) {
+    // A skill invocation starts with a skill identifier ($team, $ralplan), not a
+    // numeric dollar amount ($100) or path ($/foo).
+    const name = firstToken.slice(1);
+    return /^[a-zA-Z][a-zA-Z0-9_:-]*$/.test(name) ? "command" : "steer";
+  }
+  return "steer";
 }
 /** Default window (ms) over which the several delivery paths of ONE physical Ctrl+C
  *  press — readline 'keypress', the rl/process 'SIGINT' event, and the raw \u0003 stdin

package/src/commands/launch/session-slash.ts

@@ -188,8 +188,6 @@ export async function runSessionSlash(input: string, ctx: SessionSlashCtx): Prom
         history.length = 1;
         for (const m of messages) history.push(m);
         sessionId = rid;
-        // Restore the model this session was last using (per-session model).
-        if (header.model) { sessionModel = header.model; sessionModelChanged = true; }
         // Restore the unsent input-box draft left over at last save, if any.
         if (header.draft) draft = header.draft;
 

package/src/commands/launch.ts

@@ -66,6 +66,7 @@ import type { SandboxConfig, SandboxSupervisor } from "../agent/sandbox/types";
 import { runAgySessionTurn } from "./launch/agy-turn";
 import { listProviderModels } from "../ai/model-discovery";
 import { rememberModelPatch, recentModelsForDisplay } from "../agent/model-recency";
+import { resolveStartupDefaultModel } from "../agent/session-model";
 import { describeModel, describeAllProviders, describeProvider, resolveProvider, thinkingMaxTokens, resolveMaxOutputTokens, thinkingToReasoningEffort, discoverModels, flattenModels, resolveSelection, catalogMetadata, catalogByProvider, liveProviderCatalogModels, resolveRoleModel, CODEX_MODELS, qualifyModelId, modelServableWithConfig, isLocalProviderReachable } from "../ai";
 import { rehydrateLiveModels, writeModelCache } from "../ai/model-cache";
 import type { ProviderModelsResult, PickEntry, ProviderName, ModelRole, ThinkLevel } from "../ai";
@@ -544,7 +545,6 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
     }
   } catch {}
   const cfg = await readGlobalConfig();
-  const defaultModel = cfg.defaultModel;
   let initialSessionModel =
     flags.model ??
     (flags.modelRole ? resolveRoleModel(flags.modelRole, cfg) : flags.provider ? providerDefaultModel(flags.provider) : undefined);
@@ -564,6 +564,11 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
       return;
     }
   }
+  // A session always opens on the configured default model, or, when the stored login cannot
+  // serve it, on the first authenticated model (session-local; the saved default is untouched).
+  // An explicit --model/--model-role/--provider pin takes precedence and skips this.
+  const startupModel = initialSessionModel === undefined ? await resolveStartupDefaultModel(cfg) : { model: cfg.defaultModel, notice: undefined };
+  const defaultModel = startupModel.model;
 
   if (flags.tmux) {
     if (!process.env.TMUX && jeoEnv("TMUX_LAUNCHED") !== "1") {
@@ -987,7 +992,6 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
             const { header, messages } = await loadSession(id, cwd);
             for (const m of messages) history.push(m);
             sessionId = id;
-            if (!initialSessionModel && header.model) sessionModel = header.model;
             const modelNote = sessionModel ? ` · model ${sessionModel}` : "";
             console.log(`Resumed session ${id} (${messages.length} messages).${modelNote}`);
             // Reproduce the prior screen exactly (gjc/gajae-code parity): a bare
@@ -1049,9 +1053,6 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
           const { header, messages } = await loadSession(id, cwd);
           for (const m of messages) history.push(m);
           sessionId = id;
-          // Restore the model this session was last using unless the CLI explicitly
-          // pinned one (flags.model/role/provider → initialSessionModel wins).
-          if (!initialSessionModel && header.model) sessionModel = header.model;
           // Restore the unsent input-box draft (gajae-code parity) — see
           // startupDraft's own doc comment for why this path can't feed
           // queuedPromptInput.partial directly yet.
@@ -1967,7 +1968,7 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
           if ((pendingMutationVerification || evidence.sawMutation) && !(evidence.sawVerification && !evidence.verificationStale)) {
             return (
               `Cannot finish: a workspace mutation from this session still lacks a successful, non-stale verification. ` +
-              `Run a relevant test/build/typecheck/lint after the last change, then call done again.`
+              `Run a relevant test/build/typecheck/lint after the last change (e.g. 'bun test', 'bun run typecheck', 'tsc --noEmit', 'npm test', 'pytest', 'cargo test', or 'go test ./...'), then call done again.`
             );
           }
 
@@ -2497,6 +2498,7 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
   };
 
   if (isOneShot) {
+    if (startupModel.notice) console.error(startupModel.notice);
     // A one-shot run has ~17 exit points below. The session notify endpoint (a
     // listening socket + a discovery file the Telegram daemon polls) is created for
     // the WHOLE launch lifetime up at `startSessionNotifyEndpoint`, but its teardown
@@ -2843,6 +2845,7 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
     if (sweepable) await playWelcomeSweep(welcomeData, { cycles: sweepCycles });
     else console.log(renderWelcome(welcomeData).join("\n"));
   }
+  if (startupModel.notice) console.log(chalk.yellow(startupModel.notice));
 
 
 
@@ -3177,7 +3180,14 @@ async function runLaunchSession(args: string[], registerEndpointCleanup?: (clean
   queueBusySnapshot = () => ({
     text: queuedPromptInput.partial,
   });
-  queueBusyClear = () => { queuedPromptInput.partial = ""; };
+  queueBusyClear = () => {
+    queuedPromptInput.partial = "";
+    const r = rl as unknown as { line?: string; cursor?: number };
+    if (typeof r.line === "string") {
+      r.line = "";
+      r.cursor = 0;
+    }
+  };
   queueBusyCommand = (line: string) => {
     // NO_MIDTURN_DISPATCH=1 keeps the legacy prefill path (tee up, press Enter); the
     // default routes to the immediate-dispatch queue served at the top of the loop.

package/src/commands/ralplan.ts

@@ -80,15 +80,28 @@ export async function runConsensusCriticGate(args: {
   // is gated the SAME way: zero observed read/search/find/ast_grep/lsp calls means
   // the [OKAY]/[ITERATE]/[REJECT] text is unevidenced regardless of what it claims.
   let evidenceCalls = 0;
+  let contractCorrections = 0;
   const runOnce = () => runAgentLoop(history, {
     cwd: args.cwd,
     model: activeModel,
     maxSteps,
-    budget: { maxExtensions: 0 },
+    budget: { maxExtensions: 1 },
     signal: args.signal,
     tools: subagentToolset(role),
     rateLimitFallbackAvailable,
     events: {
+      onBeforeDone: reason => {
+        if (evidenceCalls === 0 || contractCorrections >= 1) return null;
+        const check = validateSubagentDoneReason(role, reason);
+        if (!check.ok) {
+          contractCorrections++;
+          return (
+            `Your critic report is missing required section(s): ${check.missing?.join(", ")}. ` +
+            `Call done again starting with [OKAY], [ITERATE], or [REJECT] and include a non-empty 'Justification:' section.`
+          );
+        }
+        return null;
+      },
       onToolResult: (tool, success) => {
         if (success && (tool === "read" || tool === "search" || tool === "find" || tool === "ast_grep" || tool === "lsp")) evidenceCalls++;
       },

package/src/prompts/AGENTS.md

@@ -23,7 +23,7 @@ Bundled system prompts, role definitions, and workflow skill documentation for t
 - Do not remove existing constraints without explicit reason.
 
 ### Testing Requirements
-- Prompt changes should be verified via end-to-end testing or `bun run run-evolution.sh`.
+- Prompt changes should be verified via end-to-end testing.
 
 ### Common Patterns
 - XML-like tags for structural organization within prompts.

package/src/util/posix-tools.ts

@@ -0,0 +1,66 @@
+/**
+ * POSIX tool resolution for Windows hosts.
+ *
+ * `Bun.spawn(["bash"|"grep"|"find", …])` resolves from PATH, where Windows
+ * ships imposters ahead of Git for Windows:
+ *  - `C:\Windows\System32\bash.exe` launches WSL — Windows paths
+ *    (`C:\Users\…`) do not exist inside it and caller env vars are dropped.
+ *  - `C:\Windows\System32\find.exe` is the legacy DOS FIND (substring
+ *    filter), not POSIX find.
+ *
+ * Resolve to real Git for Windows binaries instead, with an env override.
+ * Non-Windows platforms pass the bare name through unchanged.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export type PosixTool = "bash" | "grep" | "find";
+
+export interface ResolveOptions {
+  /** Platform override for tests (default: process.platform). */
+  readonly platform?: NodeJS.Platform;
+  /** Env override for tests (default: process.env). */
+  readonly env?: Record<string, string | undefined>;
+  /** File-existence probe override for tests (default: fs.existsSync). */
+  readonly exists?: (p: string) => boolean;
+}
+
+/** Candidate absolute paths for a tool, in preference order. */
+export function candidatePaths(
+  tool: PosixTool,
+  env: Record<string, string | undefined>
+): string[] {
+  const override = env[`JOC_${tool.toUpperCase()}_PATH`];
+  const roots = [
+    env["ProgramFiles"] && path.join(env["ProgramFiles"], "Git"),
+    env["ProgramFiles(x86)"] && path.join(env["ProgramFiles(x86)"], "Git"),
+    env["LOCALAPPDATA"] && path.join(env["LOCALAPPDATA"], "Programs", "Git"),
+  ].filter((r): r is string => Boolean(r));
+  // bash lives in both bin/ and usr/bin/; grep/find only in usr/bin/.
+  const subdirs = tool === "bash" ? ["bin", path.join("usr", "bin")] : [path.join("usr", "bin")];
+  return [
+    ...(override ? [override] : []),
+    ...roots.flatMap(root => subdirs.map(sub => path.join(root, sub, `${tool}.exe`))),
+  ];
+}
+
+const cache = new Map<PosixTool, string>();
+
+/**
+ * Resolve `tool` to a Unix-semantics executable. Returns an absolute Git
+ * for Windows path when found, otherwise the bare name (PATH fallback).
+ */
+export function resolvePosixTool(tool: PosixTool, opts: ResolveOptions = {}): string {
+  const platform = opts.platform ?? process.platform;
+  if (platform !== "win32") return tool;
+  const injected = opts.env || opts.exists;
+  if (!injected) {
+    const hit = cache.get(tool);
+    if (hit) return hit;
+  }
+  const env = opts.env ?? process.env;
+  const exists = opts.exists ?? existsSync;
+  const found = candidatePaths(tool, env).find(c => exists(c)) ?? tool;
+  if (!injected) cache.set(tool, found);
+  return found;
+}