@duckmind/dm-linux-x64 0.63.9 → 0.64.2

package/extensions/dm-lens/clients/dispatch/runners/utils/runner-helpers.js

@@ -0,0 +1,1078 @@
+var __dirname = "/Users/que/Projects/dm/dm-mono/packages/coding-agent/dist/extensions/dm-lens/clients/dispatch/runners/utils";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { logSessionStart } from "../../../sessionstart-logger.js";
+import { incrementDegradationCount } from "../../../degradation-ledger.js";
+import { getGlobalDmLensDir } from "../../../file-utils.js";
+import {
+  createGenerationSource
+} from "../../../generation-guard.js";
+import { PathKeyedMap } from "../../../path-keyed-map.js";
+import {
+  normalizeEphemeralMapKey,
+  normalizeMapKey
+} from "../../../path-utils.js";
+import {
+  ensureTool,
+  getInstallAttempt,
+  getLastEnsureResolutionSource,
+  getToolInstallStrategy,
+  isSpawnableCommand,
+  resetPathWalkMemo
+} from "../../../installer/index.js";
+import {
+  getServersForFileWithConfig,
+  isServerDisabled
+} from "../../../lsp/config.js";
+import {
+  findGlobalBinary,
+  findLocalBinAt,
+  findLocalBinsUpwards,
+  findLocalBinUpwards,
+  VENDOR_BIN_DIRS,
+  VENV_BIN_DIRS
+} from "../../../package-manager.js";
+import { logLatency } from "../../../latency-logger.js";
+import { safeSpawnAsync } from "../../../safe-spawn.js";
+import { compareOrdinal } from "../../../string-utils.js";
+import {
+  getToolCommandSpec,
+  shouldAutoInstallTool
+} from "../../../tool-policy.js";
+import { isInSpawnTimeoutCooldown } from "../../../spawn-timeout-cooldown.js";
+import { createAvailabilityProbeFlight } from "../../../availability-probe-flight.js";
+import {
+  classifyProbeFailure,
+  createAvailabilityLatch,
+  describeInstallAttempt,
+  describeProbeEvidence,
+  isLatchingOutcome,
+  logAvailabilityDecision,
+  startHostStallSampler,
+  transientRetryDelayMs
+} from "./availability-policy.js";
+export {
+  createAvailabilityLatch,
+  classifyProbeFailure,
+  describeProbeEvidence,
+  describeUnavailability,
+  isTransientDecision,
+  logAvailabilityDecision,
+  startHostStallSampler
+} from "./availability-policy.js";
+export function lspPrimaryCoversFile(ctx, serverId) {
+  if (ctx.pi?.getFlag?.("no-lsp"))
+    return false;
+  if (isServerDisabled(serverId, ctx.filePath))
+    return false;
+  const primary = getServersForFileWithConfig(ctx.filePath).find((s) => s.role !== "auxiliary");
+  return primary?.id === serverId;
+}
+const _realThisDir = (() => {
+  if (typeof __dirname !== "undefined")
+    return __dirname;
+  return path.dirname(fileURLToPath(import.meta.url));
+})();
+let _thisDir = _realThisDir;
+export function _setThisDirForTests(dir) {
+  _thisDir = dir ?? _realThisDir;
+}
+const _managedToolsDir = path.join(getGlobalDmLensDir(), "tools");
+function managedNodeToolCandidates(tool) {
+  const base = path.join(getGlobalDmLensDir(), "tools", "node_modules", ".bin", tool);
+  return process.platform === "win32" ? [`${base}.cmd`, `${base}.exe`, base] : [base];
+}
+const managedBinaryVerdicts = new Map;
+const managedVerifyInFlight = new Map;
+const MANAGED_VERIFY_TIMEOUT_MS = 5000;
+const MANAGED_VERIFY_COOLDOWN_MS = 60000;
+const MANAGED_VERIFY_COOLDOWN_MAX_MS = 15 * 60000;
+function managedVerifyCooldownMs(attempts) {
+  return Math.min(MANAGED_VERIFY_COOLDOWN_MAX_MS, MANAGED_VERIFY_COOLDOWN_MS * 2 ** (attempts - 1));
+}
+async function runManagedVerification(candidate, stamp, priorAttempts, generation, verificationArgs = ["--version"]) {
+  let transient = false;
+  let ok;
+  try {
+    const { verifyToolBinary } = await import("../../../installer/index.js");
+    ok = await verifyToolBinary(candidate, undefined, () => {
+      transient = true;
+    }, MANAGED_VERIFY_TIMEOUT_MS, verificationArgs);
+  } catch {
+    transient = true;
+    ok = false;
+  }
+  if (!ok && transient) {
+    const attempts = priorAttempts + 1;
+    generation.guardedWrite(stamp, () => {
+      managedBinaryVerdicts.set(stamp, {
+        verdict: "unverified",
+        attempts,
+        retryAtMs: Date.now() + managedVerifyCooldownMs(attempts)
+      });
+    });
+    return "unverified";
+  }
+  generation.guardedWrite(stamp, () => {
+    managedBinaryVerdicts.set(stamp, { verdict: ok ? "ok" : "broken" });
+  });
+  if (!ok) {
+    logSessionStart(`dispatch availability: managed shim ${candidate} exists but does not run; falling through to PATH`);
+  }
+  return ok ? "ok" : "broken";
+}
+async function verifyManagedCandidate(candidate, verificationArgs = ["--version"]) {
+  let stamp;
+  try {
+    const stat = fs.statSync(candidate);
+    stamp = `${candidate}:${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return "absent";
+  }
+  const memo = managedBinaryVerdicts.get(stamp);
+  let priorAttempts = 0;
+  if (memo) {
+    if (memo.verdict !== "unverified")
+      return memo.verdict;
+    if (Date.now() < memo.retryAtMs)
+      return "unverified";
+    priorAttempts = memo.attempts;
+  }
+  const existing = managedVerifyInFlight.get(stamp);
+  if (existing)
+    return existing;
+  const generation = availabilityGeneration.capture();
+  const probe = runManagedVerification(candidate, stamp, priorAttempts, generation, verificationArgs).finally(() => {
+    generation.guardedWrite(stamp, () => {
+      if (managedVerifyInFlight.get(stamp) === probe) {
+        managedVerifyInFlight.delete(stamp);
+      }
+    });
+  });
+  managedVerifyInFlight.set(stamp, probe);
+  return probe;
+}
+export async function findManagedNodeToolBinary(tool, verificationArgs = ["--version"]) {
+  for (const candidate of managedNodeToolCandidates(tool)) {
+    const verdict = await verifyManagedCandidate(candidate, verificationArgs);
+    if (verdict === "ok" || verdict === "unverified")
+      return candidate;
+  }
+  return null;
+}
+export function createVenvFinder(command, windowsExt = "", verificationArgs = ["--version"]) {
+  return async (cwd) => {
+    const venvBin = findLocalBinAt(command, cwd, {
+      windowsExt,
+      binDirs: VENV_BIN_DIRS
+    });
+    if (venvBin)
+      return venvBin;
+    const managed = await findManagedNodeToolBinary(command, verificationArgs);
+    if (managed)
+      return managed;
+    return command;
+  };
+}
+export async function resolveManagedToolClient(options) {
+  const probed = await options.probe();
+  if (probed.outcome !== "missing")
+    return probed;
+  if (!shouldAutoInstallTool(options.toolId))
+    return probed;
+  const state = installStateFor(options.cwd, options.toolId);
+  if (state.suppressed)
+    return probed;
+  const installed = await ensureTool(options.toolId);
+  if (!installed) {
+    noteInstallFailure(options.toolId, options.cwd);
+    return probed;
+  }
+  const value = await options.acceptInstalled(installed);
+  if (value === null) {
+    noteInstallFailure(options.toolId, options.cwd);
+    return { outcome: "non-installable" };
+  }
+  noteInstallSuccess(options.toolId, options.cwd);
+  return { outcome: "success", value };
+}
+export async function getManagedToolEnvironment(_toolId, cwd) {
+  let env;
+  try {
+    const { getToolEnvironment } = await import("../../../installer/index.js");
+    env = await getToolEnvironment();
+  } catch {
+    env = { ...process.env };
+  }
+  if (!cwd)
+    return env;
+  const separator = process.platform === "win32" ? ";" : ":";
+  const currentPath = env.PATH || env.Path || process.env.PATH || "";
+  const localBin = path.join(cwd, "node_modules", ".bin");
+  const augmentedPath = `${localBin}${separator}${currentPath}`;
+  return {
+    ...env,
+    PATH: augmentedPath,
+    ...process.platform === "win32" ? { Path: augmentedPath } : {}
+  };
+}
+export async function discoverManagedTool(toolId) {
+  return await ensureTool(toolId, { allowInstall: false }) ?? null;
+}
+const installAttemptsByCwd = new PathKeyedMap(normalizeMapKey);
+const resolveInstallInFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+const correctedAvailabilityByCwd = new PathKeyedMap(normalizeMapKey);
+const uncorrectedEmissionsByCwd = new PathKeyedMap(normalizeMapKey);
+const latchedUnavailableByCwd = new PathKeyedMap(normalizeMapKey);
+const availabilityGeneration = createGenerationSource("dispatch-availability");
+export const getDispatchAvailabilityGeneration = () => availabilityGeneration.current();
+const checkerProbeFlights = createAvailabilityProbeFlight({ generation: getDispatchAvailabilityGeneration });
+export function recordAvailabilityProbeOverrun(tool, key, elapsedMs, budgetMs, failure) {
+  if (budgetMs === undefined || elapsedMs <= budgetMs)
+    return;
+  if (failure === "timeout" && elapsedMs <= budgetMs * 2)
+    return;
+  incrementDegradationCount({
+    kind: "availability-probe-overrun",
+    subject: `${tool}:${key}`,
+    reason: `probe took ${Math.round(elapsedMs)}ms; budget was ${Math.round(budgetMs)}ms`
+  });
+}
+function installStateFor(cwd, toolId) {
+  let states = installAttemptsByCwd.get(cwd);
+  if (!states) {
+    states = new Map;
+    installAttemptsByCwd.set(cwd, states);
+  }
+  let state = states.get(toolId);
+  if (!state) {
+    state = { attempts: 0, suppressed: false };
+    states.set(toolId, state);
+  }
+  return state;
+}
+function noteInstallFailure(toolId, cwd) {
+  const state = installStateFor(cwd, toolId);
+  state.attempts += 1;
+  state.suppressed = true;
+  logSessionStart(`dispatch availability ${toolId}: install attempt ${state.attempts} failed; suppressing retries until the next session or a successful install`);
+}
+function noteInstallSuccess(toolId, cwd) {
+  const states = installAttemptsByCwd.get(cwd);
+  states?.delete(toolId);
+  if (states?.size === 0)
+    installAttemptsByCwd.delete(cwd);
+}
+function hasId(map, cwd, id) {
+  return map.get(cwd)?.has(id) ?? false;
+}
+function addId(map, cwd, id) {
+  let ids = map.get(cwd);
+  if (!ids) {
+    ids = new Set;
+    map.set(cwd, ids);
+  }
+  ids.add(id);
+}
+function deleteIds(map, cwd, ids) {
+  const existing = map.get(cwd);
+  if (!existing)
+    return;
+  for (const id of ids)
+    existing.delete(id);
+  if (existing.size === 0)
+    map.delete(cwd);
+}
+function hasCorrectedAvailability(cwd, toolId) {
+  return hasId(correctedAvailabilityByCwd, cwd, toolId);
+}
+function noteAvailabilityCorrected(cwd, toolId) {
+  addId(correctedAvailabilityByCwd, cwd, toolId);
+}
+function noteLatchedUnavailable(cwd, tool) {
+  addId(latchedUnavailableByCwd, cwd, tool);
+}
+function clearLatchedUnavailable(cwd, ...tools) {
+  deleteIds(latchedUnavailableByCwd, cwd, tools);
+}
+function latchKeysFor(toolId, command) {
+  const keys = [toolId];
+  if (command)
+    keys.push(command, path.basename(command));
+  return keys;
+}
+function hasLatchedUnavailable(cwd, tools) {
+  return tools.some((tool) => hasId(latchedUnavailableByCwd, cwd, tool));
+}
+function sourceTagForToolId(toolId) {
+  switch (getToolInstallStrategy(toolId)) {
+    case "npm":
+      return "managed-dir";
+    case "pip":
+      return "pip-user";
+    case "github":
+      return "github-release";
+    case "archive":
+      return "archive-dist";
+    case "maven":
+      return "maven-jar";
+    default:
+      return;
+  }
+}
+function resolvedTagForAttempt(toolId, attempt) {
+  if (attempt?.outcome === "declined" || attempt?.outcome === "skipped") {
+    return "declined";
+  }
+  return getLastEnsureResolutionSource(toolId) === "path" ? "path" : "cache";
+}
+function emitCompensatingAvailableRow(cwd, toolId, installStartedAt, installedPath, latchKeys) {
+  if (hasCorrectedAvailability(cwd, toolId))
+    return;
+  const correctsLatchedRow = hasLatchedUnavailable(cwd, latchKeys);
+  if (correctsLatchedRow) {
+    noteAvailabilityCorrected(cwd, toolId);
+    clearLatchedUnavailable(cwd, ...latchKeys);
+  } else {
+    if (hasId(uncorrectedEmissionsByCwd, cwd, toolId))
+      return;
+    addId(uncorrectedEmissionsByCwd, cwd, toolId);
+  }
+  const attempt = getInstallAttempt(toolId);
+  const installEvidence = describeInstallAttempt(attempt);
+  const evidence = {
+    ...installEvidence,
+    binary: path.basename(installedPath),
+    source: sourceTagForToolId(toolId),
+    ...installEvidence.install !== "succeeded" && {
+      resolved: resolvedTagForAttempt(toolId, attempt)
+    },
+    correctsLatchedRow
+  };
+  logAvailabilityDecision({
+    tool: toolId,
+    verdict: "available",
+    outcome: "success",
+    cause: "ok",
+    elapsedMs: Date.now() - installStartedAt,
+    latched: false,
+    classifiedBy: "caller",
+    evidence
+  }, cwd);
+}
+export function resetDispatchAvailabilityState() {
+  installAttemptsByCwd.clear();
+  resolveInstallInFlightByCwd.clear();
+  correctedAvailabilityByCwd.clear();
+  uncorrectedEmissionsByCwd.clear();
+  latchedUnavailableByCwd.clear();
+  managedBinaryVerdicts.clear();
+  managedVerifyInFlight.clear();
+  resetPathWalkMemo();
+  availabilityGeneration.bump();
+  checkerProbeFlights.clear();
+  cwdProbeFlights.clear();
+}
+export function createAvailabilityChecker(command, windowsExt = "", versionArgs = ["--version"], options = {}) {
+  const cacheByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+  const inFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+  let checkerGeneration = availabilityGeneration.current();
+  let checkerFlightGeneration = 0;
+  const findCommand = createVenvFinder(command, windowsExt, versionArgs);
+  function ensureCurrentGeneration() {
+    if (checkerGeneration === availabilityGeneration.current())
+      return;
+    cacheByCwd.clear();
+    inFlightByCwd.clear();
+    checkerGeneration = availabilityGeneration.current();
+    checkerFlightGeneration++;
+  }
+  const reset = () => {
+    cacheByCwd.clear();
+    inFlightByCwd.clear();
+    checkerGeneration = availabilityGeneration.current();
+    checkerFlightGeneration++;
+  };
+  function getCache(cwd) {
+    ensureCurrentGeneration();
+    const key = path.resolve(cwd || process.cwd());
+    const existing = cacheByCwd.get(key);
+    if (existing)
+      return existing;
+    const created = {
+      available: null,
+      command: null,
+      outcome: null,
+      cause: null,
+      elapsedMs: 0,
+      retryAtMs: 0,
+      transientAttempts: 0
+    };
+    cacheByCwd.set(key, created);
+    return created;
+  }
+  function noteDecision(cache, resolvedCwd, verdict) {
+    cache.available = verdict.available;
+    cache.outcome = verdict.outcome;
+    cache.cause = verdict.cause;
+    cache.elapsedMs = verdict.elapsedMs;
+    let retryAfterMs;
+    if (verdict.available) {
+      cache.retryAtMs = 0;
+      cache.transientAttempts = 0;
+    } else if (isLatchingOutcome(verdict.outcome)) {
+      cache.retryAtMs = 0;
+      cache.transientAttempts = 0;
+    } else {
+      cache.transientAttempts += 1;
+      retryAfterMs = transientRetryDelayMs(cache.transientAttempts, verdict.cause);
+      cache.retryAtMs = Date.now() + retryAfterMs;
+    }
+    const latched = verdict.available || isLatchingOutcome(verdict.outcome);
+    if (!verdict.available && latched) {
+      noteLatchedUnavailable(resolvedCwd, command);
+    } else if (verdict.available) {
+      clearLatchedUnavailable(resolvedCwd, ...latchKeysFor(command));
+    }
+    logAvailabilityDecision({
+      tool: command,
+      verdict: verdict.available ? "available" : "unavailable",
+      outcome: verdict.outcome,
+      cause: verdict.cause,
+      elapsedMs: verdict.elapsedMs,
+      latched,
+      classifiedBy: verdict.classifiedBy,
+      ...verdict.evidence !== undefined && { evidence: verdict.evidence },
+      ...verdict.hostStallMs !== undefined && {
+        hostStallMs: verdict.hostStallMs
+      },
+      ...retryAfterMs !== undefined && { retryAfterMs },
+      budgetMs: options.probeTimeout ?? 5000
+    }, resolvedCwd);
+  }
+  async function isAvailableAsync(cwd) {
+    ensureCurrentGeneration();
+    const resolvedCwd = cwd || process.cwd();
+    const cache = getCache(resolvedCwd);
+    if (cache.available === false) {
+      if (cache.outcome !== "transient")
+        return false;
+      if (Date.now() < cache.retryAtMs)
+        return false;
+      cache.available = null;
+    }
+    if (cache.available === true && cache.command) {
+      if (await isSpawnableCommand(cache.command))
+        return true;
+      cache.available = null;
+      cache.command = null;
+      cache.outcome = null;
+      cache.cause = null;
+    }
+    const key = path.resolve(resolvedCwd);
+    const existing = inFlightByCwd.get(key);
+    if (existing)
+      return existing;
+    const promiseGeneration = checkerGeneration;
+    let promise;
+    promise = (async () => {
+      const fastPath = await options.fastPath?.();
+      if (fastPath) {
+        cache.command = fastPath;
+        noteDecision(cache, resolvedCwd, {
+          available: true,
+          outcome: "success",
+          cause: "fast-path",
+          elapsedMs: 0,
+          classifiedBy: "caller"
+        });
+        return true;
+      }
+      try {
+        const cwdStat = await fs.promises.stat(resolvedCwd);
+        if (!cwdStat.isDirectory()) {
+          noteDecision(cache, resolvedCwd, {
+            available: false,
+            outcome: "non-installable",
+            cause: "bad-cwd",
+            elapsedMs: 0,
+            classifiedBy: "caller"
+          });
+          return false;
+        }
+      } catch {
+        noteDecision(cache, resolvedCwd, {
+          available: false,
+          outcome: "non-installable",
+          cause: "bad-cwd",
+          elapsedMs: 0,
+          classifiedBy: "caller"
+        });
+        return false;
+      }
+      const cmd = await findCommand(resolvedCwd);
+      if (isInSpawnTimeoutCooldown(cmd)) {
+        noteDecision(cache, resolvedCwd, {
+          available: false,
+          outcome: "transient",
+          cause: "probe-timeout",
+          elapsedMs: 0,
+          classifiedBy: "caller",
+          evidence: {
+            command: cmd,
+            status: null
+          }
+        });
+        return false;
+      }
+      const env = await options.environment?.(resolvedCwd);
+      const stallSampler = startHostStallSampler();
+      const startedAt = Date.now();
+      let result;
+      let hostStallMs;
+      let probeJoined = false;
+      try {
+        const shared = checkerProbeFlights.run(`checker:${command}|${versionArgs.join("|")}|${key}|${checkerFlightGeneration}|${windowsExt}|${cmd}|${JSON.stringify(Object.entries(env ?? {}).sort(([a], [b]) => compareOrdinal(a, b)))}`, () => safeSpawnAsync(cmd, versionArgs, {
+          timeout: options.probeTimeout ?? 5000,
+          cwd: resolvedCwd,
+          env,
+          input: ""
+        }));
+        probeJoined = shared.joined;
+        result = await shared.promise;
+      } finally {
+        hostStallMs = stallSampler.stop();
+      }
+      const elapsedMs = Date.now() - startedAt;
+      recordAvailabilityProbeOverrun(command, resolvedCwd, elapsedMs, options.probeTimeout ?? 5000, result.failure);
+      if (!result.error && result.status === 0) {
+        cache.command = cmd;
+        noteDecision(cache, resolvedCwd, {
+          available: true,
+          outcome: "success",
+          cause: "ok",
+          elapsedMs,
+          hostStallMs,
+          classifiedBy: probeJoined ? "joined" : "probe",
+          evidence: describeProbeEvidence(result)
+        });
+        return true;
+      }
+      const { outcome, cause, evidence } = classifyProbeFailure(result, {
+        hostStallMs,
+        unclassifiedFailureOutcome: options.unclassifiedFailureOutcome
+      });
+      if (result.spawnFailure?.kind === "tool-not-found")
+        resetPathWalkMemo();
+      noteDecision(cache, resolvedCwd, {
+        available: false,
+        outcome,
+        cause,
+        elapsedMs,
+        hostStallMs,
+        classifiedBy: probeJoined ? "joined" : "probe",
+        evidence
+      });
+      return false;
+    })().finally(() => {
+      if (checkerGeneration === promiseGeneration && inFlightByCwd.get(key) === promise) {
+        inFlightByCwd.delete(key);
+      }
+    });
+    inFlightByCwd.set(key, promise);
+    return promise;
+  }
+  function getCommand(cwd) {
+    ensureCurrentGeneration();
+    const cache = getCache(cwd || process.cwd());
+    return cache.command;
+  }
+  function getOutcome(cwd) {
+    ensureCurrentGeneration();
+    return getCache(cwd || process.cwd()).outcome;
+  }
+  function getVerdict(cwd) {
+    ensureCurrentGeneration();
+    const cache = getCache(cwd || process.cwd());
+    return {
+      outcome: cache.outcome,
+      cause: cache.cause,
+      elapsedMs: cache.elapsedMs,
+      latched: cache.available !== false || isLatchingOutcome(cache.outcome ?? "missing"),
+      retryAtMs: cache.retryAtMs
+    };
+  }
+  return { isAvailableAsync, getCommand, getOutcome, getVerdict, reset };
+}
+const cwdProbeFlights = createAvailabilityProbeFlight({
+  generation: getDispatchAvailabilityGeneration
+});
+export function createCwdCachedProbe(probe, options) {
+  const latchByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+  const inFlightByCwd = new PathKeyedMap(normalizeEphemeralMapKey);
+  let probeGeneration = availabilityGeneration.current();
+  function clear() {
+    latchByCwd.clear();
+    inFlightByCwd.clear();
+  }
+  function ensureCurrentGeneration() {
+    if (probeGeneration === availabilityGeneration.current())
+      return;
+    clear();
+    probeGeneration = availabilityGeneration.current();
+  }
+  function latchFor(key) {
+    const existing = latchByCwd.get(key);
+    if (existing)
+      return existing;
+    const created = createAvailabilityLatch();
+    latchByCwd.set(key, created);
+    return created;
+  }
+  function note(latch, key, verdict) {
+    let retryAfterMs;
+    if (verdict.available) {
+      latch.noteAvailable(verdict.cause);
+    } else {
+      const delay = latch.noteUnavailable(verdict.outcome, verdict.cause);
+      if (delay > 0)
+        retryAfterMs = delay;
+    }
+    const latched = verdict.available || isLatchingOutcome(verdict.outcome);
+    if (!verdict.available && latched) {
+      noteLatchedUnavailable(key, options.tool);
+    } else if (verdict.available) {
+      clearLatchedUnavailable(key, ...latchKeysFor(options.tool));
+    }
+    logAvailabilityDecision({
+      tool: options.tool,
+      verdict: verdict.available ? "available" : "unavailable",
+      outcome: verdict.outcome,
+      cause: verdict.cause,
+      elapsedMs: verdict.elapsedMs,
+      latched,
+      hostStallMs: verdict.hostStallMs,
+      ...retryAfterMs !== undefined && { retryAfterMs },
+      ...options.budgetMs !== undefined && { budgetMs: options.budgetMs },
+      classifiedBy: verdict.classifiedBy ?? "probe",
+      ...verdict.evidence !== undefined && { evidence: verdict.evidence }
+    }, key);
+  }
+  const run = (cwd) => {
+    ensureCurrentGeneration();
+    const key = path.resolve(cwd || process.cwd());
+    const latch = latchFor(key);
+    const memo = latch.read();
+    if (memo !== null)
+      return Promise.resolve(memo);
+    const existing = inFlightByCwd.get(key);
+    if (existing)
+      return existing;
+    const promiseGeneration = probeGeneration;
+    let promise;
+    promise = (async () => {
+      const stallSampler = startHostStallSampler();
+      const startedAt = Date.now();
+      let result;
+      let thrown;
+      let probeJoined = false;
+      try {
+        const shared = cwdProbeFlights.run(`cwd:${options.tool}|${options.flightKeyComponent ?? ""}|${key}`, () => probe(key));
+        probeJoined = shared.joined;
+        result = await shared.promise;
+      } catch (error) {
+        thrown = error;
+      }
+      const hostStallMs = stallSampler.stop();
+      const elapsedMs = Date.now() - startedAt;
+      const shape = result ?? {
+        error: thrown instanceof Error ? thrown : new Error(String(thrown))
+      };
+      recordAvailabilityProbeOverrun(options.tool, key, elapsedMs, options.budgetMs, shape.failure);
+      if (result && !result.error && result.status === 0) {
+        note(latch, key, {
+          available: true,
+          outcome: "success",
+          cause: "ok",
+          elapsedMs,
+          hostStallMs,
+          classifiedBy: probeJoined ? "joined" : "probe",
+          evidence: describeProbeEvidence(result, options.tool)
+        });
+        return true;
+      }
+      const { outcome, cause, evidence } = classifyProbeFailure(shape, {
+        hostStallMs,
+        command: options.tool,
+        unclassifiedFailureOutcome: options.unclassifiedFailureOutcome
+      });
+      note(latch, key, {
+        available: false,
+        outcome,
+        cause,
+        elapsedMs,
+        hostStallMs,
+        classifiedBy: probeJoined ? "joined" : "probe",
+        evidence
+      });
+      return false;
+    })().finally(() => {
+      if (probeGeneration === promiseGeneration && inFlightByCwd.get(key) === promise) {
+        inFlightByCwd.delete(key);
+      }
+    });
+    inFlightByCwd.set(key, promise);
+    return promise;
+  };
+  const cached = run;
+  cached.getVerdict = (cwd) => {
+    ensureCurrentGeneration();
+    const latch = latchFor(path.resolve(cwd || process.cwd()));
+    const outcome = latch.getOutcome();
+    return {
+      outcome,
+      cause: latch.getCause(),
+      elapsedMs: 0,
+      latched: outcome !== null && isLatchingOutcome(outcome),
+      retryAtMs: latch.getRetryAtMs()
+    };
+  };
+  cached.reset = () => {
+    clear();
+    probeGeneration = availabilityGeneration.current();
+  };
+  return cached;
+}
+export function resolveNodeToolCommand(cwd, toolName, windowsExt = ".cmd") {
+  const isWin = process.platform === "win32";
+  const binName = isWin ? `${toolName}${windowsExt}` : toolName;
+  const local = path.join(cwd, "node_modules", ".bin", binName);
+  if (fs.existsSync(local))
+    return local;
+  return toolName;
+}
+export function resolveToolCommand(cwd, toolId) {
+  const spec = getToolCommandSpec(toolId);
+  if (!spec)
+    return null;
+  return resolveNodeToolCommand(cwd, spec.command, spec.windowsExt ?? ".cmd");
+}
+export function resolveVendorToolCommand(cwd, toolName, windowsExt = ".bat") {
+  return findLocalBinUpwards(toolName, cwd, {
+    windowsExt,
+    binDirs: VENDOR_BIN_DIRS
+  }) ?? null;
+}
+export async function resolveToolCommandWithInstallFallback(cwd, toolId, timeout = 5000) {
+  const spec = getToolCommandSpec(toolId);
+  if (!spec)
+    return null;
+  return resolveCommandWithInstallFallback(resolveToolCommand(cwd, toolId) ?? spec.command, spec.managedToolId ?? toolId, cwd, spec.versionArgs ?? ["--version"], timeout);
+}
+async function verifyOrInstallCommand(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
+  const spawnable = await isSpawnableCommand(command);
+  if (spawnable) {
+    const versionCheck = await safeSpawnAsync(command, versionArgs, {
+      timeout,
+      cwd,
+      input: ""
+    });
+    if (!versionCheck.error && versionCheck.status === 0) {
+      return command;
+    }
+    return null;
+  }
+  if (!shouldAutoInstallTool(toolId))
+    return null;
+  const state = installStateFor(cwd, toolId);
+  if (state.suppressed)
+    return null;
+  const installStartedAt = Date.now();
+  const installed = await ensureTool(toolId);
+  if (installed) {
+    noteInstallSuccess(toolId, cwd);
+    emitCompensatingAvailableRow(cwd, toolId, installStartedAt, installed, latchKeysFor(toolId, command));
+    return installed;
+  }
+  noteInstallFailure(toolId, cwd);
+  return null;
+}
+export async function resolveCommandArgsWithInstallFallback(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
+  const versionCheck = await safeSpawnAsync(command.cmd, [...command.args, ...versionArgs], { timeout, cwd, input: "" });
+  if (!versionCheck.error && versionCheck.status === 0) {
+    return command;
+  }
+  const installed = await verifyOrInstallCommand(command.cmd, toolId, cwd, versionArgs, timeout);
+  if (!installed) {
+    return null;
+  }
+  if (installed === command.cmd) {
+    return command;
+  }
+  return { cmd: installed, args: [] };
+}
+export async function resolveCommandWithInstallFallback(command, toolId, cwd, versionArgs = ["--version"], timeout = 5000) {
+  return verifyOrInstallCommand(command, toolId, cwd, versionArgs, timeout);
+}
+async function resolveAvailableOrInstallUnshared(checker, toolId, cwd) {
+  const available = await checker.isAvailableAsync(cwd);
+  if (available) {
+    return checker.getCommand(cwd);
+  }
+  if (checker.getOutcome?.(cwd) !== "missing")
+    return null;
+  if (!shouldAutoInstallTool(toolId))
+    return null;
+  const state = installStateFor(cwd, toolId);
+  if (state.suppressed) {
+    return null;
+  }
+  const installStartedAt = Date.now();
+  const installed = await ensureTool(toolId);
+  if (installed) {
+    noteInstallSuccess(toolId, cwd);
+    checker.reset?.();
+    noteLatchedUnavailable(cwd, toolId);
+    emitCompensatingAvailableRow(cwd, toolId, installStartedAt, installed, latchKeysFor(toolId, checker.getCommand(cwd) ?? undefined));
+    return installed;
+  }
+  noteInstallFailure(toolId, cwd);
+  return null;
+}
+export function resolveAvailableOrInstall(checker, toolId, cwd) {
+  const key = normalizeEphemeralMapKey(cwd);
+  let byTool = resolveInstallInFlightByCwd.get(key);
+  if (!byTool) {
+    byTool = new Map;
+    resolveInstallInFlightByCwd.set(key, byTool);
+  }
+  const existing = byTool.get(toolId);
+  if (existing)
+    return existing;
+  const generation = availabilityGeneration.capture();
+  const promise = resolveAvailableOrInstallUnshared(checker, toolId, cwd).finally(() => {
+    generation.guardedWrite(`${toolId}@${key}`, () => {
+      const current = resolveInstallInFlightByCwd.get(key);
+      if (current?.get(toolId) === promise) {
+        current.delete(toolId);
+        if (current.size === 0)
+          resolveInstallInFlightByCwd.delete(key);
+      }
+    });
+  });
+  byTool.set(toolId, promise);
+  return promise;
+}
+const sgLatch = createAvailabilityLatch();
+let sgCmd = null;
+let sgCmdArgs = [];
+let sgSweepSawTransient = false;
+let sgSweepTransientCause = "probe-timeout";
+let sgSweepHostStallMs = 0;
+let sgSweepUnreachable = [];
+let sgSweepDurablyMissing = [];
+function isAstGrepVersionOutput(output) {
+  return /\bast[- ]grep\b/i.test(output);
+}
+async function probeAstGrepCommandAsync(cmd, argsPrefix = []) {
+  const sampler = startHostStallSampler();
+  let check;
+  let hostStallMs;
+  try {
+    check = await safeSpawnAsync(cmd, [...argsPrefix, "--version"], {
+      timeout: 5000
+    });
+  } finally {
+    hostStallMs = sampler.stop();
+    sgSweepHostStallMs += hostStallMs;
+  }
+  if (!check.error && check.status === 0 && isAstGrepVersionOutput(`${check.stdout}
+${check.stderr}`)) {
+    return true;
+  }
+  const { outcome, cause } = classifyProbeFailure(check, { hostStallMs });
+  if (outcome === "transient") {
+    sgSweepSawTransient = true;
+    sgSweepTransientCause = cause;
+    const name = path.basename(cmd);
+    if (!sgSweepUnreachable.includes(name))
+      sgSweepUnreachable.push(name);
+  } else if (!sgSweepDurablyMissing.includes(cmd)) {
+    sgSweepDurablyMissing.push(cmd);
+  }
+  return false;
+}
+function buildSgLocalBins() {
+  const isWin = process.platform === "win32";
+  const hasBash = !!(process.env.MSYSTEM || process.env.GIT_SHELL || process.env.BASH);
+  const extensions = isWin ? hasBash ? ["", ".exe", ".cmd"] : [".cmd", ".exe", ""] : [""];
+  const binaryCandidates = ["ast-grep", "sg"].flatMap((base) => extensions.map((ext) => `${base}${ext}`));
+  const projectWalkOptions = { windowsExt: "" };
+  const ownInstallWalkOptions = { windowsExt: "", ceiling: false };
+  const bins = [
+    ...findLocalBinsUpwards(binaryCandidates, _thisDir, ownInstallWalkOptions).map((binPath) => ({ path: binPath, source: "own-install" })),
+    ...findLocalBinsUpwards(binaryCandidates, process.cwd(), projectWalkOptions).map((binPath) => ({ path: binPath, source: "project" }))
+  ];
+  for (const candidate of binaryCandidates) {
+    const managedBin = path.join(_managedToolsDir, "node_modules", ".bin", candidate);
+    if (fs.existsSync(managedBin)) {
+      bins.push({ path: managedBin, source: "own-install" });
+    }
+  }
+  return bins;
+}
+let sgAvailableInFlight = null;
+let sgAvailabilityGeneration = availabilityGeneration.current();
+function ensureCurrentSgGeneration() {
+  if (sgAvailabilityGeneration === availabilityGeneration.current())
+    return;
+  sgLatch.reset();
+  sgCmd = null;
+  sgCmdArgs = [];
+  sgAvailableInFlight = null;
+  sgAvailabilityGeneration = availabilityGeneration.current();
+}
+export async function isSgAvailableAsync() {
+  ensureCurrentSgGeneration();
+  const memo = sgLatch.read();
+  if (memo !== null)
+    return memo;
+  if (sgAvailableInFlight)
+    return sgAvailableInFlight;
+  const flight = (async () => {
+    const startedAt = Date.now();
+    sgSweepSawTransient = false;
+    sgSweepTransientCause = "probe-timeout";
+    sgSweepHostStallMs = 0;
+    sgSweepUnreachable = [];
+    sgSweepDurablyMissing = [];
+    for (const candidate of buildSgLocalBins()) {
+      if (await probeAstGrepCommandAsync(candidate.path)) {
+        sgCmd = candidate.path;
+        sgCmdArgs = [];
+        noteSgAvailable(startedAt, { source: candidate.source });
+        return true;
+      }
+    }
+    for (const cmd of ["ast-grep", "sg"]) {
+      if (await probeAstGrepCommandAsync(cmd)) {
+        sgCmd = cmd;
+        sgCmdArgs = [];
+        noteSgAvailable(startedAt, { source: "global" });
+        return true;
+      }
+    }
+    for (const name of ["ast-grep", "sg"]) {
+      const globalBin = await findGlobalBinary(name);
+      if (globalBin && await probeAstGrepCommandAsync(globalBin)) {
+        sgCmd = globalBin;
+        sgCmdArgs = [];
+        noteSgAvailable(startedAt, { source: "global" });
+        return true;
+      }
+    }
+    if (await probeAstGrepCommandAsync("npx", ["--no", "--", "ast-grep"])) {
+      sgCmd = "npx";
+      sgCmdArgs = ["--no", "--", "ast-grep"];
+      noteSgAvailable(startedAt, { source: "npx" });
+      return true;
+    }
+    if (sgSweepSawTransient && sgLatch.isProvisional() && sgCmd !== null && !sgSweepDurablyMissing.includes(sgCmd)) {
+      noteSgAvailable(startedAt, { retained: true });
+      return true;
+    }
+    noteSgUnavailable(startedAt, sgSweepSawTransient ? "transient" : "missing", sgSweepSawTransient ? sgSweepTransientCause : "not-found");
+    return false;
+  })().finally(() => {
+    if (sgAvailableInFlight === flight)
+      sgAvailableInFlight = null;
+  });
+  sgAvailableInFlight = flight;
+  return flight;
+}
+function noteSgAvailable(startedAt, opts = {}) {
+  const provisional = sgSweepSawTransient;
+  let retryAfterMs = 0;
+  if (provisional) {
+    retryAfterMs = sgLatch.noteProvisionallyAvailable(sgSweepTransientCause);
+  } else {
+    sgLatch.noteAvailable();
+  }
+  if (opts.source) {
+    logLatency({
+      type: "phase",
+      phase: "tool_bin_resolved",
+      filePath: "<dm-lens>",
+      durationMs: Math.round(Date.now() - startedAt),
+      metadata: {
+        tool: "ast-grep",
+        source: opts.source,
+        ceilingApplied: opts.source === "project"
+      }
+    });
+  }
+  logAvailabilityDecision({
+    tool: "ast-grep",
+    verdict: "available",
+    outcome: "success",
+    cause: provisional ? sgSweepTransientCause : "ok",
+    elapsedMs: Date.now() - startedAt,
+    latched: !provisional,
+    classifiedBy: "probe",
+    hostStallMs: sgSweepHostStallMs,
+    budgetMs: 5000,
+    ...provisional && {
+      provisional: true,
+      unreachablePreferred: [...sgSweepUnreachable],
+      ...opts.retained === true && { retained: true },
+      ...retryAfterMs > 0 && { retryAfterMs }
+    }
+  });
+}
+function noteSgUnavailable(startedAt, outcome, cause) {
+  const retryAfterMs = sgLatch.noteUnavailable(outcome, cause);
+  logAvailabilityDecision({
+    tool: "ast-grep",
+    verdict: "unavailable",
+    outcome,
+    cause,
+    elapsedMs: Date.now() - startedAt,
+    latched: outcome !== "transient",
+    hostStallMs: sgSweepHostStallMs,
+    ...retryAfterMs > 0 && { retryAfterMs },
+    budgetMs: 5000,
+    classifiedBy: "probe"
+  });
+}
+export function getSgCommand() {
+  ensureCurrentSgGeneration();
+  return {
+    cmd: sgCmd ?? "npx",
+    args: sgCmdArgs.length ? sgCmdArgs : ["--no", "--", "ast-grep"]
+  };
+}
+export async function resolveLocalFirstAsync(toolName, cwd, windowsExt = ".cmd") {
+  const isWin = process.platform === "win32";
+  const binName = isWin ? `${toolName}${windowsExt}` : toolName;
+  const local = path.join(cwd, "node_modules", ".bin", binName);
+  if (fs.existsSync(local))
+    return { cmd: local, args: [] };
+  const globalBin = await findGlobalBinary(toolName, windowsExt);
+  if (globalBin)
+    return { cmd: globalBin, args: [] };
+  const globalCheck = await safeSpawnAsync(toolName, ["--version"], {
+    timeout: 3000
+  });
+  if (!globalCheck.error && globalCheck.status === 0) {
+    return { cmd: toolName, args: [] };
+  }
+  return { cmd: "npx", args: ["--no", toolName] };
+}
+export const pyright = createAvailabilityChecker("pyright", ".exe");
+export const ruff = createAvailabilityChecker("ruff", ".exe");
+export const biome = createAvailabilityChecker("biome");
+export const sg = {
+  isAvailableAsync: isSgAvailableAsync,
+  getCommand: getSgCommand
+};