aiden-runtime 4.9.0 → 4.9.2

package/dist/core/v4/update/depWarningFilter.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/update/depWarningFilter.ts — v4.9.1.
+ *
+ * Strip Node `DeprecationWarning` noise (DEP0190 and friends) from
+ * npm install stderr before it reaches the user. Filtered lines are
+ * preserved in `~/.aiden/logs/update.log` so diagnostics aren't lost.
+ *
+ * Conservative match — only filters lines that BOTH look like a Node
+ * deprecation header AND name a DEP code or the trace-deprecation hint.
+ * Legitimate npm errors (EACCES, ENOTFOUND, ENOENT, etc.) pass through.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDeprecationLine = isDeprecationLine;
+exports.splitStderr = splitStderr;
+exports.logFilteredWarnings = logFilteredWarnings;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+/** True iff the line is Node-deprecation chatter we should hide. */
+function isDeprecationLine(line) {
+    // Node's deprecation banner header: "(node:NNNN) [DEP0190] DeprecationWarning: ..."
+    if (/^\s*\(node:\d+\)\s*(?:\[DEP\d+\]\s*)?DeprecationWarning:/.test(line))
+        return true;
+    // The follow-up hint Node emits underneath the header.
+    if (/Use `node --trace-deprecation/.test(line))
+        return true;
+    // Bare DEP code lines (some Node versions emit these stand-alone).
+    if (/^\s*\[DEP\d+\]/.test(line))
+        return true;
+    return false;
+}
+/**
+ * Split an stderr blob into `kept` (user-visible) and `filtered`
+ * (deprecation noise, routed to the diagnostic log).
+ */
+function splitStderr(blob) {
+    if (!blob)
+        return { kept: '', filtered: '' };
+    const lines = blob.split(/\r?\n/);
+    const kept = [];
+    const filtered = [];
+    for (const ln of lines) {
+        if (isDeprecationLine(ln))
+            filtered.push(ln);
+        else
+            kept.push(ln);
+    }
+    return { kept: kept.join('\n'), filtered: filtered.join('\n') };
+}
+/**
+ * Append filtered lines to `~/.aiden/logs/update.log` with an ISO
+ * timestamp header. Fail-open: a log-write failure must NEVER crash
+ * the install path.
+ */
+async function logFilteredWarnings(filtered, opts = {}) {
+    if (!filtered || !filtered.trim())
+        return;
+    try {
+        const root = opts.aidenRoot ?? node_path_1.default.join(node_os_1.default.homedir(), '.aiden');
+        const logDir = node_path_1.default.join(root, 'logs');
+        await node_fs_1.promises.mkdir(logDir, { recursive: true });
+        const entry = `[${new Date().toISOString()}] update.npm-deprecation:\n${filtered}\n\n`;
+        await node_fs_1.promises.appendFile(node_path_1.default.join(logDir, 'update.log'), entry, 'utf8');
+    }
+    catch { /* fail-open */ }
+}

package/dist/core/v4/update/executeInstall.js

@@ -42,11 +42,20 @@
  *   - No registry probe — call `checkForUpdate` first if you need to
  *     know whether an install is warranted.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INSTALL_TIMEOUT_MS = void 0;
 exports.executeInstall = executeInstall;
 exports.parseInstalledVersion = parseInstalledVersion;
 const node_child_process_1 = require("node:child_process");
+const node_os_1 = __importDefault(require("node:os"));
+const depWarningFilter_1 = require("./depWarningFilter");
+const platformInstructions_1 = require("./platformInstructions");
+const progressBar_1 = require("../../../cli/v4/ui/progressBar");
+const spawnCommand_1 = require("../util/spawnCommand");
+const recoveryScript_1 = require("./recoveryScript");
 /** 90 s wall-clock cap. Generous on cold caches / slow networks. */
 exports.INSTALL_TIMEOUT_MS = 90000;
 const DEFAULT_PACKAGE_SPEC = 'aiden-runtime@latest';
@@ -64,39 +73,64 @@ async function executeInstall(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? exports.INSTALL_TIMEOUT_MS;
     const packageSpec = opts.packageSpec ?? DEFAULT_PACKAGE_SPEC;
     const platform = opts.platform ?? process.platform;
+    const home = opts.home ?? node_os_1.default.homedir();
+    const env = opts.env ?? process.env;
+    const onPhase = opts.onPhase ?? ((_p) => { });
     return new Promise((resolve) => {
         const args = ['install', '-g', packageSpec];
-        // v4.8.1 Slice 2 — drop `shell: true`. Node 20+ emits
-        // `DeprecationWarning: Passing args to a child process with shell
-        // option true can lead to security vulnerabilities` whenever
-        // shell:true is paired with an args array. We don't need the
-        // shell either — on Windows we spawn `npm.cmd` explicitly (the
-        // shim that PATHEXT would otherwise resolve to); on POSIX we
-        // spawn `npm` directly. No user input flows into argv on either
-        // path so the prior shell-resolution wasn't load-bearing.
-        const cmd = platform === 'win32' ? 'npm.cmd' : 'npm';
-        const spawnOpts = {
-            stdio: ['ignore', 'pipe', 'pipe'],
-        };
+        // v4.9.2 — route through the shared spawnCommand helper. On
+        // Windows it wraps `npm.cmd` through `cmd.exe /d /s /c` with
+        // escaped args (no shell:true → no argument injection; no plain
+        // .cmd spawn → no Node 20+ EINVAL). On Unix it's a direct spawn.
+        onPhase('spawning');
         let child;
         try {
-            child = spawn(cmd, args, spawnOpts);
+            const r = (0, spawnCommand_1.spawnCommand)('npm', args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                platform,
+                spawnImpl: spawn,
+            });
+            child = r.child;
         }
         catch (err) {
-            resolve({
-                success: false,
-                error: `Could not launch npm: ${err.message}. ` +
-                    `Run \`npm install -g aiden-runtime@latest\` manually.`,
-            });
+            // Synchronous spawn failure (helper crash, cmd.exe missing,
+            // invalid argv). Drop a recovery script the user can run by
+            // hand and report its path.
+            (async () => {
+                let recoveryPath = null;
+                try {
+                    recoveryPath = await (0, recoveryScript_1.writeRecoveryScript)({ platform, home, packageSpec });
+                }
+                catch { /* best-effort */ }
+                resolve({
+                    success: false,
+                    error: `Could not launch npm: ${err.message}. ` +
+                        (recoveryPath
+                            ? `A recovery script was written to ${recoveryPath} — run it to complete the install.`
+                            : `Run \`npm install -g ${packageSpec}\` manually.`),
+                });
+            })();
             return;
         }
         let stdoutBuf = '';
         let stderrBuf = '';
+        // v4.9.1 — parse phase signal off each chunk.
+        const tryEmitPhase = (chunk) => {
+            for (const ln of chunk.split(/\r?\n/)) {
+                const p = (0, progressBar_1.detectNpmPhase)(ln);
+                if (p)
+                    onPhase(p);
+            }
+        };
         child.stdout?.on('data', (chunk) => {
-            stdoutBuf += chunk.toString();
+            const s = chunk.toString();
+            stdoutBuf += s;
+            tryEmitPhase(s);
         });
         child.stderr?.on('data', (chunk) => {
-            stderrBuf += chunk.toString();
+            const s = chunk.toString();
+            stderrBuf += s;
+            tryEmitPhase(s);
         });
         // Timeout — kill the child + resolve as a failure with the captured
         // output so the user sees what npm was doing.
@@ -121,7 +155,11 @@ async function executeInstall(opts = {}) {
         child.on('close', (code) => {
             clearTimeout(timer);
             const stdout = stdoutBuf;
-            const stderr = stderrBuf;
+            // v4.9.1 — strip Node DEP* noise from stderr before any surfacing
+            // to the user. Filtered lines land in ~/.aiden/logs/update.log.
+            const { kept: stderr, filtered } = (0, depWarningFilter_1.splitStderr)(stderrBuf);
+            if (filtered)
+                void (0, depWarningFilter_1.logFilteredWarnings)(filtered);
             const exitCode = code ?? -1;
             if (timedOut) {
                 resolve({
@@ -134,14 +172,16 @@ async function executeInstall(opts = {}) {
             }
             // Permission-denied: surface platform-specific remediations.
             if (isPermissionDenied(stdout, stderr, exitCode)) {
+                onPhase('failed');
                 resolve({
                     success: false,
-                    error: permissionDeniedMessage(platform),
+                    error: permissionDeniedMessage(platform, home, env),
                     stdout, stderr, exitCode,
                 });
                 return;
             }
             if (exitCode !== 0) {
+                onPhase('failed');
                 resolve({
                     success: false,
                     error: `Install failed (npm exit ${exitCode}). ` +
@@ -153,6 +193,7 @@ async function executeInstall(opts = {}) {
             }
             // Success — parse installed version from npm output. Pattern:
             // "+ aiden-runtime@4.1.3" or "added 1 package ... aiden-runtime@4.1.3"
+            onPhase('installed');
             const installedVersion = parseInstalledVersion(stdout) ?? parseInstalledVersion(stderr) ?? undefined;
             resolve({
                 success: true,
@@ -190,38 +231,14 @@ function isPermissionDenied(stdout, stderr, exitCode) {
     return false;
 }
 /**
- * Build the platform-specific copy-paste remediation. Provides three
- * distinct paths — system-wide-with-elevation (Windows admin),
- * sudo (macOS/Linux), or user-local-prefix (cross-platform) — so the
- * user has options without us trying to self-escalate to UAC/sudo
- * from inside the running REPL.
+ * v4.9.1 — Build the platform-specific copy-paste remediation. Delegates
+ * to `platformInstructions.ts` for the heavy lifting so the same builder
+ * powers both EPERM remediation + stale-prefix warnings + the future
+ * `aiden update --setup-user-prefix` helper.
  */
-function permissionDeniedMessage(platform) {
-    const userLocal = 'Or use a user-local npm prefix to avoid privileges entirely:\n' +
-        '              npm config set prefix ~/.npm-global\n' +
-        '              export PATH=~/.npm-global/bin:$PATH    # add to your shell profile\n' +
-        '              npm install -g aiden-runtime@latest';
-    if (platform === 'win32') {
-        return [
-            'Install failed: permission denied (npm needs Administrator for global install).',
-            '',
-            'To update manually:',
-            '  Windows:  Open PowerShell as Administrator, then:',
-            '              npm install -g aiden-runtime@latest',
-            '',
-            userLocal,
-        ].join('\n');
-    }
-    // darwin / linux / others — sudo path.
-    return [
-        'Install failed: permission denied (npm needs sudo for global install).',
-        '',
-        'To update manually:',
-        '  macOS / Linux:',
-        '              sudo npm install -g aiden-runtime@latest',
-        '',
-        userLocal,
-    ].join('\n');
+function permissionDeniedMessage(platform, home, env) {
+    const instr = (0, platformInstructions_1.permissionDeniedInstructions)({ platform, home, env });
+    return [instr.headline, '', ...instr.steps].join('\n');
 }
 /**
  * Find the installed version in npm output. Two common patterns:

package/dist/core/v4/update/platformInstructions.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/update/platformInstructions.ts — v4.9.1.
+ *
+ * Per-platform copy-paste remediation text for:
+ *   - EPERM / EACCES during global npm install
+ *   - Stale / risky npm prefix detection
+ *
+ * Branches purely on `process.platform` (and `$SHELL` for unix shell-
+ * rc-file recommendations). Shell syntax MUST be correct per-platform:
+ * PowerShell on Windows, bash/zsh on Unix. Cross-contamination is a
+ * regression (the v4.9.0 bug we're hot-fixing).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectShell = detectShell;
+exports.permissionDeniedInstructions = permissionDeniedInstructions;
+exports.detectStalePrefix = detectStalePrefix;
+/**
+ * Detect the user's interactive shell on POSIX. Returns the basename
+ * (`zsh` / `bash` / `sh`) or null when undetectable. Pure — env is
+ * injected so tests pin a value.
+ */
+function detectShell(env = process.env) {
+    const sh = env.SHELL;
+    if (!sh)
+        return null;
+    const last = sh.split(/[\\/]/).pop() || '';
+    return last.toLowerCase() || null;
+}
+/** rc-file path the user should edit, per shell. POSIX only. */
+function rcFileFor(shell, home) {
+    if (shell === 'zsh')
+        return `${home}/.zshrc`;
+    if (shell === 'bash')
+        return `${home}/.bashrc   (or ~/.bash_profile on macOS)`;
+    return `${home}/.profile`;
+}
+/**
+ * Build the EPERM/EACCES remediation. Two options per platform —
+ * elevation (one-time) and user-local prefix (permanent, no privs).
+ */
+function permissionDeniedInstructions(opts) {
+    const env = opts.env ?? process.env;
+    if (opts.platform === 'win32') {
+        return {
+            headline: 'Install failed: permission denied. npm needs Administrator for a global install on Windows.',
+            shell: 'powershell',
+            steps: [
+                'Option 1 — Run once with elevated privileges:',
+                '  • Open PowerShell as Administrator (right-click → "Run as administrator")',
+                '  • npm install -g aiden-runtime@latest',
+                '',
+                'Option 2 — Permanent: switch npm to a user-local prefix (no admin needed ever again):',
+                '  • npm config set prefix "$env:USERPROFILE\\AppData\\Roaming\\npm"',
+                '  • [Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\\AppData\\Roaming\\npm;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")',
+                '  • Close + reopen PowerShell, then:  npm install -g aiden-runtime@latest',
+            ],
+        };
+    }
+    // POSIX: darwin / linux / *bsd / etc.
+    const shell = detectShell(env);
+    const rcFile = rcFileFor(shell, opts.home);
+    return {
+        headline: `Install failed: permission denied. npm needs sudo for a global install on ${opts.platform}.`,
+        shell: shell ?? undefined,
+        rcFile,
+        steps: [
+            'Option 1 — Run once with elevated privileges:',
+            '  • sudo npm install -g aiden-runtime@latest',
+            '',
+            'Option 2 — Permanent: switch npm to a user-local prefix (no sudo needed ever again):',
+            `  • npm config set prefix "${opts.home}/.npm-global"`,
+            `  • echo 'export PATH="${opts.home}/.npm-global/bin:$PATH"' >> ${rcFile}`,
+            `  • source ${rcFile}`,
+            '  • npm install -g aiden-runtime@latest',
+        ],
+    };
+}
+/**
+ * Stale / risky prefix detection. Returns a warning when the npm
+ * `prefix` config points at a location that needs elevation OR is
+ * known to cause permission churn. `null` when the prefix is safe.
+ *
+ * `writable` is the result of a `fs.access` check the caller does
+ * before invoking us (we don't want to do filesystem I/O in a pure
+ * builder — caller controls the side effect).
+ */
+function detectStalePrefix(opts) {
+    const env = opts.env ?? process.env;
+    const p = opts.prefix;
+    // Windows risk: Program Files.
+    if (opts.platform === 'win32') {
+        if (/^[a-zA-Z]:\\Program Files/i.test(p)) {
+            return {
+                warning: `npm prefix is "${p}" — global installs here require Administrator every time.`,
+                switchSteps: [
+                    'Switch to a user-local prefix to avoid the prompt forever:',
+                    '  • npm config set prefix "$env:USERPROFILE\\AppData\\Roaming\\npm"',
+                    '  • [Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\\AppData\\Roaming\\npm;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")',
+                    '  • Close + reopen PowerShell.',
+                ],
+            };
+        }
+        return null;
+    }
+    // POSIX risk: /usr or /usr/local without write access.
+    const risky = p === '/usr' || p === '/usr/local' || p.startsWith('/usr/');
+    if (risky && !opts.writable) {
+        const shell = detectShell(env);
+        const rcFile = rcFileFor(shell, opts.home);
+        return {
+            warning: `npm prefix is "${p}" — global installs here require sudo every time.`,
+            switchSteps: [
+                'Switch to a user-local prefix to avoid sudo forever:',
+                `  • npm config set prefix "${opts.home}/.npm-global"`,
+                `  • echo 'export PATH="${opts.home}/.npm-global/bin:$PATH"' >> ${rcFile}`,
+                `  • source ${rcFile}`,
+            ],
+        };
+    }
+    return null;
+}

package/dist/core/v4/update/recoveryScript.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/update/recoveryScript.ts — v4.9.2 SLICE 1.
+ *
+ * Fallback when spawnCommand() itself fails to launch npm (synchronous
+ * throw — invalid argv shape, cmd.exe missing, etc.). We write a small
+ * shell script the user can run by hand to complete the install and
+ * report its path in the failure message. Honest: we tried, we couldn't
+ * launch, here's the exact thing to type.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRecoveryScript = writeRecoveryScript;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Write a recovery script under `~/.aiden/`:
+ *   - Windows → update-recovery.ps1 (PowerShell)
+ *   - Unix    → update-recovery.sh  (bash, +x)
+ *
+ * Returns the absolute path written. Creates `~/.aiden/` if missing.
+ */
+async function writeRecoveryScript(input) {
+    const aidenDir = node_path_1.default.join(input.home, '.aiden');
+    await node_fs_1.promises.mkdir(aidenDir, { recursive: true });
+    if (input.platform === 'win32') {
+        const p = node_path_1.default.join(aidenDir, 'update-recovery.ps1');
+        const body = [
+            '# Aiden v4.9.2 — install-recovery fallback.',
+            '# Run from PowerShell (right-click → "Run with PowerShell" if associated).',
+            `Write-Host "Installing ${input.packageSpec} via npm..."`,
+            `npm install -g ${input.packageSpec}`,
+            'if ($LASTEXITCODE -ne 0) {',
+            '  Write-Host "If you saw EPERM/EACCES, retry from an Administrator PowerShell."',
+            '  exit $LASTEXITCODE',
+            '}',
+            `Write-Host "Done. Type 'aiden' to launch the new version."`,
+            '',
+        ].join('\r\n');
+        await node_fs_1.promises.writeFile(p, body, 'utf8');
+        return p;
+    }
+    const p = node_path_1.default.join(aidenDir, 'update-recovery.sh');
+    const body = [
+        '#!/usr/bin/env bash',
+        '# Aiden v4.9.2 — install-recovery fallback.',
+        'set -e',
+        `echo "Installing ${input.packageSpec} via npm..."`,
+        `if ! npm install -g ${input.packageSpec}; then`,
+        '  echo "Install failed. If you saw EACCES, retry with: sudo $0"',
+        '  exit 1',
+        'fi',
+        'echo "Done. Type \\"aiden\\" to launch the new version."',
+        '',
+    ].join('\n');
+    await node_fs_1.promises.writeFile(p, body, 'utf8');
+    try {
+        await node_fs_1.promises.chmod(p, 0o755);
+    }
+    catch { /* noop on platforms that don't support chmod */ }
+    return p;
+}

package/dist/core/v4/util/spawnCommand.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/util/spawnCommand.ts — v4.9.2 SLICE 1.
+ *
+ * Cross-platform spawn helper that survives the Node 18.20+ / 20+
+ * Windows EINVAL trap on `.cmd` / `.bat` shims. Two surfaces consume it:
+ *   - core/v4/update/executeInstall.ts  (spawns `npm install -g …`)
+ *   - core/v4/mcp/transport.ts          (spawns user-configured MCP servers,
+ *                                        typically `npx -y <server>`)
+ *
+ * Both previously called `spawn(cmd, args, { shell: false })` directly,
+ * which throws EINVAL on Windows when `cmd` resolves to `.cmd` / `.bat`.
+ * The naive fix — `shell: true` — would silently permit argument
+ * injection through MCP server config (user-supplied command line),
+ * so we route Windows shims through `cmd.exe /d /s /c <quoted>` with
+ * `windowsVerbatimArguments: true` and manual cmd-meta escaping.
+ *
+ * Returns the raw ChildProcess (not a callback abstraction): both
+ * consumers need the full duplex surface (stdin write, stdout/stderr
+ * stream, exit + error events, SIGTERM → SIGKILL escalation). The
+ * helper's value is resolving the EINVAL trap, not abstracting I/O.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCommand = resolveCommand;
+exports.escapeCmdArg = escapeCmdArg;
+exports.spawnCommand = spawnCommand;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Resolve a bare command name to an absolute disk path via PATH lookup.
+ * On Windows tries PATHEXT order (.cmd, .exe, .bat, .ps1). If `command`
+ * is already absolute or contains a path separator, returns it verbatim
+ * (still detects shim suffix). Returns null when no match — caller can
+ * still spawn the bare name and let node:child_process emit ENOENT.
+ *
+ * Implemented in pure Node (no `where` subprocess — that would face
+ * the same spawn problem).
+ */
+function resolveCommand(command, opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const isWin = platform === 'win32';
+    // Already absolute or has a separator → trust the caller, just detect suffix.
+    if (node_path_1.default.isAbsolute(command) || command.includes('/') || command.includes('\\')) {
+        if (!(0, node_fs_1.existsSync)(command))
+            return null;
+        return { path: command, isShim: isWin && /\.(cmd|bat)$/i.test(command) };
+    }
+    const pathDirs = (env.PATH ?? env.Path ?? '').split(node_path_1.default.delimiter).filter(Boolean);
+    const pathExts = isWin
+        ? (env.PATHEXT ?? '.CMD;.EXE;.BAT;.COM').split(';').filter(Boolean)
+        : [''];
+    for (const dir of pathDirs) {
+        for (const ext of pathExts) {
+            const candidate = node_path_1.default.join(dir, command + ext);
+            try {
+                if ((0, node_fs_1.existsSync)(candidate) && (0, node_fs_1.statSync)(candidate).isFile()) {
+                    return { path: candidate, isShim: isWin && /\.(cmd|bat)$/i.test(candidate) };
+                }
+            }
+            catch { /* permissions / ENOENT — keep walking */ }
+        }
+    }
+    return null;
+}
+/**
+ * Escape an argv element for cmd.exe /c invocation. Wraps in double
+ * quotes if the value contains whitespace or any cmd metachar (& | <
+ * > ( ) @ ^ "), doubling any embedded quotes. Used together with
+ * `windowsVerbatimArguments: true` so Node passes our quoted string
+ * straight through to cmd.exe without its own (broken-for-.cmd)
+ * quoting heuristics.
+ *
+ * Reference: cross-spawn / npm-cli use the same pattern; Node 20+
+ * refuses to do this for us when spawning .cmd files because the
+ * heuristics were the source of CVE-2024-27980.
+ */
+function escapeCmdArg(s) {
+    if (s.length === 0)
+        return '""';
+    // Conservative: any whitespace OR cmd metachar triggers quoting.
+    if (!/[\s&|<>()@^"]/.test(s))
+        return s;
+    // Double internal quotes (cmd.exe convention) and wrap.
+    return '"' + s.replace(/"/g, '""') + '"';
+}
+/**
+ * Cross-platform spawn. See file header for the why.
+ *
+ *   - Unix              → spawn(cmd, args, { shell:false, ...opts })
+ *   - Win + .cmd/.bat   → spawn('cmd.exe', ['/d','/s','/c', quoted], {
+ *                            shell:false,
+ *                            windowsVerbatimArguments: true, ...opts })
+ *   - Win + .exe / abs  → spawn(cmd, args, { shell:false, ...opts })
+ *   - Win + bare name   → resolveCommand() picks; bucket by suffix.
+ *
+ * Never throws synchronously for "not found" — emits 'error' on the
+ * returned ChildProcess like plain spawn() does. May throw synchronously
+ * for the same reasons spawn() itself does (e.g. invalid argv types).
+ */
+function spawnCommand(command, args, opts = {}) {
+    const spawn = opts.spawnImpl ?? node_child_process_1.spawn;
+    const platform = opts.platform ?? process.platform;
+    const isWin = platform === 'win32';
+    const baseOpts = {
+        stdio: opts.stdio ?? ['pipe', 'pipe', 'pipe'],
+        env: opts.env,
+        cwd: opts.cwd,
+        shell: false,
+    };
+    if (!isWin) {
+        const child = spawn(command, args, baseOpts);
+        return { child, resolvedCmd: command, resolvedArgs: args, viaCmdExe: false };
+    }
+    // Windows: detect shim suffix.
+    const resolved = resolveCommand(command, { platform, env: opts.env });
+    const isShim = resolved
+        ? resolved.isShim
+        : /\.(cmd|bat)$/i.test(command); // unresolved but caller passed .cmd explicitly
+    if (!isShim) {
+        const child = spawn(command, args, baseOpts);
+        return { child, resolvedCmd: command, resolvedArgs: args, viaCmdExe: false };
+    }
+    // Wrap through cmd.exe /d /s /c. Pass resolved path if we have it so
+    // we don't re-walk PATH; otherwise let cmd.exe resolve the bare name.
+    //
+    // cmd.exe /s rule: it strips a single pair of outer quotes from the
+    // command line and parses the remainder. We therefore wrap the entire
+    // escaped argv sequence in an OUTER quote pair on top of each
+    // individual arg's escapeCmdArg quoting. Otherwise a command path
+    // containing whitespace (e.g. "C:\Program Files\nodejs\npm.CMD")
+    // gets its inner quotes stripped, breaking on the first space.
+    const target = resolved?.path ?? command;
+    const line = '"' + [target, ...args].map(escapeCmdArg).join(' ') + '"';
+    const cmdArgs = ['/d', '/s', '/c', line];
+    const child = spawn('cmd.exe', cmdArgs, {
+        ...baseOpts,
+        windowsVerbatimArguments: true,
+    });
+    return { child, resolvedCmd: 'cmd.exe', resolvedArgs: cmdArgs, viaCmdExe: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-runtime",
-  "version": "4.9.0",
+  "version": "4.9.2",
   "publishConfig": {
     "access": "public"
   },