@vellumai/cli 0.8.10-dev.202606102242.5285563 → 0.8.10-dev.202606102342.319a8d3

package/AGENTS.md

@@ -63,6 +63,8 @@ The CLI must **never** read from or write to the `.vellum/` directory (e.g. `~/.
 
 For example, the signing key used for JWT auth between the daemon and gateway is persisted in the lockfile (`resources.signingKey`) so that client actor tokens survive daemon/gateway restarts. On first start (or when the key is missing), the CLI generates a new key via `generateLocalSigningKey()` in `lib/local.ts`, saves it to the lockfile entry, and passes it to both `startLocalDaemon` and `startGateway` as the `ACTOR_TOKEN_SIGNING_KEY` env var. The CLI does **not** read or write to the `.vellum/` directory for signing keys — it uses the lockfile instead.
 
+**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Swift clients, the Electron main process, the host-mode assistant, and the CLI (see `clients/shared/App/Auth/DeviceIdStore.swift` and `apps/macos/src/main/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
+
 ## Process liveness
 
 Use `resolveProcessState()` from `lib/process.ts` when checking whether a daemon or gateway should be (re)started. It combines PID existence with an HTTP `/healthz` probe, a readiness grace period, and a [`isVellumProcess()`](https://man7.org/linux/man-pages/man1/ps.1.html) guard against PID reuse — see the function's JSDoc for the full flow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.10-dev.202606102242.5285563",
+  "version": "0.8.10-dev.202606102342.319a8d3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/device-id.test.ts

@@ -0,0 +1,167 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+// Bun's os.homedir() ignores runtime HOME changes, so mock it (same pattern
+// as multi-local.test.ts) to keep production-path tests off the real ~/.vellum.
+let fakeHome: string | undefined;
+const realOs = await import("node:os");
+const osMock = () => ({
+  ...realOs,
+  homedir: () => fakeHome ?? realOs.homedir(),
+});
+mock.module("node:os", osMock);
+mock.module("os", osMock);
+
+import {
+  getOrCreateHostDeviceId,
+  resetHostDeviceIdCache,
+} from "../lib/device-id.js";
+import { snapshotEnv } from "./helpers/env.js";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+const restoreEnv = snapshotEnv([
+  "XDG_CONFIG_HOME",
+  "VELLUM_ENVIRONMENT",
+  "VELLUM_DEVICE_ID",
+]);
+
+describe("getOrCreateHostDeviceId", () => {
+  let tempHome: string;
+  let deviceFile: string;
+
+  beforeEach(() => {
+    delete process.env.VELLUM_DEVICE_ID;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-device-id-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    // Non-prod so the resolver targets $XDG_CONFIG_HOME/vellum-dev/
+    // instead of the real ~/.config/vellum/.
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    deviceFile = join(tempHome, "vellum-dev", "device.json");
+    resetHostDeviceIdCache();
+  });
+
+  afterEach(() => {
+    restoreEnv();
+    rmSync(tempHome, { recursive: true, force: true });
+    resetHostDeviceIdCache();
+  });
+
+  test("creates device.json with a UUID when missing", () => {
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    expect(existsSync(deviceFile)).toBe(true);
+    const parsed = JSON.parse(readFileSync(deviceFile, "utf-8"));
+    expect(parsed.deviceId).toBe(id);
+    expect(readFileSync(deviceFile, "utf-8").endsWith("\n")).toBe(true);
+  });
+
+  test("returns the existing deviceId without rewriting the file", () => {
+    mkdirSync(join(tempHome, "vellum-dev"), { recursive: true });
+    writeFileSync(deviceFile, JSON.stringify({ deviceId: "existing-id" }));
+    const before = statSync(deviceFile).mtimeMs;
+
+    expect(getOrCreateHostDeviceId()).toBe("existing-id");
+    expect(statSync(deviceFile).mtimeMs).toBe(before);
+    expect(readFileSync(deviceFile, "utf-8")).toBe(
+      JSON.stringify({ deviceId: "existing-id" }),
+    );
+  });
+
+  test("caches the resolved id until reset", () => {
+    const first = getOrCreateHostDeviceId();
+    rmSync(deviceFile);
+
+    expect(getOrCreateHostDeviceId()).toBe(first);
+
+    resetHostDeviceIdCache();
+    const second = getOrCreateHostDeviceId();
+    expect(second).toMatch(UUID_RE);
+    expect(second).not.toBe(first);
+  });
+
+  test("preserves unrelated fields when adding deviceId", () => {
+    mkdirSync(join(tempHome, "vellum-dev"), { recursive: true });
+    writeFileSync(deviceFile, JSON.stringify({ other: "kept", deviceId: "" }));
+
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    const parsed = JSON.parse(readFileSync(deviceFile, "utf-8"));
+    expect(parsed.other).toBe("kept");
+    expect(parsed.deviceId).toBe(id);
+  });
+
+  test("VELLUM_DEVICE_ID env var wins and skips file access", () => {
+    process.env.VELLUM_DEVICE_ID = "env-device-id";
+
+    expect(getOrCreateHostDeviceId()).toBe("env-device-id");
+    expect(existsSync(deviceFile)).toBe(false);
+  });
+
+  test("malformed JSON regenerates without throwing", () => {
+    mkdirSync(join(tempHome, "vellum-dev"), { recursive: true });
+    writeFileSync(deviceFile, "{not json");
+
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    const parsed = JSON.parse(readFileSync(deviceFile, "utf-8"));
+    expect(parsed).toEqual({ deviceId: id });
+  });
+});
+
+describe("getOrCreateHostDeviceId (production)", () => {
+  let tempHome: string;
+  let deviceFile: string;
+
+  beforeEach(() => {
+    delete process.env.VELLUM_DEVICE_ID;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-device-id-prod-test-"));
+    fakeHome = tempHome;
+    process.env.XDG_CONFIG_HOME = join(tempHome, ".config");
+    process.env.VELLUM_ENVIRONMENT = "production";
+    deviceFile = join(tempHome, ".vellum", "device.json");
+    resetHostDeviceIdCache();
+  });
+
+  afterEach(() => {
+    fakeHome = undefined;
+    restoreEnv();
+    rmSync(tempHome, { recursive: true, force: true });
+    resetHostDeviceIdCache();
+  });
+
+  test("creates device.json in the shared ~/.vellum dir", () => {
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    expect(existsSync(deviceFile)).toBe(true);
+    expect(JSON.parse(readFileSync(deviceFile, "utf-8")).deviceId).toBe(id);
+  });
+
+  test("reuses an existing ~/.vellum/device.json", () => {
+    mkdirSync(join(tempHome, ".vellum"), { recursive: true });
+    writeFileSync(
+      deviceFile,
+      JSON.stringify({ deviceId: "shared-prod-id" }),
+    );
+
+    expect(getOrCreateHostDeviceId()).toBe("shared-prod-id");
+    expect(readFileSync(deviceFile, "utf-8")).toBe(
+      JSON.stringify({ deviceId: "shared-prod-id" }),
+    );
+  });
+});

package/src/__tests__/helpers/env.ts

@@ -0,0 +1,19 @@
+/**
+ * Snapshot the given env vars now; returns a restore function suitable for
+ * `afterEach` that resets each var to its captured value (or deletes it).
+ */
+export function snapshotEnv(keys: readonly string[]): () => void {
+  const saved: Record<string, string | undefined> = {};
+  for (const key of keys) {
+    saved[key] = process.env[key];
+  }
+  return () => {
+    for (const key of keys) {
+      if (saved[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = saved[key];
+      }
+    }
+  };
+}

package/src/__tests__/statefulset.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildServiceRunArgs,
+  getBuilderManagedEnvKeys,
+  type BuildServiceRunArgsOpts,
+  type DockerStatefulSetSpec,
+  type ServiceName,
+} from "../lib/statefulset.js";
+import { PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
+
+const SECRET_KEYS = [
+  "CES_SERVICE_TOKEN",
+  "ACTOR_TOKEN_SIGNING_KEY",
+  "GUARDIAN_BOOTSTRAP_SECRET",
+];
+
+describe("getBuilderManagedEnvKeys", () => {
+  test("gateway always-set keys cover spec static + secret entries and PATH", () => {
+    const { always } = getBuilderManagedEnvKeys("gateway");
+
+    const expected = [
+      "VELLUM_WORKSPACE_DIR",
+      "GATEWAY_SECURITY_DIR",
+      "ASSISTANT_HOST",
+      "CES_CREDENTIAL_URL",
+      "GATEWAY_IPC_SOCKET_DIR",
+      "ASSISTANT_IPC_SOCKET_DIR",
+      "GATEWAY_PORT",
+      "RUNTIME_HTTP_PORT",
+      ...SECRET_KEYS,
+      "PATH",
+    ];
+    for (const key of expected) {
+      expect(always.has(key)).toBe(true);
+    }
+
+    expect(always.has("VELLUM_DISABLE_PLATFORM")).toBe(false);
+    expect(always.has("VELLUM_DEVICE_ID")).toBe(false);
+  });
+
+  test("assistant always-set keys include secrets and builder-computed extras", () => {
+    const { always } = getBuilderManagedEnvKeys("assistant");
+
+    const expected = [
+      ...SECRET_KEYS,
+      "VELLUM_ASSISTANT_NAME",
+      "GATEWAY_INTERNAL_URL",
+      "RUNTIME_HTTP_HOST",
+      "PATH",
+    ];
+    for (const key of expected) {
+      expect(always.has(key)).toBe(true);
+    }
+  });
+
+  test("gateway hostForwarded equals the three spec host entries", () => {
+    const { hostForwarded } = getBuilderManagedEnvKeys("gateway");
+    const sorted = [...hostForwarded].sort((a, b) => a.name.localeCompare(b.name));
+    expect(sorted).toEqual([
+      { name: "VELAY_BASE_URL", hostVar: "VELAY_BASE_URL" },
+      { name: "VELLUM_ENVIRONMENT", hostVar: "VELLUM_ENVIRONMENT" },
+      { name: "VELLUM_PLATFORM_URL", hostVar: "VELLUM_PLATFORM_URL" },
+    ]);
+  });
+
+  test("assistant hostForwarded includes provider keys and platform URL", () => {
+    const { hostForwarded } = getBuilderManagedEnvKeys("assistant");
+    expect(hostForwarded).toContainEqual({
+      name: "ANTHROPIC_API_KEY",
+      hostVar: "ANTHROPIC_API_KEY",
+    });
+    for (const envVar of Object.values(PROVIDER_ENV_VAR_NAMES)) {
+      expect(hostForwarded).toContainEqual({ name: envVar, hostVar: envVar });
+    }
+    expect(hostForwarded).toContainEqual({
+      name: "VELLUM_PLATFORM_URL",
+      hostVar: "VELLUM_PLATFORM_URL",
+    });
+  });
+
+  test("hostForwarded keeps container name when hostVar differs", () => {
+    const spec: DockerStatefulSetSpec = {
+      startOrder: ["gateway"],
+      readiness: { endpoint: "/readyz", timeoutMs: 1, intervalMs: 1 },
+      volumeClaimTemplates: [],
+      containers: [
+        {
+          name: "gateway-sidecar",
+          internalName: "gateway",
+          network: "container",
+          env: [{ kind: "host", name: "CONTAINER_NAME", hostVar: "HOST_NAME" }],
+          volumeMounts: [],
+        },
+      ],
+    };
+
+    const { hostForwarded } = getBuilderManagedEnvKeys("gateway", spec);
+    expect(hostForwarded).toEqual([
+      { name: "CONTAINER_NAME", hostVar: "HOST_NAME" },
+    ]);
+  });
+
+  test("throws on unknown service name", () => {
+    expect(() => getBuilderManagedEnvKeys("bogus" as ServiceName)).toThrow(
+      'docker-statefulset: unknown service "bogus"',
+    );
+  });
+});
+
+describe("buildServiceRunArgs extra env routing", () => {
+  const opts: BuildServiceRunArgsOpts = {
+    gatewayPort: 18080,
+    imageTags: {
+      assistant: "assistant:test",
+      gateway: "gateway:test",
+      "credential-executor": "ces:test",
+    },
+    instanceName: "test-instance",
+    res: {
+      assistantContainer: "test-assistant",
+      cesContainer: "test-ces",
+      gatewayContainer: "test-gateway",
+      network: "test-net",
+    },
+    extraGatewayEnv: { VELLUM_DISABLE_PLATFORM: "1" },
+    extraAssistantEnv: { FOO: "bar" },
+  };
+
+  const runArgs = buildServiceRunArgs(opts);
+
+  test("extraGatewayEnv lands only in gateway args", () => {
+    const gatewayArgs = runArgs.gateway();
+    expect(gatewayArgs).toContain("VELLUM_DISABLE_PLATFORM=1");
+    expect(gatewayArgs).not.toContain("FOO=bar");
+  });
+
+  test("extraAssistantEnv lands only in assistant args", () => {
+    const assistantArgs = runArgs.assistant();
+    expect(assistantArgs).toContain("FOO=bar");
+    expect(assistantArgs).not.toContain("VELLUM_DISABLE_PLATFORM=1");
+  });
+
+  test("credential-executor args get neither extra env map", () => {
+    const cesArgs = runArgs["credential-executor"]();
+    expect(cesArgs).not.toContain("VELLUM_DISABLE_PLATFORM=1");
+    expect(cesArgs).not.toContain("FOO=bar");
+  });
+});

package/src/__tests__/upgrade-replay-env.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { resetHostDeviceIdCache } from "../lib/device-id.js";
+import type { DockerStatefulSetSpec } from "../lib/statefulset.js";
+import { buildReplayEnv, buildReplayState } from "../lib/upgrade-lifecycle.js";
+import { snapshotEnv } from "./helpers/env.js";
+
+const restoreEnv = snapshotEnv([
+  "VELLUM_PLATFORM_URL",
+  "ANTHROPIC_API_KEY",
+  "VELLUM_DEVICE_ID",
+]);
+
+afterEach(() => {
+  restoreEnv();
+  resetHostDeviceIdCache();
+});
+
+describe("buildReplayEnv", () => {
+  test("gateway: drops secrets, statics, and PATH; keeps flag overrides", () => {
+    const captured = {
+      GUARDIAN_BOOTSTRAP_SECRET: "s1",
+      CES_SERVICE_TOKEN: "s2",
+      ACTOR_TOKEN_SIGNING_KEY: "s3",
+      PATH: "/usr/bin",
+      GATEWAY_PORT: "18080",
+      VELLUM_DISABLE_PLATFORM: "1",
+      VELLUM_DEVICE_ID: "abc",
+    };
+
+    expect(buildReplayEnv(captured, "gateway")).toEqual({
+      VELLUM_DISABLE_PLATFORM: "1",
+      VELLUM_DEVICE_ID: "abc",
+    });
+  });
+
+  test("gateway: captured VELLUM_PLATFORM_URL dropped when set on host", () => {
+    process.env.VELLUM_PLATFORM_URL = "https://host.example.com";
+    const replay = buildReplayEnv(
+      { VELLUM_PLATFORM_URL: "https://stale.example.com" },
+      "gateway",
+    );
+    expect(replay).toEqual({});
+  });
+
+  test("gateway: captured VELLUM_PLATFORM_URL kept when unset on host", () => {
+    delete process.env.VELLUM_PLATFORM_URL;
+    const replay = buildReplayEnv(
+      { VELLUM_PLATFORM_URL: "https://stale.example.com" },
+      "gateway",
+    );
+    expect(replay).toEqual({
+      VELLUM_PLATFORM_URL: "https://stale.example.com",
+    });
+  });
+
+  test("assistant: drops builder-computed extras, secrets, and PATH; keeps custom flags", () => {
+    delete process.env.ANTHROPIC_API_KEY;
+    const captured = {
+      VELLUM_ASSISTANT_NAME: "my-assistant",
+      GATEWAY_INTERNAL_URL: "http://localhost:8080",
+      GUARDIAN_BOOTSTRAP_SECRET: "s1",
+      CES_SERVICE_TOKEN: "s2",
+      ACTOR_TOKEN_SIGNING_KEY: "s3",
+      PATH: "/usr/bin",
+      MY_CUSTOM_FLAG: "yes",
+      ANTHROPIC_API_KEY: "sk-captured",
+    };
+
+    expect(buildReplayEnv(captured, "assistant")).toEqual({
+      MY_CUSTOM_FLAG: "yes",
+      ANTHROPIC_API_KEY: "sk-captured",
+    });
+  });
+
+  test("assistant: captured ANTHROPIC_API_KEY dropped when set on host", () => {
+    process.env.ANTHROPIC_API_KEY = "sk-host";
+    const replay = buildReplayEnv(
+      { ANTHROPIC_API_KEY: "sk-captured", MY_CUSTOM_FLAG: "yes" },
+      "assistant",
+    );
+    expect(replay).toEqual({ MY_CUSTOM_FLAG: "yes" });
+  });
+
+  test("a secret added to the spec is auto-excluded with no code change", () => {
+    const spec: DockerStatefulSetSpec = {
+      startOrder: ["gateway"],
+      readiness: { endpoint: "/readyz", timeoutMs: 1, intervalMs: 1 },
+      volumeClaimTemplates: [],
+      containers: [
+        {
+          name: "gateway-sidecar",
+          internalName: "gateway",
+          network: "container",
+          env: [
+            { kind: "secret", name: "FUTURE_SECRET", secret: "signingKey" },
+          ],
+          volumeMounts: [],
+        },
+      ],
+    };
+
+    const replay = buildReplayEnv(
+      { FUTURE_SECRET: "leaky", VELLUM_DEVICE_ID: "abc" },
+      "gateway",
+      spec,
+    );
+    expect(replay).toEqual({ VELLUM_DEVICE_ID: "abc" });
+  });
+});
+
+describe("buildReplayState", () => {
+  beforeEach(() => {
+    // VELLUM_DEVICE_ID env precedence keeps getOrCreateHostDeviceId off the
+    // filesystem in tests.
+    process.env.VELLUM_DEVICE_ID = "host-device-id";
+    resetHostDeviceIdCache();
+  });
+
+  test("backfills VELLUM_DEVICE_ID on gateway replay env when absent", () => {
+    const state = buildReplayState({}, { VELLUM_DISABLE_PLATFORM: "1" });
+    expect(state.extraGatewayEnv).toEqual({
+      VELLUM_DISABLE_PLATFORM: "1",
+      VELLUM_DEVICE_ID: "host-device-id",
+    });
+  });
+
+  test("captured VELLUM_DEVICE_ID wins over host-derived id", () => {
+    const state = buildReplayState({}, { VELLUM_DEVICE_ID: "existing" });
+    expect(state.extraGatewayEnv.VELLUM_DEVICE_ID).toBe("existing");
+  });
+
+  test("plucks secrets from the captured envs", () => {
+    const state = buildReplayState(
+      { CES_SERVICE_TOKEN: "ces-token", ACTOR_TOKEN_SIGNING_KEY: "sign-key" },
+      { GUARDIAN_BOOTSTRAP_SECRET: "bootstrap" },
+    );
+    expect(state.bootstrapSecret).toBe("bootstrap");
+    expect(state.cesServiceToken).toBe("ces-token");
+    expect(state.signingKey).toBe("sign-key");
+  });
+
+  test("generates fresh secrets when missing from captured env", () => {
+    const state = buildReplayState({}, {});
+    expect(state.bootstrapSecret).toBeUndefined();
+    expect(state.cesServiceToken).toMatch(/^[0-9a-f]{64}$/);
+    expect(state.signingKey).toMatch(/^[0-9a-f]{64}$/);
+  });
+});

package/src/commands/rollback.ts

@@ -1,5 +1,3 @@
-import { randomBytes } from "crypto";
-
 import {
   findAssistantByName,
   getActiveAssistant,
@@ -27,9 +25,8 @@ import {
   buildProgressEvent,
   buildStartingEvent,
   buildUpgradeCommitMessage,
-  captureContainerEnv,
+  captureReplayState,
   commitWorkspaceViaGateway,
-  CONTAINER_ENV_EXCLUDE_KEYS,
   fetchCurrentVersion,
   fetchPreviousVersion,
   performDockerRollback,
@@ -308,39 +305,13 @@ export async function rollback(): Promise<void> {
       `🔄 Rolling back Docker assistant '${instanceName}' to ${previousVersion}...\n`,
     );
 
-    // Capture current container env
-    console.log("💾 Capturing existing container environment...");
-    const capturedEnv = await captureContainerEnv(res.assistantContainer);
-    console.log(
-      `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
-    );
-
-    // Capture GUARDIAN_BOOTSTRAP_SECRET from the gateway container (it is only
-    // set on gateway, not assistant) so it persists across container restarts.
-    const gatewayEnv = await captureContainerEnv(res.gatewayContainer);
-    const bootstrapSecret = gatewayEnv["GUARDIAN_BOOTSTRAP_SECRET"];
-
-    // Extract CES_SERVICE_TOKEN from captured env, or generate fresh one
-    const cesServiceToken =
-      capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
-
-    // Extract or generate the shared JWT signing key.
-    const signingKey =
-      capturedEnv["ACTOR_TOKEN_SIGNING_KEY"] || randomBytes(32).toString("hex");
-
-    // Build extra env vars, excluding keys managed by buildServiceRunArgs
-    const envKeysSetByRunArgs = new Set(CONTAINER_ENV_EXCLUDE_KEYS);
-    for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
-      if (process.env[envVar]) {
-        envKeysSetByRunArgs.add(envVar);
-      }
-    }
-    const extraAssistantEnv: Record<string, string> = {};
-    for (const [key, value] of Object.entries(capturedEnv)) {
-      if (!envKeysSetByRunArgs.has(key)) {
-        extraAssistantEnv[key] = value;
-      }
-    }
+    const {
+      bootstrapSecret,
+      cesServiceToken,
+      signingKey,
+      extraAssistantEnv,
+      extraGatewayEnv,
+    } = await captureReplayState(res);
 
     // Parse gateway port from entry's runtimeUrl, fall back to default
     let gatewayPort = GATEWAY_INTERNAL_PORT;
@@ -401,6 +372,7 @@ export async function rollback(): Promise<void> {
         bootstrapSecret,
         cesServiceToken,
         extraAssistantEnv,
+        extraGatewayEnv,
         gatewayPort,
         imageTags: previousImageRefs,
         instanceName,

package/src/commands/upgrade.ts

@@ -1,4 +1,3 @@
-import { randomBytes } from "crypto";
 import { spawnSync } from "child_process";
 
 import cliPkg from "../../package.json";
@@ -40,10 +39,9 @@ import {
   buildProgressEvent,
   buildStartingEvent,
   buildUpgradeCommitMessage,
-  captureContainerEnv,
+  captureReplayState,
   captureUpgradeFailureLogs,
   commitWorkspaceViaGateway,
-  CONTAINER_ENV_EXCLUDE_KEYS,
   rollbackMigrations,
   UPGRADE_PROGRESS,
   waitForReady,
@@ -297,16 +295,13 @@ async function upgradeDocker(
     }),
   );
 
-  console.log("💾 Capturing existing container environment...");
-  const capturedEnv = await captureContainerEnv(res.assistantContainer);
-  console.log(
-    `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
-  );
-
-  // Capture GUARDIAN_BOOTSTRAP_SECRET from the gateway container (it is only
-  // set on gateway, not assistant) so it persists across container restarts.
-  const gatewayEnv = await captureContainerEnv(res.gatewayContainer);
-  const bootstrapSecret = gatewayEnv["GUARDIAN_BOOTSTRAP_SECRET"];
+  const {
+    bootstrapSecret,
+    cesServiceToken,
+    signingKey,
+    extraAssistantEnv,
+    extraGatewayEnv,
+  } = await captureReplayState(res);
 
   // Notify connected clients that an upgrade is about to begin.
   // This must fire BEFORE any progress broadcasts so the UI sets
@@ -361,18 +356,6 @@ async function upgradeDocker(
     // use default
   }
 
-  // Extract CES_SERVICE_TOKEN from the captured env so it can be passed via
-  // the dedicated cesServiceToken parameter (which propagates it to all three
-  // containers). If the old instance predates CES_SERVICE_TOKEN, generate a
-  // fresh one so gateway and CES can authenticate.
-  const cesServiceToken =
-    capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
-
-  // Extract or generate the shared JWT signing key. Pre-env-var instances
-  // won't have it in capturedEnv, so generate fresh in that case.
-  const signingKey =
-    capturedEnv["ACTOR_TOKEN_SIGNING_KEY"] || randomBytes(32).toString("hex");
-
   // Create pre-upgrade backup (best-effort, daemon must be running)
   await broadcastUpgradeEvent(
     entry.runtimeUrl,
@@ -415,23 +398,6 @@ async function upgradeDocker(
   await stopContainers(res);
   console.log("✅ Containers stopped\n");
 
-  // Build the set of extra env vars to replay on the new assistant container.
-  // Captured env vars serve as the base; keys already managed by
-  // buildServiceRunArgs are excluded to avoid duplicates.
-  const envKeysSetByRunArgs = new Set(CONTAINER_ENV_EXCLUDE_KEYS);
-  // Only exclude keys that buildServiceRunArgs will actually set
-  for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
-    if (process.env[envVar]) {
-      envKeysSetByRunArgs.add(envVar);
-    }
-  }
-  const extraAssistantEnv: Record<string, string> = {};
-  for (const [key, value] of Object.entries(capturedEnv)) {
-    if (!envKeysSetByRunArgs.has(key)) {
-      extraAssistantEnv[key] = value;
-    }
-  }
-
   console.log("🚀 Starting upgraded containers...");
   await startContainers(
     {
@@ -439,6 +405,7 @@ async function upgradeDocker(
       bootstrapSecret,
       cesServiceToken,
       extraAssistantEnv,
+      extraGatewayEnv,
       gatewayPort,
       imageTags,
       instanceName,
@@ -544,6 +511,7 @@ async function upgradeDocker(
             bootstrapSecret,
             cesServiceToken,
             extraAssistantEnv,
+            extraGatewayEnv,
             gatewayPort,
             imageTags: previousImageRefs,
             instanceName,

package/src/lib/device-id.ts

@@ -0,0 +1,85 @@
+/**
+ * Host device ID resolver. Resolution order: `VELLUM_DEVICE_ID` env var,
+ * then `device.json`. Production uses the machine-wide shared
+ * `~/.vellum/device.json`, matching Electron (`apps/macos/src/main/device-id.ts`)
+ * and Swift (`VellumPaths.deviceIdFile`); non-production uses
+ * `<configDir>/device.json`.
+ *
+ * Not to be confused with `guardian-token.ts`'s salted-hash Guardian
+ * identity (`computeDeviceId` / `getOrCreatePersistedDeviceId`) — do not
+ * merge the two.
+ */
+
+import { randomUUID } from "crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+import { getConfigDir } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
+
+let cached: string | undefined;
+
+function resolveDeviceIdPaths(): { dir: string; file: string } {
+  const env = getCurrentEnvironment();
+  const dir =
+    env.name === "production"
+      ? join(homedir(), ".vellum")
+      : getConfigDir(env);
+  return { dir, file: join(dir, "device.json") };
+}
+
+/**
+ * Get the stable device ID for this host machine, creating and persisting
+ * one in `device.json` if absent. `VELLUM_DEVICE_ID` takes precedence over
+ * any file. Never throws: on write failure the generated UUID is still
+ * cached and returned for the process lifetime.
+ */
+export function getOrCreateHostDeviceId(): string {
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const fromEnv = process.env.VELLUM_DEVICE_ID?.trim();
+  if (fromEnv) {
+    cached = fromEnv;
+    return cached;
+  }
+
+  const { dir, file } = resolveDeviceIdPaths();
+
+  // Preserve unrelated fields from any existing JSON object.
+  let existing: Record<string, unknown> = {};
+  try {
+    const raw: unknown = JSON.parse(readFileSync(file, "utf-8"));
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+      existing = raw as Record<string, unknown>;
+    }
+  } catch {
+    // Missing, unreadable, or malformed — start fresh.
+  }
+
+  if (typeof existing.deviceId === "string" && existing.deviceId.length > 0) {
+    cached = existing.deviceId;
+    return cached;
+  }
+
+  const generated = randomUUID();
+  try {
+    mkdirSync(dir, { recursive: true });
+    existing.deviceId = generated;
+    writeFileSync(file, JSON.stringify(existing, null, 2) + "\n", {
+      mode: 0o644,
+    });
+  } catch {
+    // Write failure — use the generated ID in-memory only.
+  }
+
+  cached = generated;
+  return cached;
+}
+
+/** Reset the cached device ID. Used by tests to force re-resolution. */
+export function resetHostDeviceIdCache(): void {
+  cached = undefined;
+}

package/src/lib/docker.ts

@@ -22,6 +22,7 @@ import type { AssistantEntry } from "./assistant-config";
 import { buildHatchConfigValues, writeInitialConfig } from "./config-utils";
 import { buildServiceRunArgs } from "./statefulset.js";
 import type { Species } from "./constants";
+import { getOrCreateHostDeviceId } from "./device-id.js";
 import { getDefaultPorts } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { leaseGuardianToken } from "./guardian-token";
@@ -882,6 +883,8 @@ function startFileWatcher(opts: {
   signingKey?: string;
   bootstrapSecret?: string;
   cesServiceToken?: string;
+  extraAssistantEnv?: Record<string, string>;
+  extraGatewayEnv?: Record<string, string>;
   gatewayPort: number;
   imageTags: Record<ServiceName, string>;
   instanceName: string;
@@ -901,6 +904,8 @@ function startFileWatcher(opts: {
     signingKey: opts.signingKey,
     bootstrapSecret: opts.bootstrapSecret,
     cesServiceToken: opts.cesServiceToken,
+    extraAssistantEnv: opts.extraAssistantEnv,
+    extraGatewayEnv: opts.extraGatewayEnv,
     gatewayPort,
     imageTags,
     instanceName,
@@ -1327,8 +1332,10 @@ export async function hatchDocker(
       extraAssistantEnv.VELLUM_DISABLE_PLATFORM =
         flagEnvVars.VELLUM_DISABLE_PLATFORM;
     }
-    const extraGatewayEnv =
-      Object.keys(flagEnvVars).length > 0 ? flagEnvVars : undefined;
+    const extraGatewayEnv = {
+      ...flagEnvVars,
+      VELLUM_DEVICE_ID: getOrCreateHostDeviceId(),
+    };
     await startContainers(
       {
         signingKey,
@@ -1430,6 +1437,8 @@ export async function hatchDocker(
         signingKey,
         bootstrapSecret,
         cesServiceToken,
+        extraAssistantEnv,
+        extraGatewayEnv,
         gatewayPort,
         imageTags,
         instanceName,

package/src/lib/statefulset.ts

@@ -262,6 +262,49 @@ export interface BuildServiceRunArgsOpts extends DockerRunSecrets {
   avatarDevicePath?: string;
 }
 
+interface BuilderManagedEnvKeys {
+  /** Always set by buildServiceRunArgs (spec static/secret entries, builder-computed extras, image-baked PATH). Never replay. */
+  always: ReadonlySet<string>;
+  /**
+   * Spec host-forwarded entries. `name` is the container-side env key (what
+   * docker inspect captures); `hostVar` is the host process.env variable
+   * buildServiceRunArgs reads. Exclude captured `name` from replay only when
+   * process.env[hostVar] is set.
+   */
+  hostForwarded: ReadonlyArray<{ name: string; hostVar: string }>;
+}
+
+/**
+ * Env var names that `buildServiceRunArgs` manages for a service, derived
+ * from the spec so future entries are picked up automatically.
+ */
+export function getBuilderManagedEnvKeys(
+  service: ServiceName,
+  spec = DOCKER_STATEFUL_SET_SPEC,
+): BuilderManagedEnvKeys {
+  const container = spec.containers.find((c) => c.internalName === service);
+  if (!container) throw new Error(`docker-statefulset: unknown service "${service}"`);
+
+  const always = new Set<string>(["PATH"]);
+  const hostForwarded: Array<{ name: string; hostVar: string }> = [];
+  for (const entry of container.env) {
+    if (entry.kind === "host") {
+      hostForwarded.push({ name: entry.name, hostVar: entry.hostVar ?? entry.name });
+    } else {
+      always.add(entry.name);
+    }
+  }
+
+  // Builder-computed extras added outside the spec env arrays
+  if (service === "assistant") {
+    always.add("VELLUM_ASSISTANT_NAME");
+    always.add("GATEWAY_INTERNAL_URL");
+    always.add(AVATAR_DEVICE_ENV_VAR);
+  }
+
+  return { always, hostForwarded };
+}
+
 function resolveVolume(
   spec: DockerStatefulSetSpec,
   instanceName: string,

package/src/lib/upgrade-lifecycle.ts

@@ -7,6 +7,7 @@ import type { AssistantEntry } from "./assistant-config.js";
 import { saveAssistantEntry } from "./assistant-config.js";
 import { createBackup, pruneOldBackups, restoreBackup } from "./backup-ops.js";
 import { emitCliError } from "./cli-error.js";
+import { getOrCreateHostDeviceId } from "./device-id.js";
 import {
   captureImageRefs,
   DOCKER_READY_TIMEOUT_MS,
@@ -19,6 +20,11 @@ import { getStateDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loadGuardianToken } from "./guardian-token.js";
 import { resolveImageRefs } from "./platform-releases.js";
+import {
+  getBuilderManagedEnvKeys,
+  type DockerStatefulSetSpec,
+  type ServiceName,
+} from "./statefulset.js";
 import { exec, execOutput } from "./step-runner.js";
 import { compareVersions } from "./version-compat.js";
 
@@ -141,20 +147,6 @@ export function buildUpgradeCommitMessage(options: {
   return lines.join("\n");
 }
 
-/**
- * Environment variable keys that are set by CLI run arguments and should
- * not be replayed from a captured container environment during upgrades
- * or rollbacks. Shared between upgrade.ts and rollback.ts.
- */
-export const CONTAINER_ENV_EXCLUDE_KEYS: ReadonlySet<string> = new Set([
-  "CES_SERVICE_TOKEN",
-  "GUARDIAN_BOOTSTRAP_SECRET",
-  "VELLUM_ASSISTANT_NAME",
-  "RUNTIME_HTTP_HOST",
-  "PATH",
-  "ACTOR_TOKEN_SIGNING_KEY",
-]);
-
 /**
  * Capture environment variables from a running Docker container so they
  * can be replayed onto the replacement container after upgrade.
@@ -183,6 +175,93 @@ export async function captureContainerEnv(
   return captured;
 }
 
+/**
+ * Filter a captured container env down to the entries safe to replay onto a
+ * replacement container.
+ *
+ * Drops every key `buildServiceRunArgs` sets itself (spec static/secret
+ * entries, builder-computed extras, PATH). Spec-managed secrets re-enter via
+ * the dedicated `DockerRunSecrets` path, so adding a secret to the spec
+ * automatically excludes it here. Spec host-forwarded keys are dropped only
+ * when the host variable is currently set, so fresh host values win over
+ * stale captured ones.
+ *
+ * Security contract: the returned env is memory-only — never persist it to
+ * disk, and log counts only, never values.
+ */
+export function buildReplayEnv(
+  capturedEnv: Record<string, string>,
+  service: ServiceName,
+  spec?: DockerStatefulSetSpec,
+): Record<string, string> {
+  const { always, hostForwarded } = getBuilderManagedEnvKeys(service, spec);
+  const hostManaged = new Set(
+    hostForwarded.filter((h) => process.env[h.hostVar]).map((h) => h.name),
+  );
+  return Object.fromEntries(
+    Object.entries(capturedEnv).filter(
+      ([key]) => !always.has(key) && !hostManaged.has(key),
+    ),
+  );
+}
+
+/** Secrets and replay env derived from the outgoing containers. */
+interface ReplayState {
+  bootstrapSecret: string | undefined;
+  cesServiceToken: string;
+  signingKey: string;
+  extraAssistantEnv: Record<string, string>;
+  extraGatewayEnv: Record<string, string>;
+}
+
+/**
+ * Derive the secrets and replay env for replacement containers from
+ * already-captured assistant/gateway envs. GUARDIAN_BOOTSTRAP_SECRET is only
+ * set on the gateway; CES_SERVICE_TOKEN and ACTOR_TOKEN_SIGNING_KEY fall back
+ * to fresh values for instances that predate them. VELLUM_DEVICE_ID is
+ * backfilled from the host for gateways hatched before device-id injection
+ * (captured value wins — it was itself host-derived).
+ */
+export function buildReplayState(
+  capturedEnv: Record<string, string>,
+  gatewayEnv: Record<string, string>,
+): ReplayState {
+  const extraGatewayEnv = buildReplayEnv(gatewayEnv, "gateway");
+  extraGatewayEnv.VELLUM_DEVICE_ID ??= getOrCreateHostDeviceId();
+
+  return {
+    bootstrapSecret: gatewayEnv["GUARDIAN_BOOTSTRAP_SECRET"],
+    cesServiceToken:
+      capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex"),
+    signingKey:
+      capturedEnv["ACTOR_TOKEN_SIGNING_KEY"] || randomBytes(32).toString("hex"),
+    extraAssistantEnv: buildReplayEnv(capturedEnv, "assistant"),
+    extraGatewayEnv,
+  };
+}
+
+/**
+ * Capture the assistant and gateway container envs and derive the replay
+ * state for the replacement containers. Logs only the assistant env-var
+ * count (security contract on `buildReplayEnv`).
+ */
+export async function captureReplayState(
+  res: Pick<
+    ReturnType<typeof dockerResourceNames>,
+    "assistantContainer" | "gatewayContainer"
+  >,
+): Promise<ReplayState> {
+  console.log("💾 Capturing existing container environment...");
+  const [capturedEnv, gatewayEnv] = await Promise.all([
+    captureContainerEnv(res.assistantContainer),
+    captureContainerEnv(res.gatewayContainer),
+  ]);
+  console.log(
+    `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
+  );
+  return buildReplayState(capturedEnv, gatewayEnv);
+}
+
 /**
  * Best-effort fetch of the running service group version from the gateway
  * `/healthz` endpoint.  Returns `undefined` when the endpoint is
@@ -581,37 +660,13 @@ export async function performDockerRollback(
     console.warn("⚠️  Pre-rollback backup failed (continuing with rollback)\n");
   }
 
-  // Capture container env, extract secrets
-  console.log("💾 Capturing existing container environment...");
-  const capturedEnv = await captureContainerEnv(res.assistantContainer);
-  console.log(
-    `   Captured ${Object.keys(capturedEnv).length} env var(s) from ${res.assistantContainer}\n`,
-  );
-
-  // Capture GUARDIAN_BOOTSTRAP_SECRET from the gateway container (it is only
-  // set on gateway, not assistant) so it persists across container restarts.
-  const gatewayEnv = await captureContainerEnv(res.gatewayContainer);
-  const bootstrapSecret = gatewayEnv["GUARDIAN_BOOTSTRAP_SECRET"];
-
-  const cesServiceToken =
-    capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
-
-  const signingKey =
-    capturedEnv["ACTOR_TOKEN_SIGNING_KEY"] || randomBytes(32).toString("hex");
-
-  // Build extra env vars, excluding keys managed by buildServiceRunArgs
-  const envKeysSetByRunArgs = new Set(CONTAINER_ENV_EXCLUDE_KEYS);
-  for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
-    if (process.env[envVar]) {
-      envKeysSetByRunArgs.add(envVar);
-    }
-  }
-  const extraAssistantEnv: Record<string, string> = {};
-  for (const [key, value] of Object.entries(capturedEnv)) {
-    if (!envKeysSetByRunArgs.has(key)) {
-      extraAssistantEnv[key] = value;
-    }
-  }
+  const {
+    bootstrapSecret,
+    cesServiceToken,
+    signingKey,
+    extraAssistantEnv,
+    extraGatewayEnv,
+  } = await captureReplayState(res);
 
   // Parse gateway port from entry's runtimeUrl
   let gatewayPort = GATEWAY_INTERNAL_PORT;
@@ -684,6 +739,7 @@ export async function performDockerRollback(
       bootstrapSecret,
       cesServiceToken,
       extraAssistantEnv,
+      extraGatewayEnv,
       gatewayPort,
       imageTags: targetImageTags,
       instanceName,
@@ -801,6 +857,7 @@ export async function performDockerRollback(
             bootstrapSecret,
             cesServiceToken,
             extraAssistantEnv,
+            extraGatewayEnv,
             gatewayPort,
             imageTags: currentImageRefs,
             instanceName,