@vellumai/assistant 0.12.2 → 0.12.3-staging.2

package/src/credential-execution/ces-runtime.ts

@@ -9,10 +9,16 @@ import {
   setCesReconnect,
 } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
-import { type CesClient, createCesClient } from "./client.js";
+import {
+  openCesRpcSession,
+  reconnectCesRpcSession,
+} from "./ces-connect.js";
+import {
+  type CesClient,
+  type CesClientHandshakeOptions,
+} from "./client.js";
 import {
   type CesProcessManager,
-  CesUnavailableError,
   createCesProcessManager,
 } from "./process-manager.js";
 import {
@@ -45,70 +51,69 @@ interface CesStartupResult {
 }
 
 /**
- * Start the CES process and perform the RPC handshake. Returns immediately with
- * handles to the in-flight initialization — callers don't need to await this
- * for startup to continue.
+ * Open the assistant's CES RPC client and perform the handshake. Returns
+ * immediately with handles to the in-flight initialization: callers don't
+ * need to await this for startup to continue.
  *
- * The managed sidecar accepts exactly one bootstrap connection, so this must be
- * called at the process level (not per-conversation).
+ * Claims reconnect ownership before any credential read so boot identity
+ * loading cannot open a second, identity-less session through the child
+ * entry point. CES serves a multi-connection Unix socket, so child
+ * processes in other address spaces still open their own connections.
  */
 function startCesProcess(config: AssistantConfig): CesStartupResult {
   const pm = createCesProcessManager({ assistantConfig: config });
   const abortController = new AbortController();
   let currentClient: CesClient | undefined;
+  let handshake: CesClientHandshakeOptions = {};
+
+  // Own this process's CES session before resolveManagedProxyContext()
+  // reads the API key. That read must not take the child open path.
+  setCesReconnect(async () => {
+    const client = await reconnectCesRpcSession(pm, handshake);
+    if (client) {
+      log.info("CES reconnection handshake accepted");
+    }
+    return client;
+  });
 
   const handshakePromise = (async (): Promise<CesClient | undefined> => {
     try {
-      const transport = await pm.start();
-      if (abortController.signal.aborted) {
-        throw new Error("CES initialization aborted during shutdown");
-      }
-      const client = createCesClient(transport);
-      currentClient = client;
       // Resolve the assistant API key so CES can use it for platform
       // credential materialisation. In managed mode the key is provisioned
-      // after hatch and stored in the credential store — CES can't read
-      // the env var, so we pass it via the handshake.
+      // after hatch and stored in the credential store. CES can't read
+      // the env var, so we pass it via the handshake. Reconnect ownership
+      // is already claimed, so this read uses HTTP or the encrypted store,
+      // not a second RPC session.
       const proxyCtx = await resolveManagedProxyContext();
+      if (abortController.signal.aborted) {
+        return undefined;
+      }
       const assistantId = getPlatformAssistantId();
-      const { accepted, reason } = await client.handshake({
+      handshake = {
         ...(proxyCtx.assistantApiKey
           ? { assistantApiKey: proxyCtx.assistantApiKey }
           : {}),
         ...(assistantId ? { assistantId } : {}),
+      };
+      const session = await openCesRpcSession({
+        processManager: pm,
+        signal: abortController.signal,
+        handshake,
       });
-      if (abortController.signal.aborted) {
-        client.close();
-        throw new Error("CES initialization aborted during shutdown");
-      }
-      if (accepted) {
+      currentClient = session?.client;
+      if (session) {
         log.info(
           "CES client initialized and handshake accepted (server-level)",
         );
-        return client;
       }
+      return session?.client;
+    } catch (err) {
       log.warn(
-        { reason },
-        "CES handshake rejected — CES tools will be unavailable",
+        { error: err instanceof Error ? err.message : String(err) },
+        "Failed to initialize CES client",
       );
-      client.close();
       currentClient = undefined;
-      await pm.stop();
-      return undefined;
-    } catch (err) {
-      if (err instanceof CesUnavailableError) {
-        log.info(
-          { reason: err.message },
-          "CES is not available — CES tools will be unavailable",
-        );
-      } else {
-        log.warn(
-          { error: err instanceof Error ? err.message : String(err) },
-          "Failed to initialize CES client — CES tools will be unavailable",
-        );
-      }
       await pm.stop().catch(() => {});
-      currentClient = undefined;
       return undefined;
     }
   })();
@@ -154,11 +159,11 @@ function updateClientRef(client: CesClient | undefined): void {
 }
 
 /**
- * Bring up the daemon's CES connection: start the process, run the handshake
- * (blocking up to a 20s timeout so credential reads can route through CES
- * before provider init), register the reconnection callback, and keep the live
- * client reference in sync. Non-fatal — on failure the daemon falls back to the
- * direct credential store.
+ * Open the assistant's CES RPC client: handshake (blocking up to a 20s
+ * timeout so credential reads can route through CES before provider init)
+ * and keep the live client reference in sync. Reconnect ownership is
+ * claimed before the identity read. Non-fatal: on failure the assistant
+ * falls back to the direct credential store.
  */
 export async function startCes(config: AssistantConfig): Promise<void> {
   const cesResult = startCesProcess(config);
@@ -171,7 +176,7 @@ export async function startCes(config: AssistantConfig): Promise<void> {
       timeoutMs: DEFAULT_CES_STARTUP_TIMEOUT_MS,
       onTimeout: () => {
         log.warn(
-          "CES handshake timed out after 20s — falling back to direct credential store",
+          "CES handshake timed out after 20s, falling back to direct credential store",
         );
       },
     });
@@ -193,56 +198,13 @@ export async function startCes(config: AssistantConfig): Promise<void> {
     }
   }
 
-  // Register CES reconnection callback so the credential layer can re-establish
-  // the connection when the transport dies, instead of falling back to the
-  // encrypted file store.
+  // Reconnect ownership is claimed inside startCesProcess before the
+  // identity read. Snapshotting the API key there (not here) avoids a
+  // second resolveManagedProxyContext() after setCesClient, which would
+  // read the key through CES while reconnecting.
   if (cesResult.processManager) {
     const pm = cesResult.processManager;
 
-    // Snapshot the managed-proxy context and assistant ID at CES startup so the
-    // reconnect closure below never calls back into `resolveManagedProxyContext()`.
-    // That function reads the assistant API key via `getSecureKeyAsync()`, which
-    // — once `setCesClient()` has resolved the backend to CES RPC — routes the
-    // read through CES itself. During a reconnect the old transport is dead and
-    // a new one is being set up by this very closure, so the nested credential
-    // read recursively awaits its own in-flight reconnection and deadlocks until
-    // `CREDENTIAL_OP_TIMEOUT_MS` (45s) fires. That 45-second stall delays every
-    // CES restart and causes dependent credential reads (e.g. Meet's STT
-    // provider resolution) to return `undefined` during the window. API key
-    // rotation uses the `updateAssistantApiKey` RPC on the live client, not a
-    // reconnect, so caching at startup is safe.
-    const startupProxyCtx = await resolveManagedProxyContext();
-    const startupAssistantId = getPlatformAssistantId();
-
-    setCesReconnect(async () => {
-      try {
-        await pm.stop();
-        const transport = await pm.start();
-        const newClient = createCesClient(transport);
-        const { accepted, reason } = await newClient.handshake({
-          ...(startupProxyCtx.assistantApiKey
-            ? { assistantApiKey: startupProxyCtx.assistantApiKey }
-            : {}),
-          ...(startupAssistantId ? { assistantId: startupAssistantId } : {}),
-        });
-        if (accepted) {
-          log.info("CES reconnection handshake accepted");
-          return newClient;
-        }
-        log.warn({ reason }, "CES reconnection handshake rejected");
-        newClient.close();
-        await pm.stop().catch(() => {});
-        return undefined;
-      } catch (err) {
-        log.warn(
-          { error: err instanceof Error ? err.message : String(err) },
-          "CES reconnection attempt failed",
-        );
-        await pm.stop().catch(() => {});
-        return undefined;
-      }
-    });
-
     // Proactive reconnect: when the transport dies (socket close, process
     // exit), start a retry-with-backoff loop immediately instead of waiting
     // for the next credential operation to trigger the lazy reconnect path.

package/src/credential-execution/executable-discovery.ts

@@ -1,196 +1,88 @@
 /**
- * CES executable discovery and transport bootstrap.
+ * CES socket discovery and transport bootstrap.
  *
- * Provides two discovery strategies:
- *
- * 1. **Sibling mode** — Locates the CLI-launched CES sibling process via its
- *    Unix socket (`CES_LOCAL_SOCKET`). Used by bare-metal/local instances.
- *
- * 2. **Managed mode** — Locates the bootstrap Unix socket exposed by the CES
- *    sidecar container through a shared emptyDir volume, and returns a
- *    connected Unix socket transport.
- *
- * Both strategies fail closed: if the socket cannot be found, the discovery
- * returns a structured error rather than falling back to in-process
- * credential handling.
+ * Local siblings and managed sidecars share one resolver: `ces.sock` under
+ * `CES_BOOTSTRAP_SOCKET_DIR` (default `/run/ces-bootstrap`). Discovery fails
+ * closed if the socket cannot be found.
  */
 
 import { existsSync } from "node:fs";
-import { join } from "node:path";
 
-import { getIsContainerized } from "../config/env-registry.js";
+import {
+  isNamedPipePath,
+  resolveIpcEndpoint,
+} from "@vellumai/ipc-server-utils";
+
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("ces-discovery");
 
-// ---------------------------------------------------------------------------
-// Well-known paths
-// ---------------------------------------------------------------------------
-
-/** Default directory for the bootstrap socket shared volume. */
+/** Default directory for the CES Unix socket. */
 const DEFAULT_BOOTSTRAP_SOCKET_DIR = "/run/ces-bootstrap";
 
-/** Bootstrap socket filename. */
-const BOOTSTRAP_SOCKET_NAME = "ces.sock";
-
 /**
- * Resolve the CES bootstrap socket path.
- *
- * Priority:
- * 1. `CES_BOOTSTRAP_SOCKET_DIR` env var (directory) — appends `ces.sock`
- * 2. `CES_BOOTSTRAP_SOCKET` env var (full file path override)
- * 3. Hardcoded default: `/run/ces-bootstrap/ces.sock`
+ * Resolve the CES socket path used in every environment.
  *
- * The pod template exports `CES_BOOTSTRAP_SOCKET_DIR`; the full-path
- * override is kept for local testing convenience.
+ * Uses `CES_BOOTSTRAP_SOCKET_DIR` when set, otherwise `/run/ces-bootstrap`.
+ * `ces.sock` is resolved through `resolveIpcEndpoint`.
  */
-function getManagedBootstrapSocketPath(): string {
-  const dir = process.env["CES_BOOTSTRAP_SOCKET_DIR"];
-  if (dir) {
-    return join(dir, BOOTSTRAP_SOCKET_NAME);
-  }
-  return (
-    process.env["CES_BOOTSTRAP_SOCKET"] ??
-    join(DEFAULT_BOOTSTRAP_SOCKET_DIR, BOOTSTRAP_SOCKET_NAME)
-  );
+function getCesSocketPath(): string {
+  const dir =
+    process.env["CES_BOOTSTRAP_SOCKET_DIR"]?.trim() ||
+    DEFAULT_BOOTSTRAP_SOCKET_DIR;
+  return resolveIpcEndpoint("ces", { workspaceDir: dir }).path;
 }
 
-// ---------------------------------------------------------------------------
-// Discovery result types
-// ---------------------------------------------------------------------------
-
 export interface ManagedDiscoverySuccess {
   mode: "managed";
   socketPath: string;
 }
 
-/**
- * A local CES running as an independent sibling process (not spawned by the
- * assistant), reached over a Unix socket. Transport-identical to managed; the
- * distinct mode records that the assistant does not own this process's
- * lifecycle. This is the default topology for bare-metal/local instances.
- */
-export interface SiblingDiscoverySuccess {
-  mode: "sibling";
-  socketPath: string;
-}
-
 export interface DiscoveryFailure {
   mode: "unavailable";
   reason: string;
 }
 
-export type DiscoveryResult =
-  | ManagedDiscoverySuccess
-  | SiblingDiscoverySuccess
-  | DiscoveryFailure;
-
-// ---------------------------------------------------------------------------
-// Managed discovery
-// ---------------------------------------------------------------------------
+export type DiscoveryResult = ManagedDiscoverySuccess | DiscoveryFailure;
 
 /**
- * Discover the managed CES sidecar via its bootstrap Unix socket.
- *
- * Checks that the well-known socket file exists on disk. Does NOT open a
- * connection — the CES sidecar accepts exactly one connection and then
- * unlinks the socket, so a probe would consume the only slot. The actual
- * connection is made later by `CesProcessManager.start()`.
+ * Discover CES via the shared bootstrap Unix socket.
  *
- * The socket path is derived from `CES_BOOTSTRAP_SOCKET_DIR` (matching the
- * pod template), with `CES_BOOTSTRAP_SOCKET` as a full-path fallback.
+ * Checks that the well-known socket exists. Does not open a connection.
+ * CES serves a multi-connection listener, so the assistant and its child
+ * processes can each connect. The actual connection is made later by
+ * `CesProcessManager.start()`.
  */
-export function discoverManagedCes():
-  | ManagedDiscoverySuccess
-  | DiscoveryFailure {
-  const socketPath = getManagedBootstrapSocketPath();
+export function discoverCes(): DiscoveryResult {
+  const socketPath = getCesSocketPath();
 
-  if (!existsSync(socketPath)) {
+  if (!isNamedPipePath(socketPath) && !existsSync(socketPath)) {
     const reason = `CES bootstrap socket not found at ${socketPath}`;
     log.warn(reason);
     return { mode: "unavailable", reason };
   }
 
-  log.info({ socketPath }, "Managed CES bootstrap socket found");
+  log.info({ socketPath }, "CES bootstrap socket found");
   return { mode: "managed", socketPath };
 }
 
-// ---------------------------------------------------------------------------
-// Sibling discovery (local bare-metal topology)
-// ---------------------------------------------------------------------------
-
-/**
- * Discover a CLI-launched local CES sibling via its Unix socket. The CLI sets
- * `CES_LOCAL_SOCKET` on both the sibling and the daemon so they agree on the
- * path. Does not open a connection — that happens in `CesProcessManager.start()`.
- */
-export function discoverLocalSiblingCes():
-  | SiblingDiscoverySuccess
-  | DiscoveryFailure {
-  const socketPath = process.env["CES_LOCAL_SOCKET"];
-  if (!socketPath) {
-    const reason =
-      "CES_LOCAL_SOCKET is not set — cannot locate the CES sibling socket. The CLI should set this during wake/hatch.";
-    log.warn(reason);
-    return { mode: "unavailable", reason };
-  }
-  if (!existsSync(socketPath)) {
-    return {
-      mode: "unavailable",
-      reason: `CES sibling socket not found at ${socketPath}`,
-    };
-  }
-  log.info({ socketPath }, "Local CES sibling socket found");
-  return { mode: "sibling", socketPath };
-}
-
-// ---------------------------------------------------------------------------
-// Auto-discovery
-// ---------------------------------------------------------------------------
-
-/**
- * Automatically discover CES using the appropriate strategy for the
- * current deployment topology.
- *
- * - Containerized environments → managed sidecar discovery
- * - Non-containerized → CLI-launched sibling socket discovery
- */
-export function discoverCes(): DiscoveryResult {
-  if (getIsContainerized()) {
-    return discoverManagedCes();
-  }
-  return discoverLocalSiblingCes();
-}
-
-/** How long to poll for the managed bootstrap socket before giving up. */
+/** How long to poll for the CES socket before giving up. */
 const MANAGED_DISCOVERY_TIMEOUT_MS = 3_000;
 
-/** Delay between managed bootstrap-socket discovery attempts. */
+/** Delay between CES socket discovery attempts. */
 const MANAGED_DISCOVERY_INTERVAL_MS = 100;
 
 /**
- * Discover CES, polling for the managed bootstrap socket with a short
- * backoff before failing.
- *
- * The managed CES sidecar re-binds its bootstrap socket after each assistant
- * session ends — it outlives any single assistant and accepts the next
- * connection (see `credential-executor/src/main.ts`). A reconnecting
- * assistant (e.g. after a container restart) can therefore probe during the
- * brief window before the socket is re-bound. A single existence check would
- * race that window and incorrectly report the sidecar as unavailable; polling
- * absorbs the gap.
+ * Discover CES, polling for the socket with a short backoff before failing.
  *
- * Local discovery is returned immediately — a missing binary will not appear
- * by waiting, so there is nothing to poll for.
+ * CES binds its socket asynchronously. A reconnecting assistant can probe
+ * during the brief window before the socket is re-bound. Polling absorbs
+ * that gap.
  */
 export async function discoverCesWithRetry({
   timeoutMs = MANAGED_DISCOVERY_TIMEOUT_MS,
   intervalMs = MANAGED_DISCOVERY_INTERVAL_MS,
 }: { timeoutMs?: number; intervalMs?: number } = {}): Promise<DiscoveryResult> {
-  // Both the managed bootstrap socket and the CLI-launched sibling socket
-  // are bound asynchronously, so polling is worthwhile. A missing local
-  // binary (the old stdio path) would not appear by waiting, but that path
-  // is gone — the sibling is the only local topology now.
   const deadline = Date.now() + timeoutMs;
   let result = discoverCes();
   while (result.mode === "unavailable" && Date.now() < deadline) {

package/src/credential-execution/process-manager.test.ts

@@ -3,12 +3,10 @@ import { createServer, type Server } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
-  afterAll,
   afterEach,
   beforeEach,
   describe,
   expect,
-  mock,
   test,
 } from "bun:test";
 
@@ -21,22 +19,18 @@ const untilClosed = (predicate: () => boolean) =>
     message: "socket close never propagated to the transport",
   });
 
-// ---------------------------------------------------------------------------
-// onTransportClose tests
-// ---------------------------------------------------------------------------
-
-// Mock executable-discovery so start() connects to our test socket.
-const realDiscovery = await import("./executable-discovery.js");
-
 let mockSocketPath = "";
 
-mock.module("./executable-discovery.js", () => ({
-  ...realDiscovery,
-  discoverCesWithRetry: async () => ({
-    mode: "sibling" as const,
+function discoverTestSocket() {
+  return Promise.resolve({
+    mode: "managed" as const,
     socketPath: mockSocketPath,
-  }),
-}));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// onTransportClose tests
+// ---------------------------------------------------------------------------
 
 describe("CesProcessManager.onTransportClose", () => {
   let tempDir: string;
@@ -67,12 +61,8 @@ describe("CesProcessManager.onTransportClose", () => {
     rmSync(tempDir, { recursive: true, force: true });
   });
 
-  afterAll(() => {
-    mock.module("./executable-discovery.js", () => realDiscovery);
-  });
-
   test("fires handler when the transport dies (socket closed)", async () => {
-    const pm = createCesProcessManager({});
+    const pm = createCesProcessManager({ discover: discoverTestSocket });
     const transport = await pm.start();
     expect(transport.isAlive()).toBe(true);
 
@@ -93,7 +83,7 @@ describe("CesProcessManager.onTransportClose", () => {
   });
 
   test("does not fire handler before the transport dies", async () => {
-    const pm = createCesProcessManager({});
+    const pm = createCesProcessManager({ discover: discoverTestSocket });
     await pm.start();
 
     let closeFired = false;
@@ -109,7 +99,7 @@ describe("CesProcessManager.onTransportClose", () => {
   });
 
   test("fires handler immediately if transport is already dead", async () => {
-    const pm = createCesProcessManager({});
+    const pm = createCesProcessManager({ discover: discoverTestSocket });
     const transport = await pm.start();
 
     // Kill the transport by destroying the server-side socket.
@@ -186,7 +176,10 @@ describe("CesProcessManager transport-death logging", () => {
 
   test("logs WARN when the transport dies unexpectedly (remote close)", async () => {
     const { calls, logger } = makeRecordingLogger();
-    const pm = createCesProcessManager({ logger });
+    const pm = createCesProcessManager({
+      logger,
+      discover: discoverTestSocket,
+    });
     const transport = await pm.start();
 
     // The remote (server) closes the connection: genuinely-unexpected death.
@@ -205,7 +198,10 @@ describe("CesProcessManager transport-death logging", () => {
 
   test("does not log WARN on an intentional stop()", async () => {
     const { calls, logger } = makeRecordingLogger();
-    const pm = createCesProcessManager({ logger });
+    const pm = createCesProcessManager({
+      logger,
+      discover: discoverTestSocket,
+    });
     await pm.start();
 
     await pm.stop();

package/src/credential-execution/process-manager.ts

@@ -1,17 +1,17 @@
 /**
  * CES process manager.
  *
- * Creates transport connections to the CES process — either a CLI-launched
- * sibling over a Unix socket (bare-metal/local), or a managed sidecar over
- * its bootstrap socket (containerized). The process manager owns only the
- * transport connection lifecycle; the CES process itself is managed by the
- * CLI (sibling) or the pod infrastructure (managed).
+ * Creates a transport connection to the CES process over the shared bootstrap
+ * socket. Local CLI siblings and managed sidecars bind the same path under
+ * `CES_BOOTSTRAP_SOCKET_DIR`. The process manager owns only the transport
+ * connection lifecycle; the CES process itself is managed by the CLI
+ * (sibling) or the pod infrastructure (managed).
  *
- * Managed env contract:
- * - CES_BOOTSTRAP_SOCKET  — Path to the bootstrap Unix socket (shared emptyDir)
- * - /assistant-data-ro     — Assistant data mounted read-only into the CES sidecar
- * - /ces-data              — CES private data directory (separate PVC)
- * - CES_HEALTH_PORT        — Health check port exposed by the CES sidecar
+ * Env contract:
+ * - CES_BOOTSTRAP_SOCKET_DIR: directory containing `ces.sock`
+ * - /assistant-data-ro: assistant data mounted read-only into CES
+ * - /ces-data: CES private data directory (separate PVC)
+ * - CES_HEALTH_PORT: health check port exposed by the CES sidecar
  */
 
 import { createConnection, type Socket } from "node:net";
@@ -24,7 +24,6 @@ import {
   discoverCesWithRetry,
   type DiscoveryResult,
   type ManagedDiscoverySuccess,
-  type SiblingDiscoverySuccess,
 } from "./executable-discovery.js";
 
 const log = getLogger("ces-process-manager");
@@ -62,6 +61,12 @@ export interface CesProcessManagerConfig {
 
   /** Logger override. Defaults to the module logger; injected in tests. */
   logger?: PmLogger;
+
+  /**
+   * Socket discovery. Defaults to `discoverCesWithRetry`. Tests inject a
+   * stub that returns a known socket path.
+   */
+  discover?: typeof discoverCesWithRetry;
 }
 
 // ---------------------------------------------------------------------------
@@ -70,7 +75,7 @@ export interface CesProcessManagerConfig {
 
 export interface CesProcessManager {
   /**
-   * Connect to the CES process (sibling socket or managed sidecar socket).
+   * Connect to the CES bootstrap socket.
    * Returns a CesTransport ready for use with createCesClient().
    *
    * Throws if CES is unavailable.
@@ -107,6 +112,7 @@ export function createCesProcessManager(
   config: CesProcessManagerConfig,
 ): CesProcessManager {
   const pmLog = config.logger ?? log;
+  const discover = config.discover ?? discoverCesWithRetry;
   let managedSocket: Socket | null = null;
   let discoveryResult: DiscoveryResult | null = null;
   let running = false;
@@ -119,16 +125,15 @@ export function createCesProcessManager(
         throw new Error("CES process manager is already running");
       }
 
-      // Poll for the socket with a short backoff. Both the managed bootstrap
-      // socket and the CLI-launched sibling socket are bound asynchronously,
-      // so a reconnecting assistant can briefly race the re-bind.
-      discoveryResult = await discoverCesWithRetry();
+      // Poll for the socket with a short backoff. CES binds
+      // asynchronously, so a reconnecting assistant can briefly race
+      // the re-bind.
+      discoveryResult = await discover();
 
       if (discoveryResult.mode === "unavailable") {
         throw new CesUnavailableError(discoveryResult.reason);
       }
 
-      // managed sidecar or CLI-launched sibling — both connect to a socket.
       const transport = await connectManagedSocket(discoveryResult);
       currentTransport = transport;
       wireTransportClose(transport);
@@ -200,11 +205,11 @@ export function createCesProcessManager(
   }
 
   // -------------------------------------------------------------------------
-  // Socket connection — managed sidecar or CLI-launched local sibling
+  // Socket connection
   // -------------------------------------------------------------------------
 
   async function connectManagedSocket(
-    discovery: ManagedDiscoverySuccess | SiblingDiscoverySuccess,
+    discovery: ManagedDiscoverySuccess,
   ): Promise<SocketTransport> {
     pmLog.info(
       { socketPath: discovery.socketPath, mode: discovery.mode },

package/src/daemon/__tests__/conversation-surfaces-launch.test.ts

@@ -440,7 +440,12 @@ describe("handleSurfaceAction — launch_conversation dispatch", () => {
     // claimed to eliminate that round-trip; this test enforces it.
     nextKeyStoreResult = { conversationId: "conv-pending-set" };
 
-    const ctx = makeContext();
+    const settleStructuralWait = mock(() => true);
+    const ctx = makeContext({
+      modeSessions: {
+        settleStructuralWait,
+      } as unknown as Conversation["modeSessions"],
+    });
     registerCardSurface(ctx, "surface-pending");
     // Simulate `ui_show` having stamped a pending entry for this surface
     // (which it does for any interactive card, including persistent ones).
@@ -473,6 +478,10 @@ describe("handleSurfaceAction — launch_conversation dispatch", () => {
     // Pending entry was deleted so subsequent sibling clicks on the same
     // persistent card aren't blocked behind a stale "owes-an-answer" flag.
     expect(ctx.pendingSurfaceActions.has("surface-pending")).toBe(false);
+    expect(settleStructuralWait).toHaveBeenCalledWith(
+      { kind: "surface", responseId: "surface-pending" },
+      { status: "completed", endReason: "surface_launch_settled" },
+    );
 
     await processStartedPromise;
     resolveProcess();