@remodex/rmx 1.0.2

package/src/lib/upstream-retry.ts

@@ -0,0 +1,508 @@
+/**
+ * Retry guard for upstream fetches that die on stale pooled keep-alive sockets.
+ *
+ * chatgpt.com (Cloudflare) closes idle keep-alive connections server-side; Bun's fetch pool
+ * reuses the half-closed socket and the request write fails with ECONNRESET before any
+ * response bytes arrive. Retrying on a fresh connection is safe for our replayable
+ * (string-body) upstream requests, because fetch() rejects only before response headers —
+ * a caught error here means no response was ever received.
+ *
+ * Deliberately narrow: timeouts, aborts, ECONNREFUSED/DNS/TLS failures, and HTTP error
+ * statuses (returned as Response, never thrown) are NOT retried. Mid-stream SSE resets are
+ * out of scope — the response has already resolved by then.
+ *
+ * MUST stay a leaf module: imports nothing from server.ts or adapters (kiro-retry imports
+ * the shared abort helpers from here).
+ */
+import { clearableDeadline } from "./abort";
+import { readBoundedResponseBody } from "./bounded-body";
+
+// 1 initial + 2 retries: the pool may hold more than one stale socket.
+const RESET_RETRY_MAX_ATTEMPTS = 3;
+const RESET_RETRY_BASE_DELAY_MS = 150;
+const RESET_RETRY_MAX_DELAY_MS = 1_000;
+
+// Transient-5xx status retry layer (pre-stream only; devlog/_plan/260716_claudecode_hardening/010).
+const TRANSIENT_RETRY_MAX_ATTEMPTS = 3; // 1 initial + 2 retries
+const TRANSIENT_RETRY_BASE_DELAY_MS = 400;
+const TRANSIENT_RETRY_MAX_DELAY_MS = 5_000;
+// A failed attempt slower than this is the "slow 502" incident shape (191s observed on
+// 2026-07-15): retrying it only duplicates upstream load past client timeouts — return it.
+const TRANSIENT_RETRY_SLOW_ATTEMPT_MS = 15_000;
+const NON_JSON_INSPECTION_MAX_BYTES = 8 * 1024;
+const NON_JSON_INSPECTION_TIMEOUT_MS = 1_000;
+
+/**
+ * Upstream statuses treated as transient: gateway errors and Cloudflare 52x.
+ * 500 is included per the OpenAI SDK default (auto-retries >=500; Tier-2 proven in
+ * devlog/260716_ocx_claude_sol_502_midstream/02). 507 was observed in the 48h ledger
+ * but is deliberately excluded (storage-class, not gateway-transient).
+ */
+export function isTransientUpstreamStatus(status: number): boolean {
+  return status === 500 || status === 502 || status === 503 || status === 504
+    || status === 520 || status === 521 || status === 522;
+}
+
+export interface RetryBackoffOptions {
+  baseDelayMs: number;
+  maxDelayMs: number;
+  headers?: Headers;
+}
+
+export function abortError(signal?: AbortSignal): unknown {
+  return signal?.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+export async function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return;
+  if (signal?.aborted) throw abortError(signal);
+  await new Promise<void>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout>;
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(abortError(signal));
+    };
+    timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Best-effort, bounded cancellation of a response body before a retry backoff.
+ *
+ * The 429 paths release the unread body before waiting so sockets do not accumulate under a
+ * rate-limit storm, but a never-settling `cancel()` promise must not be able to block the
+ * abort-aware backoff (client cancel, `maxIntervalMs`, or the cumulative header deadline).
+ * Cancellation is started and its rejection observed; the await is bounded by `timeoutMs`
+ * and the abort signal. This mirrors the rotation-path guarantee (release is initiated, not
+ * awaited forever) while preserving the resource-release intent of the same-target paths.
+ */
+export async function releaseResponseBodyBestEffort(
+  body: ReadableStream<Uint8Array> | null,
+  signal: AbortSignal | undefined,
+  timeoutMs = 1_000,
+): Promise<void> {
+  if (!body) return;
+  if (signal?.aborted) {
+    void body.cancel().catch(() => {});
+    return;
+  }
+  const cancel = body.cancel().catch(() => {});
+  if (!signal) {
+    await Promise.race([cancel, new Promise<void>(resolve => setTimeout(resolve, timeoutMs))]);
+    return;
+  }
+  await new Promise<void>(resolve => {
+    let timer: ReturnType<typeof setTimeout>;
+    /**
+     * Abort hook: clear the bounded-body release timer and settle the promise so a
+     * never-settling cancel() can never block the abort-aware backoff.
+     */
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, timeoutMs);
+    signal.addEventListener("abort", onAbort, { once: true });
+    void cancel.then(() => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Abort-aware sleep that yields an adapter `heartbeat` at least every `heartbeatIntervalMs`.
+ * The Responses bridge treats a returned iterator event as upstream liveness and aborts turns
+ * that stay silent past the stall budget (default 300s), while a retryOn429 wait may legally
+ * reach 600s — so deliberate waits must keep the watchdog fed or a long backoff is killed
+ * mid-turn. The final chunk always yields once, which doubles as the post-wait liveness beat.
+ */
+export async function* sleepWithHeartbeats(
+  ms: number,
+  signal?: AbortSignal,
+  heartbeatIntervalMs = 10_000,
+): AsyncGenerator<{ type: "heartbeat" }> {
+  if (ms <= 0) return;
+  // Guard against a non-positive interval: a zero/negative step would spin the loop forever
+  // while sleepWithAbort early-returns without ever observing the abort signal. NaN must be
+  // normalized too: Math.max(1, NaN) is NaN, which would abort the wait after one beat.
+  const stepMs = Number.isNaN(heartbeatIntervalMs) ? 1 : Math.max(1, heartbeatIntervalMs);
+  let remaining = ms;
+  while (remaining > 0) {
+    const chunk = Math.min(remaining, stepMs);
+    await sleepWithAbort(chunk, signal);
+    remaining -= chunk;
+    yield { type: "heartbeat" };
+  }
+}
+
+export interface SameTarget429WaitOptions {
+  body: ReadableStream<Uint8Array> | null;
+  signal?: AbortSignal;
+  delayMs: number;
+  /**
+   * When set, the wait yields adapter heartbeats so bridge stall watchdogs stay fed.
+   * Omit for pre-stream recovery paths that have no stall watchdog.
+   */
+  heartbeatIntervalMs?: number;
+}
+
+/**
+ * Shared pre-replay prep for opt-in same-target 429 waits:
+ * release the unread 429 body, then sleep (optionally with heartbeats).
+ * Callers still own attempt budgeting, abort re-checks, and the replay itself.
+ */
+export async function* prepareSameTarget429Wait(
+  options: SameTarget429WaitOptions,
+): AsyncGenerator<{ type: "heartbeat" }> {
+  await releaseResponseBodyBestEffort(options.body, options.signal);
+  if (options.heartbeatIntervalMs === undefined) {
+    await sleepWithAbort(options.delayMs, options.signal);
+    return;
+  }
+  yield* sleepWithHeartbeats(options.delayMs, options.signal, options.heartbeatIntervalMs);
+}
+
+export function isConnectionResetError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  // Aborts and timeouts are caller decisions / honest failures — never retryable.
+  if (err.name === "AbortError" || err.name === "TimeoutError") return false;
+  const code = (err as { code?: unknown }).code;
+  if (code === "ECONNRESET" || code === "EPIPE") return true;
+  const msg = err.message.toLowerCase();
+  return msg.includes("socket connection was closed unexpectedly")
+    || msg.includes("connection reset by peer");
+}
+
+function retryAfterDelayMs(headers: Headers): number | undefined {
+  const raw = headers.get("retry-after")?.trim();
+  if (!raw) return undefined;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const dateMs = Date.parse(raw);
+  if (!Number.isFinite(dateMs)) return undefined;
+  return Math.max(0, dateMs - Date.now());
+}
+
+export function retryBackoffDelayMs(attempt: number, opts: RetryBackoffOptions): number {
+  const retryAfter = opts.headers ? retryAfterDelayMs(opts.headers) : undefined;
+  if (retryAfter !== undefined) return Math.min(retryAfter, opts.maxDelayMs);
+  const exp = Math.min(opts.baseDelayMs * (2 ** attempt), opts.maxDelayMs);
+  return Math.floor(exp * (0.8 + Math.random() * 0.4));
+}
+
+export function cancelResponseBodyBestEffort(res: Response): void {
+  try {
+    const cancellation = res.body?.cancel();
+    if (cancellation) void cancellation.catch(() => {});
+  } catch {
+    // Cancellation is cleanup only; retries must not wait for or fail because of it.
+  }
+}
+
+export async function fetchWithAttemptDeadline(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+  abortSignal?: AbortSignal,
+  preferIdentityEncoding = false,
+): Promise<Response> {
+  const attemptTimeout = clearableDeadline(timeoutMs, abortSignal);
+  const headers = new Headers(init.headers);
+  if (preferIdentityEncoding && !headers.has("accept-encoding")) {
+    headers.set("accept-encoding", "identity");
+  }
+  try {
+    return await fetch(url, {
+      ...init,
+      headers,
+      signal: attemptTimeout.signal,
+    });
+  } finally {
+    // Only the header timer is cleared. The composed signal still contains the parent, so a
+    // caller abort after headers continue to cancel consumption of the returned response body.
+    attemptTimeout.clear();
+  }
+}
+
+export interface ResetRetryOptions {
+  abortSignal?: AbortSignal;
+  /** Short host/path label for the retry warn log (no secrets/query strings). */
+  label?: string;
+  attempts?: number;
+}
+
+export interface TransientRetryOptions extends ResetRetryOptions {
+  /** Test seam: per-attempt slow budget override (defaults to TRANSIENT_RETRY_SLOW_ATTEMPT_MS). */
+  slowAttemptMs?: number;
+}
+
+export interface TransientNonJsonRetryOptions extends TransientRetryOptions {
+  /**
+   * Provider-owned HTTP statuses whose non-JSON response body is known to be an
+   * intermittent edge failure. Empty/absent policy is intentionally unsupported:
+   * callers must opt in with an explicit closed list.
+   */
+  statuses: readonly number[];
+}
+
+export type UpstreamSendRecovery =
+  | "connection-reset"
+  | "transient-5xx"
+  | "transient-non-json";
+type ReplayableFetch = (recovery?: UpstreamSendRecovery) => Promise<Response>;
+
+/**
+ * Rejection thrown by the upstream retry helpers when the terminal attempt
+ * rejects after earlier attempts already produced credential-visible evidence:
+ * transient HTTP responses, or a connection reset after the request was read.
+ *
+ * That evidence proves the host and credential path were reached, so the
+ * failure must stay account-attributed even though the terminal promise looks
+ * like a transport rejection (issue #914 review: mixed 5xx/reset -> rejection
+ * must not be downgraded to the account-neutral pre-connection class). The
+ * original rejection is preserved as `cause` so its code and message stay
+ * inspectable. Extracted from PR #966 (Yuxin-Qiao) with attribution.
+ */
+export class UpstreamRetryEvidenceError extends Error {
+  constructor(
+    public readonly transientStatuses: readonly number[],
+    cause: unknown,
+    /** True when a connection-reset retry already reached the origin. */
+    public readonly resetSeen = false,
+  ) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    const kinds: string[] = [];
+    if (transientStatuses.length > 0) kinds.push("transient HTTP response(s)");
+    if (resetSeen) kinds.push("a credential-visible connection reset");
+    super(
+      kinds.length > 0
+        ? `upstream fetch failed after ${kinds.join(" and ")}: ${detail}`
+        : `upstream fetch failed: ${detail}`,
+      { cause },
+    );
+    this.name = "UpstreamRetryEvidenceError";
+  }
+}
+
+/**
+ * Opt out of Bun's keep-alive pool after a connection-reset retry.
+ *
+ * Prefer the Bun fetch extension `keepalive: false` (transport-level) over
+ * relying on the hop-by-hop `Connection: close` header alone — Bun has ignored
+ * that header in past releases (oven-sh/bun#20492), so a header-only retry can
+ * still reuse the same half-closed pooled socket. Still set Connection: close
+ * as a belt-and-suspenders signal for intermediaries that honor it.
+ */
+export function applyUpstreamRecoveryInit<T extends RequestInit>(
+  init: T,
+  recovery?: UpstreamSendRecovery,
+): T & { headers: Headers } {
+  const headers = new Headers(init.headers);
+  if (recovery !== "connection-reset" && recovery !== "transient-non-json") {
+    return { ...init, headers };
+  }
+  headers.set("connection", "close");
+  return { ...init, headers, keepalive: false };
+}
+
+/**
+ * Run `doFetch`, retrying only connection-reset-shaped rejections (see
+ * isConnectionResetError) with jittered backoff. The caller's thunk must be replay-safe
+ * (string body); every retry is logged so persistent resets stay visible.
+ */
+export async function fetchWithResetRetry(
+  doFetch: ReplayableFetch,
+  opts: ResetRetryOptions = {},
+  firstRecovery?: UpstreamSendRecovery,
+): Promise<Response> {
+  const attempts = Math.max(1, opts.attempts ?? RESET_RETRY_MAX_ATTEMPTS);
+  let lastError: unknown;
+  let sawReset = false;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    if (opts.abortSignal?.aborted) throw abortError(opts.abortSignal);
+    try {
+      return await doFetch(attempt === 0 ? firstRecovery : "connection-reset");
+    } catch (err) {
+      if (opts.abortSignal?.aborted) throw err;
+      if (!isConnectionResetError(err)) {
+        // A reset that already reached the origin is credential-visible
+        // evidence: keep it attached so the terminal rejection cannot be
+        // downgraded to the pre-connection neutral class (#914 review).
+        if (sawReset) throw new UpstreamRetryEvidenceError([], err, true);
+        throw err;
+      }
+      if (attempt === attempts - 1) throw err;
+      sawReset = true;
+      lastError = err;
+      console.warn(
+        `[upstream-retry] connection reset${opts.label ? ` (${opts.label})` : ""} — retrying (${attempt + 2}/${attempts})`,
+      );
+      await sleepWithAbort(retryBackoffDelayMs(attempt, {
+        baseDelayMs: RESET_RETRY_BASE_DELAY_MS,
+        maxDelayMs: RESET_RETRY_MAX_DELAY_MS,
+      }), opts.abortSignal);
+    }
+  }
+  throw lastError ?? new Error("upstream fetch failed");
+}
+
+/**
+ * fetchWithResetRetry plus a transient-5xx status retry layer, PRE-STREAM only: a
+ * returned Response has by definition not been relayed to the client yet, so replaying
+ * the (string-body) request is safe. The failed attempt's body is cancelled before the
+ * retry; every returned response (ok, non-transient, aborted, slow, exhausted) keeps
+ * its body intact. Honors Retry-After via retryBackoffDelayMs.
+ *
+ * A failed attempt slower than the slow budget is returned as-is (slow-502 shape);
+ * note `opts.attempts` is shared with the inner reset layer (no caller passes it today).
+ */
+export async function fetchWithTransientRetry(
+  doFetch: ReplayableFetch,
+  opts: TransientRetryOptions = {},
+): Promise<Response> {
+  const attempts = Math.max(1, opts.attempts ?? TRANSIENT_RETRY_MAX_ATTEMPTS);
+  const slowAttemptMs = opts.slowAttemptMs ?? TRANSIENT_RETRY_SLOW_ATTEMPT_MS;
+  const transientStatuses: number[] = [];
+  let attemptStart = Date.now();
+  let res = await fetchWithResetRetry(doFetch, opts);
+  for (let attempt = 0; attempt < attempts - 1; attempt++) {
+    if (res.ok || !isTransientUpstreamStatus(res.status)) return res;
+    if (opts.abortSignal?.aborted) return res;
+    if (Date.now() - attemptStart > slowAttemptMs) return res;
+    console.warn(
+      `[upstream-retry] transient ${res.status}${opts.label ? ` (${opts.label})` : ""} — retrying (${attempt + 2}/${attempts})`,
+    );
+    const delay = retryBackoffDelayMs(attempt, {
+      baseDelayMs: TRANSIENT_RETRY_BASE_DELAY_MS,
+      maxDelayMs: TRANSIENT_RETRY_MAX_DELAY_MS,
+      headers: res.headers,
+    });
+    cancelResponseBodyBestEffort(res);
+    await sleepWithAbort(delay, opts.abortSignal);
+    attemptStart = Date.now();
+    transientStatuses.push(res.status);
+    try {
+      res = await fetchWithResetRetry(doFetch, opts, "transient-5xx");
+    } catch (err) {
+      // Keep the prior 5xx evidence attached: the origin already responded, so
+      // this rejection is not pre-connection and must not classify as neutral.
+      throw new UpstreamRetryEvidenceError(transientStatuses, err);
+    }
+  }
+  return res;
+}
+
+function normalizedMediaType(response: Response): string {
+  return (response.headers.get("content-type") ?? "")
+    .split(";", 1)[0]!
+    .trim()
+    .toLowerCase();
+}
+
+function isJsonMediaType(mediaType: string): boolean {
+  return mediaType === "application/json" || mediaType.endsWith("+json");
+}
+
+async function isNonJsonRetryCandidate(
+  response: Response,
+  statuses: ReadonlySet<number>,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (!statuses.has(response.status)) return false;
+  if (signal?.aborted) throw abortError(signal);
+
+  const mediaType = normalizedMediaType(response);
+  // The observed Zen edge failure is an HTML Method Not Allowed page. Avoid
+  // teeing that body just to rediscover what the media type already proves.
+  if (mediaType === "text/html" || mediaType === "application/xhtml+xml") return true;
+  // A protocol-shaped SSE error is not the incident covered by this recovery.
+  if (mediaType === "text/event-stream") return false;
+
+  try {
+    const inspected = await readBoundedResponseBody(response.clone(), {
+      signal,
+      fatalUtf8: true,
+      maxBytes: NON_JSON_INSPECTION_MAX_BYTES,
+      totalTimeoutMs: NON_JSON_INSPECTION_TIMEOUT_MS,
+      inactivityTimeoutMs: NON_JSON_INSPECTION_TIMEOUT_MS,
+      firstByteTimeoutMs: NON_JSON_INSPECTION_TIMEOUT_MS,
+    });
+    if (!inspected.displaySafe || inspected.truncated) return false;
+    const text = inspected.text.trim();
+    if (!text) return true;
+    try {
+      JSON.parse(text);
+      return false;
+    } catch {
+      // Only textual, missing, or falsely JSON-labelled bodies qualify. Binary
+      // payloads fail closed even when they are not parseable as JSON.
+      return mediaType === "" || mediaType.startsWith("text/") || isJsonMediaType(mediaType);
+    }
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    return false;
+  }
+}
+
+/**
+ * Provider-opted pre-stream recovery for intermittent edge responses that use a
+ * deterministic-looking HTTP status but return an invalid/non-JSON body.
+ *
+ * The status list is registry-owned at the call site. A valid JSON error is
+ * always returned untouched, so genuine method/route mismatches are never hidden.
+ * Failed response bodies are cancelled before the abort-aware backoff, and the
+ * recovery send disables keep-alive to avoid reusing the same unhealthy edge.
+ */
+export async function fetchWithTransientNonJsonRetry(
+  doFetch: ReplayableFetch,
+  opts: TransientNonJsonRetryOptions,
+): Promise<Response> {
+  const statuses = new Set(
+    opts.statuses.filter(status => Number.isInteger(status) && status >= 400 && status <= 599),
+  );
+  if (statuses.size === 0) return fetchWithResetRetry(doFetch, opts);
+
+  const attempts = Math.max(1, opts.attempts ?? TRANSIENT_RETRY_MAX_ATTEMPTS);
+  const slowAttemptMs = opts.slowAttemptMs ?? TRANSIENT_RETRY_SLOW_ATTEMPT_MS;
+  const transientStatuses: number[] = [];
+  let attemptStart = Date.now();
+  let response = await fetchWithResetRetry(doFetch, opts);
+
+  for (let attempt = 0; attempt < attempts - 1; attempt++) {
+    if (response.ok || opts.abortSignal?.aborted) return response;
+    if (Date.now() - attemptStart > slowAttemptMs) return response;
+    if (!await isNonJsonRetryCandidate(response, statuses, opts.abortSignal)) return response;
+
+    console.warn(
+      `[upstream-retry] transient non-JSON ${response.status}${opts.label ? ` (${opts.label})` : ""} — retrying (${attempt + 2}/${attempts})`,
+    );
+    const delay = retryBackoffDelayMs(attempt, {
+      baseDelayMs: TRANSIENT_RETRY_BASE_DELAY_MS,
+      maxDelayMs: TRANSIENT_RETRY_MAX_DELAY_MS,
+      headers: response.headers,
+    });
+    cancelResponseBodyBestEffort(response);
+    await sleepWithAbort(delay, opts.abortSignal);
+    attemptStart = Date.now();
+    transientStatuses.push(response.status);
+    try {
+      response = await fetchWithResetRetry(doFetch, opts, "transient-non-json");
+    } catch (error) {
+      throw new UpstreamRetryEvidenceError(transientStatuses, error);
+    }
+  }
+  return response;
+}

package/src/lib/win-exec.ts

@@ -0,0 +1,115 @@
+/**
+ * Cross-platform command launching (devlog 260715_cross_platform_audit/020).
+ *
+ * Windows npm installs expose CLIs as `.cmd` shims, and Node/Bun refuse shell-less
+ * `.cmd` spawns (CVE-2024-27980 hardening). Bare names like `spawn("claude")` also
+ * skip PATHEXT resolution entirely, so they ENOENT even when `claude.cmd` is on PATH.
+ * This module mirrors the battle-tested cross-spawn approach: resolve the real target
+ * via PATH×PATHEXT, launch `.exe` targets directly (argument boundaries preserved by
+ * the normal shell-less spawn), and route `.cmd`/`.bat` targets through
+ * `cmd.exe /d /s /c "<escaped line>"` with `windowsVerbatimArguments: true`.
+ */
+import { existsSync } from "node:fs";
+import { win32 } from "node:path";
+
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+/** cross-spawn parse.js: only npm local-bin shims get double escaping. */
+const IS_CMD_SHIM = /node_modules[\\/].bin[\\/][^\\/]+\.cmd$/i;
+
+/** cross-spawn escape.js argument(): quote + escape one argument for cmd.exe /d /s /c. */
+export function escapeCmdArg(arg: string, doubleEscape = false): string {
+  let out = String(arg).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+  out = `"${out}"`.replace(CMD_META, "^$1");
+  return doubleEscape ? out.replace(CMD_META, "^$1") : out;
+}
+
+/** cross-spawn escape.js command(): escape the command token itself (no quoting). */
+export function escapeCmdCommand(command: string): string {
+  return command.replace(CMD_META, "^$1");
+}
+
+export interface ResolveDeps {
+  env?: Record<string, string | undefined>;
+  exists?: (path: string) => boolean;
+}
+
+/**
+ * Resolve a bare command name to its first PATH×PATHEXT hit (win32 semantics).
+ * Commands that already carry an extension, a separator, or an absolute prefix are
+ * returned unchanged; unresolvable names fall back unchanged (spawn will surface it).
+ */
+export function resolveWindowsCommand(command: string, deps: ResolveDeps = {}): string {
+  const env = deps.env ?? process.env;
+  const exists = deps.exists ?? existsSync;
+  if (win32.extname(command) || command.includes("\\") || command.includes("/") || win32.isAbsolute(command)) {
+    return command;
+  }
+  // Windows environment variables are case-insensitive, and a spawned child can
+  // arrive with `Path`, `PATH`, or both depending on who built its env. Reading
+  // only two fixed spellings silently resolved against the wrong list once a
+  // caller added a second casing, so match however the key is spelled.
+  const lookup = (name: string): string | undefined => {
+    const direct = env[name] ?? env[name.toUpperCase()] ?? env[name.toLowerCase()];
+    if (direct !== undefined) return direct;
+    const key = Object.keys(env).find(k => k.toLowerCase() === name.toLowerCase());
+    return key ? env[key] : undefined;
+  };
+  const exts = (lookup("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+  for (const dir of (lookup("PATH") ?? "").split(win32.delimiter).filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = win32.join(dir, command + ext.toLowerCase());
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return command;
+}
+
+export interface SpawnInvocation {
+  file: string;
+  args: string[];
+  options: { windowsVerbatimArguments?: boolean };
+}
+
+/**
+ * Platform-safe invocation preserving argument boundaries (cross-spawn parse.js).
+ * POSIX: passthrough. win32 `.exe`: resolved direct spawn. win32 `.cmd`/`.bat`:
+ * `ComSpec /d /s /c "<escaped command line>"` with verbatim args; npm local-bin
+ * shims get cross-spawn's double escaping, all other batch targets single.
+ */
+export function commandInvocation(
+  command: string,
+  args: readonly string[],
+  platform: NodeJS.Platform = process.platform,
+  deps: ResolveDeps = {},
+): SpawnInvocation {
+  if (platform !== "win32") return { file: command, args: [...args], options: {} };
+  const resolved = resolveWindowsCommand(command, deps);
+  if (!/\.(cmd|bat)$/i.test(resolved)) return { file: resolved, args: [...args], options: {} };
+  const env = deps.env ?? process.env;
+  const doubleEscape = IS_CMD_SHIM.test(resolved);
+  const line = [escapeCmdCommand(resolved), ...args.map(a => escapeCmdArg(a, doubleEscape))].join(" ");
+  return {
+    file: env.ComSpec ?? "cmd.exe",
+    args: ["/d", "/s", "/c", `"${line}"`],
+    options: { windowsVerbatimArguments: true },
+  };
+}
+
+/**
+ * `sh -c <command>` analog per platform. The configured command string is passed
+ * VERBATIM in content; on win32 it gets the outer quotes `/s` requires, so
+ * `"C:\Program Files\x.exe" --json` runs as `cmd.exe /d /s /c ""C:\Program Files\x.exe" --json"`.
+ * Contract: the command is platform-native shell syntax (sh on POSIX, CMD on Windows).
+ */
+export function shellInvocation(
+  command: string,
+  platform: NodeJS.Platform = process.platform,
+  env: Record<string, string | undefined> = process.env,
+): SpawnInvocation {
+  if (platform !== "win32") return { file: "sh", args: ["-c", command], options: {} };
+  return {
+    file: env.ComSpec ?? "cmd.exe",
+    args: ["/d", "/s", "/c", `"${command}"`],
+    options: { windowsVerbatimArguments: true },
+  };
+}

package/src/lib/win-paths.ts

@@ -0,0 +1,68 @@
+/**
+ * Windows path → batch-safe env indirection.
+ *
+ * cmd.exe parses .cmd files in the console's OEM codepage (CP949/GBK/CP437…), NOT UTF-8.
+ * Any absolute path we bake into a generated batch file breaks for users whose profile
+ * directory contains non-ASCII characters (e.g. Korean/Chinese usernames), because the
+ * UTF-8 bytes we wrote are decoded as mojibake at parse time. Instead of baking the
+ * profile prefix literally, rewrite it as a `%USERPROFILE%`-style token: cmd expands the
+ * variable natively at parse time in the correct codepage, so the non-ASCII prefix never
+ * has to survive a file-encoding round trip.
+ */
+
+export type WindowsEnvMap = Record<string, string | undefined>;
+
+/** Ordered by specificity; longest resolved prefix wins regardless of this order. */
+const INDIRECTION_VARS = ["LOCALAPPDATA", "APPDATA", "USERPROFILE"] as const;
+
+/** True when `prefix` matches a leading whole-component span of `path` (case-insensitive). */
+function isComponentPrefix(path: string, prefix: string): boolean {
+  if (path.length < prefix.length) return false;
+  if (path.slice(0, prefix.length).toLowerCase() !== prefix.toLowerCase()) return false;
+  if (path.length === prefix.length) return true;
+  const next = path[prefix.length];
+  return next === "\\" || next === "/";
+}
+
+/**
+ * Split a Windows path into an env-token prefix and the remaining literal suffix.
+ * Returns `token: ""` (and the full path as `rest`) when no known prefix applies.
+ */
+export function splitWindowsEnvPrefix(path: string, env: WindowsEnvMap = process.env): { token: string; rest: string } {
+  let best: { name: string; value: string } | null = null;
+  for (const name of INDIRECTION_VARS) {
+    const raw = env[name]?.trim();
+    if (!raw) continue;
+    const value = raw.replace(/[\\/]+$/, "");
+    if (!value || !isComponentPrefix(path, value)) continue;
+    if (!best || value.length > best.value.length) best = { name, value };
+  }
+  if (!best) return { token: "", rest: path };
+  return { token: `%${best.name}%`, rest: path.slice(best.value.length) };
+}
+
+/**
+ * Render a single path for embedding in a batch `set "X=…"` line: env-token prefix kept
+ * verbatim (cmd must expand it), remaining literal suffix run through the caller's batch
+ * escaping (which doubles `%` and would otherwise destroy the token itself).
+ */
+export function windowsEnvIndirectBatchValue(
+  path: string,
+  escape: (value: string) => string,
+  env: WindowsEnvMap = process.env,
+): string {
+  const { token, rest } = splitWindowsEnvPrefix(path, env);
+  return token + escape(rest);
+}
+
+/** Same as {@link windowsEnvIndirectBatchValue} for `;`-separated path lists (PATH). */
+export function windowsEnvIndirectBatchPathList(
+  value: string,
+  escape: (value: string) => string,
+  env: WindowsEnvMap = process.env,
+): string {
+  return value
+    .split(";")
+    .map(part => (part ? windowsEnvIndirectBatchValue(part, escape, env) : part))
+    .join(";");
+}