@omega.js/mcp-router 0.1.0

package/src/cli.js

@@ -0,0 +1,223 @@
+/**
+ * `omega-mcp` — the management CLI for the router's upstream registry.
+ *
+ * It reads the LAYERED view (bundled defaults + overlay) and writes ONLY the
+ * overlay at `~/.omega/mcp-router/servers/`: enabling, disabling, adding,
+ * removing, and caching tool schemas all land there. A bundled default is
+ * never edited, only shadowed — for a consumer it lives in node_modules.
+ *
+ * Registration is not this CLI's job: the omega Claude plugin declares the
+ * router in its .mcp.json, so there is nothing to sync into a client config.
+ */
+
+const registry = require('./lib/registry.js');
+const { resolveSpawn } = require('./lib/env.js');
+// The one-shot spawn-connect-list-close the router's own refresh runs, so this
+// CLI carries the same deadline, read budget, and failure cleanup. The helper
+// requires the SDK only once that path is reached, so commands that don't need
+// it (list, help) still work even when node_modules is missing.
+const { listToolsOnce } = require('./lib/oneshot.js');
+
+/**
+ * Spawn an upstream once, read its tool list, and cache it to the overlay.
+ *
+ * @param {string} name - Upstream name
+ * @param {object} layers - `{ bundledDir, overlayDir }`
+ * @returns {Promise<number>} How many tools were cached
+ */
+async function fetchAndCacheSchema(name, layers) {
+  const upstream = registry.loadUpstream(name, layers);
+  if (!upstream) throw new Error(`Server "${name}" not found`);
+  if (!upstream.command) throw new Error(`Server "${name}" has no command`);
+
+  const spawn = resolveSpawn(upstream);
+  const tools = await listToolsOnce({
+    command: spawn.command,
+    args: spawn.args,
+    env: { ...process.env, ...spawn.env },
+  });
+
+  registry.patchOverlayEntry(name, { tools }, layers);
+  return tools.length;
+}
+
+const HELP = `
+Usage: omega-mcp <command> [name] [args...]
+
+Commands:
+  list, ls              List all upstream servers, status, and cached tool counts
+  enable, on <name>     Enable an upstream (auto-refreshes schema cache)
+                        --force overrides a "locked": true upstream
+  disable, off <name>   Disable an upstream
+  add <name> <cmd> ...  Add a private upstream (auto-refreshes schema cache)
+  remove, rm <name>     Remove a private upstream (bundled defaults: disable instead)
+  refresh <name>        Re-fetch and cache an upstream's tool schemas
+
+Architecture:
+  All upstreams are proxied through a single MCP server, "mcp-router".
+  Tools surface to Claude as: mcp__mcp-router__<upstream>__<tool>
+  Upstreams are lazy-spawned: no child processes until a tool is actually called.
+
+  Config is layered: the defaults bundled with @omega.js/mcp-router, then your
+  overlay at ~/.omega/mcp-router/servers/<name>/config.json, whose top-level
+  keys win. Every command here writes the overlay only. Secrets go in
+  ~/.omega/mcp-router/.env and reach a command as \${NAME} placeholders.
+
+  Per-chat control (from inside Claude):
+    router__list_upstreams, router__enable_upstream, router__disable_upstream,
+    router__refresh_upstream
+
+  Per-server config supports an optional "default": "auto" | "on-demand" field.
+  "on-demand" upstreams require Claude to call router__enable_upstream before
+  their tools become visible — useful for noisy servers.
+
+  An overlay entry may also carry "locked": true. A locked upstream refuses
+  every enable: this CLI's (unless you pass --force) and the per-chat
+  router__enable_upstream, which has no override. Disable and remove stay open.
+
+Examples:
+  omega-mcp list
+  omega-mcp enable chrome-devtools-extension
+  omega-mcp disable chrome-devtools
+  omega-mcp add my-server npx -y my-mcp-server@latest
+  omega-mcp refresh chrome-devtools
+`;
+
+/**
+ * Run one CLI invocation.
+ *
+ * @param {string[]} argv - Arguments after the bin name
+ * @param {object} [options] - `{ bundledDir, overlayDir, out, err }` (tests inject all four)
+ * @returns {Promise<number>} Process exit code
+ */
+async function run(argv, options = {}) {
+  const layers = registry.layers(options);
+  const out = options.out || ((line) => console.log(line));
+  const err = options.err || ((line) => console.error(line));
+
+  // `--force` is a flag on the command, never part of an added upstream's own
+  // command line, so it is stripped for the command/name positions only, and
+  // `add` keeps reading the RAW argv for the command it is being handed.
+  const force = argv.includes('--force');
+  const positional = argv.filter((arg) => arg !== '--force');
+  const command = positional[0];
+  const name = positional[1];
+
+  /**
+   * Best-effort cache refresh — report failure but never abort the caller.
+   *
+   * @param {string} target - Upstream name
+   * @returns {Promise<void>} Always resolves
+   */
+  const tryRefresh = async (target) => {
+    try {
+      const count = await fetchAndCacheSchema(target, layers);
+      out(`Cached ${count} tool(s) for "${target}"`);
+    } catch (error) {
+      err(`Warning: could not cache schema for "${target}": ${error.message}`);
+      err(`Run \`omega-mcp refresh ${target}\` later to retry.`);
+    }
+  };
+
+  if ((command === 'enable' || command === 'on' || command === 'disable' || command === 'off') && name) {
+    const upstream = registry.loadUpstream(name, layers);
+    if (!upstream) {
+      err(`Server "${name}" not found`);
+      return 1;
+    }
+    const enabled = command === 'enable' || command === 'on';
+    // A lock guards WAKING an upstream only: disable stays open.
+    if (enabled && upstream.locked && !force) {
+      err(registry.lockedRefusal(name));
+      return 1;
+    }
+    registry.patchOverlayEntry(name, { enabled }, layers);
+    out(`${enabled ? 'Enabled' : 'Disabled'} ${name}`);
+    if (enabled) await tryRefresh(name);
+    return 0;
+  }
+
+  if (command === 'add') {
+    const commandArgs = argv.slice(2);
+    if (!name || commandArgs.length === 0) {
+      err('Usage: omega-mcp add <name> <command> [args...]');
+      err('Example: omega-mcp add firebase npx -y firebase-tools@latest mcp');
+      return 1;
+    }
+    if (registry.loadUpstream(name, layers)) {
+      err(`Server "${name}" already exists. Remove it first or edit its config.json directly.`);
+      return 1;
+    }
+    registry.patchOverlayEntry(name, { enabled: true, command: commandArgs[0], args: commandArgs.slice(1) }, layers);
+    out(`Added ${name}`);
+    await tryRefresh(name);
+    return 0;
+  }
+
+  if ((command === 'remove' || command === 'rm') && name) {
+    if (!registry.removeOverlayEntry(name, layers)) {
+      if (registry.isBundled(name, layers)) {
+        err(`Server "${name}" is a bundled default and cannot be removed. Run \`omega-mcp disable ${name}\` instead.`);
+      } else {
+        err(`Server "${name}" not found`);
+      }
+      return 1;
+    }
+    out(registry.isBundled(name, layers)
+      ? `Removed your overrides for ${name} — the bundled default is back in effect`
+      : `Removed ${name}`);
+    return 0;
+  }
+
+  if (command === 'refresh' && name) {
+    try {
+      const count = await fetchAndCacheSchema(name, layers);
+      out(`Cached ${count} tool(s) for "${name}"`);
+      return 0;
+    } catch (error) {
+      err(`Refresh failed for "${name}": ${error.message}`);
+      return 1;
+    }
+  }
+
+  if (command === 'list' || command === 'ls') {
+    out('\nMCP Servers (proxied through mcp-router):\n');
+    for (const upstream of Object.values(registry.loadUpstreams(layers))) {
+      const status = upstream.enabled_on_disk ? '\x1b[32m●\x1b[0m' : '\x1b[90m○\x1b[0m';
+      const mode = upstream.default === 'on-demand' ? ' [on-demand]' : '';
+      const locked = upstream.locked ? ' [locked]' : '';
+      const source = upstream.bundled ? (upstream.overlaid ? ' (bundled, overridden)' : ' (bundled)') : ' (yours)';
+      const tools = upstream.tools.length ? ` (${upstream.tools.length} tools cached)` : ' (no cache)';
+      out(`  ${status} ${upstream.name}${mode}${locked}${source}${tools}`);
+    }
+    out('');
+    return 0;
+  }
+
+  if (command === 'help' || !command) {
+    out(HELP);
+    return 0;
+  }
+
+  err(`Unknown command: ${command}`);
+  err('Run "omega-mcp help" for usage information.');
+  return 1;
+}
+
+/**
+ * The bin entry — run argv and set the process exit code.
+ *
+ * @returns {void}
+ */
+function main() {
+  run(process.argv.slice(2))
+    .then((code) => {
+      process.exitCode = code;
+    })
+    .catch((err) => {
+      console.error(err && err.stack ? err.stack : String(err));
+      process.exitCode = 1;
+    });
+}
+
+module.exports = { run, main, fetchAndCacheSchema };

package/src/ensure-deps.js

@@ -0,0 +1,63 @@
+/**
+ * Dependency self-bootstrap for launches from a bare checkout.
+ *
+ * The plugin's .mcp.json runs the router straight out of the marketplace
+ * clone, and a fresh clone has no node_modules. Before any SDK import, this
+ * installs the package's own dependencies once — a no-op whenever they
+ * already resolve (dev checkouts with the monorepo installed, every launch
+ * after the first).
+ *
+ * This file runs BEFORE node_modules exists, so everything it requires — and
+ * everything those files require — must stay builtin-only.
+ */
+
+const path = require('node:path');
+
+const { resolveBin } = require('./lib/env.js');
+const { log } = require('./lib/log.js');
+
+const PKG_ROOT = path.join(__dirname, '..');
+
+// The exact specifier the router imports — the SDK's exports map has no
+// ./package.json entry, so probing a real export is the honest check.
+const PROBE = '@modelcontextprotocol/sdk/server/index.js';
+
+/**
+ * Make the package's dependencies resolvable, installing them if needed.
+ *
+ * @param {object} [options] - `{ resolve, spawnSync, pkgRoot }` seams for tests
+ * @returns {boolean} True when dependencies resolve (or were just installed)
+ */
+function ensureDeps(options = {}) {
+  const resolve = options.resolve || require.resolve;
+  const spawnSync = options.spawnSync || require('node:child_process').spawnSync;
+  const pkgRoot = options.pkgRoot || PKG_ROOT;
+
+  try {
+    resolve(PROBE, { paths: [pkgRoot] });
+    return true;
+  } catch {
+    log('info', 'first launch from a bare checkout — installing dependencies…');
+  }
+
+  // The bare name would need a PATH the router may not have (same reason the
+  // spawn shapes resolve theirs); win32 still needs the shell to run a .cmd,
+  // and quoting keeps the default `C:\Program Files\nodejs` install working.
+  const shell = process.platform === 'win32';
+  const npm = resolveBin('npm');
+
+  // stdout stays 'ignore' — this process's stdout is the MCP wire.
+  const result = spawnSync(shell ? `"${npm}"` : npm, ['install', '--omit=dev', '--no-fund', '--no-audit'], {
+    cwd: pkgRoot,
+    stdio: ['ignore', 'ignore', 'inherit'],
+    shell,
+  });
+
+  if (result.status !== 0) {
+    log('fatal', `npm install failed — run it in ${pkgRoot} and relaunch`);
+    return false;
+  }
+  return true;
+}
+
+module.exports = { ensureDeps, PKG_ROOT };

package/src/launch-cft.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * The `chrome-devtools-extension` upstream's launcher.
+ *
+ * chrome-devtools-mcp needs an explicit executable to drive an unpacked
+ * extension, and the one every machine already has is Chrome for Testing in
+ * puppeteer's download cache. This finds the newest CFT there — platform-aware,
+ * because the cache lays each platform out differently — and execs the MCP
+ * server against it, forwarding stdio so the router talks to it as usual.
+ *
+ * Set OMEGA_EXTENSION_PATH to the unpacked extension directory before the
+ * session starts and it is loaded into that Chrome.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const { resolveBin } = require('./lib/env.js');
+const { log } = require('./lib/log.js');
+
+const MCP_PACKAGE = 'chrome-devtools-mcp@1.4.0';
+
+/**
+ * Where puppeteer downloads Chrome for Testing.
+ *
+ * @returns {string} Absolute cache path
+ */
+function defaultCacheDir() {
+  return path.join(os.homedir(), '.cache', 'puppeteer', 'chrome');
+}
+
+/**
+ * The executable a CFT version directory holds on one platform. macOS hides
+ * it inside an .app bundle whose name changes with the channel, so that leg
+ * globs; linux and windows are fixed paths.
+ *
+ * @param {string} versionDir - Absolute `<cache>/<version>` directory
+ * @param {string} platform - A process.platform value
+ * @param {string} arch - A process.arch value
+ * @returns {string|null} Absolute executable path, or null when this dir has none
+ */
+function executableIn(versionDir, platform, arch) {
+  if (platform === 'darwin') {
+    const root = path.join(versionDir, arch === 'arm64' ? 'chrome-mac-arm64' : 'chrome-mac-x64');
+    let bundles;
+    try {
+      bundles = fs.readdirSync(root).filter((entry) => entry.endsWith('.app'));
+    } catch {
+      return null;
+    }
+    for (const bundle of bundles) {
+      const macos = path.join(root, bundle, 'Contents', 'MacOS');
+      let binaries;
+      try {
+        binaries = fs.readdirSync(macos);
+      } catch {
+        continue;
+      }
+      if (binaries.length > 0) return path.join(macos, binaries[0]);
+    }
+    return null;
+  }
+
+  const relative = platform === 'win32'
+    ? path.join('chrome-win64', 'chrome.exe')
+    : path.join('chrome-linux64', 'chrome');
+  const executable = path.join(versionDir, relative);
+  return fs.existsSync(executable) ? executable : null;
+}
+
+/**
+ * Compare two cache directory names (`mac_arm-150.0.7871.24`) by version,
+ * newest first — a plain string sort puts 99 above 150.
+ *
+ * @param {string} a - A directory name
+ * @param {string} b - Another directory name
+ * @returns {number} Sort order
+ */
+function byVersionDesc(a, b) {
+  const parts = (name) => (name.split('-').pop() || '').split('.').map((piece) => Number.parseInt(piece, 10) || 0);
+  const left = parts(a);
+  const right = parts(b);
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const diff = (right[index] || 0) - (left[index] || 0);
+    if (diff !== 0) return diff;
+  }
+  return b.localeCompare(a);
+}
+
+/**
+ * The newest Chrome for Testing executable in the cache.
+ *
+ * @param {object} [options] - `{ cacheDir, platform, arch }` — all injectable for tests
+ * @returns {string|null} Absolute executable path, or null when the cache holds none
+ */
+function findChromeForTesting(options = {}) {
+  const cacheDir = options.cacheDir || defaultCacheDir();
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+
+  let versions;
+  try {
+    versions = fs.readdirSync(cacheDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return null;
+  }
+
+  for (const version of versions.sort(byVersionDesc)) {
+    const executable = executableIn(path.join(cacheDir, version), platform, arch);
+    if (executable) return executable;
+  }
+  return null;
+}
+
+/**
+ * The chrome-devtools-mcp argv for a found executable.
+ *
+ * @param {string} executable - Absolute Chrome for Testing path
+ * @param {object} env - Environment to read OMEGA_EXTENSION_PATH from
+ * @returns {string[]} Arguments for `npx`
+ */
+function buildArgs(executable, env) {
+  const args = [
+    '-y',
+    MCP_PACKAGE,
+    '--isolated',
+    '--acceptInsecureCerts',
+    '--usage-statistics=false',
+    `--executablePath=${executable}`,
+  ];
+  if (env.OMEGA_EXTENSION_PATH) {
+    args.push(`--chromeArg=--load-extension=${env.OMEGA_EXTENSION_PATH}`);
+    args.push('--ignoreDefaultChromeArg=--disable-extensions');
+  }
+  args.push('--categoryExtensions');
+  return args;
+}
+
+/**
+ * Find CFT and exec the MCP server against it.
+ *
+ * @param {object} [options] - `{ find, spawn, env, exit }` seams for tests
+ * @returns {void}
+ */
+function main(options = {}) {
+  const find = options.find || findChromeForTesting;
+  const spawnFn = options.spawn || spawn;
+  const env = options.env || process.env;
+  const exit = options.exit || ((code) => process.exit(code));
+
+  const executable = find();
+  if (!executable) {
+    // No silent fallback to the user's own Chrome: an extension test in the
+    // personal browser is exactly what this upstream exists to avoid.
+    log('fatal', `No Chrome for Testing found in ${defaultCacheDir()}. Install one with \`npx puppeteer browsers install chrome\`.`);
+    return exit(1);
+  }
+
+  // win32 has no directly spawnable `npx` — it is npx.cmd, which Node only
+  // runs through a shell; quoting keeps the resolved absolute path working
+  // from the default `C:\Program Files\nodejs` install.
+  const shell = process.platform === 'win32';
+  const npx = resolveBin('npx');
+  const child = spawnFn(shell ? `"${npx}"` : npx, buildArgs(executable, env), { stdio: 'inherit', env, shell });
+  child.on('exit', (code, signal) => exit(signal ? 1 : code ?? 0));
+  return undefined;
+}
+
+module.exports = { findChromeForTesting, executableIn, buildArgs, byVersionDesc, defaultCacheDir, main };
+
+if (require.main === module) main();

package/src/launch-omega-extension.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * The `omega-extension` upstream's launcher.
+ *
+ * The extension MCP server lives inside @omega.js/manager, at
+ * `extension/mcp-server/index.js`. This resolves the manager's package root
+ * from its main export — the exports map deliberately has no `./package.json`
+ * entry, so the root is the main file's directory's parent — and runs the
+ * server with stdio forwarded to the router.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const { log } = require('./lib/log.js');
+
+const MANAGER_PACKAGE = '@omega.js/manager';
+const SERVER_RELATIVE = path.join('extension', 'mcp-server', 'index.js');
+
+/**
+ * The installed @omega.js/manager package root.
+ *
+ * @param {object} [options] - `{ resolve }` — the resolver seam (defaults to require.resolve)
+ * @returns {string|null} Absolute package root, or null when the manager is not installed
+ */
+function resolveManagerRoot(options = {}) {
+  const resolve = options.resolve || require.resolve;
+  const exists = options.exists || fs.existsSync;
+  try {
+    // main is dist/index.js — two dirnames up from it is the package root.
+    return path.dirname(path.dirname(resolve(MANAGER_PACKAGE)));
+  } catch {
+    // A bare checkout has no workspace links, but the manager package sits
+    // beside this one in the monorepo.
+    const sibling = path.join(__dirname, '..', '..', 'manager');
+    return exists(path.join(sibling, 'package.json')) ? sibling : null;
+  }
+}
+
+/**
+ * The extension MCP server entry inside an installed manager.
+ *
+ * @param {object} [options] - `{ resolve, exists }` seams for tests
+ * @returns {{server: string}|{error: string}} The entry path, or why there is none
+ */
+function resolveServerPath(options = {}) {
+  const exists = options.exists || fs.existsSync;
+  const root = resolveManagerRoot(options);
+  if (!root) return { error: `${MANAGER_PACKAGE} is not installed — the omega-extension upstream needs it on disk.` };
+
+  const server = path.join(root, SERVER_RELATIVE);
+  if (!exists(server)) return { error: `${MANAGER_PACKAGE} is installed at ${root} but ${SERVER_RELATIVE} is missing.` };
+  return { server };
+}
+
+/**
+ * Resolve the server and run it.
+ *
+ * @param {object} [options] - `{ resolve, exists, spawn, exit, execPath }` seams for tests
+ * @returns {void}
+ */
+function main(options = {}) {
+  const spawnFn = options.spawn || spawn;
+  const exit = options.exit || ((code) => process.exit(code));
+
+  const resolved = resolveServerPath(options);
+  if (resolved.error) {
+    log('fatal', resolved.error);
+    return exit(1);
+  }
+
+  // NODE_PATH carries this package's node_modules to the server: in a bare
+  // checkout the manager tree has none of its own, and the server's imports
+  // (the MCP SDK, ws) are declared here for exactly this launch. Ancestor
+  // node_modules still win wherever the monorepo is installed.
+  const nodePath = [path.join(__dirname, '..', 'node_modules'), process.env.NODE_PATH]
+    .filter(Boolean)
+    .join(path.delimiter);
+  const child = spawnFn(options.execPath || process.execPath, [resolved.server], {
+    stdio: 'inherit',
+    env: { ...process.env, NODE_PATH: nodePath },
+  });
+  child.on('exit', (code, signal) => exit(signal ? 1 : code ?? 0));
+  return undefined;
+}
+
+module.exports = { resolveManagerRoot, resolveServerPath, main };
+
+if (require.main === module) main();

package/src/lib/env.js

@@ -0,0 +1,118 @@
+/**
+ * Secrets and placeholders.
+ *
+ * `${NAME}` placeholders in an upstream's command/args/env resolve from the
+ * overlay `.env` first, then process.env — so tokens never live in a tracked
+ * config.json. `${NAME:-default}` takes the same lookups and falls back to the
+ * literal default when they all miss, which is what lets a bundled upstream
+ * carry an optional port without an `sh -c` wrapper around its command. Other
+ * shell forms (`${VAR:+...}`) are not ours and pass through untouched. A
+ * session env override is checked ahead of both lookups, so a per-session port
+ * reaches the placeholder that names it.
+ *
+ * One reserved name: `${MCP_ROUTER_ROOT}` always resolves to this package's
+ * root directory (checked BEFORE .env and process.env), which is how a
+ * bundled upstream points at a launcher script it ships with.
+ *
+ * Spawn shapes also get their bare `node`/`npm`/`npx` command resolved to an
+ * absolute path here, so a child comes up on machines where those names are
+ * not on the router's own PATH.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseEnv } = require('node:util');
+
+const { log } = require('./log.js');
+const { PACKAGE_ROOT, envFile } = require('./paths.js');
+
+const RESERVED = { MCP_ROUTER_ROOT: PACKAGE_ROOT };
+const RESOLVABLE_BINS = new Set(['node', 'npm', 'npx']);
+
+/**
+ * Read the overlay .env into a plain object. Node's own `util.parseEnv` does
+ * the parsing — quoting, escapes inside double quotes, `export` prefixes and
+ * trailing comments are all its business, never ours (Ian 2026-08-21).
+ *
+ * @param {string} [file] - Path to read; defaults to the resolved env file
+ * @returns {object} NAME → value (missing file is not an error — process.env may still answer)
+ */
+function loadEnvFile(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file || envFile(), 'utf8');
+  } catch {
+    return {};
+  }
+  return parseEnv(raw);
+}
+
+/**
+ * Substitute `${NAME}` and `${NAME:-default}` placeholders in one string.
+ *
+ * @param {string} str - The raw command/arg/env value
+ * @param {object} secrets - Values from the overlay .env
+ * @param {object} [overrides] - Session env override; beats both ambient sources
+ * @returns {string} The resolved string; a placeholder with no value and no default stays literal
+ */
+function interpolate(str, secrets, overrides = {}) {
+  return String(str).replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (whole, name, fallback) => {
+    if (RESERVED[name] !== undefined) return RESERVED[name];
+    if (overrides[name] !== undefined) return overrides[name];
+    if (secrets[name] !== undefined) return secrets[name];
+    if (process.env[name] !== undefined) return process.env[name];
+    // A default IS a value — nothing is missing, so nothing is warned about.
+    if (fallback !== undefined) return fallback;
+    log('warn', `No value for placeholder ${whole} (expected in ${envFile()} or the environment); leaving literal`);
+    return whole;
+  });
+}
+
+/**
+ * Resolve a bare `node`/`npm`/`npx` to the binary beside this process's own
+ * node. process.execPath is the real, already-resolved node even when the
+ * router was launched through a shell shim or from an nvm-only PATH, so its
+ * siblings are reachable where the bare name is not — which is the difference
+ * between a child that starts and a `Request timed out`.
+ *
+ * @param {string} cmd - The interpolated command from a registry entry
+ * @returns {string} The absolute sibling when it exists; otherwise `cmd` untouched, to fall back to PATH
+ */
+function resolveBin(cmd) {
+  if (cmd.includes('/') || cmd.includes('\\')) return cmd;
+  if (!RESOLVABLE_BINS.has(cmd)) return cmd;
+  if (cmd === 'node') return process.execPath;
+  // win32 names these npx.cmd/npm.cmd on disk; probe rather than assume.
+  const names = process.platform === 'win32' ? [`${cmd}.cmd`, cmd] : [cmd];
+  for (const name of names) {
+    const candidate = path.join(path.dirname(process.execPath), name);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return cmd;
+}
+
+/**
+ * Resolve an upstream's spawn shape. Re-reads .env on every call so a rotated
+ * token is picked up without a router restart (spawns are rare, the read is
+ * trivial).
+ *
+ * A session env override (`router__enable_upstream {env}`) feeds the same
+ * placeholder resolution, ahead of .env and process.env: the override is what
+ * the caller asked THIS child to run with, so a `${OMEGA_CDP_PORT:-9222}` in
+ * the spawn shape has to see it — the values are baked here now, not expanded
+ * later by a child shell.
+ *
+ * @param {object} upstream - A registry entry (`command`, `args`, `env`)
+ * @param {object} [overrideEnv] - Session env override for placeholder resolution
+ * @returns {{command: string, args: string[], env: object}} Interpolated spawn shape
+ */
+function resolveSpawn(upstream, overrideEnv = {}) {
+  const secrets = loadEnvFile();
+  return {
+    command: resolveBin(interpolate(upstream.command, secrets, overrideEnv)),
+    args: (upstream.args || []).map((arg) => interpolate(arg, secrets, overrideEnv)),
+    env: Object.fromEntries(Object.entries(upstream.env || {}).map(([key, value]) => [key, interpolate(value, secrets, overrideEnv)])),
+  };
+}
+
+module.exports = { loadEnvFile, interpolate, resolveBin, resolveSpawn, RESERVED };