@vellumai/cli 0.8.10-dev.202606110317.792ac3c → 0.8.10-dev.202606110544.2aed335

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

@@ -64,3 +64,16 @@ export function resolveConfigDir(
   }
   return path.join(xdgConfigHome, `vellum-${vellumEnv}`);
 }
+
+/**
+ * The on-disk location of an assistant's guardian token, given an already
+ * resolved config dir. The single source of truth for this path so the CLI
+ * writer and every host-seam reader agree — a divergence here is what leaves a
+ * freshly leased token unreadable and bricks the connect.
+ */
+export function guardianTokenPath(
+  configDir: string,
+  assistantId: string,
+): string {
+  return path.join(configDir, "assistants", assistantId, "guardian-token.json");
+}

package/node_modules/@vellumai/local-mode/src/guardian-token.ts

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
-import path from "node:path";
 
+import { guardianTokenPath } from "./config";
 import type { CliInvocation } from "./util";
 
 const GUARDIAN_TOKEN_REFRESH_TIMEOUT_MS = 15_000;
@@ -40,7 +40,7 @@ export function getGuardianAccessToken(
     return Promise.resolve({ ok: false, status: 403, error: "Forbidden" });
   }
 
-  const tokenPath = path.join(configDir, "assistants", assistantId, "guardian-token.json");
+  const tokenPath = guardianTokenPath(configDir, assistantId);
 
   let raw: string;
   try {

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

@@ -14,7 +14,7 @@ export {
   resolveDevCliInvocation,
 } from "./util";
 export type { CliInvocation } from "./util";
-export { resolveLocalConfigFromEnv, resolveLockfilePaths, resolveConfigDir } from "./config";
+export { resolveLocalConfigFromEnv, resolveLockfilePaths, resolveConfigDir, guardianTokenPath } from "./config";
 export type { LocalEndpointConfig } from "./config";
 export { defaultEnvironmentFilePath, readDefaultEnvironment, resolveEnvironmentName } from "./environment";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.10-dev.202606110317.792ac3c",
+  "version": "0.8.10-dev.202606110544.2aed335",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/guardian-token.test.ts

@@ -11,6 +11,8 @@ import {
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
+import { guardianTokenPath, resolveConfigDir } from "@vellumai/local-mode";
+
 import {
   getOrCreatePersistedDeviceId,
   guardianTokenDueForRenewal,
@@ -20,6 +22,8 @@ import {
   seedGuardianTokenFromSiblingEnv,
   type GuardianTokenData,
 } from "../lib/guardian-token.js";
+import { getConfigDir } from "../lib/environments/paths.js";
+import { getCurrentEnvironment } from "../lib/environments/resolve.js";
 
 function makeTokenData(suffix: string): GuardianTokenData {
   const now = new Date().toISOString();
@@ -473,3 +477,78 @@ describe("guardianTokenDueForRenewal", () => {
     ).toBe(false);
   });
 });
+
+// Drift guard between the guardian-token WRITE path (CLI: getGuardianTokenPath
+// → getConfigDir(getCurrentEnvironment())) and the READ path used by every
+// host-seam reader (getGuardianAccessToken → resolveConfigDir(env) from
+// @vellumai/local-mode). A divergence here writes a freshly leased token where
+// the connect can't read it, bricking local-assistant connect. saveGuardianToken
+// already resolves through the shared resolver; this asserts the two resolvers
+// stay in lockstep so a future change to either can't silently relocate tokens.
+describe("guardian-token path resolver parity (CLI ↔ shared)", () => {
+  let tempHome: string;
+  let savedXdg: string | undefined;
+  let savedEnv: string | undefined;
+
+  beforeEach(() => {
+    savedXdg = process.env.XDG_CONFIG_HOME;
+    savedEnv = process.env.VELLUM_ENVIRONMENT;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-guardian-parity-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    delete process.env.VELLUM_ENVIRONMENT;
+  });
+
+  afterEach(() => {
+    if (savedXdg === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = savedXdg;
+    if (savedEnv === undefined) delete process.env.VELLUM_ENVIRONMENT;
+    else process.env.VELLUM_ENVIRONMENT = savedEnv;
+    rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  // The CLI's own resolver and the shared @vellumai/local-mode resolver must
+  // agree on the config dir for every environment source.
+  const expectResolversAgree = () => {
+    expect(getConfigDir(getCurrentEnvironment())).toBe(
+      resolveConfigDir(process.env),
+    );
+  };
+
+  test("unset → production: resolvers agree and saveGuardianToken lands there", () => {
+    expectResolversAgree();
+    saveGuardianToken("alpha", makeTokenData("prod"));
+    expect(
+      existsSync(guardianTokenPath(resolveConfigDir(process.env), "alpha")),
+    ).toBe(true);
+  });
+
+  test("VELLUM_ENVIRONMENT=dev: resolvers agree and token lands there", () => {
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    expectResolversAgree();
+    saveGuardianToken("alpha", makeTokenData("dev"));
+    expect(
+      existsSync(guardianTokenPath(resolveConfigDir(process.env), "alpha")),
+    ).toBe(true);
+  });
+
+  test("VELLUM_ENVIRONMENT=local: resolvers agree and token lands there", () => {
+    process.env.VELLUM_ENVIRONMENT = "local";
+    expectResolversAgree();
+    saveGuardianToken("alpha", makeTokenData("local"));
+    expect(
+      existsSync(guardianTokenPath(resolveConfigDir(process.env), "alpha")),
+    ).toBe(true);
+  });
+
+  test("persisted default env file (no VELLUM_ENVIRONMENT): resolvers agree", () => {
+    // Mirror `vellum env set dev`: the default-env file lives at the fixed,
+    // env-agnostic path $XDG_CONFIG_HOME/vellum/environment.
+    mkdirSync(join(tempHome, "vellum"), { recursive: true });
+    writeFileSync(join(tempHome, "vellum", "environment"), "dev\n");
+    expectResolversAgree();
+    saveGuardianToken("alpha", makeTokenData("default-dev"));
+    expect(
+      existsSync(guardianTokenPath(resolveConfigDir(process.env), "alpha")),
+    ).toBe(true);
+  });
+});

package/src/__tests__/wake.test.ts

@@ -58,10 +58,27 @@ mock.module("../lib/docker.js", () => ({
 const seedGuardianTokenFromSiblingEnvMock = mock<
   typeof guardianToken.seedGuardianTokenFromSiblingEnv
 >(() => false);
+// Default: a token exists, so the re-provision recovery path is skipped. Tests
+// that exercise recovery override loadGuardianToken to return null.
+const loadGuardianTokenMock = mock<typeof guardianToken.loadGuardianToken>(
+  () => ({ accessToken: "existing" }) as ReturnType<
+    typeof guardianToken.loadGuardianToken
+  >,
+);
+const resetGuardianBootstrapMock = mock<
+  typeof guardianToken.resetGuardianBootstrap
+>(async () => {});
+const leaseGuardianTokenMock = mock<typeof guardianToken.leaseGuardianToken>(
+  async () =>
+    ({}) as Awaited<ReturnType<typeof guardianToken.leaseGuardianToken>>,
+);
 
 mock.module("../lib/guardian-token.js", () => ({
   ...realGuardianToken,
   seedGuardianTokenFromSiblingEnv: seedGuardianTokenFromSiblingEnvMock,
+  loadGuardianToken: loadGuardianTokenMock,
+  resetGuardianBootstrap: resetGuardianBootstrapMock,
+  leaseGuardianToken: leaseGuardianTokenMock,
 }));
 
 const resolveProcessStateMock = mock<typeof processLib.resolveProcessState>(
@@ -169,6 +186,16 @@ beforeEach(() => {
   startGatewayMock.mockResolvedValue("http://127.0.0.1:7830");
   seedGuardianTokenFromSiblingEnvMock.mockReset();
   seedGuardianTokenFromSiblingEnvMock.mockReturnValue(false);
+  loadGuardianTokenMock.mockReset();
+  loadGuardianTokenMock.mockReturnValue({ accessToken: "existing" } as ReturnType<
+    typeof guardianToken.loadGuardianToken
+  >);
+  resetGuardianBootstrapMock.mockReset();
+  resetGuardianBootstrapMock.mockResolvedValue(undefined);
+  leaseGuardianTokenMock.mockReset();
+  leaseGuardianTokenMock.mockResolvedValue(
+    {} as Awaited<ReturnType<typeof guardianToken.leaseGuardianToken>>,
+  );
   maybeStartNgrokTunnelMock.mockReset();
   maybeStartNgrokTunnelMock.mockResolvedValue(null);
 });
@@ -212,4 +239,45 @@ describe("vellum wake", () => {
       },
     );
   });
+
+  test("re-provisions the guardian token when missing and --repair-guardian is passed", async () => {
+    process.argv = ["bun", "vellum", "wake", "--repair-guardian", "local-assistant"];
+    loadGuardianTokenMock.mockReturnValue(null);
+
+    await wake();
+
+    // Resets the gateway's spent bootstrap state, then re-leases against the
+    // loopback gateway with the lockfile's bootstrap secret.
+    expect(resetGuardianBootstrapMock).toHaveBeenCalledWith(
+      "http://127.0.0.1:7830",
+      "generated-bootstrap-secret",
+    );
+    expect(leaseGuardianTokenMock).toHaveBeenCalledWith(
+      "http://127.0.0.1:7830",
+      "local-assistant",
+      "generated-bootstrap-secret",
+    );
+  });
+
+  test("does NOT re-provision without --repair-guardian, even when the token is missing", async () => {
+    // The automatic connect-repair path spawns `wake <id>` with no flags. A
+    // re-lease here would revoke other device-bound tokens (other tabs / local
+    // clients), so it must never run from auto-repair.
+    process.argv = ["bun", "vellum", "wake", "local-assistant"];
+    loadGuardianTokenMock.mockReturnValue(null);
+
+    await wake();
+
+    expect(resetGuardianBootstrapMock).not.toHaveBeenCalled();
+    expect(leaseGuardianTokenMock).not.toHaveBeenCalled();
+  });
+
+  test("skips re-provision when a guardian token already exists", async () => {
+    process.argv = ["bun", "vellum", "wake", "--repair-guardian", "local-assistant"];
+    // loadGuardianToken returns a token by default — recovery must not run.
+    await wake();
+
+    expect(resetGuardianBootstrapMock).not.toHaveBeenCalled();
+    expect(leaseGuardianTokenMock).not.toHaveBeenCalled();
+  });
 });

package/src/commands/backup.ts

@@ -16,6 +16,7 @@ import {
   platformRequestSignedUrl,
   readPlatformToken,
 } from "../lib/platform-client.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 export async function backup(): Promise<void> {
   const args = process.argv.slice(3);
@@ -112,7 +113,7 @@ export async function backup(): Promise<void> {
   // Call the export endpoint
   let response: Response;
   try {
-    response = await fetch(`${entry.runtimeUrl}/v1/migrations/export`, {
+    response = await loopbackSafeFetch(`${entry.runtimeUrl}/v1/migrations/export`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${accessToken}`,
@@ -138,7 +139,7 @@ export async function backup(): Promise<void> {
       }
       if (refreshedToken) {
         accessToken = refreshedToken;
-        response = await fetch(`${entry.runtimeUrl}/v1/migrations/export`, {
+        response = await loopbackSafeFetch(`${entry.runtimeUrl}/v1/migrations/export`, {
           method: "POST",
           headers: {
             Authorization: `Bearer ${accessToken}`,

package/src/commands/client.ts

@@ -56,6 +56,7 @@ import {
   readPlatformToken,
 } from "../lib/platform-client";
 import { tuiLog } from "../lib/tui-log";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
@@ -619,7 +620,7 @@ async function handleLocalEndpoints(
 
     try {
       const hasBody = req.method !== "GET" && req.method !== "HEAD";
-      const proxyRes = await fetch(targetUrl, {
+      const proxyRes = await loopbackSafeFetch(targetUrl, {
         method: req.method,
         headers,
         body: hasBody ? req.body : undefined,
@@ -760,7 +761,7 @@ async function runWebInterface(
         try {
           const hasBody = req.method !== "GET" && req.method !== "HEAD";
           const body = hasBody ? await req.arrayBuffer() : undefined;
-          const proxyRes = await fetch(target.toString(), {
+          const proxyRes = await loopbackSafeFetch(target.toString(), {
             method: req.method,
             headers,
             body,

package/src/commands/devices.ts

@@ -28,6 +28,7 @@ import {
   canPromptForConfirmation,
   confirmAction,
 } from "../lib/confirm-action.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 interface DeviceRecord {
   hashedDeviceId: string;
@@ -108,7 +109,7 @@ async function listDevices(entry: AssistantEntry, base: string): Promise<void> {
 
   let response: Response;
   try {
-    response = await fetch(`${base}/v1/devices`, {
+    response = await loopbackSafeFetch(`${base}/v1/devices`, {
       method: "GET",
       headers: getClientRegistrationHeaders(CLI_INTERFACE_ID),
     });
@@ -186,7 +187,7 @@ async function revokeDevice(
 
   let response: Response;
   try {
-    response = await fetch(`${base}/v1/devices/revoke`, {
+    response = await loopbackSafeFetch(`${base}/v1/devices/revoke`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",

package/src/commands/pair.ts

@@ -26,6 +26,7 @@ import {
 } from "../lib/client-identity.js";
 import { GATEWAY_PORT } from "../lib/constants.js";
 import { getLocalLanIPv4 } from "../lib/local.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 function isLoopbackHost(url: string): boolean {
   try {
@@ -154,7 +155,7 @@ export async function pair(): Promise<void> {
 
   let response: Response;
   try {
-    response = await fetch(`${mintUrl}/v1/pair`, {
+    response = await loopbackSafeFetch(`${mintUrl}/v1/pair`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",

package/src/commands/restore.ts

@@ -16,6 +16,7 @@ import {
   platformPollJobStatus,
 } from "../lib/platform-client.js";
 import { performDockerRollback } from "../lib/upgrade-lifecycle.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 function printUsage(): void {
   console.log(
@@ -588,7 +589,7 @@ export async function restore(): Promise<void> {
 
     let response: Response;
     try {
-      response = await fetch(
+      response = await loopbackSafeFetch(
         `${entry.runtimeUrl}/v1/migrations/import-preflight`,
         {
           method: "POST",
@@ -694,7 +695,7 @@ export async function restore(): Promise<void> {
 
     let response: Response;
     try {
-      response = await fetch(`${entry.runtimeUrl}/v1/migrations/import`, {
+      response = await loopbackSafeFetch(`${entry.runtimeUrl}/v1/migrations/import`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,

package/src/commands/retire.ts

@@ -36,6 +36,7 @@ import {
   resetLogFile,
   writeToLogFile,
 } from "../lib/xdg-log.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 export { retireLocal };
 
@@ -96,7 +97,7 @@ async function retireVellum(
 
   const platformUrl = runtimeUrl || getPlatformUrl();
   const url = `${platformUrl}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
-  const response = await fetch(url, {
+  const response = await loopbackSafeFetch(url, {
     method: "DELETE",
     headers: await authHeaders(token, runtimeUrl),
   });

package/src/commands/roadmap.ts

@@ -1,4 +1,5 @@
 import { readPlatformToken, getWebUrl } from "../lib/platform-client.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 function printUsage(): void {
   console.log("Usage: vellum roadmap <subcommand>");
@@ -88,7 +89,7 @@ async function apiFetch(
   if (options.token) headers["X-Session-Token"] = options.token;
   if (options.body) headers["Content-Type"] = "application/json";
 
-  return fetch(url, {
+  return loopbackSafeFetch(url, {
     method: options.method ?? "GET",
     headers,
     body: options.body ? JSON.stringify(options.body) : undefined,

package/src/commands/upgrade.ts

@@ -47,6 +47,7 @@ import {
   waitForReady,
 } from "../lib/upgrade-lifecycle.js";
 import { compareVersions } from "../lib/version-compat.js";
+import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
 interface UpgradeArgs {
   name: string | null;
@@ -230,7 +231,7 @@ async function upgradeDocker(
     lastWorkspaceMigrationId?: string;
   } = {};
   try {
-    const healthResp = await fetch(
+    const healthResp = await loopbackSafeFetch(
       `${entry.runtimeUrl}/healthz?include=migrations`,
       {
         signal: AbortSignal.timeout(5000),
@@ -695,7 +696,7 @@ async function upgradePlatform(
     body.version = version;
   }
 
-  const response = await fetch(url, {
+  const response = await loopbackSafeFetch(url, {
     method: "POST",
     headers,
     body: JSON.stringify(body),

package/src/commands/wake.ts

@@ -7,7 +7,12 @@ import {
   saveAssistantEntry,
 } from "../lib/assistant-config.js";
 import { dockerResourceNames, wakeContainers } from "../lib/docker.js";
-import { seedGuardianTokenFromSiblingEnv } from "../lib/guardian-token.js";
+import {
+  leaseGuardianToken,
+  loadGuardianToken,
+  resetGuardianBootstrap,
+  seedGuardianTokenFromSiblingEnv,
+} from "../lib/guardian-token.js";
 import { resolveProcessState, stopProcessByPidFile } from "../lib/process";
 import {
   generateLocalSigningKey,
@@ -37,11 +42,23 @@ export async function wake(): Promise<void> {
     console.log(
       "  --foreground   Run assistant in foreground with logs printed to terminal",
     );
+    console.log(
+      "  --repair-guardian  Re-provision the guardian token if missing (resets the\n" +
+        "                     gateway bootstrap and re-leases — REVOKES other device-bound\n" +
+        "                     tokens, so only use deliberately, never from auto-repair)",
+    );
     process.exit(0);
   }
 
   const watch = args.includes("--watch");
   const foreground = args.includes("--foreground");
+  // Re-leasing the guardian token calls guardian/init, which revokes every
+  // other device-bound token (other tabs, other local clients on this machine).
+  // Gate it behind an explicit flag so the automatic connect-repair path
+  // (`runWake` spawns `wake <id>` with no flags) can never revoke a live session
+  // — it only ever restarts + sibling-seeds. A genuine spent-bootstrap brick is
+  // recovered deliberately via `vellum wake <id> --repair-guardian`.
+  const repairGuardian = args.includes("--repair-guardian");
   const nameArg = args.find((a) => !a.startsWith("-"));
   const entry = resolveTargetAssistant(nameArg);
 
@@ -221,6 +238,37 @@ export async function wake(): Promise<void> {
     console.log("   Seeded guardian token from sibling environment.");
   }
 
+  // Last-resort recovery (explicit `--repair-guardian` only): if no guardian
+  // token exists for this env even after sibling seeding, re-provision one. The
+  // single-use bootstrap secret may already be spent — a prior connect can
+  // lease a token that's then lost, or the gateway marks the secret consumed
+  // before the client persists it — which otherwise bricks connect into a
+  // 401 → auth-rate-limit → 429 cascade with no path back short of retire+hatch.
+  // Reset the gateway's bootstrap lock+consumed state (loopback-only, authorized
+  // by the lockfile secret — mirrors the macOS client's forceReBootstrap), then
+  // re-lease. Gated behind the flag because the re-lease revokes other
+  // device-bound tokens; it must never run from the automatic repair path.
+  if (repairGuardian && !loadGuardianToken(entry.assistantId)) {
+    const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        await resetGuardianBootstrap(loopbackUrl, bootstrapSecret);
+        await leaseGuardianToken(loopbackUrl, entry.assistantId, bootstrapSecret);
+        console.log("   Re-provisioned guardian token.");
+        break;
+      } catch (err) {
+        if (attempt < maxAttempts) {
+          await new Promise((r) => setTimeout(r, 2000 * 2 ** (attempt - 1)));
+        } else {
+          console.warn(
+            `   Guardian token re-provision failed after ${maxAttempts} attempts: ${err}`,
+          );
+        }
+      }
+    }
+  }
+
   // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
   const workspaceDir = join(resources.instanceDir, ".vellum", "workspace");
   const ngrokChild = await maybeStartNgrokTunnel(

package/src/lib/assistant-client.ts

@@ -19,6 +19,7 @@ import {
   refreshGuardianToken,
   guardianTokenDueForRenewal,
 } from "./guardian-token.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const FALLBACK_RUNTIME_URL = `http://127.0.0.1:${GATEWAY_PORT}`;
@@ -203,7 +204,7 @@ export class AssistantClient {
     const doFetch = (): Promise<Response> => {
       const headers = buildHeaders();
       if (opts?.signal) {
-        return fetch(url, {
+        return loopbackSafeFetch(url, {
           method,
           headers,
           body: jsonBody,
@@ -213,7 +214,7 @@ export class AssistantClient {
       const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), timeout);
-      return fetch(url, {
+      return loopbackSafeFetch(url, {
         method,
         headers,
         body: jsonBody,

package/src/lib/backup-ops.ts

@@ -13,6 +13,7 @@ import {
   loadGuardianToken,
   refreshGuardianToken,
 } from "./guardian-token.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 /** Default backup directory following XDG convention */
 export function getBackupsDir(): string {
@@ -66,7 +67,7 @@ export async function createBackup(
       return null;
     }
 
-    let response = await fetch(`${runtimeUrl}/v1/migrations/export`, {
+    let response = await loopbackSafeFetch(`${runtimeUrl}/v1/migrations/export`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${accessToken}`,
@@ -87,7 +88,7 @@ export async function createBackup(
         return null;
       }
       accessToken = refreshed.accessToken;
-      response = await fetch(`${runtimeUrl}/v1/migrations/export`, {
+      response = await loopbackSafeFetch(`${runtimeUrl}/v1/migrations/export`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
@@ -152,7 +153,7 @@ export async function restoreBackup(
       return false;
     }
 
-    let response = await fetch(`${runtimeUrl}/v1/migrations/import`, {
+    let response = await loopbackSafeFetch(`${runtimeUrl}/v1/migrations/import`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${accessToken}`,
@@ -171,7 +172,7 @@ export async function restoreBackup(
         return false;
       }
       accessToken = refreshed.accessToken;
-      response = await fetch(`${runtimeUrl}/v1/migrations/import`, {
+      response = await loopbackSafeFetch(`${runtimeUrl}/v1/migrations/import`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,

package/src/lib/docker.ts

@@ -67,6 +67,7 @@ export {
   ASSISTANT_INTERNAL_PORT,
   GATEWAY_INTERNAL_PORT,
 } from "./environments/paths.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 /** Max time to wait for the assistant container to emit the readiness sentinel. */
 export const DOCKER_READY_TIMEOUT_MS = 5 * 60 * 1000;
@@ -1530,7 +1531,7 @@ async function waitForGatewayAndLease(opts: {
 
   while (Date.now() - start < DOCKER_READY_TIMEOUT_MS) {
     try {
-      const resp = await fetch(readyUrl, {
+      const resp = await loopbackSafeFetch(readyUrl, {
         signal: AbortSignal.timeout(5000),
       });
       if (resp.ok) {

package/src/lib/guardian-token.ts

@@ -17,9 +17,14 @@ import { platform } from "os";
 import { dirname, join } from "path";
 
 import { SEEDS } from "@vellumai/environments";
+import {
+  guardianTokenPath,
+  resolveConfigDir,
+} from "@vellumai/local-mode";
 
 import { getConfigDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 const DEVICE_ID_SALT = "vellum-assistant-host-id";
 
@@ -38,12 +43,12 @@ export interface GuardianTokenData {
 }
 
 function getGuardianTokenPath(assistantId: string): string {
-  return join(
-    getConfigDir(getCurrentEnvironment()),
-    "assistants",
-    assistantId,
-    "guardian-token.json",
-  );
+  // Resolve via the shared @vellumai/local-mode resolver — the same one every
+  // host-seam reader (`getGuardianAccessToken`) uses — so the token is always
+  // written where it's read. Must stay in lockstep with `getConfigDir(
+  // getCurrentEnvironment())`; the parity test in guardian-token.test.ts guards
+  // against drift.
+  return guardianTokenPath(resolveConfigDir(process.env), assistantId);
 }
 
 /**
@@ -342,7 +347,7 @@ export async function refreshGuardianToken(
 
     const tokenData = current ?? before;
 
-    const response = await fetch(`${gatewayUrl}/v1/guardian/refresh`, {
+    const response = await loopbackSafeFetch(`${gatewayUrl}/v1/guardian/refresh`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -402,7 +407,7 @@ export async function leaseGuardianToken(
   if (bootstrapSecret) {
     headers["x-bootstrap-secret"] = bootstrapSecret;
   }
-  const response = await fetch(`${gatewayUrl}/v1/guardian/init`, {
+  const response = await loopbackSafeFetch(`${gatewayUrl}/v1/guardian/init`, {
     method: "POST",
     headers,
     body: JSON.stringify({ platform: "cli", deviceId }),
@@ -430,6 +435,37 @@ export async function leaseGuardianToken(
   return tokenData;
 }
 
+/**
+ * Clear the gateway's guardian-init lock + consumed-secret state via
+ * `POST /v1/guardian/reset-bootstrap`, so a spent single-use bootstrap secret
+ * can be used again by a subsequent `leaseGuardianToken`. Loopback-only on the
+ * gateway; when bootstrap secrets are configured the gateway requires a
+ * matching `x-bootstrap-secret`. Mirrors the macOS client's `forceReBootstrap`
+ * recovery. Throws on a non-OK response.
+ */
+export async function resetGuardianBootstrap(
+  gatewayUrl: string,
+  bootstrapSecret?: string,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (bootstrapSecret) {
+    headers["x-bootstrap-secret"] = bootstrapSecret;
+  }
+  const response = await fetch(`${gatewayUrl}/v1/guardian/reset-bootstrap`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({}),
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(
+      `guardian/reset-bootstrap failed (${response.status}): ${body}`,
+    );
+  }
+}
+
 /**
  * Copy a guardian token from a sibling environment's config directory into
  * the current environment's dir when the current one is missing it.

package/src/lib/hatch-local.ts

@@ -44,6 +44,7 @@ import {
 } from "./provider-secrets.js";
 import { logHatchNextSteps } from "./hatch-next-steps.js";
 import { checkProviderApiKey } from "./api-key-check.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 /**
  * Attempts to place a symlink at the given path pointing to cliBinary.
@@ -358,7 +359,7 @@ export async function hatchLocal(
     while (true) {
       await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
       try {
-        const res = await fetch(healthUrl, {
+        const res = await loopbackSafeFetch(healthUrl, {
           signal: AbortSignal.timeout(3000),
         });
         if (res.ok) {

package/src/lib/health-check.ts

@@ -1,3 +1,5 @@
+import { loopbackSafeFetch } from "./loopback-fetch.js";
+
 export const HEALTH_CHECK_TIMEOUT_MS = 1500;
 
 interface HealthResponse {
@@ -44,7 +46,7 @@ export async function checkManagedHealth(
       HEALTH_CHECK_TIMEOUT_MS,
     );
 
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: controller.signal,
       headers,
     });
@@ -105,7 +107,7 @@ export async function fetchManagedPs(
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 5000);
 
-    const response = await fetch(psUrl, {
+    const response = await loopbackSafeFetch(psUrl, {
       signal: controller.signal,
       headers,
     });
@@ -144,7 +146,7 @@ async function fetchLegacyConnectionStatus(
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 5000);
 
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       method: "POST",
       signal: controller.signal,
       headers,
@@ -188,7 +190,7 @@ export async function checkHealth(
       headers["Authorization"] = `Bearer ${bearerToken}`;
     }
 
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: controller.signal,
       headers,
     });

package/src/lib/http-client.ts

@@ -1,3 +1,5 @@
+import { loopbackSafeFetch } from "./loopback-fetch.js";
+
 /**
  * Build the base URL for the daemon HTTP server.
  */
@@ -15,7 +17,7 @@ export async function httpHealthCheck(
 ): Promise<boolean> {
   try {
     const url = `${buildDaemonUrl(port)}/healthz`;
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: AbortSignal.timeout(timeoutMs),
     });
     return response.ok;

package/src/lib/local-runtime-client.ts

@@ -9,6 +9,7 @@ import {
   resolveRuntimeMigrationUrl,
   resolveRuntimeUrl,
 } from "./runtime-url.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 /**
  * Thrown when the local runtime returns 409 for an export/import request
@@ -122,7 +123,7 @@ export async function localRuntimeExportToGcs(
     body.description = params.description;
   }
 
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     resolveRuntimeMigrationUrl(entry, "export-to-gcs"),
     {
       method: "POST",
@@ -166,7 +167,7 @@ export async function localRuntimeImportFromGcs(
   token: string,
   params: { bundleUrl: string },
 ): Promise<{ jobId: string }> {
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     resolveRuntimeMigrationUrl(entry, "import-from-gcs"),
     {
       method: "POST",
@@ -211,7 +212,7 @@ export async function localRuntimePollJobStatus(
   token: string,
   jobId: string,
 ): Promise<UnifiedJobStatus> {
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     resolveRuntimeMigrationUrl(entry, `jobs/${jobId}`),
     {
       headers: await migrationRequestHeaders(entry, token),
@@ -285,7 +286,7 @@ export async function localRuntimeIdentity(
 ): Promise<RuntimeIdentity> {
   const url = resolveRuntimeUrl(entry, "health");
   const doRequest = async (): Promise<Response> =>
-    fetch(url, {
+    loopbackSafeFetch(url, {
       method: "GET",
       headers: await migrationRequestHeaders(entry, token),
     });

package/src/lib/loopback-fetch.ts

@@ -0,0 +1,28 @@
+/**
+ * Bun's fetch pools sockets even when the server responds `Connection:
+ * close` (e.g. the Werkzeug dev platform on localhost), so the next request
+ * to the same origin is written to a dead socket and hangs until its abort
+ * timeout fires. Disable keepalive for loopback targets to force a fresh
+ * connection per request; remote hosts are unaffected.
+ */
+
+function isLoopbackUrl(url: string): boolean {
+  try {
+    // WHATWG URL canonicalizes hostnames, so IPv6 loopback is always "[::1]".
+    const h = new URL(url).hostname;
+    return (
+      h === "localhost" || h === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(h)
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function loopbackSafeFetch(
+  url: string,
+  init?: RequestInit,
+): Promise<Response> {
+  return isLoopbackUrl(url)
+    ? fetch(url, { ...init, keepalive: false })
+    : fetch(url, init);
+}

package/src/lib/ngrok.ts

@@ -11,6 +11,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 function getDefaultWorkspaceDir(): string {
   return (
@@ -78,7 +79,7 @@ export function getNgrokVersion(): string | null {
  */
 async function queryNgrokTunnels(): Promise<NgrokTunnel[] | null> {
   try {
-    const res = await fetch(NGROK_API_URL, {
+    const res = await loopbackSafeFetch(NGROK_API_URL, {
       signal: AbortSignal.timeout(2_000),
     });
     if (!res.ok) return null;

package/src/lib/platform-client.ts

@@ -11,6 +11,7 @@ import { join, dirname } from "path";
 import { getLockfilePlatformBaseUrl } from "./assistant-config.js";
 import { getConfigDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 function getPlatformTokenPath(): string {
   return join(getConfigDir(getCurrentEnvironment()), "platform-token");
@@ -229,7 +230,7 @@ export async function ensureSelfHostedLocalRegistration(
     body.public_ingress_url = publicBaseUrl;
   }
 
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${resolvedUrl}/v1/assistants/self-hosted-local/ensure-registration/`,
     {
       method: "POST",
@@ -292,7 +293,7 @@ export async function reprovisionAssistantApiKey(
     body.assistant_version = assistantVersion;
   }
 
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${resolvedUrl}/v1/assistants/self-hosted-local/reprovision-api-key/`,
     {
       method: "POST",
@@ -358,7 +359,7 @@ export async function readGatewayCredential(
       headers["Authorization"] = `Bearer ${bearerToken}`;
     }
 
-    const response = await fetch(`${gatewayUrl}/v1/secrets/read`, {
+    const response = await loopbackSafeFetch(`${gatewayUrl}/v1/secrets/read`, {
       method: "POST",
       headers,
       body: JSON.stringify({ type: "credential", name, reveal: true }),
@@ -416,7 +417,7 @@ async function injectGatewayCredential(
     headers["Authorization"] = `Bearer ${bearerToken}`;
   }
 
-  const response = await fetch(`${gatewayUrl}/v1/secrets`, {
+  const response = await loopbackSafeFetch(`${gatewayUrl}/v1/secrets`, {
     method: "POST",
     headers,
     body: JSON.stringify({ type: "credential", name, value }),
@@ -486,7 +487,7 @@ export async function hatchAssistant(
   const resolvedUrl = platformUrl || getPlatformUrl();
   const url = `${resolvedUrl}/v1/assistants/hatch/`;
 
-  const response = await fetch(url, {
+  const response = await loopbackSafeFetch(url, {
     method: "POST",
     headers: await authHeaders(token, platformUrl),
     body: JSON.stringify({}),
@@ -545,7 +546,7 @@ export async function checkExistingPlatformAssistant(
   );
 
   try {
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: controller.signal,
       headers: await authHeaders(token, platformUrl),
     });
@@ -583,7 +584,7 @@ export async function fetchPlatformAssistants(
   );
 
   try {
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: controller.signal,
       headers: await authHeaders(token, platformUrl),
     });
@@ -624,7 +625,7 @@ export async function fetchOrganizationId(
   );
 
   try {
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: controller.signal,
       headers: { ...tokenAuthHeader(token) },
     });
@@ -671,7 +672,7 @@ export async function fetchCurrentUser(
   );
 
   try {
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: controller.signal,
       headers: { "X-Session-Token": token },
     });
@@ -706,11 +707,14 @@ export async function rollbackPlatformAssistant(
   platformUrl?: string,
 ): Promise<{ detail: string; version: string | null }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(`${resolvedUrl}/v1/assistants/rollback/`, {
-    method: "POST",
-    headers: await authHeaders(token, platformUrl),
-    body: JSON.stringify(version ? { version } : {}),
-  });
+  const response = await loopbackSafeFetch(
+    `${resolvedUrl}/v1/assistants/rollback/`,
+    {
+      method: "POST",
+      headers: await authHeaders(token, platformUrl),
+      body: JSON.stringify(version ? { version } : {}),
+    },
+  );
 
   const body = (await response.json().catch(() => ({}))) as {
     detail?: string;
@@ -744,7 +748,7 @@ export async function platformUploadToSignedUrl(
   uploadUrl: string,
   bundleData: Uint8Array<ArrayBuffer>,
 ): Promise<void> {
-  const response = await fetch(uploadUrl, {
+  const response = await loopbackSafeFetch(uploadUrl, {
     method: "PUT",
     headers: {
       "Content-Type": "application/octet-stream",
@@ -766,7 +770,7 @@ export async function platformImportPreflightFromGcs(
   platformUrl?: string,
 ): Promise<{ statusCode: number; body: Record<string, unknown> }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${resolvedUrl}/v1/migrations/import-preflight-from-gcs/`,
     {
       method: "POST",
@@ -789,7 +793,7 @@ export async function platformImportBundleFromGcs(
   platformUrl?: string,
 ): Promise<{ statusCode: number; body: Record<string, unknown> }> {
   const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${resolvedUrl}/v1/migrations/import-from-gcs/`,
     {
       method: "POST",
@@ -970,7 +974,7 @@ export async function platformRequestSignedUrl(
   }
 
   const doRequest = async (): Promise<Response> =>
-    fetch(`${resolvedUrl}/v1/migrations/signed-url/`, {
+    loopbackSafeFetch(`${resolvedUrl}/v1/migrations/signed-url/`, {
       method: "POST",
       headers: await authHeaders(token, platformUrl),
       body: JSON.stringify(body),
@@ -1040,9 +1044,12 @@ export async function platformPollJobStatus(
   platformUrl?: string,
 ): Promise<UnifiedJobStatus> {
   const resolvedUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(`${resolvedUrl}/v1/migrations/jobs/${jobId}/`, {
-    headers: await authHeaders(token, platformUrl),
-  });
+  const response = await loopbackSafeFetch(
+    `${resolvedUrl}/v1/migrations/jobs/${jobId}/`,
+    {
+      headers: await authHeaders(token, platformUrl),
+    },
+  );
 
   if (response.status === 404) {
     throw new Error("Migration job not found");

package/src/lib/platform-releases.ts

@@ -1,6 +1,7 @@
 import { getPlatformUrl } from "./platform-client.js";
 import { DOCKERHUB_IMAGES } from "./docker.js";
 import type { ServiceName } from "./docker.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 export interface ResolvedImageRefs {
   imageTags: Record<ServiceName, string>;
@@ -15,7 +16,7 @@ export interface ResolvedImageRefs {
 export async function fetchLatestStableVersion(): Promise<string | null> {
   try {
     const platformUrl = getPlatformUrl();
-    const response = await fetch(`${platformUrl}/v1/releases/?stable=true`, {
+    const response = await loopbackSafeFetch(`${platformUrl}/v1/releases/?stable=true`, {
       signal: AbortSignal.timeout(10_000),
     });
     if (!response.ok) return null;
@@ -80,7 +81,7 @@ async function fetchPlatformImageRefs(
 
     log?.(`Fetching releases from ${url}`);
 
-    const response = await fetch(url, {
+    const response = await loopbackSafeFetch(url, {
       signal: AbortSignal.timeout(10_000),
     });
 

package/src/lib/terminal-client.ts

@@ -7,6 +7,7 @@
  */
 
 import { authHeaders, getPlatformUrl } from "./platform-client.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 // ---------------------------------------------------------------------------
 // Create / Close
@@ -25,7 +26,7 @@ export async function createTerminalSession(
   if (service) {
     body.service = service;
   }
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/`,
     {
       method: "POST",
@@ -49,7 +50,7 @@ export async function closeTerminalSession(
   platformUrl?: string,
 ): Promise<void> {
   const baseUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/`,
     {
       method: "DELETE",
@@ -76,7 +77,7 @@ export async function sendTerminalInput(
   platformUrl?: string,
 ): Promise<void> {
   const baseUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/input/`,
     {
       method: "POST",
@@ -100,7 +101,7 @@ export async function resizeTerminalSession(
   platformUrl?: string,
 ): Promise<void> {
   const baseUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/resize/`,
     {
       method: "POST",
@@ -137,7 +138,7 @@ export async function* subscribeTerminalEvents(
   signal?: AbortSignal,
 ): AsyncGenerator<TerminalOutputEvent> {
   const baseUrl = platformUrl || getPlatformUrl();
-  const response = await fetch(
+  const response = await loopbackSafeFetch(
     `${baseUrl}/v1/assistants/${assistantId}/terminal/sessions/${sessionId}/events/`,
     {
       headers: await authHeaders(token, platformUrl),

package/src/lib/upgrade-lifecycle.ts

@@ -27,6 +27,7 @@ import {
 } from "./statefulset.js";
 import { exec, execOutput } from "./step-runner.js";
 import { compareVersions } from "./version-compat.js";
+import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 // ---------------------------------------------------------------------------
 // Failure log capture
@@ -274,7 +275,7 @@ export async function fetchCurrentVersion(
   runtimeUrl: string,
 ): Promise<string | undefined> {
   try {
-    const resp = await fetch(`${runtimeUrl}/healthz`, {
+    const resp = await loopbackSafeFetch(`${runtimeUrl}/healthz`, {
       signal: AbortSignal.timeout(5000),
     });
     if (resp.ok) {
@@ -299,7 +300,7 @@ export async function fetchAssistantIngressUrl(
 ): Promise<string | undefined> {
   if (!bearerToken) return undefined;
   try {
-    const resp = await fetch(`${runtimeUrl}/integrations/ingress/config`, {
+    const resp = await loopbackSafeFetch(`${runtimeUrl}/integrations/ingress/config`, {
       headers: { Authorization: `Bearer ${bearerToken}` },
       signal: AbortSignal.timeout(5000),
     });
@@ -341,7 +342,7 @@ export async function fetchPreviousVersion(
   try {
     const { getPlatformUrl } = await import("./platform-client.js");
     const platformUrl = getPlatformUrl();
-    const resp = await fetch(`${platformUrl}/v1/releases/?stable=true`, {
+    const resp = await loopbackSafeFetch(`${platformUrl}/v1/releases/?stable=true`, {
       signal: AbortSignal.timeout(10_000),
     });
     if (!resp.ok) return undefined;
@@ -373,7 +374,7 @@ export async function waitForReady(runtimeUrl: string): Promise<boolean> {
 
   while (Date.now() - start < DOCKER_READY_TIMEOUT_MS) {
     try {
-      const resp = await fetch(readyUrl, {
+      const resp = await loopbackSafeFetch(readyUrl, {
         signal: AbortSignal.timeout(5000),
       });
       if (resp.ok) {
@@ -419,7 +420,7 @@ export async function broadcastUpgradeEvent(
     if (token?.accessToken) {
       headers["Authorization"] = `Bearer ${token.accessToken}`;
     }
-    await fetch(`${gatewayUrl}/v1/admin/upgrade-broadcast`, {
+    await loopbackSafeFetch(`${gatewayUrl}/v1/admin/upgrade-broadcast`, {
       method: "POST",
       headers,
       body: JSON.stringify(event),
@@ -448,7 +449,7 @@ export async function commitWorkspaceViaGateway(
     if (token?.accessToken) {
       headers["Authorization"] = `Bearer ${token.accessToken}`;
     }
-    await fetch(`${gatewayUrl}/v1/admin/workspace-commit`, {
+    await loopbackSafeFetch(`${gatewayUrl}/v1/admin/workspace-commit`, {
       method: "POST",
       headers,
       body: JSON.stringify({ message }),
@@ -491,7 +492,7 @@ export async function rollbackMigrations(
       body.targetWorkspaceMigrationId = targetWorkspaceMigrationId;
     if (rollbackToRegistryCeiling) body.rollbackToRegistryCeiling = true;
 
-    const resp = await fetch(`${gatewayUrl}/v1/admin/rollback-migrations`, {
+    const resp = await loopbackSafeFetch(`${gatewayUrl}/v1/admin/rollback-migrations`, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
@@ -572,7 +573,7 @@ export async function performDockerRollback(
     lastWorkspaceMigrationId?: string;
   } = {};
   try {
-    const healthResp = await fetch(
+    const healthResp = await loopbackSafeFetch(
       `${entry.runtimeUrl}/healthz?include=migrations`,
       { signal: AbortSignal.timeout(5000) },
     );