@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/cli-resources.d.ts

@@ -1,4 +1,3 @@
-/** A single install method. Exactly one of the keys (npm/brew/script/binary) is set. */
 export type InstallMethod = {
     npm: string;
 } | {
@@ -8,21 +7,12 @@ export type InstallMethod = {
 } | {
     binary: BinarySpec;
 };
-/** Per-platform binary download spec. Keys are `<os>-<arch>` (e.g. darwin-arm64). */
 export interface BinarySpec {
     [platform: string]: {
         url: string;
-        /** Path inside the archive (relative). Required when url is a .tar.gz/.zip. */
         extract?: string;
     };
 }
-/**
- * How to verify a CLI is installed. Structured so we can dispatch to spawnSync
- * with an argv array — never through a shell.
- *
- * `which` — just check PATH for `cmd`.
- * `version` — spawn `cmd` with `args` and require exit 0.
- */
 export type CheckSpec = {
     kind: 'which';
     cmd: string;
@@ -31,135 +21,87 @@ export type CheckSpec = {
     cmd: string;
     args: string[];
 };
-/** Parsed CLI manifest. */
 export interface CliManifest {
-    /** Name as it appears on the command line (e.g. "higgsfield"). */
     name: string;
-    /** One-line summary shown in `agents cli list`. */
     description?: string;
-    /** Project homepage; used in detail view + post-install messaging. */
     homepage?: string;
-    /** Structured check spec; never a raw shell command. */
     check: CheckSpec;
-    /** Install methods tried in order; first one whose tool is available is used. */
     install: InstallMethod[];
-    /** Message printed after successful install — typically auth instructions. */
     postInstall?: string;
-    /** Origin layer this manifest was resolved from. */
     source: string;
-    /** Absolute path to the yaml file. */
     path: string;
 }
-/** A validation problem in a CLI manifest. */
 interface CliManifestError {
-    /** Filename that failed to parse. */
     file: string;
-    /** Human-readable reason. */
     reason: string;
 }
-/**
- * Parse a single CLI manifest from its YAML contents.
- * Returns a manifest on success; throws on schema violations so callers can
- * decide whether to surface or swallow the error per file.
- */
 export declare function parseCliManifest(contents: string, opts: {
     name: string;
     source: string;
     path: string;
 }): CliManifest;
-/**
- * Discover all CLI manifests resolvable from the current cwd. Returns valid
- * manifests and any parse errors separately so the CLI can show both.
- */
 export declare function listCliManifests(cwd?: string): {
     manifests: CliManifest[];
     errors: CliManifestError[];
 };
-/** Resolve a single CLI manifest by name. Returns null when not declared. */
 export declare function resolveCliManifest(name: string, cwd?: string): CliManifest | null;
 export declare function hasCommand(cmd: string): boolean;
-/**
- * Run the manifest's check. Dispatches on CheckSpec.kind — never invokes a
- * shell, never interpolates strings into a command line.
- */
 export declare function isCliInstalled(manifest: CliManifest): boolean;
-/**
- * Async, non-blocking sibling of {@link isCliInstalled}. Same dispatch and
- * Windows-shim retry, but over `execFile` so many manifests can be checked
- * concurrently — the fix for RUSH-2136, where `agents doctor --json` ran a dozen+
- * blocking 10s-timeout `spawnSync` checks SERIALLY (measured ~136s on an idle
- * box). `execFile`'s `timeout` still SIGKILLs a wedged check, so a single
- * hanging probe can't stall the whole set past 10s.
- */
 export declare function isCliInstalledAsync(manifest: CliManifest): Promise<boolean>;
-/**
- * Pick the first install method whose required host tool is available.
- * Returns null when none of the declared methods can run on this host.
- */
 export declare function selectInstallMethod(manifest: CliManifest): InstallMethod | null;
-/** Render a CheckSpec back to a human-readable command string (display only). */
 export declare function describeCheck(check: CheckSpec): string;
-/** Short description of a method for display. */
 export declare function describeMethod(method: InstallMethod): string;
 export interface InstallResult {
     manifest: CliManifest;
-    /** Method that was attempted (null if no compatible method existed). */
     method: InstallMethod | null;
-    /** True when the post-install `check` passed. */
     installed: boolean;
-    /** stdout/stderr captured from the install command, for surfacing on failure. */
     output?: string;
-    /** Set when the install runner threw or exited non-zero. */
     error?: string;
 }
-/**
- * Resolve the directory a `binary` install method downloads/extracts into.
- *
- * `/usr/local/bin` used to be hardcoded here, which fails on Apple Silicon
- * Macs where that directory is root-owned and not user-writable (Homebrew
- * moved on to /opt/homebrew but left /usr/local/bin behind). Resolution
- * order:
- *  1. `AGENTS_CLI_BIN_DIR` — explicit override, used as-is when set.
- *  2. `~/.local/bin` — the XDG user-bin dir already used for shims (see
- *     posixpath.ts / shims.ts); created with mkdir -p if missing.
- *  3. `/usr/local/bin` — last resort, for hosts where it's still writable.
- *     When it isn't either, throw an actionable error naming the env var and
- *     ~/.local/bin instead of letting curl/tar fail with a bare EACCES.
- *
- * Called once per install/dry-run so the same directory is used everywhere
- * that method is described or executed.
- */
 export declare function resolveBinDir(): string;
-/**
- * Display-only rendering of how a method would be run, for `--dry-run` and
- * status output. Not used by installCli — execution goes through runInstallMethod
- * which dispatches to spawnSync with argv arrays.
- */
 export declare function buildInstallCommand(method: InstallMethod): string;
-/**
- * Install a single CLI by running its first compatible method. Streams the
- * underlying command's output to the parent terminal so users see brew/npm
- * progress live. Verifies success by re-running `check`.
- */
 export declare function installCli(manifest: CliManifest, opts?: {
     dryRun?: boolean;
+    logToStderr?: boolean;
 }): InstallResult;
+export declare function npmPin(manifest: CliManifest): {
+    pkg: string;
+    version: string;
+} | null;
+export declare function installedCliVersion(manifest: CliManifest): Promise<string | null>;
+export declare function owningNpmPrefix(cmd: string, pkg: string): string | null;
+export type CliUpgradeResult = {
+    name: string;
+    status: 'current';
+    version: string;
+} | {
+    name: string;
+    status: 'upgraded';
+    from: string;
+    to: string;
+} | {
+    name: string;
+    status: 'skipped' | 'failed';
+    reason: string;
+};
+export declare const UPGRADE_TIMEOUT_MS: number;
+export declare function upgradeCliToPin(manifest: CliManifest, opts?: {
+    signal?: AbortSignal;
+    deadlineAt?: number;
+}): Promise<CliUpgradeResult>;
+export declare function upgradeOutdatedClis(opts?: {
+    signal?: AbortSignal;
+    deadlineAt?: number;
+    cwd?: string;
+}): Promise<CliUpgradeResult[]>;
 interface CliStatus {
     manifest: CliManifest;
     installed: boolean;
 }
-/** Convenience: list all manifests + their installed-on-host status. */
 export declare function listCliStatus(cwd?: string): {
     statuses: CliStatus[];
     errors: CliManifestError[];
 };
-/**
- * Async sibling of {@link listCliStatus} that probes every manifest CONCURRENTLY
- * (RUSH-2136). The sync version runs each blocking `spawnSync` check one after
- * another, so a dozen host CLIs whose checks are slow serialize into a
- * multi-minute stall on `agents doctor --json`. This awaits them in parallel, so
- * total wall time is the slowest single check (bounded at 10s), not their sum.
- */
 export declare function listCliStatusAsync(cwd?: string): Promise<{
     statuses: CliStatus[];
     errors: CliManifestError[];

package/dist/lib/cli-resources.js

@@ -1,20 +1,3 @@
-/**
- * CLI tool resources — declarative manifests for command-line binaries the user
- * wants installed on the host (e.g. higgsfield, gh, glab).
- *
- * A CLI resource is a YAML file under <repo>/cli/<name>.yaml. Resolution follows
- * the same project > user > system > extra-repo precedence as other resources,
- * but unlike skills/commands/hooks, CLI resources are NOT copied into per-agent
- * version homes — they install binaries onto the host PATH. The relationship is
- * "Brewfile-style": declare once in ~/.agents/cli/, install on any new machine.
- *
- * Security: every field that becomes a child-process argument is validated
- * against a strict allowlist and dispatched via spawnSync with an argv array.
- * Nothing here ever runs through a shell — manifests can come from project repos
- * or pulled extras, so anything that would let a manifest author smuggle in
- * `;`, `$(...)`, backticks, redirects, or pipe operators is a remote-code-
- * execution sink.
- */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
@@ -25,14 +8,10 @@ import { probeCapture } from './probe.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { execFileShellSpec } from './platform/exec.js';
 import { localBinDir } from './platform/posixpath.js';
-// ─── Validation primitives ───────────────────────────────────────────────────
-/** Token allowed inside `check:` strings — letters, digits, underscore, dot, slash, dash. */
+import { compareVersions } from './agent-spec/primitives.js';
 const SAFE_CHECK_TOKEN = /^[a-zA-Z0-9_./-]+$/;
-/** npm package name with optional scope and optional version/tag. */
 const NPM_PACKAGE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(@[a-zA-Z0-9._-]+)?$/;
-/** Homebrew formula name (and optional tap prefix). */
 const BREW_FORMULA = /^([a-z0-9][a-z0-9_.-]*\/[a-z0-9][a-z0-9_.-]*\/)?[a-z0-9][a-z0-9_.+-]*$/;
-/** Path segment inside a tarball — no leading slash, no `..`, no shell metas. */
 const SAFE_PATH_SEGMENT = /^[a-zA-Z0-9_./-]+$/;
 function assertSafeCheckToken(tok) {
     if (!SAFE_CHECK_TOKEN.test(tok)) {
@@ -66,13 +45,6 @@ function assertSafePathSegment(seg) {
         throw new Error(`extract path is not allowlisted: ${JSON.stringify(seg)}`);
     }
 }
-// ─── Parsing ─────────────────────────────────────────────────────────────────
-/**
- * Parse a `check:` field into a CheckSpec. Accepts either a structured object
- * (`{ kind: 'which'|'version', cmd, args? }`) or a legacy whitespace-separated
- * string. String form is split on whitespace and each token is validated against
- * SAFE_CHECK_TOKEN — manifests cannot smuggle in shell metacharacters.
- */
 function parseCheckSpec(raw, defaultName) {
     if (raw == null) {
         assertSafeCheckToken(defaultName);
@@ -114,21 +86,7 @@ function parseCheckSpec(raw, defaultName) {
     }
     throw new Error('check must be a string or an object with { kind, cmd, args? }');
 }
-/**
- * Parse a single CLI manifest from its YAML contents.
- * Returns a manifest on success; throws on schema violations so callers can
- * decide whether to surface or swallow the error per file.
- */
 export function parseCliManifest(contents, opts) {
-    // Tolerant parse. A manifest may legitimately carry OS-specific strings — a
-    // Windows path like `C:\Users\...` embedded in a double-quoted YAML scalar
-    // trips YAML's escape rules (`\U` is an invalid escape) and makes the strict
-    // `yaml.parse` throw a parser error. That throw must NOT pre-empt the
-    // security validation below: the per-field allowlist checks (unsafe tokens,
-    // non-https URLs, path traversal) are the authoritative gate on a hostile
-    // manifest. parseDocument collects those escape errors instead of throwing
-    // and still recovers the scalar values, so the dangerous content reaches
-    // assertSafeCheckToken / assertNpmPackage and is rejected on its merits.
     const raw = yaml.parseDocument(contents, { strict: false }).toJS();
     if (!raw || typeof raw !== 'object') {
         throw new Error('manifest must be a YAML object');
@@ -214,10 +172,6 @@ export function parseCliManifest(contents, opts) {
         path: opts.path,
     };
 }
-/**
- * Discover all CLI manifests resolvable from the current cwd. Returns valid
- * manifests and any parse errors separately so the CLI can show both.
- */
 export function listCliManifests(cwd) {
     const resolved = listResources('clis', cwd);
     const manifests = [];
@@ -240,7 +194,6 @@ export function listCliManifests(cwd) {
     }
     return { manifests, errors };
 }
-/** Resolve a single CLI manifest by name. Returns null when not declared. */
 export function resolveCliManifest(name, cwd) {
     const resolved = resolveResource('clis', name, cwd);
     if (!resolved)
@@ -254,26 +207,15 @@ export function resolveCliManifest(name, cwd) {
         path: resolved.path,
     });
 }
-// ─── Host detection ──────────────────────────────────────────────────────────
-/**
- * Return true if a command resolves on the current PATH. Uses POSIX `command -v`
- * (or `where` on Windows) via spawn argv (no shell); results are cached for the
- * lifetime of the process.
- */
 const cmdExistsCache = new Map();
 export function hasCommand(cmd) {
     if (cmdExistsCache.has(cmd))
         return cmdExistsCache.get(cmd);
     let ok;
     if (process.platform === 'win32') {
-        // `sh` only exists when Git Bash is installed; `where` is the native PATH
-        // probe (resolves .exe/.cmd/.bat via PATHEXT). Argv keeps `cmd` uninterpolated.
         ok = spawnSync('where', [cmd], { stdio: 'ignore' }).status === 0;
     }
     else {
-        // `command` is a shell builtin on most POSIX shells; invoking `sh -c 'command -v X'`
-        // with X as an *argument* (not interpolated) is the safe path. `cmd` may be passed
-        // by callers that haven't validated it, so we route via argv to neutralize metas.
         ok = spawnSync('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', '_', cmd], {
             stdio: 'ignore',
         }).status === 0;
@@ -281,10 +223,6 @@ export function hasCommand(cmd) {
     cmdExistsCache.set(cmd, ok);
     return ok;
 }
-/**
- * Run the manifest's check. Dispatches on CheckSpec.kind — never invokes a
- * shell, never interpolates strings into a command line.
- */
 export function isCliInstalled(manifest) {
     const c = manifest.check;
     if (c.kind === 'which') {
@@ -294,11 +232,6 @@ export function isCliInstalled(manifest) {
     const result = spawnSync(c.cmd, c.args, { stdio: 'ignore', timeout: 10_000 });
     if (result.status === 0)
         return true;
-    // On Windows the PATH entry point is often a `.cmd`/`.bat` shim (npm installs,
-    // script installers), which Node refuses to spawn without a shell (ENOENT /
-    // EINVAL). A failed *spawn* — not a failed run — gets one retry through the
-    // shell, as a single pre-composed line (DEP0190-safe). Check tokens are
-    // SAFE_CHECK_TOKEN-validated at parse time, so the line cannot inject.
     if (process.platform === 'win32' && result.error) {
         const line = composeWin32CommandLine(c.cmd, c.args);
         const retry = spawnSync(line, { stdio: 'ignore', timeout: 10_000, shell: true });
@@ -306,29 +239,13 @@ export function isCliInstalled(manifest) {
     }
     return false;
 }
-/**
- * Async, non-blocking sibling of {@link isCliInstalled}. Same dispatch and
- * Windows-shim retry, but over `execFile` so many manifests can be checked
- * concurrently — the fix for RUSH-2136, where `agents doctor --json` ran a dozen+
- * blocking 10s-timeout `spawnSync` checks SERIALLY (measured ~136s on an idle
- * box). `execFile`'s `timeout` still SIGKILLs a wedged check, so a single
- * hanging probe can't stall the whole set past 10s.
- */
 export function isCliInstalledAsync(manifest) {
     const c = manifest.check;
     if (c.kind === 'which') {
         cmdExistsCache.delete(c.cmd);
         return Promise.resolve(hasCommand(c.cmd));
     }
-    // probeCapture, not bare execFile: a checked CLI can fork children of its
-    // own (copilot's platform-binary downloader), and settling without reaping
-    // the probe's process group would orphan them mid-write (RUSH-3028).
     return probeCapture(c.cmd, c.args, 10_000).then(() => true, (err) => {
-        // A spawn failure (as opposed to a non-zero exit) surfaces as a string
-        // errno code (ENOENT/EINVAL) on the rejection; a non-zero exit or
-        // timeout carries no errno. On Windows a `.cmd`/`.bat` shim spawn-fails
-        // without a shell — retry once through the shell, exactly as the sync
-        // path does.
         const spawnFailed = typeof err.code === 'string';
         if (process.platform === 'win32' && spawnFailed) {
             const line = composeWin32CommandLine(c.cmd, c.args);
@@ -339,11 +256,6 @@ export function isCliInstalledAsync(manifest) {
         return false;
     });
 }
-// ─── Method selection ────────────────────────────────────────────────────────
-/**
- * Pick the first install method whose required host tool is available.
- * Returns null when none of the declared methods can run on this host.
- */
 export function selectInstallMethod(manifest) {
     for (const method of manifest.install) {
         if ('npm' in method && hasCommand('npm'))
@@ -360,11 +272,9 @@ export function selectInstallMethod(manifest) {
     }
     return null;
 }
-/** Render a CheckSpec back to a human-readable command string (display only). */
 export function describeCheck(check) {
     return check.kind === 'which' ? check.cmd : `${check.cmd} ${check.args.join(' ')}`.trim();
 }
-/** Short description of a method for display. */
 export function describeMethod(method) {
     if ('npm' in method)
         return `npm install -g ${method.npm}`;
@@ -376,9 +286,7 @@ export function describeMethod(method) {
     const spec = method.binary[key];
     return spec ? `download ${spec.url}` : 'binary download';
 }
-/** Env var that overrides where `binary` installs write their downloaded file(s). */
 const BIN_DIR_ENV = 'AGENTS_CLI_BIN_DIR';
-/** Historical default install dir — kept only as a last-resort fallback. */
 const LEGACY_BIN_DIR = '/usr/local/bin';
 function isWritableDir(dir, opts) {
     try {
@@ -391,23 +299,6 @@ function isWritableDir(dir, opts) {
         return false;
     }
 }
-/**
- * Resolve the directory a `binary` install method downloads/extracts into.
- *
- * `/usr/local/bin` used to be hardcoded here, which fails on Apple Silicon
- * Macs where that directory is root-owned and not user-writable (Homebrew
- * moved on to /opt/homebrew but left /usr/local/bin behind). Resolution
- * order:
- *  1. `AGENTS_CLI_BIN_DIR` — explicit override, used as-is when set.
- *  2. `~/.local/bin` — the XDG user-bin dir already used for shims (see
- *     posixpath.ts / shims.ts); created with mkdir -p if missing.
- *  3. `/usr/local/bin` — last resort, for hosts where it's still writable.
- *     When it isn't either, throw an actionable error naming the env var and
- *     ~/.local/bin instead of letting curl/tar fail with a bare EACCES.
- *
- * Called once per install/dry-run so the same directory is used everywhere
- * that method is described or executed.
- */
 export function resolveBinDir() {
     const override = process.env[BIN_DIR_ENV];
     if (override && override.trim())
@@ -422,11 +313,6 @@ export function resolveBinDir() {
         `  export ${BIN_DIR_ENV}="$HOME/.local/bin"\n` +
         `then re-run the install.`);
 }
-/**
- * Display-only rendering of how a method would be run, for `--dry-run` and
- * status output. Not used by installCli — execution goes through runInstallMethod
- * which dispatches to spawnSync with argv arrays.
- */
 export function buildInstallCommand(method) {
     if ('npm' in method)
         return `npm install -g ${method.npm}`;
@@ -446,20 +332,11 @@ export function buildInstallCommand(method) {
         ? `curl -fsSL ${spec.url} -o /tmp/agents-cli-bin.tgz && tar -xzf /tmp/agents-cli-bin.tgz -C ${binDir} ${spec.extract}`
         : `curl -fsSL ${spec.url} -o ${path.join(binDir, 'agents-cli-downloaded')}`;
 }
-/**
- * Execute an install method via spawnSync with argv arrays. Each branch
- * re-validates the relevant field — defense in depth, since callers may
- * construct InstallMethod values without going through parseCliManifest
- * (tests, future programmatic use).
- *
- * For `script`, the download is staged to a temp file and then exec'd as
- * `sh <file>` so we never need a shell pipe (`curl | sh`).
- */
-function runInstallMethod(method) {
+function runInstallMethod(method, stdio) {
     if ('npm' in method) {
         assertNpmPackage(method.npm);
         const invocation = execFileShellSpec('npm', ['install', '-g', method.npm]);
-        const r = spawnSync(invocation.command, invocation.args, { stdio: 'inherit', shell: invocation.shell });
+        const r = spawnSync(invocation.command, invocation.args, { stdio, shell: invocation.shell });
         if (r.status !== 0) {
             throw new Error(`npm install -g ${method.npm} exited with status ${r.status ?? 'unknown'}`);
         }
@@ -467,7 +344,7 @@ function runInstallMethod(method) {
     }
     if ('brew' in method) {
         assertBrewFormula(method.brew);
-        const r = spawnSync('brew', ['install', method.brew], { stdio: 'inherit' });
+        const r = spawnSync('brew', ['install', method.brew], { stdio });
         if (r.status !== 0) {
             throw new Error(`brew install ${method.brew} exited with status ${r.status ?? 'unknown'}`);
         }
@@ -479,10 +356,10 @@ function runInstallMethod(method) {
         try {
             let dl;
             if (hasCommand('curl')) {
-                dl = spawnSync('curl', ['-fsSL', method.script, '-o', tmp], { stdio: 'inherit' });
+                dl = spawnSync('curl', ['-fsSL', method.script, '-o', tmp], { stdio });
             }
             else if (hasCommand('wget')) {
-                dl = spawnSync('wget', ['-q', '-O', tmp, method.script], { stdio: 'inherit' });
+                dl = spawnSync('wget', ['-q', '-O', tmp, method.script], { stdio });
             }
             else {
                 throw new Error('neither curl nor wget is available on PATH');
@@ -490,7 +367,7 @@ function runInstallMethod(method) {
             if (dl.status !== 0) {
                 throw new Error(`download of install script failed (status ${dl.status ?? 'unknown'})`);
             }
-            const r = spawnSync('sh', [tmp], { stdio: 'inherit' });
+            const r = spawnSync('sh', [tmp], { stdio });
             if (r.status !== 0) {
                 throw new Error(`install script exited with status ${r.status ?? 'unknown'}`);
             }
@@ -499,7 +376,7 @@ function runInstallMethod(method) {
             try {
                 fs.unlinkSync(tmp);
             }
-            catch { /* best effort */ }
+            catch { }
         }
         return;
     }
@@ -514,12 +391,12 @@ function runInstallMethod(method) {
             assertSafePathSegment(spec.extract);
             const tmp = path.join(os.tmpdir(), `agents-cli-bin-${process.pid}-${Date.now()}.tgz`);
             try {
-                const dl = spawnSync('curl', ['-fsSL', spec.url, '-o', tmp], { stdio: 'inherit' });
+                const dl = spawnSync('curl', ['-fsSL', spec.url, '-o', tmp], { stdio });
                 if (dl.status !== 0) {
                     throw new Error(`binary download failed (status ${dl.status ?? 'unknown'})`);
                 }
                 const x = spawnSync('tar', ['-xzf', tmp, '-C', binDir, spec.extract], {
-                    stdio: 'inherit',
+                    stdio,
                 });
                 if (x.status !== 0) {
                     throw new Error(`tar extract failed (status ${x.status ?? 'unknown'})`);
@@ -529,11 +406,11 @@ function runInstallMethod(method) {
                 try {
                     fs.unlinkSync(tmp);
                 }
-                catch { /* best effort */ }
+                catch { }
             }
         }
         else {
-            const r = spawnSync('curl', ['-fsSL', spec.url, '-o', path.join(binDir, 'agents-cli-downloaded')], { stdio: 'inherit' });
+            const r = spawnSync('curl', ['-fsSL', spec.url, '-o', path.join(binDir, 'agents-cli-downloaded')], { stdio });
             if (r.status !== 0) {
                 throw new Error(`binary download failed (status ${r.status ?? 'unknown'})`);
             }
@@ -541,11 +418,6 @@ function runInstallMethod(method) {
         return;
     }
 }
-/**
- * Install a single CLI by running its first compatible method. Streams the
- * underlying command's output to the parent terminal so users see brew/npm
- * progress live. Verifies success by re-running `check`.
- */
 export function installCli(manifest, opts = {}) {
     const method = selectInstallMethod(manifest);
     if (!method) {
@@ -560,7 +432,7 @@ export function installCli(manifest, opts = {}) {
         return { manifest, method, installed: false, output: `[dry-run] would run: ${describeMethod(method)}` };
     }
     try {
-        runInstallMethod(method);
+        runInstallMethod(method, opts.logToStderr ? ['inherit', 2, 'inherit'] : 'inherit');
     }
     catch (err) {
         return {
@@ -570,14 +442,113 @@ export function installCli(manifest, opts = {}) {
             error: `install command failed: ${err.message}`,
         };
     }
-    // Re-check; many installers exit 0 but leave the binary off PATH for the
-    // current shell (e.g. brew on a fresh install). Trust `check`, not the
-    // installer's exit code.
     cmdExistsCache.delete(manifest.name);
     const installed = isCliInstalled(manifest);
     return { manifest, method, installed };
 }
-/** Convenience: list all manifests + their installed-on-host status. */
+const EXACT_SEMVER = /^\d+\.\d+\.\d+$/;
+const FIRST_SEMVER = /\d+\.\d+\.\d+/;
+export function npmPin(manifest) {
+    const method = manifest.install.find((m) => 'npm' in m);
+    if (!method)
+        return null;
+    const at = method.npm.lastIndexOf('@');
+    if (at <= 0)
+        return null;
+    const version = method.npm.slice(at + 1);
+    return EXACT_SEMVER.test(version) ? { pkg: method.npm.slice(0, at), version } : null;
+}
+export async function installedCliVersion(manifest) {
+    const c = manifest.check;
+    if (c.kind !== 'version')
+        return null;
+    try {
+        const { stdout } = await probeCapture(c.cmd, c.args, 10_000);
+        return FIRST_SEMVER.exec(stdout)?.[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveOnPath(cmd) {
+    for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, cmd);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return fs.realpathSync(candidate);
+        }
+        catch {
+        }
+    }
+    return null;
+}
+export function owningNpmPrefix(cmd, pkg) {
+    const real = resolveOnPath(cmd);
+    if (!real)
+        return null;
+    const marker = `${path.sep}lib${path.sep}node_modules${path.sep}${pkg.split('/').join(path.sep)}${path.sep}`;
+    const idx = real.indexOf(marker);
+    return idx > 0 ? real.slice(0, idx) : null;
+}
+export const UPGRADE_TIMEOUT_MS = 5 * 60_000;
+function runNpmInstall(prefix, spec, signal) {
+    return new Promise((resolve, reject) => {
+        execFile('npm', ['install', '-g', '--prefix', prefix, spec], { timeout: UPGRADE_TIMEOUT_MS, signal, maxBuffer: 16 * 1024 * 1024 }, (err, _stdout, stderr) => {
+            if (err)
+                reject(new Error(`npm install -g --prefix ${prefix} ${spec} failed: ${String(stderr).trim().split('\n').pop() ?? err.message}`));
+            else
+                resolve();
+        });
+    });
+}
+export async function upgradeCliToPin(manifest, opts = {}) {
+    const { signal, deadlineAt } = opts;
+    const name = manifest.name;
+    const pin = npmPin(manifest);
+    if (!pin)
+        return { name, status: 'skipped', reason: 'no exact npm pin' };
+    if (manifest.check.kind !== 'version')
+        return { name, status: 'skipped', reason: 'check reports no version' };
+    const from = await installedCliVersion(manifest);
+    if (!from)
+        return { name, status: 'skipped', reason: 'not installed or reports no version' };
+    if (compareVersions(from, pin.version) >= 0)
+        return { name, status: 'current', version: from };
+    if (process.platform === 'win32')
+        return { name, status: 'skipped', reason: `outdated (${from} < ${pin.version}); unattended upgrade is POSIX-only` };
+    const prefix = owningNpmPrefix(manifest.check.cmd, pin.pkg);
+    if (!prefix) {
+        return { name, status: 'skipped', reason: `outdated (${from} < ${pin.version}) but ${manifest.check.cmd} on PATH is not an npm install of ${pin.pkg}` };
+    }
+    if (deadlineAt !== undefined && Date.now() + UPGRADE_TIMEOUT_MS > deadlineAt) {
+        return { name, status: 'skipped', reason: `outdated (${from} < ${pin.version}); deferred, not enough time left in this tick` };
+    }
+    try {
+        await runNpmInstall(prefix, `${pin.pkg}@${pin.version}`, signal);
+    }
+    catch (err) {
+        return { name, status: 'failed', reason: err.message };
+    }
+    const to = await installedCliVersion(manifest);
+    if (to !== pin.version) {
+        return { name, status: 'failed', reason: `installed ${pin.pkg}@${pin.version} into ${prefix} but ${manifest.check.cmd} still reports ${to ?? 'no version'}` };
+    }
+    return { name, status: 'upgraded', from, to };
+}
+export async function upgradeOutdatedClis(opts = {}) {
+    const { manifests } = listCliManifests(opts.cwd);
+    const results = [];
+    for (const manifest of manifests) {
+        if (opts.signal?.aborted)
+            break;
+        if (manifest.source === 'project')
+            continue;
+        results.push(await upgradeCliToPin(manifest, opts));
+    }
+    return results;
+}
 export function listCliStatus(cwd) {
     const { manifests, errors } = listCliManifests(cwd);
     const statuses = manifests.map((manifest) => ({
@@ -586,13 +557,6 @@ export function listCliStatus(cwd) {
     }));
     return { statuses, errors };
 }
-/**
- * Async sibling of {@link listCliStatus} that probes every manifest CONCURRENTLY
- * (RUSH-2136). The sync version runs each blocking `spawnSync` check one after
- * another, so a dozen host CLIs whose checks are slow serialize into a
- * multi-minute stall on `agents doctor --json`. This awaits them in parallel, so
- * total wall time is the slowest single check (bounded at 10s), not their sum.
- */
 export async function listCliStatusAsync(cwd) {
     const { manifests, errors } = listCliManifests(cwd);
     const statuses = await Promise.all(manifests.map(async (manifest) => ({