viewable-one 0.0.0-stage → 0.12.1

package/lib/update.mjs

@@ -0,0 +1,302 @@
+// "THERE IS A NEWER ONE", once a day and no more.
+//
+// A daemon installed once and never thought about again is a daemon that
+// stays on whatever version the tester installed in September. So it asks npm
+// what the latest is, once a day, and writes the answer into the mark file
+// the app already reads every tick - `version` and `updateAvailable`, beside
+// `at`. NEW KEYS ONLY: `readRunnerPresence` in the app reads `at` exactly as
+// it did, an old app ignores what it does not know, and an old runner writing
+// neither key still satisfies a new app. That is the whole compatibility
+// story and it is why nothing existing was renamed.
+//
+// THE DAILY CHECK IS A NOTICE. The checker never downloads, installs or
+// restarts anything: an auto-updating daemon that spends credits is a
+// different decision from the one ruling 1 made. The app shows one quiet line
+// and the person explicitly runs `viewable update` when they choose.
+
+import { createRequire } from "node:module";
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { basename, join, posix, win32 } from "node:path";
+import { readRunnerHealth, waitForRunnerHealth } from "./runner-health.mjs";
+import { noDaemonInstall } from "./logindaemon.mjs";
+import { fileURLToPath } from "node:url";
+
+import { runnableCommand } from "./windows-command.mjs";
+
+export const DAY_MS = 86_400_000;
+export const PACKAGE_NAME = "viewable-one";
+/** npm over a cold cache is slow and this runs inside `doctor`, where a
+ * person is waiting. Offline is "unknown", not a hang. */
+export const NPM_TIMEOUT_MS = 8_000;
+
+/** This package's own version, read from the package.json beside it. */
+export function packageVersion() {
+  try {
+    const path = fileURLToPath(new URL("../package.json", import.meta.url));
+    return JSON.parse(readFileSync(path, "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/** Compare two dotted versions. Returns >0 when a is newer. Pre-release tags
+ * are ignored rather than ordered: "is there a newer one" does not need the
+ * full semver grammar, and half an implementation of it would be worse than
+ * none. */
+export function compareVersions(a, b) {
+  const parts = (v) =>
+    String(v ?? "")
+      .split("-")[0]
+      .split(".")
+      .map((n) => Number(n) || 0);
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/** Ask npm. Returns the version string, or null for offline / not published /
+ * anything else. `exec` is injected so the tests never touch the network.
+ *
+ * npm installs as `npm.cmd` on Windows, so this goes through the same
+ * `runnableCommand` resolution as every other binary this package looks for -
+ * otherwise the version row lies and says "offline" on a machine with a
+ * perfectly good connection. */
+export const execNpm = (args, { timeoutMs = NPM_TIMEOUT_MS, platform = process.platform, env = process.env, exists, readFile, execImpl = execFile } = {}) =>
+  new Promise((resolve) => {
+    let resolved;
+    try {
+      resolved = runnableCommand("npm", args, { platform, env, ...(exists ? { exists } : {}), ...(readFile ? { readFile } : {}) });
+    } catch {
+      resolve({ ok: false, stdout: "" });
+      return;
+    }
+    execImpl(resolved.file, resolved.args, { timeout: timeoutMs, windowsHide: true, env, shell: resolved.shell }, (error, stdout) =>
+      resolve({ ok: !error, stdout: String(stdout ?? "") }),
+    );
+  });
+
+export async function latestFromNpm({ exec = execNpm, name = PACKAGE_NAME, timeoutMs = NPM_TIMEOUT_MS } = {}) {
+  const result = await exec(["view", name, "version"], { timeoutMs });
+  if (!result?.ok) return null;
+  const version = String(result.stdout).trim().split(/\s+/)[0];
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version) ? version : null;
+}
+
+/** The daily checker the daemon's beat calls.
+ *
+ * `mark()` is SYNCHRONOUS and cheap, because it is called from the liveness
+ * beat and the beat must never wait on the network: it returns what is known
+ * now and starts a check in the background if one is due. The first beat of a
+ * process therefore writes `updateAvailable: false` and the next one, after
+ * npm answers, writes the truth. */
+export function makeUpdateChecker({
+  version = packageVersion(),
+  latest = latestFromNpm,
+  intervalMs = DAY_MS,
+  now = () => Date.now(),
+  log = () => {},
+} = {}) {
+  // null rather than 0, so the FIRST beat always asks. With Date.now() a zero
+  // would happen to work; with an injected clock starting at zero it silently
+  // never checks, and the daemon that never checks is the whole failure this
+  // module is for.
+  let checkedAt = null;
+  let known = null;
+  let running = false;
+  const state = () => ({
+    version,
+    updateAvailable: known !== null && compareVersions(known, version) > 0,
+    ...(known ? { latest: known } : {}),
+  });
+  const run = async () => {
+    running = true;
+    checkedAt = now();
+    try {
+      const found = await latest();
+      if (found) {
+        known = found;
+        if (compareVersions(found, version) > 0) log(`update available: ${version} -> ${found} (npm i -g ${PACKAGE_NAME})`);
+      }
+    } catch {
+      /* offline is not an error worth a line every day */
+    } finally {
+      running = false;
+    }
+  };
+  return {
+    state,
+    /** What goes into the mark file, and a check kicked off when one is due. */
+    mark() {
+      if (!running && (checkedAt === null || now() - checkedAt >= intervalMs)) void run();
+      return { version: state().version, updateAvailable: state().updateAvailable };
+    },
+    /** Await one check. `doctor` and the tests use this. */
+    async once() {
+      await run();
+      return state();
+    },
+  };
+}
+
+/** A new terminal starts with the normal system PATH, then reads the user's
+ * shell startup files. Never mistake a one-off PATH export for persistence.
+ * Commands are fixed strings; credentials never enter a shell argument. */
+export async function verifyInstalledCli({
+  env = process.env, platform = process.platform, expectedVersion = packageVersion(),
+  scriptPath = fileURLToPath(new URL("../glytch.mjs", import.meta.url)),
+  // SIGKILL: an interactive zsh ignores SIGTERM, so a hung `mise which` from
+  // a shell-function manager (mise activate, asdf before 0.16) would hang init.
+  execFileImpl = execFile,
+  exec = (file, args, options) => new Promise((resolve) => {
+    execFileImpl(file, args, { ...options, shell: false, windowsHide: true, timeout: 15_000, killSignal: "SIGKILL" },
+      (error, stdout) => resolve({ ok: !error, stdout: String(stdout ?? "") }));
+  }),
+  resolvePath = realpath, resolveCommand = runnableCommand, allowVoltaPackage = false, log = () => {},
+} = {}) {
+  const cleanEnv = { ...env };
+  // Compatibility: also strip the old credential alias from installer children.
+  delete cleanEnv.GLYTCH_BOARD_TOKEN;
+  delete cleanEnv.VIEWABLE_BOARD_TOKEN;
+  delete cleanEnv.GLYTCH_SETUP_ID;
+  delete cleanEnv.VIEWABLE_SETUP_ID;
+  let result;
+  const shell = env.SHELL || "/bin/sh";
+  if (platform === "win32") {
+    // Read persisted PATH, not just the launching terminal's stale environment.
+    const script = '$env:Path=[Environment]::GetEnvironmentVariable("Path","Machine")+";"+[Environment]::GetEnvironmentVariable("Path","User"); $c=(Get-Command glytch.cmd -ErrorAction Stop).Source; Write-Output "GLYTCH_CLI=$c"; & $c -v; exit $LASTEXITCODE';
+    result = await exec("powershell.exe", ["-NonInteractive", "-Command", script], { env: cleanEnv });
+  } else {
+    cleanEnv.PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+    result = await exec(shell, ["-lic", 'printf "GLYTCH_CLI=%s\\n" "$(command -v glytch)"; glytch -v'], { env: cleanEnv });
+  }
+  const output = result?.stdout?.trim() ?? "";
+  const command = /^GLYTCH_CLI=(.+)$/m.exec(output)?.[1]?.trim();
+  const version = output.split(/\r?\n/).at(-1)?.trim();
+  let actualScript;
+  let verifiedScriptPath = scriptPath;
+  let mustMatchScript = platform === "win32";
+  try {
+    // `command -v` prints a bare name for a shell function or alias, and a
+    // relative name would resolve against the folder init runs in.
+    if (platform !== "win32" && command && !posix.isAbsolute(command)) throw new Error("Relative CLI command");
+    const runningScript = await resolvePath(scriptPath).catch(() => scriptPath);
+    if (platform === "win32" && command) {
+      const resolved = resolveCommand(command, [], { platform, env: cleanEnv });
+      actualScript = resolved.args[0];
+    } else if (command) actualScript = command;
+    // Volta puts one shared launcher (volta-shim) on PATH for every tool it
+    // installs, so the command never resolves to our script. Ask Volta, in the
+    // same fresh shell, which file that launcher would run (#707).
+    if (platform !== "win32" && actualScript && basename(await resolvePath(actualScript)) === "volta-shim") {
+      mustMatchScript = true;
+      // Homebrew's bin directory may be absent from the fresh shell's PATH.
+      // Use the binary beside the resolved launcher, quoting it as shell data.
+      const voltaPath = posix.join(posix.dirname(await resolvePath(actualScript)), "volta");
+      const volta = await exec(shell, ["-lic", `'${voltaPath.replaceAll("'", "'\\''")}' which glytch`], { env: cleanEnv });
+      actualScript = volta?.ok ? volta.stdout.trim().split(/\r?\n/).at(-1)?.trim() : null;
+      // Only update may replace npm's Node-image guess with Volta's package
+      // image. Init must still verify the running script before registering it.
+      if (allowVoltaPackage) {
+        // Resolve the PATH directory before traversing out of Volta's bin:
+        // its spelling may itself be a symlink outside VOLTA_HOME.
+        const shimDirectory = await resolvePath(posix.dirname(command));
+        const packageScript = posix.join(shimDirectory, "..", "tools", "image", "packages", PACKAGE_NAME, "lib", "node_modules", PACKAGE_NAME, "glytch.mjs");
+        verifiedScriptPath = await resolvePath(packageScript);
+      }
+    } else if (platform !== "win32" && actualScript) {
+      actualScript = await resolvePath(actualScript);
+      // asdf uses a script shim; mise may use a script or a symlink to mise.
+      // Read the launcher rather than assuming a default shims directory:
+      // both managers support custom locations.
+      let launcher = "";
+      if (actualScript !== runningScript && basename(actualScript) !== "mise") {
+        try { launcher = readFileSync(actualScript, "utf8").slice(0, 4096); } catch { /* path-only diagnostic below */ }
+      }
+      const manager = basename(actualScript) === "mise" || /^exec .*\bmise\b/m.test(launcher) ? "mise"
+        : /^exec .*\basdf\b/m.test(launcher) ? "asdf" : null;
+      if (manager) {
+        const located = await exec(shell, ["-lic", manager === "asdf" ? "asdf which glytch" : "mise which glytch"], { env: cleanEnv });
+        actualScript = located?.ok ? located.stdout.trim().split(/\r?\n/).at(-1)?.trim() : null;
+        if (!actualScript) throw new Error("No installed script");
+        verifiedScriptPath = await resolvePath(actualScript);
+        actualScript = verifiedScriptPath;
+      } else if (basename(actualScript) !== "glytch.mjs") {
+        // A matching version does not make a shell wrapper runnable by Node.
+        // Without a known manager, only the resolved JS entry may be used.
+        throw new Error("Unresolved CLI launcher");
+      }
+      verifiedScriptPath = actualScript;
+      // A same-version install can be reached through a launcher or another
+      // global prefix. Its PATH spelling is useful evidence, not a gate (#600).
+      log(`Viewable PATH ${command} ${(await resolvePath(command)) === runningScript ? "matches" : "differs from"} ${scriptPath}.`);
+    }
+    if (actualScript) actualScript = await resolvePath(actualScript);
+    if (mustMatchScript && actualScript && actualScript !== await resolvePath(verifiedScriptPath)) {
+      // npm may still expose the old package's bin. Follow only our exact
+      // forwarder, using Node's resolution from that installed package.
+      const forwarder = "#!/usr/bin/env node\nprocess.stderr.write(\"Glytch is now Viewable: npx viewable-one\\n\");\nawait import(\"viewable-one/glytch.mjs\");";
+      if (readFileSync(actualScript, "utf8").replace(/\r\n/g, "\n").trim() === forwarder) {
+        actualScript = await resolvePath(createRequire(actualScript).resolve("viewable-one/glytch.mjs"));
+      }
+      if (actualScript !== await resolvePath(verifiedScriptPath)) actualScript = null;
+    }
+  } catch { actualScript = null; }
+  // Whatever path comes back is what the service will run with Node, so it
+  // must be an absolute path to a glytch.mjs, whichever manager named it.
+  const runnable = (platform === "win32" ? win32 : posix).isAbsolute(verifiedScriptPath ?? "") && /(^|[\\/])glytch\.mjs$/.test(verifiedScriptPath);
+  if (!result?.ok || version !== expectedVersion || !actualScript || !runnable || [scriptPath, command, actualScript, verifiedScriptPath].some((path) => /[\\/]_npx[\\/]/.test(path ?? ""))) {
+    return { ok: false, error: "Viewable could not be verified in a new normal terminal. Install with npm i -g viewable-one@latest without sudo, persist the npm bin directory in your shell startup configuration or Windows user PATH, then open a new terminal and check glytch -v. Setup is not Connected." };
+  }
+  return { ok: true, version, scriptPath: verifiedScriptPath };
+}
+
+/** The script init registers: the one a fresh terminal proved, never merely
+ * the one running now. A same-version copy in a temporary folder passes the
+ * version check, and a service pointed at it breaks once it is deleted. With
+ * service changes disabled nothing is verified and the default stands. */
+export async function initServiceScript({ env = process.env, verify = verifyInstalledCli, log = () => {} } = {}) {
+  if (noDaemonInstall(env)) return { ok: true };
+  const checked = await verify({ env, log });
+  return checked.ok ? { ok: true, scriptPath: checked.scriptPath } : checked;
+}
+
+/** Explicit only. Installation finishes before touching the existing service.
+ * No init/login/config rewrite, agent execution, or automatic updater. */
+export async function runUpdate({
+  env = process.env, platform = process.platform, exec = execNpm,
+  verify = verifyInstalledCli, sync, wait = waitForRunnerHealth,
+  readHealth = () => readRunnerHealth(env), now = Date.now, log = () => {},
+} = {}) {
+  const failure = (error) => ({ ok: false, error });
+  if (noDaemonInstall(env)) return failure("Service changes are disabled. Nothing was installed or restarted.");
+  const npm = (args, options) => exec(args, { env, platform, ...options });
+  const latest = await latestFromNpm({ exec: npm });
+  if (!latest) return failure("Could not check the latest published version. Check your connection and try viewable update again. Nothing was restarted.");
+  const root = await npm(["root", "-g"]);
+  if (!root?.ok || !root.stdout.trim()) return failure("Could not find the npm installation directory. Check npm and try again.");
+  const scriptPath = (platform === "win32" ? win32 : { join }).join(root.stdout.trim(), PACKAGE_NAME, "glytch.mjs");
+  log(`Installing Viewable ${latest}…`);
+  const installed = await npm(["install", "-g", `${PACKAGE_NAME}@${latest}`, "--force"], { timeoutMs: 180_000 });
+  if (!installed?.ok) return failure("Installation failed. Check your connection and npm directory permissions; never run sudo. The service was left alone. Retry viewable update after fixing the install.");
+  const checked = await verify({ env, platform, expectedVersion: latest, scriptPath, allowVoltaPackage: true, log });
+  if (!checked.ok) return failure(`The package was installed, but ${checked.error}`);
+  const before = readHealth();
+  const after = now();
+  const restart = sync ?? (await import("./sync.mjs")).syncLaunchAgent;
+  let result;
+  try { result = await restart({ env, platform, scriptPath: checked.scriptPath, version: latest, restart: true }); }
+  catch { return failure("The package was installed, but restarting failed. Folders and sign-in were kept. Run viewable doctor, then retry viewable update."); }
+  if (!result.ok || /not loaded|no systemd|not registered|not restarted/.test(result.state)) {
+    return failure(`Viewable ${latest} was installed, but your computer did not restart: ${result.detail}. Run viewable doctor, then retry viewable update.`);
+  }
+  const health = await wait({ env, version: latest, after, previousInstance: before?.instance });
+  if (!health.ok) return failure(`Viewable ${latest} was installed, but ${health.error}`);
+  log(`Viewable ${latest} is installed. Your computer restarted and has a fresh connection.`);
+  return { ok: true, version: latest };
+}

package/lib/usageLimit.mjs

@@ -0,0 +1,108 @@
+// A PLAN OUT OF USAGE, READ FROM THE AGENT'S OWN WORDS (#482, ruling #470:
+// "plan out of usage with the time it comes back"). Claude Code and Codex
+// each end a turn with an error when the person's plan has no usage left, and
+// each says when it comes back. This reads that sentence and nothing else:
+// no call to either company, no guess when the words carry no time.
+//
+// The runner keeps the result in the row's sidecar (`usageLimit`), and the
+// app says "Your Claude plan is out of usage for now. It comes back at 4 PM."
+//
+// The samples it knows (bridge/test/usageLimit.test.mjs has each one):
+//   Claude Code   "Claude AI usage limit reached|1760536800"   (epoch seconds)
+//                 "5-hour limit reached ∙ resets 4pm"
+//                 "You've hit your limit · resets 4pm (Europe/London)"
+//                 "Weekly limit reached ∙ resets Oct 16, 3pm"
+//   Codex         "You've hit your usage limit. ... try again at 4:05 PM."
+//                 "... or try again at Oct 16th, 2026 4:05 PM."
+//                 "... try again in 2 hours 5 minutes."
+
+const LIMIT = /usage limit|limit reached|hit your limit|out of usage|rate_limit_exceeded|usageLimitExceeded/i;
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+
+/** The wall clock in `timeZone` at `at`, as if it were UTC, in ms. */
+function wallMs(at, timeZone) {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat("en-US", {
+      timeZone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit",
+      hour: "2-digit", minute: "2-digit", second: "2-digit",
+    }).formatToParts(at).map((p) => [p.type, p.value]),
+  );
+  return Date.UTC(+parts.year, +parts.month - 1, +parts.day, +parts.hour, +parts.minute, +parts.second);
+}
+
+/** The next moment after `now` that reads `hour:minute` (on `month`/`day`
+ *  when given) on a clock in `timeZone`, or this computer's own clock. */
+function nextAt(now, { hour, minute, month, day, year }, timeZone) {
+  let zone = timeZone;
+  try { if (zone) new Intl.DateTimeFormat("en-US", { timeZone: zone }); } catch { zone = undefined; }
+  const offset = zone ? wallMs(now, zone) - now.getTime() : -now.getTimezoneOffset() * 60_000;
+  const wallNow = new Date(now.getTime() + offset);
+  const pick = (y, m, d) => Date.UTC(y, m, d, hour, minute) - offset;
+  if (month !== undefined) {
+    let at = pick(year ?? wallNow.getUTCFullYear(), month, day);
+    if (year === undefined && at <= now.getTime()) at = pick(wallNow.getUTCFullYear() + 1, month, day);
+    return new Date(at);
+  }
+  let at = pick(wallNow.getUTCFullYear(), wallNow.getUTCMonth(), wallNow.getUTCDate());
+  if (at <= now.getTime()) at += 24 * 60 * 60_000;
+  return new Date(at);
+}
+
+/** "4pm", "4:05 PM", "16:05" as {hour, minute}, or null. */
+function clockOf(text) {
+  const m = /^(\d{1,2})(?::(\d{2}))?\s*([ap]\.?m\.?)?$/i.exec(text.trim());
+  if (!m) return null;
+  let hour = Number(m[1]);
+  const minute = Number(m[2] ?? 0);
+  const half = m[3]?.[0]?.toLowerCase();
+  if (!half && m[2] === undefined) return null;
+  if (half === "p" && hour < 12) hour += 12;
+  if (half === "a" && hour === 12) hour = 0;
+  return hour < 24 && minute < 60 ? { hour, minute } : null;
+}
+
+/** "Oct 16" or "Oct 16th, 2026" as {month, day, year?}, or null. */
+function dateOf(text) {
+  const m = /^([A-Za-z]{3})[a-z]*\.?\s+(\d{1,2})(?:st|nd|rd|th)?(?:,?\s+(\d{4}))?$/.exec(text.trim());
+  const month = m ? MONTHS.indexOf(m[1].toLowerCase()) : -1;
+  return month < 0 ? null : { month, day: Number(m[2]), ...(m[3] ? { year: Number(m[3]) } : {}) };
+}
+
+/** When the plan comes back, from one stretch of the agent's words. */
+function resetOf(text, now) {
+  // Claude Code's older form: the epoch after a bar.
+  const epoch = /usage limit reached\|(\d{10,13})/i.exec(text);
+  if (epoch) {
+    const n = Number(epoch[1]);
+    return new Date(epoch[1].length > 10 ? n : n * 1000);
+  }
+  // "try again in 2 hours 5 minutes", "try again in 3 days 1 hour".
+  const span = /try again in ((?:\d+\s*(?:days?|hours?|minutes?|mins?|seconds?|secs?)[\s,and]*)+)/i.exec(text);
+  if (span) {
+    let ms = 0;
+    for (const [, n, unit] of span[1].matchAll(/(\d+)\s*(d|h|m|s)/gi)) {
+      ms += Number(n) * { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1000 }[unit.toLowerCase()];
+    }
+    if (ms > 0) return new Date(now.getTime() + ms);
+  }
+  // "resets 4pm (Europe/London)", "resets Oct 16, 3pm", "try again at Oct
+  // 16th, 2026 4:05 PM", "reset at 4pm".
+  const at = /(?:\bresets?(?:\s+at)?|try again at)\s+([^\n]+)/i.exec(text);
+  if (!at) return undefined;
+  const zone = /\(([A-Za-z_]+\/[A-Za-z_/+-]+|UTC)\)/.exec(at[1])?.[1];
+  const words = at[1].split("(")[0].replace(/\.(\s.*)?$/, "").trim();
+  const clockAt = /(\d{1,2}(?::\d{2})?\s*(?:[ap]\.?m\.?)?)$/i.exec(words);
+  const clock = clockAt ? clockOf(clockAt[1]) : null;
+  if (!clock) return undefined;
+  const date = dateOf(words.slice(0, clockAt.index).replace(/[,\s]+$/, ""));
+  return nextAt(now, { ...clock, ...(date ?? {}) }, zone);
+}
+
+/** Did the agent say the plan is out of usage? `{resetsAt}` (an ISO time,
+ *  absent when the words carry none) or null when it said something else. */
+export function readUsageLimit(text, { now = new Date() } = {}) {
+  const words = typeof text === "string" ? text : "";
+  if (!LIMIT.test(words)) return null;
+  const resetsAt = resetOf(words, now);
+  return resetsAt && !Number.isNaN(resetsAt.getTime()) ? { resetsAt: resetsAt.toISOString() } : {};
+}

package/lib/windows-command.mjs

@@ -0,0 +1,85 @@
+// Resolve Windows npm shims to their JavaScript entry points. Passing request
+// arguments through cmd.exe would let shell metacharacters in model/session
+// metadata run commands before an agent's own permission checks apply.
+import { existsSync, readFileSync } from "node:fs";
+import { win32 } from "node:path";
+
+export const DEFAULT_PATHEXT = [".COM", ".EXE", ".BAT", ".CMD"];
+
+const splitList = (value) => String(value ?? "").split(";").map((s) => s.trim()).filter(Boolean);
+const isPathLike = (bin) => /[\\/]/.test(bin) || /^[a-z]:/i.test(bin);
+const envLookup = (env, name) => {
+  const key = Object.keys(env ?? {}).find((k) => k.toUpperCase() === name.toUpperCase());
+  return key ? env[key] : undefined;
+};
+
+/** npm/cmd-shim forwards %* to either a Node script or a native executable
+ * under its own directory. Parse only that rooted, quoted target. Older
+ * OpenCode packages have an extensionless Node script; newer ones can point
+ * directly at opencode.exe. Arbitrary batch programs fail closed.
+ */
+function shimTarget(shim, { exists, readFile, nodePath }) {
+  let source;
+  try { source = readFile(shim, "utf8"); } catch { return null; }
+  if (!/^@echo off\s*$/im.test(source) && !/^@?IF EXIST "%(?:~dp0|dp0%)[\\/]node\.exe"\s*\(/im.test(source)) return null;
+  const targets = [...source.matchAll(/"%(?:~dp0|dp0%)[\\/]([^"\r\n]+)"\s+%\*(?=\s|$)/gim)];
+  if (targets.length === 0) return null;
+  const target = win32.resolve(win32.dirname(shim), targets[0][1]);
+  // Older npm shims repeat the same entry in IF/ELSE Node-launch branches.
+  // Resolve every match and refuse divergent targets rather than picking one.
+  if (targets.some((match) => win32.resolve(win32.dirname(shim), match[1]).toLowerCase() !== target.toLowerCase())) return null;
+  if (!exists(target)) return null;
+  const lines = targets.map((match) => source.slice(source.lastIndexOf("\n", match.index) + 1, match.index));
+  const line = lines[0];
+  if (targets.length === 1 && /\.(?:exe|com)$/i.test(target) && !/"%_prog%"\s*$/i.test(line)) {
+    return { file: target, prefix: [] };
+  }
+  const nodeLauncher = lines.every((candidate) => /(?:"%_prog%"|"%(?:~dp0|dp0%)[\\/]node\.exe"|\bnode(?:\.exe)?)\s*$/i.test(candidate));
+  if (!nodeLauncher || !/\bnode\b/i.test(source)) return null;
+  if (!/\.(?:js|mjs|cjs)$/i.test(target)) {
+    let firstLine;
+    try { firstLine = String(readFile(target, "utf8")).split(/\r?\n/, 1)[0]; } catch { return null; }
+    if (!/^#!.*(?:\s|\/)node(?:\.exe)?(?:\s|$)/i.test(firstLine)) return null;
+  }
+  return { file: nodePath, prefix: [target] };
+}
+
+/** The file a Windows `Path` x `PATHEXT` search finds for `bin`, or null.
+ * The one search both `runnableCommand` and detect.mjs's
+ * `resolveAgentBinary` use, so "can it be found" and "what gets spawned"
+ * never disagree. A bin that already carries a PATHEXT extension and names
+ * a place is returned as given; its existence is the spawn's to report.
+ */
+export function findWindowsCommand(bin, { env = process.env, exists = existsSync } = {}) {
+  const pathext = splitList(envLookup(env, "PATHEXT") || DEFAULT_PATHEXT.join(";"));
+  const dirs = splitList(envLookup(env, "Path"));
+  if (/\.(?:com|exe|bat|cmd)$/i.test(bin) && !isPathLike(bin)) {
+    return dirs.map((dir) => win32.join(dir, bin)).find(exists) ?? null;
+  }
+  if (pathext.some((ext) => bin.toLowerCase().endsWith(ext.toLowerCase()))) return bin;
+  if (isPathLike(bin)) return pathext.map((ext) => `${bin}${ext}`).find(exists) ?? null;
+  return dirs.flatMap((dir) => pathext.map((ext) => win32.join(dir, `${bin}${ext}`))).find(exists) ?? null;
+}
+
+/** Return a shell-free spawn description on every platform. An unresolved
+ * command is left to Node's ordinary ENOENT reporting, never cmd.exe search.
+ * Injectable filesystem hooks permit Windows-resolution tests on POSIX.
+ */
+export function runnableCommand(bin, args = [], {
+  platform = process.platform,
+  env = process.env,
+  exists = existsSync,
+  readFile = readFileSync,
+  nodePath = process.execPath,
+} = {}) {
+  if (platform !== "win32") return { file: bin, args, shell: false };
+
+  const target = findWindowsCommand(bin, { env, exists }) ?? bin;
+
+  if (/\.(?:cmd|bat)$/i.test(target)) {
+    const resolved = shimTarget(target, { exists, readFile, nodePath });
+    if (!resolved) throw new Error(`Cannot safely launch Windows batch command: ${target}`);
+    return { file: resolved.file, args: [...resolved.prefix, ...args], shell: false };
+  }
+  return { file: target, args, shell: false };
+}