ccdeck 3.29.11 → 3.31.0

package/src/server/exec-not-found.mjs

@@ -0,0 +1,213 @@
+// Whether a batch candidate's output is cmd.exe saying "no such command".
+//
+// A `.cmd` or `.bat` is launched THROUGH cmd.exe (see viaCmd in exec.mjs),
+// and cmd.exe is always there — so a missing tool is not a spawn error at all.
+// It is a healthy shell exiting non-zero after printing a sentence, and telling
+// that sentence apart from a tool that ran and failed is the whole of what this
+// module does. It decides two things for exec.mjs's candidate loop: whether to
+// try the next spelling, and whether to answer `code: "ENOENT"` — and the first
+// of those re-runs the entire command, which for `cswap remove 3` is not a
+// retry anybody wants made on a guess.
+//
+// A module of its own because it is pure: text and an exit status in, a verdict
+// out, no process and no filesystem. exec.mjs re-exports both names, so every
+// caller that imported them from there still does.
+// The three lines an ENGLISH cmd.exe prints when it cannot find what it was
+// asked to run, anchored to a whole line each. First the two-line pair for a
+// bare name, then the one it uses when a directory in an explicit path does not
+// exist.
+//
+// These are one signal out of three rather than the whole answer — see
+// looksMissing. Windows ships cmd.exe in every language it ships in, and these
+// sentences are translated with it.
+const CMD_UNKNOWN = /^'(.+)' is not recognized as an internal or external command,?$/i;
+const CMD_UNKNOWN_TAIL = /^operable program or batch file\.?$/i;
+const CMD_NO_PATH = /^the system cannot find the (?:path|file) specified\.?$/i;
+
+// cmd.exe's own errorlevel for a command token it could not resolve — the one
+// signal here that is not a human sentence, and therefore the only one that is
+// the same on a German install as on an English one. It is the number every CI
+// log in the world prints beside "is not recognized".
+//
+// Not every path reports it: some Windows builds answer a bare `cmd /c missing`
+// with a plain 1 instead, which is why this is a sufficient signal and never a
+// necessary one. A number this large cannot arrive from POSIX at all — a process
+// exit status there is masked to 0-255 before Node ever sees it — so nothing
+// outside cmd.exe can reach it by accident.
+const CMD_NOT_FOUND_EXIT = 9009;
+
+/** True when an exit status is cmd.exe saying "no such command", in any locale. */
+export const notFoundExit = (code) => Number(code) === CMD_NOT_FOUND_EXIT;
+
+// Every run of text this line wrapped in quotes. cmd.exe quotes the command
+// token it could not find in EVERY locale, and the quote character is the only
+// part of the message that is not a translation: `'…'` in English and French,
+// `"…"` in German, Spanish, Italian, Portuguese, Polish and Russian.
+const quotedRuns = (line) =>
+  [...String(line).matchAll(/'([^']+)'|"([^"]+)"/g)].map(m => m[1] ?? m[2]);
+
+// cmd.exe echoes the command token exactly as it was given, so an exact match
+// is what we expect; the comparison is only case- and quote-insensitive because
+// Windows paths are.
+const sameCommand = (quoted, name) => {
+  const norm = (s) => String(s).trim().replace(/^"+|"+$/g, "").toLowerCase();
+  return norm(quoted) === norm(name);
+};
+
+/**
+ * cmd.exe's way of saying ENOENT — and only cmd.exe's.
+ *
+ * A .cmd or .bat candidate is launched THROUGH cmd.exe, and cmd.exe exists — so
+ * a missing tool is not a spawn error at all. It is a healthy shell exiting 1
+ * after printing two lines:
+ *
+ *     'cswap' is not recognized as an internal or external command,
+ *     operable program or batch file.
+ *
+ * Read as a real failure, that stops the candidate loop early AND puts the
+ * second line — on its own, meaningless — in front of the user. Reported from
+ * Windows on 2026-08-14: the accounts panel said only "operable program or
+ * batch file." when sharing an account.
+ *
+ * The fussiness is about the other direction, which is worse. "The system
+ * cannot find the file specified" is Windows' generic text for ENOENT, and it
+ * appears INSIDE the output of tools that ran perfectly well — cswap is a
+ * Python CLI, and a FileNotFoundError traceback ends in that exact sentence.
+ * Believed there, it threw the real error away, told the user the tool was not
+ * on PATH when PATH was fine, and — the dangerous half — sent the candidate
+ * loop on to re-run the entire command, which for `cswap remove 3` means asking
+ * to delete an account a second time.
+ *
+ * So the output has to be cmd.exe's message and nothing else: cmd.exe prints it
+ * INSTEAD of running anything, so any other line, or any prefix on the line,
+ * means something ran and this is its report. And when cmd.exe names the
+ * command it could not find, that name must be the candidate we asked for — a
+ * tool that shells out itself can forward the message about some other command.
+ *
+ * `name` is the spelling cmd.exe was ACTUALLY GIVEN — which since #457 is the
+ * shim's absolute path whenever shimPath found one, not the bare candidate the
+ * loop started from. That distinction is the coupling #456 named as its reason
+ * for stopping short, and it is a one-way trap rather than a detail: cmd.exe
+ * echoes the command token back exactly as it received it, so a check against
+ * the bare name stops matching the instant the token becomes a path. What that
+ * costs is not a cosmetic mismatch — it is the honesty of the whole answer. A
+ * shim that shimPath saw and that is gone by the time cmd.exe looks for it (a
+ * stale memo, an uninstall mid-session, a network drive that dropped, a roaming
+ * profile still syncing) would come back as an ordinary exit 1 whose stderr is
+ * cmd.exe's two-line "is not recognized / operable program or batch file."
+ * instead of the `code: "ENOENT"` every panel keys its "not installed" message
+ * off. The user would be told their CLI failed, and shown half a sentence about
+ * batch files, when the truthful answer is that it is not there.
+ *
+ * Feeding it the launch spelling keeps the comparison EXACT, which is what the
+ * paragraph above is protecting: matching loosely — on the basename, say —
+ * would let a tool that shells out itself have its own child's "is not
+ * recognized" read as the tool's absence, re-running a command that may be
+ * `cswap remove 3`. So the rule is not "compare less", it is "compare against
+ * what was actually asked for".
+ *
+ * Callers that only have the text (failureText) omit it and get the shape rules
+ * alone.
+ *
+ * ── AND NOT ONLY IN ENGLISH (#552) ──────────────────────────────────────────
+ *
+ * Everything above was written against three English sentences, and cmd.exe is
+ * translated. On a German install with cswap genuinely absent it prints
+ *
+ *     Der Befehl "cswap" ist entweder falsch geschrieben oder konnte nicht
+ *     gefunden werden.
+ *
+ * — so this answered false, `run` resolved `{ ok: false, code: 1 }`,
+ * claude-accounts.mjs picked `reason: "switch_failed"` over `"no_cswap"` and the
+ * panel's install affordance never appeared. failureText then fell through to
+ * firstUseful, which puts the LAST line of a localized sentence on screen by
+ * itself: #457's symptom reproduced for every non-English locale. It also
+ * stopped the candidate loop early, so a `.bat` installed after a missing `.cmd`
+ * was never reached.
+ *
+ * Adding the German sentence, and then the French and the Japanese ones, is not
+ * a fix — it is the same defect with a longer list. So two signals that are not
+ * sentences carry the answer instead, and the English text is what remains when
+ * neither is available:
+ *
+ *   1. THE EXIT STATUS. `exitCode` 9009 is cmd.exe's own errorlevel for a
+ *      command token it could not resolve, identical in every language. See
+ *      CMD_NOT_FOUND_EXIT for why it is not required, and the paragraph below
+ *      for the two cases where it is not believed either. It is subject to the
+ *      same "cmd.exe printed nothing else" cap as rule 2, because a status is
+ *      forwarded as easily as a sentence is.
+ *
+ *   2. THE SHAPE. cmd.exe quotes the command it could not find, in every locale,
+ *      and prints that INSTEAD of running anything — so the whole output is at
+ *      most the two lines of one wrapped sentence. Text of at most two lines
+ *      whose FIRST line quotes exactly the spelling we launched is cmd.exe's
+ *      verdict about our command whatever the words around it say.
+ *
+ * Rule 2 needs `name`, and refuses without it. That is the same principle the
+ * paragraphs above argue for and not a limitation bolted on: `Error: "account-9"
+ * does not exist` is one line with a quoted token in it, and read as an absence
+ * it would send the candidate loop back round to re-run `cswap remove 3`. What
+ * makes the rule safe is that the quoted token has to be the exact spelling
+ * cmd.exe was handed — `cswap.cmd`, or the absolute path shimPath found — which
+ * is a string the tool underneath has no reason to print. The two-line cap is
+ * the other half: a Python traceback ending in "The system cannot find the file
+ * specified" is four lines and can never qualify.
+ *
+ * THE SAME TRAP THE ENGLISH RULE ALREADY AVOIDS, NOW FOR THE EXIT STATUS. A
+ * `.cmd` shim is itself a batch file, so a shim that EXISTS and whose payload
+ * interpreter does not — a scoop or npm-style `cswap.cmd` in front of a python
+ * that was uninstalled — has cmd.exe print "is not recognized" about PYTHON and
+ * hands the shim's caller that same 9009. Believed on its own, the deck would
+ * call the tool absent and re-run the command under the next spelling. So a text
+ * that positively names a command OTHER than ours vetoes every rule here,
+ * including the status: the check that made #457 safe, applied one level up.
+ *
+ * What is deliberately still missed: a LOCALIZED "the system cannot find the
+ * path specified", which carries no quoted token and no structure to key off.
+ * That case only arises when shimPath found a shim that then vanished, and it
+ * fails in the safe direction — an honest exit 1 rather than a wrong ENOENT.
+ */
+export function looksMissing(text, name = "", exitCode = null) {
+  const lines = String(text ?? "").split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+  // Whatever cmd.exe named, in whatever language it said the rest — the quoting
+  // is the part that is not a translation.
+  const named = lines.length ? quotedRuns(lines[0]) : [];
+  const namesUs = named.some(q => sameCommand(q, name));
+
+  // The veto, before anything is believed: a message about somebody else's
+  // command is not evidence about ours, and neither is the status that came
+  // with it. See the header — a `.cmd` shim in front of a missing interpreter
+  // forwards both.
+  if (name && named.length > 0 && !namesUs) return false;
+
+  // cmd.exe says this INSTEAD of running anything, so anything longer than one
+  // wrapped sentence came from something that DID run — and that outranks both
+  // signals below. A shim can forward its child's 9009 after printing pages of
+  // its own; a Python traceback is four lines and one of them quotes the very
+  // shim we launched.
+  const saidNothingElse = lines.length <= 2;
+
+  // The signal that is not a sentence. It does not need to READ the text, which
+  // is the whole reason it exists: on a non-English install there may be nothing
+  // in the text this can read.
+  if (saidNothingElse && notFoundExit(exitCode)) return true;
+  if (!lines.length) return false;
+
+  // The English shapes, whole-line anchored, exactly as before.
+  let english = true;
+  for (const line of lines) {
+    const unknown = CMD_UNKNOWN.exec(line);
+    if (unknown) {
+      if (name && !sameCommand(unknown[1], name)) return false;
+      continue;
+    }
+    if (CMD_UNKNOWN_TAIL.test(line) || CMD_NO_PATH.test(line)) continue;
+    english = false;
+    break;
+  }
+  if (english) return true;
+
+  // Otherwise: cmd.exe in some other language, recognised by its shape and by
+  // the one word in it that is ours.
+  return Boolean(name) && saidNothingElse && namesUs;
+}

package/src/server/exec-output.mjs

@@ -0,0 +1,23 @@
+// What a command that failed said about it, short enough to keep.
+//
+// claude-accounts.mjs, cswap-install.mjs and cswap-auto.mjs read a failed
+// `run` the same way — stderr when the tool wrote any, stdout otherwise,
+// trimmed, and cut to a length a panel can print — and each wrote that out in
+// full, seven times over. One rule spelled seven times is seven places to fix
+// the day a tool starts putting its reason somewhere else. The auto-switch tick
+// (cswap-auto-loop.mjs) had an eighth spelling — stderr or nothing, on the one
+// path where stdout is already known to be empty — and asks here too.
+//
+// A module of its own rather than a line in exec.mjs, which owns `run`: more
+// than a dozen suites replace exec.mjs with a mock that carries `run` and
+// nothing else, and a helper exported from there would be missing from every
+// module those suites load.
+
+/**
+ * What a failed command said, trimmed and cut to `max` characters: its stderr
+ * when it wrote any, its stdout otherwise, because tools differ on which one a
+ * failure goes to. `r` is exec.mjs's `run` answer.
+ */
+export function failureDetail(r, max) {
+  return (r.stderr || r.stdout).trim().slice(0, max);
+}

package/src/server/exec-spec.mjs

@@ -0,0 +1,341 @@
+// Which file to run for a command name, and what to hand spawn for it — on
+// Linux, macOS and Windows alike.
+//
+// Everything exec.mjs's header argues for is decided here: the spellings a bare
+// name is tried under (candidates), which of them are batch files that must go
+// through cmd.exe (isBatch, viaCmd), how one argument is quoted for a shell that
+// will parse it (shellQuoteArg), and the absolute path a `.cmd` shim is
+// launched under so it finds its own payload (shimPath, pathLookup,
+// candidateSpec). Nothing here spawns anything. The platform is a parameter
+// throughout, so the Windows answers can be checked from a machine that is not
+// Windows.
+//
+// The one piece of state is the memo of which spelling worked, per command
+// name: `candidates` reads it, and `rememberSpelling` is its one write, which
+// exec.mjs's runners call once a spelling has proved itself.
+//
+// exec.mjs re-exports every public name here, so its callers are unchanged.
+import { existsSync } from "node:fs";
+
+// Extensions Windows will execute, most specific first. `.com` is omitted —
+// nothing ships one, and every extra candidate costs a failed spawn.
+const WIN_EXTS = [".exe", ".cmd", ".bat", ""];
+
+// Which spelling worked, per command name. A failed spawn is cheap but not
+// free, and these run on a poll.
+const resolved = new Map();
+
+/**
+ * Remember that `raw` is the spelling of `cmd` that worked, so `candidates`
+ * offers it alone from now on.
+ *
+ * The memo's one write, named. Five places confirm a spelling — a clean `run`,
+ * a direct spawn and a clean exit in `runInteractive`, the same two in
+ * `runDetached` — and each has its own rule for WHEN a spelling counts as
+ * confirmed; see the notes at each. What they record is always the candidate
+ * and never a resolved path, for the reason given in `run`.
+ */
+export function rememberSpelling(cmd, raw) {
+  resolved.set(cmd, raw);
+}
+
+/**
+ * The spellings to try for `cmd`, best first.
+ *
+ * Exported with the platform as a parameter for the reason everything else in
+ * this file is: the Windows answer decides which candidate becomes a batch one,
+ * and a batch candidate is the only kind #457 touches — so a test that wants to
+ * follow a caller's bare name all the way to the command line cmd.exe receives
+ * has to be able to ask for the Windows list from a machine that is not Windows.
+ */
+export function candidates(cmd, platform = process.platform) {
+  if (platform !== "win32") return [cmd];
+  // An explicit extension is respected as given.
+  if (/\.[a-z]+$/i.test(cmd)) return [cmd];
+  const known = resolved.get(cmd);
+  return known ? [known] : WIN_EXTS.map(ext => cmd + ext);
+}
+
+/** Exported for tests: the platform is a parameter so both can be checked. */
+export const isBatch = (file, platform = process.platform) =>
+  platform === "win32" && /\.(cmd|bat)$/i.test(file);
+
+/**
+ * Rewrite a batch-file invocation as a cmd.exe one.
+ *
+ * Mirrors what Node does internally for `shell: true` on Windows — comspec,
+ * /d /s /c, the whole command line as a single quoted argument, and
+ * windowsVerbatimArguments so Node does not quote it a second time. Each
+ * argument is quoted by shellQuoteArg below, which has to satisfy cmd.exe AND
+ * the argv parser of whatever it launches — see the note there, and #624 for
+ * the half of that rule this file was missing until a real cmd.exe was asked.
+ */
+export function viaCmd(file, args) {
+  const line = [file, ...args].map(a => shellQuoteArg(a, "win32")).join(" ");
+  return {
+    file: process.env.comspec || process.env.ComSpec || "cmd.exe",
+    args: ["/d", "/s", "/c", `"${line}"`],
+    opts: { windowsVerbatimArguments: true },
+  };
+}
+
+/**
+ * Quote ONE argument into a command line a shell will parse.
+ *
+ * Everything else in this module exists to avoid needing this: an argument
+ * vector is handed to spawn untouched and nothing in it is ever read as syntax.
+ * Two callers cannot take that route, and they are the reason this is exported.
+ * A Claude Code hook is registered as `{type:"command", command:"<string>"}` —
+ * the host CLI runs that string THROUGH A SHELL on every tool call, and the
+ * format has no argv form to emit instead. So the string has to be built here,
+ * correctly, once.
+ *
+ * The inputs are not user input in the web sense, but they are not constants
+ * either: the hook path is built from $CLAUDE_CONFIG_DIR and homedir(), and the
+ * node path from process.execPath. Wrapping those in double quotes — what this
+ * used to do — is not escaping on POSIX at all: `$(…)`, a backtick and `\` are
+ * all still live inside them, so a config dir named `/tmp/a$(id)b` became shell
+ * code written into the user's settings.json and executed on every hook fire.
+ * A bare `$` in a path is the same bug wearing a duller hat — `$HOME` expands to
+ * nothing, the hook path silently becomes wrong, and hooks stop firing with no
+ * error anywhere.
+ *
+ * POSIX gets single quotes, inside which NOTHING is special, with the one
+ * escape that form has: close the quote, emit a backslash-quote, reopen.
+ *
+ * Windows gets the rule below — the same one viaCmd applies above, so this file
+ * has one Windows quoting rule rather than two. It has to satisfy TWO parsers,
+ * and that is the whole of its difficulty, because they disagree about the
+ * backslash:
+ *
+ *   cmd.exe reads the line only far enough to find where the command ends. It
+ *   has no escape for a quote at all — a `"` toggles "inside quotes", and `&`,
+ *   `|`, `<`, `>`, `^`, `(` and `)` are syntax only while outside — and it does
+ *   not treat `\` as anything. Then it hands the rest of the line on AS TEXT.
+ *
+ *   The program on the other end splits that text into argv itself, and for
+ *   node that is the UCRT parser, which DOES read `\` as an escape in front of
+ *   a quote: 2n backslashes before a `"` are n backslashes and a quote that
+ *   toggles, 2n+1 are n backslashes and a literal `"`.
+ *
+ * So an embedded `"` is written `""` rather than `\"` — two toggles is no net
+ * change to cmd.exe's idea of where it is, while the child's parser turns the
+ * pair back into one quote — and every run of backslashes that ends up in front
+ * of a quote, INCLUDING THE CLOSING ONE THIS ADDS, is doubled so the child does
+ * not read it as an escape.
+ *
+ * That last clause is #624 and it was missing. `"` + arg + `"` alone turns a
+ * path ending in a separator — `C:\Program Files\nodejs\` — into
+ * `"C:\Program Files\nodejs\"`, whose final `\"` is an escaped quote to the
+ * child: the quoted region never closes, and the argument swallows every
+ * argument after it on the line. `--provider claude` in the hook command is
+ * exactly what it swallowed. A backslash immediately before an embedded quote
+ * was the quieter half of the same defect — it was eaten as the escape.
+ *
+ * The one residual left, unchanged: cmd.exe expands `%VAR%` inside quotes too,
+ * and a command line has no escape for it. That is narrower than it sounds,
+ * since `%foo%` with no variable `foo` is left alone, and it is a limit of the
+ * platform rather than of this function. `!VAR!` is the same limit on a machine
+ * with delayed expansion turned on, which is not the default for `cmd /c`.
+ *
+ * no-shell-hook-commands.test.ts runs the output of this through a real cmd.exe
+ * on the Windows leg of the matrix and compares what the child RECEIVED against
+ * what was intended. Four literals said this function agreed with itself for
+ * three releases; they could not say whether it agreed with Windows.
+ */
+export function shellQuoteArg(arg, platform = process.platform) {
+  const s = String(arg ?? "");
+  if (platform !== "win32") return `'${s.split("'").join("'\\''")}'`;
+  let out = '"';
+  let slashes = 0;
+  for (const ch of s) {
+    if (ch === "\\") { slashes++; continue; }
+    if (ch === '"') { out += "\\".repeat(slashes * 2) + '""'; slashes = 0; continue; }
+    out += "\\".repeat(slashes) + ch;
+    slashes = 0;
+  }
+  // A run that reaches the end of the argument is in front of the closing quote,
+  // which is a quote like any other.
+  return `${out}${"\\".repeat(slashes * 2)}"`;
+}
+
+/**
+ * The absolute path of a Windows command shim, or null when nothing answers to
+ * that name.
+ *
+ * Why a bare name is not good enough, which is the whole of #456. npm's `.cmd`
+ * shims locate every file they need relative to THEMSELVES:
+ *
+ *     SET "NPM_PREFIX_JS=%~dp0\node_modules\npm\bin\npm-prefix.js"
+ *     SET "NPX_CLI_JS=%~dp0\node_modules\npm\bin\npx-cli.js"
+ *
+ * `%~dp0` is the drive and path of `%0`, and `%0` is the command token cmd.exe
+ * was given. Handed `cmd.exe /d /s /c ""npm.cmd" "install" …`, that token
+ * carries no directory of its own, so `%~dp0` came out as the deck's WORKING
+ * DIRECTORY instead of the shim's. Reported from Windows 10 with the deck
+ * started from `C:\Users\vceban`:
+ *
+ *     Error: Cannot find module 'C:\Users\vceban\node_modules\npm\bin\npm-prefix.js'
+ *     Error: Cannot find module 'C:\Users\vceban\node_modules\npm\bin\npx-cli.js'
+ *
+ * — two stacks, one defect, and `C:\Users\vceban` is the cwd rather than
+ * anything to do with npm: `where npx` on that machine printed
+ * `C:\Program Files\nodejs\npx.cmd` and `npx ccdeck` ran perfectly from a
+ * prompt. It is ours, introduced when #362 replaced `shell: true` with viaCmd:
+ * the quoting was the fix and the bare name was the cost, and it broke the
+ * managed install and the npx fallback in the same stroke, which is why every
+ * diagnosis of one half kept half-fitting.
+ *
+ * Node's own directory is tried before PATH because node and npm ship together
+ * and that is where the shims are — the same preference npxCliCandidates in
+ * npx.mjs states for npm's CLI scripts, so the repo has one rule rather than
+ * two. PATH is then walked in its own order, which is what cmd.exe would have
+ * done, minus the current directory it searches first: a deck that resolves its
+ * npm out of whatever folder it happens to be sitting in is the bug above
+ * wearing a hat.
+ *
+ * The path arithmetic is spelled out rather than done through `node:path` for
+ * the reason npxCliCandidates gives: `path` is the platform running the SUITE,
+ * so a Windows layout checked from macOS would come back with forward slashes.
+ * `execPath`, `pathEnv` and `exists` are injected for the same reason — the
+ * Windows answer has to be checkable from an OS that cannot run it.
+ *
+ * The walk itself now lives in `pathLookup` below, because #433 needed the same
+ * one for a tool that is not a shim; this is that walk with the two answers a
+ * shim needs — Windows, and node's own directory first.
+ */
+export const shimPath = (name, deps) =>
+  pathLookup(name, "win32", { besideNode: true, ...deps });
+
+/**
+ * Where `name` actually lives on PATH, as an absolute path, or null when
+ * nothing on PATH answers to it.
+ *
+ * This is the general form of shimPath above, and it exists because #433 asked
+ * for a third way to reach ccusage: the copy a user installed themselves. The
+ * deck's own error text has told people to "put ccusage on PATH yourself" since
+ * before there was anything that looked, so the choice was to either look or
+ * stop saying it — see getRunner in ccusage.mjs for which way that went.
+ *
+ * Writing it as ONE walk rather than a second one is the point. A PATH search
+ * on Windows is not a PATH search plus a note: `ccusage` there is `ccusage.cmd`
+ * or `ccusage.exe` and never the bare name, because PATHEXT is a shell's job
+ * and spawn is not a shell — which is the whole reason `candidates` exists, so
+ * that is what supplies the spellings here. And a `.cmd` found this way is
+ * returned as a FULL PATH, which is what keeps #456 fixed: launched by its bare
+ * name through cmd.exe, a shim computes `%~dp0` from the deck's working
+ * directory and goes hunting for its payload there.
+ *
+ * `besideNode` is the one thing a shim wants and a tool does not. npm ships
+ * beside node, so looking there first is right for `npm.cmd`; for anything else
+ * it would quietly overrule the order the user put their own PATH in, which is
+ * the one statement of preference they actually made.
+ *
+ * The check is existence, not executability. That is what `run`'s candidate
+ * loop effectively asks too — it spawns and moves on if the spawn fails — and
+ * an executable bit is not a thing Windows has. The residue is a directory on
+ * PATH that happens to be named after the tool; it would be resolved here and
+ * fail on spawn, with the failure naming the path, which is a better place to
+ * find out than a silent miss.
+ */
+export function pathLookup(name, platform = process.platform, {
+  execPath = process.execPath,
+  pathEnv = process.env.PATH ?? process.env.Path ?? "",
+  exists = existsSync,
+  besideNode = false,
+} = {}) {
+  // A name that already carries a directory needs no lookup, and re-rooting it
+  // would be a way to run something else entirely.
+  if (typeof name !== "string" || !name || /[\\/]/.test(name)) return null;
+  const win = platform === "win32";
+  const sep = win ? "\\" : "/";
+  const dirs = [];
+  if (besideNode) {
+    const beside = String(execPath ?? "").split(/[\\/]/).slice(0, -1).join(sep);
+    if (beside) dirs.push(beside);
+  }
+  // `;` on Windows, `:` everywhere else. Splitting on the wrong one is not a
+  // near miss: a POSIX PATH read with `;` is one enormous directory that
+  // exists nowhere, so every lookup would answer null and the feature would
+  // look like it had never been written.
+  for (const raw of String(pathEnv ?? "").split(win ? ";" : ":")) {
+    // A PATH entry may be quoted, and may end in a separator; neither is part
+    // of the directory, and both would produce a path nothing exists at.
+    const dir = raw.trim().replace(/^"|"$/g, "").replace(/[\\/]+$/, "");
+    if (dir) dirs.push(dir);
+  }
+  // On POSIX this is `[name]`, so the inner loop runs once and the cost is one
+  // stat per directory, exactly as before.
+  const spellings = candidates(name, platform);
+  for (const dir of dirs) {
+    for (const spelling of spellings) {
+      const full = `${dir}${sep}${spelling}`;
+      try {
+        if (exists(full)) return full;
+      } catch {
+        // An entry that cannot even be stat'ed — a disconnected network drive
+        // is the usual one — is a miss, not a reason to stop looking.
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * What to hand `spawn`/`execFile` for `file` and `args` on this platform, with
+ * the argument vector intact and no shell.
+ *
+ * The alternative every caller reaches for first — `shell: true`, because a
+ * .cmd cannot be spawned any other way — is the one thing that must not be
+ * used: Node joins the array into a command line with a single space and no
+ * per-argument quoting, so `--workspace C:\Users\John Smith\proj` arrives as
+ * two arguments and an `&` in a path ends the command early. Batch files go
+ * through cmd.exe with each argument quoted; everything else is spawned as
+ * given. The platform is a parameter so both branches can be tested.
+ *
+ * The one thing quoting cannot cover: cmd.exe expands `%VAR%` inside quotes
+ * too, and a command line has no escape for it. Every other metacharacter —
+ * `&`, `|`, `>`, `^`, `(` — is inert once quoted.
+ */
+export const spawnSpec = (file, args, platform = process.platform) =>
+  isBatch(file, platform) ? viaCmd(file, args) : { file, args, opts: {} };
+
+/**
+ * The same thing for ONE CANDIDATE SPELLING out of the list above — which on
+ * Windows means deciding the NAME the shim is launched under before deciding
+ * how, because those are not the same question.
+ *
+ * `spawnSpec` answers "how". This answers what #457 put in front of it. A batch
+ * candidate runs THROUGH cmd.exe (see viaCmd), and a `.cmd` shim locates its own
+ * payload relative to `%~dp0` — the drive and path of the command token cmd.exe
+ * was handed. A bare `claude.cmd` carries no directory at all, so `%~dp0` came
+ * out as the deck's WORKING DIRECTORY and the shim went hunting for its
+ * JavaScript under whatever folder the deck happened to be started from. #456
+ * proved exactly that for ccusage's `npm.cmd` and `npx.cmd`; it left exec.mjs's
+ * three runners alone, and they carry the shims the panels depend on — the
+ * `claude.cmd` behind the quota poll and the sign-in, and whatever `.cmd` a
+ * Python installer left for cswap. Same defect, same machine, wider blast
+ * radius.
+ *
+ * `?? raw` is the whole safety story and is not optional: when shimPath can see
+ * no layout it answers null, and the candidate stays the bare name today's code
+ * already uses, so nothing that works now can start failing. It is the same
+ * `?? name` ccusage.mjs and npx.mjs spell, so the repo has one rule rather than
+ * three. shimPath also refuses any name that already carries a directory, which
+ * is what keeps a caller's own absolute candidate — quotaClaudeBin's
+ * `%APPDATA%\npm\claude.cmd`, cswapCandidates' `~/.local/bin/cswap.exe` — from
+ * being re-rooted somewhere else entirely.
+ *
+ * `launch` comes back beside the spec because looksMissing has to be told the
+ * spelling cmd.exe was ACTUALLY GIVEN rather than the one the loop started
+ * from; its own header explains what breaks otherwise, and that coupling is the
+ * reason #456 stopped short of doing this.
+ *
+ * On POSIX `isBatch` is false, so no lookup happens, no filesystem is touched,
+ * `launch` is `raw`, and the spec is the object spawnSpec always returned —
+ * byte-identical, which is the point.
+ */
+export function candidateSpec(raw, args, platform = process.platform, deps) {
+  const launch = isBatch(raw, platform) ? (shimPath(raw, deps) ?? raw) : raw;
+  return { ...spawnSpec(launch, args, platform), launch };
+}