@platless/axom-cli 0.1.0

package/dist/workstation/acp/draftSubagents.js

@@ -0,0 +1,38 @@
+/** Client capability key (canonical, draft #1992): `clientCapabilities.subagents = {}`. */
+export const DRAFT_SUBAGENTS_CAPABILITY = 'subagents';
+/**
+ * The JetBrains AIR extension envelope, which is how `asyncTasks` is negotiated at all — there is
+ * no canonical field for it, and the canonical `subagents` field can be stripped by a released SDK
+ * that has never heard of it, so the AIR list carries a fallback for that one too.
+ * Keys and version verbatim from `claude-agent-acp/src/air-extension.ts`.
+ */
+export const AIR_META_KEY = 'jetbrains';
+export const AIR_EXTENSION_VERSION = 1;
+export const AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY = 'nativeSubagentSessions';
+export const AIR_ASYNC_TASKS_CAPABILITY = 'asyncTasks';
+/** The `_meta.jetbrains` payload advertising what this client understands. */
+export function airCapabilityMeta(...capabilities) {
+    return { [AIR_META_KEY]: { air: { version: AIR_EXTENSION_VERSION, capabilities } } };
+}
+/** Every draft variant name, for tests and for the mapper's own documentation. */
+export const DRAFT_SESSION_UPDATE_NAMES = [
+    'subagent_spawned',
+    'subagent_state_update',
+    'async_task_spawned',
+    'async_task_progress',
+    'async_task_state_update',
+];
+/**
+ * The one cast this file exists to contain, mirroring upstream's `asSdkSessionNotification`.
+ *
+ * `ClientCapabilities` is a closed published type with no `subagents` member, so declaring the
+ * canonical draft field makes the object structurally unassignable — and TypeScript answers that by
+ * dropping the `initialize` overload, which silently turns the response into `unknown`. That is a
+ * worse failure than the cast: it un-types every field of the handshake reply.
+ *
+ * Deliberately narrow: it casts capabilities only, at the single call site that builds them. When
+ * #1992 lands in the SDK this function is deleted and the call site keeps its shape.
+ */
+export function asSdkClientCapabilities(capabilities) {
+    return capabilities;
+}

package/dist/workstation/acp/installErrors.js

@@ -0,0 +1,89 @@
+/**
+ * Turns what a failed adapter install/update actually learned into a short, actionable sentence —
+ * the toast a person reads — instead of Node's own `Command failed: npx --yes --package=… -- …`
+ * dump landing there verbatim. That is not a hypothetical: it is exactly what a real `Update` click
+ * produced for a registry entry pinned to an unpublished npm version, with npm's multi-line
+ * `notarget` stanza and a path to a debug log nobody asked to read.
+ *
+ * Nothing here deletes that raw text: {@link logInstallFailureDetail} writes it to the daemon's own
+ * log, untruncated, at every call site in `acpAgents.ts` that turns a failure into one of this
+ * module's short sentences — npx (both the ordinary case and the pinned-fallback-also-failed case),
+ * uvx, and binary (whose `error` already carries the extraction step's own detail, see
+ * `binaryInstall.ts`). None of the three install paths' `console.*` calls existed before this module
+ * did; they were added alongside it specifically so demoting the raw detail out of the UI would not
+ * also delete the only copy of it. This module only decides what the *headline* says; the detail a
+ * person would need to actually debug the failure is logged, in full, right where that headline is
+ * built.
+ *
+ * Three shapes, matching the three things a failed install can mean (see `acpClient.ts`'s
+ * `isMissingPackageVersion`/`stderrShowsMissingPackageVersion` — the one predicate every ETARGET
+ * check in this codebase reuses rather than re-deriving):
+ *
+ * 1. An ordinary failure with no ETARGET in sight: a network hiccup, a full disk, a missing archive
+ *    tool, a timeout. {@link friendlyOrdinaryInstallError}.
+ * 2. The registry pins a version that is not published upstream, and the unpinned retry
+ *    (`unpinnedFallbackFor`, `registry/launch.ts`) that tries to work around it fails too.
+ *    {@link friendlyPinnedVersionUnavailableAndFallbackFailed}.
+ * 3. The same missing pin, but the unpinned retry succeeds — not a failure at all, so it produces no
+ *    message here. It produces a {@link PinnedVersionUnavailable} fact instead, which
+ *    `PersonalWorkstationService` (`axom-engine`) persists so a settings card can explain itself
+ *    after a reload instead of offering an `Update` that can never converge (the version now
+ *    installed can never equal the registry's own unreachable pin).
+ */
+/**
+ * Strips a leading `Command failed: <argv>` line — what Node's `execFile` puts first in
+ * `error.message`, and the exact preamble that made the reported toast unreadable — keeping only
+ * what actually went wrong. A no-op on text that never had one, so this is safe to run on every raw
+ * detail this module sees, not just npx's.
+ */
+function withoutCommandPreamble(text) {
+    const lines = text.split('\n');
+    if (/^Command failed:/i.test(lines[0] ?? ''))
+        lines.shift();
+    const rest = lines.map((line) => line.trim()).filter(Boolean).join(' ');
+    return rest || text.trim();
+}
+/** Bounded so a person reading a toast is not handed npm's full stanza — the daemon log still has it. */
+const SHORT_DETAIL_MAX_CHARS = 300;
+function shortDetail(rawDetail) {
+    const cleaned = withoutCommandPreamble(rawDetail);
+    return cleaned.length > SHORT_DETAIL_MAX_CHARS ? `${cleaned.slice(0, SHORT_DETAIL_MAX_CHARS)}…` : cleaned;
+}
+/**
+ * Writes the full, untruncated failure `rawDetail` to the daemon's own log — never over the wire,
+ * never shown in the UI — right before it is boiled down into one of this module's short sentences.
+ * Call this at every site that calls {@link friendlyOrdinaryInstallError} or
+ * {@link friendlyPinnedVersionUnavailableAndFallbackFailed} for an actual failure (not case 3's
+ * quiet success), so a person with shell access to the workstation can still diagnose a cause none
+ * of the three classified shapes covers — a month from now, with no memory of tonight.
+ *
+ * Written in the same voice as the `console.warn` pair around the ETARGET fallback in
+ * `acpAgents.ts` (`[acp] …`), so the two read as one log, not two authors: names the agent, which
+ * distribution and version spec the daemon was trying to fetch, and then the raw detail itself,
+ * verbatim — not bounded by {@link SHORT_DETAIL_MAX_CHARS}, which exists for the toast, not the log.
+ */
+export function logInstallFailureDetail(agentId, distribution, versionSpec, rawDetail) {
+    console.warn(`[acp] install failed for agent '${agentId}' via ${distribution} '${versionSpec}': ${rawDetail}`);
+}
+/**
+ * The reassurance clause every failure message ends with, when — and only when — there is a fact to
+ * back it up: [existingVersion] is `undefined` unless this call actually found a version of the
+ * adapter already on disk, read fresh at the moment the attempt failed. Never invents comfort it
+ * cannot back: an agent that has never been installed gets no claim that "the version you have"
+ * still works, because there isn't one.
+ */
+function reassurance(existingVersion) {
+    return existingVersion
+        ? ` The version already installed (${existingVersion}) was not touched and still works.`
+        : '';
+}
+/** Case 1: an ordinary failure, no ETARGET involved — network, disk, a missing archive tool, a timeout. */
+export function friendlyOrdinaryInstallError(agentId, rawDetail, existingVersion) {
+    return (`Could not fetch the adapter for '${agentId}': ${shortDetail(rawDetail)}. Try again in a moment, ` +
+        `or check the daemon log if it keeps failing.${reassurance(existingVersion)}`);
+}
+/** Case 2: the registry's pin is missing upstream, and the unpinned retry meant to work around it failed too. */
+export function friendlyPinnedVersionUnavailableAndFallbackFailed(agentId, pinned, fallbackDetail, existingVersion) {
+    return (`The registry pins '${agentId}' to version ${pinned}, which is not published. Installing the ` +
+        `latest available version instead failed too: ${shortDetail(fallbackDetail)}.${reassurance(existingVersion)}`);
+}

package/dist/workstation/acp/installProbe.js

@@ -0,0 +1,363 @@
+/**
+ * Everything this daemon knows about what is **actually on this machine** — the half of the
+ * external-agent story the ACP registry cannot tell, because the registry describes packages and
+ * this describes a filesystem.
+ *
+ * ## The rule these functions exist to keep
+ *
+ * The settings page previously reported "Ready to launch" for every agent whose registry entry had
+ * an `npx` or `uvx` block. That is a property of the *entry*, identical on every machine on earth,
+ * and it was rendered as a claim about the reader's laptop — so agents nobody had installed read as
+ * ready, and Antigravity, which was installed, read as unusable. Nothing here may repeat that:
+ * every function below answers by looking at the disk, and returns "no"/"unknown" rather than
+ * inferring from metadata.
+ *
+ * ## Nothing here starts an agent
+ *
+ * {@link findOnPath} is `which`, not `command --version`: presence on `PATH` is the whole question,
+ * and the roster is built for all 39 registry agents at once, so a probe that executed anything
+ * would fan out 39 processes on every scan. {@link readNpxCache} is two `readdir`/`readFile`
+ * passes over npm's own cache directory. The one function here that does spawn something,
+ * {@link installNpxPackage}, runs `node -e ""` under `npm exec --package=…` — it downloads and
+ * unpacks the adapter and deliberately never executes it.
+ */
+import { execFile } from 'node:child_process';
+import { accessSync, constants, readdirSync, readFileSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import semver from 'semver';
+export function probeEnvironment(env = process.env) {
+    return {
+        path: env.PATH,
+        pathExt: env.PATHEXT,
+        platform: process.platform,
+        home: os.homedir(),
+        npmCache: env.npm_config_cache,
+        localAppData: env.LOCALAPPDATA,
+    };
+}
+const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+/**
+ * `which`, with no subprocess: the first entry of `PATH` that holds an executable file called
+ * `command`, or `undefined`.
+ *
+ * **Deliberately does not run the program.** "Is it installed" is answered by the file being there;
+ * `--version` would answer a different, more expensive question, and asking it once per registry
+ * agent would start 39 programs behind a settings page that only wanted a list.
+ *
+ * `statSync` rather than `lstatSync` on purpose — vendor installers routinely drop a symlink into
+ * `~/.local/bin`, and a probe that refused to follow it would report a working CLI as missing.
+ */
+export function findOnPath(command, env = probeEnvironment()) {
+    if (!command)
+        return undefined;
+    const platform = env.platform ?? process.platform;
+    const delimiter = platform === 'win32' ? ';' : ':';
+    const extensions = platform === 'win32'
+        ? (env.pathExt ?? DEFAULT_PATHEXT).split(';').filter(Boolean)
+        : [''];
+    for (const directory of (env.path ?? '').split(delimiter)) {
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = path.join(directory, command + extension);
+            try {
+                if (!statSync(candidate).isFile())
+                    continue;
+                // X_OK is meaningless on win32 (node reports every readable file as executable), so the
+                // extension list above is what stands in for it there.
+                if (platform !== 'win32')
+                    accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // Not there, not a file, or not ours to run. Keep looking; a PATH entry that does not
+                // exist at all is entirely normal.
+            }
+        }
+    }
+    return undefined;
+}
+/** npm's cache directory, by npm's own rules. `_npx/` lives inside it. */
+export function npmCacheDir(env = probeEnvironment()) {
+    if (env.npmCache)
+        return env.npmCache;
+    const platform = env.platform ?? process.platform;
+    const home = env.home ?? os.homedir();
+    return platform === 'win32' ? path.join(env.localAppData ?? home, 'npm-cache') : path.join(home, '.npm');
+}
+/**
+ * The package name inside an npm specifier: `@scope/name@1.2.3` → `@scope/name`, `name@1.2.3` →
+ * `name`. Returns the input unchanged when it carries no version.
+ */
+export function npmPackageName(spec) {
+    const at = spec.lastIndexOf('@');
+    return at > 0 ? spec.slice(0, at) : spec;
+}
+/**
+ * The version half of an npm specifier: `@scope/name@1.2.3` → `1.2.3`, `name@1.2.3` → `1.2.3`.
+ * `undefined` when the specifier carries no version, which the ACP registry never actually does —
+ * see `registry/launch.ts`'s "pinned specifier, never bare" — but this stays honest for whatever
+ * calls it next.
+ */
+export function npmPackageVersion(spec) {
+    const name = npmPackageName(spec);
+    return name === spec ? undefined : spec.slice(name.length + 1);
+}
+/**
+ * Every npm-distributed package `npx` has actually unpacked into this machine's npm cache, indexed
+ * by package name, read once so a 39-agent roster costs one directory scan rather than 39.
+ *
+ * ## Why this reads `node_modules/`, not a manifest field
+ *
+ * The previous version of this function trusted `<npm cache>/_npx/<hash>/package.json`'s
+ * `_npx.packages` array — the specifier npm was asked to install, written verbatim by npm itself.
+ * That held on the machine it was written and verified on, and nowhere else: **measured** on a
+ * second real machine (four npm majors older), the same manifest carries no `_npx` key at all, and
+ * the specifier that *is* there (in `dependencies`) has been rewritten into a semver range
+ * (`^0.70.0` for a registry entry that asked for exactly `0.70.0`). Both of those are choices a
+ * manifest writer made, not properties of the download, so a check built on either one is a bet on
+ * one npm version's choices rather than on what actually happened on disk.
+ *
+ * What every npm version agrees on, because it is what "installed" *means*, is that a package that
+ * was fetched has its own `package.json` sitting under `node_modules/<name>/` with that package's
+ * own `name` and `version` — npm did not write that file, the published package did, years before
+ * npm ever downloaded it. Reading that instead means nothing here depends on which fields one
+ * particular npm chooses to leave in the manifest one level up, or on reproducing npm's own cache
+ * hash: this still just walks `_npx/*` and looks inside.
+ *
+ * ## Why the directory alone is not enough
+ *
+ * An install that was interrupted (a killed `npm`, a dropped link) can leave a cache entry behind
+ * with `node_modules` missing or partial, and reporting that as installed would be precisely the
+ * kind of unchecked claim this module exists to prevent. So an entry counts only when the package's
+ * own `package.json` is present and its `name` matches the directory it was found under — a stray
+ * or half-written file does not.
+ */
+export function readNpxCache(env = probeEnvironment()) {
+    const npxDir = path.join(npmCacheDir(env), '_npx');
+    const index = new Map();
+    let entries;
+    try {
+        entries = readdirSync(npxDir, { withFileTypes: true });
+    }
+    catch {
+        // No `_npx` at all — a machine that has never run npx. Nothing is cached, which is an answer.
+        return index;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const nodeModules = path.join(npxDir, entry.name, 'node_modules');
+        let packageDirs;
+        try {
+            packageDirs = readdirSync(nodeModules, { withFileTypes: true });
+        }
+        catch {
+            // A manifest with nothing unpacked behind it — an interrupted install, or (on some npm
+            // versions) no manifest at all. Either way, there is nothing here to report as installed.
+            continue;
+        }
+        for (const dir of packageDirs) {
+            if (!dir.isDirectory())
+                continue;
+            if (dir.name.startsWith('@')) {
+                // A scope directory: the real package is one level further down.
+                let scopedDirs;
+                try {
+                    scopedDirs = readdirSync(path.join(nodeModules, dir.name), { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const scoped of scopedDirs) {
+                    if (!scoped.isDirectory())
+                        continue;
+                    recordNpxPackage(path.join(nodeModules, dir.name, scoped.name), `${dir.name}/${scoped.name}`, index);
+                }
+                continue;
+            }
+            recordNpxPackage(path.join(nodeModules, dir.name), dir.name, index);
+        }
+    }
+    return index;
+}
+/** Reads one `node_modules/<name>/package.json` and records it, only if it is what it claims to be. */
+function recordNpxPackage(dir, expectedName, index) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const name = manifest?.name;
+    const version = manifest?.version;
+    if (name !== expectedName || typeof version !== 'string')
+        return;
+    const list = index.get(name) ?? [];
+    list.push({ name, version });
+    index.set(name, list);
+}
+/**
+ * The version of one registry specifier's package (`@scope/name@1.2.3` → the `name` half) that is
+ * **actually cached** on disk, per {@link readNpxCache} — never whether it matches the specifier's
+ * pinned version.
+ *
+ * Deleted `npxCacheSatisfies` (the boolean this replaces) for a concrete failure it caused: the ACP
+ * registry pins an exact adapter version, and the moment upstream published a patch — the registry
+ * moving from `claude-agent-acp@0.74.0` to `@0.75.0` while the machine still had 0.74.0 unpacked —
+ * an agent that was configured, working and verified got rendered as never having been checked.
+ * The version is the fact; "is an update available" is a conclusion drawn by comparing it against
+ * the registry's pin, and those are two different questions that must not be collapsed into one
+ * boolean.
+ *
+ * npm's npx cache routinely holds several versions of the same package side by side (see
+ * {@link readNpxCache}'s doc), so the selection rule is: report the registry's pinned version when
+ * it is among those cached (so an exact match never gets shadowed by a newer sibling); otherwise
+ * report the greatest by semver; versions that do not parse as semver sort after every valid one,
+ * compared as strings.
+ */
+export function npxCacheVersion(spec, cache) {
+    const found = cache.get(npmPackageName(spec));
+    if (!found || found.length === 0)
+        return undefined;
+    return pickInstalledVersion(found.map((p) => p.version), npmPackageVersion(spec));
+}
+/**
+ * The version-selection rule shared by every install surface that can find more than one version
+ * of the same thing sitting on disk at once — {@link npxCacheVersion} here, and `binaryInstall.ts`'s
+ * `installedBinaryVersion` (a binary adapter's layout, `<root>/<agent>/<version>/`, is deliberately
+ * built to let several versions coexist the same way npm's `_npx` cache does). Extracted rather than
+ * reimplemented a second time, so both surfaces answer "which one do I mean" identically: the
+ * `pinned` version when it is among `versions` (an exact match must never be shadowed by a newer
+ * sibling); otherwise the greatest by semver; versions that do not parse as semver sort after every
+ * valid one, compared as plain strings.
+ */
+export function pickInstalledVersion(versions, pinned) {
+    if (versions.length === 0)
+        return undefined;
+    if (pinned && versions.includes(pinned))
+        return pinned;
+    return [...versions].sort((a, b) => {
+        const av = semver.valid(a);
+        const bv = semver.valid(b);
+        if (av && bv)
+            return semver.rcompare(av, bv);
+        if (av)
+            return -1;
+        if (bv)
+            return 1;
+        return b.localeCompare(a);
+    })[0];
+}
+/**
+ * Wall-clock budget for one adapter download.
+ *
+ * ## It is no longer the client's HTTP ceiling
+ *
+ * This used to be 20s, justified by the settings page's 30s `AXOM_REQUEST_TIMEOUT_MS`: a longer
+ * budget would have meant telling the reader the request failed while this process kept working
+ * invisibly. That premise is gone. Install, update and try-run are asynchronous tasks now
+ * (design §6.4) — the REST call returns a task id immediately and the page polls it — so nothing is
+ * waiting on an HTTP round trip and the only thing 20s still bounded was the *work*.
+ *
+ * And it bounded it far too tightly. A cold `claude-acp` install unpacks
+ * `@anthropic-ai/claude-agent-sdk`, measured at 243 MB (design §2.3); on any ordinary connection
+ * that does not finish in 20 seconds, so the install died every time — now behind a spinner, which
+ * is worse than before, not better. The budget's job is to bound a download that will *never*
+ * finish (a hung mirror, a proxy black hole), not one that is merely large.
+ *
+ * ## What still bounds it from above
+ *
+ * `AgentChannelSession.AGENT_CHANNEL_INSTALL_TIMEOUT_MS` on the server, which must stay above the
+ * worst case this daemon can spend: {@link runDependencyInstall}'s
+ * {@link DEPENDENCY_INSTALL_TIMEOUT_MS} followed by one adapter fetch at this budget — `pi-acp` is
+ * exactly that pair. Raising either constant means raising that one too, and its own comment says
+ * the same thing back.
+ *
+ * A download that does run out comes back as a failure that says so, and trying again resumes from
+ * npm's own partial cache rather than starting over.
+ */
+export const ADAPTER_INSTALL_TIMEOUT_MS = 300_000;
+/**
+ * Wall-clock budget for one {@link runDependencyInstall} — a curated `dependency.install` argv, in
+ * practice an `npm install -g` of a vendor CLI.
+ *
+ * Its own constant rather than {@link ADAPTER_INSTALL_TIMEOUT_MS} reused, because the two are
+ * consecutive halves of a single `AcpAgents.install` for a catalog agent with a dependency and the
+ * server's tunnel budget has to be able to add them up. Same size today; that is a fact about the
+ * work, not a reason to collapse them into one name.
+ */
+export const DEPENDENCY_INSTALL_TIMEOUT_MS = 300_000;
+/**
+ * Download and unpack one npx-distributed adapter into npm's cache **without running it**.
+ *
+ * `npx --yes --package=<spec> -- <node> -e ""` installs `<spec>` exactly as the launch spec's
+ * `npx --yes <spec>` would — same cache directory, same unpacked package underneath it, which is
+ * why {@link readNpxCache} can see it afterwards (measured, not assumed) — and then runs *node*,
+ * not the adapter. Running the adapter is what the first real launch does; this is only meant to
+ * make that launch fast, and an adapter started here would open stdio and sit waiting for an ACP
+ * `initialize` that is never coming.
+ *
+ * `process.execPath` rather than the string `node`: `npx` puts the freshly installed package's
+ * `bin` directory first on `PATH` for the child, and an absolute path cannot be shadowed by it.
+ *
+ * The same `npx`/`npx.cmd` choice `resolveLaunch` makes, for the same reason — this has to warm the
+ * cache that *that* command will read.
+ */
+export function installNpxPackage(spec, options = {}) {
+    const env = options.env ?? probeEnvironment();
+    // 钉版本才谈得上"已经装过":`spec` 不带版本时 `npmPackageVersion` 是 `undefined`,而缓存里一个
+    // 都没有时 `npxCacheVersion` 同样是 `undefined` —— 两个 `undefined` 相等,若不单独守住这一条,
+    // 一个从未被任何 npx 调用装过的包名,只要没剥版本前先被查过缓存,就会在这里被判定成"已经装好",
+    // 一次 npx 都不用起。registry 自己从不发不钉版本的 spec(见 `registry/launch.ts` 的说明),这条分支
+    // 过去因此从没被真正走到过;`unpinnedFallbackFor` 的回退——`AcpAgents.installNpxWithFallback`——
+    // 是第一个会把不带版本的 spec 递进来的调用方,伪装成功比真的失败更糟:界面会说"已安装",磁盘上
+    // 其实什么都没有。
+    const pinnedVersion = npmPackageVersion(spec);
+    if (pinnedVersion !== undefined && npxCacheVersion(spec, readNpxCache(env)) === pinnedVersion) {
+        return Promise.resolve({ ok: true, alreadyInstalled: true });
+    }
+    const platform = env.platform ?? process.platform;
+    const command = options.npxCommand ?? (platform === 'win32' ? 'npx.cmd' : 'npx');
+    return new Promise((resolve) => {
+        execFile(command, ['--yes', `--package=${spec}`, '--', process.execPath, '-e', ''], { timeout: options.timeoutMs ?? ADAPTER_INSTALL_TIMEOUT_MS, windowsHide: true }, (error, _stdout, stderr) => {
+            if (!error) {
+                resolve({ ok: true, alreadyInstalled: false });
+                return;
+            }
+            // npm says what actually went wrong (a 404 specifier, a proxy refusal, no disk) on stderr;
+            // `error.message` alone is "Command failed: npx …" plus, for a timeout, nothing at all.
+            const rawStderr = stderr.toString();
+            const detail = rawStderr.trim().split('\n').slice(-4).join(' ').trim();
+            resolve({
+                ok: false,
+                error: detail ? `${error.message.split('\n')[0]}: ${detail}` : error.message,
+                stderr: rawStderr,
+            });
+        });
+    });
+}
+/**
+ * Run one literal argv from `registry/catalog.ts`'s `dependency.install` — the *other* thing in
+ * this module that spawns anything, and the reason it may: that field is a security boundary
+ * (`catalog.ts`'s own doc comment), never a string, and this function is its only executor.
+ *
+ * `command` and `args` arrive pre-split and go to `execFile` exactly as given, with no
+ * `{ shell: true }` anywhere in this file. That is the whole guarantee: nothing downstream of the
+ * catalog — not registry data, not an agent's own stdout, not user input — ever has a chance to be
+ * interpolated into a string a shell would re-parse, because there is no shell in this path at all.
+ */
+export function runDependencyInstall(command, args, options = {}) {
+    return new Promise((resolve) => {
+        execFile(command, args, { timeout: options.timeoutMs ?? DEPENDENCY_INSTALL_TIMEOUT_MS, windowsHide: true }, (error, _stdout, stderr) => {
+            if (!error) {
+                resolve({ ok: true });
+                return;
+            }
+            const detail = stderr.toString().trim().split('\n').slice(-4).join(' ').trim();
+            resolve({ ok: false, error: detail ? `${error.message.split('\n')[0]}: ${detail}` : error.message });
+        });
+    });
+}