@aiwg/cli 2026.10.1 → 2026.10.3

package/dist/src/models/wrapper-route.js

@@ -1,6 +1,7 @@
 import { compileModelPolicy, } from './provider-policy.js';
 import { MODEL_WRAPPERS } from './provider-models.js';
 import { routeModelTier } from './router.js';
+import { resolveWorkerPlan } from './resolver.js';
 function roleForTier(tier) {
     if (tier === 'economy')
         return 'efficiency';
@@ -14,6 +15,23 @@ export function buildWrapperRouteEnvelope(request) {
     if (!request.assignment.trim())
         throw new Error('Wrapper routing requires a bounded assignment.');
     const decision = routeModelTier(request);
+    if (request.worker?.snapshot.config.parallelism?.worker_dispatch && !request.deterministic) {
+        const worker = resolveWorkerPlan(request.worker.snapshot, {
+            ...request.worker.request,
+            authority: request,
+        });
+        const role = worker.role;
+        const wrapper = role ? MODEL_WRAPPERS[role] : null;
+        return {
+            version: 1, provider: request.provider, decision, role,
+            tier: role ? worker.policy?.roleGuidance?.[role]?.tier ?? null : null,
+            wrapper, capability: request.capability, assignment: request.assignment.trim(), model: null, worker,
+            launch: { mechanism: request.launchMechanism, target: worker.selected ? wrapper : null,
+                prompt: worker.selected
+                    ? `Run this bounded assignment through ${wrapper}.\nSelected worker: ${worker.selected.group}/${worker.selected.member}; model ${worker.selected.model}; effort ${worker.selected.effort ?? 'not-applicable'}.\nAssignment: ${request.assignment.trim()}\nRevalidate current input digests before invocation; return claims for conductor verification.`
+                    : 'Worker resolution is blocked; inspect the plan diagnostics and exclusions.' },
+        };
+    }
     const tier = decision.modelTier;
     const role = roleForTier(tier);
     const wrapper = role ? MODEL_WRAPPERS[role] : null;

package/dist/src/ops/registry.js

@@ -10,7 +10,7 @@ import { readFile, writeFile, mkdir, readdir } from 'fs/promises';
 import { resolve, dirname, basename, sep } from 'path';
 import { homedir } from 'os';
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
-import { execSync } from 'child_process';
+import { boundedExecFileSync } from '../process/bounded-child-process.mjs';
 import { resolveConfigDir } from '../config/user-config.js';
 import { resolveWorkspace } from '../config/workspace.js';
 import { projectControlPath } from '../config/project-artifacts.js';
@@ -495,7 +495,10 @@ export class OpsRegistry {
             if (remote) {
                 console.log(`  Pushing ${repoName} to ${remote}/${branch}...`);
                 try {
-                    execSync(`git push ${shellEscape(remote)} ${shellEscape(branch)}`, {
+                    if (remote.startsWith('-') || branch.startsWith('-')) {
+                        throw new Error('Remote and branch must not start with "-"');
+                    }
+                    boundedExecFileSync('git', ['push', '--end-of-options', remote, branch], 'network', {
                         cwd: repo.path,
                         stdio: 'pipe',
                     });
@@ -541,23 +544,15 @@ async function provisionRepo(repoPath, fromUrl, silent) {
             }
         }
         await mkdir(dirname(repoPath), { recursive: true });
-        execSync(`git clone ${shellEscape(fromUrl)} ${shellEscape(repoPath)}`, { stdio: silent ? 'pipe' : 'inherit' });
+        // Cloning a full repository; long tier (#3062).
+        boundedExecFileSync('git', ['clone', '--', fromUrl, repoPath], 'long', { stdio: silent ? 'pipe' : 'inherit' });
         return { action: 'Cloned', remote: readGitRemote(repoPath) };
     }
     // Case 3: fresh init.
     await mkdir(repoPath, { recursive: true });
-    execSync('git init', { cwd: repoPath, stdio: 'pipe' });
+    boundedExecFileSync('git', ['init'], 'quick', { cwd: repoPath, stdio: 'pipe' });
     return { action: 'Created', remote: undefined };
 }
-/**
- * Minimal shell escaping for git URLs and paths passed via execSync.
- * URLs are URL-encoded already, but paths may contain spaces.
- */
-function shellEscape(s) {
-    if (/^[A-Za-z0-9_@:./~+,=-]+$/.test(s))
-        return s;
-    return `'${s.replace(/'/g, "'\\''")}'`;
-}
 /**
  * Return the `origin` remote URL for a git repo rooted at `dirPath`, or
  * undefined if not a git repo or no origin configured.
@@ -566,7 +561,7 @@ function readGitRemote(dirPath) {
     if (!existsSync(resolve(dirPath, '.git')))
         return undefined;
     try {
-        const out = execSync('git config --get remote.origin.url', {
+        const out = boundedExecFileSync('git', ['config', '--get', 'remote.origin.url'], 'quick', {
             cwd: dirPath,
             stdio: ['ignore', 'pipe', 'ignore'],
         })

package/dist/src/plugins/standalone-packager.js

@@ -1,5 +1,5 @@
 // @ts-nocheck
-import { spawnSync } from 'node:child_process';
+import { boundedSpawnSync } from '../process/bounded-child-process.mjs';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -65,7 +65,8 @@ function writeProviderMetadata(root, provider, manifest) {
     }
 }
 function createDeterministicArchive(sourceDir, archivePath) {
-    const result = spawnSync('tar', [
+    // Packaging a local plugin directory; quick tier (#3062).
+    const result = boundedSpawnSync('tar', [
         '--sort=name',
         '--mtime=@0',
         '--owner=0',
@@ -76,7 +77,7 @@ function createDeterministicArchive(sourceDir, archivePath) {
         '-C',
         path.dirname(sourceDir),
         path.basename(sourceDir),
-    ], { encoding: 'utf8' });
+    ], 'quick', { encoding: 'utf8' });
     if (result.status !== 0)
         throw new Error(`Could not create deterministic archive: ${result.stderr || 'tar failed'}`);
 }

package/dist/src/process/bounded-child-process.mjs

@@ -0,0 +1,387 @@
+/**
+ * Bounded synchronous child-process wrappers (#3062).
+ *
+ * `execSync`/`execFileSync`/`spawnSync` block the calling thread for as long
+ * as the child — or any grandchild still holding an inherited pipe — lives.
+ * With no timeout that is unbounded: it hung the test suite once and can
+ * hang the CLI when it runs without a terminal. These wrappers make every
+ * call bounded by construction: a required `tier` selects the wall-clock
+ * cap, the call never inherits stdin, and a timeout always surfaces as the
+ * normal Node `ETIMEDOUT` error/result with a message that names the
+ * command, tier and bound.
+ *
+ * Tiers (see `SYNC_PROCESS_TIER_BOUNDS_MS`):
+ *   - `quick`   30s  — local queries: git status/rev-parse/config, version
+ *                      probes, `which`/`where`, `df`, tmux queries.
+ *   - `network` 2m   — git fetch/pull/ls-remote/push, `gh`/API calls.
+ *   - `long`    10m  — installs, clones, docker, builds, test runs launched
+ *                      by scripts. Overridable via `AIWG_SYNC_LONG_TIMEOUT_MS`
+ *                      (see `resolveSyncProcessTimeoutMs`); `quick`/`network`
+ *                      are not overridable.
+ *
+ * Choose the tier by what the command does, not by where the call site
+ * lives.
+ *
+ * Interactive-by-design calls (an editor, a login flow, launching a harness
+ * binary the user is meant to talk to) do not belong here — bounding them
+ * would just make the interactive session time out. Leave those sites on
+ * the plain Node APIs.
+ *
+ * ## Why timeout kills with SIGKILL, not SIGTERM-then-SIGKILL
+ *
+ * Node's own `timeout`/`killSignal` option sends `killSignal` exactly once
+ * when the bound elapses, then keeps blocking until the child actually
+ * exits. If the child ignores that signal — trivial to do for SIGTERM, and
+ * exactly the "grandchild holding an inherited pipe" scenario this gate
+ * exists to catch — the call hangs forever regardless of the configured
+ * timeout; killSignal only picks *which* signal is sent once, not whether
+ * the wait ever ends. There is no portable way to schedule a second signal
+ * from inside a single blocking native call: the calling thread is blocked
+ * in a C++ synchronous spawn, so no JS timer can run to escalate.
+ *
+ * These wrappers therefore always kill with `killSignal: 'SIGKILL'` and
+ * ignore any `killSignal` a caller passes in `options` — honoring a
+ * caller-supplied `'SIGTERM'` would silently reopen exactly the hang this
+ * module exists to close for a child that traps and ignores it. SIGKILL
+ * cannot be caught, blocked or ignored, so the *direct child* reliably dies
+ * at the bound — confirmed with a real child that traps and ignores SIGTERM
+ * (see `test/unit/process/bounded-child-process.test.mjs`): with
+ * `killSignal: 'SIGTERM'` the call hangs indefinitely; with `'SIGKILL'` it
+ * returns at the bound, every time.
+ *
+ * ## What SIGKILL does *not* guarantee: descendant cleanup
+ *
+ * These wrappers bound one synchronous call to one direct child process.
+ * SIGKILL is sent to that child only — never to a process group or a
+ * descendant tree. A direct child that itself spawned a grandchild (for
+ * example a backgrounded, detached, or double-forked process) is not
+ * supervised here: that grandchild is not signaled, is not waited for, and
+ * may keep running after this call returns (see
+ * `test/fixtures/process/spawn-detached-pipe-holder.mjs` and its test for a
+ * concrete case). A synchronous Node call cannot supervise a process tree —
+ * doing so needs an asynchronous process-group/session owner, which is a
+ * different mechanism than what `execSync`/`execFileSync`/`spawnSync` give
+ * us. Callers that spawn a tool known to background work of its own are
+ * responsible for that tool's own cleanup contract; this module only
+ * guarantees the direct child is gone and the calling thread is unblocked
+ * by the stated bound.
+ *
+ * @module src/process/bounded-child-process
+ */
+
+import {
+  execSync as nodeExecSync,
+  execFileSync as nodeExecFileSync,
+  spawnSync as nodeSpawnSync,
+} from 'node:child_process';
+
+/** Env var that raises or disables the `long` tier bound. `0` disables it (no timeout). */
+export const AIWG_SYNC_LONG_TIMEOUT_MS_ENV = 'AIWG_SYNC_LONG_TIMEOUT_MS';
+
+/**
+ * Default wall-clock bounds per tier, in milliseconds. `quick` and `network`
+ * are fixed; `long` is the default absent `AIWG_SYNC_LONG_TIMEOUT_MS`.
+ */
+export const SYNC_PROCESS_TIER_BOUNDS_MS = Object.freeze({
+  quick: 30_000,
+  network: 120_000,
+  long: 600_000,
+});
+
+const VALID_TIERS = new Set(Object.keys(SYNC_PROCESS_TIER_BOUNDS_MS));
+
+let warnedInvalidLongTimeoutEnv = false;
+
+/**
+ * Resolve the `long` tier bound, honoring `AIWG_SYNC_LONG_TIMEOUT_MS`.
+ *
+ * - Unset/empty → the default (`SYNC_PROCESS_TIER_BOUNDS_MS.long`).
+ * - `"0"` → disabled: no bound is applied to the `long` tier at all.
+ * - A positive integer → that many milliseconds.
+ * - Anything else → the default, with one warning to stderr per process.
+ *
+ * @returns {number} Milliseconds, or `0` meaning "no bound".
+ */
+function resolveLongTierTimeoutMs() {
+  const raw = process.env[AIWG_SYNC_LONG_TIMEOUT_MS_ENV];
+  if (raw === undefined || raw.trim() === '') return SYNC_PROCESS_TIER_BOUNDS_MS.long;
+  const trimmed = raw.trim();
+  if (trimmed === '0') return 0;
+  const parsed = Number(trimmed);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    if (!warnedInvalidLongTimeoutEnv) {
+      warnedInvalidLongTimeoutEnv = true;
+      console.warn(
+        `[aiwg] ${AIWG_SYNC_LONG_TIMEOUT_MS_ENV}=${JSON.stringify(raw)} is not a positive integer or "0"; ` +
+        `using the default long-tier bound (${SYNC_PROCESS_TIER_BOUNDS_MS.long}ms).`,
+      );
+    }
+    return SYNC_PROCESS_TIER_BOUNDS_MS.long;
+  }
+  return parsed;
+}
+
+/**
+ * Exposed for tests and for the gate/report tooling: resolve the effective
+ * bound for a tier right now (reads the env override for `long` each call,
+ * same as the wrappers do).
+ *
+ * @param {'quick'|'network'|'long'} tier
+ * @returns {number} Milliseconds; `0` means "no bound" (long tier disabled).
+ */
+export function resolveSyncProcessTimeoutMs(tier) {
+  assertValidTier(tier);
+  if (tier === 'long') return resolveLongTierTimeoutMs();
+  return SYNC_PROCESS_TIER_BOUNDS_MS[tier];
+}
+
+function assertValidTier(tier) {
+  if (!VALID_TIERS.has(tier)) {
+    throw new TypeError(
+      `Sync process tier must be one of ${[...VALID_TIERS].map((t) => `'${t}'`).join(', ')}; got ${JSON.stringify(tier)}.`,
+    );
+  }
+}
+
+/**
+ * The bound actually applied to one call: the tier bound, unless the
+ * caller's own `options.timeout` is a smaller positive number (an explicit
+ * smaller timeout always wins; a zero/negative/non-numeric one is ignored —
+ * a call site cannot silently opt out of the tier bound by passing
+ * `timeout: 0` itself; only the `long`-tier env var can disable a bound).
+ *
+ * @param {'quick'|'network'|'long'} tier
+ * @param {{timeout?: number}} [options]
+ * @returns {number}
+ */
+function effectiveTimeoutMs(tier, options) {
+  const bound = resolveSyncProcessTimeoutMs(tier);
+  const explicit = options?.timeout;
+  if (typeof explicit === 'number' && Number.isFinite(explicit) && explicit > 0 && (bound === 0 || explicit < bound)) {
+    return explicit;
+  }
+  return bound;
+}
+
+/**
+ * Clamp a caller-controlled value to a guaranteed-positive millisecond
+ * bound, for the one case `boundedExecSync`/`boundedExecFileSync`/
+ * `boundedSpawnSync` don't cover by themselves: a *raw* `execSync`/
+ * `execFileSync`/`spawnSync` call site whose `timeout` option is computed
+ * from caller input (a CLI flag, a config value, a converted unit) rather
+ * than a literal — `timeout: options.timeout` or `timeout: timeoutSec *
+ * 1000` with an untrusted `timeoutSec`, for example. `tools/testing/
+ * check-sync-child-process-timeouts.mjs` (#3062 B/C finding 8) recognizes
+ * a call to this function, by binding, as a provably positive timeout —
+ * so wrap the dynamic value here instead of passing it through directly.
+ *
+ * `value` passes through only when it is itself a finite number `> 0`;
+ * anything else (`0`, a negative number, `NaN`, `undefined`, a string,
+ * ...) falls back to `fallbackMs` — so a caller-controlled `timeoutSec: 0`
+ * cannot disable the bound. `fallbackMs` itself falls back to the `quick`
+ * tier bound if it is not a valid positive number, so this function can
+ * never itself return a non-positive or non-finite value.
+ *
+ * @param {unknown} value
+ * @param {number} fallbackMs
+ * @returns {number}
+ */
+export function positiveTimeoutMs(value, fallbackMs) {
+  const resolvedFallback = typeof fallbackMs === 'number' && Number.isFinite(fallbackMs) && fallbackMs > 0
+    ? fallbackMs
+    : SYNC_PROCESS_TIER_BOUNDS_MS.quick;
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : resolvedFallback;
+}
+
+/**
+ * Whether a `stdio[0]` (stdin slot) value describes the parent's own stdin —
+ * the form Node would otherwise inherit from. Covers the string shorthand,
+ * the literal fd `0`, and the `process.stdin` stream object itself; leaves
+ * `'pipe'`, `'ignore'`, other fds, and unrelated stream objects alone.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isParentStdinDescriptor(value) {
+  return value === 'inherit' || value === 0 || value === process.stdin;
+}
+
+/**
+ * A bounded call never inherits stdin; stdout/stderr may still be inherited
+ * for progress output. When the caller supplies `input`, an inherited
+ * stdin form is normalized to `'pipe'` instead of `'ignore'` — `input`
+ * needs a real pipe to deliver its payload through, and `'ignore'` would
+ * silently drop it (#3062 B/C finding 9). `options` is otherwise left
+ * untouched when stdin was not going to be inherited anyway.
+ *
+ * @param {Record<string, unknown>} options
+ * @returns {Record<string, unknown>}
+ */
+function withoutInheritedStdin(options) {
+  if (options.input !== undefined) {
+    // `input` needs stdin to actually be a pipe to deliver its payload —
+    // a caller-specified inherited-stdin form in `stdio[0]` must not win
+    // over that (#3062 B/C finding 9: an earlier version returned
+    // `options` completely untouched here, so `input` combined with
+    // `stdio: 'inherit'`/fd `0`/`process.stdin` could still leave stdin
+    // connected to the parent's real stdin instead of the pipe `input`
+    // is written to). stdout/stderr and the payload itself are untouched.
+    if (options.stdio === 'inherit') {
+      return { ...options, stdio: ['pipe', 'inherit', 'inherit'] };
+    }
+    if (Array.isArray(options.stdio) && isParentStdinDescriptor(options.stdio[0])) {
+      const stdio = options.stdio.slice();
+      stdio[0] = 'pipe';
+      return { ...options, stdio };
+    }
+    return options;
+  }
+  if (options.stdio === 'inherit') {
+    return { ...options, stdio: ['ignore', 'inherit', 'inherit'] };
+  }
+  if (Array.isArray(options.stdio) && isParentStdinDescriptor(options.stdio[0])) {
+    const stdio = options.stdio.slice();
+    stdio[0] = 'ignore';
+    return { ...options, stdio };
+  }
+  return options;
+}
+
+/**
+ * Build the final Node options: bounded stdin, resolved timeout, and a
+ * forced `killSignal: 'SIGKILL'`. Unlike `timeout`, `killSignal` is not
+ * negotiable: a caller-supplied `killSignal` (e.g. `'SIGTERM'`) is
+ * overwritten, not honored, because a child that ignores it would defeat
+ * the bound this module exists to guarantee (see the module header).
+ *
+ * @param {Record<string, unknown> | undefined} options
+ * @param {number} boundMs
+ * @returns {Record<string, unknown>}
+ */
+function toNodeOptions(options, boundMs) {
+  const base = withoutInheritedStdin(options ?? {});
+  return {
+    ...base,
+    timeout: boundMs,
+    killSignal: 'SIGKILL',
+  };
+}
+
+function describeCommand(command, args) {
+  if (args === undefined) return command;
+  return [command, ...args].join(' ');
+}
+
+/**
+ * On timeout (`error.code === 'ETIMEDOUT'`), prepend a message naming the
+ * command, tier and bound. Leaves every other field (`code`, `signal`,
+ * `status`, `killed`) exactly as Node set them, and leaves non-timeout
+ * errors untouched, so existing catch blocks that inspect those fields (or
+ * just catch-and-ignore) keep working.
+ *
+ * `signal` disambiguates *why* `ETIMEDOUT` fired: when it is `'SIGKILL'` the
+ * direct child itself was still running and got killed at the bound: the
+ * common case. When it is anything else (including `null`), the direct
+ * child had already exited — `status`/`signal` on the result reflect its
+ * real exit — but this call was still blocked waiting for its stdout/stderr
+ * pipe to reach EOF, which only happens once every process holding that
+ * pipe's write end (the child *and* any surviving descendant it handed the
+ * fd to) has closed it. A surviving, pipe-holding descendant reproduces
+ * that even though the child it came from is long gone (see
+ * `test/fixtures/process/spawn-detached-pipe-holder.mjs`).
+ *
+ * @template {Error & {code?: string, signal?: string | null}} E
+ * @param {E | null | undefined} error
+ * @param {{description: string, tier: string, boundMs: number, signal?: string | null}} context
+ * @returns {E | null | undefined}
+ */
+function enrichTimeoutError(error, { description, tier, boundMs, signal }) {
+  if (!error || error.code !== 'ETIMEDOUT') return error;
+  const effectiveSignal = signal !== undefined ? signal : error.signal;
+  const killClause = effectiveSignal === 'SIGKILL'
+    ? 'the direct child was killed (SIGKILL)'
+    : 'the direct child had already exited, but this call was still waiting for its stdout/stderr pipe to close';
+  error.message =
+    `\`${description}\` exceeded the '${tier}' tier bound of ${boundMs}ms; ${killClause}. ` +
+    `Any descendant the child spawned (detached, backgrounded, or otherwise ignoring signals) is not supervised ` +
+    `by this call and may still be running — holding that pipe open is enough to trigger this timeout even after ` +
+    `the child itself has exited. ` +
+    (tier === 'long' ? `Set ${AIWG_SYNC_LONG_TIMEOUT_MS_ENV} to a larger number of milliseconds, or 0 to remove the bound. ` : '') +
+    error.message;
+  return error;
+}
+
+/**
+ * Bounded `child_process.execSync`. Same arguments and return value as
+ * Node's `execSync(command, options)`, with a required `tier` inserted
+ * before `options`.
+ *
+ * @param {string} command
+ * @param {'quick'|'network'|'long'} tier
+ * @param {Record<string, unknown>} [options]
+ * @returns {Buffer | string}
+ */
+export function boundedExecSync(command, tier, options) {
+  assertValidTier(tier);
+  const boundMs = effectiveTimeoutMs(tier, options);
+  const nodeOptions = toNodeOptions(options, boundMs);
+  try {
+    return nodeExecSync(command, nodeOptions);
+  } catch (error) {
+    throw enrichTimeoutError(error, { description: command, tier, boundMs });
+  }
+}
+
+/**
+ * Bounded `child_process.execFileSync`. Same arguments and return value as
+ * Node's `execFileSync(file, args, options)`, with a required `tier`
+ * inserted before `options`. Unlike the native API, `args` is always
+ * required (pass `[]` for none) so tier can occupy a fixed position.
+ *
+ * @param {string} file
+ * @param {readonly string[]} args
+ * @param {'quick'|'network'|'long'} tier
+ * @param {Record<string, unknown>} [options]
+ * @returns {Buffer | string}
+ */
+export function boundedExecFileSync(file, args, tier, options) {
+  assertValidTier(tier);
+  const boundMs = effectiveTimeoutMs(tier, options);
+  const nodeOptions = toNodeOptions(options, boundMs);
+  try {
+    return nodeExecFileSync(file, args, nodeOptions);
+  } catch (error) {
+    throw enrichTimeoutError(error, { description: describeCommand(file, args), tier, boundMs });
+  }
+}
+
+/**
+ * Bounded `child_process.spawnSync`. Same arguments and return shape as
+ * Node's `spawnSync(command, args, options)`, with a required `tier`
+ * inserted before `options`. Unlike the native API, `args` is always
+ * required (pass `[]` for none) so tier can occupy a fixed position.
+ *
+ * `spawnSync` never throws; on timeout the returned object has an `error`
+ * with `code: 'ETIMEDOUT'` whose message has been enriched in place. In the
+ * common case the direct child was still running and gets killed at the
+ * bound, so `status: null` and `signal: 'SIGKILL'`. If the direct child had
+ * already exited but a surviving descendant is still holding its
+ * stdout/stderr pipe open, `status`/`signal` instead reflect that real exit
+ * (e.g. `status: 0`, `signal: null`) while `error.code` is still
+ * `'ETIMEDOUT'` — check `error`, not just `status`/`signal`, to detect the
+ * timeout in that case.
+ *
+ * @param {string} command
+ * @param {readonly string[]} args
+ * @param {'quick'|'network'|'long'} tier
+ * @param {Record<string, unknown>} [options]
+ * @returns {import('node:child_process').SpawnSyncReturns<Buffer | string>}
+ */
+export function boundedSpawnSync(command, args, tier, options) {
+  assertValidTier(tier);
+  const boundMs = effectiveTimeoutMs(tier, options);
+  const nodeOptions = toNodeOptions(options, boundMs);
+  const result = nodeSpawnSync(command, args, nodeOptions);
+  enrichTimeoutError(result.error, { description: describeCommand(command, args), tier, boundMs, signal: result.signal });
+  return result;
+}

package/dist/src/process/cli-command.mjs

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+// Share PATH/PATHEXT lookup with callers that can launch arbitrary batch files.
+function* executableCandidates(command, searchPath, pathExt, preferNative = false, cwd = process.cwd()) {
+  const candidates = path.isAbsolute(command)
+    ? [command]
+    : /[\\/]/.test(command)
+      ? [path.resolve(cwd, ...command.split(/[\\/]/))]
+      : searchPath.split(';').filter(Boolean).map(dir => path.join(dir, command));
+  for (const candidate of candidates) {
+    const pathExtensions = pathExt.split(';').filter(Boolean).map(ext => ext.toLowerCase());
+    const extension = path.extname(candidate).toLowerCase();
+    const extensions = extension && (pathExtensions.includes(extension) || existsSync(candidate))
+      ? ['']
+      : pathExtensions;
+    if (preferNative) {
+      extensions.sort((a, b) => Number(!/\.(?:exe|com)$/i.test(a)) - Number(!/\.(?:exe|com)$/i.test(b)));
+    }
+    for (const extension of extensions) {
+      const executable = `${candidate}${extension}`;
+      if (existsSync(executable)) yield executable;
+    }
+  }
+}
+
+export function resolveExecutable(
+  command,
+  platform = process.platform,
+  searchPath = process.env.PATH ?? '',
+  pathExt = process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD',
+  cwd = process.cwd(),
+) {
+  if (platform !== 'win32') return command;
+  for (const executable of executableCandidates(command, searchPath, pathExt, true, cwd)) {
+    return executable;
+  }
+  return command;
+}
+
+// npm's Windows shims cannot be spawned directly without a shell. Resolve only
+// their standard Node invocation; never evaluate batch contents or shell args.
+export function cliCommand(
+  command,
+  args,
+  platform = process.platform,
+  searchPath = process.env.PATH ?? '',
+  pathExt = process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD',
+  cwd = process.cwd(),
+) {
+  if (platform !== 'win32') return [command, args];
+  for (const shim of executableCandidates(command, searchPath, pathExt, false, cwd)) {
+    if (!/\.(?:cmd|bat)$/i.test(shim)) return [shim, args];
+    const contents = readFileSync(shim, 'utf8');
+    const entry = contents.match(
+      /^\s*(?:endLocal & goto #_undefined_# 2>NUL \|\| title %COMSPEC% & )?(?:set PATHEXT=%PATHEXT:;.JS;=;% & )?"%_prog%"\s+((?:(?:"[^"\r\n&|<>^%]*"|[^\s"&|<>^%]+)\s+)*)"%dp0%\\([^"\r\n]+)"\s+%\*\s*$/m,
+    );
+    // Node distributions bundle npm/npx launchers with named entry variables
+    // rather than cmd-shim's _prog invocation. Resolve their local JS entry.
+    const bundled = !entry && /^(?:npm|npx)\.cmd$/i.test(path.basename(shim))
+      ? contents.match(/^SET "(NPM|NPX)_CLI_JS=%~dp0\\(node_modules\\npm\\bin\\(?:npm|npx)-cli\.js)"\s*$/im)
+      : null;
+    if (!entry && (!bundled || !contents.includes(`"%NODE_EXE%" "%${bundled[1]}_CLI_JS%" %*`))) {
+      throw new Error(`Unsupported Windows CLI shim: ${shim}`);
+    }
+    const nodeArgs = entry
+      ? Array.from(entry[1].matchAll(/"([^"]*)"|([^\s"]+)/g), match => match[1] ?? match[2])
+      : [];
+    const script = path.resolve(path.dirname(shim), ...(entry ? entry[2] : bundled[2]).split('\\'));
+    if (!existsSync(script)) throw new Error(`Missing Windows CLI entry point: ${script}`);
+    const localNode = path.join(path.dirname(shim), 'node.exe');
+    return [existsSync(localNode) ? localNode : process.execPath, [...nodeArgs, script, ...args]];
+  }
+  return [command, args];
+}

package/dist/src/providers/capability-matrix.js

@@ -82,6 +82,14 @@ export function getProviderCapabilities(providerKey) {
     }
     return undefined;
 }
+/**
+ * Get the S0 route-feasibility row for a provider by key or alias.
+ * Returns undefined when the matrix carries no row (e.g. registry-only
+ * `generic`, which is not a matrix provider).
+ */
+export function getRouteFeasibility(providerKey) {
+    return getProviderCapabilities(providerKey)?.route_feasibility;
+}
 export function getAgentCapabilities(providerKey, agentType = 'default') {
     const caps = getProviderCapabilities(providerKey);
     if (!caps?.agent_capabilities)