@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/runs/shared/dm-spawn.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-export const PI_CODING_AGENT_PACKAGE = "@duckmind/dm-coding-agent";
+export const DM_CODING_AGENT_PACKAGE = "@duckmind/dm-coding-agent";
 export const DM_SUBAGENT_PI_BINARY_ENV = "DM_SUBAGENT_PI_BINARY";
 export function findPiPackageRootFromEntry(entryPoint) {
   let dir = path.dirname(entryPoint);
@@ -9,7 +9,7 @@ export function findPiPackageRootFromEntry(entryPoint) {
     const packageJsonPath = path.join(dir, "package.json");
     if (fs.existsSync(packageJsonPath)) {
       const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
-      if (pkg.name === PI_CODING_AGENT_PACKAGE)
+      if (pkg.name === DM_CODING_AGENT_PACKAGE)
         return dir;
     }
     dir = path.dirname(dir);
@@ -17,7 +17,7 @@ export function findPiPackageRootFromEntry(entryPoint) {
   return;
 }
 export function resolveInstalledPiPackageRoot() {
-  return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)));
+  return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(DM_CODING_AGENT_PACKAGE)));
 }
 export function resolvePiPackageRoot() {
   try {
@@ -35,14 +35,24 @@ function isRunnableNodeScript(filePath, existsSync) {
 function normalizePath(filePath) {
   return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
 }
-export function resolveWindowsPiCliScript(deps = {}) {
+function isStandalonePiExecutable(execPath) {
+  const executableName = execPath.split(/[\\/]/).pop();
+  return /^dm(?:\.exe)?$/i.test(executableName ?? "");
+}
+export function resolvePiCliScript(deps = {}) {
   const existsSync = deps.existsSync ?? fs.existsSync;
+  const realpathSync = deps.realpathSync ?? fs.realpathSync;
   const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
   const argv1 = deps.argv1 ?? process.argv[1];
   if (argv1) {
     const argvPath = normalizePath(argv1);
     if (isRunnableNodeScript(argvPath, existsSync)) {
-      return argvPath;
+      try {
+        const canonicalArgvPath = realpathSync(argvPath);
+        if (isRunnableNodeScript(canonicalArgvPath, existsSync) && findPiPackageRootFromEntry(canonicalArgvPath)) {
+          return canonicalArgvPath;
+        }
+      } catch {}
     }
   }
   try {
@@ -52,13 +62,13 @@ export function resolveWindowsPiCliScript(deps = {}) {
         return path.join(root, "package.json");
       const packageRoot = deps.resolvePackageEntry ? findPiPackageRootFromEntry(deps.resolvePackageEntry()) : resolveInstalledPiPackageRoot();
       if (!packageRoot)
-        throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
+        throw new Error(`Could not resolve ${DM_CODING_AGENT_PACKAGE} package root`);
       return path.join(packageRoot, "package.json");
     });
     const packageJsonPath = resolvePackageJson();
     const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
     const binField = packageJson.bin;
-    const binPath = typeof binField === "string" ? binField : binField?.pi ?? Object.values(binField ?? {})[0];
+    const binPath = typeof binField === "string" ? binField : binField?.dm ?? Object.values(binField ?? {})[0];
     if (!binPath)
       return;
     const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
@@ -76,15 +86,16 @@ export function getPiSpawnCommand(args, deps = {}) {
   if (piBinary) {
     return { command: piBinary, args };
   }
-  const platform = deps.platform ?? process.platform;
-  if (platform === "win32") {
-    const piCliPath = resolveWindowsPiCliScript(deps);
-    if (piCliPath) {
-      return {
-        command: deps.execPath ?? process.execPath,
-        args: [piCliPath, ...args]
-      };
-    }
+  const execPath = deps.execPath ?? process.execPath;
+  if (isStandalonePiExecutable(execPath)) {
+    return { command: execPath, args };
+  }
+  const piCliPath = resolvePiCliScript(deps);
+  if (piCliPath) {
+    return {
+      command: execPath,
+      args: [piCliPath, ...args]
+    };
   }
   return { command: "dm", args };
 }

package/extensions/dm-subagents/src/runs/shared/dynamic-fanout.js

@@ -7,26 +7,34 @@ const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ITEM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const ITEM_REF_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)(?:\.([^{}]+))?\}/g;
 const RESERVED_TEMPLATE_NAMES = new Set(["task", "previous", "chain_dir", "outputs"]);
-const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance"]);
-const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "sessionFiles", "thinkingOverrides"]);
+const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance", "agentContract", "gateOn"]);
+const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
 const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
 const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
-const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "toolBudget", "acceptance"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
 const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
   ...DYNAMIC_PARALLEL_KEYS,
   "outputName",
   "structured",
   "inheritProjectContext",
+  "inheritGlobalContext",
   "inheritSkills",
   "skills",
   "outputPath",
+  "namespaceOutputPath",
   "maxSubagentDepth",
+  "timeoutMs",
+  "waitToolEnabled",
+  "waitToolDefaultTimeoutMs",
   "structuredOutput",
   "structuredOutputSchema",
   "tools",
+  "allowNestedSubagents",
   "extensions",
   "subagentOnlyExtensions",
   "mcpDirectTools",
+  "mutationTools",
+  "capabilityCeiling",
   "completionGuard",
   "systemPrompt",
   "systemPromptMode",
@@ -34,7 +42,11 @@ const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
   "modelCandidates",
   "sessionFile",
   "effectiveAcceptance",
-  "parentSessionId"
+  "acceptanceInput",
+  "acceptanceRole",
+  "parentSessionId",
+  "launchResolvedExtensions",
+  "requestedCwd"
 ]);
 const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
 export function isSafeOutputName(name) {
@@ -267,15 +279,16 @@ export function collectDynamicResults(step, items, results) {
       ...result?.structuredOutput !== undefined ? { structured: result.structuredOutput } : {},
       ...result?.error ? { error: result.error } : {},
       ...result?.timedOut ? { timedOut: true } : {},
+      ...result?.stopped ? { stopped: true } : {},
       ...result?.savedOutputPath ? { outputPath: result.savedOutputPath } : {},
       ...result?.artifactPaths ? { artifactPaths: result.artifactPaths } : {}
     };
   });
 }
-export function validateDynamicCollection(schema, value) {
+export async function validateDynamicCollection(schema, value) {
   if (!schema)
     return;
-  const validation = validateStructuredOutputValue(schema, value);
+  const validation = await validateStructuredOutputValue(schema, value);
   if (validation.status === "invalid") {
     throw new DynamicFanoutError(`Collected output validation failed: ${validation.message}`);
   }

package/extensions/dm-subagents/src/runs/shared/extension-bindings.js

@@ -0,0 +1,81 @@
+export const DM_SUBAGENT_EXTENSION_BINDINGS_ENV = "DM_SUBAGENT_EXTENSION_BINDINGS";
+export const MAX_EXTENSION_BINDING_NAMESPACES = 16;
+export const MAX_EXTENSION_BINDINGS_BYTES = 16 * 1024;
+export const MAX_EXTENSION_BINDINGS_DEPTH = 16;
+export const MAX_EXTENSION_BINDINGS_PROPERTIES = 256;
+const EXTENSION_BINDING_NAMESPACE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62})\/[1-9][0-9]{0,8}$/;
+function canonicalizeJson(value, path, depth, seen, propertyCount) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error(`${path} must contain only finite JSON numbers.`);
+    return value;
+  }
+  if (typeof value !== "object")
+    throw new Error(`${path} must contain only plain JSON values.`);
+  if (depth > MAX_EXTENSION_BINDINGS_DEPTH)
+    throw new Error(`${path} exceeds the maximum nesting depth of ${MAX_EXTENSION_BINDINGS_DEPTH}.`);
+  if (seen.has(value))
+    throw new Error(`${path} must not contain cycles.`);
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const output = [];
+      for (let index = 0;index < value.length; index++) {
+        if (!Object.prototype.hasOwnProperty.call(value, index))
+          throw new Error(`${path} must not contain sparse arrays.`);
+        output.push(canonicalizeJson(value[index], `${path}[${index}]`, depth + 1, seen, propertyCount));
+      }
+      return Object.freeze(output);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+      throw new Error(`${path} must contain only plain JSON objects.`);
+    if (Object.getOwnPropertySymbols(value).length > 0)
+      throw new Error(`${path} must not contain symbol keys.`);
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const output = {};
+    for (const key of Object.keys(descriptors).sort()) {
+      const descriptor = descriptors[key];
+      if (!descriptor.enumerable || !("value" in descriptor))
+        throw new Error(`${path}.${key} must be an enumerable data property.`);
+      propertyCount.value += 1;
+      if (propertyCount.value > MAX_EXTENSION_BINDINGS_PROPERTIES)
+        throw new Error(`extensionBindings exceeds ${MAX_EXTENSION_BINDINGS_PROPERTIES} total properties.`);
+      Object.defineProperty(output, key, { value: canonicalizeJson(descriptor.value, `${path}.${key}`, depth + 1, seen, propertyCount), enumerable: true, writable: false, configurable: false });
+    }
+    return Object.freeze(output);
+  } finally {
+    seen.delete(value);
+  }
+}
+export function normalizeExtensionBindings(input) {
+  if (input === undefined)
+    return;
+  if (!input || typeof input !== "object" || Array.isArray(input))
+    throw new Error("extensionBindings must be a plain JSON object.");
+  const prototype = Object.getPrototypeOf(input);
+  if (prototype !== Object.prototype && prototype !== null)
+    throw new Error("extensionBindings must be a plain JSON object.");
+  const keys = Object.keys(input);
+  if (keys.length > MAX_EXTENSION_BINDING_NAMESPACES)
+    throw new Error(`extensionBindings supports at most ${MAX_EXTENSION_BINDING_NAMESPACES} namespaces.`);
+  for (const key of keys) {
+    if (!EXTENSION_BINDING_NAMESPACE.test(key))
+      throw new Error(`extensionBindings namespace '${key}' must use a package-like name followed by '/<positive-version>'.`);
+  }
+  const value = canonicalizeJson(input, "extensionBindings", 0, new Set, { value: 0 });
+  const json = JSON.stringify(value);
+  const bytes = Buffer.byteLength(json, "utf8");
+  if (bytes > MAX_EXTENSION_BINDINGS_BYTES)
+    throw new Error(`extensionBindings canonical JSON is ${bytes} bytes; maximum is ${MAX_EXTENSION_BINDINGS_BYTES}.`);
+  return { value, json };
+}
+export function encodeExtensionBindings(input) {
+  return input === undefined ? undefined : normalizeExtensionBindings(input).json;
+}
+export function omitExtensionBindingsEnv(env) {
+  const { [DM_SUBAGENT_EXTENSION_BINDINGS_ENV]: _extensionBindings, ...sanitized } = env;
+  return sanitized;
+}

package/extensions/dm-subagents/src/runs/shared/external-cli-contract.js

@@ -0,0 +1,134 @@
+const UNSUPPORTED = {
+  steer: "The one-shot stdin adapter closes input after launch and cannot accept live steer messages.",
+  resume: "The one-shot stdin adapter has no durable external session identity.",
+  structuredOutput: "The generic external CLI adapter does not parse a trusted structured result.",
+  toolEvents: "The generic external CLI adapter treats stdout as untrusted text, not native DM tool events.",
+  supervisor: "The generic external CLI adapter has no trusted supervisor event transport.",
+  forkContext: "Native DM fork context is not available without an adapter-owned handoff artifact.",
+  extensionBindings: "Native DM extension bindings are never passed to external runners."
+};
+const CAPABILITY_KEYS = new Set(Object.keys(UNSUPPORTED));
+const PROMPT_FILE_UNSUPPORTED = {
+  ...UNSUPPORTED,
+  steer: "The one-shot prompt-file adapter closes input after launch and cannot accept live steer messages.",
+  resume: "The one-shot prompt-file adapter does not retain a durable external session identity."
+};
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS = [
+  "codex-exec",
+  "codex-exec-writer",
+  "claude-code",
+  "claude-code-writer",
+  "cursor-agent",
+  "cursor-agent-writer"
+];
+const CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET = new Set(CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS);
+export const CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL = CODE_OWNED_EXTERNAL_CLI_ADAPTER_IDS.map((id) => `'${id}'`).join(", ");
+export function isCodeOwnedExternalCliAdapterId(value) {
+  return typeof value === "string" && CODE_OWNED_EXTERNAL_CLI_ADAPTER_ID_SET.has(value);
+}
+const RESERVED_READ_ONLY_ADAPTERS = [
+  { name: "claude-code", writer: "claude-code-writer", access: "file-write" },
+  { name: "codex-exec", writer: "codex-exec-writer", access: "workspace-write" },
+  { name: "cursor-agent", writer: "cursor-agent-writer", access: "workspace-write" }
+];
+export function validateCodeOwnedProfileRunner(agent) {
+  const selectionNames = [agent.name, ...agent.localName ? [agent.localName] : [], ...agent.aliases ?? []];
+  for (const adapter of RESERVED_READ_ONLY_ADAPTERS) {
+    if (selectionNames.includes(adapter.name) && !(agent.runner?.type === "external-cli" && agent.runner.adapter === adapter.name)) {
+      return `Selection name '${adapter.name}' is reserved for the read-only '${adapter.name}' adapter. Use '${adapter.writer}' for explicit ${adapter.access} access.`;
+    }
+  }
+  return;
+}
+export function parseExternalCliCapabilityNarrowing(value, label) {
+  if (value === undefined)
+    return;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object.`);
+  const input = value;
+  const unknown = Object.keys(input).filter((key) => !CAPABILITY_KEYS.has(key));
+  if (unknown.length > 0)
+    throw new Error(`${label} has unsupported fields: ${unknown.join(", ")}.`);
+  for (const [key, setting] of Object.entries(input)) {
+    if (setting !== false)
+      throw new Error(`${label}.${key} may only be false; user config cannot widen code-owned external adapter capabilities.`);
+  }
+  return input;
+}
+export function resolveExternalCliRunnerStatus(input) {
+  const codexExec = input.adapter === "codex-exec";
+  const codexExecWriter = input.adapter === "codex-exec-writer";
+  const claudeCode = input.adapter === "claude-code";
+  const claudeCodeWriter = input.adapter === "claude-code-writer";
+  const cursorAgent = input.adapter === "cursor-agent";
+  const cursorAgentWriter = input.adapter === "cursor-agent-writer";
+  const cursor = cursorAgent || cursorAgentWriter;
+  const unsupported = cursor ? PROMPT_FILE_UNSUPPORTED : UNSUPPORTED;
+  return {
+    type: "external-cli",
+    command: input.command,
+    args: input.args ?? [],
+    promptDelivery: cursor ? "prompt-file" : input.promptDelivery ?? "stdin",
+    adapter: { id: input.adapter ?? "external-cli", version: 1, executionMode: cursor ? "one-shot-prompt-file" : "one-shot-stdin" },
+    ...codexExec ? { safety: { sandbox: "read-only", approvalPolicy: "never", ephemeral: true } } : {},
+    ...codexExecWriter ? { safety: { access: "workspace-write", sandbox: "workspace-write", approvalPolicy: "never", ephemeral: true } } : {},
+    ...claudeCode ? { safety: { access: "read-only", authentication: "existing-cli-required", permissionMode: "plan", tools: "none", mcp: "empty-strict", settingSources: "user", userSettingsTrust: "required", sessionPersistence: false } } : {},
+    ...claudeCodeWriter ? { safety: { access: "workspace-write", authentication: "existing-cli-required", permissionMode: "acceptEdits", tools: "Read,Write,Edit,Glob,Grep", mcp: "empty-strict", settingSources: "user", userSettingsTrust: "required", sessionPersistence: false } } : {},
+    ...cursorAgent ? { safety: { access: "read-only", authentication: "cursor-api-key-or-existing-login", mode: "ask", sandbox: "enabled", workspaceTrust: "existing-required", sessionReuse: false } } : {},
+    ...cursorAgentWriter ? { safety: { access: "workspace-write", authentication: "cursor-api-key-or-existing-login", mode: "print", sandbox: "enabled", workspaceTrust: "existing-required", sessionReuse: false } } : {},
+    capabilities: {
+      stop: true,
+      steer: false,
+      resume: false,
+      structuredOutput: false,
+      toolEvents: false,
+      supervisor: "unsupported",
+      forkContext: false,
+      extensionBindings: false
+    },
+    unsupportedReasons: unsupported,
+    nonResumableReason: unsupported.resume
+  };
+}
+export function normalizeExternalCliRunnerStatus(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const input = value;
+  if (input.type !== "external-cli" || typeof input.command !== "string" || !input.command.trim())
+    return;
+  const args = Array.isArray(input.args) && input.args.every((arg) => typeof arg === "string") ? input.args : undefined;
+  const promptDelivery = input.promptDelivery === "stdin" ? "stdin" : undefined;
+  const adapterId = input.adapter && typeof input.adapter === "object" && !Array.isArray(input.adapter) ? input.adapter.id : undefined;
+  if (adapterId === "grok-build") {
+    return {
+      type: "external-cli",
+      command: input.command,
+      args: args ?? [],
+      promptDelivery: "prompt-file",
+      adapter: { id: "grok-build", version: 1, executionMode: "one-shot-prompt-file" },
+      capabilities: { stop: true, steer: false, resume: false, structuredOutput: false, toolEvents: false, supervisor: "unsupported", forkContext: false, extensionBindings: false },
+      unsupportedReasons: PROMPT_FILE_UNSUPPORTED,
+      nonResumableReason: PROMPT_FILE_UNSUPPORTED.resume
+    };
+  }
+  const adapter = isCodeOwnedExternalCliAdapterId(adapterId) ? adapterId : undefined;
+  return resolveExternalCliRunnerStatus({ ...adapter ? { adapter } : {}, command: input.command, ...args ? { args } : {}, ...promptDelivery ? { promptDelivery } : {} });
+}
+export function externalCliReceiptMetadata(input) {
+  const { runner } = input;
+  return {
+    adapter: { ...runner.adapter },
+    capabilities: { ...runner.capabilities },
+    ...runner.safety ? { safety: { ...runner.safety } } : {},
+    ...input.externalProcess ? {
+      outputArtifacts: {
+        stdoutPath: input.externalProcess.stdoutPath,
+        stderrPath: input.externalProcess.stderrPath,
+        ...input.outputReference || input.externalProcess.finalOutputPath ? { finalOutputPath: input.outputReference ?? input.externalProcess.finalOutputPath } : {}
+      }
+    } : input.outputReference ? { outputArtifacts: { finalOutputPath: input.outputReference } } : {},
+    handoff: { mode: "fresh" },
+    supervisor: { mode: "unsupported", reason: runner.unsupportedReasons.supervisor },
+    nonResumableReason: runner.nonResumableReason
+  };
+}

package/extensions/dm-subagents/src/runs/shared/external-cli-preflight.js

@@ -0,0 +1,98 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const MAX_PROBE_OUTPUT_BYTES = 256 * 1024;
+const MAX_PROBE_TIMEOUT_MS = 5000;
+const MAX_CACHE_ENTRIES = 64;
+const cache = new Map;
+const lookup = new Map;
+function resolveBinary(command, env) {
+  if (path.isAbsolute(command) || command.includes(path.sep)) {
+    const resolved = path.resolve(command);
+    fs.accessSync(resolved, fs.constants.X_OK);
+    return resolved;
+  }
+  const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    if (!directory)
+      continue;
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `${command}${extension}`);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return fs.realpathSync(candidate);
+      } catch {}
+    }
+  }
+  throw new Error(`External CLI binary '${command}' was not found on PATH.`);
+}
+function probeWithTimeout(binaryPath, args, env, label, timeoutMs, cwd) {
+  const result = spawnSync(binaryPath, [...args], {
+    cwd,
+    env,
+    encoding: "utf-8",
+    killSignal: "SIGKILL",
+    maxBuffer: MAX_PROBE_OUTPUT_BYTES,
+    timeout: timeoutMs,
+    windowsHide: true
+  });
+  if (result.error)
+    throw new Error(`External CLI ${label} preflight failed: ${result.error.message}`, { cause: result.error });
+  if (result.status !== 0)
+    throw new Error(`External CLI ${label} preflight exited with code ${result.status}: ${(result.stderr || result.stdout).trim()}`);
+  return result.stdout.trim();
+}
+function narrowPositiveInteger(value, ceiling, label) {
+  if (value === undefined)
+    return ceiling;
+  if (!Number.isSafeInteger(value) || value <= 0 || value > ceiling)
+    throw new Error(`${label} may only narrow the code-owned ceiling of ${ceiling}.`);
+  return value;
+}
+function specKey(spec) {
+  return JSON.stringify([spec.id, spec.versionArgs, spec.helpArgs, spec.evidenceArgs, spec.evidenceLabel, spec.probeTimeoutMs]);
+}
+export function preflightExternalCli(command, spec, env, cwd) {
+  const binaryPath = resolveBinary(command, env);
+  const binaryMtimeMs = fs.statSync(binaryPath).mtimeMs;
+  const lookupKey = JSON.stringify([binaryPath, binaryMtimeMs, specKey(spec)]);
+  const cachedKey = lookup.get(lookupKey);
+  const cached = cachedKey ? cache.get(cachedKey) : undefined;
+  const probeTimeoutMs = narrowPositiveInteger(spec.probeTimeoutMs, MAX_PROBE_TIMEOUT_MS, "probeTimeoutMs");
+  const base = cached ?? {
+    binaryPath,
+    binaryMtimeMs,
+    version: probeWithTimeout(binaryPath, spec.versionArgs, env, "version", probeTimeoutMs, cwd),
+    help: probeWithTimeout(binaryPath, spec.helpArgs, env, "help", probeTimeoutMs, cwd)
+  };
+  const evidence = spec.evidenceArgs ? probeWithTimeout(binaryPath, spec.evidenceArgs, env, spec.evidenceLabel ?? "evidence", probeTimeoutMs, cwd) : undefined;
+  const result = { ...base, ...evidence !== undefined ? { evidence } : {}, cacheHit: Boolean(cached) };
+  spec.validate?.(result);
+  if (!cached) {
+    const cacheKey = JSON.stringify([binaryPath, base.version, binaryMtimeMs, specKey(spec)]);
+    cache.set(cacheKey, base);
+    lookup.set(lookupKey, cacheKey);
+    while (cache.size > MAX_CACHE_ENTRIES) {
+      const oldest = cache.keys().next().value;
+      cache.delete(oldest);
+      for (const [candidateLookup, candidateCache] of lookup)
+        if (candidateCache === oldest)
+          lookup.delete(candidateLookup);
+    }
+  }
+  return result;
+}
+export function invalidateExternalCliPreflight(command, spec, _reason) {
+  const key = specKey(spec);
+  for (const [cacheKey, entry] of cache) {
+    if (entry.binaryPath === command || entry.binaryPath.endsWith(`${path.sep}${command}`) || cacheKey.includes(key))
+      cache.delete(cacheKey);
+  }
+  for (const [lookupKey, cacheKey] of lookup)
+    if (!cache.has(cacheKey))
+      lookup.delete(lookupKey);
+}
+export function clearExternalCliPreflightCacheForTests() {
+  cache.clear();
+  lookup.clear();
+}