jules-orchestrator-kit 0.53.0 → 0.54.1

package/src/git.mjs

@@ -1,5 +1,5 @@
 import { execFileSync, execSync } from "node:child_process";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, statSync } from "node:fs";
 import { join, delimiter } from "node:path";
 import { normalizePath } from "./config.mjs";
 
@@ -394,9 +394,104 @@ export function diffText(root = process.cwd(), base = "main", mode = "committed"
   return git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
 }
 
+/**
+ * Paths git summarised as binary in this diff, with the size of what changed.
+ *
+ * `git diff` prints one 43-byte line for a binary file — "Binary files a/x and
+ * b/x differ" — regardless of whether x grew by a byte or by half a megabyte.
+ * Everything downstream reads the diff *text*, so a binary file is invisible to
+ * both the payload governor and the secret scanner: a 500 KB blob measured 250
+ * bytes, and a credential with a leading NUL byte was never looked at.
+ *
+ * Sizes come from the object git actually recorded where there is one, and from
+ * the working file otherwise, so both `committed` and `working-tree` modes get a
+ * real number.
+ *
+ * @param {string} root
+ * @param {string} base
+ * @param {string} mode
+ * @returns {Array<{ file: string, bytes: number }>}
+ */
+export function binaryDiffEntries(root = process.cwd(), base = "main", mode = "committed") {
+  const resolvedRef = resolveBase(root, base);
+  const ranges =
+    mode === "working-tree" || mode === "working"
+      ? [[`${resolvedRef}...HEAD`], ["HEAD"]]
+      : [[`${resolvedRef}...HEAD`]];
+
+  const entries = new Map();
+  for (const range of ranges) {
+    let raw = "";
+    try {
+      raw = git(["diff", "--raw", "--no-renames", "-z", ...range], { cwd: root, raw: true, ignoreError: true }) || "";
+    } catch (_) {
+      continue;
+    }
+    // `--raw -z` emits ":<srcmode> <dstmode> <srcsha> <dstsha> <status>\0<path>\0".
+    const fields = raw.split("\0").filter(Boolean);
+    for (let i = 0; i < fields.length; i++) {
+      const meta = fields[i];
+      if (!meta.startsWith(":")) continue;
+      const parts = meta.slice(1).split(/\s+/);
+      const dstSha = parts[3];
+      const status = (parts[4] || "").charAt(0);
+      const file = fields[i + 1];
+      i += 1;
+      if (!file || status === "D") continue;
+
+      let bytes = 0;
+      if (dstSha && !/^0+$/.test(dstSha)) {
+        const size = git(["cat-file", "-s", dstSha], { cwd: root, ignoreError: true });
+        bytes = Number(size) || 0;
+      }
+      // An unstaged change has an all-zero destination sha; the working file is
+      // the only place its size exists.
+      if (!bytes) {
+        try {
+          bytes = statSync(join(root, file)).size;
+        } catch (_) {
+          bytes = 0;
+        }
+      }
+      // Keep the largest observation: the same path can appear in both ranges.
+      entries.set(file, Math.max(entries.get(file) || 0, bytes));
+    }
+  }
+
+  // Only the paths git itself refused to render as text are relevant; a file
+  // that diffed normally is already counted in the diff text.
+  const binaryPaths = new Set();
+  const text = diffText(root, base, mode);
+  for (const line of text.split("\n")) {
+    const m = line.match(/^Binary files (?:a\/(.+) and )?(?:b\/(.+)|\/dev\/null) differ$/);
+    if (m) binaryPaths.add(normalizePath(m[2] || m[1] || ""));
+    const m2 = line.match(/^Binary files \/dev\/null and b\/(.+) differ$/);
+    if (m2) binaryPaths.add(normalizePath(m2[1]));
+  }
+
+  return [...entries.entries()]
+    .filter(([file]) => binaryPaths.has(normalizePath(file)))
+    .map(([file, bytes]) => ({ file, bytes }));
+}
+
+/**
+ * Total bytes this change actually carries.
+ *
+ * The diff text plus the real size of every binary blob it only summarised.
+ * Without the second term the payload governor could be walked straight past
+ * with a committed binary of any size.
+ */
 export function diffBytes(root = process.cwd(), base = "main", mode = "committed") {
   const text = diffText(root, base, mode);
-  return Buffer.byteLength(text, "utf-8");
+  let bytes = Buffer.byteLength(text, "utf-8");
+  try {
+    for (const entry of binaryDiffEntries(root, base, mode)) bytes += entry.bytes;
+  } catch (_) {
+    // A payload figure that is too low is the dangerous direction, but throwing
+    // here would break every gate on a repo git cannot describe. The text-only
+    // number is still returned.
+  }
+  return bytes;
 }
 
 export function showFromOrigin(root = process.cwd(), base = "main", filePath = "") {
@@ -454,6 +549,85 @@ export function parseGitHubRepo(remoteUrl) {
  * @param {string} [root=process.cwd()]
  * @returns {string}
  */
+/**
+ * Work out which branch this repository actually treats as its base.
+ *
+ * `main` was hardcoded as the scaffolded default, which is wrong the moment
+ * `git init` picks `master` (still the default on many installed gits) or the
+ * project standardised on `develop`. The failure was not graceful: the first
+ * `agentctl check` could not resolve the base ref and rejected with exit 1.
+ *
+ * Resolution order, strongest evidence first:
+ *   1. `origin/HEAD` — the remote states its own default branch.
+ *   2. A local `main`, then `master` — the conventional names, preferred over
+ *      the checked-out branch so running `init` from a feature branch does not
+ *      record that feature branch as the base for everything after.
+ *   3. The current branch — covers a fresh `git init` with no commits, where
+ *      HEAD points at an unborn branch that `--show-current` still names.
+ *   4. `main`, when there is no git information at all to go on.
+ *
+ * @param {string} [root=process.cwd()]
+ * @returns {string}
+ */
+/**
+ * Split a list of repo-relative paths into the ones git already tracks and the
+ * ones it does not.
+ *
+ * Used to tell an onboarding mistake apart from an agent overstepping. Both
+ * arrive as the same exit-3 scope violation on the same protected paths, but
+ * "the files `init` just wrote are not committed yet" and "something edited the
+ * rules it is governed by" need opposite advice, and the operator who has just
+ * met the tool gets the wrong half if the two are not distinguished.
+ *
+ * @param {string} root
+ * @param {string[]} files - repo-relative paths
+ * @returns {{ tracked: string[], untracked: string[] }}
+ */
+export function partitionTracked(root = process.cwd(), files = []) {
+  const list = files.filter((f) => typeof f === "string" && f && !f.startsWith("-"));
+  if (list.length === 0) return { tracked: [], untracked: [] };
+  let out = "";
+  try {
+    out = git(["ls-files", "--", ...list], { cwd: root, ignoreError: true }) || "";
+  } catch (_) {
+    // Without an answer, claim nothing is tracked-or-not: callers fall back to
+    // the generic advice rather than to a guess.
+    return { tracked: [], untracked: [] };
+  }
+  const tracked = new Set(out.split("\n").map((l) => l.trim()).filter(Boolean));
+  return {
+    tracked: list.filter((f) => tracked.has(f)),
+    untracked: list.filter((f) => !tracked.has(f)),
+  };
+}
+
+export function detectDefaultBranch(root = process.cwd()) {
+  // `git()` returns trimmed stdout, and "" for a non-zero exit under
+  // ignoreError — there is no status field to read.
+  const ask = (args) => {
+    try {
+      return git(args, { cwd: root, ignoreError: true }) || "";
+    } catch (_) {
+      return "";
+    }
+  };
+
+  const remoteHead = ask(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  if (remoteHead.startsWith("origin/")) {
+    const name = remoteHead.slice("origin/".length).trim();
+    if (name) return name;
+  }
+
+  for (const candidate of ["main", "master"]) {
+    if (ask(["rev-parse", "--verify", "--quiet", `refs/heads/${candidate}`])) return candidate;
+  }
+
+  const current = ask(["branch", "--show-current"]);
+  if (current) return current;
+
+  return "main";
+}
+
 export function resolveGitRemoteOrigin(root = process.cwd()) {
   try {
     const raw = git(["config", "--get", "remote.origin.url"], { cwd: root, ignoreError: true });

package/src/ops/cli-intent.mjs

@@ -0,0 +1,29 @@
+/**
+ * Whether a command invocation is asking to be walked through a wizard, or has
+ * already said everything the wizard would ask.
+ *
+ * `agentctl task create --title X --prompt Y` states the whole task and then
+ * opened the interactive wizard anyway, which re-asked for the title and the
+ * prompt in a terminal and hung a CI job that had no terminal to answer with.
+ * Neither `--yes` nor `--non-interactive` was passed, so the CLI concluded
+ * "interactive" from the absence of a flag rather than from the presence of the
+ * answers.
+ *
+ * Kept as a pure function, out of the CLI script, because that script executes
+ * on import and so cannot be exercised from a test.
+ *
+ * @param {object} input
+ * @param {boolean} [input.interactive] - `--interactive` was passed explicitly
+ * @param {boolean} [input.nonInteractive] - `--non-interactive` / `--no-interactive`
+ * @param {boolean} [input.yes] - `--yes`
+ * @param {boolean} [input.fullySpecified] - every field the wizard would ask for is present
+ * @returns {boolean|undefined} true/false to force a mode, undefined to let the
+ *   callee decide from whether stdin is a TTY
+ */
+export function resolveWizardInteractivity(input = {}) {
+  // An explicit `--interactive` always wins: the flags may be intended as seeds
+  // to edit rather than as a complete invocation.
+  if (input.interactive === true) return true;
+  if (input.nonInteractive || input.yes || input.fullySpecified) return false;
+  return undefined;
+}

package/src/ops/command-registry.mjs

@@ -70,35 +70,44 @@ export const COMMAND_REGISTRY = [
     shortcuts: ["d", "doc"],
     examples: [
       "agentctl doctor",
-      "agentctl doctor --interactive",
-      "agentctl doctor --fix safe --yes",
+      "agentctl doctor --probe",
       "agentctl doctor --json",
     ],
+    // `--interactive`, `--fix` and `--yes` were listed here and implemented
+    // nowhere: the report carries remediation entries, but nothing applies
+    // them. Advertising a flag the command silently ignores is the same defect
+    // as documenting `queue` as a read-only browser. They come back to this
+    // list when an apply step exists.
     flags: [
-      { name: "interactive", type: "boolean", description: "Open full-screen diagnostic matrix" },
-      { name: "fix", type: "string", description: "Apply fix classes (e.g. 'safe' or check IDs)" },
-      { name: "probe", type: "boolean", description: "Enable active network/execution probes" },
+      { name: "probe", type: "boolean", description: "Actively start the provider CLI to check it answers, rather than only finding it on PATH" },
       { name: "json", type: "boolean", description: "Output structured JSON doctor report" },
-      { name: "yes", type: "boolean", description: "Bypass interactive confirmation for safe fixes" },
     ],
   },
   {
     id: "queue",
+    // This described a passive viewer — "Browse and manage", `mutates: false`,
+    // `risk: low` — while the handler runs the queue: it dispatches every task
+    // to the provider and spends budget. Someone reading `--help` before their
+    // first run was told the opposite of what the command does.
     path: ["queue"],
     title: "queue",
-    description: "Browse and manage canonical task queue",
+    description: "Execute pending task envelopes: dispatches each to the provider and moves it out of the queue",
     category: "Operate",
-    mutates: false,
-    risk: "low",
+    mutates: true,
+    risk: "moderate",
     interactive: "optional",
     requiresRepository: true,
     shortcuts: ["q"],
     examples: [
+      "agentctl queue --dry-run",
       "agentctl queue",
-      "agentctl queue --interactive",
+      "agentctl queue --dag --concurrency 3",
       "agentctl queue --json",
     ],
     flags: [
+      { name: "dag", type: "boolean", description: "Resolve depends-on order via Kahn's algorithm before running" },
+      { name: "concurrency", type: "string", description: "Parallel worker slots (defaults to limits.concurrency)" },
+      { name: "dry-run", type: "boolean", description: "Report what would run without dispatching or moving anything" },
       { name: "interactive", type: "boolean", description: "Open full-screen queue dashboard" },
       { name: "json", type: "boolean", description: "Output structured JSON queue snapshot" },
       { name: "limit", type: "string", description: "Maximum tasks to include in snapshot" },

package/src/ops/doctor-registry.mjs

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { execFileSync, spawnSync } from "node:child_process";
 import { loadConfig } from "../config.mjs";
-import { probeProvider, detectAvailableProviders } from "../provider-readiness.mjs";
+import { probeProvider, detectAvailableProviders, probeProviderLiveness } from "../provider-readiness.mjs";
 import { resolveConcurrency } from "../budget.mjs";
 
 /**
@@ -443,31 +443,53 @@ export async function runDoctorChecks(options = {}) {
     // Fall back to the default; config.present already reports a broken config.
   }
   const providerProbe = probeProvider(configuredProvider);
+  // A green row here used to read as "the provider works", when all it ever
+  // checked was a name on PATH or a variable in the environment. An installed
+  // CLI whose account has no entitlement passes both and then fails on the
+  // first dispatch, so the row has to say what it actually verified.
+  const liveness = activeProbe ? probeProviderLiveness(configuredProvider) : null;
+  const scopeNote =
+    providerProbe.kind === "exec"
+      ? "Checked: the binary is on PATH. Not checked: whether the CLI is signed in — only a dispatch can show that."
+      : "Checked: a credential is present in the environment. Not checked: whether the provider accepts it.";
+  const livenessFailed = Boolean(liveness && liveness.attempted && !liveness.ok);
+
   addResult({
     id: "provider.key",
     category: "Provider",
     title: `Provider Readiness (${providerProbe.name})`,
-    status: providerProbe.ready ? "pass" : "warn",
-    severity: providerProbe.ready ? "info" : "high",
+    alwaysShowSummary: true,
+    status: providerProbe.ready && !livenessFailed ? "pass" : "warn",
+    severity: providerProbe.ready && !livenessFailed ? "info" : "high",
     // Naming the variable, not the value: an operator who wonders which key a
     // dispatch will use should not have to echo a secret to find out.
-    summary: `${providerProbe.label} — ${providerProbe.reason}`,
-    remediation: providerProbe.ready
-      ? []
-      : [
-          {
-            summary: providerProbe.remedy,
-            risk: "low",
-            automatic: false,
-            requiresProbe: false,
-          },
-        ],
+    summary: [
+      `${providerProbe.label} — ${providerProbe.reason}`,
+      liveness && liveness.attempted ? liveness.detail : null,
+      providerProbe.ready ? scopeNote : null,
+      !activeProbe && providerProbe.kind === "exec" ? "Run `agentctl doctor --probe` to start the CLI and confirm it answers." : null,
+    ]
+      .filter(Boolean)
+      .join(" "),
+    remediation:
+      providerProbe.ready && !livenessFailed
+        ? []
+        : [
+            {
+              summary: livenessFailed ? `The CLI is installed but did not run cleanly: ${liveness.detail}` : providerProbe.remedy,
+              risk: "low",
+              automatic: false,
+              requiresProbe: !providerProbe.ready ? false : true,
+            },
+          ],
     evidence: [
       { label: "provider", value: providerProbe.name, sensitive: false },
       { label: "providerKind", value: providerProbe.kind, sensitive: false },
       { label: "ready", value: providerProbe.ready, sensitive: false },
       { label: "keySource", value: providerProbe.keySource || "", sensitive: false },
       { label: "binaryFound", value: Boolean(providerProbe.binPath), sensitive: false },
+      { label: "livenessProbed", value: Boolean(liveness && liveness.attempted), sensitive: false },
+      { label: "livenessOk", value: liveness ? liveness.ok : null, sensitive: false },
     ],
   });
 

package/src/ops/ide-scaffold.mjs

@@ -11,14 +11,32 @@ export class IdeScaffoldError extends Error {
 
 /**
  * Scaffolds IDE integration configuration files for Cursor, VS Code, and Claude Desktop.
+ *
+ * These files land in directories a project may already be using (`.cursor/`,
+ * `.vscode/`), and the merge logic preserves what is there — but `--dry-run`
+ * was accepted by the CLI and never reached here, so the only way to find out
+ * what would be touched was to let it happen.
+ *
  * @param {string} target - 'cursor' | 'vscode' | 'claude' | 'all'
  * @param {object} [options]
+ * @param {string} [options.root]
+ * @param {boolean} [options.dryRun] - report the files without writing them
  * @returns {object} Summary of scaffolded files
  */
 export function scaffoldIdeConfig(target = "all", options = {}) {
   const root = options.root || resolveRoot();
+  const dryRun = Boolean(options.dryRun);
   const validTargets = new Set(["cursor", "vscode", "claude", "all"]);
 
+  /** Write unless this is a rehearsal; the directory is only made when writing. */
+  const writeUnlessRehearsing = (dir, file, contents) => {
+    if (dryRun) return;
+    try {
+      mkdirSync(dir, { recursive: true });
+    } catch (_) {}
+    writeFileSync(file, contents, "utf-8");
+  };
+
   const normTarget = (target || "all").toLowerCase();
   if (!validTargets.has(normTarget)) {
     throw new IdeScaffoldError(`Invalid target '${target}'. Allowed targets: cursor, vscode, claude, all`);
@@ -29,10 +47,6 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
   // Target: Cursor (.cursor/mcp.json)
   if (normTarget === "cursor" || normTarget === "all") {
     const cursorDir = join(root, ".cursor");
-    try {
-      mkdirSync(cursorDir, { recursive: true });
-    } catch (_) {}
-
     const cursorConfigPath = join(cursorDir, "mcp.json");
     let existingConfig = {};
     if (existsSync(cursorConfigPath)) {
@@ -52,17 +66,13 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       },
     };
 
-    writeFileSync(cursorConfigPath, JSON.stringify(updatedCursorConfig, null, 2), "utf-8");
+    writeUnlessRehearsing(cursorDir, cursorConfigPath, JSON.stringify(updatedCursorConfig, null, 2));
     results.push({ target: "cursor", file: ".cursor/mcp.json", ok: true });
   }
 
   // Target: VS Code (.vscode/tasks.json)
   if (normTarget === "vscode" || normTarget === "all") {
     const vscodeDir = join(root, ".vscode");
-    try {
-      mkdirSync(vscodeDir, { recursive: true });
-    } catch (_) {}
-
     const vscodeTasksPath = join(vscodeDir, "tasks.json");
     let existingConfig = { version: "2.0.0", tasks: [] };
     if (existsSync(vscodeTasksPath)) {
@@ -110,17 +120,13 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       tasks: updatedTasks,
     };
 
-    writeFileSync(vscodeTasksPath, JSON.stringify(updatedVsCodeConfig, null, 2), "utf-8");
+    writeUnlessRehearsing(vscodeDir, vscodeTasksPath, JSON.stringify(updatedVsCodeConfig, null, 2));
     results.push({ target: "vscode", file: ".vscode/tasks.json", ok: true });
   }
 
   // Target: Claude Desktop (claude_desktop_config.json snippet helper)
   if (normTarget === "claude" || normTarget === "all") {
     const agentDir = join(root, ".agent");
-    try {
-      mkdirSync(agentDir, { recursive: true });
-    } catch (_) {}
-
     const snippetPath = join(agentDir, "claude_desktop_config.snippet.json");
     const claudeSnippet = {
       mcpServers: {
@@ -131,9 +137,9 @@ export function scaffoldIdeConfig(target = "all", options = {}) {
       },
     };
 
-    writeFileSync(snippetPath, JSON.stringify(claudeSnippet, null, 2), "utf-8");
+    writeUnlessRehearsing(agentDir, snippetPath, JSON.stringify(claudeSnippet, null, 2));
     results.push({ target: "claude", file: ".agent/claude_desktop_config.snippet.json", ok: true });
   }
 
-  return { ok: true, target: normTarget, results };
+  return { ok: true, target: normTarget, dryRun, results };
 }

package/src/ops/verify-output.mjs

@@ -0,0 +1,38 @@
+/**
+ * Choose what to show the operator from a failed stage's captured streams.
+ *
+ * stderr is where a failing suite says what it expected; stdout is where
+ * several runners (node:test among them) put the whole report — assertion text
+ * and stack included.
+ *
+ * Preferring stderr outright discarded all of that whenever stderr held so much
+ * as the spawn wrapper's own "Command failed: npm test", which it always does.
+ * The operator was shown a line naming the command they had just typed, and
+ * nothing about which test failed or why. A wrapper line is not diagnostic
+ * output: when that is all stderr has, stdout is the report.
+ *
+ * Lives in src/ rather than in the CLI script so it can be imported and tested
+ * without executing the CLI, which runs on import.
+ *
+ * @param {{ stdout?: string, stderr?: string }} failure
+ * @returns {string}
+ */
+export function selectFailureOutput(failure = {}) {
+  const rawStderr = (failure.stderr || "").trim();
+  const rawStdout = (failure.stdout || "").trim();
+  if (!rawStderr) return rawStdout;
+
+  const stderrIsWrapperOnly = rawStderr
+    .split("\n")
+    .every((line) => line.trim() === "" || /^(command failed|error: command failed|npm err!?)/i.test(line.trim()));
+
+  if (stderrIsWrapperOnly && rawStdout) return rawStdout;
+  if (rawStdout && rawStdout !== rawStderr) {
+    // Both carry something real, so show both rather than guessing which runner
+    // this is. stderr goes last on purpose: the caller keeps only the tail, and
+    // when stderr has real content it is nearly always the failure itself —
+    // putting the runner's banner after it would spend the cap on noise.
+    return `${rawStdout}\n${rawStderr}`;
+  }
+  return rawStderr;
+}

package/src/provider-readiness.mjs

@@ -1,5 +1,7 @@
 import { existsSync, statSync } from "node:fs";
 import { join, delimiter } from "node:path";
+import { spawnSync } from "node:child_process";
+import { resolveWindowsSpawn } from "./git.mjs";
 
 /**
  * What each provider actually needs before a dispatch can succeed.
@@ -172,6 +174,7 @@ export function probeProvider(name, opts = {}) {
   return {
     name: descriptor.name,
     kind: descriptor.kind,
+    bin: descriptor.bin,
     label: descriptor.label,
     ready,
     known: true,
@@ -182,6 +185,72 @@ export function probeProvider(name, opts = {}) {
   };
 }
 
+/**
+ * Actually run the provider's CLI, rather than only finding it on PATH.
+ *
+ * `probeProvider` deliberately spawns nothing — it is called from a bare
+ * `agentctl` invocation and from `doctor`, both of which must stay instant. But
+ * a binary on PATH is a weak claim: a `gemini` that is installed and whose
+ * account has no access still reports ready, `doctor` still says 11 passed, and
+ * the first thing that disagrees is a dispatch that dies. This is the check
+ * that can disagree earlier, so it is opt-in (`agentctl doctor --probe`).
+ *
+ * It proves the binary starts and answers, not that the account is entitled —
+ * no CLI exposes "am I authorised" without doing work — but the common failures
+ * (broken install, wrong architecture, a CLI that refuses to start unauthenticated)
+ * surface here instead of mid-repair.
+ *
+ * @param {string} name
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env=process.env]
+ * @param {number} [opts.timeoutMs=8000]
+ * @returns {{ name: string, attempted: boolean, ok: boolean, detail: string }}
+ */
+export function probeProviderLiveness(name, opts = {}) {
+  const env = opts.env || process.env;
+  const base = probeProvider(name, { env });
+  if (base.kind !== "exec" || !base.binPath) {
+    return {
+      name: base.name,
+      attempted: false,
+      ok: base.ready,
+      detail: base.kind === "http" ? "Hosted provider — a credential cannot be validated without spending a request." : base.reason,
+    };
+  }
+
+  try {
+    // A global npm install puts a `.cmd` shim on PATH, and since the fix for
+    // CVE-2024-27980 Node refuses to spawn one directly — it comes back EINVAL,
+    // which would report every Windows CLI as broken. `resolveWindowsSpawn` is
+    // the same routing `runCmd` already uses: native .exe direct, everything
+    // else through cmd.exe with the argv quoted the way cmd.exe parses it back.
+    const win = resolveWindowsSpawn(base.binPath, ["--version"], env);
+    const res = win
+      ? spawnSync(win.file, win.args, {
+          encoding: "utf-8",
+          timeout: Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 8000,
+          env,
+          windowsVerbatimArguments: win.verbatim,
+        })
+      : spawnSync(base.binPath, ["--version"], {
+          encoding: "utf-8",
+          timeout: Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 8000,
+          env,
+        });
+    if (res.error) {
+      return { name: base.name, attempted: true, ok: false, detail: `\`${base.bin || base.name} --version\` could not run: ${res.error.message}` };
+    }
+    if (res.status !== 0) {
+      const why = ((res.stderr || res.stdout || "").trim().split("\n")[0] || `exit ${res.status}`).slice(0, 200);
+      return { name: base.name, attempted: true, ok: false, detail: `\`--version\` exited ${res.status}: ${why}` };
+    }
+    const version = (res.stdout || "").trim().split("\n")[0].slice(0, 80);
+    return { name: base.name, attempted: true, ok: true, detail: version ? `CLI responds: ${version}` : "CLI responds." };
+  } catch (err) {
+    return { name: base.name, attempted: true, ok: false, detail: `Probe failed: ${err.message}` };
+  }
+}
+
 /**
  * Probe every built-in provider, ready ones first, in preference order.
  *