@vellumai/cli 0.6.4 → 0.6.6

package/src/lib/assistant-config.ts

@@ -10,14 +10,9 @@ import {
 import { homedir } from "os";
 import { dirname, join } from "path";
 
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "./constants.js";
 import {
-  DAEMON_INTERNAL_ASSISTANT_ID,
-  DEFAULT_CES_PORT,
-  DEFAULT_DAEMON_PORT,
-  DEFAULT_GATEWAY_PORT,
-  DEFAULT_QDRANT_PORT,
-} from "./constants.js";
-import {
+  getDefaultPorts,
   getLockfilePath,
   getLockfilePaths,
   getMultiInstanceDir,
@@ -187,6 +182,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
   }
 
   const env = getCurrentEnvironment();
+  const defaultPorts = getDefaultPorts(env);
   let mutated = false;
 
   // Migrate top-level `baseDataDir` → `resources.instanceDir`
@@ -206,7 +202,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
   // Synthesise missing `resources` for local entries
   if (!raw.resources || typeof raw.resources !== "object") {
     const gatewayPort =
-      parsePortFromUrl(raw.runtimeUrl) ?? DEFAULT_GATEWAY_PORT;
+      parsePortFromUrl(raw.runtimeUrl) ?? defaultPorts.gateway;
     const instanceDir = join(
       getMultiInstanceDir(env),
       typeof raw.assistantId === "string"
@@ -215,10 +211,10 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
     );
     raw.resources = {
       instanceDir,
-      daemonPort: DEFAULT_DAEMON_PORT,
+      daemonPort: defaultPorts.daemon,
       gatewayPort,
-      qdrantPort: DEFAULT_QDRANT_PORT,
-      cesPort: DEFAULT_CES_PORT,
+      qdrantPort: defaultPorts.qdrant,
+      cesPort: defaultPorts.ces,
       pidFile: join(instanceDir, ".vellum", "vellum.pid"),
     };
     mutated = true;
@@ -235,20 +231,20 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       mutated = true;
     }
     if (typeof res.daemonPort !== "number") {
-      res.daemonPort = DEFAULT_DAEMON_PORT;
+      res.daemonPort = defaultPorts.daemon;
       mutated = true;
     }
     if (typeof res.gatewayPort !== "number") {
       res.gatewayPort =
-        parsePortFromUrl(raw.runtimeUrl) ?? DEFAULT_GATEWAY_PORT;
+        parsePortFromUrl(raw.runtimeUrl) ?? defaultPorts.gateway;
       mutated = true;
     }
     if (typeof res.qdrantPort !== "number") {
-      res.qdrantPort = DEFAULT_QDRANT_PORT;
+      res.qdrantPort = defaultPorts.qdrant;
       mutated = true;
     }
     if (typeof res.cesPort !== "number") {
-      res.cesPort = DEFAULT_CES_PORT;
+      res.cesPort = defaultPorts.ces;
       mutated = true;
     }
     if (typeof res.pidFile !== "string") {
@@ -378,6 +374,22 @@ export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
   process.exit(1);
 }
 
+/**
+ * Determine which cloud topology an assistant entry is running on.
+ */
+export function resolveCloud(entry: AssistantEntry): string {
+  if (entry.cloud) {
+    return entry.cloud;
+  }
+  if (entry.project) {
+    return "gcp";
+  }
+  if (entry.sshUser) {
+    return "custom";
+  }
+  return "local";
+}
+
 export function saveAssistantEntry(entry: AssistantEntry): void {
   const entries = readAssistants().filter(
     (e) => e.assistantId !== entry.assistantId,
@@ -435,20 +447,21 @@ export async function allocateLocalResources(
     );
   }
 
-  const daemonPort = await findAvailablePort(
-    DEFAULT_DAEMON_PORT,
-    reservedPorts,
-  );
-  const gatewayPort = await findAvailablePort(DEFAULT_GATEWAY_PORT, [
+  // Env-aware bases: non-prod envs sit in their own 1000-port window so
+  // running prod and staging assistants side-by-side doesn't collide. See
+  // `environments/seeds.ts:portBlock` for the layout.
+  const basePorts = getDefaultPorts(env);
+  const daemonPort = await findAvailablePort(basePorts.daemon, reservedPorts);
+  const gatewayPort = await findAvailablePort(basePorts.gateway, [
     ...reservedPorts,
     daemonPort,
   ]);
-  const qdrantPort = await findAvailablePort(DEFAULT_QDRANT_PORT, [
+  const qdrantPort = await findAvailablePort(basePorts.qdrant, [
     ...reservedPorts,
     daemonPort,
     gatewayPort,
   ]);
-  const cesPort = await findAvailablePort(DEFAULT_CES_PORT, [
+  const cesPort = await findAvailablePort(basePorts.ces, [
     ...reservedPorts,
     daemonPort,
     gatewayPort,

package/src/lib/config-utils.ts

@@ -5,8 +5,8 @@ import { join } from "path";
 /**
  * Convert flat dot-notation key=value pairs into a nested config object.
  *
- * e.g. {"services.inference.provider": "anthropic", "services.inference.model": "claude-opus-4-6"}
- *   → {services: {inference: {provider: "anthropic", model: "claude-opus-4-6"}}}
+ * e.g. {"llm.default.provider": "anthropic", "llm.default.model": "claude-opus-4-6"}
+ *   → {llm: {default: {provider: "anthropic", model: "claude-opus-4-6"}}}
  */
 export function buildNestedConfig(
   configValues: Record<string, string>,
@@ -39,8 +39,8 @@ export function buildNestedConfig(
  * values into its workspace config on first boot.
  *
  * Keys use dot-notation to address nested fields. For example:
- *   "services.inference.provider" → {services: {inference: {provider: ...}}}
- *   "services.inference.model"    → {services: {inference: {model: ...}}}
+ *   "llm.default.provider" → {llm: {default: {provider: ...}}}
+ *   "llm.default.model"    → {llm: {default: {model: ...}}}
  *
  * Returns undefined when configValues is empty (nothing to write).
  */

package/src/lib/docker.ts

@@ -6,6 +6,13 @@ import { dirname, join } from "path";
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
 import cliPkg from "../../package.json";
 
+// Pulled from skills/ — the Meet avatar device-path default is owned by the
+// meet-join skill; importing here keeps the CLI's Docker wiring locked to the
+// same value the bot and config schema use. The shared module is deliberately
+// zero-dep so this import cannot drag unrelated surface into the compiled CLI
+// binary.
+import { AVATAR_DEVICE_PATH_DEFAULT } from "../../../skills/meet-join/shared/avatar-device-path.js";
+
 import {
   findAssistantByName,
   saveAssistantEntry,
@@ -13,9 +20,10 @@ import {
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
 import { writeInitialConfig } from "./config-utils";
-import { DEFAULT_GATEWAY_PORT } from "./constants";
 import { PROVIDER_ENV_VAR_NAMES } from "../shared/provider-env-vars.js";
 import type { Species } from "./constants";
+import { getDefaultPorts } from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
 import { leaseGuardianToken } from "./guardian-token";
 import { isVellumProcess, stopProcess } from "./process";
 import { generateInstanceName } from "./random-name";
@@ -45,6 +53,64 @@ export const GATEWAY_INTERNAL_PORT = 7830;
 /** Max time to wait for the assistant container to emit the readiness sentinel. */
 export const DOCKER_READY_TIMEOUT_MS = 3 * 60 * 1000;
 
+/**
+ * Default virtual-camera device path when the Meet avatar feature is
+ * enabled. Re-exports the shared
+ * {@link ../../../skills/meet-join/shared/avatar-device-path.js AVATAR_DEVICE_PATH_DEFAULT}
+ * so the CLI's device-passthrough wiring cannot drift from the bot's
+ * Chrome-flag wiring or the workspace config default. Matches the
+ * `video_nr=10` value in the README's host-setup section
+ * (`skills/meet-join/bot/README.md`). Operators can override the path by
+ * setting `VELLUM_MEET_AVATAR_DEVICE` to something other than the default
+ * (e.g. `/dev/video11` if a different `video_nr` was used).
+ */
+export const DEFAULT_MEET_AVATAR_DEVICE_PATH = AVATAR_DEVICE_PATH_DEFAULT;
+
+/**
+ * Env-var opt-in for bind-mounting the v4l2loopback virtual-camera device
+ * into the assistant container. Set to a truthy value (`1`, `true`, `yes`)
+ * to enable; unset or falsy disables the passthrough entirely.
+ *
+ * Kept as an env-var rather than a config-schema field because the Meet
+ * avatar config schema lands in a later PR (PR 5 of the phase-4 plan) —
+ * threading the config through the CLI's boot flow now would force a
+ * forward dependency. Once the schema lands, the CLI can either keep this
+ * env-var as a pre-config override or move the opt-in into the workspace
+ * config.
+ */
+export const MEET_AVATAR_ENV_VAR = "VELLUM_MEET_AVATAR";
+
+/**
+ * Override for the virtual-camera device path. Defaults to
+ * {@link DEFAULT_MEET_AVATAR_DEVICE_PATH}.
+ */
+export const MEET_AVATAR_DEVICE_ENV_VAR = "VELLUM_MEET_AVATAR_DEVICE";
+
+/**
+ * Resolve the Meet avatar device path to pass through to the assistant
+ * container, or `null` if the feature is not opted into. Exported so tests
+ * can assert against the env-var parsing without reaching into the shell.
+ */
+export function resolveMeetAvatarDevicePath(
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  const flag = env[MEET_AVATAR_ENV_VAR];
+  if (!flag) return null;
+  const normalized = flag.trim().toLowerCase();
+  if (
+    normalized === "" ||
+    normalized === "0" ||
+    normalized === "false" ||
+    normalized === "no"
+  ) {
+    return null;
+  }
+  const override = env[MEET_AVATAR_DEVICE_ENV_VAR];
+  return override && override.length > 0
+    ? override
+    : DEFAULT_MEET_AVATAR_DEVICE_PATH;
+}
+
 /** Default memory (GiB) allocated to the Colima VM. */
 const COLIMA_DEFAULT_MEMORY_GIB = 8;
 
@@ -515,8 +581,8 @@ function serviceImageConfigs(
       tag: imageTags["credential-executor"],
     },
     gateway: {
-      context: join(repoRoot, "gateway"),
-      dockerfile: "Dockerfile",
+      context: repoRoot,
+      dockerfile: "gateway/Dockerfile",
       tag: imageTags.gateway,
     },
   };
@@ -660,6 +726,24 @@ export function serviceDockerRunArgs(opts: {
           args.push("-e", `${key}=${value}`);
         }
       }
+      // Optional Meet avatar (v4l2loopback) passthrough. When
+      // `VELLUM_MEET_AVATAR=1` is set in the caller's environment, bind the
+      // virtual-camera device node (default `/dev/video10`) into the
+      // assistant container so the nested `dockerd` can in turn pass it
+      // through to the Meet-bot container. The daemon-side equivalent of
+      // this opt-in lives on `DockerRunner.run()`'s `avatarDevicePath`
+      // option (see `skills/meet-join/daemon/docker-runner.ts`).
+      const avatarDevice = resolveMeetAvatarDevicePath();
+      if (avatarDevice) {
+        args.push(
+          "--device",
+          `${avatarDevice}:${avatarDevice}`,
+          "-e",
+          `${MEET_AVATAR_ENV_VAR}=1`,
+          "-e",
+          `${MEET_AVATAR_DEVICE_ENV_VAR}=${avatarDevice}`,
+        );
+      }
       args.push(imageTags.assistant);
       return args;
     },
@@ -1074,7 +1158,7 @@ export async function hatchDocker(
     await ensureDockerInstalled();
 
     const instanceName = generateInstanceName(species, name);
-    const gatewayPort = DEFAULT_GATEWAY_PORT;
+    const gatewayPort = getDefaultPorts(getCurrentEnvironment()).gateway;
 
     const imageTags: Record<ServiceName, string> = {
       assistant: "",

package/src/lib/environments/__tests__/paths.test.ts

@@ -200,18 +200,12 @@ describe("path helpers", () => {
       expect(ports.tcp).toBe(8765);
     });
 
-    test("returns identical defaults for dev (Phase 5 deferred)", () => {
+    test("returns base defaults for a bare env with no portsOverride", () => {
+      // Bare env literal (no portsOverride) falls through to DEFAULT_PORTS.
+      // Real non-prod seeds populate portsOverride — see seeds.test cases.
       expect(getDefaultPorts(dev)).toEqual(getDefaultPorts(prod));
     });
 
-    test("returns identical defaults for staging", () => {
-      const staging: EnvironmentDefinition = {
-        name: "staging",
-        platformUrl: "https://staging-platform.vellum.ai",
-      };
-      expect(getDefaultPorts(staging)).toEqual(getDefaultPorts(prod));
-    });
-
     test("merges env.portsOverride on top of defaults", () => {
       const env: EnvironmentDefinition = {
         ...dev,

package/src/lib/environments/__tests__/seeds.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+
+import { getDefaultPorts } from "../paths.js";
+import { SEEDS } from "../seeds.js";
+
+describe("SEEDS port blocks", () => {
+  test("production uses the legacy (pre-MVP) port layout", () => {
+    const ports = getDefaultPorts(SEEDS.production!);
+    expect(ports).toEqual({
+      daemon: 7821,
+      gateway: 7830,
+      qdrant: 6333,
+      ces: 8090,
+      outboundProxy: 8080,
+      tcp: 8765,
+    });
+  });
+
+  test.each([
+    ["staging", 17000],
+    ["dev", 18000],
+    ["test", 19000],
+    ["local", 20000],
+  ] as const)("%s block starts at %i with 100-apart services", (name, base) => {
+    const ports = getDefaultPorts(SEEDS[name]!);
+    expect(ports).toEqual({
+      daemon: base,
+      gateway: base + 100,
+      qdrant: base + 200,
+      ces: base + 300,
+      outboundProxy: base + 400,
+      tcp: base + 500,
+    });
+  });
+
+  test("non-prod blocks are disjoint across environments", () => {
+    // 100 instances per service is the scan headroom in findAvailablePort,
+    // so a block "occupies" base…base+599 from daemon through tcp. Verify no
+    // two blocks overlap for any service.
+    const blocks = (["staging", "dev", "test", "local"] as const).map(
+      (name) => ({
+        name,
+        ports: getDefaultPorts(SEEDS[name]!),
+      }),
+    );
+    const allPorts = new Set<number>();
+    for (const { name, ports } of blocks) {
+      for (const port of Object.values(ports)) {
+        // Within each block, each service has 100 slots (base…base+99).
+        for (let offset = 0; offset < 100; offset++) {
+          const p = port + offset;
+          if (allPorts.has(p)) {
+            throw new Error(
+              `port ${p} (in ${name}'s block) overlaps another env's block`,
+            );
+          }
+          allPorts.add(p);
+        }
+      }
+    }
+  });
+
+  test("non-prod blocks sit below Linux's default ephemeral range (32768)", () => {
+    for (const name of ["staging", "dev", "test", "local"] as const) {
+      const ports = getDefaultPorts(SEEDS[name]!);
+      for (const port of Object.values(ports)) {
+        // Max port we'll ever scan to is base+99 for daemon/gateway/etc.
+        expect(port + 99).toBeLessThan(32768);
+      }
+    }
+  });
+});

package/src/lib/environments/paths.ts

@@ -86,11 +86,10 @@ export function getMultiInstanceDir(env: EnvironmentDefinition): string {
 }
 
 /**
- * Default port set for an environment. Phase 5 (per-env port offsets) was
- * deferred from MVP — this currently returns the same ports for every
- * environment. Per-env specialization lands in a later phase without
- * changing the function signature or call sites. `env.portsOverride` is
- * merged on top of the defaults when set.
+ * Default port set for an environment.
+ * Seed entries for non-prod environments come with separate port ranges
+ * to avoid collisions in multi-env / multi-instance setups.
+ * Longer term, consider allocating ports dynamically at hatch/wake time.
  */
 export function getDefaultPorts(env: EnvironmentDefinition): PortMap {
   return {

package/src/lib/environments/seeds.ts

@@ -1,4 +1,28 @@
-import type { EnvironmentDefinition } from "./types.js";
+import type { EnvironmentDefinition, PortMap } from "./types.js";
+
+/**
+ * Non-prod port blocks. Each environment gets a 1000-port window in the
+ * 17000–21000 band. Within a block, services are spaced 100 apart so up to
+ * 100 assistants can coexist without the scan (`findAvailablePort`) running
+ * one service's range into the next. Band chosen to sit below Linux's
+ * default ephemeral start (32768) and macOS's (49152), and away from the
+ * 3000/5000/8000/9000 dev-tool swamp. Production keeps its legacy,
+ * non-contiguous port set (7821/7830/6333/8090/8080/8765): cross-env
+ * collision is the only problem this change targets, prod is unaffected
+ * because only one env's assistants compete on a given machine, and
+ * churning it would leave existing hatches on 7821 while new ones
+ * allocated elsewhere.
+ */
+function portBlock(base: number): PortMap {
+  return {
+    daemon: base,
+    gateway: base + 100,
+    qdrant: base + 200,
+    ces: base + 300,
+    outboundProxy: base + 400,
+    tcp: base + 500,
+  };
+}
 
 /**
  * Built-in environment definitions. Mirrors Swift's
@@ -25,16 +49,19 @@ export const SEEDS: Record<string, EnvironmentDefinition> = {
   staging: {
     name: "staging",
     platformUrl: "https://staging-platform.vellum.ai",
+    portsOverride: portBlock(17000),
   },
   test: {
     name: "test",
     // Non-functional URL — used only by unit tests for URL resolution, never
     // hit in production.
     platformUrl: "https://test-platform.vellum.ai",
+    portsOverride: portBlock(19000),
   },
   dev: {
     name: "dev",
     platformUrl: "https://dev-platform.vellum.ai",
+    portsOverride: portBlock(18000),
   },
   local: {
     name: "local",
@@ -42,5 +69,6 @@ export const SEEDS: Record<string, EnvironmentDefinition> = {
     // assistantPlatformUrl: "http://host.docker.internal:8000",
     // ^ uncomment this once dockerized hatch path is live.
     // The assistant runs in a different network namespace than the host.
+    portsOverride: portBlock(20000),
   },
 };

package/src/lib/exec-apple-container.ts

@@ -0,0 +1,122 @@
+import { createConnection } from "net";
+import { existsSync } from "fs";
+
+import type { AssistantEntry } from "./assistant-config";
+
+/**
+ * Execute a command inside an Apple Container assistant via the management
+ * socket. Non-interactive: sends the command, streams stdout/stderr to the
+ * terminal, and exits with the appropriate code.
+ */
+export async function execAppleContainer(
+  entry: AssistantEntry,
+  command: string[],
+  service: string,
+): Promise<void> {
+  const mgmtSocket = entry.mgmtSocket as string | undefined;
+  if (!mgmtSocket) {
+    console.error(
+      `No management socket found for '${entry.assistantId}'.\n` +
+        "The assistant may not be running.",
+    );
+    process.exit(1);
+  }
+
+  if (!existsSync(mgmtSocket)) {
+    console.error(
+      `Management socket not found at ${mgmtSocket}.\n` +
+        "The assistant may have been stopped.",
+    );
+    process.exit(1);
+  }
+
+  const handshake =
+    JSON.stringify({
+      command,
+      service,
+      cols: process.stdout.columns || 120,
+      rows: process.stdout.rows || 40,
+    }) + "\n";
+
+  return new Promise<void>((resolve, reject) => {
+    const socket = createConnection({ path: mgmtSocket }, () => {
+      socket.write(handshake);
+    });
+
+    const HANDSHAKE_TIMEOUT_MS = 10_000;
+    let handshakeComplete = false;
+    const handshakeChunks: Buffer[] = [];
+    let handshakeLen = 0;
+
+    socket.setTimeout(HANDSHAKE_TIMEOUT_MS);
+    socket.on("timeout", () => {
+      if (!handshakeComplete) {
+        console.error("Timed out waiting for response from management socket.");
+        socket.destroy();
+        process.exit(1);
+      }
+    });
+
+    socket.on("data", (data: Buffer) => {
+      if (!handshakeComplete) {
+        handshakeChunks.push(data);
+        handshakeLen += data.length;
+        const accumulated = Buffer.concat(handshakeChunks, handshakeLen);
+        const nlIndex = accumulated.indexOf(0x0a);
+        if (nlIndex === -1) return;
+
+        const responseLine = accumulated.slice(0, nlIndex).toString("utf-8");
+        const remainder = accumulated.slice(nlIndex + 1);
+        handshakeComplete = true;
+        socket.setTimeout(0);
+
+        let response: { status: string; message?: string };
+        try {
+          response = JSON.parse(responseLine) as {
+            status: string;
+            message?: string;
+          };
+        } catch {
+          console.error("Invalid response from management socket.");
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        if (response.status !== "ok") {
+          console.error(`Exec failed: ${response.message || "unknown error"}`);
+          socket.destroy();
+          process.exit(1);
+          return;
+        }
+
+        // Write any bytes that arrived after the handshake newline.
+        if (remainder.length > 0) {
+          process.stdout.write(remainder);
+        }
+        return;
+      }
+
+      // Stream command output to stdout.
+      process.stdout.write(data);
+    });
+
+    socket.on("end", () => {
+      if (handshakeComplete) {
+        resolve();
+      } else {
+        reject(new Error("Connection closed before handshake completed."));
+      }
+    });
+
+    socket.on("error", (err) => {
+      reject(new Error(`Management socket error: ${err.message}`));
+    });
+
+    socket.on("close", () => {
+      if (handshakeComplete) {
+        resolve();
+      }
+    });
+  });
+}

package/src/lib/guardian-token.ts

@@ -5,6 +5,7 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  statSync,
   writeFileSync,
 } from "fs";
 import { platform } from "os";
@@ -12,6 +13,7 @@ import { dirname, join } from "path";
 
 import { getConfigDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
+import { SEEDS } from "./environments/seeds.js";
 
 const DEVICE_ID_SALT = "vellum-assistant-host-id";
 
@@ -200,3 +202,64 @@ export async function leaseGuardianToken(
   saveGuardianToken(assistantId, tokenData);
   return tokenData;
 }
+
+/**
+ * Copy a guardian token from a sibling environment's config directory into
+ * the current environment's dir when the current one is missing it.
+ *
+ * The CLI's per-environment config layout (`~/.config/vellum{-env}/`) scopes
+ * the lockfile and the guardian token by VELLUM_ENVIRONMENT. Lockfiles are
+ * cross-written at hatch time, but a guardian token is only written under
+ * the env the assistant was hatched in. If the user later wakes the same
+ * assistant under a different env (e.g. a freshly built desktop app ships
+ * with VELLUM_ENVIRONMENT=local while the original hatch was under dev),
+ * the app cannot locate a bearer token and falls into a 401 → auth-rate-
+ * limit → 429 cascade against the local gateway.
+ *
+ * Returns true if a token was seeded, false if a token was already present
+ * or no sibling env had one to copy.
+ */
+export function seedGuardianTokenFromSiblingEnv(assistantId: string): boolean {
+  if (loadGuardianToken(assistantId) !== null) return false;
+
+  const currentEnvName = getCurrentEnvironment().name;
+  const destPath = getGuardianTokenPath(assistantId);
+
+  const candidates: { path: string; mtimeMs: number }[] = [];
+  for (const env of Object.values(SEEDS)) {
+    if (env.name === currentEnvName) continue;
+    const sibling = join(
+      getConfigDir(env),
+      "assistants",
+      assistantId,
+      "guardian-token.json",
+    );
+    try {
+      const stat = statSync(sibling);
+      candidates.push({ path: sibling, mtimeMs: stat.mtimeMs });
+    } catch {
+      continue;
+    }
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const now = Date.now();
+  for (const { path: sibling } of candidates) {
+    try {
+      const raw = readFileSync(sibling);
+      const parsed = JSON.parse(raw.toString("utf-8")) as GuardianTokenData;
+      const refreshExpiry = Date.parse(parsed.refreshTokenExpiresAt);
+      if (!Number.isFinite(refreshExpiry) || refreshExpiry <= now) continue;
+      const dir = dirname(destPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+      }
+      writeFileSync(destPath, raw, { mode: 0o600 });
+      chmodSync(destPath, 0o600);
+      return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}

package/src/lib/hatch-local.ts

@@ -305,10 +305,26 @@ export async function hatchLocal(
   // IP which the daemon rejects as non-loopback.
   emitProgress(6, 7, "Securing connection...");
   const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
-  try {
-    await leaseGuardianToken(loopbackUrl, instanceName);
-  } catch (err) {
-    console.error(`⚠️  Guardian token lease failed: ${err}`);
+  const maxLeaseAttempts = 3;
+  for (let attempt = 1; attempt <= maxLeaseAttempts; attempt++) {
+    try {
+      await leaseGuardianToken(loopbackUrl, instanceName);
+      break;
+    } catch (err) {
+      if (attempt < maxLeaseAttempts) {
+        const delayMs = 2000 * 2 ** (attempt - 1);
+        console.error(
+          `⚠️  Guardian token lease attempt ${attempt}/${maxLeaseAttempts} failed — retrying in ${delayMs / 1000}s: ${err}`,
+        );
+        await new Promise((r) => setTimeout(r, delayMs));
+      } else {
+        console.error(
+          `⚠️  Guardian token lease failed after ${maxLeaseAttempts} attempts: ${err}\n` +
+            `   The assistant is running but guardian-token.json was not written.\n` +
+            `   If the desktop app loses its stored credentials, re-hatch to recover.`,
+        );
+      }
+    }
   }
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram, Twilio) are configured.