@vellumai/assistant 0.11.2-dev.202608060138.f2a1896 → 0.11.2-dev.202608060508.a7ab7f7

package/node_modules/@vellumai/ces-client/src/index.ts

@@ -40,4 +40,5 @@ export {
   type CesRpcClient,
   type CesRpcClientConfig,
   type CesRpcHandshakeOptions,
+  type CesRpcLogger,
 } from "./rpc-client.js";

package/node_modules/@vellumai/ces-client/src/rpc-client.ts

@@ -69,11 +69,23 @@ interface PendingRequest {
 // Client configuration
 // ---------------------------------------------------------------------------
 
+/** Minimal logger interface. Callers can supply pino, console, etc. */
+export interface CesRpcLogger {
+  info(obj: Record<string, unknown>, msg: string): void;
+  info(msg: string): void;
+}
+
 export interface CesRpcClientConfig {
   /** Timeout for individual RPC requests (ms). Default: 30 000 */
   requestTimeoutMs?: number;
   /** Timeout for the initial handshake (ms). Default: 10 000 */
   handshakeTimeoutMs?: number;
+  /**
+   * Optional logger for lifecycle transitions (handshake accepted, close).
+   * These transitions are otherwise invisible, which made a stuck credential
+   * backend hard to diagnose.
+   */
+  logger?: CesRpcLogger;
 }
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
@@ -154,12 +166,15 @@ export function createCesRpcClient(
     config?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
   const handshakeTimeoutMs =
     config?.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+  const logger = config?.logger;
 
   const sessionId = randomUUID();
   let requestCounter = 0;
   let ready = false;
-  let inflightHandshake: Promise<{ accepted: boolean; reason?: string }> | null =
-    null;
+  let inflightHandshake: Promise<{
+    accepted: boolean;
+    reason?: string;
+  }> | null = null;
 
   const pending = new Map<string, PendingRequest>();
 
@@ -380,6 +395,7 @@ export function createCesRpcClient(
 
         if (ack.accepted) {
           ready = true;
+          logger?.info("CES RPC client handshake accepted; ready for calls");
         }
 
         return { accepted: ack.accepted, reason: ack.reason };
@@ -413,6 +429,7 @@ export function createCesRpcClient(
     close(): void {
       rejectAllPending(new CesTransportError("CES client closed"));
       ready = false;
+      logger?.info("CES RPC client closed");
       transport.close();
     },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.2-dev.202608060138.f2a1896",
+  "version": "0.11.2-dev.202608060508.a7ab7f7",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/conversation-error.test.ts

@@ -1613,7 +1613,7 @@ describe("ConnectionResolutionError classification", () => {
     expect(result.userMessage).toContain('profile "custom-fast"');
   });
 
-  it("classifies platform_unauthenticated with a log-in fix", () => {
+  it("classifies platform_unauthenticated with a log-in fix on a non-platform install", () => {
     const err = new ConnectionResolutionError(
       "vellum",
       "platform_unauthenticated",
@@ -1624,6 +1624,22 @@ describe("ConnectionResolutionError classification", () => {
     expect(result.userMessage).toContain("Log in");
   });
 
+  it("classifies platform_unauthenticated as a re-provision hint on a platform-managed assistant", () => {
+    const err = new ConnectionResolutionError(
+      "vellum",
+      "platform_unauthenticated",
+      "unavailable",
+    );
+    process.env.IS_PLATFORM = "true";
+    try {
+      const result = classifyConversationError(err, errCtx);
+      expect(result.userMessage).toContain("re-provisioned");
+      expect(result.userMessage).not.toContain("Log in");
+    } finally {
+      delete process.env.IS_PLATFORM;
+    }
+  });
+
   it("is a structured VellumError (ConfigError) for logging/monitoring", () => {
     const err = new ConnectionResolutionError("x", "not_found", "m");
     expect(err).toBeInstanceOf(VellumError);

package/src/__tests__/secret-routes-platform-proxy.test.ts

@@ -108,7 +108,10 @@ import {
   initializeProviders,
   listProviders,
 } from "../providers/registry.js";
-import { ROUTES } from "../runtime/routes/secret-routes.js";
+import {
+  notifyCesOfAssistantApiKeyUpdate,
+  ROUTES,
+} from "../runtime/routes/secret-routes.js";
 
 const addRoute = ROUTES.find(
   (r) => r.method === "POST" && r.endpoint === "secrets",
@@ -176,6 +179,31 @@ describe("secret routes managed proxy registry sync", () => {
     expect(lastGeminiConstructorOpts).toBeDefined();
   });
 
+  test("the CES key-update notification with no CES client logs a warning", async () => {
+    // When getCesClient() is undefined the push is skipped, but the skip must
+    // be logged, not dropped silently. Exercise the extracted helper directly
+    // with an injected logger.
+    const warns: string[] = [];
+    const fakeLogger = {
+      info: () => {},
+      warn: (a: unknown, b?: unknown) => {
+        warns.push(typeof a === "string" ? a : String(b));
+      },
+    };
+
+    await notifyCesOfAssistantApiKeyUpdate(
+      "ast-managed-key",
+      undefined,
+      fakeLogger as unknown as Parameters<
+        typeof notifyCesOfAssistantApiKeyUpdate
+      >[2],
+    );
+
+    expect(warns.some((m) => m.includes("no CES client is connected"))).toBe(
+      true,
+    );
+  });
+
   test("provider API key writes notify live-conversation refresh listeners", async () => {
     await addApiKey("fireworks", "fw-key");
 

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

@@ -19,6 +19,7 @@ import * as encryptedStore from "../security/encrypted-store.js";
 import {
   _resetBackend,
   deleteSecureKeyAsync,
+  getActiveBackendName,
   getSecureKeyAsync,
   getSecureKeyResultAsync,
   listSecureKeysAsync,
@@ -58,6 +59,9 @@ describe("secure-keys", () => {
     _resetBackend();
     delete process.env.VELLUM_DEV;
     delete process.env.VELLUM_DESKTOP_APP;
+    delete process.env.IS_CONTAINERIZED;
+    delete process.env.CES_CREDENTIAL_URL;
+    delete process.env.CES_LOCAL_SOCKET;
   });
 
   afterAll(() => {
@@ -507,4 +511,91 @@ describe("secure-keys", () => {
       ).toBeUndefined();
     });
   });
+
+  // -----------------------------------------------------------------------
+  // Encrypted-store → CES upgrade without a reconnect callback
+  // -----------------------------------------------------------------------
+  //
+  // Worker/CLI processes inject a CES client whose handshake is still in
+  // flight, so the first credential read falls back to the encrypted store.
+  // These processes never register `_cesReconnect`. Once the handshake
+  // completes and the client reports ready, the next read must upgrade to
+  // CES RPC, since the live client already exists and no reconnect is needed.
+  describe("encrypted-store → CES upgrade without a reconnect callback", () => {
+    test("upgrades to CES RPC once the injected client becomes ready", async () => {
+      const client = makeMockCesClient(false);
+      setCesClient(client);
+
+      // Not ready yet → falls back to the encrypted store (local mode).
+      encryptedStore.setKey("openai", "local-value");
+      expect(await getSecureKeyAsync("openai")).toBe("local-value");
+      expect(getActiveBackendName()).toBe("encrypted-store");
+
+      // Handshake completes; no `_cesReconnect` was ever registered.
+      client.setReady(true);
+
+      await getSecureKeyResultAsync("openai");
+      expect(getActiveBackendName()).toBe("ces-rpc");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Containerized pod with no ready CES backend
+  // -----------------------------------------------------------------------
+  //
+  // On a pod the local encrypted store does not exist. When no CES path is
+  // ready, reads must report the store as unreachable (presence
+  // indeterminate) rather than absent. A provisioned credential is never
+  // reported as "no key". The unreachable result must not be pinned: once a
+  // CES client arrives, the next read routes through it.
+  describe("containerized pod with no ready CES backend", () => {
+    test("reads report unreachable (indeterminate), never absent", async () => {
+      process.env.IS_CONTAINERIZED = "1";
+      delete process.env.CES_CREDENTIAL_URL;
+      delete process.env.CES_LOCAL_SOCKET;
+      _resetBackend();
+
+      const result = await getSecureKeyResultAsync("openai");
+      expect(result.value).toBeUndefined();
+      // unreachable → presence indeterminate, NEVER absent.
+      expect(result.unreachable).toBe(true);
+    });
+
+    test("does not pin the unreachable result: a ready CES client wins the next read", async () => {
+      process.env.IS_CONTAINERIZED = "1";
+      delete process.env.CES_CREDENTIAL_URL;
+      delete process.env.CES_LOCAL_SOCKET;
+      _resetBackend();
+
+      expect((await getSecureKeyResultAsync("openai")).unreachable).toBe(true);
+
+      setCesClient(makeMockCesClient(true));
+
+      const afterAttach = await getSecureKeyResultAsync("openai");
+      expect(afterAttach.unreachable).toBe(false);
+      expect(getActiveBackendName()).toBe("ces-rpc");
+    });
+  });
+
+  // -----------------------------------------------------------------------
+  // Encrypted-store read error vs genuinely-absent (local mode)
+  // -----------------------------------------------------------------------
+  describe("encrypted-store read error vs absent", () => {
+    test("genuinely-missing store → absent (unreachable false)", async () => {
+      const result = await getSecureKeyResultAsync("nope");
+      expect(result.value).toBeUndefined();
+      expect(result.unreachable).toBe(false);
+    });
+
+    test("store exists but key material is missing → unreachable", async () => {
+      encryptedStore.setKey("openai", "sk-1");
+      // Remove the store key so the existing entry can no longer be decrypted.
+      rmSync(join(TEST_DIR, "store.key"));
+      _resetBackend();
+
+      const result = await getSecureKeyResultAsync("openai");
+      expect(result.value).toBeUndefined();
+      expect(result.unreachable).toBe(true);
+    });
+  });
 });

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

@@ -176,6 +176,9 @@ export async function startCes(config: AssistantConfig): Promise<void> {
       },
     });
     if (client) {
+      log.info(
+        "CES client injected into credential resolver at startup; credential reads route through CES RPC",
+      );
       setCesClient(client);
     } else {
       // The handshake lost the startup race, so provider init proceeds on the

package/src/credential-execution/client.ts

@@ -9,6 +9,15 @@
  * delegated to the shared package.
  */
 
+import {
+  type CesRpcClient,
+  type CesRpcClientConfig,
+  type CesTransport,
+  createCesRpcClient,
+} from "@vellumai/ces-client/rpc-client";
+
+import { getLogger } from "../util/logger.js";
+
 export {
   type CesRpcClient as CesClient,
   type CesRpcClientConfig as CesClientConfig,
@@ -17,5 +26,17 @@ export {
   CesHandshakeError,
   type CesTransport,
   CesTransportError,
-  createCesRpcClient as createCesClient,
 } from "@vellumai/ces-client/rpc-client";
+
+const log = getLogger("ces-rpc-client");
+
+/**
+ * Construct a CES RPC client wired to the assistant logger so handshake-ready
+ * and close transitions are visible in the daemon logs.
+ */
+export function createCesClient(
+  transport: CesTransport,
+  config?: CesRpcClientConfig,
+): CesRpcClient {
+  return createCesRpcClient(transport, { logger: log, ...config });
+}

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

@@ -125,3 +125,102 @@ describe("CesProcessManager.onTransportClose", () => {
     await pm.stop();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Transport-death logging: WARN only for genuinely-unexpected death
+// ---------------------------------------------------------------------------
+
+type LogCall = { level: string; msg: string };
+
+function makeRecordingLogger(): {
+  calls: LogCall[];
+  logger: NonNullable<Parameters<typeof createCesProcessManager>[0]["logger"]>;
+} {
+  const calls: LogCall[] = [];
+  const rec =
+    (level: string) =>
+    (...args: unknown[]) => {
+      const msg = typeof args[0] === "string" ? args[0] : args[1];
+      calls.push({ level, msg: typeof msg === "string" ? msg : "" });
+    };
+  const logger = {
+    info: rec("info"),
+    warn: rec("warn"),
+    debug: rec("debug"),
+    error: rec("error"),
+  } as unknown as NonNullable<
+    Parameters<typeof createCesProcessManager>[0]["logger"]
+  >;
+  return { calls, logger };
+}
+
+describe("CesProcessManager transport-death logging", () => {
+  let tempDir: string;
+  let server: Server;
+  let connections: Array<import("node:net").Socket>;
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "ces-pm-log-test-"));
+    mockSocketPath = join(tempDir, "ces.sock");
+    connections = [];
+    server = createServer((socket) => {
+      connections.push(socket);
+      socket.on("error", () => {});
+    });
+    await new Promise<void>((resolve) =>
+      server.listen(mockSocketPath, resolve),
+    );
+  });
+
+  afterEach(async () => {
+    for (const sock of connections) {
+      sock.destroy();
+    }
+    connections = [];
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("logs WARN when the transport dies unexpectedly (remote close)", async () => {
+    const { calls, logger } = makeRecordingLogger();
+    const pm = createCesProcessManager({ logger });
+    const transport = await pm.start();
+
+    // The remote (server) closes the connection: genuinely-unexpected death.
+    for (const sock of connections) {
+      sock.destroy();
+    }
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(transport.isAlive()).toBe(false);
+
+    expect(
+      calls.some(
+        (c) => c.level === "warn" && c.msg.includes("died unexpectedly"),
+      ),
+    ).toBe(true);
+
+    await pm.stop();
+  });
+
+  test("does not log WARN on an intentional stop()", async () => {
+    const { calls, logger } = makeRecordingLogger();
+    const pm = createCesProcessManager({ logger });
+    await pm.start();
+
+    await pm.stop();
+    // Let the socket close event propagate after destroy().
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(
+      calls.some(
+        (c) => c.level === "warn" && c.msg.includes("died unexpectedly"),
+      ),
+    ).toBe(false);
+    expect(
+      calls.some(
+        (c) =>
+          c.level === "debug" && c.msg.includes("CES socket transport closed"),
+      ),
+    ).toBe(true);
+  });
+});

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

@@ -29,6 +29,8 @@ import {
 
 const log = getLogger("ces-process-manager");
 
+type PmLogger = ReturnType<typeof getLogger>;
+
 const SOCKET_CONNECT_TIMEOUT_MS = 5_000;
 
 // ---------------------------------------------------------------------------
@@ -57,6 +59,9 @@ export interface CesProcessManagerConfig {
    * Reserved for future feature-flag checks or config-driven behavior.
    */
   assistantConfig?: AssistantConfig;
+
+  /** Logger override. Defaults to the module logger; injected in tests. */
+  logger?: PmLogger;
 }
 
 // ---------------------------------------------------------------------------
@@ -99,12 +104,13 @@ export interface CesProcessManager {
 // ---------------------------------------------------------------------------
 
 export function createCesProcessManager(
-  _config: CesProcessManagerConfig,
+  config: CesProcessManagerConfig,
 ): CesProcessManager {
+  const pmLog = config.logger ?? log;
   let managedSocket: Socket | null = null;
   let discoveryResult: DiscoveryResult | null = null;
   let running = false;
-  let currentTransport: CesTransport | null = null;
+  let currentTransport: SocketTransport | null = null;
   const transportCloseHandlers: Array<() => void> = [];
 
   return {
@@ -136,24 +142,28 @@ export function createCesProcessManager(
       }
 
       if (managedSocket) {
+        // Mark the close as intentional so the transport-death log is debug,
+        // not a misleading WARN, on routine shutdown/reconnect.
+        currentTransport?.markClosing();
         managedSocket.destroy();
         managedSocket = null;
       }
 
       currentTransport = null;
       running = false;
-      log.info("CES process manager stopped");
+      pmLog.info("CES process manager stopped");
     },
 
     async forceStop(): Promise<void> {
       if (managedSocket) {
+        currentTransport?.markClosing();
         managedSocket.destroy();
         managedSocket = null;
       }
 
       currentTransport = null;
       running = false;
-      log.info("CES process manager force-stopped");
+      pmLog.info("CES process manager force-stopped");
     },
 
     getDiscoveryResult(): DiscoveryResult | null {
@@ -195,8 +205,8 @@ export function createCesProcessManager(
 
   async function connectManagedSocket(
     discovery: ManagedDiscoverySuccess | SiblingDiscoverySuccess,
-  ): Promise<CesTransport> {
-    log.info(
+  ): Promise<SocketTransport> {
+    pmLog.info(
       { socketPath: discovery.socketPath, mode: discovery.mode },
       "Connecting to CES over socket",
     );
@@ -207,9 +217,14 @@ export function createCesProcessManager(
     );
     managedSocket = socket;
 
-    log.info("Connected to CES over socket");
+    pmLog.info("Connected to CES over socket");
 
-    return createSocketTransport(socket);
+    // Assign currentTransport synchronously here (no await between socket
+    // assignment and this line) so stop()/forceStop() can always mark an
+    // intentional close, even if they race the connect.
+    const transport = createSocketTransport(socket, pmLog);
+    currentTransport = transport;
+    return transport;
   }
 }
 
@@ -221,23 +236,43 @@ export function createCesProcessManager(
  * Tracks the transport `alive` state and notifies registered handlers exactly
  * once when the transport dies, so the RPC client can fail-fast any in-flight
  * calls instead of waiting out their timeouts.
+ *
+ * `markClosing()` records that an imminent close was initiated by us (shutdown,
+ * reconnect, handshake rejection). A close so marked logs at debug; an
+ * unmarked death (remote socket close, socket error) logs at WARN.
  */
-function createCloseNotifier(): {
+function createCloseNotifier(log: PmLogger): {
   isAlive: () => boolean;
-  markDead: () => void;
+  markClosing: () => void;
+  markDead: (reason?: string) => void;
   onClose: (handler: () => void) => void;
 } {
   let alive = true;
   let notified = false;
+  let intentional = false;
   const handlers: Array<() => void> = [];
   return {
     isAlive: () => alive,
-    markDead() {
+    markClosing() {
+      intentional = true;
+    },
+    markDead(reason?: string) {
       alive = false;
       if (notified) {
         return;
       }
       notified = true;
+      if (intentional) {
+        log.debug(
+          { reason: reason ?? "intentional" },
+          "CES socket transport closed",
+        );
+      } else {
+        log.warn(
+          { reason: reason ?? "unknown" },
+          "CES socket transport died unexpectedly; credential ops will fail over or reconnect",
+        );
+      }
       for (const handler of handlers) {
         try {
           handler();
@@ -256,10 +291,18 @@ function createCloseNotifier(): {
 // Socket transport (managed mode)
 // ---------------------------------------------------------------------------
 
-function createSocketTransport(socket: Socket): CesTransport {
+/**
+ * A CesTransport plus `markClosing()`, which the process manager calls before
+ * an intentional socket destroy so the ensuing close logs at debug, not WARN.
+ */
+interface SocketTransport extends CesTransport {
+  markClosing(): void;
+}
+
+function createSocketTransport(socket: Socket, log: PmLogger): SocketTransport {
   const messageHandlers: Array<(message: string) => void> = [];
   let buffer = "";
-  const death = createCloseNotifier();
+  const death = createCloseNotifier(log);
 
   const decoder = new StringDecoder("utf8");
 
@@ -278,12 +321,12 @@ function createSocketTransport(socket: Socket): CesTransport {
   });
 
   socket.on("close", () => {
-    death.markDead();
+    death.markDead("socket closed");
   });
 
   socket.on("error", (err) => {
     log.warn({ err }, "CES socket transport error");
-    death.markDead();
+    death.markDead("socket error");
   });
 
   return {
@@ -304,8 +347,11 @@ function createSocketTransport(socket: Socket): CesTransport {
 
     onClose: death.onClose,
 
+    markClosing: death.markClosing,
+
     close(): void {
-      death.markDead();
+      death.markClosing();
+      death.markDead("transport.close() called");
       socket.destroy();
     },
   };

package/src/daemon/conversation-error.ts

@@ -6,6 +6,7 @@ import type {
   ConversationErrorCode,
   ConversationErrorEvent,
 } from "../api/events/conversation-error.js";
+import { getIsPlatform } from "../config/env-registry.js";
 import {
   isImageDimensionsTooLargeError,
   isImageMediaTypeMismatchError,
@@ -361,6 +362,12 @@ function connectionResolutionUserMessage(
       // doesn't.
       return `${connection}${usedBy} has no stored credential. Add an API key or reconnect it in ${fixPath}.`;
     case "platform_unauthenticated":
+      // A platform-managed assistant cannot log in or switch providers, and
+      // this classifier only sees the reason code, so one honest wording covers
+      // both the transient and the re-provision cases.
+      if (getIsPlatform()) {
+        return `${connection}${usedBy} is unavailable. If this persists, the platform credential may need to be re-provisioned on the Vellum platform.`;
+      }
       return `${connection}${usedBy} requires a Vellum platform login. Log in, or pick a different provider in ${fixPath}.`;
     case "model_incompatible":
       return `${error.model ? `Model "${error.model}"` : "The requested model"} isn't available on ${connectionName ? `connection "${connectionName}"` : "the configured connection"}${usedBy}. Pick a different model or connection in ${fixPath}.`;

package/src/providers/__tests__/preflight-resolved-config.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
 let connectionsByName: Record<string, unknown> = {};
 let secureKeys: Record<string, string | undefined> = {};
@@ -74,6 +74,11 @@ beforeEach(() => {
   secureKeys = { "credential/anthropic/api_key": "sk-ant" };
   cesUnreachable = false;
   platformLoggedIn = false;
+  delete process.env.IS_PLATFORM;
+});
+
+afterEach(() => {
+  delete process.env.IS_PLATFORM;
 });
 
 describe("preflightResolvedConfig", () => {
@@ -300,3 +305,55 @@ describe("preflightResolvedConfig", () => {
     expect(await preflightError(resolved())).toBeUndefined();
   });
 });
+
+describe("preflightResolvedConfig platform-managed credential messaging", () => {
+  const platformManaged = () => {
+    connectionsByName = {
+      vellum: {
+        name: "vellum",
+        provider: "vellum",
+        auth: { type: "platform" },
+      },
+    };
+    process.env.IS_PLATFORM = "true";
+  };
+  const managedRoute = () => resolved({ provider_connection: "vellum" });
+
+  test("store unreachable surfaces a retriable message with no login text", async () => {
+    platformManaged();
+    cesUnreachable = true;
+    const err = await preflightError(managedRoute());
+    expect(err?.reason).toBe("platform_unauthenticated");
+    expect(err?.message).toContain("temporarily unavailable");
+    expect(err?.message).not.toContain("log in");
+  });
+
+  test("credential absent asks for platform re-provisioning, not a login", async () => {
+    platformManaged();
+    // Logged out with a reachable store means the credential is genuinely absent.
+    const err = await preflightError(managedRoute());
+    expect(err?.reason).toBe("platform_unauthenticated");
+    expect(err?.message).toContain("must be re-provisioned");
+    expect(err?.message).not.toContain("log in");
+  });
+
+  test("a healthy platform login passes silently", async () => {
+    platformManaged();
+    platformLoggedIn = true;
+    expect(await preflightError(managedRoute())).toBeUndefined();
+  });
+
+  test("non-platform install keeps the log-in-or-switch wording", async () => {
+    connectionsByName = {
+      vellum: {
+        name: "vellum",
+        provider: "vellum",
+        auth: { type: "platform" },
+      },
+    };
+    // IS_PLATFORM left unset covers both local and self-hosted Docker installs.
+    const err = await preflightError(managedRoute());
+    expect(err?.reason).toBe("platform_unauthenticated");
+    expect(err?.message).toContain("log in or pick a different provider");
+  });
+});

package/src/providers/connection-resolution.ts

@@ -27,6 +27,7 @@
  *      a conversation offline.
  */
 
+import { getIsPlatform } from "../config/env-registry.js";
 import {
   resolveCallSiteConfig,
   selectWinningProfile,
@@ -468,7 +469,40 @@ export async function preflightResolvedConfig(
         errorOptions,
       );
     }
-    if ((await platformLoginPresence()) === "unauthenticated") {
+    const presence = await platformLoginPresence();
+    if (presence === "ok") {
+      return;
+    }
+    if (getIsPlatform()) {
+      // A platform-managed assistant cannot present a login screen or switch
+      // providers, so the login-or-switch wording never fits. An unreachable
+      // store is transient and recovers on its own, so it reads as a retry. A
+      // reachable but empty store can only be fixed by re-provisioning the
+      // credential platform-side.
+      if (presence === "indeterminate") {
+        throw new ConnectionResolutionError(
+          connectionName,
+          "platform_unauthenticated",
+          "The assistant's platform credentials are temporarily unavailable; retrying automatically.",
+          errorOptions,
+        );
+      }
+      log.error(
+        {
+          connectionName,
+          model: resolved.model,
+          profileName: attribution.profileName,
+        },
+        "Managed platform credential is missing and must be re-provisioned",
+      );
+      throw new ConnectionResolutionError(
+        connectionName,
+        "platform_unauthenticated",
+        "This assistant's platform credential is missing and must be re-provisioned on the Vellum platform.",
+        errorOptions,
+      );
+    }
+    if (presence === "unauthenticated") {
       throw new ConnectionResolutionError(
         connectionName,
         "platform_unauthenticated",

package/src/runtime/routes/secret-routes.ts

@@ -108,7 +108,7 @@ async function queueApiKeyPropagation(
           getPlatformAssistantId() || undefined,
         );
         log.info(
-          "Pushed queued assistant API key to CES after handshake completed",
+          "Notified CES of the queued assistant API key after handshake completed (ack only; CES reads the durable value from the credential store)",
         );
       } catch (err) {
         log.warn(
@@ -124,6 +124,44 @@ async function queueApiKeyPropagation(
   );
 }
 
+/**
+ * Notify CES that the assistant API key changed. This is advisory: the key is
+ * durably stored in the credential vault and CES reads it from there. When no
+ * CES client is connected the notification is skipped, but the skip is logged
+ * rather than dropped silently. Exported for direct testing.
+ */
+export async function notifyCesOfAssistantApiKeyUpdate(
+  value: string,
+  cesClient: CesClient | undefined,
+  logger: Pick<ReturnType<typeof getLogger>, "info" | "warn"> = log,
+): Promise<void> {
+  const generation = ++apiKeyGeneration;
+  if (!cesClient) {
+    logger.warn(
+      "Assistant API key updated but no CES client is connected; skipping the CES key-update notification (advisory only; CES reads the durable value from the credential store)",
+    );
+    return;
+  }
+  if (cesClient.isReady()) {
+    try {
+      await cesClient.updateAssistantApiKey(
+        value,
+        getPlatformAssistantId() || undefined,
+      );
+      logger.info(
+        "Notified CES of the updated assistant API key (ack only; CES reads the durable value from the credential store)",
+      );
+    } catch (err) {
+      logger.warn(
+        { error: err instanceof Error ? err.message : String(err) },
+        "Failed to notify CES of the assistant API key update (non-fatal)",
+      );
+    }
+    return;
+  }
+  void queueApiKeyPropagation(cesClient, value, generation);
+}
+
 // ---------------------------------------------------------------------------
 // Provider refresh after secret changes
 // ---------------------------------------------------------------------------
@@ -381,28 +419,7 @@ async function handleAddSecret({ body }: RouteHandlerArgs) {
         // pages unseeded until restart. Detached — must not block the response.
         void maybeReseedCapabilitiesAfterManagedCredential(getConfig());
         if (service === "vellum" && field === "assistant_api_key") {
-          const generation = ++apiKeyGeneration;
-          const cesClient = getCesClient();
-          if (cesClient) {
-            if (cesClient.isReady()) {
-              try {
-                await cesClient.updateAssistantApiKey(
-                  value,
-                  getPlatformAssistantId() || undefined,
-                );
-                log.info(
-                  "Pushed assistant API key to CES after managed proxy credential update",
-                );
-              } catch (err) {
-                log.warn(
-                  { error: err instanceof Error ? err.message : String(err) },
-                  "Failed to push assistant API key to CES (non-fatal)",
-                );
-              }
-            } else {
-              void queueApiKeyPropagation(cesClient, value, generation);
-            }
-          }
+          await notifyCesOfAssistantApiKeyUpdate(value, getCesClient());
         }
       }
       if (

package/src/security/credential-backend.ts

@@ -4,7 +4,8 @@
  * is in use.
  */
 
-import { deleteKey, getKey, listKeys, setKey } from "./encrypted-store.js";
+import { getIsContainerized } from "../config/env-registry.js";
+import { deleteKey, listKeys, readKey, setKey } from "./encrypted-store.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -62,14 +63,21 @@ class EncryptedStoreBackend implements CredentialBackend {
   readonly name = "encrypted-store";
 
   isAvailable(): boolean {
-    return true;
+    // The local encrypted store is the legitimate backend only outside
+    // containers. On a pod `keys.enc` does not exist and CES owns credentials,
+    // so reporting available here would pin reads to a store that can never
+    // hold the key. Returning false lets the resolver recover to CES.
+    return !getIsContainerized();
   }
 
   async get(account: string): Promise<CredentialGetResult> {
     try {
-      return { value: getKey(account), unreachable: false };
+      return { value: readKey(account), unreachable: false };
     } catch {
-      return { value: undefined, unreachable: false };
+      // A thrown error means the store exists but could not be read or
+      // decrypted, so it is unavailable, not absent. A genuinely-missing store
+      // or key returns undefined from readKey without throwing.
+      return { value: undefined, unreachable: true };
     }
   }
 
@@ -98,6 +106,41 @@ class EncryptedStoreBackend implements CredentialBackend {
   }
 }
 
+// ---------------------------------------------------------------------------
+// UnavailableBackend
+// ---------------------------------------------------------------------------
+
+/**
+ * A backend whose every operation reports the store as unreachable. Used on
+ * containerized pods when no CES path is ready: resolving to the (nonexistent)
+ * local encrypted store would report provisioned credentials as absent, but
+ * the correct state is "temporarily unreachable" (presence indeterminate),
+ * which callers retry rather than treating as a missing key.
+ */
+class UnavailableBackend implements CredentialBackend {
+  readonly name = "unavailable";
+
+  isAvailable(): boolean {
+    return false;
+  }
+
+  async get(): Promise<CredentialGetResult> {
+    return { value: undefined, unreachable: true };
+  }
+
+  async set(): Promise<boolean> {
+    return false;
+  }
+
+  async delete(): Promise<DeleteResult> {
+    return "error";
+  }
+
+  async list(): Promise<CredentialListResult> {
+    return { accounts: [], unreachable: true };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Factory functions
 // ---------------------------------------------------------------------------
@@ -105,3 +148,7 @@ class EncryptedStoreBackend implements CredentialBackend {
 export function createEncryptedStoreBackend(): EncryptedStoreBackend {
   return new EncryptedStoreBackend();
 }
+
+export function createUnavailableBackend(): UnavailableBackend {
+  return new UnavailableBackend();
+}

package/src/security/encrypted-store.ts

@@ -418,58 +418,80 @@ function decrypt(entry: EncryptedEntry, key: Buffer): string {
   return decrypted.toString("utf-8");
 }
 
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by `readKey()` when the store is UNAVAILABLE: the store file exists
+ * but cannot be read, the key material is missing, or an entry fails to
+ * decrypt. Distinct from a credential being ABSENT (no store file, or the
+ * store reads cleanly but lacks the requested key), which returns `undefined`.
+ *
+ * Mirrors the CES-side `StoreUnavailableError` so managed pods and local mode
+ * report the same absent-vs-unavailable distinction: an unavailable store must
+ * surface as `unreachable` (presence indeterminate), never as "no key".
+ */
+export class StoreUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StoreUnavailableError";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /**
- * Retrieve a secret from the encrypted store.
- * Returns `undefined` if the key doesn't exist or decryption fails.
+ * Retrieve a secret, distinguishing a genuinely-absent credential (returns
+ * `undefined`) from a store that exists but cannot be read or decrypted
+ * (throws {@link StoreUnavailableError}).
  */
-export function getKey(account: string): string | undefined {
-  try {
-    const store = readStore();
-    if (!store) {
-      return undefined;
-    }
+export function readKey(account: string): string | undefined {
+  // `readStore()` returns null for a missing store (or a corrupt store it has
+  // just reset) and throws on transient I/O errors (EACCES, EMFILE, EIO). A
+  // missing store is genuinely absent; a transient read error is unavailable
+  // and propagates.
+  const store = readStore();
+  if (!store) {
+    return undefined;
+  }
 
-    // If v1, trigger migration
-    if (store.version === 1) {
-      const migrated = migrateV1ToV2(store);
-      if (migrated) {
-        writeStore(migrated);
-        const entry = migrated.entries[account];
-        if (!entry) {
-          return undefined;
-        }
-        const key = getKeyForStore(migrated);
-        if (!key) {
-          return undefined;
-        }
-        return decrypt(entry, key);
-      }
-      // Migration failed -- try reading with legacy key
-      const entry = store.entries[account];
-      if (!entry) {
-        return undefined;
-      }
-      const key = getKeyForStore(store);
-      if (!key) {
-        return undefined;
-      }
-      return decrypt(entry, key);
+  let effectiveStore: StoreFile = store;
+  if (store.version === 1) {
+    const migrated = migrateV1ToV2(store);
+    if (migrated) {
+      writeStore(migrated);
+      effectiveStore = migrated;
     }
+    // Migration failed: fall through and read with the legacy PBKDF2 key.
+  }
 
-    const entry = store.entries[account];
-    if (!entry) {
-      return undefined;
-    }
+  const entry = effectiveStore.entries[account];
+  if (!entry) {
+    return undefined;
+  }
 
-    const key = getKeyForStore(store);
-    if (!key) {
-      return undefined;
-    }
-    return decrypt(entry, key);
+  const key = getKeyForStore(effectiveStore);
+  if (!key) {
+    throw new StoreUnavailableError(
+      "credential store entry present but key material is unavailable",
+    );
+  }
+  // A decrypt failure means corrupt data or wrong key material, so the credential
+  // exists but its value cannot be produced. Let it propagate as unavailable
+  // rather than swallowing it into a false "not found".
+  return decrypt(entry, key);
+}
+
+/**
+ * Retrieve a secret from the encrypted store.
+ * Returns `undefined` if the key doesn't exist or decryption fails.
+ */
+export function getKey(account: string): string | undefined {
+  try {
+    return readKey(account);
   } catch (err) {
     log.debug({ err, account }, "Failed to read from encrypted store");
     return undefined;

package/src/security/secure-keys.ts

@@ -50,7 +50,10 @@ import type {
   CredentialListResult,
   DeleteResult,
 } from "./credential-backend.js";
-import { createEncryptedStoreBackend } from "./credential-backend.js";
+import {
+  createEncryptedStoreBackend,
+  createUnavailableBackend,
+} from "./credential-backend.js";
 import { credentialKey } from "./credential-key.js";
 
 export type {
@@ -148,6 +151,10 @@ export function setCesClient(client: CesClient | undefined): void {
   _resolvedBackend = undefined;
   _resolvePromise = undefined;
   _cesHttpUnreachable = false;
+  log.info(
+    { hasClient: !!client },
+    "CES client updated; resetting resolved credential backend cache",
+  );
   _cesClientListener?.(client);
 }
 
@@ -238,6 +245,21 @@ async function resolveBackendAsync(
         // backends.
         return _resolvedBackend;
       }
+    } else if (
+      _resolvedBackend.name === "encrypted-store" &&
+      _cesClient?.isReady()
+    ) {
+      // A CES client became ready after we fell back to the encrypted store
+      // (e.g. a worker/CLI whose handshake completed post-fallback, or a
+      // client injected before its handshake finished). No reconnect callback
+      // is needed, since the live client already exists. Drop the fallback and
+      // re-resolve so the CES RPC path wins.
+      log.info(
+        "CES client is ready; upgrading credential backend from encrypted store to CES RPC",
+      );
+      _resolvedBackend = undefined;
+      _resolvePromise = undefined;
+      // Fall through to re-resolve.
     } else if (
       _cesReconnect &&
       (_resolvedBackend.name === "encrypted-store" ||
@@ -264,7 +286,16 @@ async function resolveBackendAsync(
     }
   }
   if (!_resolvePromise) {
-    _resolvePromise = doResolveBackend();
+    _resolvePromise = doResolveBackend().then((backend) => {
+      // The containerized guard returns an unreachable backend without caching
+      // it (`_resolvedBackend` stays unset). Clear the memoized promise so the
+      // next credential op re-attempts CES rather than pinning the unreachable
+      // result to a pod whose CES may since have come up.
+      if (backend.name === "unavailable") {
+        _resolvePromise = undefined;
+      }
+      return backend;
+    });
   }
   return _resolvePromise;
 }
@@ -456,10 +487,11 @@ async function doResolveBackend(): Promise<CredentialBackend> {
     const cesRpc = new CesRpcCredentialBackend(_cesClient);
     if (cesRpc.isAvailable()) {
       _resolvedBackend = cesRpc;
+      log.info("Resolved credential backend: ces-rpc");
       return cesRpc;
     }
     log.warn(
-      "CES RPC client is set but not ready — falling back to local credential store",
+      "CES RPC client is set but not ready; trying the next credential backend",
     );
   }
 
@@ -468,11 +500,12 @@ async function doResolveBackend(): Promise<CredentialBackend> {
     const ces = createCesCredentialBackend();
     if (ces.isAvailable()) {
       _resolvedBackend = ces;
+      log.info("Resolved credential backend: ces-http");
       return ces;
     }
     log.warn(
-      "CES_CREDENTIAL_URL is set but CES backend is not available — " +
-        "falling back to local credential store",
+      "CES_CREDENTIAL_URL is set but CES backend is not available; " +
+        "trying the next credential backend",
     );
   }
 
@@ -488,14 +521,29 @@ async function doResolveBackend(): Promise<CredentialBackend> {
       const cesRpc = new CesRpcCredentialBackend(lazyClient);
       if (cesRpc.isAvailable()) {
         _resolvedBackend = cesRpc;
+        log.info("Resolved credential backend: ces-rpc (lazy connect)");
         return cesRpc;
       }
     }
-    // Lazy connect failed — fall through to encrypted file store.
+    // Lazy connect failed; fall through.
+  }
+
+  // 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
+  //    next credential op re-attempts CES rather than pinning the dead answer.
+  if (getIsContainerized()) {
+    log.error(
+      "No CES credential backend is ready on a containerized pod; reporting credentials as unreachable (indeterminate). The local encrypted store is not used in managed mode.",
+    );
+    return createUnavailableBackend();
   }
 
-  // 3. Encrypted file store — fallback when CES is unavailable
+  // 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)");
   return _resolvedBackend;
 }