@vellumai/cli 0.7.3 → 0.8.1

package/src/commands/client.ts

@@ -1,4 +1,6 @@
-import { hostname } from "os";
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import path from "node:path";
 
 import {
   findAssistantByName,
@@ -14,6 +16,7 @@ import { loadGuardianToken } from "../lib/guardian-token";
 import { getLocalLanIPv4 } from "../lib/local";
 import {
   CLI_INTERFACE_ID,
+  WEB_INTERFACE_ID,
   getClientRegistrationHeaders,
 } from "../lib/client-identity";
 import {
@@ -22,7 +25,7 @@ import {
 } from "../lib/platform-client";
 import { tuiLog } from "../lib/tui-log";
 
-const SUPPORTED_INTERFACES = ["cli"] as const;
+const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
 
 const ANSI = {
@@ -133,12 +136,6 @@ function parseArgs(): ParsedArgs {
       assistantId = flagArgs[++i];
     } else if ((flag === "--interface" || flag === "-i") && flagArgs[i + 1]) {
       const value = flagArgs[++i];
-      if (value === "web") {
-        console.error(
-          `--interface web is not yet supported. Coming soon.`,
-        );
-        process.exit(1);
-      }
       if (!(SUPPORTED_INTERFACES as readonly string[]).includes(value)) {
         console.error(
           `Unknown interface '${value}'. Supported: ${SUPPORTED_INTERFACES.join(", ")}.`,
@@ -213,7 +210,7 @@ ${ANSI.bold}ARGUMENTS:${ANSI.reset}
 ${ANSI.bold}OPTIONS:${ANSI.reset}
     -u, --url <url>            Runtime URL
     -a, --assistant-id <id>    Assistant ID
-    -i, --interface <id>       Interface identifier (default: cli)
+    -i, --interface <id>       Interface identifier: cli (default) or web
     -h, --help                 Show this help message
 
 ${ANSI.bold}DEFAULTS:${ANSI.reset}
@@ -228,6 +225,66 @@ ${ANSI.bold}EXAMPLES:${ANSI.reset}
 `);
 }
 
+/**
+ * Walk up from this file's location to find a sibling `clients/web` package.
+ *
+ * Returns the absolute path to its directory, or null when not found —
+ * e.g. when the CLI is installed via npm/bunx, where the `clients/web`
+ * source isn't shipped alongside `@vellumai/cli`. For now we treat the
+ * `--interface web` path as source-checkout-only.
+ */
+function findClientsWebDir(): string | null {
+  let dir = import.meta.dir;
+  for (let depth = 0; depth < 8; depth++) {
+    const candidate = path.join(dir, "clients", "web", "package.json");
+    if (existsSync(candidate)) {
+      return path.dirname(candidate);
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Spawn the `clients/web` package's `local` script and proxy its lifecycle.
+ *
+ * The web client is deliberately not declared as a dependency of `@vellumai/cli`:
+ * the CLI is published, the web package is not. Locating it on disk and
+ * shelling out keeps the two packages independent.
+ */
+async function runWebInterface(): Promise<void> {
+  const webDir = findClientsWebDir();
+  if (!webDir) {
+    console.error(
+      `${ANSI.bold}--interface web${ANSI.reset}: unable to locate ` +
+        `clients/web. This interface currently requires running ` +
+        `vellum from a source checkout of vellum-assistant.`,
+    );
+    process.exit(1);
+  }
+
+  const child = Bun.spawn({
+    cmd: ["bun", "run", "local"],
+    cwd: webDir,
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+
+  const forward = (signal: "SIGINT" | "SIGTERM"): void => {
+    try {
+      child.kill(signal);
+    } catch {
+      // Child already exited; nothing to forward.
+    }
+  };
+  process.on("SIGINT", () => forward("SIGINT"));
+  process.on("SIGTERM", () => forward("SIGTERM"));
+
+  const exitCode = await child.exited;
+  process.exit(typeof exitCode === "number" ? exitCode : 0);
+}
+
 export async function client(): Promise<void> {
   const {
     runtimeUrl,
@@ -241,6 +298,11 @@ export async function client(): Promise<void> {
     zone,
   } = parseArgs();
 
+  if (interfaceId === WEB_INTERFACE_ID) {
+    await runWebInterface();
+    return;
+  }
+
   tuiLog.init();
   tuiLog.info("session start", {
     runtimeUrl,

package/src/commands/events.ts

@@ -49,13 +49,14 @@ interface AssistantEvent {
     content?: string;
     message?: string;
     chunk?: string;
+    tags?: unknown;
     conversationId?: string;
     [key: string]: unknown;
   };
 }
 
 /** Render an event as human-readable markdown to stdout. */
-function renderMarkdown(event: AssistantEvent): void {
+export function renderMarkdown(event: AssistantEvent): void {
   const msg = event.message;
   switch (msg.type) {
     case "assistant_text_delta":
@@ -94,6 +95,17 @@ function renderMarkdown(event: AssistantEvent): void {
     case "user_message_echo":
       console.log(`\n**You:** ${msg.text}`);
       break;
+    case "sync_changed": {
+      const tags = Array.isArray(msg.tags)
+        ? msg.tags.filter((tag): tag is string => typeof tag === "string")
+        : [];
+      const renderedTags =
+        tags.length > 0
+          ? tags.map((tag) => `\`${tag}\``).join(", ")
+          : "(no tags)";
+      console.log(`\n> **Sync changed:** ${renderedTags}`);
+      break;
+    }
     default:
       // Silently skip events that don't have a markdown representation
       // (e.g. heartbeat comments, activity states, etc.)

package/src/commands/login.ts

@@ -287,9 +287,10 @@ export async function login(): Promise<void> {
 
     // Sync cloud assistants from the platform into the local lockfile.
     // This ensures `vellum ps` shows managed assistants immediately
-    // after login (e.g. after a retire-and-rehatch cycle).
+    // after login (e.g. after a retire-and-rehatch cycle). We've just
+    // saved this token, so it's guaranteed non-empty here.
     try {
-      const result = await syncCloudAssistants();
+      const result = await syncCloudAssistants(token);
       if (result) {
         const total = result.added + result.removed;
         if (total > 0) {

package/src/commands/ps.ts

@@ -15,6 +15,7 @@ import {
   fetchManagedPs,
   type ManagedProcessEntry,
 } from "../lib/health-check";
+import { readPlatformToken } from "../lib/platform-client";
 import { dockerResourceNames } from "../lib/docker";
 import { existsSync } from "fs";
 import {
@@ -472,7 +473,7 @@ async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
 
 // ── List all assistants (no arg) ────────────────────────────────
 
-async function listAllAssistants(verbose: boolean): Promise<void> {
+export async function listAllAssistants(verbose: boolean): Promise<void> {
   const { name: envName, source: envSource } = resolveEnvironmentSource();
   const sourceLabels: Record<typeof envSource, string> = {
     flag: "--environment flag",
@@ -486,23 +487,33 @@ async function listAllAssistants(verbose: boolean): Promise<void> {
     ? (msg) => console.log(`  [verbose] ${msg}`)
     : undefined;
 
-  // Refresh cloud assistants from the platform before listing.
-  const syncResult = await syncCloudAssistants({ log });
-
-  // Show platform login status
-  if (syncResult) {
-    const parts = [`Platform: logged in`];
-    if (syncResult.email) parts[0] += ` as ${syncResult.email}`;
-    if (syncResult.added > 0 || syncResult.removed > 0) {
-      const changes: string[] = [];
-      if (syncResult.added > 0) changes.push(`${syncResult.added} added`);
-      if (syncResult.removed > 0)
-        changes.push(`${syncResult.removed} removed`);
-      parts.push(`(${changes.join(", ")})`);
-    }
-    console.log(parts.join(" "));
-  } else {
+  // Decide platform login status FIRST, before touching the network. With no
+  // local token we never enter the platform fetch path — so unreachable-host
+  // errors from the org-ID/user lookups can't leak onto stderr ahead of the
+  // "Platform: not logged in" line.
+  const platformToken = readPlatformToken();
+  if (!platformToken) {
+    log?.("No platform token found — skipping cloud sync");
     console.log("Platform: not logged in");
+  } else {
+    const syncResult = await syncCloudAssistants(platformToken, { log });
+    if (syncResult) {
+      const parts = [`Platform: logged in`];
+      if (syncResult.email) parts[0] += ` as ${syncResult.email}`;
+      if (syncResult.added > 0 || syncResult.removed > 0) {
+        const changes: string[] = [];
+        if (syncResult.added > 0) changes.push(`${syncResult.added} added`);
+        if (syncResult.removed > 0)
+          changes.push(`${syncResult.removed} removed`);
+        parts.push(`(${changes.join(", ")})`);
+      }
+      console.log(parts.join(" "));
+    } else {
+      // We had a token but the platform fetch failed (offline, expired, etc.).
+      // Treat it the same as "not logged in" from a UX perspective — the user
+      // can't reach cloud-managed assistants right now either way.
+      console.log("Platform: not logged in");
+    }
   }
   console.log("");
 

package/src/components/DefaultMainScreen.tsx

@@ -333,6 +333,8 @@ interface SseEvent {
   allowedDomains?: string[];
   // message_complete fields
   source?: "main" | "aux";
+  // sync_changed fields
+  tags?: string[];
   [key: string]: unknown;
 }
 
@@ -1856,6 +1858,11 @@ function ChatApp({
                 hRef.setBusy(false);
                 break;
 
+              case "sync_changed":
+                // The interactive CLI does not currently keep any sync-tagged
+                // caches, so generic invalidations are intentionally ignored.
+                break;
+
               default:
                 // Ignore events we don't handle (activity state, traces, etc.)
                 break;
@@ -2265,15 +2272,7 @@ function ChatApp({
       // racing with SSE events that may arrive during the sendMessage await.
       h.showSpinner("Working...");
     },
-    [
-      runtimeUrl,
-      assistantId,
-      auth,
-      project,
-      zone,
-      cleanup,
-      ensureConnected,
-    ],
+    [runtimeUrl, assistantId, auth, project, zone, cleanup, ensureConnected],
   );
 
   const handleSubmit = useCallback(

package/src/lib/__tests__/docker.test.ts

@@ -128,6 +128,17 @@ describe("buildServiceRunArgs — gateway", () => {
       buildGatewayArgs().some((arg) => arg.startsWith("VELAY_BASE_URL=")),
     ).toBe(false);
   });
+
+  test("forces gateway to run as uid 0 so it can connect to the assistant's root-owned IPC socket (mirrors K8s securityContext.runAsUser=0)", () => {
+    const args = buildGatewayArgs();
+    const userIdx = args.indexOf("--user");
+    expect(userIdx).toBeGreaterThan(-1);
+    expect(args[userIdx + 1]).toBe("0");
+  });
+
+  test("assistant container does NOT get a --user override (image USER root wins)", () => {
+    expect(buildAssistantArgs().includes("--user")).toBe(false);
+  });
 });
 
 describe("VELLUM_AVATAR_DEVICE passthrough", () => {

package/src/lib/assistant-config.ts

@@ -18,6 +18,8 @@ import {
   getMultiInstanceDir,
 } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
+import { SEEDS } from "./environments/seeds.js";
+import type { EnvironmentDefinition } from "./environments/types.js";
 import { probePort } from "./port-probe.js";
 
 /**
@@ -327,6 +329,69 @@ export function loadAllAssistants(): AssistantEntry[] {
   return readAssistants();
 }
 
+/**
+ * Read the first existing lockfile for an explicitly-provided environment,
+ * without applying legacy migrations. This is the cross-env read path used by
+ * {@link loadAllAssistantsAcrossEnvs}: it deliberately bypasses
+ * {@link readLockfile} (which always resolves the *current* env) so callers
+ * can enumerate state from every env without flipping `process.env` or the
+ * persisted default. Migrations are skipped because we never want to write
+ * to another env's lockfile from the current env's process.
+ */
+function readLockfileForEnv(env: EnvironmentDefinition): LockfileData {
+  for (const lockfilePath of getLockfilePaths(env)) {
+    if (!existsSync(lockfilePath)) continue;
+    try {
+      const raw = readFileSync(lockfilePath, "utf-8");
+      const parsed = JSON.parse(raw) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as LockfileData;
+      }
+    } catch {
+      // Malformed; try next candidate
+    }
+  }
+  return {};
+}
+
+/**
+ * Load assistant entries from every known environment's lockfile.
+ *
+ * Each {@link SEEDS} entry has its own on-host data layout (config dir,
+ * lockfile path, data dir). A running assistant from `dev` is invisible to
+ * `loadAllAssistants()` when the current env is `local`, but its host
+ * processes (daemon/gateway/qdrant) still show up in `ps ax`. The orphan
+ * detector and `vellum clean` need the union of all envs' entries to avoid
+ * misclassifying — or worse, killing — another env's running services.
+ *
+ * Optional `envs` override is provided for testability so call sites can
+ * inject a curated env list with `lockfileDirOverride` set, without having
+ * to manipulate the global SEEDS table or process.env.
+ */
+export function loadAllAssistantsAcrossEnvs(
+  envs?: EnvironmentDefinition[],
+): AssistantEntry[] {
+  const envList = envs ?? Object.values(SEEDS).map((env) => ({ ...env }));
+  const all: AssistantEntry[] = [];
+  for (const env of envList) {
+    const data = readLockfileForEnv(env);
+    const entries = data.assistants;
+    if (!Array.isArray(entries)) continue;
+    for (const raw of entries) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+      const entry = raw as AssistantEntry;
+      if (
+        typeof entry.assistantId !== "string" ||
+        typeof entry.runtimeUrl !== "string"
+      ) {
+        continue;
+      }
+      all.push(entry);
+    }
+  }
+  return all;
+}
+
 export function getActiveAssistant(): string | null {
   const data = readLockfile();
   return data.activeAssistant ?? null;

package/src/lib/client-identity.ts

@@ -12,6 +12,7 @@ import { homedir } from "os";
 import { join } from "path";
 
 export const CLI_INTERFACE_ID = "cli";
+export const WEB_INTERFACE_ID = "web";
 
 let cached: string | null = null;
 

package/src/lib/local.ts

@@ -840,6 +840,42 @@ export function isGatewayWatchModeAvailable(): boolean {
   }
 }
 
+/**
+ * Write (or overwrite) a shell wrapper at `<workspace>/bin/assistant` that
+ * pre-injects the three instance-specific env vars before exec-ing the real
+ * assistant binary from the app bundle.
+ *
+ * This lets developers invoke `<workspace>/bin/assistant <command>` directly
+ * from the terminal without manually setting env vars.  Only created when a
+ * compiled `assistant` binary is present adjacent to the CLI executable (i.e.
+ * inside a desktop app bundle) — a no-op in source/watch mode.
+ *
+ * The wrapper is idempotent: safe to call on every daemon wake.
+ */
+function writeAssistantWrapper(resources: LocalInstanceResources): void {
+  const assistantBinary = join(dirname(process.execPath), "assistant");
+  if (!existsSync(assistantBinary)) return;
+
+  const workspaceDir = join(resources.instanceDir, ".vellum", "workspace");
+  const protectedDir = join(resources.instanceDir, ".vellum", "protected");
+  const binDir = join(workspaceDir, "bin");
+
+  mkdirSync(binDir, { recursive: true });
+  const wrapperPath = join(binDir, "assistant");
+  writeFileSync(
+    wrapperPath,
+    [
+      "#!/bin/sh",
+      `export VELLUM_WORKSPACE_DIR="${workspaceDir}"`,
+      `export CREDENTIAL_SECURITY_DIR="${protectedDir}"`,
+      `export GATEWAY_SECURITY_DIR="${protectedDir}"`,
+      `exec "${assistantBinary}" "$@"`,
+      "",
+    ].join("\n"),
+    { mode: 0o755 },
+  );
+}
+
 // NOTE: startLocalDaemon() is the CLI-side daemon lifecycle manager.
 // It should eventually converge with
 // assistant/src/daemon/daemon-control.ts::startDaemon which is the
@@ -850,6 +886,7 @@ export async function startLocalDaemon(
   options?: DaemonStartOptions,
 ): Promise<void> {
   warnIfLegacyWorkspaceFallbackDetected(resources);
+  writeAssistantWrapper(resources);
 
   const foreground = options?.foreground ?? false;
   // Check for a compiled daemon binary adjacent to the CLI executable.

package/src/lib/orphan-detection.ts

@@ -1,5 +1,11 @@
 import { existsSync, readFileSync } from "fs";
+import { join } from "path";
 
+import {
+  getDaemonPidPath,
+  loadAllAssistantsAcrossEnvs,
+  type AssistantEntry,
+} from "./assistant-config.js";
 import { execOutput } from "./step-runner";
 
 export interface RemoteProcess {
@@ -67,10 +73,68 @@ export interface OrphanedProcess {
   source: string;
 }
 
-export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
+/**
+ * Collect PIDs that belong to a known assistant in any environment.
+ *
+ * For local entries this reads the daemon/gateway/qdrant/embed-worker PID
+ * files under each entry's `instanceDir`. For docker entries we include the
+ * `watcherPid` field when present (the file watcher runs as a host process,
+ * unlike the containers themselves). Other cloud topologies don't have
+ * host-side processes that show up in `ps ax`.
+ *
+ * This set is the basis for filtering the orphan list: if a running process
+ * matches a recorded PID for *any* env's assistant, it's not an orphan.
+ */
+export function getKnownPidsFromAssistants(
+  entries: AssistantEntry[],
+): Set<string> {
+  const pids = new Set<string>();
+  for (const entry of entries) {
+    if (entry.cloud === "local" && entry.resources) {
+      const vellumDir = join(entry.resources.instanceDir, ".vellum");
+      const candidates = [
+        getDaemonPidPath(entry.resources),
+        join(vellumDir, "gateway.pid"),
+        join(vellumDir, "workspace", "data", "qdrant", "qdrant.pid"),
+        join(vellumDir, "workspace", "embed-worker.pid"),
+      ];
+      for (const file of candidates) {
+        const pid = readPidFile(file);
+        if (pid) pids.add(pid);
+      }
+    }
+    if (typeof entry.watcherPid === "number") {
+      pids.add(String(entry.watcherPid));
+    }
+  }
+  return pids;
+}
+
+export interface DetectOrphansOptions {
+  /**
+   * Set of PIDs to treat as known and exclude from the orphan list. When
+   * omitted, defaults to the union of every env's recorded assistant PIDs
+   * via {@link loadAllAssistantsAcrossEnvs} +
+   * {@link getKnownPidsFromAssistants}. Tests can inject an explicit set to
+   * avoid touching the real on-host lockfiles.
+   */
+  excludePids?: Set<string>;
+}
+
+export async function detectOrphanedProcesses(
+  options: DetectOrphansOptions = {},
+): Promise<OrphanedProcess[]> {
   const results: OrphanedProcess[] = [];
   const seenPids = new Set<string>();
 
+  // PIDs that belong to a known assistant in *any* environment are not
+  // orphans. Without this filter, running `vellum ps` from an env that has
+  // no assistants — or `vellum clean` from any env — would flag (or kill)
+  // another env's healthy services as orphans.
+  const knownPids =
+    options.excludePids ??
+    getKnownPidsFromAssistants(loadAllAssistantsAcrossEnvs());
+
   // Process table scan — discover orphaned processes by scanning the OS
   // process table rather than reading PID files from the workspace.
   try {
@@ -83,6 +147,7 @@ export async function detectOrphanedProcesses(): Promise<OrphanedProcess[]> {
 
     for (const p of procs) {
       if (p.pid === ownPid || seenPids.has(p.pid)) continue;
+      if (knownPids.has(p.pid)) continue;
       const type = classifyProcess(p.command);
       if (type === "unknown") continue;
       results.push({ name: type, pid: p.pid, source: "process table" });

package/src/lib/platform-client.ts

@@ -129,9 +129,12 @@ export function invalidateOrgIdCache(
  * The org ID is cached per (token, platformUrl) for 60 seconds to avoid
  * redundant HTTP requests in tight polling loops.
  *
- * Auth errors (401 / 403) from the org-ID fetch are logged with a
- * user-friendly message before re-throwing, so callers don't need to
- * repeat that logic.
+ * Auth errors (401 / 403) from the org-ID fetch are wrapped in a
+ * user-friendly Error message before re-throwing, so callers can surface
+ * a useful message without doing their own classification. Callers that
+ * handle the throw (e.g. `syncCloudAssistants`) stay silent on stderr;
+ * callers that let it bubble get a single clean line from the top-level
+ * runner.
  */
 export async function authHeaders(
   token: string,
@@ -163,11 +166,9 @@ export async function authHeaders(
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("401") || msg.includes("403")) {
-      console.error("Authentication failed. Run 'vellum login' to refresh.");
-    } else {
-      console.error(`Failed to fetch organization: ${msg}`);
+      throw new Error("Authentication failed. Run 'vellum login' to refresh.");
     }
-    throw err;
+    throw new Error(`Failed to fetch organization: ${msg}`);
   }
 }
 

package/src/lib/statefulset.ts

@@ -99,6 +99,11 @@ export interface DockerContainerSpec {
   ports?: PortSpec[];
   env: EnvEntry[];
   volumeMounts: VolumeMount[];
+  /**
+   * Optional `--user` override for `docker run`. Mirrors K8s
+   * `securityContext.runAsUser`. Omitted ⇒ image's `USER` directive wins.
+   */
+  user?: string;
 }
 
 export interface DockerVolumeClaimTemplate {
@@ -168,6 +173,7 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
         { kind: "static", name: "DEBUG_STDOUT_LOGS",         value: "1" },
         { kind: "static", name: "VELLUM_CLOUD",              value: "docker" },
         { kind: "static", name: "RUNTIME_HTTP_HOST",         value: "0.0.0.0" },
+        { kind: "static", name: "RUNTIME_HTTP_PORT",         value: `${ASSISTANT_INTERNAL_PORT}` },
         { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
         { kind: "static", name: "VELLUM_BACKUP_DIR",         value: "/workspace/.backups" },
         { kind: "static", name: "VELLUM_BACKUP_KEY_PATH",    value: "/workspace/.backup.key" },
@@ -196,6 +202,7 @@ export const DOCKER_STATEFUL_SET_SPEC: DockerStatefulSetSpec = {
       name: "gateway-sidecar",
       internalName: "gateway",
       network: "container",
+      user: "0",
       env: [
         { kind: "static", name: "VELLUM_WORKSPACE_DIR",      value: "/workspace" },
         { kind: "static", name: "GATEWAY_SECURITY_DIR",      value: "/gateway-security" },
@@ -300,6 +307,11 @@ export function buildServiceRunArgs(
             : res.cesContainer;
       args.push("--name", containerName);
 
+      // User override (mirrors K8s securityContext.runAsUser)
+      if (container.user !== undefined) {
+        args.push("--user", container.user);
+      }
+
       // Network
       if (container.network === "bridge") {
         args.push(`--network=${res.network}`);

package/src/lib/sync-cloud-assistants.ts

@@ -6,6 +6,11 @@
  *   (e.g. retired assistants).
  *
  * Used by both `vellum login` and `vellum ps` to keep the lockfile fresh.
+ *
+ * **Contract:** callers must verify the user is logged in (i.e. a non-empty
+ * platform token exists) before invoking this helper. The "is there a token?"
+ * decision belongs at the command level so commands can render the right
+ * "Platform: …" status without ever entering the platform fetch path.
  */
 
 import {
@@ -17,7 +22,6 @@ import {
   fetchCurrentUser,
   fetchPlatformAssistants,
   getPlatformUrl,
-  readPlatformToken,
 } from "./platform-client.js";
 
 export type SyncLogger = (message: string) => void;
@@ -34,21 +38,24 @@ export interface SyncOptions {
 
 /**
  * Fetch platform assistants and reconcile against the lockfile.
- * Returns the number of entries added/removed, or `null` if the user
- * is not logged in or the fetch fails.
+ *
+ * Returns the number of entries added/removed, or `null` if the fetch fails
+ * (e.g. platform unreachable, invalid token). Callers must pre-verify a
+ * non-empty token; this function assumes one is present and will throw if
+ * called with an empty string.
  */
 export async function syncCloudAssistants(
+  token: string,
   options?: SyncOptions,
 ): Promise<SyncResult | null> {
+  if (!token) {
+    throw new Error(
+      "syncCloudAssistants called without a token. Callers must check `readPlatformToken()` first.",
+    );
+  }
   const log = options?.log;
   const platformUrl = getPlatformUrl();
   log?.(`Platform URL: ${platformUrl}`);
-
-  const token = readPlatformToken();
-  if (!token) {
-    log?.("No platform token found — skipping cloud sync");
-    return null;
-  }
   log?.(
     `Token found (${token.length} chars, prefix: ${token.slice(0, 6)}…)`,
   );