@vellumai/assistant 0.12.2-dev.202609171820.9ecfa87 → 0.12.2-dev.202609171913.b5e95d3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609171820.9ecfa87",
+  "version": "0.12.2-dev.202609171913.b5e95d3",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/credential-execution-client.test.ts

@@ -95,7 +95,7 @@ function withBootstrapDir(dir: string): () => void {
   };
 }
 
-describe("managed CES discovery", () => {
+describe("CES discovery", () => {
   test("returns unavailable when bootstrap socket does not exist", () => {
     const bootstrapDir = mkdtempSync(join(tmpdir(), "ces-missing-"));
     const restore = withBootstrapDir(bootstrapDir);

package/src/__tests__/secure-keys.test.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { createServer, type Server } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -11,6 +12,8 @@ import {
   test,
 } from "bun:test";
 
+import { resolveIpcEndpoint } from "@vellumai/ipc-server-utils";
+
 // ---------------------------------------------------------------------------
 // Mock logger (no-op — compatible with other test files' identical mock)
 // ---------------------------------------------------------------------------
@@ -602,4 +605,43 @@ describe("secure-keys", () => {
       expect(result.unreachable).toBe(true);
     });
   });
+
+  // -----------------------------------------------------------------------
+  // Session ownership: boot claims reconnect before identity reads
+  // -----------------------------------------------------------------------
+  describe("CES session owner skips a second open", () => {
+    test("a registered reconnect owner does not handshake a live CES socket", async () => {
+      const dir = mkdtempSync(join(tmpdir(), "ces-owner-"));
+      const socketPath = resolveIpcEndpoint("ces", { workspaceDir: dir }).path;
+      const savedDir = process.env.CES_BOOTSTRAP_SOCKET_DIR;
+      process.env.CES_BOOTSTRAP_SOCKET_DIR = dir;
+
+      const connections: Array<import("node:net").Socket> = [];
+      const server: Server = createServer((socket) => {
+        connections.push(socket);
+        socket.on("error", () => {});
+      });
+      await new Promise<void>((resolve) => server.listen(socketPath, resolve));
+
+      try {
+        setCesReconnect(async () => undefined);
+        const start = Date.now();
+        await getSecureKeyAsync("openai");
+        expect(Date.now() - start).toBeLessThan(1_000);
+        expect(getActiveBackendName()).toBe("encrypted-store");
+        expect(connections.length).toBe(0);
+      } finally {
+        for (const sock of connections) {
+          sock.destroy();
+        }
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+        if (savedDir !== undefined) {
+          process.env.CES_BOOTSTRAP_SOCKET_DIR = savedDir;
+        } else {
+          delete process.env.CES_BOOTSTRAP_SOCKET_DIR;
+        }
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+  });
 });

package/src/credential-execution/ces-connect.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Tests for the shared CES RPC session helper used by assistant boot and
+ * child-process credential resolution.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { openCesRpcSession, reconnectCesRpcSession } from "./ces-connect.js";
+import { createCesProcessManager } from "./process-manager.js";
+
+describe("openCesRpcSession", () => {
+  test("returns undefined when discovery fails without polling", async () => {
+    const start = Date.now();
+    const pm = createCesProcessManager({
+      discover: async () => ({
+        mode: "unavailable",
+        reason: "missing test socket",
+      }),
+    });
+
+    const session = await openCesRpcSession({ processManager: pm });
+
+    expect(session).toBeUndefined();
+    expect(pm.isRunning()).toBe(false);
+    expect(Date.now() - start).toBeLessThan(1_000);
+  });
+
+  test("returns undefined when the abort signal is already fired", async () => {
+    const abort = new AbortController();
+    abort.abort();
+    const pm = createCesProcessManager({
+      discover: async () => {
+        throw new Error("discover should not run after abort");
+      },
+    });
+
+    const session = await openCesRpcSession({
+      processManager: pm,
+      signal: abort.signal,
+    });
+
+    expect(session).toBeUndefined();
+    expect(pm.isRunning()).toBe(false);
+  });
+
+  test("creates a process manager when none is provided", async () => {
+    const session = await openCesRpcSession({
+      discover: async () => ({
+        mode: "unavailable",
+        reason: "missing test socket",
+      }),
+    });
+
+    expect(session).toBeUndefined();
+  });
+
+  test("reconnectCesRpcSession stops the manager and returns undefined when discovery fails", async () => {
+    const pm = createCesProcessManager({
+      discover: async () => ({
+        mode: "unavailable",
+        reason: "missing test socket",
+      }),
+    });
+
+    const client = await reconnectCesRpcSession(pm);
+
+    expect(client).toBeUndefined();
+    expect(pm.isRunning()).toBe(false);
+  });
+});

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

@@ -0,0 +1,115 @@
+/**
+ * Open a CES RPC client over the shared bootstrap socket.
+ *
+ * Assistant boot and child-process credential reads use this helper. Both
+ * are CES API clients: discover `ces.sock`, connect, handshake, reconnect.
+ *
+ * They stay two entry points because boot must load handshake identity
+ * without talking to CES, then hand that identity to CES. Children open a
+ * session only when this process has not already claimed one (no live
+ * client and no reconnect owner).
+ */
+
+import type { AssistantConfig } from "../config/schema.js";
+import { getLogger } from "../util/logger.js";
+import {
+  type CesClient,
+  type CesClientHandshakeOptions,
+  createCesClient,
+} from "./client.js";
+import {
+  type CesProcessManager,
+  type CesProcessManagerConfig,
+  CesUnavailableError,
+  createCesProcessManager,
+} from "./process-manager.js";
+
+const log = getLogger("ces-connect");
+
+export interface CesRpcSession {
+  client: CesClient;
+  processManager: CesProcessManager;
+}
+
+export interface OpenCesRpcSessionOptions {
+  /**
+   * Reuse an existing process manager (reconnect after `stop()`). When
+   * omitted, a new manager is created.
+   */
+  processManager?: CesProcessManager;
+  handshake?: CesClientHandshakeOptions;
+  signal?: AbortSignal;
+  assistantConfig?: AssistantConfig;
+  discover?: CesProcessManagerConfig["discover"];
+}
+
+/**
+ * Discover the CES socket, connect, and complete the RPC handshake.
+ *
+ * Returns undefined when CES is missing, the handshake is rejected, the
+ * abort signal fires, or the transport fails. The process manager is
+ * stopped on those paths so a later reconnect can call `start()` again.
+ */
+export async function openCesRpcSession(
+  options: OpenCesRpcSessionOptions = {},
+): Promise<CesRpcSession | undefined> {
+  const pm =
+    options.processManager ??
+    createCesProcessManager({
+      assistantConfig: options.assistantConfig,
+      discover: options.discover,
+    });
+
+  const fail = async (): Promise<undefined> => {
+    await pm.stop().catch(() => {});
+    return undefined;
+  };
+
+  if (options.signal?.aborted) {
+    return fail();
+  }
+
+  try {
+    const transport = await pm.start();
+    if (options.signal?.aborted) {
+      return fail();
+    }
+
+    const client = createCesClient(transport);
+    const { accepted, reason } = await client.handshake(options.handshake);
+    if (options.signal?.aborted) {
+      client.close();
+      return fail();
+    }
+    if (!accepted) {
+      log.warn({ reason }, "CES handshake rejected");
+      client.close();
+      return fail();
+    }
+
+    return { client, processManager: pm };
+  } catch (err) {
+    if (err instanceof CesUnavailableError) {
+      log.info({ reason: err.message }, "CES is not available");
+    } else {
+      log.warn(
+        { error: err instanceof Error ? err.message : String(err) },
+        "Failed to open CES RPC session",
+      );
+    }
+    return fail();
+  }
+}
+
+/**
+ * Stop the current transport and open a new session on the same process
+ * manager. Used by assistant boot and child-process reconnect callbacks.
+ */
+export async function reconnectCesRpcSession(
+  processManager: CesProcessManager,
+  handshake?: CesClientHandshakeOptions,
+): Promise<CesClient | undefined> {
+  await processManager.stop();
+  const session = await openCesRpcSession({ processManager, handshake });
+  return session?.client;
+}

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.
  *
- * CES serves a multi-connection Unix socket, so this is called at the
- * process level and child processes may open their own connections.
+ * 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/daemon/lifecycle.ts

@@ -673,11 +673,11 @@ export async function runDaemon(): Promise<void> {
   // blocked.
   startConsentRefresh();
 
-  // Bring up the assistant's CES connection (process + handshake + reconnect
-  // wiring). Blocks up to a 20s timeout so credential reads route through CES
-  // before provider init; non-fatal, falls back to the direct credential store
-  // on failure. CES serves a multi-connection bootstrap socket, so this
-  // happens at the process level and child processes can connect independently.
+  // Open the assistant's CES RPC client (handshake + reconnect wiring).
+  // Blocks up to a 20s timeout so credential reads route through CES before
+  // provider init; non-fatal, falls back to the direct credential store on
+  // failure. CES serves a multi-connection bootstrap socket, so child
+  // processes can open the same `openCesRpcSession` path independently.
   await startCes(config);
 
   // Bring up the plugin layer: install the runtime bridge, register the

package/src/security/secure-keys.ts

@@ -1,22 +1,18 @@
 /**
- * Unified secure key storage — single-backend routing through CredentialBackend
+ * Unified secure key storage: single-backend routing through CredentialBackend
  * adapters.
  *
  * Backend selection (`resolveBackendAsync`) is the single async decision point:
- *   1. CES RPC (primary) - injected via `setCesClient()`: delegates credential
- *      operations to the CES process over Unix socket RPC. This is the default
- *      path for the assistant (which calls startCes() at boot) and for
- *      child processes that lazily connect to the CES socket (see below).
- *   2. Lazy CES RPC connect - non-assistant processes (workers, CLI
- *      subprocesses) that never call startCes(). On first credential
- *      resolution they discover the CES bootstrap socket
- *      (`CES_BOOTSTRAP_SOCKET_DIR`) and cache
- *      the connection.
- *   3. CES HTTP - containerized failover when IPC is unavailable
+ *   1. CES RPC (primary) - connect to the CES bootstrap socket and talk RPC.
+ *      `openCesRpcSession` is the one client constructor. The assistant
+ *      claims session ownership at boot (`startCes`) and hands CES the
+ *      assistant API key. Child processes open a session on first credential
+ *      read only when this process has no client and no reconnect owner.
+ *   2. CES HTTP - containerized failover when IPC is unavailable
  *      (`IS_CONTAINERIZED` + `CES_CREDENTIAL_URL`). Used if the assistant's
  *      bootstrap RPC transport is down, or if a process with HTTP env could
  *      not open the socket.
- *   4. Encrypted file store (fallback) - used when CES is unavailable locally.
+ *   3. Encrypted file store (fallback) - used when CES is unavailable locally.
  *
  * All operations (reads, writes, lists, deletes) go to exactly one backend.
  * There are no cross-store fallbacks or merges. The only transport failover is
@@ -35,14 +31,11 @@ import type {
 
 import { getIsContainerized } from "../config/env-registry.js";
 import {
-  type CesClient,
-  createCesClient,
-} from "../credential-execution/client.js";
+  openCesRpcSession,
+  reconnectCesRpcSession,
+} from "../credential-execution/ces-connect.js";
+import { type CesClient } from "../credential-execution/client.js";
 import { discoverCes } from "../credential-execution/executable-discovery.js";
-import {
-  CesUnavailableError,
-  createCesProcessManager,
-} from "../credential-execution/process-manager.js";
 import { getAnyProviderEnvVar } from "../providers/provider-env-vars.js";
 import { getLogger } from "../util/logger.js";
 import { getProtectedDir } from "../util/platform.js";
@@ -85,11 +78,11 @@ let _resolvedBackend: CredentialBackend | undefined;
 let _resolvePromise: Promise<CredentialBackend> | undefined;
 
 /**
- * In-flight lazy CES connection promise for non-daemon processes.
+ * In-flight CES RPC session promise for processes that did not call startCes().
  *
  * Workers and CLI subprocesses never call startCes(). When they hit
  * resolveBackendAsync() with no _cesClient and no _cesReconnect
- * (daemon-only), this promise memoizes a direct CES connection attempt so
+ * (assistant-boot only), this promise memoizes `openCesRpcSession` so
  * concurrent credential reads in the same process share a single
  * connect+handshake rather than racing.
  */
@@ -206,10 +199,9 @@ function getEncryptedStoreBackend(): CredentialBackend {
  * Resolve the primary credential backend for this process (async).
  *
  * Priority:
- *   1. CES RPC client: primary path in every environment.
- *   2. Lazy CES RPC connect: child processes discover the CES socket.
- *   3. Containerized + CES_CREDENTIAL_URL: CES HTTP, only if IPC is down.
- *   4. Encrypted file store: local fallback when CES is unavailable.
+ *   1. CES RPC: live client, or open one via `openCesRpcSession`.
+ *   2. Containerized + CES_CREDENTIAL_URL: CES HTTP, only if IPC is down.
+ *   3. Encrypted file store: local fallback when CES is unavailable.
  *
  * Once resolved, the backend is cached. If it becomes unavailable (e.g. the
  * CES transport dies), we attempt to reconnect via `_cesReconnect` rather
@@ -415,19 +407,19 @@ export async function attemptCesReconnection(
 }
 
 /**
- * Lazily connect to a CES sibling socket from a non-daemon process.
+ * Open a CES RPC session from a process that did not call startCes().
  *
  * Workers and CLI subprocesses never call startCes(). This function
- * establishes a direct CES connection on first credential resolution,
+ * opens the same `openCesRpcSession` path the assistant uses at boot,
  * memoizing the in-flight promise so concurrent callers share a single
  * connect+handshake. Discovery uses the shared CES bootstrap socket; a
  * missing socket fails immediately so callers can fall through without
  * polling.
  *
  * On success, the client is injected via setCesClient() so subsequent
- * resolveBackendAsync() calls take the fast CES RPC path (step 1). A
- * reconnect callback is also registered so the lazy connection can heal
- * if the transport drops mid-process.
+ * resolveBackendAsync() calls take the live CES RPC path. A reconnect
+ * callback is also registered so the session can heal if the transport
+ * drops mid-process.
  *
  * Returns undefined on any failure (socket not found, handshake rejected,
  * timeout) so the caller falls through to the encrypted file store.
@@ -438,70 +430,30 @@ async function tryLazyCesConnect(): Promise<CesClient | undefined> {
   }
 
   _lazyConnectPromise = (async () => {
-    try {
-      const discovery = discoverCes();
-      if (discovery.mode === "unavailable") {
-        log.info(
-          { reason: discovery.reason },
-          "CES socket not reachable for lazy connect, falling back to encrypted file store",
-        );
-        return undefined;
-      }
-      const pm = createCesProcessManager({});
-      const transport = await pm.start();
-      const client = createCesClient(transport);
-      const { accepted, reason } = await client.handshake();
-      if (!accepted) {
-        log.warn(
-          { reason },
-          "Lazy CES connection handshake rejected — falling back to encrypted file store",
-        );
-        client.close();
-        await pm.stop().catch(() => {});
-        return undefined;
-      }
+    const discovery = discoverCes();
+    if (discovery.mode === "unavailable") {
       log.info(
-        "Lazy CES connection established — credential operations routed through CES RPC",
+        { reason: discovery.reason },
+        "CES socket not reachable for lazy connect, falling back to encrypted file store",
       );
-      setCesClient(client);
-      // Register a reconnect callback so the lazy connection self-heals
-      // if the transport drops, mirroring the daemon's proactive reconnect.
-      setCesReconnect(async () => {
-        try {
-          await pm.stop();
-          const newTransport = await pm.start();
-          const newClient = createCesClient(newTransport);
-          const { accepted: ok } = await newClient.handshake();
-          if (ok) {
-            log.info("Lazy CES reconnection successful");
-            return newClient;
-          }
-          newClient.close();
-          await pm.stop().catch(() => {});
-          return undefined;
-        } catch (err) {
-          log.warn(
-            { error: err instanceof Error ? err.message : String(err) },
-            "Lazy CES reconnection failed",
-          );
-          return undefined;
-        }
-      });
-      return client;
-    } catch (err) {
-      if (err instanceof CesUnavailableError) {
-        log.info(
-          { reason: err.message },
-          "CES socket not reachable for lazy connect — falling back to encrypted file store",
-        );
-      } else {
-        log.warn(
-          { error: err instanceof Error ? err.message : String(err) },
-          "Lazy CES connection failed — falling back to encrypted file store",
-        );
-      }
       return undefined;
     }
+    const session = await openCesRpcSession();
+    if (!session) {
+      return undefined;
+    }
+    log.info(
+      "CES RPC session established; credential operations route through CES RPC",
+    );
+    setCesClient(session.client);
+    setCesReconnect(async () => {
+      const client = await reconnectCesRpcSession(session.processManager);
+      if (client) {
+        log.info("CES RPC reconnection successful");
+      }
+      return client;
+    });
+    return session.client;
   })();
 
   try {
@@ -512,7 +464,10 @@ async function tryLazyCesConnect(): Promise<CesClient | undefined> {
 }
 
 async function doResolveBackend(): Promise<CredentialBackend> {
-  // 1. CES RPC. Primary credential backend in every environment.
+  // 1. CES RPC. Primary credential backend in every environment. Boot
+  //    claims reconnect ownership before it reads handshake identity, so
+  //    that read cannot open a second session. Children open here only
+  //    when this process has no client and no reconnect owner.
   if (_cesClient) {
     const cesRpc = new CesRpcCredentialBackend(_cesClient);
     if (cesRpc.isAvailable()) {
@@ -525,24 +480,19 @@ async function doResolveBackend(): Promise<CredentialBackend> {
     );
   }
 
-  // 2. Lazy CES RPC connect. Child processes never call startCes(). When
-  //    the assistant's setCesReconnect() is NOT registered, attempt a
-  //    direct connection to the CES bootstrap socket. On success, inject
-  //    the client via setCesClient()
-  //    and re-resolve through the CES RPC path. On failure, fall through.
   if (!_cesClient && !_cesReconnect) {
-    const lazyClient = await tryLazyCesConnect();
-    if (lazyClient) {
-      const cesRpc = new CesRpcCredentialBackend(lazyClient);
+    const client = await tryLazyCesConnect();
+    if (client) {
+      const cesRpc = new CesRpcCredentialBackend(client);
       if (cesRpc.isAvailable()) {
         _resolvedBackend = cesRpc;
-        log.info("Resolved credential backend: ces-rpc (lazy connect)");
+        log.info("Resolved credential backend: ces-rpc");
         return cesRpc;
       }
     }
   }
 
-  // 3. CES HTTP. Managed failover when IPC is unavailable.
+  // 2. CES HTTP. Managed failover when IPC is unavailable.
   if (getIsContainerized() && process.env.CES_CREDENTIAL_URL) {
     const ces = createCesCredentialBackend();
     if (ces.isAvailable()) {
@@ -556,7 +506,7 @@ async function doResolveBackend(): Promise<CredentialBackend> {
     );
   }
 
-  // 4. On a containerized pod the local encrypted store does not exist and CES
+  // 3. On a containerized pod the local encrypted store does not exist and CES
   //    owns credentials. Never resolve to the encrypted store here; it would
   //    report a provisioned credential as absent. Return an unreachable backend
   //    (presence indeterminate, which callers retry) WITHOUT caching it, so the
@@ -568,7 +518,7 @@ async function doResolveBackend(): Promise<CredentialBackend> {
     return createUnavailableBackend();
   }
 
-  // 5. Encrypted file store: the legitimate backend for local / self-hosted
+  // 4. Encrypted file store: the legitimate backend for local / self-hosted
   //    mode when CES is unavailable.
   _resolvedBackend = getEncryptedStoreBackend();
   log.info("Resolved credential backend: encrypted-store (local mode)");