@platless/axom-cli 0.1.0

package/dist/workstation/acp/acpAgents.js

@@ -0,0 +1,1287 @@
+import path from 'node:path';
+import semver from 'semver';
+import { connectAgent, isMissingPackageVersion, jsonRpcErrorCode, stderrShowsMissingPackageVersion } from './acpClient.js';
+import { AcpSession } from './acpSession.js';
+import { createReplayCapture, listNativeSessions, replayNativeSession } from './adoption.js';
+import { AcpAuth } from './auth.js';
+import { binaryTargetFor, installBinary, installedBinaryVersion, platformTriple } from './binaryInstall.js';
+import { normalizeConfigOptions } from './configOptions.js';
+import { friendlyOrdinaryInstallError, friendlyPinnedVersionUnavailableAndFallbackFailed, logInstallFailureDetail, } from './installErrors.js';
+import { ADAPTER_INSTALL_TIMEOUT_MS, findOnPath, installNpxPackage, npmPackageName, npxCacheVersion, probeEnvironment, readNpxCache, runDependencyInstall, } from './installProbe.js';
+import { createDeferredPermissionSink, registerPermissionHandlers } from './permission.js';
+import { catalogEntryFor } from './registry/catalog.js';
+import { resolveLaunch, unpinnedFallbackFor } from './registry/launch.js';
+import { RegistryClient } from './registry/registryClient.js';
+import { installUvTool, listUvTools, uvPackageName, uvToolVersion } from './uvxInstall.js';
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * A session **the agent itself refused**, after its `initialize` had already succeeded — the shape
+ * an ACP `auth_required` on `session/new` arrives in.
+ *
+ * `AcpAgents.open` throws for reasons on both sides of that line: `resolveLaunchFor` finds nothing
+ * to launch, `connectResolved` fails to spawn or times out waiting for `initialize`, and only then
+ * does `startSession` ask for a session. Everything before the `initialize` is a *machine* failure,
+ * and the agent has said nothing at all — including nothing about credentials.
+ *
+ * The distinction has to be drawn here because this is the only place that knows it, and it has to
+ * be drawn at all because `observed` outlives one connection: a daemon that talked to this agent an
+ * hour ago still holds its method table, so a spawn `ENOENT` reported with `authMethods` beside it
+ * satisfies the engine's `error != null && authMethods.isNotEmpty()` and draws a login card for a
+ * missing binary. This mirrors what the probe path already does the long way round — `verify`
+ * catches a connect failure and answers with **no** methods, so there too the pairing can only be
+ * produced by a connection whose `initialize` succeeded.
+ *
+ * The message is the underlying failure's own, verbatim, so nothing downstream that reads or logs
+ * it sees a wrapper appear; `cause` keeps the original for anyone who needs more.
+ *
+ * {@link errorCode} is the second thing the wrapper preserves, and the reason it is captured *here*
+ * rather than read back later: this constructor is the last place the original error object exists
+ * as an object. `errorMessage(cause)` is a one-way door — after it, `auth_required` and "context
+ * window exceeded" are two English sentences, and telling them apart would mean matching on text an
+ * agent may rewrite in its next release. `undefined` when the refusal was not a JSON-RPC one.
+ */
+export class AgentRefusedSessionError extends Error {
+    errorCode;
+    constructor(cause) {
+        super(errorMessage(cause), { cause });
+        this.name = 'AgentRefusedSessionError';
+        this.errorCode = jsonRpcErrorCode(cause);
+    }
+}
+/**
+ * Wall-clock budget for one on-demand verification or authentication, spawn included.
+ *
+ * Both operations start a real subprocess for an agent the user may never have run on this machine
+ * — an npx package that is not cached yet, a wrapper script with a typo in it, an adapter that opens
+ * stdio and then sits there. Without a ceiling, one such agent parks a request on the management
+ * channel until the *server's* 30s deadline fires, and the user is told the workstation is
+ * unresponsive rather than that this one agent is. Kept below that server deadline on purpose, so
+ * the answer that comes back is this daemon's diagnostic and not a timeout.
+ *
+ * 这是**没人指定预算时**的取值。`agent_verify` 现在可以带一个 `timeoutMs`,让发起方把自己的
+ * 预算带过来(见 `agentSessions.ts` 的 `clampProbeTimeout`);上面那句「留在服务端 deadline
+ * 以下」只对那条不带预算的路成立。带预算是为了后台预热:那条路上没有人在等,而一次真正的冷
+ * 启动(node 解析 + 拉 adapter + agent CLI 首跑)本来就翻得过 20 秒这道墙。
+ */
+export const AGENT_PROBE_TIMEOUT_MS = 20_000;
+/**
+ * The ceiling on one whole `authenticate`, and **it is a leak guard, not a statement about how long
+ * a login should take.**
+ *
+ * A login is not a probe. {@link AGENT_PROBE_TIMEOUT_MS} answers "how long may an agent take to
+ * respond to a machine", and a person reading a device code out of a browser is not answering a
+ * machine — spec §6.2 measured an agent whose `authenticate` had still not returned after 25
+ * seconds because it was waiting on a browser callback. Ending that at twenty seconds does not make
+ * the login fail faster; it makes a login that was working look like a bug.
+ *
+ * So why a ceiling at all: every `authenticate` holds an agent subprocess and a connection open for
+ * as long as it runs, and nothing else will ever come back for them. If the reader closes the tab,
+ * walks away, or the agent simply never answers, this is the only thing that reclaims them. Ten
+ * minutes is chosen to be far past any real sign-in and far short of "until the daemon restarts" —
+ * it is deliberately not tuned, because tuning it would mean pretending it measures something.
+ */
+export const AGENT_LOGIN_CEILING_MS = 10 * 60_000;
+/**
+ * The budget one `authenticate` actually gets: `override` when it is a usable number of
+ * milliseconds, {@link AGENT_LOGIN_CEILING_MS} otherwise.
+ *
+ * Exists as a named function rather than an inline `??` so that "a login does not use the probe
+ * budget" is a claim a test can make in one call instead of having to wait out either budget in
+ * real time — see `acpAgents.test.ts`'s "gives a login a ceiling in minutes".
+ */
+export function loginDeadlineMs(override) {
+    if (typeof override !== 'number' || !Number.isFinite(override) || override <= 0)
+        return AGENT_LOGIN_CEILING_MS;
+    return override;
+}
+/** The reason {@link AgentLoginSink.signal} gives when it ends a login. */
+export class AgentLoginCancelledError extends Error {
+}
+/**
+ * `work`, but rejecting as soon as `signal` aborts.
+ *
+ * Deliberately does not cancel `work` — nothing in ACP can cancel an `authenticate` already sent, the
+ * same limitation `withDeadline` documents. The caller's `connection.close()` is what actually ends
+ * the agent; this only stops waiting on it. The abandoned promise gets a no-op `catch` for the same
+ * reason it does there: it usually rejects long after nobody is listening.
+ */
+function cancellable(work, signal, what) {
+    if (!signal)
+        return work;
+    if (signal.aborted) {
+        work.catch(() => { });
+        return Promise.reject(new AgentLoginCancelledError(`${what} was cancelled.`));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new AgentLoginCancelledError(`${what} was cancelled.`));
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+/**
+ * One login's URL bookkeeping: what has been shown, what is still on screen, and the fact that the
+ * login is over.
+ *
+ * Extracted from {@link AcpAgents.authenticate} rather than left as closures inside it because
+ * **two of its rules are otherwise unobservable**. Deduplication and the retraction on settle can be
+ * driven through a real agent; "a URL that arrives after the login ended is not shown" cannot — the
+ * only thing that could produce one is a child that is already being killed, so a test for it would
+ * be a race with a subprocess rather than an assertion. Here it is a function call.
+ *
+ * Every collection is per-call, not per-agent: two logins must not silently swallow each other's
+ * URLs because an identity provider handed out the same authorize endpoint.
+ */
+export function createLoginUrlSink(login) {
+    const shownUrls = new Set();
+    const outstanding = new Set();
+    let over = false;
+    const dismiss = (elicitationId) => {
+        // `delete` returns false for an id that was never presented — an `elicitation/complete` for a
+        // URL deduplicated away below, or one the agent invented — and for an id already retracted.
+        // Both must be silent: a retraction for a card that was never shown is not an event.
+        if (!outstanding.delete(elicitationId))
+            return;
+        login.dismiss?.(elicitationId);
+    };
+    return {
+        // **Absent when the caller has no `present`, never a wrapper around nothing.** A wrapper would
+        // be a function, and a function is all `handleCreateElicitation` and `captureChildStderr` look
+        // at: the elicitation would be *accepted* — claiming "this URL is in front of the user" — and
+        // stderr would be scanned, both on behalf of a reader who does not exist. Absence is the whole
+        // mechanism by which those two decline instead (Task 3), and it has to survive this hop.
+        ...(login.present
+            ? {
+                present: (elicitationId, url) => {
+                    // The login is over. A URL still arriving belongs to nothing — the stderr scan runs until
+                    // the child's stream ends, which is after the kill that ends the login — and showing it
+                    // would raise a card *after* the retraction, so nothing would ever take that one down.
+                    if (over)
+                        return;
+                    // Deduplication across *provenances*, not just within one. `captureChildStderr` already
+                    // deduplicates stderr against itself, but a device-code agent typically elicits the URL
+                    // and prints the same one, and those two arrive with different ids — so without this, one
+                    // login leaves two cards that nothing can ever merge.
+                    if (shownUrls.has(url))
+                        return;
+                    shownUrls.add(url);
+                    outstanding.add(elicitationId);
+                    login.present?.(elicitationId, url);
+                },
+            }
+            : {}),
+        dismiss,
+        finish: () => {
+            // Order matters: `over` first, so a line scanned between here and the last `dismiss` is
+            // dropped rather than presented into a login nobody is holding any more.
+            over = true;
+            for (const elicitationId of [...outstanding])
+                dismiss(elicitationId);
+        },
+    };
+}
+/** A verification or authentication ran past {@link AGENT_PROBE_TIMEOUT_MS}. */
+export class AgentProbeTimeoutError extends Error {
+}
+/**
+ * Reject with {@link AgentProbeTimeoutError} once `timeoutMs` has passed, whatever `work` is still
+ * doing.
+ *
+ * `work` is deliberately *not* cancelled here — nothing in ACP can cancel an `initialize` or a
+ * `session/new` in flight. What actually stops it is the caller's `connection.close()`, which kills
+ * the subprocess; this only stops the *waiting*. The abandoned promise gets a no-op `catch` because
+ * it will usually reject (the child died under it) long after nobody is listening, and an unhandled
+ * rejection would take the daemon down.
+ */
+async function withDeadline(work, timeoutMs, what) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new AgentProbeTimeoutError(`${what} did not finish within ${timeoutMs}ms.`)), timeoutMs);
+    });
+    deadline.catch(() => { });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+        work.catch(() => { });
+    }
+}
+/**
+ * 等**第一条** `available_commands_update` 的窗口。一条都没等到就收工,`observed` 保持 undefined
+ * ——按「缺席 ≠ 空表」的约定,服务端据此不写命令表那一半(见 {@link verify} 的 KDoc)。
+ *
+ * 数值沿用原来那个固定 settle 窗口(`docs/superpowers/notes/2026-08-31-codex-command-table-race.md`)。
+ * **没有证据支持把它调大**:真机上量到同一个 agent 在一台机器上回 72 条、在另一台回 0 条,但那两次
+ * 的耗时差(8.4s vs 2.1s)完全可能全部落在 spawn/connect 上,而不是广播来晚了。要区分这两件事,
+ * 得先有 {@link verify} 里那条「没等到表」的日志,不是先改这个数字。
+ */
+const COMMAND_FIRST_BROADCAST_MS = 1500;
+/**
+ * 第一条广播到手之后,每再来一条就重新计时;安静这么久没有新的就认为表定下来了。
+ *
+ * 它替掉的是「无论如何都睡满 {@link COMMAND_FIRST_BROADCAST_MS}」那个写法,买到两件事:
+ * 常见情况**更快**(第一条 100ms 到、第二条 300ms 到 → 1050ms 收工,而不是雷打不动 1500ms),
+ * 以及第一条卡在窗口末尾时**不再把第二条丢掉**(Claude 会广播两次,第二条才是过滤掉终端专用命令
+ * 之后能用的那份)。一条都没等到的路径完全不受影响 —— 这是它严格不劣于原实现的原因。
+ */
+const COMMAND_QUIET_MS = 750;
+/**
+ * 绝对上限:第一条广播之后总共最多再等这么久,防一个不停重推的 agent 把安静期无限续下去。
+ * 必须显著小于 {@link AGENT_PROBE_TIMEOUT_MS} —— 连接和 `session/new` 还要在这之前各花一段。
+ */
+const COMMAND_SETTLE_CEILING_MS = 5_000;
+/** ACP 的 `AvailableCommand` → 隧道形状:`input.hint` 拍平成 `inputHint`。 */
+function toAvailableCommandWire(raw) {
+    const command = raw;
+    return {
+        name: typeof command.name === 'string' ? command.name : '',
+        description: typeof command.description === 'string' ? command.description : '',
+        ...(typeof command.input?.hint === 'string' ? { inputHint: command.input.hint } : {}),
+    };
+}
+/**
+ * Everything one live connection reveals about an agent, in the one shape {@link AcpAgents.observe}
+ * merges.
+ *
+ * A function rather than four separate object literals so that a field added to
+ * {@link AuthObservation} cannot be recorded on some connection paths and silently missed on
+ * others — `verify` and `listNativeSessions` are exactly the paths a settings page depends on, and
+ * they are the ones nobody remembers.
+ */
+function observationOf(connection) {
+    return { authMethods: connection.authMethods, supportsSteering: connection.supportsSteering };
+}
+/**
+ * The version of `agent`'s ACP adapter actually found on this machine, dispatched by distribution
+ * channel — the npx cache (`npxCacheVersion`), a hoisted `uv tool list` snapshot (`uvVersions`), or
+ * the binary install root (`installedBinaryVersion`). Unlike `adapterInstalled`, which only ever
+ * answered for npx, this covers all three, and `undefined` here is a genuine "not installed" rather
+ * than "did not look" — every branch is a cheap local read this daemon always performs.
+ *
+ * An agent with more than one distribution (uncommon on the live registry, but not ruled out by the
+ * types) is checked npx-first, then uvx, then binary — the same preference order `resolveLaunch`
+ * uses to pick which one actually launches.
+ *
+ * `uvVersions` is a pre-read `uv tool list` snapshot ({@link listUvTools}), not a live call: `uv` is
+ * a real subprocess, and this function runs once per registry entry inside {@link AcpAgents.roster}'s
+ * map — spawning it per uvx agent there is exactly the per-agent-subprocess defect the roster's own
+ * doc comment rules out (39 entries, on every scan). The caller reads `uv tool list` exactly once and
+ * hands the parsed result in here for a plain map lookup.
+ */
+function adapterVersionFor(agent, npxCache, adapterRoot, uvVersions) {
+    const { npx, uvx, binary } = agent.distribution;
+    if (npx)
+        return npxCacheVersion(npx.package, npxCache);
+    if (uvx)
+        return uvVersions.get(uvPackageName(uvx.package));
+    if (binary)
+        return installedBinaryVersion(agent.id, adapterRoot, agent.version);
+    return undefined;
+}
+/**
+ * Whether `agent` cannot be launched on this machine **at all** — not "its `binary` archive is
+ * missing for this platform", which is what this used to check on its own, independent of whatever
+ * else the agent offers.
+ *
+ * `resolveLaunch` (`registry/launch.ts`) tries npx first, then uvx, then binary, and an agent with
+ * either of the first two is launchable through it regardless of what its `binary` block does or
+ * does not cover — `kilo` and `sigit` on the live registry both carry `npx` *and* `binary`, and a
+ * platform missing their binary archive is still fully served by npx. So this derives its answer
+ * from the same preference order rather than asking a second, independent question that can drift
+ * from it: `false` the moment `npx` or `uvx` is present, whatever `binary` says; otherwise `true`
+ * when there is no `binary` distribution either (nothing left to launch through), or when there is
+ * one but it publishes no archive for this machine's platform triple. See `binaryInstall.ts`'s
+ * module doc for the coverage numbers the binary-only case was measured against.
+ */
+function isUnsupportedPlatform(agent, platform, arch) {
+    const { npx, uvx, binary } = agent.distribution;
+    if (npx || uvx)
+        return false;
+    if (!binary)
+        return true;
+    const triple = platformTriple(platform, arch);
+    return !triple || !binaryTargetFor(agent, triple);
+}
+export class AcpAgents {
+    registry;
+    platform;
+    arch;
+    probe;
+    runCommand;
+    /**
+     * Where `binaryInstall.ts` unpacks binary-distributed adapters —
+     * `<workstation config dir>/acp-adapters`, derived from the same `cacheDir` the registry cache
+     * itself lives in directly (ruling F2 in the plan's pre-flight scan: `resolveLaunch`'s binary
+     * branch needs this root and nothing else in this class's options carries it).
+     */
+    adapterRoot;
+    /** Last observation per registry agent id; in-process only, by design — see {@link AuthObservation}. */
+    observed = new Map();
+    /** Injectable `uv` runner for {@link roster}'s single hoisted `uv tool list` read; see {@link AcpAgentsOptions.runUv}. */
+    runUv;
+    /** Injectable `npx` binary for {@link installAdapter}'s npx branch; see {@link AcpAgentsOptions.npxCommand}. */
+    npxCommand;
+    constructor(options) {
+        this.registry = options.registry ?? new RegistryClient({ cacheDir: options.cacheDir });
+        this.platform = options.platform ?? process.platform;
+        this.arch = options.arch ?? process.arch;
+        this.probe = options.probe ?? probeEnvironment();
+        this.runCommand = options.runCommand ?? runDependencyInstall;
+        this.runUv = options.runUv;
+        this.npxCommand = options.npxCommand;
+        this.adapterRoot = path.join(options.cacheDir, 'acp-adapters');
+    }
+    /**
+     * The roster reported in the `hello` frame and answered to an external-agents scan, one entry per
+     * registry agent.
+     *
+     * `available` means *launchable by this build*, which is "the registry gives it an npx or uvx
+     * distribution" — a binary-only agent stays in the roster and reports `false` so the settings page
+     * can say why it cannot be started (ruling R6), rather than vanishing from the list.
+     *
+     * ## `available` is not, and never was, an installation
+     *
+     * It is a property of the **registry entry**: identical on every machine on earth. A settings page
+     * that rendered it as "Ready to launch" told readers that agents they had never installed were
+     * ready, and told one reader that the Antigravity he *had* installed was unusable. `adapterInstalled`
+     * is the one field that does describe this machine (has the ACP adapter already been downloaded
+     * here), spread in only when it was genuinely established.
+     *
+     * `recommended` / `defaultName` / `defaultLabel` come from `registry/catalog.ts` — the curated list
+     * of agents Axom has actually verified, which replaced the old "official CLI on PATH" table. They
+     * are spread in only for a catalog hit; an agent outside the catalog is not claimed either way.
+     *
+     * Never throws, for the same reason the deleted `rosterFor` swallowed a failing probe: a registry
+     * that is unreachable on a cold-start machine must not be able to stop the daemon from connecting.
+     * An empty roster is the honest answer there — this build genuinely knows of no agents yet.
+     *
+     * `authMethods`/`authenticated` are carried **only for agents this process has already connected
+     * to** (see {@link AuthObservation}). Building the roster does not spawn anything, so a freshly
+     * started daemon reports neither field for anything — that absence is the truthful answer and the
+     * server contract spells out that it means "unknown", not "not authenticated".
+     */
+    async roster() {
+        let agents;
+        try {
+            agents = await this.registry.load();
+        }
+        catch (error) {
+            console.warn(`[acp] agent registry unavailable, reporting an empty roster: ${errorMessage(error)}`);
+            return [];
+        }
+        // Read once for the whole roster, not once per agent: this is a directory scan, and the
+        // registry has 39 entries.
+        const npxCache = readNpxCache(this.probe);
+        // Same reasoning, for `uv`: a directory scan has no subprocess to spawn, but `uv tool list` does,
+        // and building the roster must not spawn anything per agent (see this method's own doc comment).
+        // Read it exactly once here and let every uvx-distributed agent below look itself up in the
+        // result, instead of `adapterVersionFor` shelling out to `uv` again for each one. `uv` is now a
+        // non-blocking call (see `uvxInstall.ts`'s `RunUv`), hence the `await` — it still happens only
+        // this once per roster build, not once per agent.
+        const uvTools = await listUvTools(this.runUv);
+        const uvVersions = new Map(uvTools.map((entry) => [entry.name, entry.version]));
+        // Hoisted for the same reason as `npxCache`/`uvTools`: it is the same value for every entry in
+        // this roster (a fact about this machine, not this agent), so it is computed once rather than
+        // once per agent inside the `.map` below.
+        const triple = platformTriple(this.platform, this.arch);
+        // `Promise.all` over an async map, not a plain `.map`, only because `resolvable` below now
+        // returns a `Promise` (it calls the now-async `resolveLaunch`) — every entry still resolves
+        // synchronously off the already-hoisted `uvTools` snapshot, so this adds no real waiting and no
+        // extra `uv` spawns, just Promise bookkeeping around work that was already computed once.
+        return Promise.all(agents.map(async (agent) => {
+            const observation = this.observed.get(agent.id);
+            const catalog = catalogEntryFor(agent.id);
+            // Computed once and used by both `adapterInstalled` and `adapterVersion` below: they are two
+            // halves of one disk read, and deriving them separately is exactly how they drifted apart.
+            const adapterVersion = adapterVersionFor(agent, npxCache, this.adapterRoot, uvVersions);
+            return {
+                type: agent.id,
+                // `uvTools` is the same hoisted `uv tool list` snapshot `adapterVersion` below looks up in
+                // (`uvVersions`) — handed through so this doesn't make `resolveLaunch` spawn `uv` again for
+                // every uvx-distributed agent (see `resolvable`'s own doc comment).
+                available: await this.resolvable(agent, uvTools),
+                version: agent.version,
+                // Always present: the registry document itself always carries a version for every entry,
+                // unlike `adapterVersion` below, which depends on what this particular machine has done.
+                registryVersion: agent.version,
+                // **Presence, at any version — never a match against the registry's pin.**
+                //
+                // This field used to compare the cached version against `registry/launch.ts`'s pinned one,
+                // which is the very conflation this whole redesign exists to remove: a configured, working
+                // `claude-acp` cached at 0.74.0 against a registry that had moved to 0.75.0 read as *not
+                // installed*, which made `installedVersion` null on the card, which made `updatable` false,
+                // which meant the one reader who most needed an `Update` button was the one reader who
+                // never got offered one (design §11). Which version is on disk is `adapterVersion`'s job
+                // below; whether it is behind the pin is the card's `updatable` comparison. Neither belongs
+                // here. Range handling survives only where a genuine range specifier can appear — the
+                // *launch* decision in `registry/launch.ts` — not in this presence check.
+                //
+                // Covers all three distribution channels, so `false` is now a real answer rather than
+                // "did not look": `adapterVersionFor` reads the npx cache, the hoisted `uv tool list`
+                // snapshot and our own binary install root, and every one of them is a local read.
+                //
+                // `dependencySatisfied` folds in the catalog's extra prerequisite (design §4.4): `pi-acp`'s
+                // adapter sitting in the npx cache with no `pi` on `PATH` is not an agent this machine can
+                // add — the card would offer `Add`, the try-run would fail, and the reader would be told
+                // nothing about the missing CLI. Reporting it not-installed is what makes `Install` fetch
+                // the dependency too.
+                adapterInstalled: adapterVersion !== undefined && this.dependencySatisfied(agent.id),
+                // The version half of the same answer — see `adapterVersionFor`'s doc comment. Absent
+                // rather than null when nothing is installed, on this file's usual "never write down what
+                // nobody looked at" rule.
+                ...(adapterVersion ? { adapterVersion } : {}),
+                // `true`-or-absent, like `recommended`/`supportsSteering` below: this only ever fires for a
+                // `binary` distribution missing an archive for this machine's platform triple.
+                //
+                // `platformTriple` rides along only in this branch: it exists to explain *this* refusal (a
+                // settings page rendering "Not available for `<platform triple>`" must quote the identifier
+                // that actually decided it, not reconstruct one from the workstation's separately-reported
+                // OS name/arch, which can drift from the registry's own triple vocabulary), so an agent this
+                // machine can launch has no use for it. Absent when the machine's own platform/arch falls
+                // outside the registry's six triples (see `binaryInstall.ts`'s `platformTriple`) — `true`
+                // with no triple to quote is still the correct, honest signal in that case.
+                ...(isUnsupportedPlatform(agent, this.platform, this.arch)
+                    ? { unsupportedPlatform: true, ...(triple ? { platformTriple: triple } : {}) }
+                    : {}),
+                // The registry publishes a human-facing name for every agent; carrying it is what stops the
+                // other end from having to invent one out of the id. Spread on the same "absent, not empty"
+                // principle as the auth fields below: a registry entry with a blank `name` has published
+                // nothing, and `displayName: ''` would hand a settings page an empty label to render where
+                // its id-derived fallback would have said something.
+                ...(agent.name ? { displayName: agent.name } : {}),
+                ...(agent.description ? { description: agent.description } : {}),
+                // Spread from `registry/catalog.ts` only for a catalog hit — `recommended` has no `false`,
+                // the same "absent means unknown/no" rule as `supportsSteering` below.
+                ...(catalog ? { recommended: true, defaultName: catalog.defaultName } : {}),
+                ...(catalog?.defaultLabel ? { defaultLabel: catalog.defaultLabel } : {}),
+                // Spread rather than assign: an explicit `authMethods: undefined` would still be an own
+                // property, and "the key is here but empty" is exactly the ambiguity these fields exist to
+                // avoid on the roster's other end.
+                ...(observation ? { authMethods: observation.authMethods } : {}),
+                ...(observation?.authenticated ? { authenticated: observation.authenticated } : {}),
+                // Spread on the same principle, and `=== true` rather than truthy: an agent this process
+                // has connected to and found *not* steering-capable publishes nothing, because absent
+                // already means "do not offer it". See `BridgeInfo.supportsSteering`.
+                ...(observation?.supportsSteering === true ? { supportsSteering: true } : {}),
+            };
+        }));
+    }
+    /**
+     * Record what a just-established connection revealed about one agent. Called on every connection,
+     * including the throwaway one {@link listNativeSessions} makes, because the `initialize` response
+     * is the only place `authMethods` ever appears.
+     *
+     * Merges rather than replaces, so a connection that only got as far as `initialize` cannot erase
+     * the `authenticated` proof an earlier session left behind.
+     */
+    observe(agentId, observation) {
+        const previous = this.observed.get(agentId);
+        this.observed.set(agentId, { ...previous, ...observation });
+    }
+    /**
+     * What one agent was last seen to advertise as ways of signing in, or `undefined` when this
+     * process has never connected to it.
+     *
+     * The read half of {@link observe}, for the **session** path. {@link roster} folds the same
+     * observation into a `BridgeInfo`, but the roster travels once, in the `agent_hello` handshake —
+     * a snapshot taken before anything has been connected to, so it is empty for exactly the agent
+     * nobody has used yet. A session's failure frames need the answer at the moment they are built,
+     * which is after `open` recorded it (deliberately before `startSession`, so an
+     * `auth_required` rejection still has the table behind it).
+     *
+     * **`undefined` and `[]` are different answers and both are meaningful**: `undefined` = never
+     * connected, so nothing can be said; `[]` = connected, and the agent advertised no sign-in
+     * method. Callers put that difference straight on the wire; see
+     * `AGENT_WIRE_SESSION_AUTH_METHODS_VERSION`.
+     *
+     * Keyed by **registry agent id** ({@link AcpOpenSpec.agentId}), never by the workstation's
+     * configured entry name — the two are different values, and looking up by the wrong one would
+     * report "never connected" for every session ever opened.
+     */
+    observedAuthMethods(agentId) {
+        return this.observed.get(agentId)?.authMethods;
+    }
+    /**
+     * Start one session: spawn the agent, negotiate `initialize`, and either continue in
+     * {@link AcpOpenSpec.nativeSessionId} or open a fresh one.
+     *
+     * The subprocess is killed on every failure path after it was spawned — an agent left running for
+     * a session that never registered is exactly the orphan the manager's own tombstone machinery
+     * exists to prevent one layer up.
+     */
+    async open(spec) {
+        const resolved = await this.resolveLaunchFor(spec.agentId, spec.command, spec.args);
+        const capture = createReplayCapture();
+        const permissions = createDeferredPermissionSink();
+        const connection = await this.connectResolved(spec.agentId, resolved, spec.env, spec.agentEnv, {
+            // Both registrations go in one hook: `ClientApp.connect()` copies its handler table once, so
+            // this is the only moment either of them can be installed (see `acpClient.ts`'s
+            // `ConnectAgentOptions.configure`).
+            //
+            // The capture goes FIRST, and the order is load-bearing rather than stylistic. The SDK awaits
+            // every handler in registration order (`jsonrpc.js`'s `processIncomingMessage`), so each one
+            // ahead of the capture costs it a microtask hop before it ever sees a `session/update` — while
+            // the response that ends the same `session/load` / `session/prompt` is applied synchronously
+            // off the reader. Registering the capture behind the three permission handlers is what made
+            // that gap wide enough to observe (measured: a turn's trailing deltas arriving after its own
+            // `stop`). `settleUpdates` is the actual fix — this is defence in depth, and it is not a
+            // substitute: nothing here forces the capture to stay first.
+            //
+            // ## Prerequisite for anything added to this hook: **every handler registered here must be
+            // ## synchronous with respect to `session/update`**
+            //
+            // This is where that property is established, so this is where it is written down —
+            // `settleUpdates` (`adoption.ts`) depends on it and cannot check it. It waits one macrotask
+            // boundary, which drains a chain of *synchronous* handlers' microtask continuations and
+            // nothing more; a handler that awaits a real macrotask (a timer, a file read, a subprocess,
+            // an HTTP call) before returning `Handled.no` moves the rest of the chain past that boundary
+            // and the wait ends with **zero** updates delivered — measured, and silent apart from
+            // `settleUpdates`' own maxRounds diagnostic, which this failure does not even trip.
+            //
+            // Both current registrations satisfy it. `capture.register` is a plain synchronous
+            // `onNotification` body. The permission handlers do block on a human answer, but only for
+            // `session/request_permission` and `elicitation/*`; for a `session/update` they fall through
+            // without awaiting anything real. Anything added here later has to clear the same bar — if it
+            // genuinely needs to await, it must do that work *after* handing the message on, not before.
+            configure: (app) => {
+                capture.register(app);
+                // **No `present` here, and that is a decision rather than an omission.** A session
+                // connection lives for hours; a `url` elicitation raised on one is not a sign-in the reader
+                // asked for, and there is no login for a card on screen to belong to. So
+                // `handleCreateElicitation` declines it rather than accepting into a void, which is an
+                // answer the agent can act on. The one connection that *does* wire both callbacks is the
+                // throwaway one {@link authenticate} opens — see {@link connectFor}. The stderr half of the
+                // same rule is enforced by the compiler: `ConnectAgentOptions.present` is typed `never`, so
+                // this call's sibling option cannot arm the sniffer on a session either.
+                //
+                // `dismiss` is a no-op for the same reason: nothing was presented, so nothing can be
+                // retracted, and an agent that sends `elicitation/complete` anyway must not crash the
+                // connection over it.
+                registerPermissionHandlers(app, permissions.sink, { dismiss: () => { } });
+            },
+        });
+        this.observe(spec.agentId, observationOf(connection));
+        try {
+            const started = await this.startSession(connection, capture, spec);
+            // Only here, never before: the agent accepted a session, which is the one piece of evidence
+            // ACP offers that it is not waiting on credentials. Recording it up at `initialize` time
+            // would claim authentication for an agent about to reject `session/new` with auth_required.
+            this.observe(spec.agentId, { ...observationOf(connection), authenticated: true });
+            permissions.bind(started.session);
+            return {
+                session: hostedSession(started.session, connection, started.history, started.configOptions),
+                nativeSessionId: started.nativeSessionId,
+            };
+        }
+        catch (error) {
+            await connection.close().catch(() => undefined);
+            // Marked, not merely rethrown: everything above this `try` failed before the agent said
+            // anything, and only a failure from here on can be an `auth_required`. See
+            // {@link AgentRefusedSessionError} — `agentSessions.ts` is the reader.
+            throw new AgentRefusedSessionError(error);
+        }
+    }
+    /**
+     * List one agent's native sessions for adoption, via a throwaway connection — listing happens
+     * before any session exists, so there is nothing running to ask.
+     *
+     * Degrades to an empty list rather than an error when the agent does not advertise
+     * `sessionCapabilities.list` (that gate lives in `adoption.ts`); a *connection* failure still
+     * throws, because "this agent is not installed" and "this agent has no sessions" must not look
+     * alike to the user.
+     */
+    async listNativeSessions(spec) {
+        const resolved = await this.resolveLaunchFor(spec.agentId, spec.command, spec.args);
+        const connection = await this.connectResolved(spec.agentId, resolved, spec.env, spec.agentEnv);
+        this.observe(spec.agentId, observationOf(connection));
+        try {
+            const result = await listNativeSessions(connection, { cwd: spec.filterCwd });
+            return result.sessions;
+        }
+        finally {
+            await connection.close().catch(() => undefined);
+        }
+    }
+    /**
+     * Verify one agent on demand: spawn it, negotiate `initialize`, try to open a session, then throw
+     * the whole thing away. Nothing is kept running — a verification is a question, not a resource.
+     *
+     * This is the only way the roster's auth fields can ever be populated for an agent nobody has
+     * started a session with, which is the case a settings page is looking at: {@link roster} reads
+     * {@link AuthObservation} and building the roster spawns nothing, so before the first verification
+     * (or the first real session) every agent reports "unknown" and stays that way. What is learned
+     * here goes through {@link observe}, so the next `hello`/scan carries it.
+     *
+     * ### Two outcomes, and neither of them is "not authenticated"
+     *
+     * A session that opened proves the agent is not waiting on credentials — that is `authenticated:
+     * true`. A session that did not open proves nothing at all: the agent may need signing in, or its
+     * cwd may not exist, or it may have crashed. That case comes back as {@link
+     * AcpVerification.sessionError} — the observed facts, with no verdict attached — and the
+     * observation is *not* updated, so an earlier proof is not erased by a later inconclusive attempt.
+     *
+     * Failing to connect at all throws, because "this agent is not installed" and "this agent is
+     * installed and would not start a session" are different answers to the user.
+     */
+    async verify(spec, timeoutMs = AGENT_PROBE_TIMEOUT_MS) {
+        const connection = await this.connectFor(spec, timeoutMs);
+        const authMethods = connection.authMethods;
+        this.observe(spec.agentId, observationOf(connection));
+        try {
+            let observed;
+            let observedConfig;
+            await withDeadline((async () => {
+                const opened = await AcpSession.open(connection, { cwd: spec.cwd });
+                // Captured off `session/new`'s own response, not off the settle wait below: the snapshot
+                // exists the moment `AcpSession.open` resolves, unlike the command table, which the agent
+                // only broadcasts afterwards.
+                observedConfig = opened.configOptions;
+                // The table is broadcast *after* `session/new` is answered (`acp-agent.js:752-757`), so a
+                // verification that closed here — as this one used to — could never see it. The sink is
+                // attached after `open` on purpose and is still safe: `AcpSession` buffers events until
+                // one is attached (`onEvent`'s `drain()`), so nothing that arrived in between is lost.
+                // Settle rather than "first push wins": Claude broadcasts twice — once on `session/new`
+                // and again when the init frame lets it filter out terminal-bound commands. Taking the
+                // first would leave commands in the menu that do nothing over ACP.
+                //
+                // 但**不能靠一个固定的等待**。这里原本是 `setTimeout(1500)` 死等，于是这段代码在和
+                // agent 的广播赛跑，而且**机器越快越容易输**：`session/new` 秒回时,1.5 秒窗口内广播还
+                // 没到,`observed` 保持 undefined,整张命令表就此丢失。真机上量到过同一个 agent 在热机器
+                // 上 2.1 秒回来 0 条、在慢机器上 8.4 秒回来 72 条 —— 差别只是后者慢到"顺便"等到了。
+                //
+                // 原来是无条件 `setTimeout(1500)` 睡满。改成两段:一条都没来 → 到
+                // [COMMAND_FIRST_BROADCAST_MS] 就收工(与原实现逐字同样的时间与结果);来了第一条 →
+                // 改用安静期收尾,并受 [COMMAND_SETTLE_CEILING_MS] 兜底。**严格不劣于原实现**:
+                // 没有广播的路径一模一样,有广播的路径要么更快,要么多收到一条原本会被丢掉的。
+                let finish;
+                const settled = new Promise((resolve) => {
+                    finish = resolve;
+                });
+                let quietTimer;
+                let ceilingTimer;
+                let firstTimer = setTimeout(() => finish?.(), COMMAND_FIRST_BROADCAST_MS);
+                opened.session.onEvent((event) => {
+                    if (event.eventName !== 'available_commands_update')
+                        return;
+                    const commands = event.payload.availableCommands;
+                    if (Array.isArray(commands))
+                        observed = commands.map(toAvailableCommandWire);
+                    // 第一条到手:等第一条的窗口作废,换成"安静就收工"+ 绝对上限。
+                    if (firstTimer !== undefined) {
+                        clearTimeout(firstTimer);
+                        firstTimer = undefined;
+                        ceilingTimer = setTimeout(() => finish?.(), COMMAND_SETTLE_CEILING_MS);
+                    }
+                    // 每再来一条就把安静计时重新起头 —— Claude 的第二条才是能用的那份。
+                    if (quietTimer !== undefined)
+                        clearTimeout(quietTimer);
+                    quietTimer = setTimeout(() => finish?.(), COMMAND_QUIET_MS);
+                });
+                await settled;
+                if (firstTimer !== undefined)
+                    clearTimeout(firstTimer);
+                if (quietTimer !== undefined)
+                    clearTimeout(quietTimer);
+                if (ceilingTimer !== undefined)
+                    clearTimeout(ceilingTimer);
+                if (observed === undefined) {
+                    // A 那条日志的 daemon 侧对应物。没有它,"这个 agent 在这个目录下没有命令" 与
+                    // "表来晚了、窗口没接住" 在任何一层都分不开 —— 而这两件事的修法完全不同。
+                    console.warn(`[acp] agent '${spec.agentId}' broadcast no command table within ` +
+                        `${COMMAND_FIRST_BROADCAST_MS}ms of opening a session in ${spec.cwd}`);
+                }
+                await opened.session.close().catch(() => undefined);
+            })(), timeoutMs, `Opening a session on agent '${spec.agentId}'`);
+            this.observe(spec.agentId, { ...observationOf(connection), authenticated: true });
+            return {
+                authMethods,
+                authenticated: true,
+                ...(observed !== undefined ? { availableCommands: observed } : {}),
+                ...(observedConfig !== undefined ? { configOptions: observedConfig } : {}),
+            };
+        }
+        catch (error) {
+            // Prefixed rather than relayed raw: the SDK masks an agent-thrown error as "Internal error",
+            // and a settings page showing that alone tells the user nothing about which agent it came from
+            // or what was being attempted.
+            return { authMethods, sessionError: `Agent '${spec.agentId}' did not open a session: ${errorMessage(error)}` };
+        }
+        finally {
+            await connection.close().catch(() => undefined);
+        }
+    }
+    /**
+     * Run one agent's `authenticate` for a `methodId` **it advertised**, over a throwaway connection.
+     *
+     * The refusal for an unadvertised (or terminal) `methodId` is {@link AcpAuth}'s and happens before
+     * anything is written to the agent — which is why this hands `AcpAuth` the connection rather than
+     * re-deriving the check: there is exactly one place that rule lives.
+     *
+     * Deliberately does not report an auth state. `authenticate` resolving means the agent accepted
+     * the call, which is not the same as a session it will now open; the caller asks {@link verify}
+     * for that, and gets an observation made the only way ACP allows one to be made. What is recorded
+     * here is `authMethods`, because `initialize` happened.
+     */
+    async authenticate(spec, methodId, login = {}) {
+        const urls = createLoginUrlSink(login);
+        // **The retraction has to cover the connect, not just the login.** The sniffer is armed inside
+        // `connectAgent` at `spawn()`, before `initialize` — so a URL can be presented while this is
+        // still awaiting, and every way connecting fails (initialize timeout, spawn error, an
+        // unsupported protocol version, the unpinned retry failing too) would otherwise leave the card
+        // up with nothing left running that could ever take it down. Measured, not reasoned: a probe of
+        // the first version reported `PRESENTED [ 'stderr-auth-url-…' ] RETRACTED []`. And the trigger
+        // is ordinary — the scan covers the `npx` install, whose own output can carry a "visit this
+        // URL" line, and a login whose agent then fails to install is exactly when that appears.
+        try {
+            const connection = await this.connectFor(spec, AGENT_PROBE_TIMEOUT_MS, {
+                ...(urls.present ? { present: urls.present } : {}),
+                dismiss: urls.dismiss,
+            });
+            this.observe(spec.agentId, observationOf(connection));
+            try {
+                const what = `Signing in to agent '${spec.agentId}' with method '${methodId}'`;
+                await withDeadline(cancellable(new AcpAuth(connection).authenticate(methodId), login.signal, what), loginDeadlineMs(login.ceilingMs), what);
+            }
+            finally {
+                // The connection dies here and not a moment earlier — this `finally` runs when the login
+                // *settles*, never on a probe-sized deadline part-way through one.
+                await connection.close().catch(() => undefined);
+            }
+        }
+        finally {
+            // The retraction trigger a stderr-sourced URL can never get from the protocol — see
+            // {@link createLoginUrlSink}. This runs on every exit, including every way connecting failed.
+            urls.finish();
+        }
+    }
+    /**
+     * The spawn half shared by {@link verify} and {@link authenticate}. No session either way — but
+     * **not "no handlers" any more**, and the difference is the whole of Task 4b: `authenticate` is a
+     * round trip through a human, so its connection carries the elicitation/permission handlers and
+     * the stderr sniffer that a login URL reaches the reader through. `verify` passes no `login` and
+     * so gets exactly what it always got: a bare connection nobody can raise a card on.
+     *
+     * **This is the only method in this class that builds a `present`**, and that is the mechanism, not
+     * a convention: {@link connectResolved} — the route every other connection takes, including
+     * {@link open}'s long-lived session — accepts only {@link ConnectAgentOptions}, whose `present` is
+     * typed `never`. Arming the stderr sniffer anywhere else would mean writing a fresh `connectAgent`
+     * call by hand, which is a visibly deliberate act rather than one more argument. What that buys is
+     * in `acpClient.ts`'s `ConnectLoginAgentOptions.present`: the scan starts at `spawn()` and cannot
+     * tell a third party's "visit this URL" from a login's, which is survivable for the seconds a
+     * login connection lives and is not survivable for the hours a session connection does.
+     *
+     * The *elicitation* half of the same rule is convention, not type: `registerPermissionHandlers`
+     * takes an optional `present` from any caller, and {@link open} passes none on purpose (see the
+     * comment there). It is the lesser of the two — that callback fires only on a real `url`
+     * elicitation, never on install output — but it is not mechanised, and a reader should not have to
+     * infer which half is which.
+     *
+     * `timeoutMs` budgets **the connect**, not what the caller then does with the connection: it is
+     * `connectAgent`'s `initialize` deadline, whose expiry kills the child. A login's own budget is
+     * {@link AGENT_LOGIN_CEILING_MS} and is applied around `authenticate` alone.
+     */
+    async connectFor(spec, timeoutMs, login) {
+        const resolved = await this.resolveLaunchFor(spec.agentId, spec.command, spec.args);
+        // The same budget as the caller's, not the 30s default: `connectAgent` kills the child when it
+        // fires, which is the only thing that stops an agent that opened stdio and never spoke.
+        if (!login)
+            return this.connectResolved(spec.agentId, resolved, spec.env, spec.agentEnv, { initializeTimeoutMs: timeoutMs });
+        const options = {
+            initializeTimeoutMs: timeoutMs,
+            ...(login.present ? { present: login.present } : {}),
+            configure: (app) => {
+                // The same registration the session connection makes (see `open`), with the two
+                // elicitation callbacks actually wired — this is the only connection they can be reached
+                // on, because `authenticate` does not run on a session's connection.
+                //
+                // The sink is deferred and never bound, deliberately: there is no `AcpSession` here, so an
+                // agent that sent `session/request_permission` on a login connection would be referring to
+                // a session that cannot exist. `createDeferredPermissionSink` answers that by throwing a
+                // named error, which the SDK turns into a JSON-RPC error for the agent — loud and
+                // attributable, rather than a card dropped into nothing.
+                registerPermissionHandlers(app, createDeferredPermissionSink().sink, {
+                    present: login.present,
+                    dismiss: login.dismiss ?? (() => { }),
+                });
+            },
+        };
+        return withUnpinnedFallback(spec.agentId, resolved, (launch) => connectAgent(launch, spec.env, spec.agentEnv, options));
+    }
+    /**
+     * Continue in an already-existing native session when we have an id for one and the agent can load
+     * it; otherwise open a new session and report the new id truthfully.
+     *
+     * Two things are deliberately *not* failures here. An agent that does not advertise
+     * `loadSession` still gets a session — the manager already tolerates the id it asked for coming
+     * back different (it warns and re-points), so refusing to open would be strictly worse than
+     * continuing in a fresh one. A `session/load` that is advertised but rejected (a stale id the
+     * agent has since deleted, most likely) is treated the same way, for the same reason.
+     *
+     * `AcpSession.attach` runs **before** the replay, not after: it subscribes to the connection's live
+     * `session/update` stream, and `ReplayCapture` withholds updates from that subscription for exactly
+     * as long as the id is armed — i.e. for the whole `session/load`. Subscribing afterwards would
+     * leave a gap between the replay's `take()` and the subscription in which a live update is dropped.
+     */
+    async startSession(connection, capture, spec) {
+        const nativeSessionId = spec.nativeSessionId;
+        if (nativeSessionId) {
+            if (!connection.capabilities.loadSession) {
+                console.warn(`[acp] agent '${spec.agentId}' does not support session/load; starting a new session ` +
+                    `instead of continuing '${nativeSessionId}'`);
+            }
+            else {
+                // `AcpSession.attach` reads `initial.configOptions` lazily (see its own doc comment) —
+                // exactly so this can hand it a mutable object *before* the snapshot exists, and fill it in
+                // below once `session/load`'s response arrives. Snapshotting eagerly here (e.g. passing
+                // `{ configOptions: [] }` outright) would leave the attached session's `configOptions`
+                // empty forever, because nothing would ever revisit it.
+                const initial = { configOptions: [] };
+                const session = AcpSession.attach(connection, nativeSessionId, capture, initial);
+                try {
+                    const history = [];
+                    for await (const event of replayNativeSession(connection, capture, {
+                        cwd: spec.cwd,
+                        nativeSessionId,
+                        onLoaded: (response) => {
+                            initial.configOptions = normalizeConfigOptions(response.configOptions, response.modes);
+                        },
+                    })) {
+                        // Folded and validated either way (one code path, no second copy of the replay rules);
+                        // retained only when someone is going to ask for it, so a long history is not held for
+                        // the life of a session that will never replay it.
+                        if (spec.backfill)
+                            history.push(event);
+                    }
+                    return { session, nativeSessionId, history, configOptions: initial.configOptions };
+                }
+                catch (error) {
+                    console.warn(`[acp] session/load for '${nativeSessionId}' on agent '${spec.agentId}' failed ` +
+                        `(${errorMessage(error)}); starting a new session instead`);
+                    await session.close().catch(() => undefined);
+                }
+            }
+        }
+        const opened = await AcpSession.open(connection, { cwd: spec.cwd });
+        return { session: opened.session, nativeSessionId: opened.nativeSessionId, history: [], configOptions: opened.configOptions };
+    }
+    /**
+     * Fetch one agent's ACP adapter onto this machine, ahead of the first launch that would otherwise
+     * have to. What the settings page's **Config** button does before it writes anything.
+     *
+     * ## Why an explicit step exists at all
+     *
+     * `resolveLaunch` produces `npx --yes <adapter>@<version>`, and npx downloads the adapter the
+     * first time it runs one — which meant the very first `open` on a fresh machine paid for a
+     * multi-megabyte download inside a session the user had already started, with nothing on screen
+     * saying so. Doing it here moves that cost to a button press, and — because it is the same cache
+     * npx reads — makes the roster's `adapterInstalled` true afterwards. The uvx and binary paths
+     * install into `uv tool dir` and `<workstation config dir>/acp-adapters` respectively, which are
+     * likewise exactly where the roster and the launch path look.
+     *
+     * ## Three answers, and the third one is not a failure
+     *
+     * `ok` with `alreadyInstalled` means there was nothing to do. `ok` without it means this call
+     * downloaded it. `unsupported` means there is nothing for *this machine* to fetch — the entry
+     * declares no launchable distribution, or it is binary-only with no archive for this platform
+     * triple. Reported as its own outcome rather than as an error so the page can grey the card out
+     * instead of offering a retry that cannot succeed.
+     *
+     * All three distributions are fetched, not just npx — see {@link installAdapter}, which dispatches
+     * npx → uvx → binary in `resolveLaunch`'s own preference order.
+     *
+     * ## The catalog's `dependency` runs first, and can refuse to run anything at all
+     *
+     * `registry/catalog.ts` may curate one extra prerequisite for an agent (`pi-acp` needs the `pi`
+     * CLI) that the adapter fetch above does nothing to provide. That block is handled *before* the
+     * adapter step, in two gates:
+     *
+     * 1. `requiresNode`, checked against this daemon's own `process.version` (or the injected
+     *    `nodeVersion`, for tests) — because npm only *warns*, never refuses, on an `engines`
+     *    mismatch. On a Node-20 machine `npm install -g` for `pi` "succeeds", `findOnPath` then finds
+     *    the binary, and a check that stopped at presence-on-`PATH` would report the dependency
+     *    satisfied right before the agent fails at run time with an engines error nobody could trace
+     *    back to install. Failing this gate returns `nodeTooOld` and runs no command at all — not
+     *    even the `findOnPath` probe below, since there would be nothing useful to install anyway.
+     * 2. `check` on `PATH` (via `findOnPath`) — only when that comes back empty does this call the
+     *    catalog's literal `install` argv through {@link AcpAgents.runCommand}, which is
+     *    `execFile`-based and never a shell (see `catalog.ts`'s security note on that array).
+     *
+     * An agent outside the catalog, or one with no `dependency` block, skips straight to the adapter
+     * step below — nothing here changes for `claude-acp`, `codex-acp`, or any other uncurated agent.
+     *
+     * Never starts the agent: see {@link installNpxPackage}.
+     */
+    async install(agentId, options = {}) {
+        const dependency = catalogEntryFor(agentId)?.dependency;
+        if (dependency) {
+            const nodeVersion = options.nodeVersion ?? process.version;
+            if (dependency.requiresNode && !semver.satisfies(nodeVersion, dependency.requiresNode)) {
+                return {
+                    ok: false,
+                    error: `Agent '${agentId}' needs Node ${dependency.requiresNode}, but this daemon is running ` +
+                        `${nodeVersion}.`,
+                    nodeTooOld: { required: dependency.requiresNode, found: nodeVersion },
+                };
+            }
+        }
+        let dependencyInstalled;
+        if (dependency && findOnPath(dependency.check, this.probe) === undefined) {
+            const [command, ...args] = dependency.install;
+            const outcome = await this.runCommand(command, args, { timeoutMs: options.timeoutMs });
+            if (!outcome.ok) {
+                return { ok: false, error: outcome.error };
+            }
+            dependencyInstalled = true;
+        }
+        const agents = await this.registry.load();
+        const agent = agents.find((candidate) => candidate.id === agentId);
+        if (!agent) {
+            return { ok: false, error: `Agent '${agentId}' is not in the ACP agent registry.` };
+        }
+        const outcome = await this.installAdapter(agent, options.timeoutMs);
+        if (!outcome.ok)
+            return outcome;
+        return {
+            ok: true,
+            adapterInstalled: true,
+            alreadyInstalled: outcome.alreadyInstalled,
+            ...(dependencyInstalled ? { dependencyInstalled } : {}),
+            ...(outcome.pinnedVersionUnavailable ? { pinnedVersionUnavailable: outcome.pinnedVersionUnavailable } : {}),
+        };
+    }
+    /**
+     * Fetch one agent's ACP adapter through **whichever distribution it actually ships**, dispatching
+     * npx → uvx → binary: the same preference order `resolveLaunch` uses to decide which one will be
+     * launched, so `Install` always fetches the thing that will later be started.
+     *
+     * ## Why this exists
+     *
+     * {@link install} used to refuse anything without an `npx` block outright, which made
+     * `installBinary` (`binaryInstall.ts`) and `installUvTool` (`uvxInstall.ts`) unreachable from
+     * production: they were written, tested, and called by nothing. On the live registry snapshot that
+     * is 18 of 39 agents — 16 binary-only and 2 uvx-only — every one of them rendering an `Install`
+     * button whose task could only ever fail. Design §4.1's "three distributions, one model" is this
+     * function.
+     *
+     * ## `unsupported` still exists, and now means something narrower
+     *
+     * Two cases, and neither of them is "this build has not got round to it yet":
+     *
+     * - the registry entry declares no launchable distribution at all, so there is nothing to fetch;
+     * - the entry is binary-only and publishes no archive for **this machine's** platform triple —
+     *   `windows-aarch64` covers 9 of 18 binary entries (see `binaryInstall.ts`'s module doc). Checked
+     *   here rather than left to `installBinary`'s own identical check so the answer carries
+     *   `unsupported`, which is what a card renders as `Unsupported` instead of a retryable error.
+     *
+     * Every other failure is an ordinary `error` the reader can retry.
+     *
+     * `checksumVerified` from the binary path is deliberately not propagated into
+     * {@link AcpInstallResult}: a registry entry with no `sha256` (`antigravity-acp`, `cursor`)
+     * installs successfully and this result must not imply either that it was verified or that
+     * anything went wrong. `binaryInstall.ts` logs the fact where it is established.
+     */
+    async installAdapter(agent, timeoutMs) {
+        const { npx, uvx, binary } = agent.distribution;
+        if (npx) {
+            return this.installNpxWithFallback(agent, npx.package, timeoutMs);
+        }
+        if (uvx) {
+            // `uv tool install <pkg>==<ver>`, not `uvx <pkg>`: the launch path reads the entry point out
+            // of `uv tool dir`, so this has to populate that same place (design §4.2).
+            const outcome = await (this.runUv ? installUvTool(uvx.package, this.runUv) : installUvTool(uvx.package));
+            if (outcome.ok)
+                return { ok: true, alreadyInstalled: outcome.alreadyInstalled };
+            // What's already on disk, read fresh at the moment of failure -- never the version this call
+            // just tried to fetch, and never assumed: `installUvTool` resolves before touching the
+            // environment (measured: a bad pin's resolution failure leaves whatever was already `uv tool
+            // install`ed running, untouched), so whatever `uv tool list` reports right now is exactly what
+            // survived this attempt.
+            const existingVersion = await uvToolVersion(uvPackageName(uvx.package), this.runUv);
+            logInstallFailureDetail(agent.id, 'uvx', uvx.package, outcome.error);
+            return { ok: false, error: friendlyOrdinaryInstallError(agent.id, outcome.error, existingVersion) };
+        }
+        if (binary) {
+            const triple = platformTriple(this.platform, this.arch);
+            if (!triple || !binaryTargetFor(agent, triple)) {
+                return {
+                    ok: false,
+                    unsupported: true,
+                    error: `Agent '${agent.id}' publishes no archive for ${triple ?? `${this.platform}-${this.arch}`}.`,
+                };
+            }
+            const outcome = await installBinary(agent, {
+                root: this.adapterRoot,
+                platform: this.platform,
+                arch: this.arch,
+            });
+            if (outcome.ok)
+                return { ok: true, alreadyInstalled: outcome.alreadyInstalled };
+            // Same "read what's actually there, right now" rule as the uvx branch above: `installBinary`
+            // never touches a sibling version directory on failure (it only ever removes the *new*
+            // version's own, half-written one -- see that function's own doc), so this reads whichever
+            // version, if any, survived the attempt untouched.
+            const existingVersion = installedBinaryVersion(agent.id, this.adapterRoot);
+            logInstallFailureDetail(agent.id, 'binary', agent.version, outcome.error);
+            return { ok: false, error: friendlyOrdinaryInstallError(agent.id, outcome.error, existingVersion) };
+        }
+        return {
+            ok: false,
+            unsupported: true,
+            error: `Agent '${agent.id}' declares no launchable distribution, so there is no adapter to install.`,
+        };
+    }
+    /**
+     * `installNpxPackage` for the registry-pinned specifier and, when — and only when — that failure
+     * is npm's own `ETARGET`, one retry with the pin stripped. The install-time sibling of
+     * {@link connectResolved}, which does the same thing for a launch that is already running; see its
+     * doc comment for why the condition is ETARGET specifically and why the retry happens at most once.
+     *
+     * ## Why `Install`/`Update` needed this and `connectResolved` alone was not enough
+     *
+     * The launch-time fallback only ever fires *after* an `Install` has already put something usable
+     * on disk — it exists to recover a session that is about to open, not to get the adapter onto the
+     * machine in the first place. Before this method, a registry entry pinned to an npm version that
+     * does not exist failed here, at `Install`/`Update`, every single time, and never got anywhere
+     * near `connectResolved`: the card offered a button whose task could only ever fail, worse than
+     * the launch-time defect it was fixed for.
+     */
+    async installNpxWithFallback(agent, pinnedSpec, timeoutMs) {
+        const outcome = await installNpxPackage(pinnedSpec, {
+            env: this.probe,
+            timeoutMs: timeoutMs ?? ADAPTER_INSTALL_TIMEOUT_MS,
+            npxCommand: this.npxCommand,
+        });
+        if (outcome.ok)
+            return { ok: true, alreadyInstalled: outcome.alreadyInstalled };
+        // What (if anything) of this package is already on disk, read *before* any fallback runs --
+        // `installNpxPackage`'s own failure never touches an existing npx cache entry (measured: `npm
+        // exec --package=` only ever adds to the cache), so this is a fact about what survives this
+        // attempt no matter which branch below is taken.
+        const existingVersion = npxCacheVersion(npmPackageName(pinnedSpec), readNpxCache(this.probe));
+        const fallback = unpinnedFallbackFor(agent, this.platform);
+        if (!fallback || !stderrShowsMissingPackageVersion(outcome.stderr)) {
+            logInstallFailureDetail(agent.id, 'npx', pinnedSpec, outcome.stderr || outcome.error);
+            return {
+                ok: false,
+                error: friendlyOrdinaryInstallError(agent.id, outcome.stderr || outcome.error, existingVersion),
+            };
+        }
+        // 两条都是 warn,而且都要能被一个月后读日志的人看懂——他不知道今晚发生了什么,只看得见这两行。
+        // 措辞跟 `connectResolved` 里那两条故意保持一致,只把"启动"换成"安装"。
+        console.warn(`[acp] agent '${agent.id}' could not be installed at the version the ACP registry pins ` +
+            `('${fallback.pinned}'): npm has no published version matching it (npm error code ` +
+            'ETARGET). This is a bad entry published upstream, not a broken install on this machine.');
+        console.warn(`[acp] retrying the install for agent '${agent.id}' once as '${fallback.unpinned}', with the ` +
+            "version pin removed, so npm resolves whatever it currently calls 'latest'. That is " +
+            'deliberately NOT the version the registry asked for: if this agent then misbehaves, ' +
+            'suspect the version before suspecting the agent.');
+        const retryOutcome = await installNpxPackage(fallback.unpinned, {
+            env: this.probe,
+            timeoutMs: timeoutMs ?? ADAPTER_INSTALL_TIMEOUT_MS,
+            npxCommand: this.npxCommand,
+        });
+        if (!retryOutcome.ok) {
+            // 不钉版本那次再失败,抛出去的是把两件事都说清楚的一句话:registry 钉的版本不存在,而且
+            // 绕过去的那次尝试自己也没成 —— 而不是原来那条已经绕过去的 ETARGET。
+            logInstallFailureDetail(agent.id, 'npx', fallback.unpinned, retryOutcome.stderr || retryOutcome.error);
+            return {
+                ok: false,
+                error: friendlyPinnedVersionUnavailableAndFallbackFailed(agent.id, fallback.pinned, retryOutcome.stderr || retryOutcome.error, existingVersion),
+            };
+        }
+        // The fallback succeeded: this machine now has *some* version of the adapter, but never the one
+        // the registry actually pins -- npm does not have it, so `Update` could offer to fetch it again
+        // forever and never converge. Reading the version back off the cache (rather than trusting
+        // `fallback.unpinned`'s own unversioned specifier) is what lets the caller persist a concrete
+        // fact ("Y is installed") instead of a vague "not the pinned one".
+        const installedInstead = npxCacheVersion(fallback.unpinned, readNpxCache(this.probe));
+        return {
+            ok: true,
+            alreadyInstalled: retryOutcome.alreadyInstalled,
+            ...(installedInstead ? { pinnedVersionUnavailable: { pinned: fallback.pinned, installedInstead } } : {}),
+        };
+    }
+    /**
+     * Whether the catalog's extra prerequisite for this agent (`registry/catalog.ts`'s `dependency`)
+     * is already on `PATH` — never whether the adapter itself has been fetched, and never whether
+     * this daemon's Node satisfies `requiresNode` (that gate only matters at {@link install} time, not
+     * for reporting what is already on the machine). An agent outside the catalog, or one with no
+     * `dependency` block, needs nothing extra and reads as satisfied.
+     *
+     * {@link roster} folds this into `adapterInstalled`: an agent whose adapter is on disk but whose
+     * curated prerequisite is not reports **not installed**, so its card offers `Install` (which
+     * fetches the dependency) instead of an `Add` whose try-run was always going to fail on
+     * `Could not start pi: executable not found`. Design §4.4, point 2.
+     */
+    dependencySatisfied(agentId, probe = this.probe) {
+        const dependency = catalogEntryFor(agentId)?.dependency;
+        if (!dependency)
+            return true;
+        return findOnPath(dependency.check, probe) !== undefined;
+    }
+    /** A config-supplied `command` is the whole launch spec (ruling R3); otherwise the registry decides. */
+    async resolveLaunchFor(agentId, command, args) {
+        // 裁决 R3 的覆盖没有回退可言:用户自己写下的命令行就是**全部**,这里不该去猜他们的哪一段
+        // 参数是版本号。
+        if (command)
+            return { launch: { command, args, env: {} } };
+        const agents = await this.registry.load();
+        const agent = agents.find((candidate) => candidate.id === agentId);
+        if (!agent) {
+            throw new Error(`Agent '${agentId}' is not in the ACP agent registry. Check the id, refresh the registry, ` +
+                'or give this agent an explicit command in the workstation config.');
+        }
+        // 每次启动都从刚读到的 registry 现算一遍,没有任何一处把回退记下来:上游把版本修好的那一刻,
+        // 钉版本的那条路自己就恢复了,不需要谁去清什么状态。
+        return {
+            launch: await resolveLaunch(agent, this.platform, this.arch, this.adapterRoot),
+            fallback: unpinnedFallbackFor(agent, this.platform),
+        };
+    }
+    /**
+     * Connect a launch that is not a login — every connection this class makes except
+     * {@link connectFor}'s login one — with {@link withUnpinnedFallback}'s ETARGET retry around it.
+     *
+     * **`options` is {@link ConnectAgentOptions}, whose `present` is `never`**, and that is the whole
+     * point of this method still existing as a separate one: the stderr sniffer cannot be armed
+     * through the route {@link open} and {@link listNativeSessions} take. It used to take a second
+     * `login` parameter for `connectFor`'s benefit, which meant the same door stood open one argument
+     * further along; `connectFor` builds its own options now.
+     */
+    async connectResolved(agentId, resolved, env, agentEnv, options = {}) {
+        return withUnpinnedFallback(agentId, resolved, (launch) => connectAgent(launch, env, agentEnv, options));
+    }
+    /**
+     * Whether `resolveLaunch` can produce a spec for this agent on this machine (see {@link roster}).
+     *
+     * `uvTools` is {@link roster}'s single hoisted `uv tool list` snapshot, passed straight through to
+     * `resolveLaunch`'s uvx branch. Without it, `resolveLaunch` falls back to reading `uv tool list`
+     * itself via its default runner — a real `uv` subprocess per uvx-distributed agent, called from
+     * inside `roster()`'s per-agent map, which is exactly the per-agent-spawn defect `adapterVersionFor`
+     * was hoisted out of. This is the second call site that same invariant covers: building the roster
+     * must start nothing per agent, no matter how many code paths ask "is this agent launchable".
+     *
+     * `resolveLaunch` itself is `async` now (`uv` is a non-blocking call — see `uvxInstall.ts`'s
+     * `RunUv`), so this awaits it; with `uvTools` always supplied here, that branch never actually
+     * waits on anything; it resolves off the already-hoisted snapshot exactly as synchronously as
+     * before, just wrapped in a settled `Promise`.
+     */
+    async resolvable(agent, uvTools) {
+        try {
+            await resolveLaunch(agent, this.platform, this.arch, this.adapterRoot, undefined, uvTools);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Run `attempt` on the launch the registry pins, and — only when npm answers ETARGET — once more on
+ * the unpinned fallback.
+ *
+ * Extracted from `connectResolved` so that the login path can reuse the retry **without** reusing
+ * `connectResolved`'s options parameter, which is typed to forbid `present`. Both callers get the
+ * same retry and the same two log lines; only one of them can arm the stderr sniffer, and it says so
+ * in its own signature rather than by passing an extra argument the other caller could also pass.
+ *
+ * ## Only on ETARGET, and only once
+ *
+ * 只在 npm 自己说「这个版本不存在」时重试。一次冷启动要几十秒(npx 得先把适配器下下来),所以
+ * 「失败就重试」等于把每一次真实故障的代价翻倍。这里认的是 npm 打在子进程 stderr 上的错误码,见
+ * `acpClient.ts` 的 `isMissingPackageVersion` —— 那是证据;从一根断掉的管子倒推「大概是版本不对吧」
+ * 是猜测,两者在日志里长得一样,后果不一样。
+ *
+ * 不钉版本那次再失败,抛出去的就是**它自己**的错误。把原来的 ETARGET 报上去会让读日志的人接着去
+ * 追一个已经绕过去的问题。
+ */
+async function withUnpinnedFallback(agentId, resolved, attempt) {
+    try {
+        return await attempt(resolved.launch);
+    }
+    catch (error) {
+        const fallback = resolved.fallback;
+        if (!fallback || !isMissingPackageVersion(error))
+            throw error;
+        // 两条都是 warn,而且都要能被一个月后读日志的人看懂 —— 他不知道今晚发生了什么,只看得见这两行。
+        console.warn(`[acp] agent '${agentId}' could not be launched at the version the ACP registry pins ` +
+            `('${fallback.pinned}'): npm has no published version matching it (npm error code ` +
+            'ETARGET). This is a bad entry published upstream, not a broken install on this machine.');
+        console.warn(`[acp] retrying agent '${agentId}' once as '${fallback.unpinned}', with the version pin ` +
+            "removed, so npm resolves whatever it currently calls 'latest'. That is deliberately NOT " +
+            'the version the registry asked for: if this agent now misbehaves, suspect the version ' +
+            'before suspecting the agent.');
+        return await attempt(fallback.launch);
+    }
+}
+/**
+ * Wrap one `AcpSession` plus the connection it runs on into the shape the manager holds.
+ *
+ * Two behaviours are added on top of `AcpSession`. Lifetime: `close()` must end the subprocess as
+ * well as the session, or `agent_close` would leave a live agent behind holding its cwd and its
+ * quota. `backfill` is attached only when there is history to replay, because its *absence* is what
+ * the manager reads as "nothing to replay". And the config option snapshot: {@link
+ * AcpAgentSession.configOptions} must answer with the **latest** one, not the one this session
+ * opened with, so the cell below is what `setConfigOption` writes back into and what the getter
+ * reads — see that field's own doc for what a stale answer costs on every reconnect.
+ */
+function hostedSession(session, connection, history, configOptions) {
+    // `AcpSession` keeps a cell of its own for the same value, but does not expose it — and the two
+    // are written from the same place (the wrapper below is the only caller of its setter), so this
+    // one cannot drift from it.
+    let snapshot = configOptions;
+    const hosted = {
+        // Verbatim. This used to be the one place a string became a `ContentBlock[]`
+        // (`session.prompt([{ type: 'text', text }])`) — a stopgap for as long as `agent_prompt` could
+        // only carry text. That seam is gone: the frame now carries blocks, so wrapping here would be a
+        // second, narrower opinion about the shape of a user message.
+        prompt: (blocks) => session.prompt(blocks),
+        // Both halves come off the live agent: the process's own exit state, and the session's own
+        // outstanding-prompt list. Nothing here is remembered by this daemon.
+        get liveness() {
+            return {
+                agentAlive: connection.agentProcessAlive() && session.readable,
+                turnRunning: session.turnRunning,
+            };
+        },
+        answer: (requestId, outcome) => session.answer(requestId, outcome),
+        interrupt: () => session.interrupt(),
+        setConfigOption: async (configId, value) => {
+            snapshot = await session.setConfigOption(configId, value);
+            return snapshot;
+        },
+        get configOptions() {
+            return snapshot;
+        },
+        steer: (blocks, priority) => session.steer(blocks, priority),
+        // Straight off the connection that opened this session — never inferred, and never read back
+        // from the roster, whose entry for this agent may still be the pre-connection one.
+        supportsSteering: connection.supportsSteering,
+        // Same source, same rule, and likewise never defaulted: an empty list here is the agent saying
+        // nothing about *when*, which ruling N4 reads as "the server may not name a timing".
+        steeringTimings: connection.steeringTimings,
+        agentInfo: connection.agentInfo,
+        supportsImageInput: connection.capabilities.promptImage,
+        onEvent: (cb) => session.onEvent(cb),
+        onTurnDone: (cb) => session.onTurnDone(cb),
+        async close() {
+            try {
+                await session.close();
+            }
+            finally {
+                // Runs even if the session's own shutdown threw: the subprocess is the expensive thing to
+                // leak, and nothing else in the daemon will come back for it.
+                await connection.close().catch(() => undefined);
+            }
+        },
+    };
+    if (history.length > 0) {
+        hosted.backfill = async function* backfill() {
+            for (const event of history)
+                yield event;
+        };
+    }
+    return hosted;
+}