@vellumai/assistant 0.5.4 → 0.5.5

package/src/security/secure-keys.ts

@@ -3,6 +3,7 @@
  * adapters.
  *
  * Backend selection (`resolveBackend`) is the single decision point:
+ *   - Containerized (IS_CONTAINERIZED + CES_CREDENTIAL_URL set): CES HTTP client.
  *   - Production (VELLUM_DEV unset or "0"): keychain backend when available.
  *   - Dev mode (VELLUM_DEV=1): encrypted file store always.
  *
@@ -16,7 +17,10 @@ import type {
   SecureKeyDeleteResult,
 } from "@vellumai/credential-storage";
 
+import providerEnvVarsRegistry from "../../../meta/provider-env-vars.json" with { type: "json" };
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
+import { createCesCredentialBackend } from "./ces-credential-client.js";
 import type { CredentialBackend, DeleteResult } from "./credential-backend.js";
 import {
   createEncryptedStoreBackend,
@@ -50,18 +54,39 @@ function getEncryptedStoreBackend(): CredentialBackend {
 
 /**
  * Resolve the primary credential backend for this process.
- * Production (VELLUM_DEV unset or "0") uses keychain when available.
- * Dev mode (VELLUM_DEV=1) always uses the encrypted file store.
+ *
+ * Priority:
+ *   1. Containerized + CES_CREDENTIAL_URL → CES HTTP client (skip keychain
+ *      and encrypted store entirely — the sidecar owns credential storage).
+ *   2. Production (VELLUM_DEV unset or "0") → keychain when available.
+ *   3. Dev mode (VELLUM_DEV=1) → encrypted file store always.
  *
  * Once resolved, the backend does not change during the process lifetime.
  * Call `_resetBackend()` in tests to clear the cached resolution.
  */
 function resolveBackend(): CredentialBackend {
   if (!_resolvedBackend) {
-    if (process.env.VELLUM_DEV !== "1" && getKeychainBackend().isAvailable()) {
-      _resolvedBackend = getKeychainBackend();
-    } else {
-      _resolvedBackend = getEncryptedStoreBackend();
+    if (getIsContainerized() && process.env.CES_CREDENTIAL_URL) {
+      const ces = createCesCredentialBackend();
+      if (ces.isAvailable()) {
+        _resolvedBackend = ces;
+      } else {
+        log.warn(
+          "CES_CREDENTIAL_URL is set but CES backend is not available — " +
+            "falling back to local credential store",
+        );
+      }
+    }
+
+    if (!_resolvedBackend) {
+      if (
+        process.env.VELLUM_DEV !== "1" &&
+        getKeychainBackend().isAvailable()
+      ) {
+        _resolvedBackend = getKeychainBackend();
+      } else {
+        _resolvedBackend = getEncryptedStoreBackend();
+      }
     }
   }
   return _resolvedBackend;
@@ -70,6 +95,8 @@ function resolveBackend(): CredentialBackend {
 /**
  * List all account names across both backends (async).
  *
+ * In CES mode, only the CES backend is queried — there are no local stores.
+ *
  * When the primary backend is the keychain, this merges keys from the keychain
  * and the encrypted store (for legacy keys that haven't been migrated). The
  * result is deduplicated. When the primary backend is already the encrypted
@@ -79,6 +106,9 @@ export async function listSecureKeysAsync(): Promise<string[]> {
   const backend = resolveBackend();
   const primaryKeys = await backend.list();
 
+  // CES mode — the sidecar is the single source of truth, no local merge.
+  if (backend.name === "ces-http") return primaryKeys;
+
   // If primary backend is NOT the encrypted store, also check
   // the encrypted store for legacy keys that haven't been migrated.
   if (backend !== getEncryptedStoreBackend()) {
@@ -96,8 +126,10 @@ export async function listSecureKeysAsync(): Promise<string[]> {
 
 /**
  * Retrieve a secret from secure storage. Reads from the primary backend
- * first. If the primary backend is the keychain, falls back to the encrypted
- * store for legacy keys that haven't been migrated.
+ * first. In CES mode, the sidecar is the single source of truth — no
+ * local fallback. In local mode, if the primary backend is the keychain,
+ * falls back to the encrypted store for legacy keys that haven't been
+ * migrated.
  */
 export async function getSecureKeyAsync(
   account: string,
@@ -106,6 +138,9 @@ export async function getSecureKeyAsync(
   const result = await backend.get(account);
   if (result != null) return result;
 
+  // CES mode — no local fallback.
+  if (backend.name === "ces-http") return undefined;
+
   // Legacy fallback: if primary backend is NOT the encrypted store,
   // check the encrypted store for keys that haven't been migrated.
   if (backend !== getEncryptedStoreBackend()) {
@@ -135,13 +170,25 @@ export async function setSecureKeyAsync(
 }
 
 /**
- * Delete a secret from secure storage. Always attempts deletion on both
- * the keychain backend (if available) and the encrypted store backend,
- * regardless of routing mode. This cleans up legacy data from both stores.
+ * Delete a secret from secure storage.
+ *
+ * In containerized mode with CES, deletion is routed exclusively through the
+ * CES backend — there are no local stores to clean up.
+ *
+ * In local mode, always attempts deletion on both the keychain backend (if
+ * available) and the encrypted store backend, regardless of routing mode.
+ * This cleans up legacy data from both stores.
  */
 export async function deleteSecureKeyAsync(
   account: string,
 ): Promise<DeleteResult> {
+  const backend = resolveBackend();
+
+  // In CES mode, the sidecar is the only store — no local cleanup needed.
+  if (backend.name === "ces-http") {
+    return backend.delete(account);
+  }
+
   const keychain = getKeychainBackend();
   const enc = getEncryptedStoreBackend();
 
@@ -164,18 +211,14 @@ export async function deleteSecureKeyAsync(
 // ---------------------------------------------------------------------------
 
 /**
- * Env var names keyed by provider. The convention is `<PROVIDER>_API_KEY`.
- * Ollama is intentionally omitted — it doesn't require an API key.
+ * Env var names keyed by provider. Loaded from the shared registry at
+ * `meta/provider-env-vars.json` — the single source of truth also consumed
+ * by the CLI and the macOS client.
+ * Ollama is intentionally omitted from the registry — it doesn't require
+ * an API key.
  */
-const PROVIDER_ENV_VARS: Record<string, string> = {
-  anthropic: "ANTHROPIC_API_KEY",
-  openai: "OPENAI_API_KEY",
-  gemini: "GEMINI_API_KEY",
-  fireworks: "FIREWORKS_API_KEY",
-  openrouter: "OPENROUTER_API_KEY",
-  brave: "BRAVE_API_KEY",
-  perplexity: "PERPLEXITY_API_KEY",
-};
+const PROVIDER_ENV_VARS: Record<string, string> =
+  providerEnvVarsRegistry.providers;
 
 /**
  * Retrieve a provider API key, checking secure storage first and falling

package/src/signals/bash.ts

@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
 import { getSignalsDir, getWorkspaceDir } from "../util/platform.js";
 
@@ -65,6 +66,8 @@ function writeResult(requestId: string, result: BashSignalResult): void {
  * when a matching signal file is created or modified.
  */
 export function handleBashSignal(filename: string): void {
+  if (getIsContainerized()) return;
+
   if (!isDebugMode()) {
     log.warn(
       { filename },

package/src/signals/cancel.ts

@@ -13,6 +13,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
 import { getSignalsDir } from "../util/platform.js";
 
@@ -39,6 +40,8 @@ export function registerCancelCallback(cb: CancelCallback): void {
  * Called by ConfigWatcher when the signal file is written or modified.
  */
 export function handleCancelSignal(): void {
+  if (getIsContainerized()) return;
+
   try {
     const content = readFileSync(join(getSignalsDir(), "cancel"), "utf-8");
     const parsed = JSON.parse(content) as { conversationId?: string };

package/src/signals/confirm.ts

@@ -10,6 +10,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import type { UserDecision } from "../permissions/types.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getLogger } from "../util/logger.js";
@@ -37,6 +38,8 @@ function isUserDecision(value: string): value is UserDecision {
  * Called by ConfigWatcher when the signal file is written or modified.
  */
 export function handleConfirmationSignal(): void {
+  if (getIsContainerized()) return;
+
   try {
     const content = readFileSync(join(getSignalsDir(), "confirm"), "utf-8");
     const parsed = JSON.parse(content) as {

package/src/signals/conversation-undo.ts

@@ -16,6 +16,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
 import { getSignalsDir } from "../util/platform.js";
 
@@ -46,6 +47,8 @@ export function registerConversationUndoCallback(cb: UndoCallback): void {
  * file is written.
  */
 export async function handleConversationUndoSignal(): Promise<void> {
+  if (getIsContainerized()) return;
+
   const resultPath = join(getSignalsDir(), "conversation-undo.result");
 
   const writeResult = (

package/src/signals/event-stream.ts

@@ -24,6 +24,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import type { AssistantEvent } from "../runtime/assistant-event.js";
 import { getSignalsDir } from "../util/platform.js";
 
@@ -86,6 +87,8 @@ export function appendEventToStream(
   conversationId: string,
   event: AssistantEvent,
 ): void {
+  if (getIsContainerized()) return;
+
   const dirs = getSubscriberDirs(conversationId);
   if (dirs.length === 0) return;
 
@@ -130,6 +133,10 @@ export function watchEventStream(
   conversationId: string,
   callback: (event: AssistantEvent) => void,
 ): EventStreamWatcher {
+  if (getIsContainerized()) {
+    return { dispose() {} };
+  }
+
   const parentDir = eventsDir();
   mkdirSync(parentDir, { recursive: true });
   const subDir = join(parentDir, `${conversationId}.${process.pid}`);

package/src/signals/shotgun.ts

@@ -15,6 +15,7 @@ import crypto from "node:crypto";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import {
   fireWatchCompletionNotifier,
   fireWatchStartNotifier,
@@ -54,6 +55,8 @@ function writeResult(requestId: string, result: ShotgunResult): void {
  * when a matching signal file is created or modified.
  */
 export function handleShotgunSignal(filename: string): void {
+  if (getIsContainerized()) return;
+
   const signalPath = join(getSignalsDir(), filename);
   let raw: string;
   try {

package/src/signals/trust-rule.ts

@@ -12,6 +12,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { addRule } from "../permissions/trust-store.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getTool } from "../tools/registry.js";
@@ -27,6 +28,8 @@ const VALID_TRUST_DECISIONS: ReadonlySet<string> = new Set(["allow", "deny"]);
  * Called by ConfigWatcher when the signal file is written or modified.
  */
 export function handleTrustRuleSignal(): void {
+  if (getIsContainerized()) return;
+
   const resultPath = join(getSignalsDir(), "trust-rule.result");
 
   const writeError = (requestId: string | undefined, error: string): void => {

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -41,14 +41,12 @@ mock.module("../memory/turn-events-store.js", () => ({
   queryUnreportedTurnEvents: mockQueryUnreportedTurnEvents,
 }));
 
-const mockResolveManagedProxyContext = mock(async () => ({
-  enabled: false,
-  platformBaseUrl: "",
-  assistantApiKey: "",
-}));
+let mockPlatformClient: Record<string, unknown> | null = null;
 
-mock.module("../providers/managed-proxy/context.js", () => ({
-  resolveManagedProxyContext: mockResolveManagedProxyContext,
+mock.module("../platform/client.js", () => ({
+  VellumPlatformClient: {
+    create: async () => mockPlatformClient,
+  },
 }));
 
 const mockGetTelemetryPlatformUrl = mock(() => "https://platform.vellum.ai");
@@ -142,7 +140,7 @@ beforeEach(() => {
   mockQueryUnreportedUsageEvents.mockReset();
   mockQueryUnreportedTurnEvents.mockReset();
   mockQueryUnreportedTurnEvents.mockReturnValue([]);
-  mockResolveManagedProxyContext.mockReset();
+  mockPlatformClient = null;
   mockGetTelemetryPlatformUrl.mockReset();
   mockGetTelemetryAppToken.mockReset();
   mockGetDeviceId.mockReset();
@@ -156,11 +154,6 @@ beforeEach(() => {
 
   // Defaults
   mockGetMemoryCheckpoint.mockReturnValue(null);
-  mockResolveManagedProxyContext.mockResolvedValue({
-    enabled: false,
-    platformBaseUrl: "",
-    assistantApiKey: "",
-  });
   mockGetTelemetryPlatformUrl.mockReturnValue("https://platform.vellum.ai");
   mockGetTelemetryAppToken.mockReturnValue("default-test-token");
 
@@ -179,37 +172,31 @@ afterEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("UsageTelemetryReporter", () => {
-  test("authenticated flush uses Api-Key header and proxy URL", async () => {
-    mockResolveManagedProxyContext.mockResolvedValue({
-      enabled: true,
-      platformBaseUrl: "https://test.vellum.ai",
-      assistantApiKey: "test-key",
+  test("authenticated flush uses client.fetch with platform path", async () => {
+    const clientFetchMock = mock(async (_path: string, _init?: RequestInit) => {
+      return new Response('{"accepted":2}', { status: 200 });
     });
+    mockPlatformClient = {
+      baseUrl: "https://test.vellum.ai",
+      assistantApiKey: "test-key",
+      platformAssistantId: "asst-123",
+      fetch: clientFetchMock,
+    };
     const events = [makeUsageEvent(), makeUsageEvent()];
     mockQueryUnreportedUsageEvents.mockReturnValue(events);
-    mockFetch.mockImplementation(() =>
-      Promise.resolve(
-        new Response(`{"accepted":${events.length}}`, { status: 200 }),
-      ),
-    );
 
     const reporter = new UsageTelemetryReporter();
     await reporter.flush();
 
-    expect(mockFetch).toHaveBeenCalledTimes(1);
-    const [url, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
-    expect(url).toBe("https://test.vellum.ai/v1/telemetry/ingest/");
-    expect((opts.headers as Record<string, string>)["Authorization"]).toBe(
-      "Api-Key test-key",
-    );
+    expect(clientFetchMock).toHaveBeenCalledTimes(1);
+    const [path] = clientFetchMock.mock.calls[0] as [string, RequestInit];
+    expect(path).toBe("/v1/telemetry/ingest/");
+    // globalThis.fetch should NOT have been called directly
+    expect(mockFetch).not.toHaveBeenCalled();
   });
 
   test("anonymous flush uses X-Telemetry-Token and default URL", async () => {
-    mockResolveManagedProxyContext.mockResolvedValue({
-      enabled: false,
-      platformBaseUrl: "",
-      assistantApiKey: "",
-    });
+    mockPlatformClient = null;
     mockGetTelemetryPlatformUrl.mockReturnValue("https://platform.test.ai");
     mockGetTelemetryAppToken.mockReturnValue("anon-token");
 
@@ -375,9 +362,9 @@ describe("UsageTelemetryReporter", () => {
       (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
     );
 
-    // Top-level: installation_id, app_version, and events array (no turn_events key)
+    // Top-level: installation_id, assistant_version, and events array (no turn_events key)
     expect(body.installation_id).toBe("test-device-id");
-    expect(body.app_version).toBe("1.2.3-test");
+    expect(body.assistant_version).toBe("1.2.3-test");
     expect(Array.isArray(body.events)).toBe(true);
     expect(body.events.length).toBe(1);
     expect(body.turn_events).toBeUndefined();

package/src/telemetry/usage-telemetry-reporter.ts

@@ -22,7 +22,7 @@ import {
 import { queryUnreportedLifecycleEvents } from "../memory/lifecycle-events-store.js";
 import { queryUnreportedUsageEvents } from "../memory/llm-usage-store.js";
 import { queryUnreportedTurnEvents } from "../memory/turn-events-store.js";
-import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { VellumPlatformClient } from "../platform/client.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import { getExternalAssistantId } from "../runtime/auth/external-assistant-id.js";
 import { getDeviceId } from "../util/device-id.js";
@@ -139,22 +139,11 @@ export class UsageTelemetryReporter {
         return;
 
       // Resolve auth context — skip flush when neither auth mode is viable
-      const proxyCtx = await resolveManagedProxyContext();
-      if (!proxyCtx.enabled && !getTelemetryAppToken()) {
+      const client = await VellumPlatformClient.create();
+      if (!client && !getTelemetryAppToken()) {
         return;
       }
 
-      let url: string;
-      let authHeaders: Record<string, string>;
-
-      if (proxyCtx.enabled) {
-        url = `${proxyCtx.platformBaseUrl}${TELEMETRY_PATH}`;
-        authHeaders = { Authorization: `Api-Key ${proxyCtx.assistantApiKey}` };
-      } else {
-        url = `${getTelemetryPlatformUrl()}${TELEMETRY_PATH}`;
-        authHeaders = { "X-Telemetry-Token": getTelemetryAppToken() };
-      }
-
       // Build payload
       const typedEvents: TelemetryEvent[] = [
         ...events.map(
@@ -195,26 +184,39 @@ export class UsageTelemetryReporter {
       const payload = {
         device_id: getDeviceId(),
         assistant_id: assistantId,
-        app_version: APP_VERSION,
+        assistant_version: APP_VERSION,
         ...(organizationId ? { organization_id: organizationId } : {}),
         ...(userId ? { user_id: userId } : {}),
         events: typedEvents,
       };
 
       // Send
-      const resp = await fetch(url, {
+      const fetchInit: RequestInit = {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          ...authHeaders,
         },
         body: JSON.stringify(payload),
-      });
+      };
+
+      let resp: Response;
+      if (client) {
+        resp = await client.fetch(TELEMETRY_PATH, fetchInit);
+      } else {
+        const url = `${getTelemetryPlatformUrl()}${TELEMETRY_PATH}`;
+        resp = await fetch(url, {
+          ...fetchInit,
+          headers: {
+            "Content-Type": "application/json",
+            "X-Telemetry-Token": getTelemetryAppToken(),
+          },
+        });
+      }
 
       if (!resp.ok) {
         await resp.text(); // consume body to release connection
         log.warn(
-          { status: resp.status, url },
+          { status: resp.status },
           "Usage telemetry POST failed — will retry next cycle",
         );
         return;

package/src/util/device-id.ts

@@ -6,8 +6,10 @@
  * extensible for future per-device metadata.
  *
  * Path resolution:
- *   - Containerized (IS_CONTAINERIZED=true): uses BASE_DATA_DIR, which maps to a
- *     persistent volume. Each container is effectively its own "device."
+ *   - Containerized (IS_CONTAINERIZED=true): uses /home/assistant (the assistant
+ *     user's persistent home dir) so device.json lives on the assistant's own
+ *     filesystem rather than the shared data volume. Falls back to BASE_DATA_DIR
+ *     for migration from the old location.
  *   - Local (single or multi-instance): uses homedir() so all instances on the
  *     same machine share a single device ID, even when BASE_DATA_DIR is set to
  *     an instance-scoped directory.
@@ -31,18 +33,34 @@ let cached: string | undefined;
 /**
  * Resolve the base directory for device.json.
  *
- * In containerized environments, BASE_DATA_DIR points to a persistent volume
- * and homedir() is ephemeral, so we must use BASE_DATA_DIR.
+ * In containerized environments, device.json is stored under /home/assistant
+ * (the assistant user's persistent home dir) rather than on the shared data
+ * volume. Device ID is assistant-specific state that doesn't need to be shared.
  * In local environments (including multi-instance), homedir() is stable and
  * shared across instances, giving a true per-machine device ID.
  */
 export function getDeviceIdBaseDir(): string {
   if (getIsContainerized()) {
-    return getBaseDataDir() || homedir();
+    return "/home/assistant";
   }
   return homedir();
 }
 
+/**
+ * Resolve the legacy base directory for device.json migration.
+ *
+ * Returns the old containerized path (BASE_DATA_DIR) so we can fall back to
+ * reading device.json from the shared volume if it hasn't been migrated yet.
+ * Returns undefined when not containerized or when no legacy path exists.
+ */
+function getLegacyDeviceIdBaseDir(): string | undefined {
+  if (!getIsContainerized()) {
+    return undefined;
+  }
+  const baseDataDir = getBaseDataDir();
+  return baseDataDir || undefined;
+}
+
 /**
  * Get the stable device ID for this machine.
  *
@@ -78,10 +96,55 @@ export function getDeviceId(): string {
       }
     }
   } catch (err) {
-    log.warn({ err }, "Failed to read device.json — generating new device ID");
+    log.warn({ err }, "Failed to read device.json — checking legacy path");
+  }
+
+  // Migration fallback: check the legacy location (shared volume) if the new
+  // location doesn't have a valid device.json yet.
+  const legacyBase = getLegacyDeviceIdBaseDir();
+  if (legacyBase) {
+    const legacyPath = join(legacyBase, ".vellum", "device.json");
+    try {
+      if (existsSync(legacyPath)) {
+        const raw = JSON.parse(readFileSync(legacyPath, "utf-8"));
+        if (
+          raw &&
+          typeof raw === "object" &&
+          typeof raw.deviceId === "string" &&
+          raw.deviceId.length > 0
+        ) {
+          cached = raw.deviceId as string;
+          log.info(
+            { deviceId: cached },
+            "Resolved device ID from legacy device.json — will persist to new location",
+          );
+          // Persist to the new location so future reads don't need the fallback
+          try {
+            mkdirSync(vellumDir, { recursive: true });
+            writeFileSync(
+              filePath,
+              JSON.stringify({ deviceId: cached }, null, 2) + "\n",
+              { mode: 0o644 },
+            );
+            log.info("Migrated device.json to new location");
+          } catch (writeErr) {
+            log.warn(
+              { err: writeErr },
+              "Failed to migrate device.json to new location",
+            );
+          }
+          return cached;
+        }
+      }
+    } catch (err) {
+      log.warn(
+        { err },
+        "Failed to read legacy device.json — generating new device ID",
+      );
+    }
   }
 
-  // Either the file doesn't exist, or deviceId was missing/empty.
+  // Either the file doesn't exist at either location, or deviceId was missing/empty.
   // Generate a new UUID and persist it.
   try {
     mkdirSync(vellumDir, { recursive: true });

package/src/util/logger.ts

@@ -76,20 +76,44 @@ let rootLogger: pino.Logger | null = null;
 let activeLogDate: string | null = null;
 let activeLogFileConfig: LogFileConfig | null = null;
 
+function resolveLogDir(config: LogFileConfig): string | undefined {
+  if (!config.dir) return undefined;
+
+  if (!existsSync(config.dir)) {
+    try {
+      mkdirSync(config.dir, { recursive: true });
+    } catch (err) {
+      if (getIsContainerized()) {
+        // Config has a host-specific path that can't be created inside the
+        // container (e.g. /Users/…). Fall back to the default log directory.
+        const fallback = join(getLogPath(), "..");
+        console.warn(
+          `[logger] Configured logFile.dir "${config.dir}" cannot be created ` +
+            `in container (${(err as Error).message}). Falling back to "${fallback}".`,
+        );
+        if (!existsSync(fallback)) {
+          mkdirSync(fallback, { recursive: true });
+        }
+        return fallback;
+      }
+      throw err;
+    }
+  }
+
+  return config.dir;
+}
+
 function buildRotatingLogger(config: LogFileConfig): pino.Logger {
-  if (!config.dir) {
+  const dir = resolveLogDir(config);
+  if (!dir) {
     return pino(
       { name: "assistant", serializers: logSerializers },
       pinoPretty(prettyOpts({ destination: 1 })),
     );
   }
 
-  if (!existsSync(config.dir)) {
-    mkdirSync(config.dir, { recursive: true });
-  }
-
   const today = formatDate(new Date());
-  const filePath = logFilePathForDate(config.dir, new Date());
+  const filePath = logFilePathForDate(dir, new Date());
   const fileDest = pino.destination({
     dest: filePath,
     sync: false,
@@ -107,7 +131,7 @@ function buildRotatingLogger(config: LogFileConfig): pino.Logger {
   );
 
   activeLogDate = today;
-  activeLogFileConfig = config;
+  activeLogFileConfig = { ...config, dir };
 
   // When stdout is not a TTY (e.g. desktop app redirects to a hatch log file),
   // write to the rotating file only — the hatch log already captured early
@@ -144,8 +168,10 @@ function ensureCurrentDate(): void {
 export function initLogger(config: LogFileConfig): void {
   rootLogger = buildRotatingLogger(config);
 
-  if (config.dir && config.retentionDays > 0) {
-    const removed = pruneOldLogFiles(config.dir, config.retentionDays);
+  // Use the resolved dir (may differ from config.dir when containerized)
+  const resolvedDir = activeLogFileConfig?.dir;
+  if (resolvedDir && config.retentionDays > 0) {
+    const removed = pruneOldLogFiles(resolvedDir, config.retentionDays);
     if (removed > 0) {
       rootLogger.info(
         { removed, retentionDays: config.retentionDays },