@oeronteros-1/opencode-orchestra 1.0.28 → 1.0.30

package/dist/routing/classifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../src/routing/classifier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../src/routing/classifier.ts"],"names":[],"mappings":"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"}

package/dist/routing/fallback.d.ts

@@ -1,33 +1,42 @@
-import type { BudgetMode, ModelCandidateInput, ModelCost } from "../config/schema.js";
+import type { BudgetMode, ModelCandidateInput, ModelCost, ModelTier } from "../config/schema.js";
 import { resolveModel } from "./model-resolver.js";
 export interface FallbackEntry {
     id: string;
     cost: ModelCost;
-    /** Lower is cheaper; used to prefer cheaper fallbacks after a failure. */
+    /** Static cost-class rank: paid (2) > subscription (1) > free (0). */
     costRank: number;
+    /** True when the capability is declared or explicitly scored; false when unknown. */
+    compatible: boolean;
+    priority: number;
+    tier: ModelTier;
 }
 export interface FallbackChain {
     /** The winning model id (first choice). */
     primary: string;
-    /** Ordered cheaper alternatives after the primary. */
+    /** Ordered alternatives after the primary (compatibility first). */
     alternatives: FallbackEntry[];
     /** All entries (primary + alternatives) in failover order. */
     all: FallbackEntry[];
 }
+export type ErrorKind = "rate-limit" | "server" | "timeout" | "auth" | "invalid-request" | "other";
 interface RetryableError {
-    /** HTTP status or "timeout". Rate-limit (429) and 5xx are retryable. */
-    kind: "rate-limit" | "server" | "timeout" | "other";
+    /** Retryable failures trigger failover; auth and invalid-request are terminal. */
+    kind: ErrorKind;
 }
 /**
- * Classify an error into retryable categories. A retryable failure should
- * trigger failover to a cheaper model in the chain.
+ * Classify an error into policy categories. Only rate-limit, timeout, and
+ * server failures are retryable; auth and invalid-request stop the chain.
  */
 export declare function classifyError(error: unknown): RetryableError;
 export declare function isRetryable(kind: RetryableError["kind"]): boolean;
 /**
  * Build a failover chain for a capability pool. The primary is the current
- * winner; alternatives are the remaining candidates sorted by increasing cost
- * (cheaper first), so a retry steps down in price instead of up.
+ * winner; alternatives are the remaining candidates ranked deterministically:
+ * capability compatibility, then priority, tier, budget-aware cost class, and
+ * model id. Explicitly incompatible candidates are excluded before resolution
+ * so the primary is always compatible; unknown-capability candidates stay
+ * eligible but rank below compatible ones. Budget filters (paid exclusion)
+ * apply to alternatives as well as the primary.
  */
 export declare function buildFallbackChain(pool: ModelCandidateInput[], capability: Parameters<typeof resolveModel>[0]["capability"], budget: BudgetMode, allowPaid: boolean, options?: {
     preferredCosts?: ModelCost[];
@@ -37,7 +46,7 @@ export declare function buildFallbackChain(pool: ModelCandidateInput[], capabili
 }): FallbackChain | undefined;
 /**
  * Given a chain and the id of a model that just failed, return the next
- * cheaper alternative to try, or undefined when the chain is exhausted.
+ * alternative to try, or undefined when the chain is exhausted.
  */
 export declare function nextAfterFailure(chain: FallbackChain, failedId: string): string | undefined;
 export {};

package/dist/routing/fallback.js

@@ -1,11 +1,39 @@
-import { normalizeCandidate, resolveModel } from "./model-resolver.js";
+import { isCapabilityCompatible, isCapabilityIncompatible, normalizeCandidate, resolveModel, } from "./model-resolver.js";
 const COST_RANK = { paid: 2, subscription: 1, free: 0 };
+const TIER_RANK = { frontier: 2, lead: 1, worker: 0 };
+/**
+ * Budget-aware cost-class preference applied as the tie-break after priority
+ * and tier. `ModelCost` is a closed union, so an unknown cost can never be
+ * coerced into a cheaper class.
+ */
+const BUDGET_COST_PREFERENCE = {
+    eco: ["free", "subscription", "paid"],
+    balanced: ["subscription", "free", "paid"],
+    quality: ["subscription", "paid", "free"],
+    ebobo: ["paid", "subscription", "free"],
+};
 function compareCodepoints(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+function costPreferenceOrder(budget, preferredCosts) {
+    if (preferredCosts && preferredCosts.length > 0)
+        return preferredCosts;
+    return BUDGET_COST_PREFERENCE[budget];
+}
+function costPreferenceRank(cost, order) {
+    const index = order.indexOf(cost);
+    return index === -1 ? order.length : index;
+}
+function isBudgetEligible(candidate, allowPaid, paidCallsUsed, maxPaidCalls) {
+    if (candidate.cost !== "paid")
+        return true;
+    if (!allowPaid)
+        return false;
+    return maxPaidCalls === undefined || paidCallsUsed < maxPaidCalls;
+}
 /**
- * Classify an error into retryable categories. A retryable failure should
- * trigger failover to a cheaper model in the chain.
+ * Classify an error into policy categories. Only rate-limit, timeout, and
+ * server failures are retryable; auth and invalid-request stop the chain.
  */
 export function classifyError(error) {
     const candidate = typeof error === "object" && error !== null ? error : undefined;
@@ -18,6 +46,12 @@ export function classifyError(error) {
                 : String(error);
     const status = candidate?.status ?? candidate?.statusCode;
     const text = (status !== undefined ? String(status) + " " : "") + message.toLowerCase();
+    if (status === 401 || status === 403 || text.includes("unauthorized") || text.includes("forbidden") || text.includes("invalid api key") || text.includes("authentication")) {
+        return { kind: "auth" };
+    }
+    if (status === 400 || status === 404 || text.includes("not found") || text.includes("bad request") || text.includes("invalid request")) {
+        return { kind: "invalid-request" };
+    }
     if (status === 429 || text.includes("429") || text.includes("rate limit") || text.includes("rate-limit") || text.includes("too many requests")) {
         return { kind: "rate-limit" };
     }
@@ -34,15 +68,25 @@ export function isRetryable(kind) {
 }
 /**
  * Build a failover chain for a capability pool. The primary is the current
- * winner; alternatives are the remaining candidates sorted by increasing cost
- * (cheaper first), so a retry steps down in price instead of up.
+ * winner; alternatives are the remaining candidates ranked deterministically:
+ * capability compatibility, then priority, tier, budget-aware cost class, and
+ * model id. Explicitly incompatible candidates are excluded before resolution
+ * so the primary is always compatible; unknown-capability candidates stay
+ * eligible but rank below compatible ones. Budget filters (paid exclusion)
+ * apply to alternatives as well as the primary.
  */
 export function buildFallbackChain(pool, capability, budget, allowPaid, options = {}) {
     const normalized = pool.map(normalizeCandidate);
     if (normalized.length === 0)
         return undefined;
+    // The primary must always be capability-compatible: drop explicitly
+    // incompatible candidates before resolution so a high-priority incompatible
+    // model (e.g. an ebobo frontier) cannot take the primary slot.
+    const compatiblePool = normalized.filter((candidate) => !isCapabilityIncompatible(candidate, capability));
+    if (compatiblePool.length === 0)
+        return undefined;
     const winner = resolveModel({
-        pool,
+        pool: compatiblePool,
         capability,
         budget,
         allowPaid,
@@ -51,31 +95,58 @@ export function buildFallbackChain(pool, capability, budget, allowPaid, options
         ...(options.paidCallsUsed !== undefined ? { paidCallsUsed: options.paidCallsUsed } : {}),
         ...(options.maxPaidCalls !== undefined ? { maxPaidCalls: options.maxPaidCalls } : {}),
     });
-    const primary = winner?.id ?? normalized[0]?.id;
-    if (!primary)
+    // If every compatible candidate was budget-excluded (e.g. an all-paid pool
+    // under an eco budget or a fully exhausted paid cap), `resolveModel` has no
+    // winner and there is no valid primary — never fail open to the first raw
+    // pool entry, which could surface a paid model as primary.
+    if (!winner)
         return undefined;
-    const byId = new Map(normalized.map((candidate) => [candidate.id, candidate]));
-    const primaryEntry = toEntry(byId.get(primary));
-    const alternatives = normalized
+    const primary = winner.id;
+    const paidCallsUsed = options.paidCallsUsed ?? 0;
+    const costOrder = costPreferenceOrder(budget, options.preferredCosts);
+    const byId = new Map(compatiblePool.map((candidate) => [candidate.id, candidate]));
+    const primaryCandidate = byId.get(primary);
+    const primaryEntry = primaryCandidate ? toEntry(primaryCandidate, capability) : undefined;
+    const alternatives = compatiblePool
         .filter((candidate) => candidate.id !== primary)
-        .sort((a, b) => COST_RANK[a.cost] - COST_RANK[b.cost] || compareCodepoints(a.id, b.id))
-        .map((candidate) => toEntry(candidate));
+        .filter((candidate) => isBudgetEligible(candidate, allowPaid, paidCallsUsed, options.maxPaidCalls))
+        .sort((a, b) => {
+        const compat = compatibilityTier(b, capability) - compatibilityTier(a, capability);
+        if (compat !== 0)
+            return compat;
+        if (a.priority !== b.priority)
+            return b.priority - a.priority;
+        const tier = TIER_RANK[b.tier] - TIER_RANK[a.tier];
+        if (tier !== 0)
+            return tier;
+        const cost = costPreferenceRank(a.cost, costOrder) - costPreferenceRank(b.cost, costOrder);
+        if (cost !== 0)
+            return cost;
+        return compareCodepoints(a.id, b.id);
+    })
+        .map((candidate) => toEntry(candidate, capability));
     return {
         primary,
         alternatives,
         all: primaryEntry ? [primaryEntry, ...alternatives] : alternatives,
     };
 }
-function toEntry(candidate) {
+function compatibilityTier(candidate, capability) {
+    return isCapabilityCompatible(candidate, capability) ? 1 : 0;
+}
+function toEntry(candidate, capability) {
     return {
-        id: candidate?.id ?? "",
-        cost: candidate?.cost ?? "free",
-        costRank: COST_RANK[candidate?.cost ?? "free"],
+        id: candidate.id,
+        cost: candidate.cost,
+        costRank: COST_RANK[candidate.cost],
+        compatible: isCapabilityCompatible(candidate, capability),
+        priority: candidate.priority,
+        tier: candidate.tier,
     };
 }
 /**
  * Given a chain and the id of a model that just failed, return the next
- * cheaper alternative to try, or undefined when the chain is exhausted.
+ * alternative to try, or undefined when the chain is exhausted.
  */
 export function nextAfterFailure(chain, failedId) {
     const index = chain.all.findIndex((entry) => entry.id === failedId);

package/dist/routing/fallback.js.map

@@ -1 +1 @@
-{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../../src/routing/fallback.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fallback.js","sourceRoot":"","sources":["../../src/routing/fallback.ts"],"names":[],"mappings":"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"}

package/dist/routing/model-resolver.d.ts

@@ -1,4 +1,24 @@
 import type { BudgetMode, CapabilityName, ModelCandidateInput, ModelCost, ModelTier } from "../config/schema.js";
+/**
+ * Stable machine-readable routing decision identifier. The resolver only emits
+ * the scoring codes; `exact_override` is reserved for an explicit orch-lead
+ * agent override and is produced by the tool layer, not the resolver.
+ */
+export type RoutingReasonCode = "frontier" | "preferred_tier" | "preferred_cost" | "capability_match" | "price" | "priority" | "exact_override";
+export interface RoutingReason {
+    code: RoutingReasonCode;
+    /** Bounded diagnostic copy; never contains secrets, prompts, or credentials. */
+    text: string;
+    matchedCapabilities: CapabilityName[];
+    score: number;
+    budget: BudgetMode;
+}
+/**
+ * Bound a routing reason's diagnostic text to a fixed length. The text only
+ * carries model id, cost class, tier, and score — never secrets, prompts, or
+ * credentials — so a plain truncation is safe.
+ */
+export declare function boundReasonText(text: string, limit?: number): string;
 export interface ModelCandidate {
     id: string;
     cost: ModelCost;
@@ -23,6 +43,13 @@ export interface ResolveModelRequest {
     paidCallsUsed?: number;
     maxPaidCalls?: number;
 }
+/**
+ * The shared resolution parameters for the orch-lead agent. Both the tool
+ * layer (routing metadata) and `createLeadAgent` (the actually assigned model)
+ * resolve the lead pool through this exact request so the reported lead always
+ * matches the assigned one.
+ */
+export declare function leadResolveRequest(budget: BudgetMode): Omit<ResolveModelRequest, "pool" | "capability">;
 export interface ResolvedModel {
     id: string;
     score: number;
@@ -35,6 +62,26 @@ export interface ResolvedModel {
      * with a retryable error, step down this list instead of re-hitting it.
      */
     fallback: string[];
+    /** Structured, machine-readable routing decision for the winning model. */
+    routingReason?: RoutingReason;
 }
 export declare function normalizeCandidate(input: ModelCandidateInput): ModelCandidate;
+/**
+ * Shared capability scoring helpers. `resolveModel` uses these for scoring and
+ * `buildFallbackChain` uses them to filter and rank fallback alternatives.
+ */
+export declare function hasDeclaredCapability(candidate: ModelCandidate, capability: CapabilityName): boolean;
+export declare function hasExplicitScore(candidate: ModelCandidate, capability: CapabilityName): boolean;
+/**
+ * A candidate is compatible when it either declares the capability or carries
+ * an explicit positive score for it.
+ */
+export declare function isCapabilityCompatible(candidate: ModelCandidate, capability: CapabilityName): boolean;
+/**
+ * A candidate is explicitly incompatible when it declares *some* capabilities,
+ * does not declare the required one, and has no explicit score for it. Unknown
+ * candidates (empty capabilities) are NOT incompatible: they stay eligible but
+ * rank at lower confidence.
+ */
+export declare function isCapabilityIncompatible(candidate: ModelCandidate, capability: CapabilityName): boolean;
 export declare function resolveModel(request: ResolveModelRequest): ResolvedModel | undefined;

package/dist/routing/model-resolver.js

@@ -1,4 +1,38 @@
 import { costAdjustment, getBudgetPolicy } from "./budget.js";
+/** Maximum length of the `RoutingReason.text` diagnostic string. */
+const REASON_TEXT_LIMIT = 200;
+/**
+ * Bound a routing reason's diagnostic text to a fixed length. The text only
+ * carries model id, cost class, tier, and score — never secrets, prompts, or
+ * credentials — so a plain truncation is safe.
+ */
+export function boundReasonText(text, limit = REASON_TEXT_LIMIT) {
+    if (text.length <= limit)
+        return text;
+    return text.slice(0, limit - 1) + "…";
+}
+/**
+ * The shared resolution parameters for the orch-lead agent. Both the tool
+ * layer (routing metadata) and `createLeadAgent` (the actually assigned model)
+ * resolve the lead pool through this exact request so the reported lead always
+ * matches the assigned one.
+ */
+export function leadResolveRequest(budget) {
+    return {
+        budget,
+        allowPaid: budget === "quality" || budget === "ebobo",
+        preferredCosts: budget === "balanced"
+            ? ["subscription"]
+            : budget === "eco"
+                ? ["free"]
+                : [],
+        preferredTiers: budget === "balanced"
+            ? ["lead"]
+            : budget === "quality" || budget === "ebobo"
+                ? ["frontier", "lead"]
+                : [],
+    };
+}
 export function normalizeCandidate(input) {
     if (typeof input === "string") {
         return {
@@ -22,6 +56,34 @@ export function normalizeCandidate(input) {
         ...(input.priceOutput !== undefined ? { priceOutput: input.priceOutput } : {}),
     };
 }
+/**
+ * Shared capability scoring helpers. `resolveModel` uses these for scoring and
+ * `buildFallbackChain` uses them to filter and rank fallback alternatives.
+ */
+export function hasDeclaredCapability(candidate, capability) {
+    return candidate.capabilities.includes(capability);
+}
+export function hasExplicitScore(candidate, capability) {
+    return (candidate.scores[capability] ?? 0) > 0;
+}
+/**
+ * A candidate is compatible when it either declares the capability or carries
+ * an explicit positive score for it.
+ */
+export function isCapabilityCompatible(candidate, capability) {
+    return hasDeclaredCapability(candidate, capability) || hasExplicitScore(candidate, capability);
+}
+/**
+ * A candidate is explicitly incompatible when it declares *some* capabilities,
+ * does not declare the required one, and has no explicit score for it. Unknown
+ * candidates (empty capabilities) are NOT incompatible: they stay eligible but
+ * rank at lower confidence.
+ */
+export function isCapabilityIncompatible(candidate, capability) {
+    return candidate.capabilities.length > 0
+        && !hasDeclaredCapability(candidate, capability)
+        && !hasExplicitScore(candidate, capability);
+}
 const COST_ORDER = { paid: 2, subscription: 1, free: 0 };
 function compareCodepoints(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
@@ -42,7 +104,7 @@ export function resolveModel(request) {
         .filter((candidate) => candidate.cost !== "paid" || request.maxPaidCalls === undefined || (request.paidCallsUsed ?? 0) < request.maxPaidCalls)
         .map((candidate) => {
         const explicit = candidate.scores[request.capability] ?? 0;
-        const declared = candidate.capabilities.includes(request.capability) ? 18 : 0;
+        const declared = hasDeclaredCapability(candidate, request.capability) ? 18 : 0;
         const contextBonus = candidate.context === "xlarge" ? 8 : candidate.context === "large" ? 4 : 0;
         const frontierBonus = request.budget === "ebobo"
             ? candidate.tier === "frontier"
@@ -67,7 +129,17 @@ export function resolveModel(request) {
             ...(preferredTierBonus ? ["preferred-tier=" + preferredTierBonus] : []),
             ...(priceAdj !== 0 ? ["price=" + priceAdj] : []),
         ];
-        return { candidate, score, reason };
+        return {
+            candidate,
+            score,
+            reason,
+            explicit,
+            declared,
+            frontierBonus,
+            preferredCostBonus,
+            preferredTierBonus,
+            priceAdj,
+        };
     })
         .sort((a, b) => b.score - a.score || compareCodepoints(a.candidate.id, b.candidate.id));
     const winner = ranked[0];
@@ -77,6 +149,41 @@ export function resolveModel(request) {
         .slice(1)
         .sort((a, b) => COST_ORDER[a.candidate.cost] - COST_ORDER[b.candidate.cost] || a.score - b.score || compareCodepoints(a.candidate.id, b.candidate.id))
         .map((item) => item.candidate.id);
+    const matchedCapabilities = winner.explicit || winner.declared ? [request.capability] : [];
+    // Deterministic reason code by dominant scoring signal, strongest first.
+    let code;
+    let component;
+    if (winner.frontierBonus > 0) {
+        code = "frontier";
+        component = "frontier=" + winner.frontierBonus;
+    }
+    else if (winner.preferredTierBonus > 0) {
+        code = "preferred_tier";
+        component = "tier=" + winner.candidate.tier;
+    }
+    else if (winner.preferredCostBonus > 0) {
+        code = "preferred_cost";
+        component = "cost=" + winner.candidate.cost;
+    }
+    else if (winner.explicit || winner.declared) {
+        code = "capability_match";
+        component = "capability=" + (winner.explicit ? "explicit" : "declared");
+    }
+    else if (winner.priceAdj !== 0) {
+        code = "price";
+        component = "price=" + winner.priceAdj;
+    }
+    else {
+        code = "priority";
+        component = "priority=" + winner.candidate.priority;
+    }
+    const routingReason = {
+        code,
+        text: boundReasonText(`id=${winner.candidate.id} cost=${winner.candidate.cost} ${component} score=${winner.score}`),
+        matchedCapabilities,
+        score: winner.score,
+        budget: request.budget,
+    };
     return {
         id: winner.candidate.id,
         score: winner.score,
@@ -85,6 +192,7 @@ export function resolveModel(request) {
         ...(winner.candidate.priceOutput !== undefined ? { priceOutput: winner.candidate.priceOutput } : {}),
         reason: winner.reason,
         fallback,
+        routingReason,
     };
 }
 //# sourceMappingURL=model-resolver.js.map

package/dist/routing/model-resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/routing/model-resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model-resolver.js","sourceRoot":"","sources":["../../src/routing/model-resolver.ts"],"names":[],"mappings":"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"}

package/dist/spawn.d.ts

@@ -1,5 +1,10 @@
 import { spawnSync } from "node:child_process";
 export type SpawnSyncOptions = NonNullable<Parameters<typeof spawnSync>[2]>;
+type SpawnSyncDependency = (command: string, args: string[], options: SpawnSyncOptions) => ReturnType<typeof spawnSync>;
+export interface SpawnFallbackDependencies {
+    platform?: NodeJS.Platform;
+    spawnSync?: SpawnSyncDependency;
+}
 /**
  * Quote a command line for cmd.exe: parts containing spaces or cmd
  * metacharacters are wrapped in double quotes so paths with spaces and
@@ -16,10 +21,18 @@ export declare function safeForCmdRetry(parts: string[]): boolean;
  * with EINVAL on CVE-2024-27980-patched Node). The retry is skipped for
  * inputs cmd.exe could reinterpret — see {@link safeForCmdRetry} — and
  * off-Windows the native result is always returned untouched.
+ *
+ * When a bare command name resolves to a `.cmd`/`.bat` shim ahead of any
+ * spawnable executable on Windows, the direct spawn is skipped entirely and
+ * the command runs through cmd.exe, mirroring cmd.exe's own resolution order.
+ * This keeps PATH-based shims authoritative even when a real `.exe` of the
+ * same name sits further down PATH (patched Node would otherwise bypass the
+ * shim and run the real tool).
  */
-export declare function spawnWithCmdFallback(command: string, args: string[], options?: SpawnSyncOptions): ReturnType<typeof spawnSync>;
+export declare function spawnWithCmdFallback(command: string, args: string[], options?: SpawnSyncOptions, deps?: SpawnFallbackDependencies): ReturnType<typeof spawnSync>;
 /**
  * User home for tool discovery. Windows tests override HOME to shadow the
  * real per-user toolchain, so honor it before falling back to os.homedir().
  */
 export declare function homeDirectory(): string;
+export {};

package/dist/spawn.js

@@ -1,5 +1,8 @@
 import { spawnSync } from "node:child_process";
+import { statSync } from "node:fs";
 import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 /**
  * Quote a command line for cmd.exe: parts containing spaces or cmd
  * metacharacters are wrapped in double quotes so paths with spaces and
@@ -26,17 +29,77 @@ const UNSAFE_FOR_CMD_RETRY = /["%\r\n;,!]/;
 export function safeForCmdRetry(parts) {
     return !parts.some((part) => UNSAFE_FOR_CMD_RETRY.test(part));
 }
+/** cmd.exe's default executable search order within a directory. */
+const DEFAULT_PATHEXT = [".COM", ".EXE", ".BAT", ".CMD"];
+/**
+ * Mirror cmd.exe's PATH resolution for a bare command name: scan the current
+ * directory and then PATH in order, trying PATHEXT extensions within each
+ * directory, and return the first existing file. Patched Windows Node skips
+ * `.cmd`/`.bat` candidates when resolving direct spawns, so a `.cmd` shim in
+ * an earlier PATH entry would otherwise be silently shadowed by a real `.exe`
+ * further down PATH. Knowing which candidate wins lets us route `.cmd`/`.bat`
+ * wins through the cmd.exe retry deterministically.
+ */
+function resolveCommandCandidate(command, env, cwd) {
+    const pathext = (env.PATHEXT ?? DEFAULT_PATHEXT.join(";"))
+        .split(";")
+        .map((extension) => extension.trim())
+        .filter((extension) => extension.length > 0)
+        .map((extension) => (extension.startsWith(".") ? extension : "." + extension));
+    const directories = [cwd, ...(env.PATH ?? "").split(";").map((directory) => directory.replace(/^"|"$/g, ""))].filter((directory) => directory.length > 0);
+    for (const directory of directories) {
+        for (const extension of pathext) {
+            const candidate = path.join(directory, command + extension);
+            try {
+                if (statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                // Not a file; try the next extension.
+            }
+        }
+    }
+    return undefined;
+}
 /**
  * Run a command natively, retrying through cmd.exe when Windows cannot
  * spawn the target directly (`.cmd`/`.bat` shims and shell scripts fail
  * with EINVAL on CVE-2024-27980-patched Node). The retry is skipped for
  * inputs cmd.exe could reinterpret — see {@link safeForCmdRetry} — and
  * off-Windows the native result is always returned untouched.
+ *
+ * When a bare command name resolves to a `.cmd`/`.bat` shim ahead of any
+ * spawnable executable on Windows, the direct spawn is skipped entirely and
+ * the command runs through cmd.exe, mirroring cmd.exe's own resolution order.
+ * This keeps PATH-based shims authoritative even when a real `.exe` of the
+ * same name sits further down PATH (patched Node would otherwise bypass the
+ * shim and run the real tool).
  */
-export function spawnWithCmdFallback(command, args, options = {}) {
-    const direct = spawnSync(command, args, options);
-    if (process.platform === "win32" && direct.error !== undefined && safeForCmdRetry([command, ...args])) {
-        const retry = spawnSync(quoteLineForCmd([command, ...args]), [], { ...options, shell: true });
+export function spawnWithCmdFallback(command, args, options = {}, deps = {}) {
+    const runSpawn = deps.spawnSync || spawnSync;
+    const platform = deps.platform || process.platform;
+    const isBareName = !command.includes("\\") && !command.includes("/") && path.extname(command).length === 0;
+    let shellAttempt;
+    if (platform === "win32" && isBareName && safeForCmdRetry([command, ...args])) {
+        const env = options.env ?? process.env;
+        const cwd = typeof options.cwd === "string"
+            ? options.cwd
+            : options.cwd instanceof URL
+                ? fileURLToPath(options.cwd)
+                : process.cwd();
+        const candidate = resolveCommandCandidate(command, env, cwd);
+        if (candidate !== undefined && /\.(cmd|bat)$/i.test(candidate)) {
+            shellAttempt = runSpawn(quoteLineForCmd([command, ...args]), [], { ...options, shell: true });
+            if (shellAttempt.error === undefined)
+                return shellAttempt;
+        }
+    }
+    const direct = runSpawn(command, args, options);
+    // When the shim already ran through cmd.exe above and failed to SPAWN, do
+    // not shell out a second time — the shim could execute twice, doubling its
+    // side effects. Fail closed with the direct-spawn result instead.
+    if (platform === "win32" && direct.error !== undefined && shellAttempt === undefined && safeForCmdRetry([command, ...args])) {
+        const retry = runSpawn(quoteLineForCmd([command, ...args]), [], { ...options, shell: true });
         if (retry.error === undefined)
             return retry;
     }