@platless/axom-cli 0.1.0 → 0.5.9

package/dist/workstation/acp/acpAgents.js

@@ -1,18 +1,78 @@
+import { homedir } from 'node:os';
+/**
+ * The daemon's single entry point into ACP — what `agentSessions.ts` holds where it used to hold a
+ * `Map<string, AgentBridge>`.
+ *
+ * ## What replaced what
+ *
+ * The deleted bridge SPI dispatched on a *bridge type* (`claude-code` | `codex` | `acp`) to one of
+ * several implementations. There is only one implementation now, so there is nothing to dispatch to:
+ * ruling R1 deleted the interface rather than leaving an extension point with a single member. What
+ * varies per agent is no longer code but **data** — the launch spec — so the key is a **registry
+ * agent id** (`claude-acp`, `codex-acp`, …) and this class turns that id into a running subprocess
+ * by way of the ACP agent registry (`registry/`) and a processor-driven session (`processorSession.ts`, over keeper-acp or the
+ * local transport); `connectAgent` (`acpClient.ts`) serves the short-lived connections (list, delete, verify, sign-in).
+ *
+ * ## One connection per session, deliberately
+ *
+ * Every {@link AcpAgents.open} spawns its own agent subprocess and its own `AcpConnection`, and
+ * {@link AcpAgentSession.close} tears both down together. Pooling one connection across sessions
+ * would be cheaper and is exactly what `permission.ts`'s `PermissionSink` doc comment warns against:
+ * `registerPermissionHandlers` binds one sink per connection with no per-session routing, so two
+ * sessions sharing a connection would cross-deliver permission cards, and `createDeferredPermissionSink`
+ * would throw on the second `bind()`. The one-subprocess-per-session shape is also what the deleted
+ * bridges had, so nothing downstream had to change.
+ *
+ * ## Config overrides beat the registry (ruling R3)
+ *
+ * A workstation's agent config block may carry `command`/`args`. When it does, that is the whole
+ * launch spec — the registry is not consulted at all, and no registry-supplied `env` is merged in.
+ * This is the escape hatch for an agent that is not in the registry, a locally built adapter, or a
+ * wrapper script; it is also what lets this module's own tests drive a real ACP subprocess without
+ * reaching the network or running `npx`.
+ */
+import { RequestError } from '@agentclientprotocol/sdk';
+import { certifiedRuntime } from '../qoderAdapter/foregroundOutput.js';
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
 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 { connectAgent, jsonRpcErrorCode, stderrShowsMissingPackageVersion } from './acpClient.js';
+import { launchForTerminalLogin, runTerminalLogin, terminalInvocationFor } from './terminalLogin.js';
+import { createCommandTableProbe } from './commandTableProbe.js';
+import { deleteNativeSessions, listNativeSessions } 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 { binaryTargetFor, installBinary, platformTriple } from './binaryInstall.js';
+import { binaryBuild } from './builds/install/binary.js';
+import { defaultNpmCommand, ensurePristine, npmBuild } from './builds/install/npm.js';
+import { installUvBuild } from './builds/install/uv.js';
+import { adoptNpxCopy, findNpxCopy, legacyBinaryVersions, moveLegacyBinary, RESERVED_ROOT_NAMES } from './builds/migrate.js';
+import { AdapterNotInstalledError, AdapterStillInstallingError, binaryBuildDir, npmPristineDir, inside } from './builds/model.js';
+import { AdapterNodeVersionError } from './builds/nodeGate.js';
+import { buildKey as buildKeyOf, collectBuilds, collectLegacy, processCommandLines } from './builds/gc.js';
+import { keyGenOf, refOfSession, resolveSuperseded, restoreConfigOptions, sessionKeyFor, SWITCH_ABANDONED_NOTE, SWITCH_SUSPEND_TIMEOUT_MS, } from './switching.js';
+import { decodeCheckpoint } from './processor/checkpoint.js';
+import { BuildStore } from './builds/store.js';
+import { selectPackagePatches, patchDigest } from './managedPatches.js';
+import { nativeExtensionFor, nativeAccountLimitsVersionFor } from './patchAssets.js';
+import { ACCOUNT_LIMITS_READ_TIMEOUT_MS } from '../protocol/accountLimits.js';
+import { buildSessionMcpServers } from './delegationMcp.js';
+import { overlayEnvSecrets } from './envSecrets.js';
+import { AdoptionRefusedError, ProcessorSession } from './processorSession.js';
+import { hostsRunningAdapter } from './processor/transport/generations.js';
+import { isOutboxTail } from './outbox.js';
+import { LocalTransport } from './processor/transport/local.js';
+import { AcpKeeperUnavailableError } from '../keepers/acp/client.js';
+import { prepareQoderStartup, QODER_MANAGED_VERSION } from './qoderStartup.js';
+import { friendlyOrdinaryInstallError, friendlyPinnedVersionUnavailableAndFallbackFailed, friendlyUvMissingError, logInstallFailureDetail, } from './installErrors.js';
+import { ADAPTER_INSTALL_TIMEOUT_MS, npmCacheDir, npmPackageName, npmPackageVersion, pickInstalledVersion, findOnPath, probeEnvironment, runDependencyInstall, } from './installProbe.js';
 import { createDeferredPermissionSink, registerPermissionHandlers } from './permission.js';
-import { catalogEntryFor } from './registry/catalog.js';
-import { resolveLaunch, unpinnedFallbackFor } from './registry/launch.js';
+import { catalogEntryFor, catalogLaunchEnv, effectiveEntries, RECOMMENDED_RANK, withCatalogOverrides } from './registry/catalog.js';
+import { detected } from './registry/detect.js';
+import { launchForBuild, withPathPrefix } from './registry/launch.js';
 import { RegistryClient } from './registry/registryClient.js';
-import { installUvTool, listUvTools, uvPackageName, uvToolVersion } from './uvxInstall.js';
+import { defaultRunUv, parseUvxSpec, UV_TOOL_INSTALL_TIMEOUT_MS } from './uvxInstall.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -44,8 +104,8 @@ function errorMessage(error) {
  */
 export class AgentRefusedSessionError extends Error {
     errorCode;
-    constructor(cause) {
-        super(errorMessage(cause), { cause });
+    constructor(cause, publicMessage) {
+        super(publicMessage ?? errorMessage(cause), publicMessage === undefined ? { cause } : undefined);
         this.name = 'AgentRefusedSessionError';
         this.errorCode = jsonRpcErrorCode(cause);
     }
@@ -184,9 +244,11 @@ export function createLoginUrlSink(login) {
 /** A verification or authentication ran past {@link AGENT_PROBE_TIMEOUT_MS}. */
 export class AgentProbeTimeoutError extends Error {
 }
+/** A real session stopped answering after initialize; closing its transport reaps the child. */
+export class AgentSessionStartTimeoutError extends Error {
+}
 /**
- * Reject with {@link AgentProbeTimeoutError} once `timeoutMs` has passed, whatever `work` is still
- * doing.
+ * Reject with the specified timeout error 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
@@ -194,10 +256,10 @@ export class AgentProbeTimeoutError extends Error {
  * 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) {
+async function withDeadline(work, timeoutMs, what, timeoutError = AgentProbeTimeoutError) {
     let timer;
     const deadline = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new AgentProbeTimeoutError(`${what} did not finish within ${timeoutMs}ms.`)), timeoutMs);
+        timer = setTimeout(() => reject(new timeoutError(`${what} did not finish within ${timeoutMs}ms.`)), timeoutMs);
     });
     deadline.catch(() => { });
     try {
@@ -212,7 +274,7 @@ async function withDeadline(work, timeoutMs, what) {
  * 等**第一条** `available_commands_update` 的窗口。一条都没等到就收工,`observed` 保持 undefined
  * ——按「缺席 ≠ 空表」的约定,服务端据此不写命令表那一半(见 {@link verify} 的 KDoc)。
  *
- * 数值沿用原来那个固定 settle 窗口(`docs/superpowers/notes/2026-08-31-codex-command-table-race.md`)。
+ * 数值沿用原来那个固定 settle 窗口(`archived/docs/superpowers/notes/2026-08-31-codex-command-table-race.md`)。
  * **没有证据支持把它调大**:真机上量到同一个 agent 在一台机器上回 72 条、在另一台回 0 条,但那两次
  * 的耗时差(8.4s vs 2.1s)完全可能全部落在 spawn/connect 上,而不是广播来晚了。要区分这两件事,
  * 得先有 {@link verify} 里那条「没等到表」的日志,不是先改这个数字。
@@ -232,6 +294,13 @@ const COMMAND_QUIET_MS = 750;
  * 必须显著小于 {@link AGENT_PROBE_TIMEOUT_MS} —— 连接和 `session/new` 还要在这之前各花一段。
  */
 const COMMAND_SETTLE_CEILING_MS = 5_000;
+/**
+ * p3-fix7 N9: a verification whose first opening saw no command table opens one more session and waits this long for
+ * the first broadcast. "Nothing seen" is not an observation: the dispatch planner reads "offers
+ * superpowers:brainstorming" off this table, and a missed table can flip a project to native. Kept well inside
+ * {@link AGENT_PROBE_TIMEOUT_MS} with the first attempt's window and two session openings.
+ */
+const COMMAND_RETRY_FIRST_BROADCAST_MS = 4_000;
 /** ACP 的 `AvailableCommand` → 隧道形状:`input.hint` 拍平成 `inputHint`。 */
 function toAvailableCommandWire(raw) {
     const command = raw;
@@ -250,42 +319,49 @@ function toAvailableCommandWire(raw) {
  * others — `verify` and `listNativeSessions` are exactly the paths a settings page depends on, and
  * they are the ones nobody remembers.
  */
+/** The same observation, off the processor's `initialize` reading (a live session's). */
+function observationOfFacts(facts) {
+    return {
+        authMethods: facts.authMethods,
+        supportsAccountLimits: facts.supportsAccountLimits,
+        supportsSteering: facts.supportsSteering,
+        terminalLogins: new Map(facts.terminalLogins),
+    };
+}
+/** keeper-acp's bound on a spawn spec's lists (`params.ts` MAX_LIST). */
+const ACP_STDERR_SECRETS_MAX = 256;
+/** A spawn spec's environment is complete (keeper-acp never reads its own): `process.env`'s unset entries dropped. */
+function completeEnvironment(env) {
+    const out = {};
+    for (const [key, value] of Object.entries(env))
+        if (typeof value === 'string')
+            out[key] = value;
+    return out;
+}
+/** `initialize` on a session open (`connectAgent`'s default, which the old path used). */
+const DEFAULT_SESSION_INITIALIZE_TIMEOUT_MS = 30_000;
 function observationOf(connection) {
-    return { authMethods: connection.authMethods, supportsSteering: connection.supportsSteering };
+    return {
+        authMethods: connection.authMethods,
+        supportsAccountLimits: connection.supportsAccountLimits,
+        supportsSteering: connection.supportsSteering,
+        terminalLogins: connection.terminalLogins,
+    };
 }
 /**
- * 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.
+ * The version a new session of an agent would run on this machine: its **current build**
+ * (`builds.json`, spec §6.4 — `adapterVersion` reports current), for every distribution, uv included
+ * (Task 15b). `undefined` is a genuine "not installed".
  */
-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;
+function adapterVersionFor(current) {
+    return current?.version;
 }
 /**
  * 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
+ * Install dispatches 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
@@ -304,34 +380,215 @@ function isUnsupportedPlatform(agent, platform, arch) {
     const triple = platformTriple(platform, arch);
     return !triple || !binaryTargetFor(agent, triple);
 }
+/** The version an entry asks npm for: its npx specifier's pin, else the entry's version. */
+function requestedVersionOf(entry) {
+    const npx = entry.agent.distribution.npx;
+    return (npx && npmPackageVersion(npx.package)) || entry.agent.version;
+}
+/**
+ * How long an open waits for an install it had to start (spec §6.2) before failing with
+ * {@link AdapterStillInstallingError}. The server gives a whole open `AGENT_CHANNEL_OPEN_TIMEOUT_MS`
+ * = 120 s (`AgentChannelSession.kt`); this leaves ~30 s for the spawn, `initialize` and
+ * `session/new|load` that follow, so the reader gets this actionable error instead of a generic
+ * "open timed out". The install itself is not bounded by this — it keeps running under the agent lock
+ * with its own install budget, and a retried open waits on that lock.
+ */
+export const OPEN_INSTALL_BUDGET_MS = 90_000;
+/** How long the resume offer waits for keeper-acp's session list (the offer goes out regardless). */
+const LEFTOVER_LIST_TIMEOUT_MS = 5_000;
+/** keeper-acp sessions rebuilt at once by the start-time adoption. */
+const ADOPT_CONCURRENCY = 8;
+/** The version installing `entry` asks for — what an open that has to install shows the user. */
+function installingVersionOf(entry) {
+    const { npx, uvx } = entry.agent.distribution;
+    if (npx)
+        return requestedVersionOf(entry);
+    return (uvx && parseUvxSpec(uvx.package).version) || entry.agent.version;
+}
+/** The registry could not be read for a migration: tried again by the next launch rather than given up on. */
+class RegistryUnavailableForMigration extends Error {
+}
+/** Pre-build binary agent directories directly under the `acp-adapters` root (`builds/migrate.ts`). */
+async function legacyAgentDirs(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.') && !RESERVED_ROOT_NAMES.has(entry.name)).map((entry) => entry.name);
+}
+/**
+ * {@link BridgeInfo.currentBuild}/`builds`/`switchPending` for one agent (spec §6.4): the current build (with its sessions, possibly
+ * none) and every build a live session runs. `listed` false (keeper-acp could not be listed): only `currentBuild`.
+ */
+export function rosterBuildFields(current, sessions, listed) {
+    const patchedBuild = (build) => build.kind === 'npm-patched' || build.patchDigest !== undefined;
+    const fields = {};
+    if (current)
+        fields.currentBuild = { id: current.buildId, version: current.version, ...(patchedBuild(current) ? { patched: true } : {}) };
+    if (!listed)
+        return fields;
+    const tallies = new Map();
+    const tally = (id, version, patched) => {
+        let entry = tallies.get(id);
+        if (!entry) {
+            entry = { id, version, patched, sessions: 0, idle: 0, busy: 0, unmovable: 0, busyReasons: new Set(), unmovableReasons: new Set() };
+            tallies.set(id, entry);
+        }
+        return entry;
+    };
+    if (current)
+        tally(current.buildId, current.version, patchedBuild(current));
+    const pendingTargets = [];
+    for (const session of sessions ?? []) {
+        const entry = tally(session.buildId, session.version, session.patched);
+        entry.sessions += 1;
+        entry[session.state] += 1;
+        const reasons = session.state === 'busy' ? entry.busyReasons : session.state === 'unmovable' ? entry.unmovableReasons : undefined;
+        for (const reason of session.reasons ?? [])
+            if (reasons && reasons.size < ROSTER_REASONS_MAX)
+                reasons.add(reason);
+        if (session.pendingTo !== undefined)
+            pendingTargets.push(session.pendingTo);
+    }
+    if (tallies.size === 0)
+        return fields;
+    // The current build first, then the rest by version (newest first), so a card reads the same on every scan.
+    const ordered = [...tallies.values()].sort((a, b) => (a.id === current?.buildId ? -1 : b.id === current?.buildId ? 1 : 0) || compareVersionsDesc(a.version, b.version) || a.id.localeCompare(b.id));
+    fields.builds = ordered.map((entry) => ({
+        id: entry.id, version: entry.version, ...(entry.patched ? { patched: true } : {}),
+        ...(entry.id === current?.buildId ? { current: true } : {}),
+        sessions: entry.sessions, idle: entry.idle, busy: entry.busy, unmovable: entry.unmovable,
+        ...(entry.busyReasons.size > 0 ? { busyReasons: [...entry.busyReasons] } : {}),
+        ...(entry.unmovableReasons.size > 0 ? { unmovableReasons: [...entry.unmovableReasons] } : {}),
+    }));
+    if (pendingTargets.length > 0) {
+        const first = pendingTargets[0];
+        fields.switchPending = { remaining: pendingTargets.length, ...(pendingTargets.every((target) => target === first) ? { toBuild: first } : {}) };
+    }
+    return fields;
+}
+function compareVersionsDesc(a, b) {
+    const va = semver.parse(a, { loose: true });
+    const vb = semver.parse(b, { loose: true });
+    return va && vb ? semver.rcompare(va, vb) : 0;
+}
+/** Why a local-fallback session is never moved (spec §6.3 "当前限制"): it does not outlive the daemon, so its next reopen uses current. */
+export const LOCAL_SESSION_UNMOVABLE = 'it is running without the session keeper; it will use the current build when reopened';
+/** At most this many distinct reasons per build entry (the card explains, it does not list every session). */
+const ROSTER_REASONS_MAX = 4;
 export class AcpAgents {
+    sessionStartTimeoutMs;
     registry;
     platform;
     arch;
     probe;
     runCommand;
     /**
-     * Where `binaryInstall.ts` unpacks binary-distributed adapters —
+     * The adapter builds root (`builds/model.ts` layout) —
      * `<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).
+     * itself lives in directly.
      */
     adapterRoot;
+    commandRetryFirstBroadcastMs;
     /** 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}. */
+    quotaReaders = new Map();
+    /** The `uv` uv builds are installed with; see {@link AcpAgentsOptions.runUv}. */
     runUv;
-    /** Injectable `npx` binary for {@link installAdapter}'s npx branch; see {@link AcpAgentsOptions.npxCommand}. */
-    npxCommand;
+    /** Injectable `npm` for adapter builds; see {@link AcpAgentsOptions.npmCommand}. */
+    npmCommand;
+    nodePath;
+    binaryFetch;
+    patchRecipes;
+    /** `builds.json` and the per-agent install/switch/GC lock (spec §6.1). */
+    builds;
+    /** The registry with catalog supplements but without overrides applied — {@link effectiveEntries} applies them, keeping launchEnv apart. */
+    baseRegistry;
+    /** {@link OPEN_INSTALL_BUDGET_MS}, overridable for tests. */
+    openInstallBudgetMs;
+    cacheDir;
+    transports;
+    generations;
+    /** The once-per-daemon adoption's discovery ({@link adoptKeeperSessions}). */
+    adoption;
+    /**
+     * keeper-acp generations whose listing failed (timed out, not answering) at the adoption or a retry since (final review finding 3):
+     * their sessions are neither adopted nor orphans yet — {@link retryKeeperAdoption} lists them again, no open spawns while one
+     * remains (a spawn into a session of it would stop its running adapter), and they are never retired meanwhile.
+     */
+    unlistedGens = new Set();
+    /** The retry in flight ({@link retryKeeperAdoption}). */
+    retrying;
+    leftoverListTimeoutMs;
+    /** Which keeper-acp generation holds a session key (discovery and leftover listings): its IPC goes there. */
+    keeperOwner = new Map();
+    /** The highest seq a keeper-acp session's outbox held when it was listed (the local fallback numbers above it, Task 21). */
+    keeperHeads = new Map();
+    /** Sessions this daemon holds (or is spawning) on an older generation, by key: that generation is never stopped meanwhile. */
+    heldOnOlder = new Map();
+    /** Refs whose session the manager is retiring to respawn it ({@link holdForReopen}): their older generation stays held. */
+    reopenHolds = new Set();
+    /** Keys this daemon spawned on keeper-acp: never adopted (they are its own). */
+    ownKeeperKeys = new Set();
+    initializeTimeoutMs;
+    /** One legacy migration per agent per process ({@link migrateAgent}); the daemon's start and any open share it. */
+    migrations = new Map();
+    /**
+     * Each ref's current keeper-acp key generation (Task 24): key `<ref>` (0) until a switch moves it to `<ref>#s<n>`. Learned from
+     * every listing (the spawn label's `keyGen` is the persisted record) and set by every switch; a ref absent here uses itself.
+     */
+    refKeys = new Map();
+    /**
+     * keeper-acp sessions whose adapter runs but which cannot be continued (spec §5.5.6: no readable checkpoint and raw truncated, or
+     * its open never completed), by key: left running, marked degraded, and switched at the ref's next `agent_open` — the process is
+     * closed and a new one loads the native session (never `session/new`).
+     */
+    unrecoverable = new Map();
+    /** Daemon leases on builds (opens resolving → spawning, switches, short-lived connections), `agentId\0buildId` → count (GC). */
+    leases = new Map();
+    /** When each build was last seen referenced (GC's 10-minute grace); unknown builds count from this daemon's start. */
+    buildSeen = new Map();
+    startedAt = Date.now();
+    /** Refs whose switch cannot happen (spec §6.4 `unmovable`), with why — until the session goes or its target changes. */
+    unmovableRefs = new Map();
+    /** The persistent intents (`builds.json` `switchPending`), read once and kept in step with every write. */
+    intents;
+    /** One GC at a time (a later one runs after it). */
+    collecting;
+    /** One {@link retireIdleGenerations} pass at a time, and whether another was asked for meanwhile. */
+    retiringGenerations;
+    retireAgain = false;
     constructor(options) {
-        this.registry = options.registry ?? new RegistryClient({ cacheDir: options.cacheDir });
+        this.sessionStartTimeoutMs = options.sessionStartTimeoutMs ?? 60_000;
+        if (!(this.sessionStartTimeoutMs > 0) || !Number.isFinite(this.sessionStartTimeoutMs)) {
+            throw new RangeError('sessionStartTimeoutMs must be finite and positive');
+        }
+        // Through the catalog, always: an injected registry too, so tests exercise the same overlay.
+        this.baseRegistry = options.registry ?? new RegistryClient({ cacheDir: options.cacheDir });
+        this.registry = withCatalogOverrides(this.baseRegistry);
         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.runUv = options.runUv ?? defaultRunUv;
+        this.nodePath = options.nodePath ?? process.execPath;
+        this.npmCommand = options.npmCommand ?? defaultNpmCommand(this.nodePath, this.platform);
+        this.binaryFetch = options.binaryFetch;
+        this.patchRecipes = options.patchRecipes;
+        this.commandRetryFirstBroadcastMs = options.commandRetryFirstBroadcastMs ?? COMMAND_RETRY_FIRST_BROADCAST_MS;
+        this.openInstallBudgetMs = options.openInstallBudgetMs ?? OPEN_INSTALL_BUDGET_MS;
         this.adapterRoot = path.join(options.cacheDir, 'acp-adapters');
+        this.builds = new BuildStore(this.adapterRoot);
+        this.cacheDir = options.cacheDir;
+        this.transports = { ...options.transports };
+        this.generations = options.keeperGenerations;
+        this.initializeTimeoutMs = options.initializeTimeoutMs ?? DEFAULT_SESSION_INITIALIZE_TIMEOUT_MS;
+        this.leftoverListTimeoutMs = options.leftoverListTimeoutMs ?? LEFTOVER_LIST_TIMEOUT_MS;
+        // Read once, up front: an `agent_open` asks for a ref's intent on its way to the reply (Task 24).
+        void this.loadIntents().catch(() => undefined);
     }
     /**
      * The roster reported in the `hello` frame and answered to an external-agents scan, one entry per
@@ -349,9 +606,15 @@ export class AcpAgents {
      * 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
+     * `curated` / `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.
+     * `recommended` is the catalog's own static flag (claude, codex, pi) and nothing else — it used to
+     * be spread for every catalog hit, which is what `curated` now says. `detected` is the catalog's
+     * local detection (`registry/detect.ts`): the agent itself, or its prerequisite, is on this machine
+     * the way the user installed it — a reason to recommend, never a claim that Axom installed it.
+     * `missingPrerequisite` names a prerequisite that is absent *and* that `install` cannot fetch, so
+     * the card can say what to do instead of offering an `Install` that can only refuse.
      *
      * 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.
@@ -362,7 +625,7 @@ export class AcpAgents {
      * 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() {
+    async roster(options = {}) {
         let agents;
         try {
             agents = await this.registry.load();
@@ -371,37 +634,39 @@ export class AcpAgents {
             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
+        // Read once for the whole roster, not once per agent: every npm/binary agent's installed version
+        // is its current build (spec §6.4).
+        const buildsDocument = await this.builds.read().catch((error) => {
+            console.warn(`[acp] adapter builds unreadable, reporting none installed: ${errorMessage(error)}`);
+            return { schema: 1, agents: {} };
+        });
+        // Since Task 15b uv agents are builds too: building the roster spawns no `uv` (and nothing else).
+        // Hoisted for the same reason as `buildsDocument`: 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) => {
+        // Spec §6.4: the build data is joined only for a scan (`options.sessions`) — never the hello — and only when every keeper-acp
+        // generation could be listed (`undefined`: absent, "not looked at").
+        const running = options.sessions ? await this.classifiedRunningSessions(options.sessions) : undefined;
+        return agents.map((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);
+            const current = this.builds.currentIn(buildsDocument, agent.id);
+            const adapterVersion = adapterVersionFor(current);
+            // One detection pass per agent, shared by `adapterInstalled`, `detected` and
+            // `missingPrerequisite`: three readings of the same look at the disk must not disagree.
+            const prerequisite = catalog?.prerequisite;
+            const prerequisiteMet = !prerequisite || detected(prerequisite.detect, this.probe, triple);
+            const inUse = detected(catalog?.detect, this.probe, triple) || (prerequisite !== undefined && prerequisiteMet);
+            // A `pathLaunch` agent has no installable artifact: its `available` is exactly "the body is on
+            // this machine" (see `registry/catalog.ts`). No build will ever exist for it, so the build
+            // halves below stay honestly absent.
+            const pathLaunchAvailable = catalog?.pathLaunch !== undefined && inUse;
             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),
+                available: this.resolvable(agent, current) || pathLaunchAvailable,
                 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.
@@ -415,19 +680,18 @@ export class AcpAgents {
                 // 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.
+                // here.
                 //
-                // 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.
+                // Since spec 2026-10-11 §6.4 "installed" means the agent has a **current build** (npm, binary
+                // and — since Task 15b — uv), and `adapterVersion`
+                // is that build's version — the version a new session would actually run.
                 //
-                // `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),
+                // `prerequisiteMet` folds in the catalog's prerequisite (design §4.4): `pi-acp`'s adapter
+                // installed 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
+                // prerequisite too (or, with nothing to fetch, `missingPrerequisite` below explain it).
+                adapterInstalled: adapterVersion !== undefined && prerequisiteMet,
                 // 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.
@@ -442,7 +706,11 @@ export class AcpAgents {
                 // 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)
+                // A `pathLaunch` agent has no distribution to be "unsupported" about: its launch path is the
+                // machine's own installation (detect-driven, above), not a downloadable artifact's platform
+                // coverage — the empty-distribution supplement would otherwise read as "nothing left to
+                // launch through".
+                ...(!pathLaunchAvailable && 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
@@ -452,10 +720,30 @@ export class AcpAgents {
                 // 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 } : {}),
+                // Spread from `registry/catalog.ts` only for a catalog hit — `curated`, `recommended` and
+                // `detected` have no `false`, the same "absent means unknown/no" rule as `supportsSteering`.
+                // An `unverified` entry keeps its defaults but is not one Axom vouches for (see `catalog.ts`).
+                ...(catalog ? { ...(catalog.unverified ? {} : { curated: true }), defaultName: catalog.defaultName } : {}),
                 ...(catalog?.defaultLabel ? { defaultLabel: catalog.defaultLabel } : {}),
+                ...(catalog?.recommended ? { recommended: true } : {}),
+                // 静态推荐条目的展示序（目录数组序）：推荐层按它排，使目录能表达 "pi 第一、hermes 第二"
+                // 这类顺序意图 —— 名册序做不到（supplement 追加在后），字母序与本意相反。
+                ...(RECOMMENDED_RANK.has(agent.id) ? { recommendedRank: RECOMMENDED_RANK.get(agent.id) } : {}),
+                ...(catalog?.pathLaunch
+                    ? {
+                        pathLaunch: {
+                            command: catalog.pathLaunch.command,
+                            ...(catalog.pathLaunch.args ? { args: [...catalog.pathLaunch.args] } : {}),
+                            ...(catalog.pathLaunch.hint ? { hint: catalog.pathLaunch.hint } : {}),
+                        },
+                    }
+                    : {}),
+                ...(inUse ? { detected: true } : {}),
+                // Only when nothing here can fix it: a prerequisite with an `install` argv (Pi) is fetched by
+                // `Install`, which the card already offers because `adapterInstalled` is false.
+                ...(prerequisite && !prerequisiteMet && !prerequisite.install
+                    ? { missingPrerequisite: { label: prerequisite.label, ...(prerequisite.hint ? { hint: prerequisite.hint } : {}) } }
+                    : {}),
                 // 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.
@@ -465,8 +753,121 @@ export class AcpAgents {
                 // 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 } : {}),
+                // The installed native extension is known without spawning a process or reading quota.
+                // A pre-upgrade live session's initialize observation must not hide its refresh entry.
+                ...(observation?.supportsAccountLimits || (current && current.launch.runtime !== 'node' && nativeExtensionFor(current.agentId, current.version)) ? { supportsAccountLimits: true } : {}),
+                ...(options.sessions ? rosterBuildFields(current, running?.get(agent.id), running !== undefined) : {}),
             };
-        }));
+        });
+    }
+    /**
+     * The live sessions' builds joined with the manager's view of each (Task 25), grouped by agent; `undefined` when a keeper-acp
+     * generation could not be listed (the counts would be wrong, so none are reported).
+     */
+    async classifiedRunningSessions(classify) {
+        const running = await this.runningSessions();
+        if (!running)
+            return undefined;
+        const byAgent = new Map();
+        for (const session of running) {
+            const state = session.local
+                ? { state: 'unmovable', reasons: [LOCAL_SESSION_UNMOVABLE] }
+                : await classify(session).catch((error) => {
+                    console.warn(`[acp] roster: the state of ${session.sessionRef} could not be read: ${errorMessage(error)}`);
+                    return { state: 'busy', reasons: ['its state could not be read right now'] };
+                });
+            const list = byAgent.get(session.agentId) ?? [];
+            list.push({ ...session, ...state });
+            byAgent.set(session.agentId, list);
+        }
+        return byAgent;
+    }
+    /**
+     * Every live session's adapter process with its build (spec §6.4, Task 25): keeper-acp's process labels across every live
+     * generation, plus the local fallback's. One entry per ref (a ref a crash left with two keys is counted once, by its newest key).
+     * `undefined` when keeper-acp — any generation — cannot be listed.
+     */
+    async runningSessions() {
+        const listed = await this.listRunningAdapters();
+        if (!listed)
+            return undefined;
+        const byRef = new Map();
+        for (const { summary, local } of listed) {
+            const ref = refOfSession(summary);
+            const { agentId, buildId, version, kind } = summary.label;
+            if (ref === undefined || typeof agentId !== 'string' || typeof buildId !== 'string')
+                continue;
+            const keyGen = keyGenOf(summary.label);
+            const previous = byRef.get(ref);
+            if (previous && previous.keyGen >= keyGen)
+                continue;
+            byRef.set(ref, {
+                keyGen,
+                session: { sessionRef: ref, agentId, buildId, version: typeof version === 'string' ? version : buildId, patched: kind === 'npm-patched', local },
+            });
+        }
+        return [...byRef.values()].map(({ session }) => session);
+    }
+    /** The adapter processes running now, in every live keeper-acp generation and the local fallback; `undefined` if any cannot be listed. */
+    async listRunningAdapters() {
+        const found = [];
+        if (this.transports.keeper) {
+            let transports;
+            if (this.generations) {
+                try {
+                    const live = await this.generations.live();
+                    transports = await Promise.all(live.map((gen) => this.generations.transportFor(gen)));
+                }
+                catch {
+                    return undefined;
+                }
+            }
+            else {
+                transports = [this.transports.keeper];
+            }
+            for (const transport of transports) {
+                try {
+                    for (const summary of await withDeadline(transport.list(), this.leftoverListTimeoutMs, 'keeper-acp list', Error)) {
+                        if (hostsRunningAdapter(summary))
+                            found.push({ summary, local: false });
+                    }
+                }
+                catch {
+                    return undefined;
+                }
+            }
+        }
+        if (this.transports.local) {
+            try {
+                for (const summary of await this.transports.local.list())
+                    if (hostsRunningAdapter(summary))
+                        found.push({ summary, local: true });
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return found;
+    }
+    /** The agent's current build id and every installed build id (`builds.json`), for `agent_switch_idle` (Task 25). */
+    async buildIdsOf(agentId) {
+        const entry = await this.builds.agent(agentId);
+        return { ...(entry?.current ? { current: entry.current } : {}), installed: Object.keys(entry?.builds ?? {}) };
+    }
+    /** Roster-visible change listeners (see {@link onRosterChanged}). */
+    rosterChangedListeners = [];
+    /**
+     * Subscribe to roster-visible observation changes.
+     *
+     * Fired when an agent's quota capability (`supportsAccountLimits`) is first observed by this
+     * process — the one roster field that can change mid-flight without a build changing, hence
+     * without the build-upkeep push that carries every other roster update. The daemon answers by
+     * re-scanning and pushing the roster; offline, the next hello carries it. Observations are
+     * in-memory, so a restart forgets the capability and this firing together — the next spawn
+     * re-learns both.
+     */
+    onRosterChanged(listener) {
+        this.rosterChangedListeners.push(listener);
     }
     /**
      * Record what a just-established connection revealed about one agent. Called on every connection,
@@ -478,7 +879,21 @@ export class AcpAgents {
      */
     observe(agentId, observation) {
         const previous = this.observed.get(agentId);
-        this.observed.set(agentId, { ...previous, ...observation });
+        const merged = { ...previous, ...observation };
+        this.observed.set(agentId, merged);
+        if (merged.supportsAccountLimits === true && previous?.supportsAccountLimits !== true) {
+            // The quota capability was just learned mid-flight. Without a push here the server's roster
+            // copy stays at the hello/build-change snapshot, and the account UI it gates never renders
+            // (observed 2026-10-13: this daemon's first zcode spawn advertised the capability, the
+            // server's roster remained at that morning's build-change push, no scan happened, and no
+            // account UI ever appeared for the agent).
+            for (const listener of this.rosterChangedListeners) {
+                try {
+                    listener();
+                }
+                catch { /* a listener must not break the observe path */ }
+            }
+        }
     }
     /**
      * What one agent was last seen to advertise as ways of signing in, or `undefined` when this
@@ -504,267 +919,1527 @@ export class AcpAgents {
         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.
+     * Start one session (Task 19, spec 2026-10-11 §5.3/§5.4): build the spawn spec, spawn the adapter in keeper-acp (the local
+     * fallback when keeper-acp is unavailable), let the processor negotiate `initialize`, then either continue in
+     * {@link AcpOpenSpec.nativeSessionId} or open a fresh one — every step a note or a write in the session's raw log.
      *
-     * 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.
+     * The adapter is stopped 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));
+        const requestId = spec.openRequestId ?? randomUUID();
+        const openStarted = performance.now();
+        // Log identifiers and timing only: commands, environment, cwd and lease headers can hold secrets.
+        const phase = async (name, work) => {
+            const started = performance.now();
+            const log = (status) => console.info(`${new Date().toISOString()} [acp-open] request=${JSON.stringify(requestId)} agent=${JSON.stringify(spec.agentId)}` +
+                ` phase=${name} status=${status} durationMs=${Math.round(performance.now() - started)}` +
+                ` totalMs=${Math.round(performance.now() - openStarted)}`);
+            log('started');
+            try {
+                const result = await work();
+                log('completed');
+                return result;
+            }
+            catch (error) {
+                log('failed');
+                throw error;
+            }
+        };
+        // A successful open-time install becomes the session's own `agent_install_outcome` note (Task 20: numbered by the processor,
+        // recorded in the outbox); the caller still hears every outcome (a failure has no session to go on).
+        let installed;
+        if (!spec.command) {
+            await phase('ensure-installed', () => this.installForOpen(spec.agentId, (outcome) => {
+                if (outcome.ok)
+                    installed = outcome;
+                spec.onInstallOutcome?.(outcome);
+            }));
+        }
+        let resolved = await phase('prepare-launch', () => this.resolveLaunchFor(spec.agentId, spec.command, spec.args));
+        // Spec §5.5.6 (Task 24): a session the adoption could not continue is switched by this open — its process is closed and a new
+        // one loads the native session, never falling back to `session/new`.
+        if (this.transports.keeper && spec.sessionRef !== undefined && spec.nativeSessionId) {
+            await this.adoptKeeperSessions();
+            if (this.unrecoverable.has(this.keyFor(spec.sessionRef)))
+                spec = { ...spec, requireSessionLoad: true };
+        }
+        // GC never takes the build between resolving it and the spawn (whose keeper-acp label references it from then on).
+        const releaseLease = this.leaseBuild(spec.agentId, resolved.launch.label?.buildId);
+        const startup = spec.agentId === 'qoder' && spec.delegationMcp
+            ? await phase('prepare-qoder', () => prepareQoderStartup(resolved.launch, spec.delegationMcp, spec.cwd, spec.env, spec.agentEnv))
+            : undefined;
+        if (startup)
+            resolved = { launch: startup.launch, source: resolved.source };
+        let session;
+        try {
+            session = await phase('initialize', () => this.startProcessorSession(resolved, spec, startup, installed));
+        }
+        catch (error) {
+            await startup?.dispose();
+            if (startup)
+                throw new Error('Managed Qoder startup could not initialize');
+            throw error;
+        }
+        finally {
+            releaseLease();
+        }
+        const facts = session.initializeFacts;
+        this.observe(spec.agentId, observationOfFacts(facts));
         try {
-            const started = await this.startSession(connection, capture, spec);
+            if (startup && (session.agentInfo?.name !== 'qoder-cli' || session.agentInfo.version !== QODER_MANAGED_VERSION)) {
+                throw new Error('Managed Qoder runtime identity is not certified');
+            }
+            // Qoder 1.1.61 accepts HTTP MCP at startup, but rejects that entry in ACP new/load.
+            const sessionSpec = { ...spec, managedHistoryResumeRequired: !!spec.delegationMcp || spec.managedHistoryResumeRequired,
+                ...(startup ? { delegationMcp: undefined, requireSessionLoad: spec.requireSessionLoad || !!spec.nativeSessionId } : {}) };
+            const operation = spec.nativeSessionId && facts.capabilities.loadSession ? 'session/load' : 'session/new';
+            const started = await phase(operation, () => withDeadline(this.startSession(session, facts, sessionSpec), this.sessionStartTimeoutMs, `Agent '${spec.agentId}' ${operation}`, AgentSessionStartTimeoutError));
             // 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,
-            };
+            this.observe(spec.agentId, { ...observationOfFacts(facts), authenticated: true });
+            return { session, nativeSessionId: started.nativeSessionId };
         }
         catch (error) {
-            await connection.close().catch(() => undefined);
+            await session.close('auto').catch(() => undefined);
+            await startup?.dispose();
             // 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);
+            throw new AgentRefusedSessionError(error, startup ? 'Managed Qoder session could not open' : undefined);
         }
     }
     /**
-     * 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.
+     * Spawn the adapter behind a {@link ProcessorSession} and wait for its `initialize` (spec §5.3: keeper-acp, or the local
+     * fallback when keeper-acp cannot be reached — §5.7). The spawn spec carries the **complete** environment (keeper-acp never
+     * reads its own), the daemon's working directory (where `connectAgent` started adapters), a managed startup's secrets for
+     * stderr redaction and its temporary files to remove on exit; the label is opaque to the keeper.
      */
-    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;
+    async startProcessorSession(resolved, spec, startup, installOutcome) {
+        const { spawn, label: baseLabel, launch } = this.spawnSpecOf(resolved, spec, startup);
+        const ref = spec.sessionRef;
+        const sessionKey = ref ?? `open-${randomUUID()}`;
+        // A ref whose earlier life ran in the daemon (the local fallback, or a migrated legacy journal) and left frames the server has
+        // not applied continues there for this life, so they are resent from where they are; a drained one is released, its watermark
+        // kept as the floor. Either way the processor numbers after everything that ref ever held (spec §5.5).
+        const resumeFrom = spec.seqBase?.() ?? 0;
+        const local = await this.localLeftover(sessionKey);
+        let seqBase = Math.max(resumeFrom, local?.lastSeq ?? 0);
+        const stayLocal = local !== undefined && local.lastSeq > resumeFrom && local.unacknowledged;
+        if (local && !stayLocal)
+            await this.localTransport().release(sessionKey).catch(() => undefined);
+        // Sessions an earlier daemon left in keeper-acp are discovered (and adopted) before keeper-acp spawns anything for this one.
+        if (this.transports.keeper)
+            await this.adoptKeeperSessions();
+        // keeper-acp's key for the ref: the ref itself, or the key its last switch moved it to (Task 24).
+        const keyGen = ref !== undefined ? this.refKeys.get(ref) ?? 0 : 0;
+        const keeperKey = ref !== undefined ? sessionKeyFor(ref, keyGen) : sessionKey;
+        // A generation that could not be listed may run THIS ref's adapter — only possible when the ref already has a keeper-acp session
+        // directory (keys are deterministic, the data dir is shared): reopening it into a new spawn would stop that adapter, so such an
+        // open is refused until the generation is listed (the manager retried right before this frame). A brand-new ref spawns as usual:
+        // keeper-acp itself refuses (`foreign`) a directory another live keeper holds. (final review finding 3, correction)
+        if (this.transports.keeper && !stayLocal && ref !== undefined && this.keeperAdoptionPending()) {
+            const candidates = [...new Set([ref, keeperKey])];
+            let existing = true;
+            try {
+                existing = (await Promise.all(candidates.map((key) => this.generations?.hasSessionDir?.(key) ?? Promise.resolve(true)))).some(Boolean);
+            }
+            catch {
+                existing = true;
+            }
+            if (existing) {
+                throw new Error(`keeper-acp (generation ${[...this.unlistedGens].join(', ')}) is not answering; this session may still be running there. Try again shortly.`);
+            }
         }
-        finally {
-            await connection.close().catch(() => undefined);
+        const options = {
+            spawn, seqBase, backfill: spec.backfill === true,
+            ...(installOutcome ? { installOutcome } : {}),
+            launch,
+            ...(startup ? { onClosed: () => startup.dispose() } : {}),
+        };
+        let session;
+        if (this.transports.keeper && !stayLocal) {
+            try {
+                // A kept session of this ref in an older generation that still runs (it hosts other adapters): the new spawn goes into it,
+                // there — its raw log and outbox continue as any reused session's; nothing is moved or released. Moving it to the current
+                // generation is §6.3 switching (Task 24). Every other open goes to the current generation (fix round 1, I-2/I-3).
+                const target = await this.spawnTargetFor(keeperKey);
+                // Spec §5.5.6 (Task 24): a session the adoption could not continue still runs its adapter — this open is its switch: the
+                // process is closed first (keeper-acp refuses a second spawn into a running session), then the new one loads.
+                const unrecoverable = this.unrecoverable.get(keeperKey);
+                if (unrecoverable) {
+                    await target.transport.terminate(keeperKey).catch((error) => {
+                        console.warn(`[acp] stopping the unrecoverable session ${keeperKey} before its reopen failed: ${errorMessage(error)}`);
+                    });
+                }
+                this.ownKeeperKeys.add(keeperKey);
+                if (target.gen !== undefined)
+                    this.heldOnOlder.set(keeperKey, target.gen);
+                else
+                    this.heldOnOlder.delete(keeperKey); // a reopen hold on an older generation that is gone now
+                try {
+                    session = await ProcessorSession.start({ ...options, sessionKey: keeperKey, transport: target.transport,
+                        label: { ...baseLabel, ...(keyGen > 0 ? { keyGen } : {}) },
+                        onDegrade: this.recordDegraded(keeperKey, target.gen ?? 'current'),
+                        ...(target.gen !== undefined ? { onClosed: () => this.olderSessionClosed(keeperKey, options.onClosed) } : {}) });
+                }
+                catch (error) {
+                    this.heldOnOlder.delete(keeperKey);
+                    throw error;
+                }
+                this.unrecoverable.delete(keeperKey);
+                if (target.gen === undefined)
+                    this.keeperOwner.delete(keeperKey);
+                this.keeperHeads.delete(keeperKey);
+            }
+            catch (error) {
+                if (!(error instanceof AcpKeeperUnavailableError))
+                    throw error;
+                console.warn(`[acp] keeper-acp is unavailable (${errorMessage(error)}); running agent '${spec.agentId}' in the daemon`);
+            }
+        }
+        if (!session) {
+            // keeper-acp holds an earlier life of this ref this daemon cannot read now: its unacknowledged frames may never reach the
+            // server. Number above everything it held (as far as the last listing knew), and say that output may be missing (Task 21).
+            const keeperHead = stayLocal ? undefined : this.keeperHeads.get(keeperKey);
+            const gap = keeperHead !== undefined && this.keeperOwner.has(keeperKey);
+            if (gap)
+                seqBase = Math.max(seqBase, keeperHead);
+            session = await ProcessorSession.start({ ...options, sessionKey, label: baseLabel, seqBase, transport: this.localTransport(),
+                ...(gap ? { outputGap: `keeper-acp, which holds this session's earlier output (through seq ${keeperHead}), cannot be reached` } : {}) });
         }
-    }
-    /**
-     * 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 } : {}),
-            };
+            await session.initialized(this.initializeTimeoutMs);
         }
         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)}` };
+            await session.close('auto').catch(() => undefined);
+            throw error;
         }
-        finally {
-            await connection.close().catch(() => undefined);
+        return session;
+    }
+    /**
+     * The spawn spec, label and launch diagnostics of a launch (spec §5.3): the **complete** environment (keeper-acp never reads its
+     * own), the daemon's working directory (where `connectAgent` started adapters), a managed startup's secrets for stderr redaction and
+     * its temporary files to remove on exit; the label is opaque to the keeper.
+     */
+    spawnSpecOf(resolved, spec, startup) {
+        const { launch } = resolved;
+        const env = completeEnvironment(withPathPrefix({ ...process.env, ...launch.env, ...spec.env, ...spec.agentEnv }, launch.pathPrefix));
+        const cwd = process.cwd();
+        // keeper-acp takes at most ACP_STDERR_SECRETS_MAX; a managed startup's own secrets come first.
+        const allSecrets = [...(startup?.secrets ?? []), ...overlayEnvSecrets(spec)];
+        if (allSecrets.length > ACP_STDERR_SECRETS_MAX) {
+            console.warn(`[acp] agent '${spec.agentId}': ${allSecrets.length - ACP_STDERR_SECRETS_MAX} of ${allSecrets.length} env values ` +
+                `are not redacted from its stderr (keeper-acp takes at most ${ACP_STDERR_SECRETS_MAX})`);
         }
+        const stderrSecrets = allSecrets.slice(0, ACP_STDERR_SECRETS_MAX);
+        const spawn = {
+            command: launch.command, args: [...launch.args], env, cwd,
+            ...(stderrSecrets.length > 0 ? { stderrSecrets } : {}),
+            ...(startup ? { removeOnExit: [startup.dir] } : {}),
+        };
+        const label = {
+            sessionRef: spec.sessionRef ?? null, agentId: spec.agentId, agentKey: spec.agentKey ?? null,
+            buildId: launch.label?.buildId ?? null, version: launch.label?.version ?? null, kind: launch.label?.kind ?? null,
+            specDigest: createHash('sha256').update(JSON.stringify([spawn.command, spawn.args, spawn.cwd, Object.keys(env).sort()])).digest('hex').slice(0, 16),
+        };
+        return {
+            spawn, label,
+            launch: {
+                source: resolved.source, platform: process.platform, architecture: process.arch, transport: 'stdio',
+                executable: (findOnPath(launch.command, probeEnvironment(env)) ?? launch.command).slice(0, 4096),
+            },
+        };
     }
     /**
-     * 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.
+     * The daemon's once-per-process adoption (Task 21, spec §5.5): every keeper-acp generation that runs (and the current one when
+     * session directories wait on disk for it) is listed; each session whose adapter still runs is adopted where it is
+     * ({@link ProcessorSession.adopt}) — its {@link KeeperAdoption.session} resolves with the rebuilt session, or `undefined` when it
+     * could not be continued (its adapter is stopped then, its outbox kept). Sessions whose adapter is gone stay leftovers (offered as
+     * orphans, resent on a reopen). Resolves once the listing is done; rebuilding goes on behind it. Never rejects.
      */
-    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));
+    adoptKeeperSessions() {
+        this.adoption ??= this.discoverKeeperSessions().catch((error) => {
+            console.warn(`[acp] adopting keeper-acp sessions failed: ${errorMessage(error)}`);
+            return [];
+        });
+        return this.adoption;
+    }
+    async discoverKeeperSessions() {
+        const generations = this.generations;
+        if (!generations || !this.transports.keeper)
+            return [];
+        const current = await generations.current();
+        const live = await generations.live();
+        const gens = live.includes(current) || !await generations.hasSessionData() ? live : [...live, current];
+        return this.adoptFrom(gens, current);
+    }
+    /**
+     * Whether a keeper-acp generation could not be listed yet (see {@link unlistedGens}): the manager then retries the adoption
+     * ({@link retryKeeperAdoption}) before it handles a frame, offers its inventory or polls. Synchronous.
+     */
+    keeperAdoptionPending() { return this.unlistedGens.size > 0; }
+    /**
+     * Final review finding 3: lists again the keeper-acp generations whose listing failed (at the daemon's start or a retry since) and
+     * adopts their sessions exactly as the start-time adoption does; each adoption is returned once, here. A generation that stopped
+     * meanwhile is dropped (the current generation recovers its directories). One retry at a time; never rejects.
+     */
+    retryKeeperAdoption() {
+        if (!this.adoption || this.unlistedGens.size === 0)
+            return Promise.resolve([]);
+        this.retrying ??= (async () => {
+            await this.adoption;
+            const generations = this.generations;
+            if (!generations || this.unlistedGens.size === 0)
+                return [];
+            const current = await generations.current();
+            const live = new Set(await generations.live());
+            for (const gen of [...this.unlistedGens])
+                if (gen !== current && !live.has(gen))
+                    this.unlistedGens.delete(gen);
+            return this.adoptFrom([...this.unlistedGens], current);
+        })().catch((error) => {
+            console.warn(`[acp] retrying the adoption of keeper-acp sessions failed: ${errorMessage(error)}`);
+            return [];
+        }).finally(() => { this.retrying = undefined; });
+        return this.retrying;
+    }
+    /** Lists `gens` and adopts what they hold (see {@link adoptKeeperSessions}); a generation that cannot be listed is remembered. */
+    async adoptFrom(gens, current) {
+        const generations = this.generations;
+        const listed = [];
+        for (const gen of gens) {
+            let transport;
+            let sessions;
             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);
+                transport = await generations.transportFor(gen);
+                sessions = await withDeadline(transport.list(), this.leftoverListTimeoutMs, `keeper-acp ${gen} list`, Error);
             }
-            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);
+            catch (error) {
+                // keeper-acp of the current build could not be launched or reached: the local fallback serves this daemon (spec §5.7) — it is
+                // not a generation whose running sessions wait to be adopted (final review finding 3, correction).
+                if (gen === current && error instanceof AcpKeeperUnavailableError) {
+                    console.warn(`[acp] keeper-acp (generation ${gen}) is unavailable; its kept sessions are not adopted: ${errorMessage(error)}`);
+                    continue;
+                }
+                this.unlistedGens.add(gen);
+                console.warn(`[acp] keeper-acp generation ${gen} could not be listed; its sessions are adopted once it answers: ${errorMessage(error)}`);
+                continue;
             }
+            this.unlistedGens.delete(gen);
+            for (const summary of sessions)
+                if (!this.ownKeeperKeys.has(summary.sessionKey))
+                    listed.push({ gen, transport, summary });
         }
-        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();
+        const found = [];
+        const queue = [];
+        for (const { gen, transport, summary } of await this.withoutSuperseded(listed)) {
+            const key = summary.sessionKey;
+            this.noteKeeperSession(gen, summary);
+            const running = summary.process.state === 'running' || summary.process.state === 'starting';
+            // An exited adapter's session is looked at too (Task 23, spec §5.3): its raw tail may hold a running turn's real end, which is
+            // folded and delivered before the session is reported dead — when there is nothing to finish, `adoptOne` leaves it alone.
+            const exitedWithRaw = summary.process.state === 'exited' && summary.raw !== null;
+            if (!running && !exitedWithRaw)
+                continue;
+            const ref = refOfSession(summary);
+            if (!running && ref === undefined)
+                continue;
+            if (ref === undefined) {
+                // No ref the server could reopen it under: nobody will ever drive it.
+                console.warn(`[acp] keeper-acp session ${key} names no session ref; stopping its adapter (its outbox is kept)`);
+                void transport.terminate(key).catch(() => null);
+                continue;
+            }
+            let settle;
+            const session = new Promise((resolve) => { settle = resolve; });
+            queue.push(async () => { settle(await this.adoptOne(transport, gen, gen === current, summary, !running)); });
+            found.push({
+                sessionRef: ref, agentId: String(summary.label.agentId ?? ''), agentKey: String(summary.label.agentKey ?? ''),
+                journalMaxSeq: this.keeperHeads.get(key) ?? 0, ...(running ? {} : { agentAlive: false }), session,
+            });
         }
+        // A few at a time: each rebuild reads a checkpoint and up to one cadence of raw.
+        const worker = async () => { for (let next = queue.shift(); next; next = queue.shift())
+            await next(); };
+        void Promise.all(Array.from({ length: ADOPT_CONCURRENCY }, worker)).then(() => this.retireIdleGenerations());
+        return found;
     }
     /**
-     * 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
+     * Task 24: one keeper-acp session per ref. Two exist only when a switch was interrupted by a crash (the successor `<ref>#s<n>` is
+     * spawned, and loaded, while the predecessor still exists; the predecessor is released last): `resolveSuperseded` keeps the newest
+     * key whose open completed — its import of the predecessor's outbox had landed — or, when none did, the oldest. The others are
+     * stopped and released. Every listed ref's current key generation is recorded.
+     */
+    async withoutSuperseded(listed) {
+        const byRef = new Map();
+        const kept = [];
+        for (const entry of listed) {
+            const ref = refOfSession(entry.summary);
+            if (ref === undefined) {
+                kept.push(entry);
+                continue;
+            }
+            byRef.set(ref, [...(byRef.get(ref) ?? []), entry]);
+        }
+        for (const [ref, entries] of byRef) {
+            let winner = entries[0];
+            if (entries.length > 1) {
+                const resolved = await resolveSuperseded(entries.map((entry) => ({ ...entry, sessionKey: entry.summary.sessionKey, label: entry.summary.label })), (entry) => this.openCompleted(entry.transport, entry.summary.sessionKey));
+                winner = entries.find((entry) => entry.summary.sessionKey === resolved.winner.sessionKey);
+                for (const gone of resolved.superseded) {
+                    console.warn(`[acp] ${ref}: keeper-acp session ${gone.sessionKey} (generation ${gone.gen}) was superseded by ${winner.summary.sessionKey} ` +
+                        '(a switch a restart interrupted); stopping and releasing it');
+                    await gone.transport.terminate(gone.sessionKey).catch(() => null);
+                    await gone.transport.release(gone.sessionKey).catch((error) => {
+                        console.warn(`[acp] releasing the superseded session ${gone.sessionKey} failed: ${errorMessage(error)}`);
+                    });
+                }
+            }
+            this.refKeys.set(ref, keyGenOf(winner.summary.label));
+            kept.push(winner);
+        }
+        return kept;
+    }
+    /** Whether a keeper-acp session's head checkpoint says its open had completed (no load history open). */
+    async openCompleted(transport, sessionKey) {
+        try {
+            const attached = await transport.attach(sessionKey);
+            if (!attached.checkpoint)
+                return false;
+            // A successor the switch gave up on (its rollback took the session back) never wins, whatever its checkpoint says.
+            if (await this.switchAbandoned(transport, sessionKey, attached))
+                return false;
+            const checkpoint = decodeCheckpoint(Buffer.from(attached.checkpoint.blob, 'base64').toString('utf8'));
+            return checkpoint.state.open.status === 'open' && checkpoint.state.history === null;
+        }
+        catch {
+            return false;
+        }
+    }
+    noteKeeperSession(gen, summary) {
+        this.keeperOwner.set(summary.sessionKey, gen);
+        const tail = isOutboxTail(summary.outbox.committedTail) ? summary.outbox.committedTail.seq : 0;
+        this.keeperHeads.set(summary.sessionKey, Math.max(summary.outbox.lastSeq ?? 0, tail));
+        const ref = refOfSession(summary);
+        if (ref !== undefined && keyGenOf(summary.label) >= (this.refKeys.get(ref) ?? 0))
+            this.refKeys.set(ref, keyGenOf(summary.label));
+    }
+    async adoptOne(transport, gen, current, summary, exited = false) {
+        const key = summary.sessionKey;
+        try {
+            if (!current)
+                this.heldOnOlder.set(key, gen);
+            const options = { transport, sessionKey: key, label: summary.label, onDegrade: this.recordDegraded(key, gen),
+                // An older generation that no longer hosts a session of this daemon (or a running adapter) is stopped once this one is gone.
+                ...(current ? {} : { onClosed: () => this.olderSessionClosed(key) }) };
+            const session = exited ? await ProcessorSession.adopt({ ...options, allowExited: true }) : await ProcessorSession.adopt(options);
+            if (!session) {
+                // An exited adapter with no turn left to finish: nothing to hold; it stays a leftover for its ref's next open.
+                this.heldOnOlder.delete(key);
+                return undefined;
+            }
+            // The owner of an older generation's session is kept: a reopen after its adapter exits spawns there (fix round 1, I-2).
+            if (current)
+                this.keeperOwner.delete(key);
+            return session;
+        }
+        catch (error) {
+            this.heldOnOlder.delete(key);
+            if (exited) {
+                // Its adapter had already exited: there is nothing to stop. Its outbox stays for its ref's next open (which loads it).
+                console.warn(`[acp] keeper-acp session ${key} (generation ${gen}, adapter exited) could not be adopted` +
+                    `${error instanceof AdoptionRefusedError ? '' : ' (keeper-acp failed)'}: ${errorMessage(error)}; keeping its outbox`);
+                return undefined;
+            }
+            // Spec §5.5.6 (Task 24 replaces Task 21's interim stop): a session this daemon cannot continue — its open never completed, or
+            // its checkpoint is unreadable and raw truncated — is marked degraded and left running; the ref's next `agent_open` switches it
+            // (closes the process, then a new one loads the native session). Until then it is offered as an orphan; its outbox is kept.
+            const reason = errorMessage(error);
+            console.warn(`[acp] keeper-acp session ${key} (generation ${gen}) could not be adopted` +
+                `${error instanceof AdoptionRefusedError ? '' : ' (keeper-acp failed)'}: ${reason}; marked degraded — its next open switches it`);
+            this.unrecoverable.set(key, { gen, reason });
+            this.keeperOwner.set(key, gen);
+            return undefined;
+        }
+    }
+    /** Where a keeper spawn of `sessionKey` goes: the older generation that still holds a kept session of it, else the current one. */
+    async spawnTargetFor(sessionKey) {
+        const generations = this.generations;
+        const owner = this.keeperOwner.get(sessionKey);
+        const current = this.transports.keeper;
+        if (!generations || owner === undefined || owner === await generations.current())
+            return { transport: current };
+        if (!(await generations.live()).includes(owner))
+            return { transport: current }; // gone: the current one adopts the directory
+        return { transport: await generations.transportFor(owner), gen: owner };
+    }
+    /**
+     * The manager retires a session to respawn it at once (an `agent_open` of a keeper session whose adapter is gone, Task 21 fix
+     * round 2): until the returned release, the older generation that holds it is not stopped — the retire's close no longer releases
+     * the hold, the respawn's spawn takes it over (or drops it when it goes elsewhere or fails). Release after the attempt, whatever
+     * it did.
+     */
+    holdForReopen(sessionRef) {
+        return this.holdKey(this.keyFor(sessionRef));
+    }
+    /** {@link holdForReopen} by key (a switch holds its predecessor's generation until it is released or rolled back to). */
+    holdKey(sessionKey) {
+        this.reopenHolds.add(sessionKey);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.reopenHolds.delete(sessionKey);
+            void this.retireIdleGenerations();
+        };
+    }
+    // ---- switching (Task 24, spec §6.3) ---------------------------------------------------------------------------------------
+    /** A ref's current keeper-acp key: `<ref>`, or `<ref>#s<n>` once a switch moved it (`switching.ts`). */
+    keyFor(sessionRef) {
+        return sessionKeyFor(sessionRef, this.refKeys.get(sessionRef) ?? 0);
+    }
+    /**
+     * Where a held session runs (Task 24/25): its transport key, the keeper-acp generation hosting it (`undefined`: the current one, or
+     * the local fallback), its build (`undefined`: a command override) and whether keeper-acp hosts it at all.
+     */
+    placementOf(session) {
+        if (!(session instanceof ProcessorSession))
+            return undefined;
+        const label = session.label;
+        const gen = this.heldOnOlder.get(session.sessionKey);
+        return {
+            sessionKey: session.sessionKey, keeper: session.transportMode === 'keeper',
+            ...(gen !== undefined ? { gen } : {}),
+            ...(typeof label.agentId === 'string' ? { agentId: label.agentId } : {}),
+            ...(typeof label.buildId === 'string' ? { buildId: label.buildId } : {}),
+        };
+    }
+    /**
+     * Move a live keeper-hosted session onto a new adapter process (spec §6.3): the target build (`toBuild`, else the agent's current
+     * one — a command override keeps its command) on the **current** keeper-acp generation, under a new key, build before teardown.
+     * Called only at an `agent_open` (its `spec` carries the session's fresh spawn environment) and only for a strictly idle session
+     * (the caller checks; this only holds the loop at a record boundary). Steps:
+     *
+     * 1. lease both builds; hold the predecessor's generation; hold the predecessor's loop ({@link ProcessorSession.suspend}) — its
+     *    checkpoint is the successor's initial state;
+     * 2. spawn the successor `<ref>#s<n>` with `baseOffset` past the predecessor's raw log, the predecessor's unacknowledged outbox
+     *    entries imported first, and `initialize` it — it must advertise `loadSession`, or it is stopped and released and the
+     *    predecessor goes on untouched (`unmovable`);
+     * 3. only now stop the predecessor's adapter (its transport session — raw, outbox — stays), then `session/load` on the successor
+     *    with `requireSessionLoad` **forced** whatever the `agent_open` said (never `session/new`), and set back every config option the
+     *    load did not restore;
+     * 4. success: release the predecessor (the import landed in step 2) — `switched`; failure: stop and release the successor, spawn
+     *    the predecessor's build again in the predecessor's key and load there (`rolledBack`), or, when that fails too, `lost`.
+     *
+     * Runs under the agent's build lock (install / switch / GC are serialised per agent). Never rejects.
+     */
+    async switchSession(from, spec, request) {
+        const ref = spec.sessionRef;
+        const nativeSessionId = (from instanceof ProcessorSession ? from.nativeSessionId : null) ?? spec.nativeSessionId;
+        const refuse = (reason, permanent = true) => ({ kind: 'unmovable', reason, permanent });
+        let outcome;
+        if (!(from instanceof ProcessorSession) || from.transportMode !== 'keeper' || !this.transports.keeper) {
+            outcome = refuse('only a keeper-hosted session can be moved');
+        }
+        else if (ref === undefined) {
+            outcome = refuse('the session has no ref');
+        }
+        else if (!nativeSessionId) {
+            outcome = refuse('the session has no native session to load');
+        }
+        else if (spec.delegationMcp || from.delegation) {
+            outcome = refuse('a managed delegation session is not moved');
+        }
+        else {
+            outcome = await this.builds.withAgentLock(spec.agentId, () => this.switchLocked(from, { ...spec, sessionRef: ref, nativeSessionId }, request))
+                .catch((error) => refuse(`the switch failed before anything was stopped: ${errorMessage(error)}`, false));
+        }
+        if (ref !== undefined) {
+            // The build the refusal was about, resolved (Task 25): a later "move" to a different build may try again.
+            const refusedFor = async () => request.toBuild ?? (await this.builds.agent(spec.agentId).catch(() => undefined))?.current;
+            if (outcome.kind === 'unmovable' && outcome.permanent) {
+                const toBuild = await refusedFor();
+                this.unmovableRefs.set(ref, { reason: outcome.reason, ...(toBuild ? { toBuild } : {}) });
+            }
+            else if (outcome.kind === 'rolledBack' && !outcome.retry) {
+                const toBuild = await refusedFor();
+                this.unmovableRefs.set(ref, { reason: outcome.error, ...(toBuild ? { toBuild } : {}) });
+            }
+            else if (outcome.kind === 'switched')
+                this.unmovableRefs.delete(ref);
+            // Fulfilled, or never possible: the intent goes. A transient refusal keeps it for the next idle moment.
+            if (!(outcome.kind === 'unmovable' && !outcome.permanent) && !(outcome.kind === 'rolledBack' && outcome.retry)) {
+                await this.cancelSwitch({ sessionRef: ref }).catch(() => false);
+            }
+        }
+        const what = outcome.kind === 'switched' ? `moved to ${outcome.toKey}` : outcome.kind === 'unmovable' ? `not moved: ${outcome.reason}`
+            : outcome.kind === 'rolledBack' ? `rolled back: ${outcome.error}` : `lost: ${outcome.error}`;
+        console.info(`[acp] switch of ${ref ?? '?'} (agent '${spec.agentId}', ${request.reason}): ${what}`);
+        if (outcome.kind === 'switched')
+            void this.collectBuilds().catch(() => undefined);
+        return outcome;
+    }
+    async switchLocked(from, spec, request) {
+        const ref = spec.sessionRef;
+        const agentId = spec.agentId;
+        const oldKey = from.sessionKey;
+        const oldGen = this.heldOnOlder.get(oldKey);
+        const oldTransport = oldGen === undefined ? this.transports.keeper : await this.generations.transportFor(oldGen);
+        const current = this.transports.keeper;
+        const fromBuildId = typeof from.label.buildId === 'string' ? from.label.buildId : undefined;
+        let resolved;
+        let toBuildId;
+        try {
+            if (spec.command) {
+                resolved = { launch: { command: spec.command, args: spec.args, env: {} }, source: 'command-override' };
+            }
+            else {
+                toBuildId = request.toBuild ?? (await this.builds.agent(agentId))?.current;
+                if (toBuildId === undefined)
+                    return { kind: 'unmovable', reason: `agent '${agentId}' has no current build`, permanent: true };
+                resolved = await this.launchOfBuild(agentId, toBuildId);
+            }
+        }
+        catch (error) {
+            return { kind: 'unmovable', reason: errorMessage(error), permanent: true };
+        }
+        const releases = [this.leaseBuild(agentId, fromBuildId), this.leaseBuild(agentId, toBuildId), this.holdKey(oldKey)];
+        try {
+            const configBefore = from.configOptions.map((option) => ({ ...option }));
+            let suspendTimer;
+            const checkpoint = await Promise.race([
+                from.suspend(),
+                new Promise((resolve) => { suspendTimer = setTimeout(() => resolve(undefined), SWITCH_SUSPEND_TIMEOUT_MS); }),
+            ]).finally(() => clearTimeout(suspendTimer));
+            if (!checkpoint) {
+                from.resume();
+                return { kind: 'unmovable', reason: 'its record loop could not be held at a boundary', permanent: false };
+            }
+            // 2. The successor, under a fresh key on the current generation.
+            const taken = new Set((await current.list()).map((summary) => summary.sessionKey));
+            let keyGen = Math.max(keyGenOf(from.label), this.refKeys.get(ref) ?? 0) + 1;
+            while (taken.has(sessionKeyFor(ref, keyGen)))
+                keyGen += 1;
+            const newKey = sessionKeyFor(ref, keyGen);
+            const oldRaw = (await oldTransport.list()).find((summary) => summary.sessionKey === oldKey)?.raw;
+            const baseOffset = Math.max(checkpoint.offset + 1, oldRaw?.next ?? 0);
+            const imports = from.outbox.pending.map((item) => ({ seq: item.seq, frame: item.frame }));
+            let next;
+            try {
+                next = await this.startPlaced(resolved, spec, { transport: current, sessionKey: newKey, keyGen, seqBase: from.headSeq, switchedFrom: oldKey,
+                    seed: { checkpoint, baseOffset, imports } });
+            }
+            catch (error) {
+                await current.terminate(newKey).catch(() => null);
+                await current.release(newKey).catch(() => undefined);
+                from.resume();
+                return { kind: 'unmovable', reason: `the new adapter process did not start: ${errorMessage(error)}`, permanent: false };
+            }
+            const facts = next.initializeFacts;
+            if (!facts.capabilities.loadSession) {
+                // Build before teardown: the predecessor was never touched.
+                await next.close('release').catch(() => undefined);
+                from.resume();
+                return { kind: 'unmovable', reason: `${facts.agentInfo?.name ?? agentId} ${facts.agentInfo?.version ?? ''} does not support session/load`.replace(/ +/g, ' '), permanent: true };
+            }
+            if (request.proceed && !request.proceed()) {
+                await next.close('release').catch(() => undefined);
+                from.resume();
+                return { kind: 'unmovable', reason: 'the workstation is stopping', permanent: false };
+            }
+            // The predecessor's adapter wrote something while its loop was held (fix round 1): only the predecessor can fold it, and its
+            // log goes with it. Not now — the predecessor folds it, the intent stays, the next idle moment tries again. Also looked up in
+            // keeper-acp itself: an output record already appended but not yet delivered counts the same. Only adapter output (`up`)
+            // counts (fix round 2); stderr does not hold a switch back.
+            if (from.arrivedWhileSuspended > 0 || await this.outputPast(oldTransport, oldKey, checkpoint.offset)) {
+                await next.close('release').catch(() => undefined);
+                from.resume();
+                return { kind: 'unmovable', reason: 'its adapter produced output while the switch was being prepared', permanent: false };
+            }
+            // 3. Only now: the predecessor's adapter stops (its raw and outbox stay, for a rollback) — with its loop still held.
+            await from.stopAdapter();
+            // Fix round 2: keeper-acp records what the adapter still wrote on its way out (after the check above, or on SIGTERM) into the
+            // predecessor's raw. Only the predecessor can fold it — under its own seqs, which the successor has not used yet (it numbered
+            // nothing it recorded: it is not registered) — so the switch is given up here: the successor is abandoned, the predecessor
+            // folds its whole tail (output, then its exit) on its loop, and is restarted and loaded by the rollback. Nothing is lost and the
+            // intent stays for a later idle moment.
+            if (await this.outputPast(oldTransport, oldKey, checkpoint.offset)) {
+                await this.abandonSuccessor(current, newKey, next, 'the previous adapter wrote output while it was being stopped');
+                const tailEnd = ((await oldTransport.list()).find((summary) => summary.sessionKey === oldKey)?.raw?.next ?? checkpoint.offset + 1) - 1;
+                from.resume();
+                await from.foldedThrough(tailEnd).catch((error) => {
+                    console.warn(`[acp] ${oldKey}: folding the stopped adapter's last output failed: ${errorMessage(error)}`);
+                });
+                await from.close('keep');
+                const back = await this.rollBack(from, spec, { oldKey, oldGen, oldTransport, fromBuildId, configBefore,
+                    error: 'the previous adapter wrote output while it was being stopped' });
+                return back.kind === 'rolledBack' ? { ...back, retry: true } : back;
+            }
+            await from.close('keep');
+            try {
+                await this.loadInto(next, spec, configBefore);
+            }
+            catch (error) {
+                await this.abandonSuccessor(current, newKey, next, errorMessage(error));
+                return this.rollBack(from, spec, { oldKey, oldGen, oldTransport, fromBuildId, configBefore, error: errorMessage(error) });
+            }
+            // 4. The successor holds the session and the predecessor's unacknowledged frames (imported before the load): release it.
+            this.refKeys.set(ref, keyGen);
+            this.heldOnOlder.delete(oldKey);
+            this.keeperOwner.delete(oldKey);
+            this.keeperHeads.delete(oldKey);
+            this.unrecoverable.delete(oldKey);
+            await oldTransport.release(oldKey).catch((error) => {
+                console.warn(`[acp] releasing ${oldKey} after its switch to ${newKey} failed (the next daemon drops it as superseded): ${errorMessage(error)}`);
+            });
+            return { kind: 'switched', session: next, nativeSessionId: spec.nativeSessionId, fromKey: oldKey, toKey: newKey };
+        }
+        finally {
+            for (const release of releases)
+                release();
+        }
+    }
+    /**
+     * A successor that will not hold the session (its load failed, or it failed after loading — fix round 1): marked abandoned in its
+     * own log FIRST (`switch_abandoned` note — a crash before the release must not let the next daemon's discovery pick it over the
+     * rolled-back predecessor, which then holds every newer frame), then stopped and released, retried, and loudly reported when it
+     * stays.
+     */
+    async abandonSuccessor(transport, key, session, reason) {
+        await transport.note(key, { type: SWITCH_ABANDONED_NOTE, reason: reason.slice(0, 1024) }).catch((error) => {
+            console.error(`[acp] marking the abandoned switch successor ${key} failed: ${errorMessage(error)}`);
+        });
+        await session.close('release').catch(() => undefined);
+        let last;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            let still;
+            try {
+                still = (await transport.list()).some((summary) => summary.sessionKey === key);
+            }
+            catch (error) {
+                last = error;
+                still = true;
+            }
+            if (!still)
+                return;
+            if (attempt > 0)
+                await new Promise((resolve) => setTimeout(resolve, 250 * attempt));
+            await transport.terminate(key).catch(() => null);
+            await transport.release(key).catch((error) => { last = error; });
+        }
+        console.error(`[acp] the abandoned switch successor ${key} could not be released (${last instanceof Error ? last.message : String(last)}); ` +
+            'it is marked abandoned, so the next daemon drops it in favour of its predecessor');
+    }
+    /** Whether raw holds adapter output (`up`) past `offset` (the predecessor's checkpoint): output only it can fold (fix round 2). */
+    async outputPast(transport, sessionKey, offset) {
+        for (let at = offset + 1;;) {
+            let page;
+            try {
+                page = await transport.readRaw(sessionKey, at);
+            }
+            catch {
+                return true;
+            } // cannot tell: do not risk it
+            if (page.length === 0)
+                return false;
+            if (page.some((record) => record.kind === 'up'))
+                return true;
+            at = page[page.length - 1].o + 1;
+        }
+    }
+    /** Whether a switch successor was marked abandoned (fix round 1): its log holds a `switch_abandoned` note. */
+    async switchAbandoned(transport, sessionKey, attached) {
+        for (let at = attached.raw?.first ?? 0; at <= attached.head;) {
+            let page;
+            try {
+                page = await transport.readRaw(sessionKey, at);
+            }
+            catch {
+                return false;
+            }
+            if (page.length === 0)
+                return false;
+            if (page.some((record) => record.kind === 'note' && record.note.type === SWITCH_ABANDONED_NOTE))
+                return true;
+            at = page[page.length - 1].o + 1;
+        }
+        return false;
+    }
+    /** Step 6: the predecessor's build in the predecessor's key, loaded again; `lost` when that fails too (never `session/new`). */
+    async rollBack(from, spec, old) {
+        let back;
+        try {
+            const resolved = spec.command
+                ? { launch: { command: spec.command, args: spec.args, env: {} }, source: 'command-override' }
+                : old.fromBuildId !== undefined ? await this.launchOfBuild(spec.agentId, old.fromBuildId)
+                    : (() => { throw new Error('the session\'s build is unknown'); })();
+            back = await this.startPlaced(resolved, spec, { transport: old.oldTransport, sessionKey: old.oldKey, keyGen: keyGenOf(from.label),
+                seqBase: from.headSeq, ...(old.oldGen !== undefined ? { gen: old.oldGen } : {}) });
+            if (!back.initializeFacts.capabilities.loadSession)
+                throw new Error('the previous build no longer advertises session/load');
+            await this.loadInto(back, spec, old.configBefore);
+            return { kind: 'rolledBack', session: back, nativeSessionId: spec.nativeSessionId, error: old.error };
+        }
+        catch (error) {
+            await back?.close('keep').catch(() => undefined);
+            if (old.oldGen !== undefined)
+                this.heldOnOlder.delete(old.oldKey);
+            return { kind: 'lost', error: `the new adapter could not load the session (${old.error}), and neither could the previous one (${errorMessage(error)})` };
+        }
+    }
+    /** `session/load` with `requireSessionLoad` forced (spec §5.5.4/§6.3: never `session/new`), then the config options set back. */
+    async loadInto(session, spec, configBefore) {
+        const facts = session.initializeFacts;
+        await withDeadline(this.startSession(session, facts, { ...spec, requireSessionLoad: true, backfill: false }), this.sessionStartTimeoutMs, `Agent '${spec.agentId}' session/load`, AgentSessionStartTimeoutError);
+        if (session.nativeSessionId !== spec.nativeSessionId)
+            throw new Error(`session/load bound '${session.nativeSessionId}', not '${spec.nativeSessionId}'`);
+        await restoreConfigOptions(session, configBefore, () => `switch-${randomUUID()}`, (line) => console.warn(line));
+    }
+    /** A session spawned where the caller says (a switch's successor, or its rollback), `initialize`d. */
+    async startPlaced(resolved, spec, placement) {
+        const { spawn, label, launch } = this.spawnSpecOf(resolved, spec);
+        const key = placement.sessionKey;
+        this.ownKeeperKeys.add(key);
+        if (placement.gen !== undefined)
+            this.heldOnOlder.set(key, placement.gen);
+        const session = await ProcessorSession.start({
+            spawn, launch, seqBase: placement.seqBase, backfill: false, transport: placement.transport, sessionKey: key,
+            label: { ...label, ...(placement.keyGen > 0 ? { keyGen: placement.keyGen } : {}), ...(placement.switchedFrom ? { switchedFrom: placement.switchedFrom } : {}) },
+            ...(placement.seed ? { seed: placement.seed } : {}),
+            onDegrade: this.recordDegraded(key, placement.gen ?? 'current'),
+            ...(placement.gen !== undefined ? { onClosed: () => this.olderSessionClosed(key) } : {}),
+        });
+        try {
+            await session.initialized(this.initializeTimeoutMs);
+        }
+        catch (error) {
+            await session.close(placement.seed ? 'release' : 'auto').catch(() => undefined);
+            throw error;
+        }
+        return session;
+    }
+    /** The launch of one recorded build (not necessarily the current one), through the same Node gate and launch env as any open. */
+    async launchOfBuild(agentId, buildId) {
+        const build = (await this.builds.agent(agentId))?.builds[buildId];
+        if (!build || !existsSync(inside(this.adapterRoot, build.dir)))
+            throw new AdapterNotInstalledError(agentId, `build ${buildId} is not installed`);
+        this.touchBuild(agentId, buildId);
+        return {
+            source: 'registry',
+            launch: await launchForBuild(build, this.adapterRoot, {
+                nodePath: this.nodePath, launchEnv: catalogLaunchEnv(agentId, build.registryVersion), basePath: this.probe.path,
+            }),
+        };
+    }
+    // ---- switch intents (spec §6.3 step 7) ------------------------------------------------------------------------------------
+    /** The intents, read from `builds.json` once; every write below updates this copy too. */
+    loadIntents() {
+        this.intents ??= this.builds.switchIntents().then((all) => new Map(all.map(({ agentId, sessionRef, intent }) => [sessionRef, { agentId, intent }])), (error) => { this.intents = undefined; throw error; });
+        return this.intents;
+    }
+    /** Every persistent switch intent (`builds.json` `switchPending`). */
+    async switchIntents() {
+        return [...(await this.loadIntents())].map(([sessionRef, { agentId, intent }]) => ({ agentId, sessionRef, intent }));
+    }
+    /**
+     * Record that `sessionRef` (a session of `agentId`) should move — to `toBuild`, else the agent's current build at the time, and to
+     * the current keeper-acp generation (`keeperGen: 'current'` alone: only off an older generation). Persistent: survives a restart.
+     */
+    async requestSwitch(agentId, sessionRef, intent) {
+        const record = {
+            ...(intent.toBuild !== undefined ? { toBuild: intent.toBuild } : {}), ...(intent.keeperGen ? { keeperGen: intent.keeperGen } : {}),
+            reason: intent.reason, requestedBy: intent.requestedBy ?? 'user', requestedAt: new Date().toISOString(),
+        };
+        const intents = await this.loadIntents();
+        if (!await this.builds.setSwitchIntent(agentId, sessionRef, record))
+            throw new Error(`${this.builds.file} could not be written`);
+        intents.set(sessionRef, { agentId, intent: record });
+        this.unmovableRefs.delete(sessionRef);
+    }
+    /** Cancel the intent of one ref, or every intent of one agent. `true` when one existed. */
+    async cancelSwitch(target) {
+        const intents = await this.loadIntents();
+        const refs = 'sessionRef' in target ? [target.sessionRef]
+            : [...intents].filter(([, entry]) => entry.agentId === target.agentId).map(([ref]) => ref);
+        if (!refs.some((ref) => intents.has(ref)))
+            return false;
+        const removed = await this.builds.cancelSwitchIntents(target);
+        for (const ref of refs)
+            intents.delete(ref);
+        return removed;
+    }
+    /** Why `sessionRef` cannot be moved (spec §6.4 `unmovable`), if a switch of it found so. */
+    unmovableReason(sessionRef) {
+        return this.unmovableRefs.get(sessionRef)?.reason;
+    }
+    /** {@link unmovableReason} with the build the refusal was about (`toBuild`; absent when it could not be resolved). */
+    unmovableFor(sessionRef) {
+        return this.unmovableRefs.get(sessionRef);
+    }
+    /**
+     * The switch a held session still owes its intent, or `undefined` (no intent, or it is fulfilled — then the intent is dropped).
+     * A build intent is fulfilled once the session runs the target build; a keeper-generation intent once it runs on the current
+     * generation. A command-override session only ever moves generations.
+     */
+    async pendingSwitchFor(sessionRef, session) {
+        const found = (await this.loadIntents()).get(sessionRef);
+        if (!found)
+            return undefined;
+        const placement = this.placementOf(session);
+        if (!placement?.keeper)
+            return undefined;
+        const { intent, agentId } = found;
+        const onOlder = placement.gen !== undefined;
+        const target = intent.keeperGen === 'current' && intent.toBuild === undefined ? undefined
+            : intent.toBuild ?? (await this.builds.agent(agentId))?.current;
+        const needsBuild = target !== undefined && placement.buildId !== undefined && placement.buildId !== target;
+        const needsGen = intent.keeperGen === 'current' && onOlder;
+        if (!needsBuild && !needsGen) {
+            await this.cancelSwitch({ sessionRef }).catch(() => false);
+            return undefined;
+        }
+        return { ...(needsBuild ? { toBuild: target } : {}), reason: intent.reason };
+    }
+    // ---- build leases and GC (spec §6.3 "GC") ----------------------------------------------------------------------------------
+    /** A daemon lease on a build (GC never takes it while held); the release also marks it seen now. */
+    leaseBuild(agentId, buildId) {
+        if (buildId === undefined)
+            return () => { };
+        const key = buildKeyOf(agentId, buildId);
+        this.leases.set(key, (this.leases.get(key) ?? 0) + 1);
+        this.touchBuild(agentId, buildId);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const left = (this.leases.get(key) ?? 1) - 1;
+            if (left > 0)
+                this.leases.set(key, left);
+            else
+                this.leases.delete(key);
+            this.touchBuild(agentId, buildId, Date.now());
+        };
+    }
+    /**
+     * A build was just resolved for a launch: protected until any connection started from it has necessarily ended (a login's ceiling)
+     * — the lease of the short-lived connections (verify, list, delete, login), which end on their own.
+     */
+    touchBuild(agentId, buildId, until = Date.now() + AGENT_LOGIN_CEILING_MS) {
+        const key = buildKeyOf(agentId, buildId);
+        this.buildSeen.set(key, Math.max(this.buildSeen.get(key) ?? 0, until));
+    }
+    /**
+     * The builds adapter processes run right now: every keeper-acp generation that runs, listed (a generation that cannot be listed →
+     * `undefined`: nothing may be collected), plus the local fallback's processes.
+     */
+    async runningBuildReferences() {
+        const listed = await this.listRunningAdapters();
+        if (!listed)
+            return undefined;
+        const refs = [];
+        for (const { summary } of listed) {
+            const { agentId, buildId } = summary.label;
+            if (typeof agentId === 'string' && typeof buildId === 'string')
+                refs.push({ agentId, buildId });
+        }
+        return refs;
+    }
+    /**
+     * Collect unused adapter builds (spec §6.3; `builds/gc.ts` has the rules) and what an older CLI left. Never while keeper-acp cannot
+     * be listed. One at a time; never rejects (failures are logged).
+     */
+    collectBuilds(options = {}) {
+        const previous = this.collecting;
+        let run;
+        run = (async () => {
+            await previous?.catch(() => undefined);
+            try {
+                const running = await this.runningBuildReferences();
+                const leased = [...this.leases.keys()].map((key) => { const [agentId, buildId] = key.split('\u0000'); return { agentId: agentId, buildId: buildId }; });
+                // A pending switch's target build is leased until the switch ran (fix round 1): GC must not take it first.
+                for (const { agentId, intent } of await this.switchIntents().catch(() => [])) {
+                    if (intent.toBuild !== undefined)
+                        leased.push({ agentId, buildId: intent.toBuild });
+                }
+                const report = await collectBuilds({ store: this.builds, running, leased, lastSeen: this.buildSeen, seenByDefault: this.startedAt,
+                    now: options.now ?? Date.now(), ...(options.graceMs !== undefined ? { graceMs: options.graceMs } : {}) });
+                if (report.skipped) {
+                    console.info(`[acp-builds] GC skipped: ${report.skipped}`);
+                    return report;
+                }
+                const legacyRemoved = await collectLegacy({ store: this.builds, commandLines: await processCommandLines() });
+                return { ...report, legacyRemoved };
+            }
+            catch (error) {
+                console.warn(`[acp-builds] GC failed: ${errorMessage(error)}`);
+                return undefined;
+            }
+            finally {
+                if (this.collecting === run)
+                    this.collecting = undefined;
+            }
+        })();
+        this.collecting = run;
+        return run;
+    }
+    /** Whether this daemon holds (or is about to respawn) a session on older generation `gen`. */
+    holds(gen) {
+        // A generation that could not be listed may host running adapters nobody adopted yet (final review finding 3).
+        return this.unlistedGens.has(gen) || [...this.heldOnOlder.values()].includes(gen);
+    }
+    /** A session of this daemon on an older generation ended: that generation may be idle now. */
+    olderSessionClosed(sessionKey, also) {
+        // A reopen's retire keeps the hold: the respawn goes into the same generation right behind it (fix round 2).
+        if (!this.reopenHolds.has(sessionKey))
+            this.heldOnOlder.delete(sessionKey);
+        void this.retireIdleGenerations();
+        return also?.();
+    }
+    /**
+     * A keeper-hosted session degraded (keeper-acp gone, or poisoned): its outbox head is remembered, so a later open of the ref that
+     * has to run in the daemon numbers above it and reports the gap (fix round 1, minor 4).
+     */
+    recordDegraded(sessionKey, gen) {
+        return (headSeq) => {
+            this.keeperHeads.set(sessionKey, Math.max(this.keeperHeads.get(sessionKey) ?? 0, headSeq));
+            if (!this.keeperOwner.has(sessionKey))
+                this.keeperOwner.set(sessionKey, gen);
+        };
+    }
+    /**
+     * Older keeper-acp generations that host no running adapter any more are stopped (the current one adopts what they kept). One pass
+     * at a time (Task 24): two concurrent passes would both stop the same generation, and the second one's listing reconnects to it
+     * while the first one asks it to stop — a pass asked for meanwhile runs once more afterwards.
+     */
+    retireIdleGenerations() {
+        if (this.retiringGenerations) {
+            this.retireAgain = true;
+            return this.retiringGenerations;
+        }
+        this.retiringGenerations = (async () => {
+            do {
+                this.retireAgain = false;
+                await this.retireIdleGenerationsOnce();
+            } while (this.retireAgain);
+        })().finally(() => { this.retiringGenerations = undefined; });
+        return this.retiringGenerations;
+    }
+    async retireIdleGenerationsOnce() {
+        const generations = this.generations;
+        if (!generations)
+            return;
+        try {
+            const current = await generations.current();
+            let stopped = false;
+            for (const gen of await generations.live()) {
+                if (gen === current)
+                    continue;
+                // Never while a session this daemon holds (or is spawning) lives there, its adapter exited or not (fix round 1, minor 7).
+                if (this.holds(gen))
+                    continue;
+                // Asked again after keeper-acp's own listing: a reopen may have taken a hold meanwhile (fix round 2).
+                if (await generations.stopIfIdle(gen, () => this.holds(gen))) {
+                    stopped = true;
+                    for (const [key, owner] of this.keeperOwner)
+                        if (owner === gen)
+                            this.keeperOwner.delete(key);
+                }
+            }
+            // The current generation adopts the kept sessions now (keeper-acp's `acp.list` adopts directories whose keeper is gone), so the
+            // next offer lists them without waiting for its periodic adoption (fix round 1, minor 5).
+            if (stopped && this.transports.keeper) {
+                for (const summary of await withDeadline(this.transports.keeper.list(), this.leftoverListTimeoutMs, 'keeper-acp list', Error)) {
+                    if (!hostsRunningAdapter(summary))
+                        this.noteKeeperSession(current, summary);
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`[acp] retiring idle keeper-acp generations failed: ${errorMessage(error)}`);
+        }
+    }
+    /**
+     * What the local transport holds under `sessionKey` from an earlier life (a fallback session's outbox, a migrated legacy journal):
+     * the highest seq it ever held and whether frames past its watermark remain. `undefined`: nothing.
+     */
+    async localLeftover(sessionKey) {
+        let summary;
+        try {
+            summary = (await this.localTransport().list()).find((s) => s.sessionKey === sessionKey);
+        }
+        catch {
+            return undefined;
+        }
+        if (!summary)
+            return undefined;
+        const tail = summary.outbox.committedTail;
+        const tailSeq = typeof tail?.seq === 'number' ? tail.seq : 0;
+        return {
+            lastSeq: Math.max(summary.outbox.lastSeq ?? 0, tailSeq),
+            unacknowledged: summary.outbox.next > Math.max(summary.outbox.first, summary.outbox.committed + 1),
+        };
+    }
+    /**
+     * Sessions an earlier life left in either transport that no live session holds (spec §5.5.2: the resume offer lists them as
+     * orphans): local outboxes, and keeper-acp's sessions once this daemon may use keeper-acp (its sweep succeeded). The caller
+     * removes the refs it holds. keeper-acp that does not answer in time contributes nothing (the offer must not wait on it).
+     */
+    async leftoverSessions() {
+        const keys = new Set();
+        try {
+            for (const summary of await this.localTransport().list())
+                keys.add(summary.sessionKey);
+        }
+        catch (error) {
+            console.warn(`[acp] listing local agent outboxes failed: ${errorMessage(error)}`);
+        }
+        if (this.transports.keeper && (this.adoption || this.ownKeeperKeys.size > 0)) {
+            await this.adoptKeeperSessions();
+            for (const [gen, transport] of await this.keeperTransports()) {
+                try {
+                    for (const summary of await withDeadline(transport.list(), this.leftoverListTimeoutMs, 'keeper-acp list', Error)) {
+                        // A running adapter in a generation the adoption has not listed yet is not an orphan: it is adopted on the next retry
+                        // (final review finding 3) — offered as an orphan, the server would end its turn and reopen it into a new spawn.
+                        if (gen !== undefined && this.unlistedGens.has(gen) && hostsRunningAdapter(summary))
+                            continue;
+                        // The ref, not the key: a switched session lives under `<ref>#s<n>` (Task 24).
+                        keys.add(refOfSession(summary) ?? summary.sessionKey);
+                        if (gen !== undefined && !hostsRunningAdapter(summary))
+                            this.noteKeeperSession(gen, summary);
+                    }
+                }
+                catch (error) {
+                    console.warn(`[acp] listing keeper-acp sessions${gen ? ` (generation ${gen})` : ''} for the resume offer failed: ${errorMessage(error)}`);
+                }
+            }
+        }
+        return [...keys].sort();
+    }
+    /**
+     * keeper-acp's transports by generation: every running one when the generations are known (the current one also when this daemon
+     * used it, or session directories wait for it — nothing is launched just to be listed), else the current one alone.
+     */
+    async keeperTransports() {
+        if (!this.transports.keeper)
+            return [];
+        const generations = this.generations;
+        if (!generations)
+            return [[undefined, this.transports.keeper]];
+        try {
+            const current = await generations.current();
+            const gens = new Set(await generations.live());
+            if (!gens.has(current) && (this.ownKeeperKeys.size > 0 || await generations.hasSessionData()))
+                gens.add(current);
+            return Promise.all([...gens].map(async (gen) => [gen, await generations.transportFor(gen)]));
+        }
+        catch {
+            return [[undefined, this.transports.keeper]];
+        }
+    }
+    /** `agent_close` for a ref no live session holds: whatever an earlier life left under it goes (its adapter stopped first). */
+    async releaseLeftover(sessionRef) {
+        const keeper = this.transports.keeper && (this.adoption || this.ownKeeperKeys.size > 0) ? (await this.keeperTransports()).map(([, t]) => t) : [];
+        for (const transport of [this.localTransport(), ...keeper]) {
+            try {
+                // Every key of the ref (`<ref>`, and `<ref>#s<n>` after a switch — Task 24).
+                for (const summary of (await transport.list()).filter((s) => s.sessionKey === sessionRef || refOfSession(s) === sessionRef)) {
+                    const key = summary.sessionKey;
+                    this.keeperOwner.delete(key);
+                    this.keeperHeads.delete(key);
+                    this.unrecoverable.delete(key);
+                    if (summary.process.state !== 'none' && summary.process.state !== 'exited')
+                        await transport.terminate(key);
+                    await transport.release(key);
+                }
+            }
+            catch (error) {
+                console.warn(`[acp] releasing what an earlier life left for ${sessionRef} failed: ${errorMessage(error)}`);
+            }
+        }
+        this.refKeys.delete(sessionRef);
+    }
+    /**
+     * A legacy `agents/sessions/<ref>.jsonl` (Task 20 removed the daemon journal): its entries become a local outbox under the ref,
+     * which the resume offer lists and a reopen resends, exactly as the journal was. Done once per file; idempotent. `false`: a local
+     * outbox for the ref already existed and was left as it is.
+     */
+    async importLegacyOutbox(sessionKey, records) {
+        const local = this.localTransport();
+        if (!(local instanceof LocalTransport))
+            throw new Error('The local transport cannot import an outbox');
+        return local.importOutbox(sessionKey, records);
+    }
+    /** The fallback transport (spec §5.7), made on first use. */
+    localTransport() {
+        this.transports.local ??= new LocalTransport({ configDir: this.cacheDir });
+        return this.transports.local;
+    }
+    /** Daemon shutdown: keeper-acp's connection is dropped (its adapters keep running); local adapters are stopped. */
+    closeTransports() {
+        this.clearQuotaReaders();
+        this.transports.keeper?.close();
+        this.generations?.close();
+        this.transports.local?.close();
+    }
+    clearQuotaReaders(agentId) {
+        for (const [key, reader] of this.quotaReaders)
+            if (!agentId || reader.agentId === agentId) {
+                this.quotaReaders.delete(key);
+                void reader.pending.then(connection => connection.close()).catch(() => undefined);
+            }
+    }
+    /**
+     * 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.
+     * Manual configuration refresh opts out of both fallbacks with `requireSessionLoad`: a failed
+     * load must not silently replace the conversation whose settings the reader wanted to refresh.
+     *
+     * Every decision is the daemon's, made on the processor's `initialize` reading; each attempt is one `agent_session_open` note
+     * and the processor's result. A load's history window is closed (`historyEnd`) as soon as its result is in — before the
+     * manager can admit a prompt (interface-contracts: `historyEnd` before any admitted prompt). The Qoder repair goes on where
+     * `enableBackgroundTerminalRepair` was called: after the `agent_session_open` note of a load (before its history is folded),
+     * after the result of a new or resumed session — a resume with `restoreCalls`.
+     */
+    async startSession(session, facts, spec) {
+        const nativeSessionId = spec.nativeSessionId;
+        const capabilities = facts.capabilities;
+        if (nativeSessionId && spec.managedHistoryResumeRequired) {
+            throw new Error('Managed native history replay has no certified boundary');
+        }
+        if (spec.delegationMcp && !capabilities.mcpHttp) {
+            throw new Error(`Agent '${spec.agentId}' does not advertise HTTP MCP support`);
+        }
+        if (spec.requireSessionLoad && !nativeSessionId) {
+            throw new Error('Refreshing settings requires an existing native session ID');
+        }
+        const historyHome = spec.agentEnv.HOME ?? spec.env.HOME ?? homedir();
+        // The finished MCP list (the lease checked here, against the clock, before any note is written); the bearer is a secretRef
+        // in the note and the down record, its value only in this daemon's memory and the adapter's stdin (spec §13).
+        const servers = buildSessionMcpServers(spec.mcpServers, spec.delegationMcp);
+        const redact = [];
+        const mcpServers = servers.map((server) => {
+            if (!('headers' in server) || !spec.delegationMcp || server.name !== 'axom-delegation')
+                return server;
+            return { ...server, headers: server.headers.map((header) => {
+                    const ref = session.secret(header.value);
+                    redact.push(ref);
+                    return { ...header, value: ref };
+                }) };
+        });
+        const delegation = spec.delegationMcp && spec.delegation ? {
+            expiresAtEpochMs: spec.delegationMcp.expiresAtEpochMs, leaseId: spec.delegation.leaseId,
+            ...(spec.delegation.bindingId !== undefined && spec.delegation.instanceId !== undefined
+                ? { bindingId: spec.delegation.bindingId, instanceId: spec.delegation.instanceId } : {}),
+        } : undefined;
+        const request = { cwd: spec.cwd, mcpServers, redact, ...(delegation ? { delegation } : {}) };
+        const refused = (result) => (result.code !== undefined ? new RequestError(result.code, result.error) : new Error(result.error));
+        // Qoder's load may emit old chunks after its response. Cached reconnects need context, not
+        // another history import. Actual adoption/backfill and explicit settings loads still use load.
+        if (nativeSessionId && certifiedRuntime(facts.agentInfo) && capabilities.resume &&
+            !spec.backfill && !spec.requireSessionLoad && !spec.delegationMcp) {
+            const result = await session.openSession({ ...request, mode: 'resume', sessionId: nativeSessionId });
+            if (!result.ok)
+                throw refused(result); // Never silently replace this cached conversation with a fresh native root.
+            await session.enableRepair(nativeSessionId, spec.cwd, historyHome, true);
+            return { nativeSessionId };
+        }
+        if (nativeSessionId) {
+            if (!capabilities.loadSession) {
+                if (spec.requireSessionLoad || spec.delegationMcp)
+                    throw new Error(`Agent '${spec.agentId}' does not support session/load`);
+                console.warn(`[acp] agent '${spec.agentId}' does not support session/load; starting a new session ` +
+                    `instead of continuing '${nativeSessionId}'`);
+            }
+            else {
+                const result = await session.openSession({ ...request, mode: 'load', sessionId: nativeSessionId, repair: { historyHome } });
+                if (result.ok) {
+                    await session.endHistory();
+                    return { nativeSessionId };
+                }
+                if (spec.requireSessionLoad || spec.delegationMcp)
+                    throw refused(result);
+                console.warn(`[acp] session/load for '${nativeSessionId}' on agent '${spec.agentId}' failed ` +
+                    `(${result.error}); starting a new session instead`);
+            }
+        }
+        const result = await session.openSession({ ...request, mode: 'new' });
+        if (!result.ok)
+            throw refused(result);
+        if (result.nativeSessionId)
+            await session.enableRepair(result.nativeSessionId, spec.cwd, historyHome);
+        return { nativeSessionId: result.nativeSessionId };
+    }
+    /**
+     * 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(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);
+        }
+    }
+    /**
+     * Delete native sessions over `session/delete`, via a throwaway connection. Per-id outcomes; an
+     * agent that does not advertise `sessionCapabilities.delete` yields `unsupported` for every id
+     * without the method being called. A *connection* failure still throws.
+     */
+    async deleteNativeSessions(spec, ids) {
+        const resolved = await this.resolveLaunchFor(spec.agentId, spec.command, spec.args);
+        const connection = await this.connectResolved(resolved, spec.env, spec.agentEnv);
+        this.observe(spec.agentId, observationOf(connection));
+        try {
+            return await deleteNativeSessions(connection, ids);
+        }
+        finally {
+            await connection.close().catch(() => undefined);
+        }
+    }
+    /** Explicit quota read, called only from an admitted footer refresh. */
+    async minimumAccountLimitsVersion(spec) {
+        if (spec.command)
+            return 2;
+        const current = await this.builds.current(spec.agentId);
+        return current ? nativeAccountLimitsVersionFor(current.agentId, current.version) : 2;
+    }
+    async readAccountLimits(spec) {
+        // Readers that need interactive credential authorization retain their process-local cache.
+        // Keeping this control connection alive performs no model calls or periodic quota queries.
+        const cached = (await this.minimumAccountLimitsVersion(spec)) >= 3;
+        const key = createHash('sha256').update(JSON.stringify(spec)).digest('hex');
+        let pending = this.quotaReaders.get(key)?.pending;
+        if (!cached || !pending) {
+            pending = this.connectFor(spec, 30_000);
+            if (cached) {
+                this.quotaReaders.set(key, { agentId: spec.agentId, pending });
+                void pending.catch(() => { if (this.quotaReaders.get(key)?.pending === pending)
+                    this.quotaReaders.delete(key); });
+            }
+        }
+        const connection = await pending;
+        try {
+            const raw = await withDeadline(connection.connection.agent.request("_axom/account/rateLimits/read", { cwd: spec.cwd }), ACCOUNT_LIMITS_READ_TIMEOUT_MS, 'Refreshing account usage');
+            const { accountLimitsSchema } = await import('../protocol/accountLimits.js');
+            return accountLimitsSchema.parse(raw);
+        }
+        catch (error) {
+            // A provider's RPC error can be retried with the same credential cache. A dead transport cannot.
+            if (cached && typeof error?.code !== 'number') {
+                this.quotaReaders.delete(key);
+                await connection.close().catch(() => undefined);
+            }
+            throw error;
+        }
+        finally {
+            if (!cached)
+                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 probe = createCommandTableProbe();
+        const connection = await this.connectFor(spec, timeoutMs, undefined, probe);
+        const authMethods = connection.authMethods;
+        this.observe(spec.agentId, observationOf(connection));
+        try {
+            let observed;
+            let observedConfig;
+            const started = Date.now();
+            await withDeadline((async () => {
+                const first = await observeCommands(probe, connection, spec.cwd, COMMAND_FIRST_BROADCAST_MS);
+                observedConfig = first.configOptions;
+                observed = first.commands;
+            })(), timeoutMs, `Opening a session on agent '${spec.agentId}'`);
+            if (observed === undefined) {
+                // p3-fix7 N9: "no table within the window" is unknown, not "this agent has no commands": look once more, with a
+                // longer window. p3-fix7b M-4: on a fresh connection (this one is bound to the first session, so a table pushed
+                // before the retry's session/new answer would read as a stranger's). p3-fix7c 3: the retry is only a second
+                // look for the table — its failure, or the deadline running out during it, leaves the table unknown and never
+                // turns a session that opened into a sessionError.
+                observed = await this.retryCommandTable(spec, timeoutMs - (Date.now() - started));
+            }
+            if (observed === undefined) {
+                // A 那条日志的 daemon 侧对应物。没有它,"这个 agent 在这个目录下没有命令" 与
+                // "表来晚了、窗口没接住" 在任何一层都分不开 —— 而这两件事的修法完全不同。
+                console.warn(`[acp] agent '${spec.agentId}' broadcast no command table within ` +
+                    `${COMMAND_FIRST_BROADCAST_MS}ms (and ${this.commandRetryFirstBroadcastMs}ms on a second session) ` +
+                    `of opening a session in ${spec.cwd}`);
+            }
+            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);
+        }
+    }
+    /** p3-fix7c 3: one more look for the command table on a fresh connection; undefined on any failure or timeout. */
+    async retryCommandTable(spec, remainingMs) {
+        if (remainingMs <= 0)
+            return undefined;
+        let retryConnection;
+        let abandoned = false;
+        try {
+            return await withDeadline((async () => {
+                const probe = createCommandTableProbe();
+                const connection = await this.connectFor(spec, remainingMs, undefined, probe);
+                retryConnection = connection;
+                // The deadline may already have fired while connecting: nobody will close it after this point but us.
+                if (abandoned) {
+                    await connection.close().catch(() => undefined);
+                    return undefined;
+                }
+                return (await observeCommands(probe, connection, spec.cwd, this.commandRetryFirstBroadcastMs)).commands;
+            })(), remainingMs, `Looking again for agent '${spec.agentId}''s command table`);
+        }
+        catch (error) {
+            abandoned = true;
+            console.warn(`[acp] retry for agent '${spec.agentId}''s command table failed: ${errorMessage(error)}`);
+            return undefined;
+        }
+        finally {
+            await retryConnection?.close().catch(() => undefined);
+        }
+    }
+    /**
+     * Run one agent's `authenticate` for a `methodId` **it advertised**, over a throwaway connection —
+     * or, for a terminal-type method, run the sign-in itself ({@link hostTerminalLogin}): ACP forbids
+     * passing a terminal method to `authenticate`, and the workstation is the terminal's host (spec
+     * 2026-09-24 D6/D12).
+     *
+     * The refusal for an unadvertised non-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 = {}) {
+        this.clearQuotaReaders(spec.agentId);
+        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 {
+            // Spec 2026-09-24 D10: a sign-in almost always follows the connection that hit
+            // `auth_required`, which already read this method. Reuse it rather than cold-start the agent.
+            const remembered = this.observed.get(spec.agentId)?.terminalLogins?.get(methodId);
+            if (remembered) {
+                await this.hostTerminalLogin(spec, remembered, urls.present, login);
+                return;
+            }
+            const connection = await this.connectFor(spec, AGENT_PROBE_TIMEOUT_MS, {
+                ...(urls.present ? { present: urls.present } : {}),
+                dismiss: urls.dismiss,
+            });
+            this.observe(spec.agentId, observationOf(connection));
+            const terminal = connection.terminalLogins.get(methodId);
+            if (terminal) {
+                // ACP: a terminal method is never passed to `authenticate`. This connection has nothing
+                // left to do, and a login can take minutes — do not hold an agent process open for it.
+                await connection.close().catch(() => undefined);
+                await this.hostTerminalLogin(spec, terminal, urls.present, login);
+                return;
+            }
+            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();
+        }
+    }
+    /**
+     * Run a terminal sign-in on this machine (spec 2026-09-24 D7, D9). The launch is resolved the same
+     * way a session's is, because the standard shape appends to it; the `_meta` shape ignores it.
+     */
+    async hostTerminalLogin(spec, terminal, present, login) {
+        // The launch is resolved for both shapes, and for the same reason a session's is: its env is
+        // the login child's environment. The `_meta` shape keeps the invocation's own command and args
+        // (see `launchForTerminalLogin`) but rides the resolved launch's env — a login that seeded a
+        // different credential slot than the sessions it was logging in for would be a no-op for them.
+        const launch = launchForTerminalLogin(terminal, (await this.resolveLaunchFor(spec.agentId, spec.command, spec.args)).launch);
+        await runTerminalLogin(terminalInvocationFor(terminal, launch, { ...spec.env, ...spec.agentEnv }), {
+            ...(present ? { present } : {}),
+            ...(login.signal ? { signal: login.signal } : {}),
+            deadlineMs: loginDeadlineMs(login.ceilingMs),
+        });
+    }
+    /**
+     * 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
@@ -782,21 +2457,24 @@ export class AcpAgents {
      * `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) {
+    async connectFor(spec, timeoutMs, login, probe) {
         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 });
+        if (!login) {
+            return this.connectResolved(resolved, spec.env, spec.agentEnv, {
+                initializeTimeoutMs: timeoutMs, ...(probe ? { configure: (app) => probe.configure(app) } : {}),
+            });
+        }
         const options = {
             initializeTimeoutMs: timeoutMs,
             ...(login.present ? { present: login.present } : {}),
-            configure: (app) => {
+            configure: (app, adapter) => {
                 // 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
+                // The sink is deferred and never bound, deliberately: there is no session 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
@@ -804,117 +2482,53 @@ export class AcpAgents {
                 registerPermissionHandlers(app, createDeferredPermissionSink().sink, {
                     present: login.present,
                     dismiss: login.dismiss ?? (() => { }),
-                });
+                }, adapter);
             },
         };
-        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 };
+        return connectAgent(resolved.launch, spec.env, spec.agentEnv, options);
     }
     /**
-     * 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.
+     * Install (or Update) one agent's ACP adapter and make it the agent's **current build** — the only
+     * thing, besides a CLI-certified change ({@link reconcileCertifiedBuilds}), that moves the pointer
+     * new sessions launch from (spec §6.1). What the settings page's Install / Update / Config does.
      *
-     * ## Why an explicit step exists at all
+     * ## Builds, not caches
      *
-     * `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.
+     * npm and binary adapters are installed into daemon-owned, immutable, versioned directories under
+     * `<configDir>/acp-adapters/` (`builds/model.ts`), staged and renamed into place whole, then
+     * recorded in `builds.json`. A new install never touches a directory a running adapter is loading
+     * from, and `open` never downloads anything: it launches the current build or fails with
+     * {@link AdapterNotInstalledError}. A registry version bump only makes the card offer Update.
+     * Install, switch and GC of one agent are serialised ({@link BuildStore.withAgentLock}), so two
+     * concurrent Updates download once. The uvx path still installs into `uv tool dir` until Task 15b.
      *
      * ## 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
+     * `ok` with `alreadyInstalled` means there was nothing to download. `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
+     * ## The catalog's `prerequisite` 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:
+     * `registry/catalog.ts` may curate one prerequisite for an agent (`pi-acp` needs the `pi` CLI,
+     * `zcode-acp` the ZCode desktop app) that the adapter fetch above does nothing to provide. That
+     * block is handled *before* the adapter step, in up to three 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
+     *    mismatch. Failing this gate returns `nodeTooOld` and runs no command at all.
+     * 2. its `detect` (`registry/detect.ts`) — only when that finds nothing 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).
+     * 3. a prerequisite with no `install` argv cannot be fetched by anyone but the reader, so a missing
+     *    one refuses with the catalog's `hint` as the error and fetches no adapter either.
      *
-     * 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}.
+     * Never starts the agent.
      */
     async install(agentId, options = {}) {
-        const dependency = catalogEntryFor(agentId)?.dependency;
+        const dependency = catalogEntryFor(agentId)?.prerequisite;
         if (dependency) {
             const nodeVersion = options.nodeVersion ?? process.version;
             if (dependency.requiresNode && !semver.satisfies(nodeVersion, dependency.requiresNode)) {
@@ -927,7 +2541,13 @@ export class AcpAgents {
             }
         }
         let dependencyInstalled;
-        if (dependency && findOnPath(dependency.check, this.probe) === undefined) {
+        if (dependency && !this.prerequisiteSatisfied(agentId)) {
+            if (!dependency.install) {
+                return {
+                    ok: false,
+                    error: dependency.hint ?? `Agent '${agentId}' needs ${dependency.label}, which is not installed on this machine.`,
+                };
+            }
             const [command, ...args] = dependency.install;
             const outcome = await this.runCommand(command, args, { timeoutMs: options.timeoutMs });
             if (!outcome.ok) {
@@ -935,12 +2555,11 @@ export class AcpAgents {
             }
             dependencyInstalled = true;
         }
-        const agents = await this.registry.load();
-        const agent = agents.find((candidate) => candidate.id === agentId);
-        if (!agent) {
+        const entry = (await this.effective()).find((candidate) => candidate.agent.id === agentId);
+        if (!entry) {
             return { ok: false, error: `Agent '${agentId}' is not in the ACP agent registry.` };
         }
-        const outcome = await this.installAdapter(agent, options.timeoutMs);
+        const outcome = await this.builds.withAgentLock(agentId, () => this.installAdapter(entry, 'user', options.timeoutMs));
         if (!outcome.ok)
             return outcome;
         return {
@@ -951,60 +2570,86 @@ export class AcpAgents {
             ...(outcome.pinnedVersionUnavailable ? { pinnedVersionUnavailable: outcome.pinnedVersionUnavailable } : {}),
         };
     }
+    /** The registry as Axom installs it (catalog supplements, pins, launchEnv kept apart) — see `registry/catalog.ts`. */
+    async effective() {
+        return effectiveEntries(await this.baseRegistry.load());
+    }
     /**
-     * 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
+     * Install one agent's adapter through **whichever distribution it actually ships**, dispatching
+     * npx → uvx → binary, then commit the build and make it current. The caller holds the agent's lock.
      *
-     * 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.
+     * `unsupported` means one of two things: the entry declares no launchable distribution at all, or
+     * it is binary-only and publishes no archive for **this machine's** platform triple. Every other
+     * failure is an ordinary `error` the reader can retry, and leaves the current build untouched.
+     */
+    async installAdapter(entry, setBy, timeoutMs, 
+    /**
+     * The certified reconcile's current build: if the install lands on that same build, its record is
+     * refreshed but the pointer (and `currentSetBy`) is left alone — that is not a move.
      */
-    async installAdapter(agent, timeoutMs) {
+    currentBuildId) {
+        const agent = entry.agent;
         const { npx, uvx, binary } = agent.distribution;
+        const source = entry.pinnedBy ?? 'registry';
+        const commit = (build) => this.builds.commit(build, { makeCurrent: build.buildId !== currentBuildId, setBy });
         if (npx) {
-            return this.installNpxWithFallback(agent, npx.package, timeoutMs);
+            const pristine = await this.installPristineWithFallback(agent, npx.package, timeoutMs);
+            if (!pristine.ok)
+                return pristine;
+            try {
+                const build = await npmBuild({
+                    store: this.builds, agentId: agent.id, name: npmPackageName(npx.package), version: pristine.version,
+                    args: npx.args ?? [], env: npx.env ?? {}, registryVersion: entry.registryVersion,
+                    source: pristine.pinnedVersionUnavailable ? 'unpinned-fallback' : source, installedBy: setBy,
+                    nodePath: this.nodePath,
+                    ...(this.patchRecipes ? { recipes: this.patchRecipes } : {}),
+                });
+                const recorded = pristine.pinnedVersionUnavailable
+                    ? { ...build, requestedVersion: requestedVersionOf(entry) }
+                    : build;
+                await commit(recorded);
+                return {
+                    ok: true, alreadyInstalled: !pristine.downloaded, build: recorded,
+                    ...(pristine.pinnedVersionUnavailable ? { pinnedVersionUnavailable: pristine.pinnedVersionUnavailable } : {}),
+                };
+            }
+            catch (error) {
+                logInstallFailureDetail(agent.id, 'npx', npx.package, String(error));
+                // The Node gate: the package's own engines.node refuses the Node it would run on. Not current.
+                if (error instanceof AdapterNodeVersionError) {
+                    return { ok: false, error: error.message, nodeTooOld: { required: error.required, found: error.found } };
+                }
+                return { ok: false, error: `Adapter build preparation failed: ${errorMessage(error)}` };
+            }
         }
         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) };
+            // A per-version build under `uv/<pkg>/<version>/` (`builds/install/uv.ts`): its own UV_TOOL_DIR
+            // and UV_TOOL_BIN_DIR, never the user's uv tools or `~/.local/bin`; launch never runs `uv`.
+            const outcome = await installUvBuild({
+                store: this.builds, agentId: agent.id, spec: uvx.package, args: uvx.args ?? [], env: uvx.env ?? {},
+                registryVersion: entry.registryVersion, source, installedBy: setBy, runUv: this.runUv,
+                timeoutMs: timeoutMs ?? UV_TOOL_INSTALL_TIMEOUT_MS,
+            }).catch((error) => ({ ok: false, error: errorMessage(error), uvMissing: undefined }));
+            if (!outcome.ok) {
+                const existingVersion = (await this.builds.current(agent.id))?.version;
+                logInstallFailureDetail(agent.id, 'uvx', uvx.package, outcome.error);
+                // `uv` itself is absent: retrying will not help, installing uv will.
+                if (outcome.uvMissing)
+                    return { ok: false, error: friendlyUvMissingError(agent.id, existingVersion) };
+                return { ok: false, error: friendlyOrdinaryInstallError(agent.id, outcome.error, existingVersion) };
+            }
+            try {
+                await commit(outcome.build);
+                return { ok: true, alreadyInstalled: !outcome.downloaded, build: outcome.build };
+            }
+            catch (error) {
+                return { ok: false, error: errorMessage(error) };
+            }
         }
         if (binary) {
             const triple = platformTriple(this.platform, this.arch);
-            if (!triple || !binaryTargetFor(agent, triple)) {
+            const target = triple ? binaryTargetFor(agent, triple) : undefined;
+            if (!triple || !target) {
                 return {
                     ok: false,
                     unsupported: true,
@@ -1015,16 +2660,26 @@ export class AcpAgents {
                 root: this.adapterRoot,
                 platform: this.platform,
                 arch: this.arch,
+                ...(this.binaryFetch ? { fetch: this.binaryFetch } : {}),
             });
-            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) };
+            if (!outcome.ok) {
+                // `installBinary` never touches another version's tree (it stages, then renames), so what
+                // survives the attempt is exactly the current build.
+                const existingVersion = (await this.builds.current(agent.id))?.version;
+                logInstallFailureDetail(agent.id, 'binary', agent.version, outcome.error);
+                return { ok: false, error: friendlyOrdinaryInstallError(agent.id, outcome.error, existingVersion) };
+            }
+            try {
+                const build = binaryBuild({
+                    root: this.adapterRoot, agentId: agent.id, version: outcome.version, target, env: target.env ?? {},
+                    registryVersion: entry.registryVersion, source, installedBy: setBy,
+                });
+                await commit(build);
+                return { ok: true, alreadyInstalled: outcome.alreadyInstalled, build };
+            }
+            catch (error) {
+                return { ok: false, error: errorMessage(error) };
+            }
         }
         return {
             ok: false,
@@ -1033,255 +2688,433 @@ export class AcpAgents {
         };
     }
     /**
-     * `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.
+     * The npm half of {@link installAdapter}: the pinned version into `npm/<sha16(name)>/<version>/pristine`
+     * and, when — and only when — npm answers `ETARGET` (the registry pinned a version npm does not
+     * have), one retry unpinned, recording the version that actually landed. This is the **only** place
+     * that fallback exists now: a launch never resolves a version (spec §6.2 "ETARGET 回退移到安装期").
      */
-    async installNpxWithFallback(agent, pinnedSpec, timeoutMs) {
-        const outcome = await installNpxPackage(pinnedSpec, {
-            env: this.probe,
-            timeoutMs: timeoutMs ?? ADAPTER_INSTALL_TIMEOUT_MS,
-            npxCommand: this.npxCommand,
-        });
+    async installPristineWithFallback(agent, pinnedSpec, timeoutMs) {
+        const name = npmPackageName(pinnedSpec);
+        const version = npmPackageVersion(pinnedSpec);
+        const budget = timeoutMs ?? ADAPTER_INSTALL_TIMEOUT_MS;
+        const install = (pinned) => ensurePristine({
+            store: this.builds, name, ...(pinned !== undefined ? { version: pinned } : {}), npmCommand: this.npmCommand, timeoutMs: budget,
+        }).catch((error) => ({ ok: false, error: errorMessage(error), stderr: '' }));
+        const outcome = await install(version);
         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)) {
+            return outcome;
+        const existingVersion = (await this.builds.current(agent.id))?.version;
+        if (version === undefined || !stderrShowsMissingPackageVersion(outcome.stderr)) {
             logInstallFailureDetail(agent.id, 'npx', pinnedSpec, outcome.stderr || outcome.error);
-            return {
-                ok: false,
-                error: friendlyOrdinaryInstallError(agent.id, outcome.stderr || outcome.error, existingVersion),
-            };
+            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 ` +
+            `('${pinnedSpec}'): 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 ` +
+        console.warn(`[acp] retrying the install for agent '${agent.id}' once as '${name}', 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);
+        const retry = await install(undefined);
+        if (!retry.ok) {
+            logInstallFailureDetail(agent.id, 'npx', name, retry.stderr || retry.error);
             return {
                 ok: false,
-                error: friendlyPinnedVersionUnavailableAndFallbackFailed(agent.id, fallback.pinned, retryOutcome.stderr || retryOutcome.error, existingVersion),
+                error: friendlyPinnedVersionUnavailableAndFallbackFailed(agent.id, pinnedSpec, retry.stderr || retry.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 } } : {}),
+        return { ...retry, pinnedVersionUnavailable: { pinned: pinnedSpec, installedInstead: retry.version } };
+    }
+    /**
+     * Move installed agents forward to what **this CLI** certifies, without anyone pressing Update
+     * (spec §6.1 "由 Axom 更新"): an agent whose effective version is pinned by this CLI (runtime.json
+     * override, catalog pin or supplement) and differs from its current build, or whose current
+     * version would now be patched differently (a recipe added, changed or retired). The new build is
+     * installed and made current with `currentSetBy: 'axom'`; running sessions keep the build they
+     * were spawned from. Agents with no current build are left alone (nothing is installed to move),
+     * as is every registry-only version change — that is the user's Update to make.
+     *
+     * Never throws: failures are logged per agent and the old current stays. Reads no registry at all
+     * when no agent is installed, so a fresh machine starts without touching the network for this.
+     */
+    async reconcileCertifiedBuilds(options = {}) {
+        const moves = [];
+        let document;
+        try {
+            document = await this.builds.read();
+        }
+        catch (error) {
+            console.warn(`[acp-builds] cannot read builds: ${errorMessage(error)}`);
+            return moves;
+        }
+        const installed = Object.keys(document.agents).filter((agentId) => this.builds.currentIn(document, agentId));
+        if (!installed.length)
+            return moves;
+        let entries;
+        try {
+            entries = await this.effective();
+        }
+        catch (error) {
+            console.warn(`[acp-builds] registry unavailable, skipping certified build reconcile: ${errorMessage(error)}`);
+            return moves;
+        }
+        for (const agentId of installed) {
+            const entry = entries.find((candidate) => candidate.agent.id === agentId);
+            if (!entry)
+                continue;
+            try {
+                const move = await this.builds.withAgentLock(agentId, () => this.reconcileOne(entry, options.timeoutMs));
+                if (move)
+                    moves.push(move);
+            }
+            catch (error) {
+                console.warn(`[acp-builds] agent '${agentId}': certified build reconcile failed: ${errorMessage(error)}`);
+            }
+        }
+        return moves;
+    }
+    async reconcileOne(entry, timeoutMs) {
+        const agentId = entry.agent.id;
+        const current = await this.builds.current(agentId);
+        if (!current)
+            return undefined;
+        // The pin this CLI certifies was already tried and npm did not have it: the current build is the
+        // install-time fallback for exactly this pin. Trying again on every daemon start would only repeat
+        // the same network round trip and land on the same build.
+        const sameUnavailablePin = current.source === 'unpinned-fallback' && current.requestedVersion === requestedVersionOf(entry);
+        if (entry.pinnedBy && entry.agent.version !== current.version && !sameUnavailablePin) {
+            const outcome = await this.installAdapter(entry, 'axom', timeoutMs, current.buildId);
+            if (!outcome.ok)
+                throw new Error(outcome.error);
+            if (!outcome.build || outcome.build.buildId === current.buildId)
+                return undefined;
+            console.info(`[acp-builds] agent '${agentId}': moved ${current.buildId} -> ${outcome.build.buildId} (pinned by ${entry.pinnedBy})`);
+            return { agentId, from: current.buildId, to: outcome.build.buildId, reason: 'certified-pin' };
+        }
+        // Same version: does this CLI patch it differently from the build that is current?
+        if ((current.kind !== 'npm' && current.kind !== 'npm-patched') || !current.package)
+            return undefined;
+        const pristine = inside(this.adapterRoot, npmPristineDir(current.package, current.version));
+        const recipes = await selectPackagePatches(current.package, current.version, inside(path.join(pristine, 'node_modules'), current.package), this.patchRecipes);
+        const wanted = recipes.length ? patchDigest(recipes) : undefined;
+        if (wanted === current.patchDigest)
+            return undefined;
+        const build = await npmBuild({
+            store: this.builds, agentId, name: current.package, version: current.version,
+            args: current.launch.args, env: current.launch.env, registryVersion: current.registryVersion,
+            source: current.source, installedBy: 'axom', nodePath: this.nodePath,
+            ...(this.patchRecipes ? { recipes: this.patchRecipes } : {}),
+        });
+        await this.builds.commit(build, { makeCurrent: true, setBy: 'axom' });
+        console.info(`[acp-builds] agent '${agentId}': moved ${current.buildId} -> ${build.buildId} (patch set changed)`);
+        return { agentId, from: current.buildId, to: build.buildId, reason: 'patch-set' };
+    }
+    /**
+     * Take over what an older CLI left on this machine (spec §6.2 "迁移", `builds/migrate.ts`), for every
+     * agent that has no current build: an `_npx` copy of exactly the effective version, or pre-build
+     * binary directories. Run by the daemon at start, in the background; an open (or any launch) of an
+     * agent whose share has not run yet waits on that agent's lock instead of reporting it not installed.
+     *
+     * Idempotent (an agent with a current build is never touched) and once per agent per process. Reads
+     * no registry when there is nothing to migrate from (no `_npx`, no legacy directories). Never throws.
+     */
+    async migrateLegacyAdapters() {
+        const migrated = [];
+        let document;
+        try {
+            document = await this.builds.read();
+        }
+        catch (error) {
+            console.warn(`[acp-builds] cannot read builds, skipping migration: ${errorMessage(error)}`);
+            return migrated;
+        }
+        const hasNpx = existsSync(path.join(npmCacheDir(this.probe), '_npx'));
+        const legacy = new Set(await legacyAgentDirs(this.adapterRoot));
+        if (!hasNpx && !legacy.size)
+            return migrated;
+        let entries;
+        try {
+            entries = await this.effective();
+        }
+        catch (error) {
+            console.warn(`[acp-builds] registry unavailable, migration deferred to first open: ${errorMessage(error)}`);
+            return migrated;
+        }
+        for (const entry of entries) {
+            const agentId = entry.agent.id;
+            if (this.builds.currentIn(document, agentId))
+                continue;
+            const { npx, uvx, binary } = entry.agent.distribution;
+            if (npx ? !hasNpx : uvx || !binary || !legacy.has(agentId))
+                continue;
+            const result = await this.migrateAgent(agentId, entries);
+            if (result)
+                migrated.push(result);
+        }
+        return migrated;
+    }
+    /** {@link migrateLegacyAdapters} for one agent, at most once per process (shared by the daemon's sweep and every launch). */
+    migrateAgent(agentId, entries) {
+        let running = this.migrations.get(agentId);
+        if (!running) {
+            running = this.builds.withAgentLock(agentId, () => this.migrateOne(agentId, entries)).catch((error) => {
+                console.warn(`[acp-builds] agent '${agentId}': migration of the previous install failed: ${errorMessage(error)}`);
+                // A registry that could not be read is worth another try; anything else is not repeated.
+                if (error instanceof RegistryUnavailableForMigration)
+                    this.migrations.delete(agentId);
+                return undefined;
+            });
+            this.migrations.set(agentId, running);
+        }
+        return running;
+    }
+    async migrateOne(agentId, known) {
+        if (await this.builds.current(agentId))
+            return undefined;
+        const npmCache = npmCacheDir(this.probe);
+        const legacyVersions = await legacyBinaryVersions(this.adapterRoot, agentId);
+        const unrecorded = await legacyBinaryVersions(path.join(this.adapterRoot, 'bin'), agentId);
+        if (!legacyVersions.length && !unrecorded.length && !existsSync(path.join(npmCache, '_npx')))
+            return undefined;
+        let entries = known;
+        if (!entries) {
+            try {
+                entries = await this.effective();
+            }
+            catch (error) {
+                throw new RegistryUnavailableForMigration(errorMessage(error));
+            }
+        }
+        const entry = entries.find((candidate) => candidate.agent.id === agentId);
+        if (!entry)
+            return undefined;
+        const { npx, uvx, binary } = entry.agent.distribution;
+        if (npx)
+            return this.migrateFromNpx(entry, npx.package, npmCache);
+        // uv: the user's own uv tool dir is not ours to take over; the first open installs a build.
+        if (uvx || !binary)
+            return undefined;
+        return this.migrateLegacyBinaries(entry, legacyVersions, unrecorded);
+    }
+    /** npm: the effective version's `_npx` copy, as this agent's current build (pristine or patched, Node gate applied). */
+    async migrateFromNpx(entry, spec, npmCache) {
+        const agentId = entry.agent.id;
+        const name = npmPackageName(spec);
+        // Exactly what the pre-build launch ran: `npx <name>@<effective version>`.
+        const version = requestedVersionOf(entry);
+        const copy = await findNpxCopy(npmCache, name, version);
+        if (!copy)
+            return undefined;
+        const { copied } = await adoptNpxCopy({ store: this.builds, name, version, nodeModules: copy });
+        const npx = entry.agent.distribution.npx;
+        const build = {
+            ...await npmBuild({
+                store: this.builds, agentId, name, version, args: npx.args ?? [], env: npx.env ?? {},
+                registryVersion: entry.registryVersion, source: entry.pinnedBy ?? 'registry', installedBy: 'axom',
+                nodePath: this.nodePath, ...(this.patchRecipes ? { recipes: this.patchRecipes } : {}),
+            }),
+            migratedFrom: 'npx-cache',
+        };
+        await this.builds.commit(build, { makeCurrent: true, setBy: 'axom' });
+        console.info(`[acp-builds] agent '${agentId}': ${name}@${version} ${copied ? 'copied from' : 'already copied from'} ${copy} as build ${build.buildId}`);
+        return { agentId, from: 'npx-cache', current: build.buildId, builds: [build.buildId] };
+    }
+    /**
+     * binary: every pre-build `acp-adapters/<agent>/<version>` renamed in place into `bin/<agent>/<version>`
+     * and recorded (plus any `bin/<agent>/<version>` an interrupted migration renamed but never recorded);
+     * the one the pre-build launch picked — the pinned version if present, else the highest — is current.
+     */
+    async migrateLegacyBinaries(entry, legacyVersions, unrecorded) {
+        const agent = entry.agent;
+        const triple = platformTriple(this.platform, this.arch);
+        const target = triple ? binaryTargetFor(agent, triple) : undefined;
+        if (!target)
+            return undefined;
+        const recorded = [];
+        const record = (version) => {
+            try {
+                recorded.push({
+                    ...binaryBuild({
+                        root: this.adapterRoot, agentId: agent.id, version, target, env: target.env ?? {},
+                        registryVersion: entry.registryVersion, source: entry.pinnedBy ?? 'registry', installedBy: 'axom',
+                    }),
+                    migratedFrom: 'legacy-binary',
+                });
+            }
+            catch (error) {
+                console.warn(`[acp-builds] agent '${agent.id}' ${version}: not taken over: ${errorMessage(error)}`);
+            }
         };
+        for (const version of [...legacyVersions].sort()) {
+            let destination;
+            try {
+                destination = inside(this.adapterRoot, binaryBuildDir(agent.id, version));
+            }
+            catch {
+                continue;
+            }
+            // The old install unpacked in place: a directory without its executable is a killed unpack. Left alone.
+            const command = path.posix.normalize(target.cmd.replace(/\\/g, '/'));
+            if (!existsSync(path.join(this.adapterRoot, agent.id, version, ...command.split('/')))) {
+                console.warn(`[acp-builds] agent '${agent.id}' ${version}: no '${target.cmd}' in the old install; left where it is.`);
+                continue;
+            }
+            if (await moveLegacyBinary(this.adapterRoot, agent.id, version, destination))
+                record(version);
+        }
+        for (const version of unrecorded)
+            if (!recorded.some((build) => build.version === version))
+                record(version);
+        const pick = pickInstalledVersion(recorded.map((build) => build.version), agent.version);
+        if (pick === undefined)
+            return undefined;
+        for (const build of recorded)
+            await this.builds.commit(build, { makeCurrent: false, setBy: 'axom' });
+        const current = recorded.find((build) => build.version === pick);
+        await this.builds.commit(current, { makeCurrent: true, setBy: 'axom' });
+        console.info(`[acp-builds] agent '${agent.id}': took over ${recorded.map((build) => build.buildId).join(', ')}; current ${current.buildId}`);
+        return { agentId: agent.id, from: 'legacy-binary', current: current.buildId, builds: recorded.map((build) => build.buildId) };
+    }
+    /**
+     * Spec §6.2: an agent with no current build — after its migration, if any — is installed **once**,
+     * by the first open that needs it ("Installing <version>" on the session). That is what the pre-build
+     * npx launch did on every open; a uv tool the user had in their own uv dir is reinstalled the same
+     * way. Only npm and uv distributions: an open never fetched a binary agent, which still fails as not
+     * installed. Every later open launches the build and downloads nothing.
+     */
+    async installForOpen(agentId, onOutcome) {
+        if (await this.builds.current(agentId))
+            return;
+        await this.migrateAgent(agentId);
+        if (await this.builds.current(agentId))
+            return;
+        let entry;
+        try {
+            entry = (await this.effective()).find((candidate) => candidate.agent.id === agentId);
+        }
+        catch {
+            return;
+        }
+        // Not in the registry, or nothing an open may fetch: `launchSpecFor` says which.
+        if (!entry || !(entry.agent.distribution.npx || entry.agent.distribution.uvx))
+            return;
+        const found = entry;
+        const version = installingVersionOf(found);
+        const agentName = found.agent.name || agentId;
+        // Started once and never aborted: an open that gives up below leaves it running under the lock.
+        const install = this.builds.withAgentLock(agentId, async () => {
+            if (await this.builds.current(agentId))
+                return undefined;
+            const outcome = await this.installAdapter(found, 'user');
+            return outcome.ok ? { ok: true, agentName, version } : { ok: false, agentName, version, error: outcome.error };
+        }).catch((error) => ({ ok: false, agentName, version, error: errorMessage(error) }));
+        let timer;
+        const budget = new Promise((resolve) => { timer = setTimeout(() => resolve('budget'), this.openInstallBudgetMs); });
+        const settled = await Promise.race([install, budget]).finally(() => clearTimeout(timer));
+        if (settled === 'budget') {
+            void install.then((late) => {
+                if (late)
+                    console.info(`[acp-builds] agent '${agentId}': install of ${version} finished after its open gave up (${late.ok ? 'installed' : late.error})`);
+            });
+            throw new AdapterStillInstallingError(agentId, agentName, version);
+        }
+        if (!settled)
+            return;
+        onOutcome?.(settled);
+        if (!settled.ok)
+            throw new Error(settled.error);
     }
     /**
-     * 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.
+     * Whether the catalog's prerequisite for this agent (`registry/catalog.ts`'s `prerequisite`) is
+     * detected on this machine (`registry/detect.ts`) — 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 `prerequisite` 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
+     * {@link roster} makes the same reading for `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 prerequisite) 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)
+    prerequisiteSatisfied(agentId, probe = this.probe) {
+        const prerequisite = catalogEntryFor(agentId)?.prerequisite;
+        if (!prerequisite)
             return true;
-        return findOnPath(dependency.check, probe) !== undefined;
+        return detected(prerequisite.detect, probe, platformTriple(this.platform, this.arch));
     }
-    /** 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: {} } };
+    /**
+     * The spawn spec a new session of `agentId` launches with: its **current build** and nothing else
+     * — no npx, no download (spec §6.1/§6.2). The spec carries the build's `label`, and a JavaScript
+     * build must pass the Node gate (`builds/nodeGate.ts`). An agent with no current build first waits
+     * for its share of the legacy migration ({@link migrateLegacyAdapters}); still none → it fails with
+     * {@link AdapterNotInstalledError} — whatever its distribution: a uv agent too launches only from its
+     * build, never through `uv`. Only {@link open} goes on to install (once) — see `installForOpen`.
+     */
+    async launchSpecFor(agentId) {
+        let current = await this.builds.current(agentId);
+        if (!current) {
+            // What an older CLI left may still be on its way into the store (daemon start runs this in the
+            // background); wait for this agent's share of it rather than report it not installed.
+            await this.migrateAgent(agentId);
+            current = await this.builds.current(agentId);
+        }
+        if (current) {
+            this.touchBuild(agentId, current.buildId);
+            return launchForBuild(current, this.adapterRoot, {
+                nodePath: this.nodePath,
+                launchEnv: catalogLaunchEnv(agentId, current.registryVersion),
+                basePath: this.probe.path,
+            });
+        }
         const agents = await this.registry.load();
-        const agent = agents.find((candidate) => candidate.id === agentId);
-        if (!agent) {
+        if (!agents.some((candidate) => candidate.id === agentId)) {
             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),
-        };
+        throw new AdapterNotInstalledError(agentId);
+    }
+    /** A config-supplied `command` is the whole launch spec (ruling R3); otherwise the current build decides. */
+    async resolveLaunchFor(agentId, command, args) {
+        if (command)
+            return { launch: { command, args, env: {} }, source: 'command-override' };
+        return { source: 'registry', launch: await this.launchSpecFor(agentId) };
     }
     /**
      * 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.
+     * {@link connectFor}'s login one.
      *
      * **`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.
+     * through the route {@link open} and {@link listNativeSessions} take.
      */
-    async connectResolved(agentId, resolved, env, agentEnv, options = {}) {
-        return withUnpinnedFallback(agentId, resolved, (launch) => connectAgent(launch, env, agentEnv, options));
+    async connectResolved(resolved, env, agentEnv, options = {}) {
+        return connectAgent(resolved.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`.
+     * Whether this agent can be launched on this machine (see {@link roster}): with a current build it
+     * can; an npm or uv agent can be once installed (Install fetches it); a binary-only agent only with a
+     * current build. Reads nothing and spawns nothing.
      */
-    async resolvable(agent, uvTools) {
-        try {
-            await resolveLaunch(agent, this.platform, this.arch, this.adapterRoot, undefined, uvTools);
+    resolvable(agent, current) {
+        if (current)
             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);
+        const { npx, uvx } = agent.distribution;
+        return Boolean(npx || uvx);
     }
 }
 /**
- * Wrap one `AcpSession` plus the connection it runs on into the shape the manager holds.
+ * Opens one session on [connection] (a verification's own, short-lived) and collects the command table the agent broadcasts
+ * after `session/new` ({@link createCommandTableProbe}). `commands` undefined = no table arrived within [firstWindowMs]
+ * (unknown, not empty).
  *
- * 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.
+ * The table is broadcast *after* `session/new` is answered (`acp-agent.js:752-757`), so a verification that closed right after
+ * opening could never see it; and it can also arrive before this client has read that answer (p3-fix7 N9), which the probe
+ * keeps. 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. 不能靠一个固定的等待:一条都没来 → 到 [firstWindowMs] 就收工;来了第一条 →
+ * 改用安静期([COMMAND_QUIET_MS])收尾,并受 [COMMAND_SETTLE_CEILING_MS] 兜底。
  */
-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;
+async function observeCommands(probe, connection, cwd, firstWindowMs) {
+    const { raw, configOptions } = await probe.observe(connection, cwd, { firstWindowMs, quietMs: COMMAND_QUIET_MS, ceilingMs: COMMAND_SETTLE_CEILING_MS });
+    return { commands: raw?.map(toAvailableCommandWire), configOptions };
 }