@platless/axom-cli 0.1.0 → 0.3.13

package/dist/workstation/acp/acpAgents.js

@@ -1,17 +1,57 @@
+import { homedir } from 'node:os';
+/**
+ * The daemon's single entry point into ACP — what `agentSessions.ts` holds where it used to hold a
+ * `Map<string, AgentBridge>`.
+ *
+ * ## What replaced what
+ *
+ * The deleted bridge SPI dispatched on a *bridge type* (`claude-code` | `codex` | `acp`) to one of
+ * several implementations. There is only one implementation now, so there is nothing to dispatch to:
+ * ruling R1 deleted the interface rather than leaving an extension point with a single member. What
+ * varies per agent is no longer code but **data** — the launch spec — so the key is a **registry
+ * agent id** (`claude-acp`, `codex-acp`, …) and this class turns that id into a running subprocess
+ * by way of the ACP agent registry (`registry/`), `connectAgent` (`acpClient.ts`) and `AcpSession`
+ * (`acpSession.ts`).
+ *
+ * ## One connection per session, deliberately
+ *
+ * Every {@link AcpAgents.open} spawns its own agent subprocess and its own `AcpConnection`, and
+ * {@link AcpAgentSession.close} tears both down together. Pooling one connection across sessions
+ * would be cheaper and is exactly what `permission.ts`'s `PermissionSink` doc comment warns against:
+ * `registerPermissionHandlers` binds one sink per connection with no per-session routing, so two
+ * sessions sharing a connection would cross-deliver permission cards, and `createDeferredPermissionSink`
+ * would throw on the second `bind()`. The one-subprocess-per-session shape is also what the deleted
+ * bridges had, so nothing downstream had to change.
+ *
+ * ## Config overrides beat the registry (ruling R3)
+ *
+ * A workstation's agent config block may carry `command`/`args`. When it does, that is the whole
+ * launch spec — the registry is not consulted at all, and no registry-supplied `env` is merged in.
+ * This is the escape hatch for an agent that is not in the registry, a locally built adapter, or a
+ * wrapper script; it is also what lets this module's own tests drive a real ACP subprocess without
+ * reaching the network or running `npx`.
+ */
+import { methods } from '@agentclientprotocol/sdk';
+import { certifiedRuntime } from '../qoderAdapter/foregroundOutput.js';
 import path from 'node:path';
+import { 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, listNativeSessions, replayNativeSession } from './adoption.js';
+import { createReplayCapture, deleteNativeSessions, listNativeSessions, replayNativeSession } from './adoption.js';
 import { AcpAuth } from './auth.js';
 import { binaryTargetFor, installBinary, installedBinaryVersion, platformTriple } from './binaryInstall.js';
 import { normalizeConfigOptions } from './configOptions.js';
+import { prepareQoderStartup, QODER_MANAGED_VERSION } from './qoderStartup.js';
 import { friendlyOrdinaryInstallError, friendlyPinnedVersionUnavailableAndFallbackFailed, logInstallFailureDetail, } from './installErrors.js';
-import { ADAPTER_INSTALL_TIMEOUT_MS, findOnPath, installNpxPackage, npmPackageName, npxCacheVersion, probeEnvironment, readNpxCache, runDependencyInstall, } from './installProbe.js';
+import { ADAPTER_INSTALL_TIMEOUT_MS, installNpxPackage, npmPackageName, npxCacheVersion, probeEnvironment, readNpxCache, runDependencyInstall, } from './installProbe.js';
 import { createDeferredPermissionSink, registerPermissionHandlers } from './permission.js';
-import { catalogEntryFor } from './registry/catalog.js';
+import { catalogEntryFor, withCatalogOverrides } from './registry/catalog.js';
+import { detected } from './registry/detect.js';
 import { resolveLaunch, unpinnedFallbackFor } from './registry/launch.js';
 import { RegistryClient } from './registry/registryClient.js';
+import { preparePatchedLaunch } from './managedPatches.js';
 import { installUvTool, listUvTools, uvPackageName, uvToolVersion } from './uvxInstall.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -44,8 +84,8 @@ function errorMessage(error) {
  */
 export class AgentRefusedSessionError extends Error {
     errorCode;
-    constructor(cause) {
-        super(errorMessage(cause), { cause });
+    constructor(cause, publicMessage) {
+        super(publicMessage ?? errorMessage(cause), publicMessage === undefined ? { cause } : undefined);
         this.name = 'AgentRefusedSessionError';
         this.errorCode = jsonRpcErrorCode(cause);
     }
@@ -184,9 +224,11 @@ export function createLoginUrlSink(login) {
 /** A verification or authentication ran past {@link AGENT_PROBE_TIMEOUT_MS}. */
 export class AgentProbeTimeoutError extends Error {
 }
+/** A real session stopped answering after initialize; closing its transport reaps the child. */
+export class AgentSessionStartTimeoutError extends Error {
+}
 /**
- * Reject with {@link AgentProbeTimeoutError} once `timeoutMs` has passed, whatever `work` is still
- * doing.
+ * Reject with the specified timeout error once `timeoutMs` has passed, whatever `work` is still doing.
  *
  * `work` is deliberately *not* cancelled here — nothing in ACP can cancel an `initialize` or a
  * `session/new` in flight. What actually stops it is the caller's `connection.close()`, which kills
@@ -194,10 +236,10 @@ export class AgentProbeTimeoutError extends Error {
  * it will usually reject (the child died under it) long after nobody is listening, and an unhandled
  * rejection would take the daemon down.
  */
-async function withDeadline(work, timeoutMs, what) {
+async function withDeadline(work, timeoutMs, what, timeoutError = AgentProbeTimeoutError) {
     let timer;
     const deadline = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new AgentProbeTimeoutError(`${what} did not finish within ${timeoutMs}ms.`)), timeoutMs);
+        timer = setTimeout(() => reject(new timeoutError(`${what} did not finish within ${timeoutMs}ms.`)), timeoutMs);
     });
     deadline.catch(() => { });
     try {
@@ -212,7 +254,7 @@ async function withDeadline(work, timeoutMs, what) {
  * 等**第一条** `available_commands_update` 的窗口。一条都没等到就收工,`observed` 保持 undefined
  * ——按「缺席 ≠ 空表」的约定,服务端据此不写命令表那一半(见 {@link verify} 的 KDoc)。
  *
- * 数值沿用原来那个固定 settle 窗口(`docs/superpowers/notes/2026-08-31-codex-command-table-race.md`)。
+ * 数值沿用原来那个固定 settle 窗口(`archived/docs/superpowers/notes/2026-08-31-codex-command-table-race.md`)。
  * **没有证据支持把它调大**:真机上量到同一个 agent 在一台机器上回 72 条、在另一台回 0 条,但那两次
  * 的耗时差(8.4s vs 2.1s)完全可能全部落在 spawn/connect 上,而不是广播来晚了。要区分这两件事,
  * 得先有 {@link verify} 里那条「没等到表」的日志,不是先改这个数字。
@@ -232,6 +274,13 @@ const COMMAND_QUIET_MS = 750;
  * 必须显著小于 {@link AGENT_PROBE_TIMEOUT_MS} —— 连接和 `session/new` 还要在这之前各花一段。
  */
 const COMMAND_SETTLE_CEILING_MS = 5_000;
+/**
+ * p3-fix7 N9: a verification whose first opening saw no command table opens one more session and waits this long for
+ * the first broadcast. "Nothing seen" is not an observation: the dispatch planner reads "offers
+ * superpowers:brainstorming" off this table, and a missed table can flip a project to native. Kept well inside
+ * {@link AGENT_PROBE_TIMEOUT_MS} with the first attempt's window and two session openings.
+ */
+const COMMAND_RETRY_FIRST_BROADCAST_MS = 4_000;
 /** ACP 的 `AvailableCommand` → 隧道形状:`input.hint` 拍平成 `inputHint`。 */
 function toAvailableCommandWire(raw) {
     const command = raw;
@@ -251,7 +300,11 @@ function toAvailableCommandWire(raw) {
  * they are the ones nobody remembers.
  */
 function observationOf(connection) {
-    return { authMethods: connection.authMethods, supportsSteering: connection.supportsSteering };
+    return {
+        authMethods: connection.authMethods,
+        supportsSteering: connection.supportsSteering,
+        terminalLogins: connection.terminalLogins,
+    };
 }
 /**
  * The version of `agent`'s ACP adapter actually found on this machine, dispatched by distribution
@@ -305,6 +358,7 @@ function isUnsupportedPlatform(agent, platform, arch) {
     return !triple || !binaryTargetFor(agent, triple);
 }
 export class AcpAgents {
+    sessionStartTimeoutMs;
     registry;
     platform;
     arch;
@@ -317,6 +371,7 @@ export class AcpAgents {
      * branch needs this root and nothing else in this class's options carries it).
      */
     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}. */
@@ -324,13 +379,19 @@ export class AcpAgents {
     /** Injectable `npx` binary for {@link installAdapter}'s npx branch; see {@link AcpAgentsOptions.npxCommand}. */
     npxCommand;
     constructor(options) {
-        this.registry = options.registry ?? new RegistryClient({ cacheDir: options.cacheDir });
+        this.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.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.commandRetryFirstBroadcastMs = options.commandRetryFirstBroadcastMs ?? COMMAND_RETRY_FIRST_BROADCAST_MS;
         this.adapterRoot = path.join(options.cacheDir, 'acp-adapters');
     }
     /**
@@ -349,9 +410,15 @@ export class AcpAgents {
      * is the one field that does describe this machine (has the ACP adapter already been downloaded
      * here), spread in only when it was genuinely established.
      *
-     * `recommended` / `defaultName` / `defaultLabel` come from `registry/catalog.ts` — the curated list
+     * `curated` / `defaultName` / `defaultLabel` come from `registry/catalog.ts` — the curated list
      * of agents Axom has actually verified, which replaced the old "official CLI on PATH" table. They
      * are spread in only for a catalog hit; an agent outside the catalog is not claimed either way.
+     * `recommended` is the catalog's own static flag (claude, codex, pi) and nothing else — it used to
+     * be spread for every catalog hit, which is what `curated` now says. `detected` is the catalog's
+     * local detection (`registry/detect.ts`): the agent itself, or its prerequisite, is on this machine
+     * the way the user installed it — a reason to recommend, never a claim that Axom installed it.
+     * `missingPrerequisite` names a prerequisite that is absent *and* that `install` cannot fetch, so
+     * the card can say what to do instead of offering an `Install` that can only refuse.
      *
      * Never throws, for the same reason the deleted `rosterFor` swallowed a failing probe: a registry
      * that is unreachable on a cold-start machine must not be able to stop the daemon from connecting.
@@ -396,6 +463,11 @@ export class AcpAgents {
             // 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);
+            // 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);
             return {
                 type: agent.id,
                 // `uvTools` is the same hoisted `uv tool list` snapshot `adapterVersion` below looks up in
@@ -422,12 +494,12 @@ export class AcpAgents {
                 // "did not look": `adapterVersionFor` reads the npx cache, the hoisted `uv tool list`
                 // snapshot and our own binary install root, and every one of them is a local read.
                 //
-                // `dependencySatisfied` folds in the catalog's extra prerequisite (design §4.4): `pi-acp`'s
-                // adapter sitting in the npx cache with no `pi` on `PATH` is not an agent this machine can
-                // add — the card would offer `Add`, the try-run would fail, and the reader would be told
-                // nothing about the missing CLI. Reporting it not-installed is what makes `Install` fetch
-                // the dependency too.
-                adapterInstalled: adapterVersion !== undefined && this.dependencySatisfied(agent.id),
+                // `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 —
+                // the card would offer `Add`, the try-run would fail, and the reader would be told nothing
+                // about the missing CLI. Reporting it not-installed is what makes `Install` fetch the
+                // prerequisite too (or, with nothing to fetch, `missingPrerequisite` below explain it).
+                adapterInstalled: adapterVersion !== undefined && prerequisiteMet,
                 // The version half of the same answer — see `adapterVersionFor`'s doc comment. Absent
                 // rather than null when nothing is installed, on this file's usual "never write down what
                 // nobody looked at" rule.
@@ -452,10 +524,18 @@ export class AcpAgents {
                 // its id-derived fallback would have said something.
                 ...(agent.name ? { displayName: agent.name } : {}),
                 ...(agent.description ? { description: agent.description } : {}),
-                // Spread from `registry/catalog.ts` only for a catalog hit — `recommended` has no `false`,
-                // the same "absent means unknown/no" rule as `supportsSteering` below.
-                ...(catalog ? { recommended: true, defaultName: catalog.defaultName } : {}),
+                // Spread from `registry/catalog.ts` only for a catalog hit — `curated`, `recommended` and
+                // `detected` have no `false`, the same "absent means unknown/no" rule as `supportsSteering`.
+                // An `unverified` entry keeps its defaults but is not one Axom vouches for (see `catalog.ts`).
+                ...(catalog ? { ...(catalog.unverified ? {} : { curated: true }), defaultName: catalog.defaultName } : {}),
                 ...(catalog?.defaultLabel ? { defaultLabel: catalog.defaultLabel } : {}),
+                ...(catalog?.recommended ? { recommended: true } : {}),
+                ...(inUse ? { detected: true } : {}),
+                // Only when nothing here can fix it: a prerequisite with an `install` argv (Pi) is fetched by
+                // `Install`, which the card already offers because `adapterInstalled` is false.
+                ...(prerequisite && !prerequisiteMet && !prerequisite.install
+                    ? { missingPrerequisite: { label: prerequisite.label, ...(prerequisite.hint ? { hint: prerequisite.hint } : {}) } }
+                    : {}),
                 // Spread rather than assign: an explicit `authMethods: undefined` would still be an own
                 // property, and "the key is here but empty" is exactly the ambiguity these fields exist to
                 // avoid on the roster's other end.
@@ -512,75 +592,118 @@ export class AcpAgents {
      * exists to prevent one layer up.
      */
     async open(spec) {
-        const resolved = await this.resolveLaunchFor(spec.agentId, spec.command, spec.args);
+        const requestId = spec.openRequestId ?? randomUUID();
+        const openStarted = performance.now();
+        // Log identifiers and timing only: commands, environment, cwd and lease headers can hold secrets.
+        const phase = async (name, work) => {
+            const started = performance.now();
+            const log = (status) => console.info(`${new Date().toISOString()} [acp-open] request=${JSON.stringify(requestId)} agent=${JSON.stringify(spec.agentId)}` +
+                ` phase=${name} status=${status} durationMs=${Math.round(performance.now() - started)}` +
+                ` totalMs=${Math.round(performance.now() - openStarted)}`);
+            log('started');
+            try {
+                const result = await work();
+                log('completed');
+                return result;
+            }
+            catch (error) {
+                log('failed');
+                throw error;
+            }
+        };
+        let resolved = await phase('prepare-launch', () => this.resolveLaunchFor(spec.agentId, spec.command, spec.args));
+        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();
-        const connection = await this.connectResolved(spec.agentId, resolved, spec.env, spec.agentEnv, {
-            // Both registrations go in one hook: `ClientApp.connect()` copies its handler table once, so
-            // this is the only moment either of them can be installed (see `acpClient.ts`'s
-            // `ConnectAgentOptions.configure`).
-            //
-            // The capture goes FIRST, and the order is load-bearing rather than stylistic. The SDK awaits
-            // every handler in registration order (`jsonrpc.js`'s `processIncomingMessage`), so each one
-            // ahead of the capture costs it a microtask hop before it ever sees a `session/update` — while
-            // the response that ends the same `session/load` / `session/prompt` is applied synchronously
-            // off the reader. Registering the capture behind the three permission handlers is what made
-            // that gap wide enough to observe (measured: a turn's trailing deltas arriving after its own
-            // `stop`). `settleUpdates` is the actual fix — this is defence in depth, and it is not a
-            // substitute: nothing here forces the capture to stay first.
-            //
-            // ## Prerequisite for anything added to this hook: **every handler registered here must be
-            // ## synchronous with respect to `session/update`**
-            //
-            // This is where that property is established, so this is where it is written down —
-            // `settleUpdates` (`adoption.ts`) depends on it and cannot check it. It waits one macrotask
-            // boundary, which drains a chain of *synchronous* handlers' microtask continuations and
-            // nothing more; a handler that awaits a real macrotask (a timer, a file read, a subprocess,
-            // an HTTP call) before returning `Handled.no` moves the rest of the chain past that boundary
-            // and the wait ends with **zero** updates delivered — measured, and silent apart from
-            // `settleUpdates`' own maxRounds diagnostic, which this failure does not even trip.
-            //
-            // Both current registrations satisfy it. `capture.register` is a plain synchronous
-            // `onNotification` body. The permission handlers do block on a human answer, but only for
-            // `session/request_permission` and `elicitation/*`; for a `session/update` they fall through
-            // without awaiting anything real. Anything added here later has to clear the same bar — if it
-            // genuinely needs to await, it must do that work *after* handing the message on, not before.
-            configure: (app) => {
-                capture.register(app);
-                // **No `present` here, and that is a decision rather than an omission.** A session
-                // connection lives for hours; a `url` elicitation raised on one is not a sign-in the reader
-                // asked for, and there is no login for a card on screen to belong to. So
-                // `handleCreateElicitation` declines it rather than accepting into a void, which is an
-                // answer the agent can act on. The one connection that *does* wire both callbacks is the
-                // throwaway one {@link authenticate} opens — see {@link connectFor}. The stderr half of the
-                // same rule is enforced by the compiler: `ConnectAgentOptions.present` is typed `never`, so
-                // this call's sibling option cannot arm the sniffer on a session either.
+        let connection;
+        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`).
                 //
-                // `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: () => { } });
-            },
-        });
+                // 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: () => { } });
+                },
+            }));
+        }
+        catch (error) {
+            await startup?.dispose();
+            if (startup)
+                throw new Error('Managed Qoder startup could not initialize');
+            throw error;
+        }
         this.observe(spec.agentId, observationOf(connection));
         try {
-            const started = await this.startSession(connection, capture, spec);
+            if (startup && (connection.agentInfo?.name !== 'qoder-cli' || connection.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));
             // 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),
+                session: hostedSession(started.session, connection, started.history, started.configOptions, startup?.dispose),
                 nativeSessionId: started.nativeSessionId,
             };
         }
         catch (error) {
             await connection.close().catch(() => undefined);
+            await startup?.dispose();
             // Marked, not merely rethrown: everything above this `try` failed before the agent said
             // anything, and only a failure from here on can be an `auth_required`. See
             // {@link AgentRefusedSessionError} — `agentSessions.ts` is the reader.
-            throw new AgentRefusedSessionError(error);
+            throw new AgentRefusedSessionError(error, startup ? 'Managed Qoder session could not open' : undefined);
         }
     }
     /**
@@ -604,6 +727,22 @@ export class AcpAgents {
             await connection.close().catch(() => undefined);
         }
     }
+    /**
+     * Delete native sessions over `session/delete`, via a throwaway connection. Per-id outcomes; an
+     * agent that does not advertise `sessionCapabilities.delete` yields `unsupported` for every id
+     * without the method being called. A *connection* failure still throws.
+     */
+    async deleteNativeSessions(spec, ids) {
+        const resolved = await this.resolveLaunchFor(spec.agentId, spec.command, spec.args);
+        const connection = await this.connectResolved(spec.agentId, resolved, spec.env, spec.agentEnv);
+        this.observe(spec.agentId, observationOf(connection));
+        try {
+            return await deleteNativeSessions(connection, ids);
+        }
+        finally {
+            await connection.close().catch(() => undefined);
+        }
+    }
     /**
      * Verify one agent on demand: spawn it, negotiate `initialize`, try to open a session, then throw
      * the whole thing away. Nothing is kept running — a verification is a question, not a resource.
@@ -632,68 +771,27 @@ export class AcpAgents {
         try {
             let observed;
             let observedConfig;
+            const started = Date.now();
             await withDeadline((async () => {
-                const opened = await AcpSession.open(connection, { cwd: spec.cwd });
-                // Captured off `session/new`'s own response, not off the settle wait below: the snapshot
-                // exists the moment `AcpSession.open` resolves, unlike the command table, which the agent
-                // only broadcasts afterwards.
-                observedConfig = opened.configOptions;
-                // The table is broadcast *after* `session/new` is answered (`acp-agent.js:752-757`), so a
-                // verification that closed here — as this one used to — could never see it. The sink is
-                // attached after `open` on purpose and is still safe: `AcpSession` buffers events until
-                // one is attached (`onEvent`'s `drain()`), so nothing that arrived in between is lost.
-                // Settle rather than "first push wins": Claude broadcasts twice — once on `session/new`
-                // and again when the init frame lets it filter out terminal-bound commands. Taking the
-                // first would leave commands in the menu that do nothing over ACP.
-                //
-                // 但**不能靠一个固定的等待**。这里原本是 `setTimeout(1500)` 死等，于是这段代码在和
-                // agent 的广播赛跑，而且**机器越快越容易输**：`session/new` 秒回时,1.5 秒窗口内广播还
-                // 没到,`observed` 保持 undefined,整张命令表就此丢失。真机上量到过同一个 agent 在热机器
-                // 上 2.1 秒回来 0 条、在慢机器上 8.4 秒回来 72 条 —— 差别只是后者慢到"顺便"等到了。
-                //
-                // 原来是无条件 `setTimeout(1500)` 睡满。改成两段:一条都没来 → 到
-                // [COMMAND_FIRST_BROADCAST_MS] 就收工(与原实现逐字同样的时间与结果);来了第一条 →
-                // 改用安静期收尾,并受 [COMMAND_SETTLE_CEILING_MS] 兜底。**严格不劣于原实现**:
-                // 没有广播的路径一模一样,有广播的路径要么更快,要么多收到一条原本会被丢掉的。
-                let finish;
-                const settled = new Promise((resolve) => {
-                    finish = resolve;
-                });
-                let quietTimer;
-                let ceilingTimer;
-                let firstTimer = setTimeout(() => finish?.(), COMMAND_FIRST_BROADCAST_MS);
-                opened.session.onEvent((event) => {
-                    if (event.eventName !== 'available_commands_update')
-                        return;
-                    const commands = event.payload.availableCommands;
-                    if (Array.isArray(commands))
-                        observed = commands.map(toAvailableCommandWire);
-                    // 第一条到手:等第一条的窗口作废,换成"安静就收工"+ 绝对上限。
-                    if (firstTimer !== undefined) {
-                        clearTimeout(firstTimer);
-                        firstTimer = undefined;
-                        ceilingTimer = setTimeout(() => finish?.(), COMMAND_SETTLE_CEILING_MS);
-                    }
-                    // 每再来一条就把安静计时重新起头 —— Claude 的第二条才是能用的那份。
-                    if (quietTimer !== undefined)
-                        clearTimeout(quietTimer);
-                    quietTimer = setTimeout(() => finish?.(), COMMAND_QUIET_MS);
-                });
-                await settled;
-                if (firstTimer !== undefined)
-                    clearTimeout(firstTimer);
-                if (quietTimer !== undefined)
-                    clearTimeout(quietTimer);
-                if (ceilingTimer !== undefined)
-                    clearTimeout(ceilingTimer);
-                if (observed === undefined) {
-                    // A 那条日志的 daemon 侧对应物。没有它,"这个 agent 在这个目录下没有命令" 与
-                    // "表来晚了、窗口没接住" 在任何一层都分不开 —— 而这两件事的修法完全不同。
-                    console.warn(`[acp] agent '${spec.agentId}' broadcast no command table within ` +
-                        `${COMMAND_FIRST_BROADCAST_MS}ms of opening a session in ${spec.cwd}`);
-                }
-                await opened.session.close().catch(() => undefined);
+                const first = await openAndObserveCommands(connection, spec.cwd, COMMAND_FIRST_BROADCAST_MS);
+                observedConfig = first.configOptions;
+                observed = first.commands;
             })(), timeoutMs, `Opening a session on agent '${spec.agentId}'`);
+            if (observed === undefined) {
+                // p3-fix7 N9: "no table within the window" is unknown, not "this agent has no commands": look once more, with a
+                // longer window. p3-fix7b M-4: on a fresh connection (this one is bound to the first session, so a table pushed
+                // before the retry's session/new answer would read as a stranger's). p3-fix7c 3: the retry is only a second
+                // look for the table — its failure, or the deadline running out during it, leaves the table unknown and never
+                // turns a session that opened into a sessionError.
+                observed = await this.retryCommandTable(spec, timeoutMs - (Date.now() - started));
+            }
+            if (observed === undefined) {
+                // A 那条日志的 daemon 侧对应物。没有它,"这个 agent 在这个目录下没有命令" 与
+                // "表来晚了、窗口没接住" 在任何一层都分不开 —— 而这两件事的修法完全不同。
+                console.warn(`[acp] agent '${spec.agentId}' broadcast no command table within ` +
+                    `${COMMAND_FIRST_BROADCAST_MS}ms (and ${this.commandRetryFirstBroadcastMs}ms on a second session) ` +
+                    `of opening a session in ${spec.cwd}`);
+            }
             this.observe(spec.agentId, { ...observationOf(connection), authenticated: true });
             return {
                 authMethods,
@@ -712,10 +810,40 @@ export class AcpAgents {
             await connection.close().catch(() => undefined);
         }
     }
+    /** p3-fix7c 3: one more look for the command table on a fresh connection; undefined on any failure or timeout. */
+    async retryCommandTable(spec, remainingMs) {
+        if (remainingMs <= 0)
+            return undefined;
+        let retryConnection;
+        let abandoned = false;
+        try {
+            return await withDeadline((async () => {
+                const connection = await this.connectFor(spec, remainingMs);
+                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;
+            })(), remainingMs, `Looking again for agent '${spec.agentId}''s command table`);
+        }
+        catch (error) {
+            abandoned = true;
+            console.warn(`[acp] retry for agent '${spec.agentId}''s command table failed: ${errorMessage(error)}`);
+            return undefined;
+        }
+        finally {
+            await retryConnection?.close().catch(() => undefined);
+        }
+    }
     /**
-     * Run one agent's `authenticate` for a `methodId` **it advertised**, over a throwaway connection.
+     * Run one agent's `authenticate` for a `methodId` **it advertised**, over a throwaway connection —
+     * or, for a terminal-type method, run the sign-in itself ({@link hostTerminalLogin}): ACP forbids
+     * passing a terminal method to `authenticate`, and the workstation is the terminal's host (spec
+     * 2026-09-24 D6/D12).
      *
-     * The refusal for an unadvertised (or terminal) `methodId` is {@link AcpAuth}'s and happens before
+     * The refusal for an unadvertised non-terminal `methodId` is {@link AcpAuth}'s and happens before
      * anything is written to the agent — which is why this hands `AcpAuth` the connection rather than
      * re-deriving the check: there is exactly one place that rule lives.
      *
@@ -735,11 +863,26 @@ export class AcpAgents {
         // is ordinary — the scan covers the `npx` install, whose own output can carry a "visit this
         // URL" line, and a login whose agent then fails to install is exactly when that appears.
         try {
+            // Spec 2026-09-24 D10: a sign-in almost always follows the connection that hit
+            // `auth_required`, which already read this method. Reuse it rather than cold-start the agent.
+            const remembered = this.observed.get(spec.agentId)?.terminalLogins?.get(methodId);
+            if (remembered) {
+                await this.hostTerminalLogin(spec, remembered, urls.present, login);
+                return;
+            }
             const connection = await this.connectFor(spec, AGENT_PROBE_TIMEOUT_MS, {
                 ...(urls.present ? { present: urls.present } : {}),
                 dismiss: urls.dismiss,
             });
             this.observe(spec.agentId, observationOf(connection));
+            const terminal = connection.terminalLogins.get(methodId);
+            if (terminal) {
+                // ACP: a terminal method is never passed to `authenticate`. This connection has nothing
+                // left to do, and a login can take minutes — do not hold an agent process open for it.
+                await connection.close().catch(() => undefined);
+                await this.hostTerminalLogin(spec, terminal, urls.present, login);
+                return;
+            }
             try {
                 const what = `Signing in to agent '${spec.agentId}' with method '${methodId}'`;
                 await withDeadline(cancellable(new AcpAuth(connection).authenticate(methodId), login.signal, what), loginDeadlineMs(login.ceilingMs), what);
@@ -756,6 +899,20 @@ export class AcpAgents {
             urls.finish();
         }
     }
+    /**
+     * Run a terminal sign-in on this machine (spec 2026-09-24 D7, D9). The launch is resolved the same
+     * way a session's is, because the standard shape appends to it; the `_meta` shape ignores it.
+     */
+    async hostTerminalLogin(spec, terminal, present, login) {
+        const launch = terminal.kind === 'meta'
+            ? { command: terminal.command, args: [], env: {} }
+            : (await this.resolveLaunchFor(spec.agentId, spec.command, spec.args)).launch;
+        await runTerminalLogin(terminalInvocationFor(terminal, launch, { ...spec.env, ...spec.agentEnv }), {
+            ...(present ? { present } : {}),
+            ...(login.signal ? { signal: login.signal } : {}),
+            deadlineMs: loginDeadlineMs(login.ceilingMs),
+        });
+    }
     /**
      * The spawn half shared by {@link verify} and {@link authenticate}. No session either way — but
      * **not "no handlers" any more**, and the difference is the whole of Task 4b: `authenticate` is a
@@ -807,7 +964,7 @@ export class AcpAgents {
                 });
             },
         };
-        return withUnpinnedFallback(spec.agentId, resolved, (launch) => connectAgent(launch, spec.env, spec.agentEnv, options));
+        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
@@ -818,6 +975,8 @@ export class AcpAgents {
      * 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
@@ -826,8 +985,38 @@ export class AcpAgents {
      */
     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}'`);
             }
@@ -839,11 +1028,14 @@ export class AcpAgents {
                 // 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);
                         },
@@ -851,19 +1043,27 @@ export class AcpAgents {
                         // 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 });
+        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 };
     }
     /**
@@ -891,30 +1091,34 @@ export class AcpAgents {
      * All three distributions are fetched, not just npx — see {@link installAdapter}, which dispatches
      * npx → uvx → binary in `resolveLaunch`'s own preference order.
      *
-     * ## The catalog's `dependency` runs first, and can refuse to run anything at all
+     * ## The catalog's `prerequisite` runs first, and can refuse to run anything at all
      *
-     * `registry/catalog.ts` may curate one extra prerequisite for an agent (`pi-acp` needs the `pi`
-     * CLI) that the adapter fetch above does nothing to provide. That block is handled *before* the
-     * adapter step, in two gates:
+     * `registry/catalog.ts` may curate one prerequisite for an agent (`pi-acp` needs the `pi` CLI,
+     * `zcode-acp` the ZCode desktop app) that the adapter fetch above does nothing to provide. That
+     * block is handled *before* the adapter step, in up to three gates:
      *
      * 1. `requiresNode`, checked against this daemon's own `process.version` (or the injected
      *    `nodeVersion`, for tests) — because npm only *warns*, never refuses, on an `engines`
-     *    mismatch. On a Node-20 machine `npm install -g` for `pi` "succeeds", `findOnPath` then finds
+     *    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 `findOnPath` probe below, since there would be nothing useful to install anyway.
-     * 2. `check` on `PATH` (via `findOnPath`) — only when that comes back empty does this call the
+     *    even the detection below, since there would be nothing useful to install anyway.
+     * 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 `dependency` block, skips straight to the adapter
+     * 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.
      *
      * Never starts the agent: see {@link installNpxPackage}.
      */
     async install(agentId, options = {}) {
-        const dependency = catalogEntryFor(agentId)?.dependency;
+        const dependency = catalogEntryFor(agentId)?.prerequisite;
         if (dependency) {
             const nodeVersion = options.nodeVersion ?? process.version;
             if (dependency.requiresNode && !semver.satisfies(nodeVersion, dependency.requiresNode)) {
@@ -927,7 +1131,13 @@ export class AcpAgents {
             }
         }
         let dependencyInstalled;
-        if (dependency && findOnPath(dependency.check, this.probe) === undefined) {
+        if (dependency && !this.prerequisiteSatisfied(agentId)) {
+            if (!dependency.install) {
+                return {
+                    ok: false,
+                    error: dependency.hint ?? `Agent '${agentId}' needs ${dependency.label}, which is not installed on this machine.`,
+                };
+            }
             const [command, ...args] = dependency.install;
             const outcome = await this.runCommand(command, args, { timeoutMs: options.timeoutMs });
             if (!outcome.ok) {
@@ -985,7 +1195,16 @@ export class AcpAgents {
     async installAdapter(agent, timeoutMs) {
         const { npx, uvx, binary } = agent.distribution;
         if (npx) {
-            return this.installNpxWithFallback(agent, npx.package, timeoutMs);
+            const installed = await this.installNpxWithFallback(agent, npx.package, timeoutMs);
+            if (!installed.ok || installed.pinnedVersionUnavailable)
+                return installed;
+            try {
+                await preparePatchedLaunch(agent, await resolveLaunch(agent, this.platform, this.arch, this.adapterRoot), this.adapterRoot, this.probe, { timeoutMs, npxCommand: this.npxCommand });
+                return installed;
+            }
+            catch (error) {
+                return { ok: false, error: `Adapter patch preparation failed: ${String(error)}` };
+            }
         }
         if (uvx) {
             // `uv tool install <pkg>==<ver>`, not `uvx <pkg>`: the launch path reads the entry point out
@@ -1104,29 +1323,29 @@ export class AcpAgents {
         };
     }
     /**
-     * Whether the catalog's extra prerequisite for this agent (`registry/catalog.ts`'s `dependency`)
-     * is already on `PATH` — never whether the adapter itself has been fetched, and never whether
-     * this daemon's Node satisfies `requiresNode` (that gate only matters at {@link install} time, not
-     * for reporting what is already on the machine). An agent outside the catalog, or one with no
-     * `dependency` block, needs nothing extra and reads as satisfied.
+     * Whether the catalog's prerequisite for this agent (`registry/catalog.ts`'s `prerequisite`) is
+     * detected on this machine (`registry/detect.ts`) — never whether the adapter itself has been
+     * fetched, and never whether this daemon's Node satisfies `requiresNode` (that gate only matters
+     * at {@link install} time, not for reporting what is already on the machine). An agent outside the
+     * catalog, or one with no `prerequisite` block, needs nothing extra and reads as satisfied.
      *
-     * {@link roster} folds this into `adapterInstalled`: an agent whose adapter is on disk but whose
-     * curated prerequisite is not reports **not installed**, so its card offers `Install` (which
-     * fetches the dependency) instead of an `Add` whose try-run was always going to fail on
+     * {@link roster} makes the same reading for `adapterInstalled`: an agent whose adapter is on disk
+     * but whose curated prerequisite is not reports **not installed**, so its card offers `Install`
+     * (which fetches the prerequisite) instead of an `Add` whose try-run was always going to fail on
      * `Could not start pi: executable not found`. Design §4.4, point 2.
      */
-    dependencySatisfied(agentId, probe = this.probe) {
-        const dependency = catalogEntryFor(agentId)?.dependency;
-        if (!dependency)
+    prerequisiteSatisfied(agentId, probe = this.probe) {
+        const prerequisite = catalogEntryFor(agentId)?.prerequisite;
+        if (!prerequisite)
             return true;
-        return findOnPath(dependency.check, probe) !== undefined;
+        return detected(prerequisite.detect, probe, platformTriple(this.platform, this.arch));
     }
     /** A config-supplied `command` is the whole launch spec (ruling R3); otherwise the registry decides. */
     async resolveLaunchFor(agentId, command, args) {
         // 裁决 R3 的覆盖没有回退可言:用户自己写下的命令行就是**全部**,这里不该去猜他们的哪一段
         // 参数是版本号。
         if (command)
-            return { launch: { command, args, env: {} } };
+            return { launch: { command, args, env: {} }, source: 'command-override' };
         const agents = await this.registry.load();
         const agent = agents.find((candidate) => candidate.id === agentId);
         if (!agent) {
@@ -1136,7 +1355,8 @@ export class AcpAgents {
         // 每次启动都从刚读到的 registry 现算一遍,没有任何一处把回退记下来:上游把版本修好的那一刻,
         // 钉版本的那条路自己就恢复了,不需要谁去清什么状态。
         return {
-            launch: await resolveLaunch(agent, this.platform, this.arch, this.adapterRoot),
+            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),
         };
     }
@@ -1151,7 +1371,7 @@ export class AcpAgents {
      * further along; `connectFor` builds its own options now.
      */
     async connectResolved(agentId, resolved, env, agentEnv, options = {}) {
-        return withUnpinnedFallback(agentId, resolved, (launch) => connectAgent(launch, env, agentEnv, options));
+        return withUnpinnedFallback(agentId, resolved, (launch, source) => connectAgent(launch, env, agentEnv, { ...options, launchSource: source }));
     }
     /**
      * Whether `resolveLaunch` can produce a spec for this agent on this machine (see {@link roster}).
@@ -1199,7 +1419,7 @@ export class AcpAgents {
  */
 async function withUnpinnedFallback(agentId, resolved, attempt) {
     try {
-        return await attempt(resolved.launch);
+        return await attempt(resolved.launch, resolved.source);
     }
     catch (error) {
         const fallback = resolved.fallback;
@@ -1213,7 +1433,7 @@ async function withUnpinnedFallback(agentId, resolved, attempt) {
             "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);
+        return await attempt(fallback.launch, 'registry-fallback');
     }
 }
 /**
@@ -1227,7 +1447,7 @@ async function withUnpinnedFallback(agentId, resolved, attempt) {
  * 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) {
+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.
@@ -1237,7 +1457,7 @@ function hostedSession(session, connection, history, configOptions) {
         // (`session.prompt([{ type: 'text', text }])`) — a stopgap for as long as `agent_prompt` could
         // only carry text. That seam is gone: the frame now carries blocks, so wrapping here would be a
         // second, narrower opinion about the shape of a user message.
-        prompt: (blocks) => session.prompt(blocks),
+        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() {
@@ -1247,6 +1467,7 @@ function hostedSession(session, connection, history, configOptions) {
             };
         },
         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);
@@ -1256,6 +1477,7 @@ function hostedSession(session, connection, history, 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,
@@ -1263,9 +1485,15 @@ function hostedSession(session, connection, history, configOptions) {
         // 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();
@@ -1274,6 +1502,7 @@ function hostedSession(session, connection, history, configOptions) {
                 // 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?.();
             }
         },
     };
@@ -1285,3 +1514,55 @@ function hostedSession(session, connection, history, configOptions) {
     }
     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).
+ *
+ * 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
+ * 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 };
+}