@vellumai/cli 0.10.0 → 0.10.1-staging.1

package/bun.lock

@@ -398,7 +398,7 @@
 
     "@typescript-eslint/eslint-plugin/ignore": ["ignore@7.0.5", "", {}, "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg=="],
 
-    "@vellumai/local-mode/@vellumai/environments": ["@vellumai/environments@file:../packages/environments", {}],
+    "@vellumai/local-mode/@vellumai/environments": ["@vellumai/environments@file:../packages/environments", { "devDependencies": { "@types/bun": "1.3.11", "typescript": "5.9.3" } }],
 
     "fast-glob/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
 

package/node_modules/@vellumai/local-mode/bun.lock

@@ -6,6 +6,7 @@
       "name": "@vellumai/local-mode",
       "dependencies": {
         "@vellumai/environments": "file:../environments",
+        "zod": "4.3.6",
       },
       "devDependencies": {
         "@types/bun": "1.3.11",
@@ -25,5 +26,7 @@
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
     "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
+
+    "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
   }
 }

package/node_modules/@vellumai/local-mode/package.json

@@ -13,7 +13,8 @@
     "test": "bun test src/"
   },
   "dependencies": {
-    "@vellumai/environments": "file:../environments"
+    "@vellumai/environments": "file:../environments",
+    "zod": "4.3.6"
   },
   "devDependencies": {
     "@types/bun": "1.3.11",

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

@@ -69,6 +69,32 @@ describe("isActiveAssistant", () => {
     expect(isActiveAssistant([lockfilePath], "active")).toBe(true);
   });
 
+  test("returns true for the sole assistant when activeAssistant is empty", () => {
+    const dir = makeTempDir();
+    const lockfilePath = path.join(dir, "lockfile.json");
+    fs.writeFileSync(
+      lockfilePath,
+      JSON.stringify({
+        assistants: [{ assistantId: "only" }],
+        activeAssistant: null,
+      }),
+    );
+    expect(isActiveAssistant([lockfilePath], "only")).toBe(true);
+  });
+
+  test("returns true for the sole assistant when activeAssistant is stale", () => {
+    const dir = makeTempDir();
+    const lockfilePath = path.join(dir, "lockfile.json");
+    fs.writeFileSync(
+      lockfilePath,
+      JSON.stringify({
+        assistants: [{ assistantId: "only" }],
+        activeAssistant: "missing",
+      }),
+    );
+    expect(isActiveAssistant([lockfilePath], "only")).toBe(true);
+  });
+
   test("returns false for a non-active assistant", () => {
     const dir = makeTempDir();
     const lockfilePath = path.join(dir, "lockfile.json");

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

@@ -6,10 +6,9 @@
  * uses node builtins for filesystem, child-process, and network work.
  *
  * Enforces that the package:
- * 1. Imports only node builtins, its own relative modules, and
- *    `@vellumai/environments` — no other `@vellumai/*` packages and no
- *    third-party runtime imports (so any bundler host can inline it).
- * 2. Declares exactly one runtime dependency: `@vellumai/environments`.
+ * 1. Imports only node builtins, its own relative modules, `@vellumai/environments`,
+ *    and `zod` (the lockfile contract's schema library) — nothing else.
+ * 2. Declares exactly those two runtime dependencies.
  * 3. Is marked `private`.
  */
 
@@ -20,7 +19,7 @@ import { join, resolve } from "node:path";
 const PACKAGE_ROOT = resolve(import.meta.dirname, "../..");
 const SRC_DIR = join(PACKAGE_ROOT, "src");
 
-const ALLOWED_PACKAGES = new Set(["@vellumai/environments"]);
+const ALLOWED_PACKAGES = new Set(["@vellumai/environments", "zod"]);
 
 function collectSourceFiles(dir: string): string[] {
   const files: string[] = [];
@@ -92,13 +91,14 @@ describe("package boundary", () => {
     }
   });
 
-  test("package.json declares it as private with only the @vellumai/environments dependency", () => {
+  test("package.json declares it as private with only its environments and zod dependencies", () => {
     const pkg = JSON.parse(
       readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
     );
     expect(pkg.private).toBe(true);
     expect(pkg.dependencies ?? {}).toEqual({
       "@vellumai/environments": "file:../environments",
+      zod: "4.3.6",
     });
   });
 });

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

@@ -39,6 +39,8 @@ export { runSleep } from "./sleep";
 export type { SleepResult } from "./sleep";
 export { runWake } from "./wake";
 export type { WakeOptions, WakeResult } from "./wake";
+export { runUpgrade } from "./upgrade";
+export type { UpgradeOptions, UpgradeResult } from "./upgrade";
 export { getLocalAssistantStatus } from "./status";
 export type {
   LocalAssistantRuntimeState,

package/node_modules/@vellumai/local-mode/src/lockfile-contract.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, test } from "bun:test";
 
-import { parseLockfile, type Lockfile } from "./lockfile-contract";
+import {
+  KNOWN_CLOUDS,
+  parseLockfile,
+  resolveCloud,
+  SENSITIVE_KEYS,
+  type Lockfile,
+} from "./lockfile-contract";
 
 describe("parseLockfile", () => {
   test("passes through a fully-populated lockfile", () => {
@@ -42,24 +48,30 @@ describe("parseLockfile", () => {
 
   test("salvages a legacy entry that has only an assistantId", () => {
     // The oldest persisted entries carry just the identity; the CLI fills the
-    // rest in lazily. assistantId is the only required field, so the entry
-    // must survive intact rather than being discarded.
+    // rest in lazily. assistantId is the only required field, so the entry must
+    // survive — normalized to the default `local` cloud.
     const parsed = parseLockfile({
       activeAssistant: "asst_1",
       assistants: [{ assistantId: "asst_1" }],
     });
-    expect(parsed.assistants).toEqual([{ assistantId: "asst_1" }]);
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_1", cloud: "local" },
+    ]);
   });
 
   test("salvages an entry whose cloud and runtimeUrl are absent", () => {
     // Older CLI builds predate the `cloud` field and persisted the runtime URL
     // under a different key (`localUrl`), so a real on-disk entry can lack both
-    // modeled fields. It must still be returned (the macOS↔CLI skew window).
+    // modeled fields. It must still be returned, normalized to `local`.
     const parsed = parseLockfile({
       activeAssistant: null,
-      assistants: [{ assistantId: "asst_1", localUrl: "http://127.0.0.1:7777" }],
+      assistants: [
+        { assistantId: "asst_1", localUrl: "http://127.0.0.1:7777" },
+      ],
     });
-    expect(parsed.assistants).toEqual([{ assistantId: "asst_1" }]);
+    expect(parsed.assistants).toEqual([
+      { assistantId: "asst_1", cloud: "local" },
+    ]);
   });
 
   test("drops malformed entries but salvages valid siblings", () => {
@@ -111,7 +123,9 @@ describe("parseLockfile", () => {
   });
 
   test("coerces a non-string activeAssistant to null", () => {
-    expect(parseLockfile({ assistants: [], activeAssistant: 7 }).activeAssistant).toBeNull();
+    expect(
+      parseLockfile({ assistants: [], activeAssistant: 7 }).activeAssistant,
+    ).toBeNull();
     expect(parseLockfile({ assistants: [] }).activeAssistant).toBeNull();
   });
 
@@ -124,9 +138,9 @@ describe("parseLockfile", () => {
   });
 
   test("drops a mistyped optional field but keeps the entry", () => {
-    // assistantId is the only required field. A mistyped optional field (here
-    // cloud / runtimeUrl) is dropped from the result, but the entry survives on
-    // the strength of its identity rather than being discarded wholesale.
+    // assistantId is the only required field. A mistyped optional field is
+    // dropped from the result, but the entry survives on the strength of its
+    // identity. (A mistyped `cloud` is dropped, then re-normalized to `local`.)
     const raw = {
       assistants: [
         { assistantId: "asst_1", cloud: 7, runtimeUrl: "http://a" }, // cloud not a string
@@ -135,7 +149,7 @@ describe("parseLockfile", () => {
       activeAssistant: null,
     };
     expect(parseLockfile(raw).assistants).toEqual([
-      { assistantId: "asst_1", runtimeUrl: "http://a" },
+      { assistantId: "asst_1", cloud: "local", runtimeUrl: "http://a" },
       { assistantId: "asst_2", cloud: "local" },
     ]);
   });
@@ -189,4 +203,126 @@ describe("parseLockfile", () => {
     });
     expect(assistant?.resources).toBeUndefined();
   });
+
+  test("keeps local runtime resource fields when well-typed", () => {
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          runtimeUrl: "http://a",
+          resources: {
+            gatewayPort: 7777,
+            daemonPort: 7778,
+            runtimeVersion: "v0.8.13",
+            runtimeInstallDir: "/tmp/vellum/runtime/0.8.13",
+          },
+        },
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants[0]?.resources).toEqual({
+      gatewayPort: 7777,
+      daemonPort: 7778,
+      runtimeVersion: "v0.8.13",
+      runtimeInstallDir: "/tmp/vellum/runtime/0.8.13",
+    });
+  });
+
+  test("strips sensitive and host-only fields from resources", () => {
+    const raw = {
+      assistants: [
+        {
+          assistantId: "asst_1",
+          cloud: "local",
+          resources: {
+            instanceDir: "/data",
+            gatewayPort: 7777,
+            daemonPort: 7778,
+            runtimeVersion: "v0.8.13",
+            runtimeInstallDir: "/tmp/vellum/runtime/0.8.13",
+            qdrantPort: 7779,
+            cesPort: 7780,
+            signingKey: "hunter2",
+          },
+        },
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants[0]?.resources).toEqual({
+      instanceDir: "/data",
+      gatewayPort: 7777,
+      daemonPort: 7778,
+      runtimeVersion: "v0.8.13",
+      runtimeInstallDir: "/tmp/vellum/runtime/0.8.13",
+    });
+  });
+
+  test("resolves cloud from legacy remote markers when the field is absent", () => {
+    // Pre-`cloud` remote entries encode topology in `project` (gcp) / `sshUser`
+    // (custom). The parser resolves these so a cloudless remote entry is never
+    // mistaken for a local one; a cloudless entry with no markers normalizes to
+    // `local`. The raw markers are not carried through.
+    const raw = {
+      assistants: [
+        { assistantId: "gcp_1", project: "my-proj", runtimeUrl: "https://a" },
+        { assistantId: "ssh_1", sshUser: "deploy", runtimeUrl: "https://b" },
+        { assistantId: "local_1", runtimeUrl: "http://localhost:7830" },
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "gcp_1", cloud: "gcp", runtimeUrl: "https://a" },
+      { assistantId: "ssh_1", cloud: "custom", runtimeUrl: "https://b" },
+      { assistantId: "local_1", cloud: "local", runtimeUrl: "http://localhost:7830" },
+    ]);
+  });
+
+  test("prefers an explicit cloud over legacy remote markers", () => {
+    const raw = {
+      assistants: [{ assistantId: "a", cloud: "vellum", project: "stale-proj" }],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "a", cloud: "vellum" },
+    ]);
+  });
+});
+
+describe("resolveCloud", () => {
+  test("prefers an explicit cloud", () => {
+    expect(resolveCloud({ cloud: "vellum", project: "p", sshUser: "u" })).toBe(
+      "vellum",
+    );
+  });
+
+  test("falls back to legacy markers, then local", () => {
+    expect(resolveCloud({ project: "p" })).toBe("gcp");
+    expect(resolveCloud({ sshUser: "u" })).toBe("custom");
+    expect(resolveCloud({})).toBe("local");
+    expect(resolveCloud({ cloud: "" })).toBe("local");
+  });
+});
+
+describe("taxonomy", () => {
+  test("KNOWN_CLOUDS covers the documented topologies", () => {
+    expect(KNOWN_CLOUDS).toEqual([
+      "local",
+      "docker",
+      "apple-container",
+      "vellum",
+      "gcp",
+      "aws",
+      "custom",
+      "paired",
+    ]);
+  });
+
+  test("SENSITIVE_KEYS lists the redacted secrets", () => {
+    expect(SENSITIVE_KEYS).toEqual([
+      "signingKey",
+      "bearerToken",
+      "guardianBootstrapSecret",
+    ]);
+  });
 });

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -1,52 +1,127 @@
 /**
- * The lockfile wire contract — the types and the parser that validates them —
- * kept in its own module so consumers can import the contract without pulling
- * in the host I/O graph (`node:fs`, the CLI resolver, the environments
- * package). The renderer relies on that separation: it imports these types
- * type-only and must not transitively reference Node built-ins.
+ * The lockfile wire contract — one Zod schema that is the single source of truth
+ * for an assistant entry's shape, its validation, the `cloud` taxonomy, the
+ * normalization, and the redaction policy.
  *
- * Validation is hand-written rather than schema-library-based on purpose: this
- * package is inlined from source by three different bundler hosts (the CLI, the
- * Electron main process, and the web dev server) and deliberately carries no
- * third-party runtime dependencies (enforced by `__tests__/package-boundary`).
- * The contract is small enough that a typed parser is clearer than a dependency.
+ * Kept in its own module, exported from the package as `./contract`, so
+ * consumers import the contract without pulling in the host I/O graph
+ * (`node:fs`, the CLI resolver). The CLI, the host I/O layer, the Electron and
+ * dev-server bridges, and the renderer all depend on this one definition. It
+ * references no node built-ins — the renderer bundles it directly — and `zod`
+ * is its only third-party import.
  *
  * The lockfile is written by the Vellum CLI and read across the macOS↔CLI
- * boundary, which do not release in lockstep. The parser is therefore
- * permissive about unknown fields: it reads only the modeled fields below and
- * ignores everything else, so a newer writer's extra fields never fail an
- * older reader. Unknown fields are preserved on disk by the write path (see
- * `lockfile.ts`); the validated value returned to callers carries only the
- * modeled shape.
- *
- * `assistantId` is the only required field — it is the entry's identity (the
- * key every reader and the write path look entries up by) and the one field
- * the CLI always writes. Everything else is optional on disk: older entries
- * predate the `cloud` field, the runtime URL has historically been persisted
- * under a different key (`localUrl`), and resource ports are only present for
- * multi-instance local setups. The parser therefore salvages any entry that
- * has a string `assistantId` and copies the remaining modeled fields only when
- * they are present and well-typed, rather than discarding an otherwise-usable
- * assistant because an optional field is missing or malformed.
+ * boundary, which do not release in lockstep, so the parser is permissive: it
+ * validates the modeled fields, salvages an entry on the strength of its
+ * `assistantId` alone (dropping individual malformed optional fields rather
+ * than the whole entry), and ignores unknown fields so a newer writer never
+ * breaks an older reader. Unknown fields are preserved on disk by the write
+ * path (see `lockfile.ts`); the validated value carries only the modeled,
+ * renderer-safe shape.
+ */
+import { z } from "zod";
+
+/**
+ * Known deployment topologies. `cloud` is stored as a free string on disk for
+ * forward-compatibility — an older reader must tolerate a newer writer's value
+ * — but the known set is enumerated here so callers switch on it exhaustively
+ * instead of matching string literals scattered across the codebase:
+ *  - `local` — on-machine daemon
+ *  - `docker` — local container
+ *  - `apple-container` — macOS-app-managed container
+ *  - `vellum` — platform-managed (uses the X-Session-Token auth path)
+ *  - `gcp` / `aws` / `custom` — remote, SSH-managed
+ *  - `paired` — a remote assistant paired from another machine
  */
+export const KNOWN_CLOUDS = [
+  "local",
+  "docker",
+  "apple-container",
+  "vellum",
+  "gcp",
+  "aws",
+  "custom",
+  "paired",
+] as const;
+export type KnownCloud = (typeof KNOWN_CLOUDS)[number];
+export type Cloud = KnownCloud | (string & {});
 
-export interface LocalAssistantResources {
-  instanceDir?: string;
-  gatewayPort: number;
-  daemonPort: number;
+/**
+ * Keys that must never cross the host→renderer boundary. Stripped from raw
+ * lockfile JSON before it leaves a host (see `stripSensitiveFields`) and absent
+ * from the renderer-facing schema below; the CLI's extended type is the only
+ * place they are modeled.
+ */
+export const SENSITIVE_KEYS = [
+  "signingKey",
+  "bearerToken",
+  "guardianBootstrapSecret",
+] as const;
+
+/**
+ * Resolve an entry's deployment topology from its raw on-disk fields. Prefers
+ * an explicit `cloud`, then the legacy markers that predate the field
+ * (`project` ⇒ gcp, `sshUser` ⇒ custom), and defaults to "local". This is the
+ * one definition every reader shares, so a cloudless entry is classified
+ * identically by the CLI, the host I/O layer, and the renderer.
+ */
+export function resolveCloud(raw: {
+  cloud?: unknown;
+  project?: unknown;
+  sshUser?: unknown;
+}): Cloud {
+  if (typeof raw.cloud === "string" && raw.cloud) return raw.cloud;
+  if (typeof raw.project === "string" && raw.project) return "gcp";
+  if (typeof raw.sshUser === "string" && raw.sshUser) return "custom";
+  return "local";
 }
 
-export interface LockfileAssistant {
-  assistantId: string;
-  name?: string;
-  cloud?: string;
-  runtimeUrl?: string;
-  species?: string;
-  hatchedAt?: string;
+/**
+ * Per-instance resources for a local assistant: the renderer-facing subset of
+ * ports, the instance directory, and the local runtime install metadata.
+ * Richer host-only fields (other ports, the signing key) live on the CLI's
+ * type and are stripped from this shape.
+ */
+export const LocalAssistantResourcesSchema = z.object({
+  instanceDir: z.string().optional(),
+  gatewayPort: z.number(),
+  daemonPort: z.number(),
+  runtimeVersion: z.string().optional(),
+  runtimeInstallDir: z.string().optional(),
+});
+export type LocalAssistantResources = z.infer<
+  typeof LocalAssistantResourcesSchema
+>;
+
+/**
+ * The renderer-safe shape of one assistant entry. `assistantId` is the only
+ * required field — the identity every reader looks entries up by — and every
+ * other field is salvaged by {@link parseLockfile}. The CLI extends this with
+ * its host-only and sensitive fields; this base carries only what is safe to
+ * surface in the renderer.
+ */
+export const LockfileAssistantSchema = z.object({
+  assistantId: z.string(),
+  name: z.string().optional(),
+  cloud: z.string().optional(),
+  runtimeUrl: z.string().optional(),
+  species: z.string().optional(),
+  hatchedAt: z.string().optional(),
   /** Owning org for platform assistants; absent for local ones. */
-  organizationId?: string;
-  resources?: LocalAssistantResources;
-}
+  organizationId: z.string().optional(),
+  resources: LocalAssistantResourcesSchema.optional(),
+});
+
+/**
+ * A validated, normalized assistant entry. Identical to the schema's inferred
+ * shape except `cloud` is always present — {@link parseLockfile} resolves it for
+ * every entry (defaulting to "local"), so readers never special-case its
+ * absence.
+ */
+export type LockfileAssistant = Omit<
+  z.infer<typeof LockfileAssistantSchema>,
+  "cloud"
+> & { cloud: Cloud };
 
 export interface Lockfile {
   assistants: LockfileAssistant[];
@@ -55,8 +130,8 @@ export interface Lockfile {
 
 /**
  * Renderer-facing result of a lockfile write, returned across the host bridge.
- * Carries no HTTP-style `status` — the hosts map that away because the
- * renderer surfaces failures by message alone.
+ * Carries no HTTP-style status — hosts map that away because the renderer
+ * surfaces failures by message alone.
  */
 export type LockfileWriteResult =
   | { ok: true; lockfile: Lockfile }
@@ -66,49 +141,30 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function parseResources(value: unknown): LocalAssistantResources | undefined {
-  if (!isRecord(value)) return undefined;
-  if (typeof value.gatewayPort !== "number") return undefined;
-  if (typeof value.daemonPort !== "number") return undefined;
-  return {
-    ...(typeof value.instanceDir === "string"
-      ? { instanceDir: value.instanceDir }
-      : {}),
-    gatewayPort: value.gatewayPort,
-    daemonPort: value.daemonPort,
-  };
-}
-
 /**
- * Validate a single assistant entry. Returns `null` only when the entry lacks a
- * string `assistantId` (its identity); any other entry is salvaged. Each
- * optional field is copied only when present and well-typed — a missing or
- * mistyped optional field is dropped from the result without discarding the
- * entry — and unknown fields are ignored.
+ * Validate and normalize a single entry. Returns null only when `assistantId`
+ * is missing or not a string; any other entry is salvaged — each modeled field
+ * is copied only when present and well-typed (a malformed optional field is
+ * dropped without discarding the entry), unknown fields are ignored, and
+ * `cloud` is resolved from the raw markers so a cloudless remote entry is never
+ * mistaken for a local one and a markerless entry defaults to "local".
  */
-function parseAssistant(value: unknown): LockfileAssistant | null {
-  if (!isRecord(value)) return null;
-  if (typeof value.assistantId !== "string") return null;
-
-  const assistant: LockfileAssistant = { assistantId: value.assistantId };
-  if (typeof value.name === "string") assistant.name = value.name;
-  if (typeof value.cloud === "string") assistant.cloud = value.cloud;
-  if (typeof value.runtimeUrl === "string") assistant.runtimeUrl = value.runtimeUrl;
-  if (typeof value.species === "string") assistant.species = value.species;
-  if (typeof value.hatchedAt === "string") assistant.hatchedAt = value.hatchedAt;
-  if (typeof value.organizationId === "string") assistant.organizationId = value.organizationId;
-  const resources = parseResources(value.resources);
-  if (resources) assistant.resources = resources;
-  return assistant;
+function parseAssistant(raw: unknown): LockfileAssistant | null {
+  if (!isRecord(raw) || typeof raw.assistantId !== "string") return null;
+  const out: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(LockfileAssistantSchema.shape)) {
+    const result = (field as z.ZodType).safeParse(raw[key]);
+    if (result.success && result.data !== undefined) out[key] = result.data;
+  }
+  out.cloud = resolveCloud(raw);
+  return out as LockfileAssistant;
 }
 
 /**
- * Coerce parsed JSON into a validated `Lockfile`. Total and non-throwing:
- * individual assistant entries that fail validation are dropped (so one
- * malformed entry can't discard the whole file), a missing/non-array
- * `assistants` becomes `[]`, and a non-string `activeAssistant` becomes
- * `null`. Callers pass the result through unchanged; the only failure modes a
- * host surfaces are I/O and JSON-parse errors, handled by `getLockfileData`.
+ * Coerce parsed JSON into a validated {@link Lockfile}. Total and non-throwing:
+ * entries that fail validation are dropped (one malformed entry can't discard
+ * the file), a missing or non-array `assistants` becomes `[]`, and a non-string
+ * `activeAssistant` becomes null.
  */
 export function parseLockfile(raw: unknown): Lockfile {
   const root = isRecord(raw) ? raw : {};

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

@@ -74,7 +74,9 @@ describe("getLockfileData", () => {
     const result = getLockfileData([lockfilePath]);
     expect(result.ok).toBe(true);
     if (result.ok) {
-      expect(result.data.assistants).toEqual([{ assistantId: "asst_legacy" }]);
+      expect(result.data.assistants).toEqual([
+        { assistantId: "asst_legacy", cloud: "local" },
+      ]);
       expect(result.data.activeAssistant).toBe("asst_legacy");
     }
   });

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

@@ -94,8 +94,15 @@ export function isActiveAssistant(
 ): boolean {
   for (const candidate of lockfilePaths) {
     try {
-      const data = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<string, unknown>;
-      return data.activeAssistant === assistantId;
+      const data = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+      if (data.activeAssistant === assistantId) return true;
+      const assistants = data.assistants;
+      if (!Array.isArray(assistants) || assistants.length !== 1) return false;
+      const [onlyAssistant] = assistants as Array<Record<string, unknown>>;
+      return onlyAssistant?.assistantId === assistantId;
     } catch {
       continue;
     }

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

@@ -20,6 +20,7 @@ const DEFAULT_PORTS = {
 
 export type LocalAssistantRuntimeState =
   | "healthy"
+  | "upgrading"
   | "sleeping"
   | "starting"
   | "crashed"