@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/acp/acpAgents.js

@@ -10,8 +10,8 @@ import { homedir } from 'node:os';
  * 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/`), `connectAgent` (`acpClient.ts`) and `AcpSession`
- * (`acpSession.ts`).
+ * 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
  *
@@ -31,28 +31,48 @@ import { homedir } from 'node:os';
  * 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 { methods } from '@agentclientprotocol/sdk';
+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 { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import semver from 'semver';
-import { connectAgent, isMissingPackageVersion, jsonRpcErrorCode, stderrShowsMissingPackageVersion } from './acpClient.js';
-import { runTerminalLogin, terminalInvocationFor } from './terminalLogin.js';
-import { AcpSession } from './acpSession.js';
-import { createReplayCapture, deleteNativeSessions, 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 { 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, logInstallFailureDetail, } from './installErrors.js';
-import { ADAPTER_INSTALL_TIMEOUT_MS, installNpxPackage, npmPackageName, npxCacheVersion, probeEnvironment, readNpxCache, runDependencyInstall, } from './installProbe.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, withCatalogOverrides } from './registry/catalog.js';
+import { catalogEntryFor, catalogLaunchEnv, effectiveEntries, RECOMMENDED_RANK, withCatalogOverrides } from './registry/catalog.js';
 import { detected } from './registry/detect.js';
-import { resolveLaunch, unpinnedFallbackFor } from './registry/launch.js';
+import { launchForBuild, withPathPrefix } from './registry/launch.js';
 import { RegistryClient } from './registry/registryClient.js';
-import { preparePatchedLaunch } from './managedPatches.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);
 }
@@ -299,46 +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,
+        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
@@ -357,6 +380,105 @@ 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;
@@ -365,34 +487,108 @@ export class AcpAgents {
     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.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.registry = withCatalogOverrides(options.registry ?? new RegistryClient({ cacheDir: options.cacheDir }));
+        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
@@ -429,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();
@@ -438,42 +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.
@@ -487,15 +680,14 @@ 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.
                 //
                 // `prerequisiteMet` folds in the catalog's 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 —
+                // 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).
@@ -514,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
@@ -530,6 +726,18 @@ export class AcpAgents {
                 ...(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.
@@ -545,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,
@@ -558,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
@@ -584,12 +919,12 @@ 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 requestId = spec.openRequestId ?? randomUUID();
@@ -611,65 +946,34 @@ export class AcpAgents {
                 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 };
-        const capture = createReplayCapture();
-        const permissions = createDeferredPermissionSink();
-        let connection;
+        let session;
         try {
-            connection = await phase('initialize', () => this.connectResolved(spec.agentId, resolved, spec.env, spec.agentEnv, {
-                ...(startup ? { stderrSecrets: startup.secrets,
-                    onProcessExit: () => { void startup.dispose().catch(() => undefined); } } : {}),
-                // 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: () => { } });
-                },
-            }));
+            session = await phase('initialize', () => this.startProcessorSession(resolved, spec, startup, installed));
         }
         catch (error) {
             await startup?.dispose();
@@ -677,28 +981,28 @@ export class AcpAgents {
                 throw new Error('Managed Qoder startup could not initialize');
             throw error;
         }
-        this.observe(spec.agentId, observationOf(connection));
+        finally {
+            releaseLease();
+        }
+        const facts = session.initializeFacts;
+        this.observe(spec.agentId, observationOfFacts(facts));
         try {
-            if (startup && (connection.agentInfo?.name !== 'qoder-cli' || connection.agentInfo.version !== QODER_MANAGED_VERSION)) {
+            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 && connection.capabilities.loadSession ? 'session/load' : 'session/new';
-            const started = await phase(operation, () => withDeadline(this.startSession(connection, capture, sessionSpec), this.sessionStartTimeoutMs, `Agent '${spec.agentId}' ${operation}`, AgentSessionStartTimeoutError));
+            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, startup?.dispose),
-                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
@@ -706,6 +1010,1175 @@ export class AcpAgents {
             throw new AgentRefusedSessionError(error, startup ? 'Managed Qoder session could not open' : undefined);
         }
     }
+    /**
+     * 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 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.`);
+            }
+        }
+        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` } : {}) });
+        }
+        try {
+            await session.initialized(this.initializeTimeoutMs);
+        }
+        catch (error) {
+            await session.close('auto').catch(() => undefined);
+            throw error;
+        }
+        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),
+            },
+        };
+    }
+    /**
+     * 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.
+     */
+    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 {
+                transport = await generations.transportFor(gen);
+                sessions = await withDeadline(transport.list(), this.leftoverListTimeoutMs, `keeper-acp ${gen} list`, Error);
+            }
+            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 });
+        }
+        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;
+    }
+    /**
+     * 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.
@@ -717,7 +2190,7 @@ export class AcpAgents {
      */
     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);
+        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 });
@@ -734,7 +2207,7 @@ export class AcpAgents {
      */
     async deleteNativeSessions(spec, ids) {
         const resolved = await this.resolveLaunchFor(spec.agentId, spec.command, spec.args);
-        const connection = await this.connectResolved(spec.agentId, resolved, spec.env, spec.agentEnv);
+        const connection = await this.connectResolved(resolved, spec.env, spec.agentEnv);
         this.observe(spec.agentId, observationOf(connection));
         try {
             return await deleteNativeSessions(connection, ids);
@@ -743,6 +2216,46 @@ export class AcpAgents {
             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.
@@ -765,7 +2278,8 @@ export class AcpAgents {
      * 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 probe = createCommandTableProbe();
+        const connection = await this.connectFor(spec, timeoutMs, undefined, probe);
         const authMethods = connection.authMethods;
         this.observe(spec.agentId, observationOf(connection));
         try {
@@ -773,7 +2287,7 @@ export class AcpAgents {
             let observedConfig;
             const started = Date.now();
             await withDeadline((async () => {
-                const first = await openAndObserveCommands(connection, spec.cwd, COMMAND_FIRST_BROADCAST_MS);
+                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}'`);
@@ -818,14 +2332,15 @@ export class AcpAgents {
         let abandoned = false;
         try {
             return await withDeadline((async () => {
-                const connection = await this.connectFor(spec, remainingMs);
+                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 openAndObserveCommands(connection, spec.cwd, this.commandRetryFirstBroadcastMs)).commands;
+                return (await observeCommands(probe, connection, spec.cwd, this.commandRetryFirstBroadcastMs)).commands;
             })(), remainingMs, `Looking again for agent '${spec.agentId}''s command table`);
         }
         catch (error) {
@@ -853,6 +2368,7 @@ export class AcpAgents {
      * 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
@@ -904,9 +2420,11 @@ export class AcpAgents {
      * way a session's is, because the standard shape appends to it; the `_meta` shape ignores it.
      */
     async hostTerminalLogin(spec, terminal, present, login) {
-        const launch = terminal.kind === 'meta'
-            ? { command: terminal.command, args: [], env: {} }
-            : (await this.resolveLaunchFor(spec.agentId, spec.command, spec.args)).launch;
+        // 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 } : {}),
@@ -939,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
@@ -961,136 +2482,34 @@ export class AcpAgents {
                 registerPermissionHandlers(app, createDeferredPermissionSink().sink, {
                     present: login.present,
                     dismiss: login.dismiss ?? (() => { }),
-                });
+                }, adapter);
             },
         };
-        return withUnpinnedFallback(spec.agentId, resolved, (launch, source) => connectAgent(launch, spec.env, spec.agentEnv, { ...options, launchSource: source }));
-    }
-    /**
-     * 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.
-     *
-     * `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 && spec.managedHistoryResumeRequired) {
-            throw new Error('Managed native history replay has no certified boundary');
-        }
-        if (spec.delegationMcp && !connection.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');
-        }
-        // 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(connection.agentInfo) && connection.capabilities.resume &&
-            !spec.backfill && !spec.requireSessionLoad && !spec.delegationMcp) {
-            const initial = { configOptions: [] };
-            const session = AcpSession.attach(connection, nativeSessionId, capture, initial);
-            try {
-                const response = await connection.connection.agent.request(methods.agent.session.resume, {
-                    sessionId: nativeSessionId, cwd: spec.cwd, mcpServers: [...(spec.mcpServers ?? [])],
-                });
-                initial.configOptions = normalizeConfigOptions(response.configOptions, response.modes);
-                session.enableBackgroundTerminalRepair(spec.cwd, spec.agentEnv.HOME ?? spec.env.HOME ?? homedir(), true);
-                return { session, nativeSessionId, history: [], configOptions: initial.configOptions };
-            }
-            catch (error) {
-                await session.close().catch(() => undefined);
-                throw error; // Never silently replace this cached conversation with a fresh native root.
-            }
-        }
-        if (nativeSessionId) {
-            if (!connection.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 {
-                // `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);
-                session.enableBackgroundTerminalRepair(spec.cwd, spec.agentEnv.HOME ?? spec.env.HOME ?? homedir());
-                try {
-                    const history = [];
-                    for await (const event of replayNativeSession(connection, capture, {
-                        cwd: spec.cwd,
-                        nativeSessionId,
-                        mcpServers: spec.mcpServers,
-                        delegationMcp: spec.delegationMcp,
-                        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.
-                        session.observeReplayEvent(event);
-                        if (spec.backfill)
-                            history.push(event);
-                    }
-                    return { session, nativeSessionId, history, configOptions: initial.configOptions };
-                }
-                catch (error) {
-                    if (spec.requireSessionLoad || spec.delegationMcp) {
-                        await session.close().catch(() => undefined);
-                        throw 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, mcpServers: spec.mcpServers, delegationMcp: spec.delegationMcp,
-        });
-        opened.session.enableBackgroundTerminalRepair(spec.cwd, spec.agentEnv.HOME ?? spec.env.HOME ?? homedir());
-        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 `prerequisite` runs first, and can refuse to run anything at all
      *
      * `registry/catalog.ts` may curate one prerequisite for an agent (`pi-acp` needs the `pi` CLI,
@@ -1099,23 +2518,14 @@ export class AcpAgents {
      *
      * 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", detection 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 detection below, since there would be nothing useful to install anyway.
+     *    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 — the same words the card already shows
-     *    from the roster's `missingPrerequisite` — and fetches no adapter either: an adapter on disk
-     *    whose engine is not would only turn the card into an `Add` whose try-run must fail.
-     *
-     * An agent outside the catalog, or one with no `prerequisite` block, skips straight to the adapter
-     * step below — nothing here changes for `claude-acp`, `codex-acp`, or any other uncurated agent.
+     *    one refuses with the catalog's `hint` as the error and fetches no adapter either.
      *
-     * Never starts the agent: see {@link installNpxPackage}.
+     * Never starts the agent.
      */
     async install(agentId, options = {}) {
         const dependency = catalogEntryFor(agentId)?.prerequisite;
@@ -1145,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 {
@@ -1161,69 +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
-     *
-     * 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.
+     * 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.
      *
-     * `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(agent, timeoutMs) {
+    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.
+     */
+    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) {
-            const installed = await this.installNpxWithFallback(agent, npx.package, timeoutMs);
-            if (!installed.ok || installed.pinnedVersionUnavailable)
-                return installed;
+            const pristine = await this.installPristineWithFallback(agent, npx.package, timeoutMs);
+            if (!pristine.ok)
+                return pristine;
             try {
-                await preparePatchedLaunch(agent, await resolveLaunch(agent, this.platform, this.arch, this.adapterRoot), this.adapterRoot, this.probe, { timeoutMs, npxCommand: this.npxCommand });
-                return installed;
+                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) {
-                return { ok: false, error: `Adapter patch preparation failed: ${String(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,
@@ -1234,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,
@@ -1252,75 +2688,342 @@ 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 prerequisite for this agent (`registry/catalog.ts`'s `prerequisite`) is
@@ -1340,229 +3043,78 @@ export class AcpAgents {
             return true;
         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: {} }, source: 'command-override' };
+    /**
+     * 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 {
-            source: 'registry',
-            launch: await preparePatchedLaunch(agent, await resolveLaunch(agent, this.platform, this.arch, this.adapterRoot), this.adapterRoot, this.probe, { npxCommand: this.npxCommand }),
-            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, source) => connectAgent(launch, env, agentEnv, { ...options, launchSource: source }));
+    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, resolved.source);
-    }
-    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, 'registry-fallback');
-    }
-}
-/**
- * Wrap one `AcpSession` plus the connection it runs on into the shape the manager holds.
- *
- * Two behaviours are added on top of `AcpSession`. Lifetime: `close()` must end the subprocess as
- * well as the session, or `agent_close` would leave a live agent behind holding its cwd and its
- * quota. `backfill` is attached only when there is history to replay, because its *absence* is what
- * the manager reads as "nothing to replay". And the config option snapshot: {@link
- * AcpAgentSession.configOptions} must answer with the **latest** one, not the one this session
- * opened with, so the cell below is what `setConfigOption` writes back into and what the getter
- * reads — see that field's own doc for what a stale answer costs on every reconnect.
- */
-function hostedSession(session, connection, history, configOptions, disposeStartup) {
-    // `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, platformTurnId) => session.prompt(blocks, platformTurnId),
-        // 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),
-        answerElicitation: (requestId, response) => session.answerElicitation(requestId, response),
-        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),
-        stopAsyncTask: (asyncTaskId) => session.stopAsyncTask(asyncTaskId),
-        // 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,
-        get runtimeDiagnostics() { return connection.runtimeDiagnostics; },
-        providerTaskAdapterSelected: connection.providerTaskAdapterSelected,
-        onProviderTaskEvent: (cb) => connection.onProviderTaskEvent(cb),
-        providerTaskStop: (taskId, requestId) => session.providerTaskStop(taskId, requestId),
-        onRuntimeDiagnostics: (cb) => connection.onRuntimeDiagnostics(cb),
-        supportsImageInput: connection.capabilities.promptImage,
-        onEvent: (cb) => session.onEvent(cb),
-        onTurnDone: (cb) => session.onTurnDone(cb),
-        onActivity: (cb) => session.onActivity(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);
-                await disposeStartup?.();
-            }
-        },
-    };
-    if (history.length > 0) {
-        hosted.backfill = async function* backfill() {
-            for (const event of history)
-                yield event;
-        };
+        const { npx, uvx } = agent.distribution;
+        return Boolean(npx || uvx);
     }
-    return hosted;
 }
 /**
- * Opens one session on [connection] and collects the command table the agent broadcasts after `session/new`, then
- * closes it. `commands` undefined = no table arrived within [firstWindowMs] (unknown, not empty).
+ * 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).
  *
- * 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. The sink is attached after `open` on purpose and is still safe:
- * `AcpSession` buffers events until one is attached (`onEvent`'s `drain()`), and since p3-fix7 N9 the connection
- * also keeps the updates that arrive before it knows its own session id (`acpClient.ts`).
- *
- * Settle rather than "first push wins": Claude broadcasts twice — once on `session/new` and again when the init frame
+ * 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] 兜底。
  */
-async function openAndObserveCommands(connection, cwd, firstWindowMs) {
-    const opened = await AcpSession.open(connection, { cwd });
-    // Captured off `session/new`'s own response: the snapshot exists the moment `open` resolves.
-    const configOptions = opened.configOptions;
-    let commands;
-    let finish;
-    const settled = new Promise((resolve) => {
-        finish = resolve;
-    });
-    let quietTimer;
-    let ceilingTimer;
-    let firstTimer = setTimeout(() => finish?.(), firstWindowMs);
-    opened.session.onEvent((event) => {
-        if (event.eventName !== 'available_commands_update')
-            return;
-        const available = event.payload.availableCommands;
-        if (Array.isArray(available))
-            commands = available.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);
-    await opened.session.close().catch(() => undefined);
-    return { commands, configOptions };
+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 };
 }