@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/acp/acpAgents.js

@@ -1,4 +1,4 @@
-import { homedir } from 'node:os';
+import { assertRuntimeRequest, loadRuntimeRelease, managedRuntimeFor, verifyManagedRuntime } from './managedRuntime.js';
 /**
  * The daemon's single entry point into ACP — what `agentSessions.ts` holds where it used to hold a
  * `Map<string, AgentBridge>`.
@@ -32,7 +32,6 @@ import { homedir } from 'node:os';
  * reaching the network or running `npx`.
  */
 import { RequestError } from '@agentclientprotocol/sdk';
-import { certifiedRuntime } from '../qoderAdapter/foregroundOutput.js';
 import { existsSync } from 'node:fs';
 import { readdir } from 'node:fs/promises';
 import path from 'node:path';
@@ -45,7 +44,7 @@ import { deleteNativeSessions, listNativeSessions } from './adoption.js';
 import { AcpAuth } from './auth.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 { defaultNpmCommand, ensurePristine, installedDependencies, 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';
@@ -57,14 +56,12 @@ 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 { AdoptionRefusedError, ProcessorSession, readOutboxTail } from './processorSession.js';
 import { hostsRunningAdapter } from './processor/transport/generations.js';
 import { isOutboxTail } from './outbox.js';
 import { LocalTransport } from './processor/transport/local.js';
 import { AcpKeeperUnavailableError } from '../keepers/acp/client.js';
-import { prepareQoderStartup, QODER_MANAGED_VERSION } from './qoderStartup.js';
 import { friendlyOrdinaryInstallError, friendlyPinnedVersionUnavailableAndFallbackFailed, friendlyUvMissingError, logInstallFailureDetail, } from './installErrors.js';
 import { ADAPTER_INSTALL_TIMEOUT_MS, npmCacheDir, npmPackageName, npmPackageVersion, pickInstalledVersion, findOnPath, probeEnvironment, runDependencyInstall, } from './installProbe.js';
 import { createDeferredPermissionSink, registerPermissionHandlers } from './permission.js';
@@ -498,11 +495,14 @@ export class AcpAgents {
     quotaReaders = new Map();
     /** The `uv` uv builds are installed with; see {@link AcpAgentsOptions.runUv}. */
     runUv;
+    serverOrigin;
     /** Injectable `npm` for adapter builds; see {@link AcpAgentsOptions.npmCommand}. */
     npmCommand;
     nodePath;
     binaryFetch;
     patchRecipes;
+    managedRuntimePolicies;
+    patchAssetRoot;
     /** `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. */
@@ -575,9 +575,12 @@ export class AcpAgents {
         this.runCommand = options.runCommand ?? runDependencyInstall;
         this.runUv = options.runUv ?? defaultRunUv;
         this.nodePath = options.nodePath ?? process.execPath;
+        this.serverOrigin = options.serverOrigin;
         this.npmCommand = options.npmCommand ?? defaultNpmCommand(this.nodePath, this.platform);
         this.binaryFetch = options.binaryFetch;
         this.patchRecipes = options.patchRecipes;
+        this.managedRuntimePolicies = options.managedRuntimePolicies;
+        this.patchAssetRoot = options.patchAssetRoot;
         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');
@@ -956,7 +959,7 @@ export class AcpAgents {
                 spec.onInstallOutcome?.(outcome);
             }));
         }
-        let resolved = await phase('prepare-launch', () => this.resolveLaunchFor(spec.agentId, spec.command, spec.args));
+        let resolved = await phase('prepare-launch', () => this.resolveLaunchFor(spec.agentId, spec.command, spec.args, spec.recordedBuildId));
         // 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) {
@@ -966,20 +969,9 @@ export class AcpAgents {
         }
         // GC never takes the build between resolving it and the spawn (whose keeper-acp label references it from then on).
         const releaseLease = this.leaseBuild(spec.agentId, resolved.launch.label?.buildId);
-        const startup = spec.agentId === 'qoder' && spec.delegationMcp
-            ? await phase('prepare-qoder', () => prepareQoderStartup(resolved.launch, spec.delegationMcp, spec.cwd, spec.env, spec.agentEnv))
-            : undefined;
-        if (startup)
-            resolved = { launch: startup.launch, source: resolved.source };
         let session;
         try {
-            session = await phase('initialize', () => this.startProcessorSession(resolved, spec, startup, installed));
-        }
-        catch (error) {
-            await startup?.dispose();
-            if (startup)
-                throw new Error('Managed Qoder startup could not initialize');
-            throw error;
+            session = await phase('initialize', () => this.startProcessorSession(resolved, spec, installed));
         }
         finally {
             releaseLease();
@@ -987,14 +979,8 @@ export class AcpAgents {
         const facts = session.initializeFacts;
         this.observe(spec.agentId, observationOfFacts(facts));
         try {
-            if (startup && (session.agentInfo?.name !== 'qoder-cli' || session.agentInfo.version !== QODER_MANAGED_VERSION)) {
-                throw new Error('Managed Qoder runtime identity is not certified');
-            }
-            // Qoder 1.1.61 accepts HTTP MCP at startup, but rejects that entry in ACP new/load.
-            const sessionSpec = { ...spec, managedHistoryResumeRequired: !!spec.delegationMcp || spec.managedHistoryResumeRequired,
-                ...(startup ? { delegationMcp: undefined, requireSessionLoad: spec.requireSessionLoad || !!spec.nativeSessionId } : {}) };
             const operation = spec.nativeSessionId && facts.capabilities.loadSession ? 'session/load' : 'session/new';
-            const started = await phase(operation, () => withDeadline(this.startSession(session, facts, sessionSpec), this.sessionStartTimeoutMs, `Agent '${spec.agentId}' ${operation}`, AgentSessionStartTimeoutError));
+            const started = await phase(operation, () => withDeadline(this.startSession(session, facts, spec), 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.
@@ -1002,32 +988,31 @@ export class AcpAgents {
             return { session, nativeSessionId: started.nativeSessionId };
         }
         catch (error) {
-            await session.close('auto').catch(() => undefined);
-            await startup?.dispose();
+            // A recorded-build reopen is the only path allowed to retain an empty keeper record after
+            // bootstrap failure: the old native session still belongs to that package, and releasing an
+            // acknowledged transport would make the next retry silently select the mutable current build.
+            await session.close(spec.recordedBuildId !== undefined ? 'keep' : 'auto').catch(() => undefined);
             // Marked, not merely rethrown: everything above this `try` failed before the agent said
             // anything, and only a failure from here on can be an `auth_required`. See
             // {@link AgentRefusedSessionError} — `agentSessions.ts` is the reader.
-            throw new AgentRefusedSessionError(error, startup ? 'Managed Qoder session could not open' : undefined);
+            throw new AgentRefusedSessionError(error, 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.
+     * reads its own), the daemon's working directory (where `connectAgent` started adapters); the label is opaque to the keeper.
      */
-    async startProcessorSession(resolved, spec, startup, installOutcome) {
-        const { spawn, label: baseLabel, launch } = this.spawnSpecOf(resolved, spec, startup);
+    async startProcessorSession(resolved, spec, installOutcome) {
+        const { spawn, label: baseLabel, launch } = this.spawnSpecOf(resolved, spec);
         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)
+        const pendingLocal = local !== undefined && local.lastSeq > resumeFrom && local.unacknowledged;
+        const stayLocal = pendingLocal && !this.transports.keeper;
+        if (local && !pendingLocal)
             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)
@@ -1056,7 +1041,6 @@ export class AcpAgents {
             spawn, seqBase, backfill: spec.backfill === true,
             ...(installOutcome ? { installOutcome } : {}),
             launch,
-            ...(startup ? { onClosed: () => startup.dispose() } : {}),
         };
         let session;
         if (this.transports.keeper && !stayLocal) {
@@ -1079,10 +1063,15 @@ export class AcpAgents {
                 else
                     this.heldOnOlder.delete(keeperKey); // a reopen hold on an older generation that is gone now
                 try {
+                    const imports = pendingLocal ? await readOutboxTail(this.localTransport(), sessionKey, local.outbox) : undefined;
+                    if (imports && local && imports.length !== local.outbox.next - Math.max(local.outbox.first, local.outbox.committed + 1)) {
+                        throw new Error('The local session outbox could not be read completely');
+                    }
                     session = await ProcessorSession.start({ ...options, sessionKey: keeperKey, transport: target.transport,
+                        ...(imports ? { imports } : {}),
                         label: { ...baseLabel, ...(keyGen > 0 ? { keyGen } : {}) },
                         onDegrade: this.recordDegraded(keeperKey, target.gen ?? 'current'),
-                        ...(target.gen !== undefined ? { onClosed: () => this.olderSessionClosed(keeperKey, options.onClosed) } : {}) });
+                        ...(target.gen !== undefined ? { onClosed: () => this.olderSessionClosed(keeperKey) } : {}) });
                 }
                 catch (error) {
                     this.heldOnOlder.delete(keeperKey);
@@ -1113,22 +1102,26 @@ export class AcpAgents {
             await session.initialized(this.initializeTimeoutMs);
         }
         catch (error) {
-            await session.close('auto').catch(() => undefined);
+            await session.close(spec.recordedBuildId !== undefined ? 'keep' : 'auto').catch(() => undefined);
             throw error;
         }
+        if (pendingLocal && session.transportMode === 'keeper') {
+            await this.localTransport().release(sessionKey).catch((error) => {
+                console.warn(`[acp] releasing the migrated local outbox for ${sessionKey} failed: ${errorMessage(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.
+     * own), the daemon's working directory (where `connectAgent` started adapters), the label is opaque to the keeper.
      */
-    spawnSpecOf(resolved, spec, startup) {
+    spawnSpecOf(resolved, spec) {
         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)];
+        // keeper-acp takes at most ACP_STDERR_SECRETS_MAX.
+        const allSecrets = [...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})`);
@@ -1137,7 +1130,6 @@ export class AcpAgents {
         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,
@@ -1450,9 +1442,6 @@ export class AcpAgents {
         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));
@@ -1731,6 +1720,7 @@ export class AcpAgents {
             source: 'registry',
             launch: await launchForBuild(build, this.adapterRoot, {
                 nodePath: this.nodePath, launchEnv: catalogLaunchEnv(agentId, build.registryVersion), basePath: this.probe.path,
+                ...this.runtimeAssets(agentId), allowLegacy: true,
             }),
         };
     }
@@ -1892,12 +1882,11 @@ export class AcpAgents {
         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) {
+    olderSessionClosed(sessionKey) {
         // 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
@@ -1979,6 +1968,7 @@ export class AcpAgents {
         const tail = summary.outbox.committedTail;
         const tailSeq = typeof tail?.seq === 'number' ? tail.seq : 0;
         return {
+            outbox: summary.outbox,
             lastSeq: Math.max(summary.outbox.lastSeq ?? 0, tailSeq),
             unacknowledged: summary.outbox.next > Math.max(summary.outbox.first, summary.outbox.committed + 1),
         };
@@ -2113,60 +2103,35 @@ export class AcpAgents {
     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 mcpServers = [...(spec.mcpServers ?? [])];
         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 request = { cwd: spec.cwd, mcpServers, redact };
         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) {
+        // The adapter declares cached reconnect semantics in initialize; explicit history/settings loads still use load.
+        if (nativeSessionId && facts.cachedReconnect === 'resume' && capabilities.resume &&
+            !spec.backfill && !spec.requireSessionLoad) {
             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)
+                if (spec.requireSessionLoad)
                     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 } });
+                const result = await session.openSession({ ...request, mode: 'load', sessionId: nativeSessionId });
                 if (result.ok) {
                     await session.endHistory();
                     return { nativeSessionId };
                 }
-                if (spec.requireSessionLoad || spec.delegationMcp)
+                if (spec.requireSessionLoad)
                     throw refused(result);
                 console.warn(`[acp] session/load for '${nativeSessionId}' on agent '${spec.agentId}' failed ` +
                     `(${result.error}); starting a new session instead`);
@@ -2175,8 +2140,6 @@ export class AcpAgents {
         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 };
     }
     /**
@@ -2570,6 +2533,9 @@ export class AcpAgents {
             ...(outcome.pinnedVersionUnavailable ? { pinnedVersionUnavailable: outcome.pinnedVersionUnavailable } : {}),
         };
     }
+    runtimeAssets(agentId) {
+        return { policy: managedRuntimeFor(agentId, this.managedRuntimePolicies), assetRoot: this.patchAssetRoot, recipes: this.patchRecipes };
+    }
     /** The registry as Axom installs it (catalog supplements, pins, launchEnv kept apart) — see `registry/catalog.ts`. */
     async effective() {
         return effectiveEntries(await this.baseRegistry.load());
@@ -2590,18 +2556,21 @@ export class AcpAgents {
     currentBuildId) {
         const agent = entry.agent;
         const { npx, uvx, binary } = agent.distribution;
+        const policy = this.runtimeAssets(agent.id).policy;
+        if (policy && (!npx || agent.version !== policy.version))
+            return { ok: false, error: 'Managed runtime Catalog/distribution differs from bundled release policy' };
         const source = entry.pinnedBy ?? 'registry';
         const commit = (build) => this.builds.commit(build, { makeCurrent: build.buildId !== currentBuildId, setBy });
         if (npx) {
-            const pristine = await this.installPristineWithFallback(agent, npx.package, timeoutMs);
+            const pristine = await this.installPristineWithFallback(agent, timeoutMs);
             if (!pristine.ok)
                 return pristine;
             try {
                 const build = await npmBuild({
-                    store: this.builds, agentId: agent.id, name: npmPackageName(npx.package), version: pristine.version,
+                    store: this.builds, agentId: agent.id, name: npx.tarball ? npx.package : 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,
+                    nodePath: this.nodePath, ...this.runtimeAssets(agent.id),
                     ...(this.patchRecipes ? { recipes: this.patchRecipes } : {}),
                 });
                 const recorded = pristine.pinnedVersionUnavailable
@@ -2693,18 +2662,24 @@ export class AcpAgents {
      * 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 installPristineWithFallback(agent, pinnedSpec, timeoutMs) {
-        const name = npmPackageName(pinnedSpec);
-        const version = npmPackageVersion(pinnedSpec);
+    async installPristineWithFallback(agent, timeoutMs) {
+        const distribution = agent.distribution.npx;
+        const pinnedSpec = distribution.package;
+        const name = distribution.tarball ? distribution.package : npmPackageName(pinnedSpec);
+        const version = distribution.tarball ? agent.version : npmPackageVersion(pinnedSpec);
+        if (distribution.tarball && !this.serverOrigin)
+            return { ok: false, error: 'Adapter is served by the Axom server; this workstation has no server configured' };
+        const tarball = distribution.tarball ? { url: new URL(distribution.tarball.path, this.serverOrigin).href, sha512: distribution.tarball.sha512 } : undefined;
+        const runtime = this.runtimeAssets(agent.id);
         const budget = timeoutMs ?? ADAPTER_INSTALL_TIMEOUT_MS;
         const install = (pinned) => ensurePristine({
-            store: this.builds, name, ...(pinned !== undefined ? { version: pinned } : {}), npmCommand: this.npmCommand, timeoutMs: budget,
+            store: this.builds, name, ...runtime, ...(pinned !== undefined ? { version: pinned } : {}), npmCommand: this.npmCommand, timeoutMs: budget, ...(tarball ? { tarball } : {}),
         }).catch((error) => ({ ok: false, error: errorMessage(error), stderr: '' }));
         const outcome = await install(version);
         if (outcome.ok)
             return outcome;
         const existingVersion = (await this.builds.current(agent.id))?.version;
-        if (version === undefined || !stderrShowsMissingPackageVersion(outcome.stderr)) {
+        if (runtime.policy || tarball || 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) };
         }
@@ -2779,6 +2754,24 @@ export class AcpAgents {
         const current = await this.builds.current(agentId);
         if (!current)
             return undefined;
+        const runtime = this.runtimeAssets(agentId);
+        if (runtime.policy) {
+            const npx = entry.agent.distribution.npx;
+            if (!npx || entry.agent.version !== runtime.policy.version)
+                throw new Error('Managed runtime Catalog/distribution differs from bundled policy');
+            assertRuntimeRequest(runtime.policy, npx.tarball ? npx.package : npmPackageName(npx.package), npx.tarball ? entry.agent.version : npmPackageVersion(npx.package));
+            const release = await loadRuntimeRelease(runtime.policy, runtime);
+            if (current.runtimeReleaseId === release.id || (!current.runtimeReleaseId && current.package === runtime.policy.package && current.version === runtime.policy.version)) {
+                await verifyManagedRuntime({ ...runtime, policy: runtime.policy, build: current, storeRoot: this.adapterRoot, nodePath: this.nodePath, initialize: false });
+                return undefined;
+            }
+            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;
+            return { agentId, from: current.buildId, to: outcome.build.buildId, reason: 'certified-pin' };
+        }
         // 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.
@@ -2796,7 +2789,7 @@ export class AcpAgents {
         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 recipes = await selectPackagePatches(current.package, current.version, inside(path.join(pristine, 'node_modules'), current.package), this.patchRecipes, await installedDependencies(pristine));
         const wanted = recipes.length ? patchDigest(recipes) : undefined;
         if (wanted === current.patchDigest)
             return undefined;
@@ -2890,6 +2883,8 @@ export class AcpAgents {
         if (!entry)
             return undefined;
         const { npx, uvx, binary } = entry.agent.distribution;
+        if (this.runtimeAssets(agentId).policy && !npx)
+            throw new Error('Managed runtime migration requires its certified npm 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.
@@ -2903,6 +2898,12 @@ export class AcpAgents {
         const name = npmPackageName(spec);
         // Exactly what the pre-build launch ran: `npx <name>@<effective version>`.
         const version = requestedVersionOf(entry);
+        const runtime = this.runtimeAssets(agentId);
+        if (runtime.policy) {
+            if (entry.agent.version !== runtime.policy.version)
+                throw new Error('Managed runtime Catalog version mismatch');
+            assertRuntimeRequest(runtime.policy, name, version);
+        }
         const copy = await findNpxCopy(npmCache, name, version);
         if (!copy)
             return undefined;
@@ -2912,7 +2913,7 @@ export class AcpAgents {
             ...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 } : {}),
+                nodePath: this.nodePath, ...runtime, ...(this.patchRecipes ? { recipes: this.patchRecipes } : {}),
             }),
             migratedFrom: 'npx-cache',
         };
@@ -3064,6 +3065,7 @@ export class AcpAgents {
             return launchForBuild(current, this.adapterRoot, {
                 nodePath: this.nodePath,
                 launchEnv: catalogLaunchEnv(agentId, current.registryVersion),
+                ...this.runtimeAssets(agentId),
                 basePath: this.probe.path,
             });
         }
@@ -3075,9 +3077,11 @@ export class AcpAgents {
         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) {
+    async resolveLaunchFor(agentId, command, args, recordedBuildId) {
         if (command)
             return { launch: { command, args, env: {} }, source: 'command-override' };
+        if (recordedBuildId !== undefined)
+            return this.launchOfBuild(agentId, recordedBuildId);
         return { source: 'registry', launch: await this.launchSpecFor(agentId) };
     }
     /**

package/dist/workstation/acp/acpClient.js

@@ -359,6 +359,19 @@ export async function closeAgentTransport(child, connection, graceMs = CHILD_EXI
     await connection.closed.catch(() => { });
 }
 const DEFAULT_INITIALIZE_TIMEOUT_MS = 30_000;
+/**
+ * 登录 URL 扩展通知的方法名与形状(见 {@link connectAgent} 内的注册点注释)。解析器**不抛**:
+ * 形状不对返回 `undefined`,处理器对 `undefined` 不做事——坏参数只少一张卡,不该伤到连接。
+ */
+const AUTH_URL_NOTIFICATION_METHOD = '_codebuddy.ai/authUrl';
+function authUrlNotificationParams(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const authUrl = raw.authUrl;
+    if (typeof authUrl !== 'string' || !/^https?:\/\//.test(authUrl))
+        return undefined;
+    return { authUrl };
+}
 /**
  * Spawns an ACP agent subprocess, connects to it over ndjson stdio, and negotiates capabilities
  * via `initialize`. `env` and `agentEnv` are overlay layers on top of the current process
@@ -393,6 +406,19 @@ export async function connectAgent(spec, env, agentEnv, options = {}) {
     // connection registers the permission handlers).
     const generation = randomUUID();
     options.configure?.(app, { generation });
+    // 登录 URL 的第三条通道:扩展通知。实测(codebuddy-code 2.171.0,2026-10-21):CodeBuddy 适配器在
+    // 应答 `authenticate` 期间推送 `_codebuddy.ai/authUrl`(`{authUrl, provider}`)——既不走
+    // `elicitation/create`,也不打 stderr(它把链接写进自己的日志文件、并打开工作站本机的浏览器,远程
+    // 读者两头都看不见)。方法名是厂商命名空间,按实测常量注册;形状校验独立于方法名做(authUrl 必须是
+    // http(s) URL),坏形状静默丢弃而不是让解析器抛错——一个登录链接不值得一条连接。与 stderr 通道同
+    // 一个 `present` 下游,URL 去重与落定收回由 `createLoginUrlSink`(acpAgents.authenticate)统一负责,
+    // 这里只负责递到同一只手里。id 前缀 `ext-auth-url-` 标出来源,与 `stderr-auth-url-` 同一条规矩。
+    if (options.present) {
+        app.onNotification(AUTH_URL_NOTIFICATION_METHOD, authUrlNotificationParams, (ctx) => {
+            if (ctx.params)
+                options.present?.(`ext-auth-url-${randomUUID()}`, ctx.params.authUrl);
+        });
+    }
     const connection = app.connect(stream);
     const timeoutMs = options.initializeTimeoutMs ?? DEFAULT_INITIALIZE_TIMEOUT_MS;
     let timeoutHandle;