@vellumai/cli 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/lib/cloudflare-tunnel.ts

@@ -0,0 +1,276 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { GATEWAY_PORT } from "./constants.js";
+
+// ── Workspace config helpers (mirrors the pattern in ngrok.ts) ───────────────
+
+function getDefaultWorkspaceDir(): string {
+  return (
+    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
+    join(homedir(), ".vellum", "workspace")
+  );
+}
+
+function getConfigPath(workspaceDir: string): string {
+  return join(workspaceDir, "config.json");
+}
+
+function loadRawConfig(workspaceDir: string): Record<string, unknown> {
+  const configPath = getConfigPath(workspaceDir);
+  if (!existsSync(configPath)) return {};
+  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
+    string,
+    unknown
+  >;
+}
+
+function saveRawConfig(
+  workspaceDir: string,
+  config: Record<string, unknown>,
+): void {
+  const configPath = getConfigPath(workspaceDir);
+  const dir = dirname(configPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  ingress.publicBaseUrl = publicUrl;
+  ingress.enabled = true;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+function clearIngressUrl(workspaceDir: string): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  delete ingress.publicBaseUrl;
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+// ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
+
+const CLOUDFLARED_TIMEOUT_MS = 30_000;
+
+// Quick-tunnel hostnames follow the pattern <word>-<word>-<word>.trycloudflare.com
+const QUICK_TUNNEL_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+/**
+ * Check whether cloudflared is installed and on PATH.
+ * Returns the version string if found, null otherwise.
+ */
+export function getCloudflareTunnelVersion(): string | null {
+  try {
+    const output = execFileSync("cloudflared", ["version"], {
+      encoding: "utf-8",
+      timeout: 5_000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawn a cloudflared quick-tunnel process forwarding HTTP traffic to
+ * `targetPort`.  The child process writes its public URL to stderr during
+ * startup — use {@link waitForCloudflareTunnelUrl} to extract it.
+ */
+export function startCloudflareTunnelProcess(targetPort: number): ChildProcess {
+  return spawn(
+    "cloudflared",
+    ["tunnel", "--url", `http://localhost:${targetPort}`, "--no-autoupdate"],
+    // Keep stdio as pipes so we can parse the URL from output.
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+}
+
+/**
+ * Listen to a running cloudflared process's stdout/stderr and resolve with
+ * the public quick-tunnel URL once cloudflared prints it.
+ *
+ * cloudflared emits a line containing the trycloudflare.com URL during
+ * startup — typically within 5–15 seconds on a normal internet connection.
+ *
+ * Rejects when:
+ * - The URL does not appear within `timeoutMs`.
+ * - The child process exits before the URL is found.
+ */
+export function waitForCloudflareTunnelUrl(
+  child: ChildProcess,
+  timeoutMs: number = CLOUDFLARED_TIMEOUT_MS,
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `cloudflared tunnel URL did not appear within ${timeoutMs / 1000}s. ` +
+            `Ensure cloudflared is working: try running 'cloudflared tunnel --url http://localhost:8080' manually.`,
+        ),
+      );
+    }, timeoutMs);
+
+    let resolved = false;
+
+    function scanLine(line: string): void {
+      if (resolved) return;
+      const match = QUICK_TUNNEL_URL_RE.exec(line);
+      if (match) {
+        resolved = true;
+        clearTimeout(timer);
+        resolve(match[0]);
+      }
+    }
+
+    // Buffer incomplete lines across chunks
+    let stdoutBuf = "";
+    let stderrBuf = "";
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdoutBuf += chunk.toString();
+      const lines = stdoutBuf.split("\n");
+      stdoutBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrBuf += chunk.toString();
+      const lines = stderrBuf.split("\n");
+      stderrBuf = lines.pop() ?? "";
+      for (const line of lines) scanLine(line);
+    });
+
+    child.on("exit", (code) => {
+      if (resolved) return;
+      clearTimeout(timer);
+      reject(
+        new Error(
+          `cloudflared exited with code ${code ?? "unknown"} before the tunnel URL appeared.`,
+        ),
+      );
+    });
+  });
+}
+
+/**
+ * Run the cloudflared quick-tunnel workflow:
+ * 1. Verify cloudflared is installed.
+ * 2. Start a quick tunnel pointing at the gateway port.
+ * 3. Parse the public URL from cloudflared output.
+ * 4. Persist the URL to the workspace config as the ingress base URL.
+ * 5. Block until the process exits or the user presses Ctrl+C.
+ * 6. Clear the ingress URL from config on exit.
+ *
+ * No Cloudflare account is required — quick tunnels are free and ephemeral.
+ */
+export interface RunCloudflareTunnelOptions {
+  /** Gateway port to forward. Defaults to the global GATEWAY_PORT. */
+  port?: number;
+  /** Workspace directory for config read/write. Defaults to ~/.vellum/workspace. */
+  workspaceDir?: string;
+}
+
+export async function runCloudflareTunnel(
+  opts: RunCloudflareTunnelOptions = {},
+): Promise<void> {
+  const version = getCloudflareTunnelVersion();
+  if (!version) {
+    console.error("Error: cloudflared is not installed.");
+    console.error("");
+    console.error("Install cloudflared:");
+    console.error("  macOS:   brew install cloudflare/cloudflare/cloudflared");
+    console.error("  Linux:   https://pkg.cloudflare.com/index.html");
+    console.error(
+      "  Windows: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
+    );
+    console.error("");
+    console.error("No Cloudflare account is required for quick tunnels.");
+    process.exit(1);
+  }
+
+  console.log(`Using ${version}`);
+
+  const port = opts.port ?? GATEWAY_PORT;
+  const workspaceDir = opts.workspaceDir ?? getDefaultWorkspaceDir();
+
+  console.log(`Starting cloudflared quick tunnel to localhost:${port}...`);
+  console.log("No Cloudflare account required — quick tunnels are free.");
+  console.log("");
+
+  let publicUrl: string | undefined;
+  const child = startCloudflareTunnelProcess(port);
+
+  const cleanup = (): void => {
+    if (!child.killed) child.kill("SIGTERM");
+    if (publicUrl) {
+      console.log("\nClearing ingress URL from config...");
+      clearIngressUrl(workspaceDir);
+    }
+  };
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  child.on("error", (err: Error) => {
+    console.error(`cloudflared process error: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    // Always clear the saved ingress URL when the tunnel process ends so
+    // webhook integrations don't keep hitting a dead endpoint.
+    if (publicUrl !== undefined) {
+      clearIngressUrl(workspaceDir);
+    }
+    if (code !== null && code !== 0) {
+      console.error(`\ncloudflared exited with code ${code}.`);
+      process.exit(1);
+    }
+  });
+
+  // Forward cloudflared output to the console so the user can see startup
+  // progress and any authentication errors.
+  child.stdout?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+  child.stderr?.on("data", (data: Buffer) => {
+    const line = data.toString().trim();
+    if (line) console.log(`[cloudflared] ${line}`);
+  });
+
+  try {
+    publicUrl = await waitForCloudflareTunnelUrl(child);
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  console.log("");
+  console.log(`Tunnel established: ${publicUrl}`);
+  console.log(`Forwarding to:     localhost:${port}`);
+  console.log("");
+
+  saveIngressUrl(workspaceDir, publicUrl);
+  console.log("Ingress URL saved to config.");
+  console.log("");
+  console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");
+
+  // Keep running until cloudflared exits (e.g., network error or user Ctrl+C)
+  await new Promise<void>((resolve) => {
+    child.on("exit", () => resolve());
+  });
+}

package/src/lib/confirm-action.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared interactive confirmation for destructive CLI commands (retire, unpair,
+ * …). Per cli/AGENTS.md, a command that removes assistant state must print the
+ * resolved identity and require confirmation, with a `--yes` bypass for
+ * automation.
+ */
+
+/** True only when we can run an interactive raw-mode confirmation prompt. */
+export function canPromptForConfirmation(): boolean {
+  return (
+    process.stdin.isTTY === true &&
+    process.stdout.isTTY === true &&
+    typeof process.stdin.setRawMode === "function"
+  );
+}
+
+/**
+ * Show `prompt` and resolve true on Enter, false on Esc/q/Ctrl-C. Restores the
+ * prior stdin raw/paused state on exit. Caller must gate on
+ * {@link canPromptForConfirmation} first.
+ */
+export async function confirmAction(prompt: string): Promise<boolean> {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+  const wasRaw = stdin.isRaw === true;
+  const wasPaused = stdin.isPaused();
+
+  stdout.write(prompt);
+  stdin.setRawMode(true);
+  stdin.resume();
+
+  return await new Promise<boolean>((resolve) => {
+    const cleanup = () => {
+      stdin.off("data", onData);
+      stdin.setRawMode(wasRaw);
+      if (wasPaused) {
+        stdin.pause();
+      }
+      stdout.write("\n");
+    };
+
+    const onData = (chunk: Buffer) => {
+      const byte = chunk[0];
+      if (byte === 13 || byte === 10) {
+        cleanup();
+        resolve(true);
+        return;
+      }
+      if (byte === 27 || byte === 3 || byte === 113 || byte === 81) {
+        cleanup();
+        resolve(false);
+      }
+    };
+
+    stdin.on("data", onData);
+  });
+}

package/src/lib/docker.ts

@@ -478,6 +478,17 @@ export async function retireDocker(name: string): Promise<void> {
     }
   }
 
+  // Future: consider stopping Colima VM when no Docker instances remain.
+  // Considerations:
+  // - Use loadAllAssistantsAcrossEnvs() instead of loadAllAssistants() to
+  //   avoid stopping Colima while another VELLUM_ENVIRONMENT still has a
+  //   running Docker instance.
+  // - Track whether Vellum started Colima (vs. the user already had it
+  //   running for non-Vellum workloads) \u2014 e.g. via a dedicated Colima
+  //   profile (`colima start --profile vellum`) or a sentinel file.
+  // - Only stop if both conditions are met: no cross-env Docker instances
+  //   AND Vellum owns the Colima lifecycle.
+
   console.log(`\u2705 Docker instance retired.`);
 }
 
@@ -1137,7 +1148,20 @@ export async function hatchDocker(
           await loadImageViaHost(HOST_IMAGE_LOADER_URL, ref, log);
         } else {
           log(`   ↪ pulling ${ref}`);
-          await exec("docker", ["pull", ref]);
+          const MAX_PULL_RETRIES = 3;
+          for (let attempt = 1; attempt <= MAX_PULL_RETRIES; attempt++) {
+            try {
+              await exec("docker", ["pull", ref]);
+              break;
+            } catch (err) {
+              if (attempt === MAX_PULL_RETRIES) throw err;
+              const delaySec = 2 ** attempt;
+              log(
+                `   ⚠ pull failed (attempt ${attempt}/${MAX_PULL_RETRIES}), retrying in ${delaySec}s...`,
+              );
+              await new Promise((r) => setTimeout(r, delaySec * 1000));
+            }
+          }
         }
       }
       log("✅ Docker images acquired");

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

@@ -27,7 +27,8 @@ const {
   getLockfilePaths,
   getMultiInstanceDir,
 } = await import("../paths.js");
-type EnvironmentDefinition = import("../types.js").EnvironmentDefinition;
+type EnvironmentDefinition =
+  import("@vellumai/environments").EnvironmentDefinition;
 
 const prod: EnvironmentDefinition = {
   name: "production",

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

@@ -1,7 +1,8 @@
 import { describe, expect, test } from "bun:test";
 
+import { SEEDS } from "@vellumai/environments";
+
 import { getDefaultPorts } from "../paths.js";
-import { SEEDS } from "../seeds.js";
 
 describe("SEEDS port blocks", () => {
   test("production uses the legacy (pre-MVP) port layout", () => {

package/src/lib/environments/paths.ts

@@ -1,7 +1,7 @@
 import { homedir } from "os";
 import { join } from "path";
 
-import type { EnvironmentDefinition, PortMap } from "./types.js";
+import type { EnvironmentDefinition, PortMap } from "@vellumai/environments";
 
 const PRODUCTION_ENVIRONMENT_NAME = "production";
 

package/src/lib/environments/resolve.ts

@@ -1,49 +1,27 @@
+import { mkdirSync, unlinkSync, writeFileSync } from "fs";
+import { dirname } from "path";
+
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
 import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  unlinkSync,
-  writeFileSync,
-} from "fs";
-import { homedir } from "os";
-import { dirname, join } from "path";
-
-import { SEEDS } from "./seeds.js";
-import type { EnvironmentDefinition } from "./types.js";
+  defaultEnvironmentFilePath,
+  readDefaultEnvironment as readPersistedDefaultEnvironment,
+} from "@vellumai/local-mode";
 
 const DEFAULT_ENVIRONMENT_NAME = "production";
 
-/**
- * Path to the user's persisted default environment file.
- * Lives at `~/.config/vellum/environment` — a fixed, environment-agnostic
- * location so it can be read before the environment is resolved.
- */
-function getDefaultEnvironmentPath(): string {
-  const xdgConfig =
-    process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-  return join(xdgConfig, "vellum", "environment");
-}
-
 /**
  * Read the persisted default environment name, if any.
  * Returns `undefined` if no file exists or the file is empty.
  */
 export function readDefaultEnvironment(): string | undefined {
-  const filePath = getDefaultEnvironmentPath();
-  try {
-    if (!existsSync(filePath)) return undefined;
-    const content = readFileSync(filePath, "utf-8").trim();
-    return content.length > 0 ? content : undefined;
-  } catch {
-    return undefined;
-  }
+  return readPersistedDefaultEnvironment(process.env);
 }
 
 /**
  * Persist a default environment name to the user config file.
  */
 export function writeDefaultEnvironment(name: string): void {
-  const filePath = getDefaultEnvironmentPath();
+  const filePath = defaultEnvironmentFilePath(process.env);
   mkdirSync(dirname(filePath), { recursive: true });
   writeFileSync(filePath, name + "\n", "utf-8");
 }
@@ -52,7 +30,7 @@ export function writeDefaultEnvironment(name: string): void {
  * Remove the persisted default environment file, falling back to production.
  */
 export function clearDefaultEnvironment(): void {
-  const filePath = getDefaultEnvironmentPath();
+  const filePath = defaultEnvironmentFilePath(process.env);
   try {
     unlinkSync(filePath);
   } catch {
@@ -115,7 +93,7 @@ export function getCurrentEnvironment(
       // writers don't end up in disjoint states on a typo.
       process.stderr.write(
         `warning: unknown environment "${name}"; falling back to "${DEFAULT_ENVIRONMENT_NAME}". ` +
-          `Add it to cli/src/lib/environments/seeds.ts and rebuild if this was intentional.\n`,
+          `Add it to packages/environments/src/seeds.ts and rebuild if this was intentional.\n`,
       );
     }
     const fallback = SEEDS[DEFAULT_ENVIRONMENT_NAME];
@@ -174,5 +152,3 @@ export function resolveEnvironmentSource(override?: string): {
   }
   return { name: DEFAULT_ENVIRONMENT_NAME, source: "default" };
 }
-
-

package/src/lib/guardian-token.ts

@@ -2,18 +2,24 @@ import { createHash, randomUUID } from "node:crypto";
 import { execSync } from "node:child_process";
 import {
   chmodSync,
+  closeSync,
   existsSync,
   mkdirSync,
+  openSync,
   readFileSync,
+  rmdirSync,
   statSync,
+  unlinkSync,
   writeFileSync,
+  writeSync,
 } from "fs";
 import { platform } from "os";
 import { dirname, join } from "path";
 
+import { SEEDS } from "@vellumai/environments";
+
 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";
 
@@ -40,6 +46,27 @@ function getGuardianTokenPath(assistantId: string): string {
   );
 }
 
+/**
+ * Best-effort removal of an assistant's stored guardian token (used by
+ * `vellum unpair` to forget a paired connection). Never throws if the token
+ * file or its per-assistant directory is already absent.
+ */
+export function deleteGuardianToken(assistantId: string): void {
+  const tokenPath = getGuardianTokenPath(assistantId);
+  try {
+    unlinkSync(tokenPath);
+  } catch {
+    /* already gone */
+  }
+  // Clean up the now-empty per-assistant directory; rmdir throws if it still
+  // holds other files, in which case we leave it.
+  try {
+    rmdirSync(dirname(tokenPath));
+  } catch {
+    /* not empty or absent */
+  }
+}
+
 function getPersistedDeviceIdPath(): string {
   return join(getConfigDir(getCurrentEnvironment()), "device-id");
 }
@@ -160,42 +187,136 @@ export function saveGuardianToken(
   chmodSync(tokenPath, 0o600);
 }
 
+/** Abort the refresh POST if the gateway is slow/unreachable (it's now on the
+ *  hot request path, so it must never hang indefinitely). */
+const REFRESH_FETCH_TIMEOUT_MS = 15_000;
+/** Max time to wait for the per-assistant refresh lock before proceeding. */
+const REFRESH_LOCK_WAIT_MS = 10_000;
+/** A lock older than this is treated as stale (holder crashed) and stolen. */
+const REFRESH_LOCK_STALE_MS = 30_000;
+const REFRESH_LOCK_POLL_MS = 100;
+
+function getRefreshLockPath(assistantId: string): string {
+  return join(dirname(getGuardianTokenPath(assistantId)), "refresh.lock");
+}
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Best-effort exclusive cross-process lock for a per-assistant token refresh.
+ * Created atomically with `wx`; a stale lock (crashed holder) is stolen.
+ * Returns true if acquired, false if it timed out (caller proceeds degraded).
+ */
+async function acquireRefreshLock(lockPath: string): Promise<boolean> {
+  mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + REFRESH_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      const fd = openSync(lockPath, "wx", 0o600);
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      return true;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") return false;
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > REFRESH_LOCK_STALE_MS) {
+          unlinkSync(lockPath); // steal a stale lock, then retry
+          continue;
+        }
+      } catch {
+        continue; // lock vanished between open and stat — retry
+      }
+      if (Date.now() >= deadline) return false;
+      await delay(REFRESH_LOCK_POLL_MS);
+    }
+  }
+}
+
+function releaseRefreshLock(lockPath: string): void {
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    /* already released/stolen */
+  }
+}
+
 /**
  * Call POST /v1/guardian/refresh on the remote gateway to obtain a new
  * access token using an existing (possibly expired) access token for auth.
  * Returns the refreshed token data (persisted locally), or null if the
  * refresh fails (e.g. no stored token, or refresh token itself is expired).
+ *
+ * Concurrency-safe: the gateway rotates refresh tokens and treats reuse of an
+ * already-rotated token as replay (revoking the whole token family), so two
+ * processes (e.g. `vellum message` + `vellum events`) refreshing the same
+ * stored token at once would self-revoke and force re-pairing. We serialize on
+ * a per-assistant lock and, once held, re-read the stored token: if another
+ * process already rotated it while we waited, we return that fresh token
+ * instead of replaying our now-stale refresh token.
  */
 export async function refreshGuardianToken(
   gatewayUrl: string,
   assistantId: string,
 ): Promise<GuardianTokenData | null> {
-  const tokenData = loadGuardianToken(assistantId);
-  if (!tokenData) return null;
+  const before = loadGuardianToken(assistantId);
+  if (!before) return null;
 
   // Gateway persists expiresAt as epoch-ms numbers; Date.parse("1234567890000")
   // returns NaN. new Date() accepts both ISO strings and epoch-ms numbers.
-  const refreshExpiry = new Date(tokenData.refreshTokenExpiresAt).getTime();
-  if (!Number.isFinite(refreshExpiry) || refreshExpiry <= Date.now()) return null;
+  const refreshExpiry = new Date(before.refreshTokenExpiresAt).getTime();
+  if (!Number.isFinite(refreshExpiry) || refreshExpiry <= Date.now())
+    return null;
 
+  const lockPath = getRefreshLockPath(assistantId);
+  const locked = await acquireRefreshLock(lockPath);
   try {
+    // Re-read under the lock: a concurrent process may have rotated the token
+    // while we waited. If the stored refresh token changed, ours is now stale
+    // (replaying it would trip reuse-detection) — use the fresh token instead.
+    const current = loadGuardianToken(assistantId);
+    if (current && current.refreshToken !== before.refreshToken) {
+      return current;
+    }
+
+    // We did NOT acquire the lock (another process is likely mid-refresh) and
+    // the stored token hasn't been rotated yet. Do NOT call the gateway: our
+    // refresh token may be the one the winner is rotating right now, and
+    // replaying a rotated token revokes the whole family (forcing re-pair).
+    // Give up — the caller surfaces the original 401, and the next attempt
+    // picks up the winner's persisted token.
+    if (!locked) return null;
+
+    const tokenData = current ?? before;
+
     const response = await fetch(`${gatewayUrl}/v1/guardian/refresh`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${tokenData.accessToken}`,
       },
-      body: JSON.stringify({ refreshToken: tokenData.refreshToken }),
+      body: JSON.stringify({
+        refreshToken: tokenData.refreshToken,
+        // The refresh token is device-bound; send the device id used at init
+        // (falling back to a fresh computation for tokens persisted before the
+        // field was stored) so the gateway can verify the binding.
+        deviceId: tokenData.deviceId || computeDeviceId(),
+      }),
+      signal: AbortSignal.timeout(REFRESH_FETCH_TIMEOUT_MS),
     });
     if (!response.ok) return null;
 
     const json = (await response.json()) as Record<string, unknown>;
     const refreshed: GuardianTokenData = {
-      guardianPrincipalId: (json.guardianPrincipalId as string) ?? tokenData.guardianPrincipalId,
+      guardianPrincipalId:
+        (json.guardianPrincipalId as string) ?? tokenData.guardianPrincipalId,
       accessToken: json.accessToken as string,
-      accessTokenExpiresAt: (json.accessTokenExpiresAt as string | number) ?? tokenData.accessTokenExpiresAt,
+      accessTokenExpiresAt:
+        (json.accessTokenExpiresAt as string | number) ??
+        tokenData.accessTokenExpiresAt,
       refreshToken: (json.refreshToken as string) ?? tokenData.refreshToken,
-      refreshTokenExpiresAt: (json.refreshTokenExpiresAt as string | number) ?? tokenData.refreshTokenExpiresAt,
+      refreshTokenExpiresAt:
+        (json.refreshTokenExpiresAt as string | number) ??
+        tokenData.refreshTokenExpiresAt,
       refreshAfter: (json.refreshAfter as string) ?? tokenData.refreshAfter,
       isNew: false,
       deviceId: tokenData.deviceId,
@@ -205,6 +326,8 @@ export async function refreshGuardianToken(
     return refreshed;
   } catch {
     return null;
+  } finally {
+    if (locked) releaseRefreshLock(lockPath);
   }
 }