@vellumai/cli 0.5.5 → 0.5.6

package/knip.json

@@ -2,7 +2,8 @@
   "entry": [
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
-    "src/adapters/openclaw-http-server.ts"
+    "src/adapters/openclaw-http-server.ts",
+    "src/lib/version-compat.ts"
   ],
   "project": ["src/**/*.ts", "src/**/*.tsx"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/health-check.test.ts

@@ -10,6 +10,7 @@ describe("checkHealth", () => {
   test("returns unreachable for non-existent host", async () => {
     const result = await checkHealth("http://127.0.0.1:1");
     expect(["unreachable", "timeout"]).toContain(result.status);
+    expect(result.version).toBeUndefined();
   });
 
   test("returns healthy for a mock healthy endpoint", async () => {
@@ -24,6 +25,24 @@ describe("checkHealth", () => {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("healthy");
       expect(result.detail).toBeNull();
+      expect(result.version).toBeUndefined();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns version when present in response", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json({ status: "healthy", version: "1.2.3" });
+      },
+    });
+
+    try {
+      const result = await checkHealth(`http://localhost:${server.port}`);
+      expect(result.status).toBe("healthy");
+      expect(result.version).toBe("1.2.3");
     } finally {
       server.stop(true);
     }
@@ -33,7 +52,11 @@ describe("checkHealth", () => {
     const server = Bun.serve({
       port: 0,
       fetch() {
-        return Response.json({ status: "degraded", message: "high latency" });
+        return Response.json({
+          status: "degraded",
+          message: "high latency",
+          version: "0.9.0",
+        });
       },
     });
 
@@ -41,6 +64,7 @@ describe("checkHealth", () => {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("degraded");
       expect(result.detail).toBe("high latency");
+      expect(result.version).toBe("0.9.0");
     } finally {
       server.stop(true);
     }
@@ -57,6 +81,7 @@ describe("checkHealth", () => {
     try {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("error (500)");
+      expect(result.version).toBeUndefined();
     } finally {
       server.stop(true);
     }

package/src/commands/ps.ts

@@ -4,6 +4,7 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  updateServiceGroupVersion,
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { loadGuardianToken } from "../lib/guardian-token";
@@ -424,7 +425,7 @@ async function listAllAssistants(): Promise<void> {
       // hitting the health endpoint. If the PID file is missing or the
       // process isn't running, the assistant is sleeping — skip the
       // network health check to avoid a misleading "unreachable" status.
-      let health: { status: string; detail: string | null };
+      let health: { status: string; detail: string | null; version?: string };
       const resources = a.resources;
       if (a.cloud === "local" && resources) {
         const pid = readPidFile(resources.pidFile);
@@ -451,6 +452,10 @@ async function listAllAssistants(): Promise<void> {
         health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
       }
 
+      if (health.status === "healthy" && health.version) {
+        updateServiceGroupVersion(a.assistantId, health.version);
+      }
+
       const infoParts = [a.runtimeUrl];
       if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
       if (a.species) infoParts.push(`species: ${a.species}`);

package/src/commands/restore.ts

@@ -89,28 +89,39 @@ interface PreflightFileEntry {
   action: string;
 }
 
+interface StructuredError {
+  code: string;
+  message: string;
+  path?: string;
+}
+
 interface PreflightResponse {
   can_import: boolean;
-  errors?: string[];
+  validation?: {
+    is_valid: false;
+    errors: StructuredError[];
+  };
   files?: PreflightFileEntry[];
   summary?: {
-    create: number;
-    overwrite: number;
-    unchanged: number;
-    total: number;
+    files_to_create: number;
+    files_to_overwrite: number;
+    files_unchanged: number;
+    total_files: number;
   };
-  conflicts?: string[];
+  conflicts?: StructuredError[];
 }
 
 interface ImportResponse {
   success: boolean;
   reason?: string;
-  errors?: string[];
+  errors?: StructuredError[];
+  message?: string;
   warnings?: string[];
   summary?: {
-    created: number;
-    overwritten: number;
-    skipped: number;
+    total_files: number;
+    files_created: number;
+    files_overwritten: number;
+    files_skipped: number;
     backups_created: number;
   };
 }
@@ -201,30 +212,38 @@ export async function restore(): Promise<void> {
     const result = (await response.json()) as PreflightResponse;
 
     if (!result.can_import) {
-      console.error("Import blocked by validation errors:");
-      for (const err of result.errors ?? []) {
-        console.error(`  - ${err}`);
+      if (result.validation?.errors?.length) {
+        console.error("Import blocked by validation errors:");
+        for (const err of result.validation.errors) {
+          console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
+        }
+      }
+      if (result.conflicts?.length) {
+        console.error("Import blocked by conflicts:");
+        for (const conflict of result.conflicts) {
+          console.error(`  - ${conflict.message}${conflict.path ? ` (${conflict.path})` : ""}`);
+        }
       }
       process.exit(1);
     }
 
     // Print summary table
     const summary = result.summary ?? {
-      create: 0,
-      overwrite: 0,
-      unchanged: 0,
-      total: 0,
+      files_to_create: 0,
+      files_to_overwrite: 0,
+      files_unchanged: 0,
+      total_files: 0,
     };
     console.log("Preflight analysis:");
-    console.log(`  Files to create:    ${summary.create}`);
-    console.log(`  Files to overwrite: ${summary.overwrite}`);
-    console.log(`  Files unchanged:    ${summary.unchanged}`);
-    console.log(`  Total:              ${summary.total}`);
+    console.log(`  Files to create:    ${summary.files_to_create}`);
+    console.log(`  Files to overwrite: ${summary.files_to_overwrite}`);
+    console.log(`  Files unchanged:    ${summary.files_unchanged}`);
+    console.log(`  Total:              ${summary.total_files}`);
     console.log("");
 
     const conflicts = result.conflicts ?? [];
     console.log(
-      `Conflicts: ${conflicts.length > 0 ? conflicts.join(", ") : "none"}`,
+      `Conflicts: ${conflicts.length > 0 ? conflicts.map((c) => c.message).join(", ") : "none"}`,
     );
 
     // List individual files with their action
@@ -276,25 +295,26 @@ export async function restore(): Promise<void> {
 
     if (!result.success) {
       console.error(
-        `Error: Import failed — ${result.reason ?? "unknown reason"}`,
+        `Error: Import failed — ${result.message ?? result.reason ?? "unknown reason"}`,
       );
       for (const err of result.errors ?? []) {
-        console.error(`  - ${err}`);
+        console.error(`  - ${err.message}${err.path ? ` (${err.path})` : ""}`);
       }
       process.exit(1);
     }
 
     // Print import report
     const summary = result.summary ?? {
-      created: 0,
-      overwritten: 0,
-      skipped: 0,
+      total_files: 0,
+      files_created: 0,
+      files_overwritten: 0,
+      files_skipped: 0,
       backups_created: 0,
     };
     console.log("✅ Restore complete.");
-    console.log(`  Files created:     ${summary.created}`);
-    console.log(`  Files overwritten: ${summary.overwritten}`);
-    console.log(`  Files skipped:     ${summary.skipped}`);
+    console.log(`  Files created:     ${summary.files_created}`);
+    console.log(`  Files overwritten: ${summary.files_overwritten}`);
+    console.log(`  Files skipped:     ${summary.files_skipped}`);
     console.log(`  Backups created:   ${summary.backups_created}`);
 
     // Print warnings if any

package/src/commands/rollback.ts

@@ -0,0 +1,280 @@
+import { randomBytes } from "crypto";
+
+import {
+  findAssistantByName,
+  getActiveAssistant,
+  loadAllAssistants,
+  saveAssistantEntry,
+} from "../lib/assistant-config";
+import type { AssistantEntry } from "../lib/assistant-config";
+import {
+  captureImageRefs,
+  clearSigningKeyBootstrapLock,
+  GATEWAY_INTERNAL_PORT,
+  dockerResourceNames,
+  migrateCesSecurityFiles,
+  migrateGatewaySecurityFiles,
+  startContainers,
+  stopContainers,
+} from "../lib/docker";
+import type { ServiceName } from "../lib/docker";
+import { loadBootstrapSecret } from "../lib/guardian-token";
+import {
+  broadcastUpgradeEvent,
+  captureContainerEnv,
+  waitForReady,
+} from "./upgrade";
+
+function parseArgs(): { name: string | null } {
+  const args = process.argv.slice(3);
+  let name: string | null = null;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log("Usage: vellum rollback [<name>]");
+      console.log("");
+      console.log("Roll back a Docker assistant to the previous version.");
+      console.log("");
+      console.log("Arguments:");
+      console.log(
+        "  <name>  Name of the assistant to roll back (default: active or only assistant)",
+      );
+      console.log("");
+      console.log("Examples:");
+      console.log(
+        "  vellum rollback                # Roll back the active assistant",
+      );
+      console.log(
+        "  vellum rollback my-assistant   # Roll back a specific assistant by name",
+      );
+      process.exit(0);
+    } else if (!arg.startsWith("-")) {
+      name = arg;
+    } else {
+      console.error(`Error: Unknown option '${arg}'.`);
+      process.exit(1);
+    }
+  }
+
+  return { name };
+}
+
+function resolveCloud(entry: AssistantEntry): string {
+  if (entry.cloud) {
+    return entry.cloud;
+  }
+  if (entry.project) {
+    return "gcp";
+  }
+  if (entry.sshUser) {
+    return "custom";
+  }
+  return "local";
+}
+
+/**
+ * Resolve which assistant to target for the rollback command. Priority:
+ * 1. Explicit name argument
+ * 2. Active assistant set via `vellum use`
+ * 3. Sole assistant (when exactly one exists)
+ */
+function resolveTargetAssistant(nameArg: string | null): AssistantEntry {
+  if (nameArg) {
+    const entry = findAssistantByName(nameArg);
+    if (!entry) {
+      console.error(`No assistant found with name '${nameArg}'.`);
+      process.exit(1);
+    }
+    return entry;
+  }
+
+  const active = getActiveAssistant();
+  if (active) {
+    const entry = findAssistantByName(active);
+    if (entry) return entry;
+  }
+
+  const all = loadAllAssistants();
+  if (all.length === 1) return all[0];
+
+  if (all.length === 0) {
+    console.error("No assistants found. Run 'vellum hatch' first.");
+  } else {
+    console.error(
+      "Multiple assistants found. Specify a name or set an active assistant with 'vellum use <name>'.",
+    );
+  }
+  process.exit(1);
+}
+
+export async function rollback(): Promise<void> {
+  const { name } = parseArgs();
+  const entry = resolveTargetAssistant(name);
+  const cloud = resolveCloud(entry);
+
+  // Only Docker assistants support rollback
+  if (cloud !== "docker") {
+    console.error(
+      "Rollback is only supported for Docker assistants. For managed assistants, use the version picker to upgrade to the previous version.",
+    );
+    process.exit(1);
+  }
+
+  // Verify rollback state exists
+  if (!entry.previousServiceGroupVersion || !entry.previousContainerInfo) {
+    console.error(
+      "No rollback state available. Run `vellum upgrade` first to create a rollback point.",
+    );
+    process.exit(1);
+  }
+
+  // Verify all three digest fields are present
+  const prev = entry.previousContainerInfo;
+  if (!prev.assistantDigest || !prev.gatewayDigest || !prev.cesDigest) {
+    console.error(
+      "Incomplete rollback state. Previous container digests are missing.",
+    );
+    process.exit(1);
+  }
+
+  // Build image refs from the previous digests
+  const previousImageRefs: Record<ServiceName, string> = {
+    assistant: prev.assistantDigest,
+    "credential-executor": prev.cesDigest,
+    gateway: prev.gatewayDigest,
+  };
+
+  const instanceName = entry.assistantId;
+  const res = dockerResourceNames(instanceName);
+
+  console.log(
+    `🔄 Rolling back Docker assistant '${instanceName}' to ${entry.previousServiceGroupVersion}...\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`,
+  );
+
+  // Extract CES_SERVICE_TOKEN from captured env, or generate fresh one
+  const cesServiceToken =
+    capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
+
+  // Retrieve or generate a bootstrap secret for the gateway.
+  const bootstrapSecret =
+    loadBootstrapSecret(instanceName) || randomBytes(32).toString("hex");
+
+  // Build extra env vars, excluding keys managed by serviceDockerRunArgs
+  const envKeysSetByRunArgs = new Set([
+    "CES_SERVICE_TOKEN",
+    "VELLUM_ASSISTANT_NAME",
+    "RUNTIME_HTTP_HOST",
+    "PATH",
+  ]);
+  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;
+    }
+  }
+
+  // Parse gateway port from entry's runtimeUrl, fall back to default
+  let gatewayPort = GATEWAY_INTERNAL_PORT;
+  try {
+    const parsed = new URL(entry.runtimeUrl);
+    const port = parseInt(parsed.port, 10);
+    if (!isNaN(port)) {
+      gatewayPort = port;
+    }
+  } catch {
+    // use default
+  }
+
+  // Notify connected clients that a rollback is about to begin (best-effort)
+  console.log("📢 Notifying connected clients...");
+  await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+    type: "starting",
+    targetVersion: entry.previousServiceGroupVersion,
+    expectedDowntimeSeconds: 60,
+  });
+  // Brief pause to allow SSE delivery before containers stop.
+  await new Promise((r) => setTimeout(r, 500));
+
+  console.log("🛑 Stopping existing containers...");
+  await stopContainers(res);
+  console.log("✅ Containers stopped\n");
+
+  // Run security file migrations and signing key cleanup
+  console.log("🔄 Migrating security files to gateway volume...");
+  await migrateGatewaySecurityFiles(res, (msg) => console.log(msg));
+
+  console.log("🔄 Migrating credential files to CES security volume...");
+  await migrateCesSecurityFiles(res, (msg) => console.log(msg));
+
+  console.log("🔑 Clearing signing key bootstrap lock...");
+  await clearSigningKeyBootstrapLock(res);
+
+  console.log("🚀 Starting containers with previous version...");
+  await startContainers(
+    {
+      bootstrapSecret,
+      cesServiceToken,
+      extraAssistantEnv,
+      gatewayPort,
+      imageTags: previousImageRefs,
+      instanceName,
+      res,
+    },
+    (msg) => console.log(msg),
+  );
+  console.log("✅ Containers started\n");
+
+  console.log("Waiting for assistant to become ready...");
+  const ready = await waitForReady(entry.runtimeUrl);
+
+  if (ready) {
+    // Capture new digests from the rolled-back containers
+    const newDigests = await captureImageRefs(res);
+
+    // Swap current/previous state to enable "rollback the rollback"
+    const updatedEntry: AssistantEntry = {
+      ...entry,
+      serviceGroupVersion: entry.previousServiceGroupVersion,
+      containerInfo: {
+        assistantImage: prev.assistantImage ?? previousImageRefs.assistant,
+        gatewayImage: prev.gatewayImage ?? previousImageRefs.gateway,
+        cesImage: prev.cesImage ?? previousImageRefs["credential-executor"],
+        assistantDigest: newDigests?.assistant,
+        gatewayDigest: newDigests?.gateway,
+        cesDigest: newDigests?.["credential-executor"],
+        networkName: res.network,
+      },
+      previousServiceGroupVersion: entry.serviceGroupVersion,
+      previousContainerInfo: entry.containerInfo,
+    };
+    saveAssistantEntry(updatedEntry);
+
+    // Notify clients that the rollback succeeded
+    await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+      type: "complete",
+      installedVersion: entry.previousServiceGroupVersion,
+      success: true,
+    });
+
+    console.log(
+      `\n✅ Docker assistant '${instanceName}' rolled back to ${entry.previousServiceGroupVersion}.`,
+    );
+  } else {
+    console.error(`\n❌ Containers failed to become ready within the timeout.`);
+    console.log(`   Check logs with: docker logs -f ${res.assistantContainer}`);
+    process.exit(1);
+  }
+}

package/src/commands/upgrade.ts

@@ -11,6 +11,7 @@ import {
 import type { AssistantEntry } from "../lib/assistant-config";
 import {
   captureImageRefs,
+  clearSigningKeyBootstrapLock,
   DOCKERHUB_IMAGES,
   DOCKER_READY_TIMEOUT_MS,
   GATEWAY_INTERNAL_PORT,
@@ -26,6 +27,7 @@ import {
   getPlatformUrl,
   readPlatformToken,
 } from "../lib/platform-client";
+import { loadBootstrapSecret, loadGuardianToken } from "../lib/guardian-token";
 import { exec, execOutput } from "../lib/step-runner";
 
 interface UpgradeArgs {
@@ -137,7 +139,7 @@ function resolveTargetAssistant(nameArg: string | null): AssistantEntry {
  * Capture environment variables from a running Docker container so they
  * can be replayed onto the replacement container after upgrade.
  */
-async function captureContainerEnv(
+export async function captureContainerEnv(
   containerName: string,
 ): Promise<Record<string, string>> {
   const captured: Record<string, string> = {};
@@ -165,7 +167,7 @@ async function captureContainerEnv(
  * Poll the gateway `/readyz` endpoint until it returns 200 or the timeout
  * elapses. Returns whether the assistant became ready.
  */
-async function waitForReady(runtimeUrl: string): Promise<boolean> {
+export async function waitForReady(runtimeUrl: string): Promise<boolean> {
   const readyUrl = `${runtimeUrl}/readyz`;
   const start = Date.now();
 
@@ -199,6 +201,35 @@ async function waitForReady(runtimeUrl: string): Promise<boolean> {
   return false;
 }
 
+/**
+ * Best-effort broadcast of an upgrade lifecycle event to connected clients
+ * via the gateway's upgrade-broadcast proxy. Uses guardian token auth.
+ * Failures are logged but never block the upgrade flow.
+ */
+export async function broadcastUpgradeEvent(
+  gatewayUrl: string,
+  assistantId: string,
+  event: Record<string, unknown>,
+): Promise<void> {
+  try {
+    const token = loadGuardianToken(assistantId);
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (token?.accessToken) {
+      headers["Authorization"] = `Bearer ${token.accessToken}`;
+    }
+    await fetch(`${gatewayUrl}/v1/admin/upgrade-broadcast`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(event),
+      signal: AbortSignal.timeout(3000),
+    });
+  } catch {
+    // Best-effort — gateway/daemon may already be shutting down or not yet ready
+  }
+}
+
 async function upgradeDocker(
   entry: AssistantEntry,
   version: string | null,
@@ -234,6 +265,18 @@ async function upgradeDocker(
     );
   }
 
+  // Persist rollback state to lockfile BEFORE any destructive changes.
+  // This enables the `vellum rollback` command to restore the previous version.
+  if (entry.serviceGroupVersion && entry.containerInfo) {
+    const rollbackEntry: AssistantEntry = {
+      ...entry,
+      previousServiceGroupVersion: entry.serviceGroupVersion,
+      previousContainerInfo: { ...entry.containerInfo },
+    };
+    saveAssistantEntry(rollbackEntry);
+    console.log(`   Saved rollback state: ${entry.serviceGroupVersion}\n`);
+  }
+
   console.log("💾 Capturing existing container environment...");
   const capturedEnv = await captureContainerEnv(res.assistantContainer);
   console.log(
@@ -246,6 +289,16 @@ async function upgradeDocker(
   await exec("docker", ["pull", imageTags["credential-executor"]]);
   console.log("✅ Docker images pulled\n");
 
+  // Notify connected clients that an upgrade is about to begin.
+  console.log("📢 Notifying connected clients...");
+  await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+    type: "starting",
+    targetVersion: versionTag,
+    expectedDowntimeSeconds: 60,
+  });
+  // Brief pause to allow SSE delivery before containers stop.
+  await new Promise((r) => setTimeout(r, 500));
+
   console.log("🛑 Stopping existing containers...");
   await stopContainers(res);
   console.log("✅ Containers stopped\n");
@@ -269,6 +322,11 @@ async function upgradeDocker(
   const cesServiceToken =
     capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
 
+  // Retrieve or generate a bootstrap secret for the gateway. The secret was
+  // persisted to disk during hatch; older instances won't have one yet.
+  const bootstrapSecret =
+    loadBootstrapSecret(instanceName) || randomBytes(32).toString("hex");
+
   // 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
   // serviceDockerRunArgs are excluded to avoid duplicates.
@@ -297,9 +355,13 @@ async function upgradeDocker(
   console.log("🔄 Migrating credential files to CES security volume...");
   await migrateCesSecurityFiles(res, (msg) => console.log(msg));
 
+  console.log("🔑 Clearing signing key bootstrap lock...");
+  await clearSigningKeyBootstrapLock(res);
+
   console.log("🚀 Starting upgraded containers...");
   await startContainers(
     {
+      bootstrapSecret,
       cesServiceToken,
       extraAssistantEnv,
       gatewayPort,
@@ -328,9 +390,18 @@ async function upgradeDocker(
         cesDigest: newDigests?.["credential-executor"],
         networkName: res.network,
       },
+      previousServiceGroupVersion: entry.serviceGroupVersion,
+      previousContainerInfo: entry.containerInfo,
     };
     saveAssistantEntry(updatedEntry);
 
+    // Notify clients on the new service group that the upgrade succeeded.
+    await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+      type: "complete",
+      installedVersion: versionTag,
+      success: true,
+    });
+
     console.log(
       `\n✅ Docker assistant '${instanceName}' upgraded to ${versionTag}.`,
     );
@@ -344,6 +415,7 @@ async function upgradeDocker(
 
         await startContainers(
           {
+            bootstrapSecret,
             cesServiceToken,
             extraAssistantEnv,
             gatewayPort,
@@ -356,19 +428,43 @@ async function upgradeDocker(
 
         const rollbackReady = await waitForReady(entry.runtimeUrl);
         if (rollbackReady) {
-          // Restore previous container info in lockfile after rollback
+          // Restore previous container info in lockfile after rollback.
+          // previousImageRefs contains sha256 digests from `docker inspect
+          // --format {{.Image}}`.  The *Image fields should hold
+          // human-readable image:tag names, so prefer the pre-upgrade
+          // containerInfo values and store digests in the *Digest fields.
           if (previousImageRefs) {
             const rolledBackEntry: AssistantEntry = {
               ...entry,
               containerInfo: {
-                assistantImage: previousImageRefs.assistant,
-                gatewayImage: previousImageRefs.gateway,
-                cesImage: previousImageRefs["credential-executor"],
+                assistantImage:
+                  entry.containerInfo?.assistantImage ??
+                  previousImageRefs.assistant,
+                gatewayImage:
+                  entry.containerInfo?.gatewayImage ??
+                  previousImageRefs.gateway,
+                cesImage:
+                  entry.containerInfo?.cesImage ??
+                  previousImageRefs["credential-executor"],
+                assistantDigest: previousImageRefs.assistant,
+                gatewayDigest: previousImageRefs.gateway,
+                cesDigest: previousImageRefs["credential-executor"],
                 networkName: res.network,
               },
+              previousServiceGroupVersion: undefined,
+              previousContainerInfo: undefined,
             };
             saveAssistantEntry(rolledBackEntry);
           }
+
+          // Notify clients that the upgrade failed and rolled back.
+          await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+            type: "complete",
+            installedVersion: entry.serviceGroupVersion ?? "unknown",
+            success: false,
+            rolledBackToVersion: entry.serviceGroupVersion,
+          });
+
           console.log(
             `\n⚠️  Rolled back to previous version. Upgrade to ${versionTag} failed.`,
           );
@@ -431,6 +527,15 @@ async function upgradePlatform(
     body.version = version;
   }
 
+  // Notify connected clients that an upgrade is about to begin.
+  const targetVersion = version ?? `v${cliPkg.version}`;
+  console.log("📢 Notifying connected clients...");
+  await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+    type: "starting",
+    targetVersion,
+    expectedDowntimeSeconds: 90,
+  });
+
   const response = await fetch(url, {
     method: "POST",
     headers: {
@@ -446,10 +551,23 @@ async function upgradePlatform(
     console.error(
       `Error: Platform upgrade failed (${response.status}): ${text}`,
     );
+    await broadcastUpgradeEvent(entry.runtimeUrl, entry.assistantId, {
+      type: "complete",
+      installedVersion: entry.serviceGroupVersion ?? "unknown",
+      success: false,
+    });
     process.exit(1);
   }
 
   const result = (await response.json()) as UpgradeApiResponse;
+
+  // NOTE: We intentionally do NOT broadcast a "complete" event here.
+  // The platform API returning 200 only means "upgrade request accepted" —
+  // the service group has not yet restarted with the new version.  The
+  // completion signal will come from the client's health-check
+  // version-change detection (DaemonConnection.swift) once the new
+  // version actually appears after the platform restarts the service group.
+
   console.log(`✅ ${result.detail}`);
   if (result.version) {
     console.log(`   Version: ${result.version}`);

package/src/commands/wake.ts

@@ -40,6 +40,14 @@ export async function wake(): Promise<void> {
   const entry = resolveTargetAssistant(nameArg);
 
   if (entry.cloud === "docker") {
+    if (watch || foreground) {
+      const ignored = [watch && "--watch", foreground && "--foreground"]
+        .filter(Boolean)
+        .join(" and ");
+      console.warn(
+        `Warning: ${ignored} ignored for Docker instances (not supported).`,
+      );
+    }
     const res = dockerResourceNames(entry.assistantId);
     await wakeContainers(res);
     console.log("Docker containers started.");

package/src/index.ts

@@ -11,6 +11,7 @@ import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
 import { restore } from "./commands/restore";
 import { retire } from "./commands/retire";
+import { rollback } from "./commands/rollback";
 import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
 import { ssh } from "./commands/ssh";
@@ -39,6 +40,7 @@ const commands = {
   recover,
   restore,
   retire,
+  rollback,
   setup,
   sleep,
   ssh,
@@ -68,6 +70,9 @@ function printHelp(): void {
   console.log("  recover  Restore a previously retired local assistant");
   console.log("  restore  Restore a .vbundle backup into a running assistant");
   console.log("  retire   Delete an assistant instance");
+  console.log(
+    "  rollback  Roll back a Docker assistant to the previous version",
+  );
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");
   console.log("  ssh      SSH into a remote assistant instance");

package/src/lib/assistant-config.ts

@@ -78,6 +78,10 @@ export interface AssistantEntry {
   serviceGroupVersion?: string;
   /** Docker image metadata for rollback. Only present for docker topology entries. */
   containerInfo?: ContainerInfo;
+  /** The service group version that was running before the last upgrade. */
+  previousServiceGroupVersion?: string;
+  /** Docker image metadata from before the last upgrade. Enables rollback to the prior version. */
+  previousContainerInfo?: ContainerInfo;
   [key: string]: unknown;
 }
 
@@ -360,6 +364,23 @@ export function saveAssistantEntry(entry: AssistantEntry): void {
   writeAssistants(entries);
 }
 
+/**
+ * Update just the serviceGroupVersion field on a lockfile entry.
+ * Reads the current entry, updates the version if changed, and writes back.
+ * No-op if the entry doesn't exist or the version hasn't changed.
+ */
+export function updateServiceGroupVersion(
+  assistantId: string,
+  version: string,
+): void {
+  const entries = readAssistants();
+  const entry = entries.find((e) => e.assistantId === assistantId);
+  if (!entry) return;
+  if (entry.serviceGroupVersion === version) return;
+  entry.serviceGroupVersion = version;
+  writeAssistants(entries);
+}
+
 /**
  * Scan upward from `basePort` to find an available port. A port is considered
  * available when `probePort()` returns false (nothing listening). Scans up to
@@ -426,6 +447,7 @@ export async function allocateLocalResources(
         entry.resources.daemonPort,
         entry.resources.gatewayPort,
         entry.resources.qdrantPort,
+        entry.resources.cesPort,
       );
     }
   }
@@ -445,13 +467,19 @@ export async function allocateLocalResources(
     daemonPort,
     gatewayPort,
   ]);
+  const cesPort = await findAvailablePort(DEFAULT_CES_PORT, [
+    ...reservedPorts,
+    daemonPort,
+    gatewayPort,
+    qdrantPort,
+  ]);
 
   return {
     instanceDir,
     daemonPort,
     gatewayPort,
     qdrantPort,
-    cesPort: DEFAULT_CES_PORT,
+    cesPort,
     pidFile: join(instanceDir, ".vellum", "vellum.pid"),
   };
 }

package/src/lib/docker.ts

@@ -14,7 +14,7 @@ import {
 import type { AssistantEntry } from "./assistant-config";
 import { DEFAULT_GATEWAY_PORT, PROVIDER_ENV_VAR_NAMES } from "./constants";
 import type { Species } from "./constants";
-import { leaseGuardianToken } from "./guardian-token";
+import { leaseGuardianToken, saveBootstrapSecret } from "./guardian-token";
 import { isVellumProcess, stopProcess } from "./process";
 import { generateInstanceName } from "./random-name";
 import { exec, execOutput } from "./step-runner";
@@ -464,6 +464,7 @@ async function buildAllImages(
  * can be restarted independently.
  */
 export function serviceDockerRunArgs(opts: {
+  bootstrapSecret?: string;
   cesServiceToken?: string;
   extraAssistantEnv?: Record<string, string>;
   gatewayPort: number;
@@ -552,6 +553,9 @@ export function serviceDockerRunArgs(opts: {
       ...(cesServiceToken
         ? ["-e", `CES_SERVICE_TOKEN=${cesServiceToken}`]
         : []),
+      ...(opts.bootstrapSecret
+        ? ["-e", `GUARDIAN_BOOTSTRAP_SECRET=${opts.bootstrapSecret}`]
+        : []),
       imageTags.gateway,
     ],
     "credential-executor": () => [
@@ -735,6 +739,7 @@ export const SERVICE_START_ORDER: ServiceName[] = [
 /** Start all three containers in dependency order. */
 export async function startContainers(
   opts: {
+    bootstrapSecret?: string;
     cesServiceToken?: string;
     extraAssistantEnv?: Record<string, string>;
     gatewayPort: number;
@@ -760,6 +765,27 @@ export async function stopContainers(
   await removeContainer(res.assistantContainer);
 }
 
+/**
+ * Remove the signing-key-bootstrap lockfile from the gateway security volume.
+ * This allows the daemon to re-fetch the signing key from the gateway on the
+ * next startup — necessary during upgrades where the gateway may generate a
+ * new key.
+ */
+export async function clearSigningKeyBootstrapLock(
+  res: ReturnType<typeof dockerResourceNames>,
+): Promise<void> {
+  await exec("docker", [
+    "run",
+    "--rm",
+    "-v",
+    `${res.gatewaySecurityVolume}:/gateway-security`,
+    "busybox",
+    "rm",
+    "-f",
+    "/gateway-security/signing-key-bootstrap.lock",
+  ]);
+}
+
 /** Stop containers without removing them (preserves state for `docker start`). */
 export async function sleepContainers(
   res: ReturnType<typeof dockerResourceNames>,
@@ -771,8 +797,14 @@ export async function sleepContainers(
   ]) {
     try {
       await exec("docker", ["stop", container]);
-    } catch {
-      // container may not exist or already stopped
+    } catch (err) {
+      const msg =
+        err instanceof Error ? err.message.toLowerCase() : String(err);
+      if (msg.includes("no such container") || msg.includes("is not running")) {
+        // container doesn't exist or already stopped — expected, skip
+        continue;
+      }
+      throw err;
     }
   }
 }
@@ -1071,9 +1103,36 @@ export async function hatchDocker(
     await exec("docker", ["volume", "create", res.cesSecurityVolume]);
     await exec("docker", ["volume", "create", res.gatewaySecurityVolume]);
 
+    // Set workspace volume ownership so non-root containers (UID 1001) can write.
+    await exec("docker", [
+      "run",
+      "--rm",
+      "-v",
+      `${res.workspaceVolume}:/workspace`,
+      "busybox",
+      "chown",
+      "1001:1001",
+      "/workspace",
+    ]);
+
+    // Clear any stale signing-key bootstrap lockfile so the daemon can
+    // fetch the key from the gateway on first startup.
+    await exec("docker", [
+      "run",
+      "--rm",
+      "-v",
+      `${res.gatewaySecurityVolume}:/gateway-security`,
+      "busybox",
+      "rm",
+      "-f",
+      "/gateway-security/signing-key-bootstrap.lock",
+    ]);
+
     const cesServiceToken = randomBytes(32).toString("hex");
+    const bootstrapSecret = randomBytes(32).toString("hex");
+    saveBootstrapSecret(instanceName, bootstrapSecret);
     await startContainers(
-      { cesServiceToken, gatewayPort, imageTags, instanceName, res },
+      { bootstrapSecret, cesServiceToken, gatewayPort, imageTags, instanceName, res },
       log,
     );
 
@@ -1252,7 +1311,9 @@ async function waitForGatewayAndLease(opts: {
       // Log periodically so the user knows we're still trying
       const elapsed = ((Date.now() - leaseStart) / 1000).toFixed(0);
       log(
-        `Guardian token lease: attempt failed after ${elapsed}s (${lastLeaseError.split("\n")[0]}), retrying...`,
+        `Guardian token lease: attempt failed after ${elapsed}s (${
+          lastLeaseError.split("\n")[0]
+        }), retrying...`,
       );
     }
     await new Promise((r) => setTimeout(r, 2000));
@@ -1260,7 +1321,10 @@ async function waitForGatewayAndLease(opts: {
 
   if (!leaseSuccess) {
     log(
-      `\u26a0\ufe0f  Guardian token lease: FAILED after ${((Date.now() - leaseStart) / 1000).toFixed(1)}s — ${lastLeaseError ?? "unknown error"}`,
+      `\u26a0\ufe0f  Guardian token lease: FAILED after ${(
+        (Date.now() - leaseStart) /
+        1000
+      ).toFixed(1)}s — ${lastLeaseError ?? "unknown error"}`,
     );
   }
 

package/src/lib/guardian-token.ts

@@ -42,6 +42,46 @@ function getPersistedDeviceIdPath(): string {
   return join(getXdgConfigHome(), "vellum", "device-id");
 }
 
+function getBootstrapSecretPath(assistantId: string): string {
+  return join(
+    getXdgConfigHome(),
+    "vellum",
+    "assistants",
+    assistantId,
+    "bootstrap-secret",
+  );
+}
+
+/**
+ * Load a previously saved bootstrap secret for the given assistant.
+ * Returns null if the file does not exist or is unreadable.
+ */
+export function loadBootstrapSecret(assistantId: string): string | null {
+  try {
+    const raw = readFileSync(getBootstrapSecretPath(assistantId), "utf-8").trim();
+    return raw.length > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist a bootstrap secret for the given assistant so that the desktop
+ * client and upgrade/rollback paths can retrieve it later.
+ */
+export function saveBootstrapSecret(
+  assistantId: string,
+  secret: string,
+): void {
+  const path = getBootstrapSecretPath(assistantId);
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(path, secret + "\n", { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
 function hashWithSalt(input: string): string {
   return createHash("sha256")
     .update(input + DEVICE_ID_SALT)
@@ -168,9 +208,14 @@ export async function leaseGuardianToken(
   assistantId: string,
 ): Promise<GuardianTokenData> {
   const deviceId = computeDeviceId();
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  const bootstrapSecret = loadBootstrapSecret(assistantId);
+  if (bootstrapSecret) {
+    headers["x-bootstrap-secret"] = bootstrapSecret;
+  }
   const response = await fetch(`${gatewayUrl}/v1/guardian/init`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers,
     body: JSON.stringify({ platform: "cli", deviceId }),
   });
 

package/src/lib/health-check.ts

@@ -3,11 +3,13 @@ export const HEALTH_CHECK_TIMEOUT_MS = 1500;
 interface HealthResponse {
   status: string;
   message?: string;
+  version?: string;
 }
 
 export interface HealthCheckResult {
   status: string;
   detail: string | null;
+  version?: string;
 }
 
 export async function checkManagedHealth(
@@ -63,6 +65,7 @@ export async function checkManagedHealth(
     return {
       status,
       detail: status !== "healthy" ? (data.message ?? null) : null,
+      version: data.version,
     };
   } catch (error) {
     const status =
@@ -108,6 +111,7 @@ export async function checkHealth(
     return {
       status,
       detail: status !== "healthy" ? (data.message ?? null) : null,
+      version: data.version,
     };
   } catch (error) {
     const status =

package/src/lib/platform-client.ts

@@ -60,14 +60,15 @@ interface OrganizationListResponse {
 }
 
 export async function fetchOrganizationId(token: string): Promise<string> {
-  const url = `${getPlatformUrl()}/v1/organizations/`;
+  const platformUrl = getPlatformUrl();
+  const url = `${platformUrl}/v1/organizations/`;
   const response = await fetch(url, {
     headers: { "X-Session-Token": token },
   });
 
   if (!response.ok) {
     throw new Error(
-      `Failed to fetch organizations (${response.status}). Try logging in again.`,
+      `Failed to fetch organizations from ${platformUrl} (${response.status}). Try logging in again.`,
     );
   }
 

package/src/lib/version-compat.ts

@@ -0,0 +1,45 @@
+/**
+ * Parse a version string into { major, minor, patch } components.
+ * Handles optional `v` prefix (e.g., "v1.2.3" or "1.2.3").
+ * Returns null if the string cannot be parsed as semver.
+ */
+export function parseVersion(
+  version: string,
+): { major: number; minor: number; patch: number } | null {
+  const stripped = version.replace(/^[vV]/, "");
+  const segments = stripped.split(".");
+
+  if (segments.length < 2) {
+    return null;
+  }
+
+  const major = parseInt(segments[0], 10);
+  const minor = parseInt(segments[1], 10);
+  const patch = segments.length >= 3 ? parseInt(segments[2], 10) : 0;
+
+  if (isNaN(major) || isNaN(minor) || isNaN(patch)) {
+    return null;
+  }
+
+  return { major, minor, patch };
+}
+
+/**
+ * Check whether two version strings are compatible.
+ * Compatibility requires matching major AND minor versions.
+ * Patch differences are allowed.
+ * Returns false if either version cannot be parsed.
+ */
+export function isVersionCompatible(
+  clientVersion: string,
+  serviceGroupVersion: string,
+): boolean {
+  const a = parseVersion(clientVersion);
+  const b = parseVersion(serviceGroupVersion);
+
+  if (a === null || b === null) {
+    return false;
+  }
+
+  return a.major === b.major && a.minor === b.minor;
+}