@vellumai/cli 0.10.5 → 0.10.6-dev.202607062043.72bc40b

package/node_modules/@vellumai/local-mode/src/__tests__/upgrade.test.ts

@@ -0,0 +1,128 @@
+import { afterEach, beforeAll, describe, expect, mock, test } from "bun:test";
+import { EventEmitter } from "node:events";
+
+import type { CliInvocation } from "../util";
+
+class FakeChild extends EventEmitter {
+  stdout = new EventEmitter();
+  stderr = new EventEmitter();
+  kill = mock(() => true);
+}
+
+let lastChild: FakeChild;
+const spawnArgs: Array<
+  [string, string[], { env?: NodeJS.ProcessEnv; stdio?: unknown }]
+> = [];
+const spawnMock = mock(
+  (
+    command: string,
+    args: string[],
+    options: { env?: NodeJS.ProcessEnv; stdio?: unknown },
+  ) => {
+    spawnArgs.push([command, args, options]);
+    lastChild = new FakeChild();
+    return lastChild;
+  },
+);
+
+mock.module("node:child_process", () => ({ spawn: spawnMock }));
+
+let runUpgrade: typeof import("../upgrade").runUpgrade;
+let isValidReleaseVersion: typeof import("../upgrade").isValidReleaseVersion;
+
+beforeAll(async () => {
+  ({ runUpgrade, isValidReleaseVersion } = await import("../upgrade"));
+});
+
+afterEach(() => {
+  spawnArgs.length = 0;
+  spawnMock.mockClear();
+});
+
+const invocation: CliInvocation = { command: "bun", baseArgs: ["run", "cli"] };
+
+describe("isValidReleaseVersion", () => {
+  test("accepts release tags, staying lenient about semver shape", () => {
+    for (const version of [
+      "latest",
+      "v1.2.3",
+      "V1.2.3", // uppercase prefix
+      "1.2.3",
+      "1.2", // two-part
+      "1.2.3.4", // four-part
+      "0.6.0-staging.5",
+      "1.2.3-rc.1+build.7",
+    ]) {
+      expect(isValidReleaseVersion(version)).toBe(true);
+    }
+  });
+
+  test("rejects package specs and path-traversal input", () => {
+    for (const version of [
+      "npm:@attacker/evil@1.0.0",
+      "https://evil.example/x.tgz",
+      "git+https://evil.example/x.git",
+      "github:attacker/vellum",
+      "file:/tmp/evil",
+      "../../../../tmp/evil",
+      "1.2.3-..", // no consecutive dots (would be a traversal segment)
+      "1.2.3-a..b",
+      "..",
+      "",
+      "vellum@1.2.3",
+    ]) {
+      expect(isValidReleaseVersion(version)).toBe(false);
+    }
+  });
+});
+
+describe("runUpgrade", () => {
+  test("spawns the CLI upgrade command for a release tag", async () => {
+    const pending = runUpgrade(invocation, "asst-42", { version: "v1.2.3" });
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true });
+    expect(spawnArgs[0]).toEqual([
+      "bun",
+      ["run", "cli", "upgrade", "asst-42", "--version", "v1.2.3"],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    ]);
+  });
+
+  test("spawns the CLI upgrade command for --latest", async () => {
+    const pending = runUpgrade(invocation, "asst-42", { latest: true });
+    lastChild.emit("close", 0);
+
+    expect(await pending).toEqual({ ok: true });
+    expect(spawnArgs[0]?.[1]).toEqual([
+      "run",
+      "cli",
+      "upgrade",
+      "asst-42",
+      "--latest",
+    ]);
+  });
+
+  test("rejects a malicious version without spawning", async () => {
+    const result = await runUpgrade(invocation, "asst-42", {
+      version: "npm:@attacker/evil@1.0.0",
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      status: 400,
+      error:
+        "Invalid upgrade version 'npm:@attacker/evil@1.0.0': expected a release tag like v1.2.3 or 'latest'.",
+    });
+    expect(spawnArgs.length).toBe(0);
+  });
+
+  test("rejects a path-traversal version without spawning", async () => {
+    const result = await runUpgrade(invocation, "asst-42", {
+      version: "../../../../tmp/evil",
+    });
+
+    expect(result.ok).toBe(false);
+    expect(spawnArgs.length).toBe(0);
+  });
+});

package/node_modules/@vellumai/local-mode/src/index.ts

@@ -48,7 +48,7 @@ export { runSleep } from "./sleep";
 export type { SleepResult } from "./sleep";
 export { runWake } from "./wake";
 export type { WakeOptions, WakeResult } from "./wake";
-export { runUpgrade } from "./upgrade";
+export { runUpgrade, isValidReleaseVersion } from "./upgrade";
 export type { UpgradeOptions, UpgradeResult } from "./upgrade";
 export { getLocalAssistantStatus } from "./status";
 export type {

package/node_modules/@vellumai/local-mode/src/upgrade.ts

@@ -14,6 +14,37 @@ export interface UpgradeOptions {
   force?: boolean;
 }
 
+// A trusted release version is the literal `latest` dist-tag, or a
+// version-shaped string: an optional `v`/`V` prefix, then a leading digit,
+// then any run of `[0-9A-Za-z.+-]`. This is intentionally lenient about the
+// *shape* of the version (2-, 3-, or 4-part, arbitrary pre-release/build
+// identifiers, uppercase `V`) so we never reject a legitimate release tag.
+//
+// Security does not depend on the shape — it depends on the CHARSET. The
+// allowed set excludes `/`, `\`, `:`, `@`, `#` and whitespace, so the value can
+// never be interpreted by `bun install` as a package-manager spec (npm alias,
+// tarball/git URL, `file:`/`github:` ref) — all of which require one of those
+// characters. The mandatory leading digit means the value can never be a bare
+// `.`/`..` path segment, and `..` is rejected outright, so the version is safe
+// to use as the runtime-install directory name.
+const RELEASE_VERSION_PATTERN = /^(?:latest|[vV]?\d[0-9A-Za-z.+-]*)$/;
+
+/**
+ * Whether `version` is a trusted release identifier: the literal `latest`, or a
+ * version-shaped tag like `v1.2.3` / `1.2.3` / `0.6.0-staging.5`. Rejects
+ * package-manager specifiers (npm aliases, tarball or git URLs) and any
+ * path-traversal-like input, while staying permissive about semver shape.
+ *
+ * Defined once here and reused by both the host-bridge boundary guard
+ * (`runUpgrade`, in the shared library backing the Electron host and the web
+ * dev-server middleware) and the CLI's runtime-install sink
+ * (`ensureLocalRuntime`), so the security boundary can never drift between the
+ * two call sites.
+ */
+export function isValidReleaseVersion(version: string): boolean {
+  return RELEASE_VERSION_PATTERN.test(version) && !version.includes("..");
+}
+
 function extractVersion(output: string): string | undefined {
   const versionPattern = "(v?[0-9]+(?:\\.[0-9]+)*(?:[-+][\\w.-]+)?)";
   const upgraded = output.match(
@@ -35,6 +66,18 @@ export function runUpgrade(
   options?: UpgradeOptions,
 ): Promise<UpgradeResult> {
   return new Promise((resolve) => {
+    // Reject an untrusted `--version` at the host boundary before spawning the
+    // CLI. `latest` (or the `--latest` flag) is always allowed; an explicit
+    // version must be a release tag. Preserves the never-reject contract.
+    if (options?.version && !isValidReleaseVersion(options.version)) {
+      resolve({
+        ok: false,
+        status: 400,
+        error: `Invalid upgrade version '${options.version}': expected a release tag like v1.2.3 or 'latest'.`,
+      });
+      return;
+    }
+
     const args = [...invocation.baseArgs, "upgrade", assistantId];
     if (options?.latest) {
       args.push("--latest");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.5",
+  "version": "0.10.6-dev.202607062043.72bc40b",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/local-runtime-version.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+
+import { isValidReleaseVersion } from "@vellumai/local-mode";
+
+import type { LocalInstanceResources } from "../lib/assistant-config.js";
+import { ensureLocalRuntime } from "../lib/local.js";
+
+// Only `instanceDir` is read, and only after the validation guard passes —
+// invalid versions throw before any filesystem access, so a minimal stub is
+// sufficient for the rejection cases.
+const resources = {
+  instanceDir: "/tmp/vellum-nonexistent-instance",
+} as unknown as LocalInstanceResources;
+
+const VALID_VERSIONS = ["latest", "v1.2.3", "1.2.3", "0.6.0-staging.5"];
+const MALICIOUS_VERSIONS = [
+  "npm:@attacker/evil@1.0.0",
+  "https://evil.example/x.tgz",
+  "git+https://evil.example/x.git",
+  "../../../../tmp/evil",
+  "1.2.3-..",
+  "1.2.3-a..b",
+];
+
+describe("ensureLocalRuntime version guard", () => {
+  test("shares the trusted-release validator with the host boundary", () => {
+    for (const version of VALID_VERSIONS) {
+      expect(isValidReleaseVersion(version)).toBe(true);
+    }
+    for (const version of MALICIOUS_VERSIONS) {
+      expect(isValidReleaseVersion(version)).toBe(false);
+    }
+  });
+
+  test("throws before any install for untrusted versions", () => {
+    for (const version of MALICIOUS_VERSIONS) {
+      expect(() => ensureLocalRuntime(resources, version)).toThrow(
+        `Invalid runtime version '${version}'`,
+      );
+    }
+  });
+});

package/src/__tests__/retire-local.test.ts

@@ -0,0 +1,157 @@
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AssistantEntry } from "../lib/assistant-config.js";
+
+const testDir = mkdtempSync(join(tmpdir(), "retire-local-test-"));
+const originalLockfileDir = process.env.VELLUM_LOCKFILE_DIR;
+
+const stopProcessByPidFileMock = mock(
+  async (_pidFile: string, _label: string): Promise<boolean> => true,
+);
+const stopOrphanedDaemonProcessesMock = mock(async (): Promise<boolean> => false);
+const stopIngressNginxMock = mock(async (): Promise<boolean> => false);
+
+mock.module("../lib/process.js", () => ({
+  stopProcessByPidFile: stopProcessByPidFileMock,
+  stopOrphanedDaemonProcesses: stopOrphanedDaemonProcessesMock,
+}));
+
+mock.module("../lib/nginx-ingress.js", () => ({
+  stopIngressNginx: stopIngressNginxMock,
+}));
+
+// Keep archive paths on the same filesystem as the test dir so rename doesn't
+// hit EXDEV (cross-device link).
+const retiredStagingDir = join(testDir, "retired");
+mock.module("../lib/retire-archive.js", () => ({
+  getArchivePath: () => join(retiredStagingDir, "test-assistant.tar.gz"),
+  getMetadataPath: () => join(retiredStagingDir, "test-assistant.meta.json"),
+}));
+
+import { retireLocal } from "../lib/retire-local.js";
+
+const instanceDir = join(testDir, "test-instance");
+const vellumDir = join(instanceDir, ".vellum");
+
+function makeEntry(assistantId: string): AssistantEntry {
+  return {
+    assistantId,
+    runtimeUrl: "http://127.0.0.1:7801",
+    cloud: "local",
+    resources: {
+      instanceDir,
+      daemonPort: 7801,
+      gatewayPort: 7831,
+      qdrantPort: 6334,
+      cesPort: 7790,
+    },
+  };
+}
+
+function writeLockfile(entries: AssistantEntry[]): void {
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify({ assistants: entries }, null, 2) + "\n",
+  );
+}
+
+describe("retireLocal — CES sibling stop", () => {
+  beforeAll(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+  });
+
+  beforeEach(() => {
+    stopProcessByPidFileMock.mockReset();
+    stopProcessByPidFileMock.mockResolvedValue(true);
+    stopOrphanedDaemonProcessesMock.mockReset();
+    stopOrphanedDaemonProcessesMock.mockResolvedValue(false);
+    stopIngressNginxMock.mockReset();
+    stopIngressNginxMock.mockResolvedValue(false);
+
+    rmSync(instanceDir, { recursive: true, force: true });
+    rmSync(join(testDir, "retired"), { recursive: true, force: true });
+    mkdirSync(vellumDir, { recursive: true });
+    writeLockfile([makeEntry("test-assistant")]);
+
+    // Suppress console output from the lifecycle reporter.
+    spyOn(console, "log").mockImplementation(() => {});
+    spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterAll(() => {
+    if (originalLockfileDir === undefined) {
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    } else {
+      process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+    }
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("stops the CES sibling alongside daemon and gateway", async () => {
+    const entry = makeEntry("test-assistant");
+    await retireLocal("test-assistant", entry, {
+      progress: () => {},
+      log: () => {},
+      warn: () => {},
+      error: () => {},
+    });
+
+    // Verify CES PID file is among the stop calls.
+    const cesStopCall = stopProcessByPidFileMock.mock.calls.find(
+      ([pidFile, label]) =>
+        pidFile === join(vellumDir, "ces.pid") &&
+        label === "credential-executor",
+    );
+    expect(cesStopCall).toBeDefined();
+
+    // Also verify daemon and gateway are still stopped (sanity).
+    const daemonStopCall = stopProcessByPidFileMock.mock.calls.find(
+      ([, label]) => label === "daemon",
+    );
+    expect(daemonStopCall).toBeDefined();
+
+    const gatewayStopCall = stopProcessByPidFileMock.mock.calls.find(
+      ([, label]) => label === "gateway",
+    );
+    expect(gatewayStopCall).toBeDefined();
+  });
+
+  test("CES stop is a no-op when ces.pid is absent", async () => {
+    // stopProcessByPidFile returns false when the PID file doesn't exist.
+    // retireLocal should still complete successfully — the CES stop is best-effort.
+    stopProcessByPidFileMock.mockImplementation(
+      async (pidFile: string): Promise<boolean> => {
+        if (pidFile.includes("ces.pid")) return false;
+        return true;
+      },
+    );
+
+    const entry = makeEntry("test-assistant");
+    await retireLocal("test-assistant", entry, {
+      progress: () => {},
+      log: () => {},
+      warn: () => {},
+      error: () => {},
+    });
+
+    // The CES stop was attempted (PID file checked) but returned false.
+    const cesStopCall = stopProcessByPidFileMock.mock.calls.find(
+      ([pidFile, label]) =>
+        pidFile === join(vellumDir, "ces.pid") &&
+        label === "credential-executor",
+    );
+    expect(cesStopCall).toBeDefined();
+  });
+});

package/src/__tests__/sleep.test.ts

@@ -139,7 +139,8 @@ describe("sleep command", () => {
       consoleLog.mockRestore();
     }
 
-    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(2);
+    // assistant + gateway + CES sibling
+    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(3);
   });
 
   test("force stops the assistant even when an active call lease exists", async () => {
@@ -154,7 +155,7 @@ describe("sleep command", () => {
       consoleLog.mockRestore();
     }
 
-    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(2);
+    expect(stopProcessByPidFileMock).toHaveBeenCalledTimes(3);
     // The assistant stop passes a generous 120s grace so the daemon's WAL
     // checkpoint completes before any SIGKILL (default 2s would truncate it).
     expect(stopProcessByPidFileMock).toHaveBeenNthCalledWith(
@@ -171,5 +172,12 @@ describe("sleep command", () => {
       undefined,
       7000,
     );
+    // The CES sibling (CES_STANDALONE opt-in) is stopped by its PID file; a
+    // no-op when absent on the default topology.
+    expect(stopProcessByPidFileMock).toHaveBeenNthCalledWith(
+      3,
+      join(assistantRootDir, "ces.pid"),
+      "credential-executor",
+    );
   });
 });

package/src/__tests__/wake.test.ts

@@ -90,11 +90,16 @@ const resolveProcessStateMock = mock<typeof processLib.resolveProcessState>(
 const stopProcessByPidFileMock = mock<typeof processLib.stopProcessByPidFile>(
   async () => true,
 );
+const isProcessAliveMock = mock<typeof processLib.isProcessAlive>(() => ({
+  alive: false,
+  pid: null,
+}));
 
 mock.module("../lib/process", () => ({
   ...realProcessLib,
   resolveProcessState: resolveProcessStateMock,
   stopProcessByPidFile: stopProcessByPidFileMock,
+  isProcessAlive: isProcessAliveMock,
 }));
 
 const generateLocalSigningKeyMock = mock<typeof local.generateLocalSigningKey>(
@@ -110,6 +115,7 @@ const startLocalDaemonMock = mock<typeof local.startLocalDaemon>(async () => {})
 const startGatewayMock = mock<typeof local.startGateway>(
   async () => "http://127.0.0.1:7830",
 );
+const startCesMock = mock<typeof local.startCes>(async () => {});
 
 mock.module("../lib/local", () => ({
   ...realLocal,
@@ -118,6 +124,7 @@ mock.module("../lib/local", () => ({
   isGatewayWatchModeAvailable: isGatewayWatchModeAvailableMock,
   startLocalDaemon: startLocalDaemonMock,
   startGateway: startGatewayMock,
+  startCes: startCesMock,
 }));
 
 const maybeStartNgrokTunnelMock = mock<typeof ngrok.maybeStartNgrokTunnel>(
@@ -184,6 +191,10 @@ beforeEach(() => {
   startLocalDaemonMock.mockResolvedValue(undefined);
   startGatewayMock.mockReset();
   startGatewayMock.mockResolvedValue("http://127.0.0.1:7830");
+  startCesMock.mockReset();
+  startCesMock.mockResolvedValue(undefined);
+  isProcessAliveMock.mockReset();
+  isProcessAliveMock.mockReturnValue({ alive: false, pid: null });
   seedGuardianTokenFromSiblingEnvMock.mockReset();
   seedGuardianTokenFromSiblingEnvMock.mockReturnValue(false);
   loadGuardianTokenMock.mockReset();
@@ -291,4 +302,27 @@ describe("vellum wake", () => {
       "generated-bootstrap-secret",
     );
   });
+
+  test("relaunches CES sibling when daemon is healthy but CES is dead", async () => {
+    // Daemon is healthy (default mock) but CES pid says dead.
+    // isProcessAliveMock defaults to { alive: false }.
+    await wake();
+
+    // startCes should be called to relaunch the dead sibling.
+    expect(startCesMock).toHaveBeenCalledTimes(1);
+    // startLocalDaemon should NOT be called (daemon already running).
+    expect(startLocalDaemonMock).not.toHaveBeenCalled();
+  });
+
+  test("does NOT relaunch CES sibling when both daemon and CES are healthy", async () => {
+    // Daemon is healthy (default mock). CES is also alive.
+    isProcessAliveMock.mockReturnValue({ alive: true, pid: 789 });
+
+    await wake();
+
+    // startCes should NOT be called (CES is alive).
+    expect(startCesMock).not.toHaveBeenCalled();
+    // startLocalDaemon should NOT be called (daemon already running).
+    expect(startLocalDaemonMock).not.toHaveBeenCalled();
+  });
 });

package/src/commands/hatch.ts

@@ -146,7 +146,7 @@ ${userSetup}
 ${envSetLines}
 VELLUM_ASSISTANT_NAME=${instanceName}
 mkdir -p "\$HOME/.config/vellum"
-cat > "\$HOME/.config/vellum/env" << DOTENV_EOF
+cat > "\$HOME/.config/vellum/.env" << DOTENV_EOF
 ${dotenvLines}
 RUNTIME_HTTP_PORT=7821
 DOTENV_EOF

package/src/commands/recover.ts

@@ -12,6 +12,7 @@ import { saveAssistantEntry } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import {
   generateLocalSigningKey,
+  startCes,
   startLocalDaemon,
   startGateway,
 } from "../lib/local";
@@ -117,9 +118,14 @@ export async function recover(): Promise<void> {
   entry.guardianBootstrapSecret = bootstrapSecret;
   saveAssistantEntry(entry);
 
-  // 8. Start daemon + gateway
-  await startLocalDaemon(false, entry.resources, { signingKey });
-  await startGateway(false, entry.resources, { signingKey, bootstrapSecret });
+  // 8. Start CES sibling (opt-in) + daemon + gateway in parallel, the way the
+  // Docker topology brings its sibling processes up together. startCes is a
+  // no-op unless CES_STANDALONE is set.
+  await Promise.all([
+    startCes(false, entry.resources),
+    startLocalDaemon(false, entry.resources, { signingKey }),
+    startGateway(false, entry.resources, { signingKey, bootstrapSecret }),
+  ]);
 
   console.log(`✅ Recovered assistant '${name}'.`);
 }

package/src/commands/sleep.ts

@@ -168,6 +168,18 @@ export async function sleep(): Promise<void> {
     console.log("Gateway stopped.");
   }
 
+  // Stop the CES sibling if one was launched (CES_STANDALONE). No-op when the
+  // PID file is absent — on the default topology the assistant owns CES as an
+  // stdio child and it exits with the daemon.
+  const cesPidFile = join(vellumDir, "ces.pid");
+  const cesStopped = await stopProcessByPidFile(
+    cesPidFile,
+    "credential-executor",
+  );
+  if (cesStopped) {
+    console.log("credential-executor stopped.");
+  }
+
   // Stop the nginx ingress if one is fronting this gateway — otherwise it
   // keeps running against a dead upstream and serves 502s.
   const ingressStopped = await stopIngressNginx(join(vellumDir, "workspace"));

package/src/commands/upgrade.ts

@@ -66,6 +66,7 @@ import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 import {
   generateLocalSigningKey,
   ensureLocalRuntime,
+  startCes,
   startGateway,
   startLocalDaemon,
   stopLocalProcesses,
@@ -434,7 +435,8 @@ async function upgradeDocker(
   }
 
   // Recover the assistant host port from the entry, fall back to default.
-  const assistantPort = entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
+  const assistantPort =
+    entry.containerInfo?.assistantPort ?? ASSISTANT_INTERNAL_PORT;
 
   // Create pre-upgrade backup (best-effort, daemon must be running)
   await broadcastUpgradeEvent(
@@ -984,8 +986,14 @@ async function upgradeLocal(
   const previousAppVersion = process.env.APP_VERSION;
   process.env.APP_VERSION = stripVersionPrefix(targetVersion);
   try {
-    await startLocalDaemon(false, entry.resources, { signingKey });
-    await startGateway(false, entry.resources, { signingKey, bootstrapSecret });
+    // Bring CES, daemon, and gateway up in parallel, the way the Docker
+    // topology starts its sibling processes together. startCes is a no-op
+    // unless CES_STANDALONE is set.
+    await Promise.all([
+      startCes(false, entry.resources),
+      startLocalDaemon(false, entry.resources, { signingKey }),
+      startGateway(false, entry.resources, { signingKey, bootstrapSecret }),
+    ]);
   } finally {
     if (previousAppVersion === undefined) {
       delete process.env.APP_VERSION;

package/src/commands/wake.ts

@@ -12,11 +12,12 @@ import {
   resetGuardianBootstrap,
   seedGuardianTokenFromSiblingEnv,
 } from "../lib/guardian-token.js";
-import { resolveProcessState, stopProcessByPidFile } from "../lib/process";
+import { resolveProcessState, stopProcessByPidFile, isProcessAlive } from "../lib/process";
 import {
   generateLocalSigningKey,
   isAssistantWatchModeAvailable,
   isGatewayWatchModeAvailable,
+  startCes,
   startLocalDaemon,
   startGateway,
 } from "../lib/local";
@@ -176,7 +177,31 @@ export async function wake(): Promise<void> {
   }
 
   if (!daemonRunning) {
-    await startLocalDaemon(watch, resources, { foreground, signingKey });
+    // Spin up CES and the daemon in parallel, the way the Docker topology
+    // brings its sibling containers up together — the assistant polls for the
+    // CES socket during startup (discoverCesWithRetry), so it tolerates CES
+    // still binding. CES's lifecycle tracks the daemon (its only consumer):
+    // restarting it under a live daemon would sever the daemon's open
+    // connection, so it is only (re)started alongside the daemon. startCes is a
+    // no-op unless CES_STANDALONE is set, in which case the assistant spawns
+    // CES itself as today.
+    await Promise.all([
+      startCes(watch, resources),
+      startLocalDaemon(watch, resources, { foreground, signingKey }),
+    ]);
+  } else {
+    // Self-heal: the daemon is already healthy, but the CES sibling may have
+    // died independently (crash, OOM kill). A dead ces.pid under a live daemon
+    // means credential operations will fail until the next wake. Relaunch the
+    // sibling so the daemon's lazy reconnect (secure-keys.ts) picks it up on
+    // the next credential read. startCes is a no-op unless CES_STANDALONE.
+    const vellumDir = join(resources.instanceDir, ".vellum");
+    const cesPidFile = join(vellumDir, "ces.pid");
+    const cesAlive = isProcessAlive(cesPidFile).alive;
+    if (!cesAlive) {
+      console.log("CES sibling not running — relaunching...");
+      await startCes(watch, resources);
+    }
   }
 
   // Start gateway
@@ -256,7 +281,11 @@ export async function wake(): Promise<void> {
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       try {
         await resetGuardianBootstrap(loopbackUrl, bootstrapSecret);
-        await leaseGuardianToken(loopbackUrl, entry.assistantId, bootstrapSecret);
+        await leaseGuardianToken(
+          loopbackUrl,
+          entry.assistantId,
+          bootstrapSecret,
+        );
         console.log("   Re-provisioned guardian token.");
         break;
       } catch (err) {

package/src/index.ts

@@ -1,5 +1,10 @@
 #!/usr/bin/env bun
 
+import { join } from "path";
+import { readFileSync } from "node:fs";
+
+import { resolveConfigDir } from "@vellumai/local-mode";
+
 import cliPkg from "../package.json";
 import { backup } from "./commands/backup";
 import { clean } from "./commands/clean";
@@ -156,6 +161,56 @@ function applyNoColorFlags(argv: string[]): void {
   }
 }
 
+/**
+ * Load env vars from the vellum config dotenv file into `process.env` so
+ * that `vellum hatch` forwards provider API keys to containers and other
+ * commands have access to them.
+ *
+ * Reads `$XDG_CONFIG_HOME/vellum{-env}/.env` — the same config directory
+ * the CLI uses for guardian tokens and environment state. The file is
+ * written by remote-hatch scripts and can be user-managed.
+ *
+ * Existing `process.env` values take precedence (standard dotenv convention).
+ * Only KEY=VALUE lines are parsed. Lines starting with # are comments.
+ * Values may be quoted with single or double quotes.
+ */
+function loadConfigDotenv(): void {
+  const configDir = resolveConfigDir(process.env);
+  const envPath = join(configDir, ".env");
+
+  let content: string;
+  try {
+    content = readFileSync(envPath, "utf-8");
+  } catch {
+    return;
+  }
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+
+    const key = trimmed.slice(0, eqIndex).trim();
+    if (!key) continue;
+
+    // Existing env vars take precedence (dotenv convention).
+    if (process.env[key] !== undefined) continue;
+
+    let value = trimmed.slice(eqIndex + 1).trim();
+    // Strip surrounding quotes.
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    process.env[key] = value;
+  }
+}
+
 /**
  * If a running assistant is detected, launch the TUI client and return true.
  * Otherwise return false so the caller can fall back to help text.
@@ -181,6 +236,10 @@ async function tryLaunchClient(): Promise<boolean> {
 }
 
 async function main() {
+  // Load $XDG_CONFIG_HOME/vellum/.env before any command runs so
+  // provider API keys and other config are available to hatch, exec, etc.
+  loadConfigDotenv();
+
   const args = process.argv.slice(2);
 
   // Must run before any command or terminal-capabilities usage

package/src/lib/docker.ts

@@ -1626,7 +1626,45 @@ async function waitForGatewayAndLease(opts: {
     log(`  Container: ${containerName}`);
     log("");
     log(`Stop with: vellum retire ${instanceName}`);
-    return { ready: true };
+
+    // Lease a guardian token even in detached mode so that `vellum ps`,
+    // `vellum exec`, and other CLI commands can authenticate to the
+    // gateway. Skip the /readyz readiness poll (the caller asked to detach
+    // and not block) but retry the lease itself since the gateway may need
+    // a moment to accept connections after the container starts.
+    const leaseStart = Date.now();
+    const leaseDeadline = containersUpAt + DOCKER_READY_TIMEOUT_MS;
+    let guardianAccessToken: string | undefined;
+    while (Date.now() < leaseDeadline) {
+      try {
+        const tokenData = await leaseGuardianToken(
+          runtimeUrl,
+          instanceName,
+          bootstrapSecret,
+        );
+        guardianAccessToken = tokenData.accessToken;
+        const leaseElapsed = ((Date.now() - leaseStart) / 1000).toFixed(1);
+        log(
+          `Guardian token lease: success after ${leaseElapsed}s (principalId=${tokenData.guardianPrincipalId})`,
+        );
+        break;
+      } catch (err) {
+        const elapsed = ((Date.now() - leaseStart) / 1000).toFixed(0);
+        const msg = err instanceof Error ? err.message : String(err);
+        log(
+          `Guardian token lease: attempt failed after ${elapsed}s (${msg.split("\n")[0]}), retrying...`,
+        );
+        await new Promise((r) => setTimeout(r, 2000));
+      }
+    }
+    if (!guardianAccessToken) {
+      log(
+        `⚠️  Guardian token lease failed after ${DOCKER_READY_TIMEOUT_MS / 1000}s.\n` +
+          `   The assistant is running but CLI commands (vellum ps, vellum exec) will not authenticate.\n` +
+          `   Re-hatch or run \`vellum setup\` to recover.`,
+      );
+    }
+    return { ready: true, guardianAccessToken };
   }
 
   log(`  Container: ${containerName}`);

package/src/lib/hatch-local.ts

@@ -25,6 +25,7 @@ import type { Species } from "./constants.js";
 import { buildHatchConfigValues, writeInitialConfig } from "./config-utils.js";
 import {
   generateLocalSigningKey,
+  startCes,
   startLocalDaemon,
   startGateway,
   stopLocalProcesses,
@@ -225,10 +226,17 @@ export async function hatchLocal(
   reporter.progress(3, 6, "Starting assistant...");
   const signingKey = generateLocalSigningKey();
   const bootstrapSecret = generateLocalSigningKey();
-  await startLocalDaemon(watch, resources, {
-    defaultWorkspaceConfigPath,
-    signingKey,
-  });
+  // Launch the CES sibling alongside the daemon, in parallel — matching the
+  // Docker topology. Under the opt-in the assistant does not spawn its own CES,
+  // so a freshly hatched instance would otherwise come up with CES unavailable.
+  // startCes is a no-op unless CES_STANDALONE is set.
+  await Promise.all([
+    startCes(watch, resources),
+    startLocalDaemon(watch, resources, {
+      defaultWorkspaceConfigPath,
+      signingKey,
+    }),
+  ]);
 
   reporter.progress(4, 6, "Starting gateway...");
   let runtimeUrl = `http://127.0.0.1:${resources.gatewayPort}`;

package/src/lib/local.ts

@@ -11,6 +11,8 @@ import { createRequire } from "module";
 import { homedir, networkInterfaces, platform, tmpdir } from "os";
 import { basename, dirname, join } from "path";
 
+import { isValidReleaseVersion } from "@vellumai/local-mode";
+
 import {
   getDaemonPidPath,
   type LocalInstanceResources,
@@ -143,11 +145,36 @@ function localRuntimeGatewayDir(
   return isGatewaySourceDir(candidate) ? candidate : undefined;
 }
 
+function localRuntimeCesDir(
+  resources: LocalInstanceResources | undefined,
+): string | undefined {
+  const installDir = resources?.runtimeInstallDir;
+  if (!installDir) return undefined;
+  const candidate = packagePath(
+    installDir,
+    "@vellumai/credential-executor",
+    "",
+  );
+  return isCesSourceDir(candidate) ? candidate : undefined;
+}
+
 export function ensureLocalRuntime(
   resources: LocalInstanceResources,
   version: string,
   options: { force?: boolean } = {},
 ): LocalRuntimeInstall {
+  // Reject anything that is not a trusted release identifier BEFORE it becomes
+  // a filesystem path segment or a `bun install` dependency spec. Without this,
+  // a package-manager spec (npm alias, tarball/git URL) or a `../`-laden string
+  // reaching this sink would install and then execute arbitrary attacker code
+  // as the local assistant runtime. Shares the validator with the host-bridge
+  // boundary guard (`runUpgrade`) so the two can never drift.
+  if (!isValidReleaseVersion(version)) {
+    throw new Error(
+      `Invalid runtime version '${version}': expected a release tag like v1.2.3 or 'latest'.`,
+    );
+  }
+
   const normalizedVersion = normalizeRuntimeVersion(version);
   const displayVersion =
     normalizedVersion === "latest" ? "latest" : `v${normalizedVersion}`;
@@ -333,6 +360,18 @@ function isGatewaySourceDir(dir: string): boolean {
   }
 }
 
+function isCesSourceDir(dir: string): boolean {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "main.ts")))
+    return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.name === "@vellumai/credential-executor";
+  } catch {
+    return false;
+  }
+}
+
 function findGatewaySourceFromCwd(): string | undefined {
   let current = process.cwd();
   while (true) {
@@ -526,6 +565,14 @@ function applyDaemonEnvOverrides(
     env.VELLUM_DEFAULT_WORKSPACE_CONFIG_PATH =
       options.defaultWorkspaceConfigPath;
   }
+  // When the CLI launches CES as a sibling (CES_STANDALONE), pin the daemon to
+  // the exact socket the sibling binds so the two agree regardless of any stale
+  // CES_LOCAL_SOCKET inherited from the parent environment. The assistant then
+  // connects to the sibling instead of spawning its own CES.
+  if (isCesSiblingOptIn()) {
+    env.CES_STANDALONE = "1";
+    env.CES_LOCAL_SOCKET = resolveCesSocketPath(resources);
+  }
   applyIpcSocketDirOverride(env);
 }
 
@@ -717,6 +764,168 @@ function resolveGatewayDir(resources?: LocalInstanceResources): string {
   }
 }
 
+function resolveCesDir(resources?: LocalInstanceResources): string {
+  const runtimeCesDir = localRuntimeCesDir(resources);
+  if (runtimeCesDir) return runtimeCesDir;
+
+  // Source tree / npm sibling: cli/src/lib/ → ../../.. → credential-executor/
+  const sourceDir = join(
+    import.meta.dir,
+    "..",
+    "..",
+    "..",
+    "credential-executor",
+  );
+  if (isCesSourceDir(sourceDir)) {
+    return sourceDir;
+  }
+
+  // npm-installed elsewhere on disk: resolve via the package entry.
+  try {
+    const pkgPath = _require.resolve(
+      "@vellumai/credential-executor/package.json",
+    );
+    return dirname(pkgPath);
+  } catch {
+    throw new Error(
+      "credential-executor not found. Ensure @vellumai/credential-executor is installed or run from the source tree.",
+    );
+  }
+}
+
+/**
+ * Resolve the Unix socket path the CLI-launched CES sibling binds and the
+ * daemon connects to. Both sides read `CES_LOCAL_SOCKET`, which the CLI sets to
+ * this exact path so they agree. On macOS, long workspace paths are relocated
+ * to a short tmpdir override (the same one the IPC sockets use) to stay under
+ * the AF_UNIX path limit.
+ */
+function resolveCesSocketPath(resources?: LocalInstanceResources): string {
+  const workspaceDir = resources
+    ? join(resources.instanceDir, ".vellum", "workspace")
+    : join(homedir(), ".vellum", "workspace");
+  const override = computeIpcSocketDirOverride(workspaceDir);
+  const socketDir = override ?? workspaceDir;
+  mkdirSync(socketDir, { recursive: true });
+  return join(socketDir, "ces.sock");
+}
+
+/**
+ * Whether the CLI should launch CES as an independent sibling process instead
+ * of leaving the assistant to spawn it as an stdio child. Temporary opt-in
+ * (`CES_STANDALONE=1`) while local CES converges onto the sibling model that
+ * containerized homes already use.
+ */
+function isCesSiblingOptIn(): boolean {
+  return process.env.CES_STANDALONE === "1";
+}
+
+/**
+ * Launch the local CES sibling over a Unix socket (opted into via
+ * `CES_STANDALONE=1`). No-op unless the opt-in is set, in which case the
+ * assistant continues to spawn CES itself as today.
+ *
+ * The sibling runs with `CES_STANDALONE=1` so its lifecycle is anchored to
+ * SIGTERM rather than stdin EOF, mirroring the gateway: a CLI-owned process
+ * with a PID file under `.vellum/ces.pid`, started by `wake` and stopped by
+ * `sleep`.
+ */
+export async function startCes(
+  watch: boolean = false,
+  resources?: LocalInstanceResources,
+): Promise<void> {
+  if (!isCesSiblingOptIn()) return;
+
+  const vellumDir = resources
+    ? join(resources.instanceDir, ".vellum")
+    : join(homedir(), ".vellum");
+  const cesPidFile = join(vellumDir, "ces.pid");
+
+  // Kill any existing sibling first — a stale CES holds the socket and would
+  // corrupt the shared credential store if a second copy also bound it.
+  await stopProcessByPidFile(cesPidFile, "credential-executor");
+
+  console.log("🔐 Starting credential-executor sibling...");
+
+  const socketPath = resolveCesSocketPath(resources);
+  // A stale socket file from an unclean shutdown blocks re-bind; CES unlinks it
+  // on startup, but remove it here too so a leftover never masks a launch bug.
+  try {
+    unlinkSync(socketPath);
+  } catch {
+    /* no stale socket — fine */
+  }
+
+  const securityDir = resources
+    ? join(resources.instanceDir, ".vellum", "protected")
+    : join(homedir(), ".vellum", "protected");
+  const workspaceDir = resources
+    ? join(resources.instanceDir, ".vellum", "workspace")
+    : join(homedir(), ".vellum", "workspace");
+  mkdirSync(securityDir, { recursive: true });
+
+  const cesEnv: Record<string, string | undefined> = {
+    ...process.env,
+    CES_STANDALONE: "1",
+    CES_LOCAL_SOCKET: socketPath,
+    CREDENTIAL_SECURITY_DIR: securityDir,
+    VELLUM_WORKSPACE_DIR: workspaceDir,
+  };
+
+  let ces;
+  const runtimeCesDir = !watch ? localRuntimeCesDir(resources) : undefined;
+  const cesBinary = join(dirname(process.execPath), "credential-executor");
+  if (!runtimeCesDir && existsSync(cesBinary) && !watch) {
+    // Compiled binary alongside the CLI (desktop app / compiled CLI).
+    const cesLogFd = openLogFile("hatch.log");
+    ces = spawn(cesBinary, [], {
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: cesEnv,
+    });
+    pipeToLogFile(ces, cesLogFd, "credential-executor");
+  } else {
+    // Source tree / bunx: run the CES entry point via bun.
+    const cesDir = runtimeCesDir ?? resolveCesDir(resources);
+    const bunArgs = watch
+      ? ["--watch", "run", "src/main.ts"]
+      : ["run", "src/main.ts"];
+    const cesLogFd = openLogFile("hatch.log");
+    ces = spawn(resolveBunExecutable(), bunArgs, {
+      cwd: cesDir,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: envWithBunPath(cesEnv),
+    });
+    pipeToLogFile(ces, cesLogFd, "credential-executor");
+    if (watch) {
+      console.log("   credential-executor started in watch mode (bun --watch)");
+    }
+  }
+
+  ces.unref();
+
+  if (ces.pid) {
+    mkdirSync(vellumDir, { recursive: true });
+    writeFileSync(cesPidFile, String(ces.pid), "utf-8");
+  }
+
+  // Wait for the socket to appear so the daemon's discovery finds it on the
+  // first probe rather than burning its retry budget.
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    if (existsSync(socketPath)) break;
+    await new Promise((r) => setTimeout(r, 50));
+  }
+  if (!existsSync(socketPath)) {
+    console.warn(
+      "⚠ credential-executor started but its socket did not appear within 10s",
+    );
+  } else {
+    console.log("✅ credential-executor started\n");
+  }
+}
+
 /**
  * Check if the daemon is responsive by hitting its HTTP `/healthz` endpoint.
  * This replaces the socket-based `isSocketResponsive()` check.
@@ -1407,6 +1616,12 @@ export async function stopLocalProcesses(
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
 
+  // Stop the CES sibling if one was launched (CES_STANDALONE). No-op when the
+  // PID file is absent, so this is safe on the default topology where the
+  // assistant owns CES as an stdio child.
+  const cesPidFile = join(vellumDir, "ces.pid");
+  await stopProcessByPidFile(cesPidFile, "credential-executor");
+
   // Kill ngrok directly by PID rather than using stopProcessByPidFile, because
   // isVellumProcess() won't match the ngrok binary — resulting in a no-op that
   // leaves ngrok running. Verify the PID still belongs to ngrok before killing

package/src/lib/process.ts

@@ -15,7 +15,7 @@ export function isVellumProcess(pid: number): boolean {
       timeout: 3000,
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
-    return /vellum-daemon|vellum-cli|vellum-gateway|@vellumai|\/\.?vellum\/|\/daemon\/main|\/\.vellum\/.*qdrant\/bin\/qdrant/.test(
+    return /vellum-daemon|vellum-cli|vellum-gateway|credential-executor|@vellumai|\/\.?vellum\/|\/daemon\/main|\/\.vellum\/.*qdrant\/bin\/qdrant/.test(
       output,
     );
   } catch {

package/src/lib/retire-local.ts

@@ -66,6 +66,18 @@ export async function retireLocal(
   const gatewayPidFile = join(vellumDir, "gateway.pid");
   await stopProcessByPidFile(gatewayPidFile, "gateway", undefined, 7000);
 
+  // Stop the CES sibling if one was launched (CES_STANDALONE). No-op when the
+  // PID file is absent — on the default topology the assistant owns CES as an
+  // stdio child and it exits with the daemon.
+  const cesPidFile = join(vellumDir, "ces.pid");
+  const cesStopped = await stopProcessByPidFile(
+    cesPidFile,
+    "credential-executor",
+  );
+  if (cesStopped) {
+    reporter.log("credential-executor stopped.");
+  }
+
   // Stop Qdrant — the daemon's graceful shutdown tries to stop it via
   // qdrantManager.stop(), but if the daemon was SIGKILL'd (after 2s timeout)
   // Qdrant may still be running as an orphan. Check both the current PID file