@vellumai/cli 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/__tests__/paired-lifecycle.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Tests for the `cloud: "paired"` lifecycle guards: `vellum wake`/`vellum sleep`
+ * must refuse a remote pairing with a clear "managed on its host machine"
+ * message instead of treating it as an on-machine process.
+ */
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const testDir = mkdtempSync(join(tmpdir(), "paired-lifecycle-test-"));
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
+const ORIGINAL_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_ARGV = [...process.argv];
+
+import { saveAssistantEntry } from "../lib/assistant-config.js";
+import { retire } from "../commands/retire.js";
+import { sleep } from "../commands/sleep.js";
+import { wake } from "../commands/wake.js";
+
+function seedPairedEntry(): void {
+  saveAssistantEntry({
+    assistantId: "px",
+    name: "Paired Box",
+    runtimeUrl: "http://10.0.0.9:7830",
+    cloud: "paired",
+    paired: true,
+    species: "vellum",
+  });
+}
+
+/** Run `fn` with console.error + process.exit spied; return {exited, errors}. */
+async function runGuarded(
+  fn: () => Promise<void>,
+): Promise<{ exited: boolean; errors: string }> {
+  const errors: string[] = [];
+  const errSpy = spyOn(console, "error").mockImplementation(
+    (...a: unknown[]) => {
+      errors.push(a.join(" "));
+    },
+  );
+  const exitSpy = spyOn(process, "exit").mockImplementation(((c?: number) => {
+    throw new Error(`exit:${c}`);
+  }) as never);
+  let exited = false;
+  try {
+    await fn();
+  } catch (e) {
+    exited = (e as Error).message === "exit:1";
+  } finally {
+    errSpy.mockRestore();
+    exitSpy.mockRestore();
+  }
+  return { exited, errors: errors.join("\n") };
+}
+
+describe("paired lifecycle guards", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    process.env.XDG_CONFIG_HOME = testDir;
+    seedPairedEntry();
+  });
+
+  afterEach(() => {
+    process.argv = [...ORIGINAL_ARGV];
+    if (ORIGINAL_LOCKFILE_DIR === undefined)
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    else process.env.VELLUM_LOCKFILE_DIR = ORIGINAL_LOCKFILE_DIR;
+    if (ORIGINAL_CONFIG_HOME === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = ORIGINAL_CONFIG_HOME;
+  });
+
+  afterAll(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("wake refuses a paired entry with a host-machine message", async () => {
+    process.argv = ["bun", "vellum", "wake", "px"];
+    const { exited, errors } = await runGuarded(wake);
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("paired from another machine");
+    expect(errors).toContain("vellum client px");
+    // It must NOT fall through to the generic local/docker guard.
+    expect(errors).not.toContain("only works with local and docker");
+  });
+
+  test("sleep refuses a paired entry with a host-machine message", async () => {
+    process.argv = ["bun", "vellum", "sleep", "px"];
+    const { exited, errors } = await runGuarded(sleep);
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("paired from another machine");
+    expect(errors).toContain("vellum client px");
+    expect(errors).not.toContain("only works with local and docker");
+  });
+
+  test("retire refuses a paired entry and points to unpair", async () => {
+    process.argv = ["bun", "vellum", "retire", "px", "--yes"];
+    const { exited, errors } = await runGuarded(retire);
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("paired from another machine");
+    expect(errors).toContain("vellum unpair");
+    // It must NOT fall through to the generic "Unknown cloud type" path.
+    expect(errors).not.toContain("Unknown cloud type");
+  });
+});

package/src/__tests__/tui-midsession-refresh.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Tests for maybeRefreshAuthHeaders: the TUI's mid-session 401 -> refresh of a
+ * PAIRED assistant's guardian token, mutating the shared auth headers in place.
+ * Scoped to cloud:"paired"; skips local/docker, platform session auth, ephemeral
+ * --token, and access-only tokens.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const ORIGINAL_XDG = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_ENV = process.env.VELLUM_ENVIRONMENT;
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
+const ORIGINAL_FETCH = globalThis.fetch;
+
+import { maybeRefreshAuthHeaders } from "../components/DefaultMainScreen";
+import { saveAssistantEntry } from "../lib/assistant-config";
+import { saveGuardianToken } from "../lib/guardian-token";
+
+const RUNTIME = "http://10.0.0.9:7830";
+const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
+
+function seedEntry(cloud: string): void {
+  saveAssistantEntry({
+    assistantId: "px",
+    name: "Paired",
+    runtimeUrl: RUNTIME,
+    cloud,
+    paired: cloud === "paired",
+    species: "vellum",
+  });
+}
+
+function seedToken(accessToken: string, refreshToken: string): void {
+  saveGuardianToken("px", {
+    guardianPrincipalId: "imported",
+    accessToken,
+    accessTokenExpiresAt: future(),
+    refreshToken,
+    refreshTokenExpiresAt: refreshToken ? future() : 0,
+    refreshAfter: "",
+    isNew: false,
+    deviceId: "dev",
+    leasedAt: new Date().toISOString(),
+  });
+}
+
+function stubRefresh(ok: boolean): { hit: () => boolean } {
+  let called = false;
+  globalThis.fetch = (async (url: unknown, _init?: RequestInit) => {
+    if (String(url).includes("/v1/guardian/refresh")) {
+      called = true;
+      return new Response(
+        ok ? JSON.stringify({ accessToken: "new-acc" }) : "x",
+        {
+          status: ok ? 200 : 401,
+          headers: { "content-type": "application/json" },
+        },
+      );
+    }
+    return new Response("", { status: 200 });
+  }) as typeof fetch;
+  return { hit: () => called };
+}
+
+describe("maybeRefreshAuthHeaders", () => {
+  let tempHome: string;
+
+  beforeEach(() => {
+    tempHome = mkdtempSync(join(tmpdir(), "tui-midsession-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    // Isolate the lockfile too — saveAssistantEntry writes the prod lockfile
+    // (~/.vellum.lock.json) unless VELLUM_LOCKFILE_DIR is set, which would
+    // mutate the real user/CI lockfile.
+    process.env.VELLUM_LOCKFILE_DIR = tempHome;
+    delete process.env.VELLUM_ENVIRONMENT;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = ORIGINAL_FETCH;
+    if (ORIGINAL_XDG === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = ORIGINAL_XDG;
+    if (ORIGINAL_LOCKFILE_DIR === undefined)
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    else process.env.VELLUM_LOCKFILE_DIR = ORIGINAL_LOCKFILE_DIR;
+    if (ORIGINAL_ENV === undefined) delete process.env.VELLUM_ENVIRONMENT;
+    else process.env.VELLUM_ENVIRONMENT = ORIGINAL_ENV;
+    rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  test("refreshes a paired assistant and mutates the auth header in place", async () => {
+    seedEntry("paired");
+    seedToken("old-acc", "ref");
+    const refresh = stubRefresh(true);
+    const auth = { Authorization: "Bearer old-acc" };
+
+    const ok = await maybeRefreshAuthHeaders(RUNTIME, "px", auth);
+
+    expect(ok).toBe(true);
+    expect(auth.Authorization).toBe("Bearer new-acc");
+    expect(refresh.hit()).toBe(true);
+  });
+
+  test("does NOT refresh a local assistant (scoped to paired only)", async () => {
+    seedEntry("local");
+    seedToken("old-acc", "ref"); // even with a refreshable token
+    const refresh = stubRefresh(true);
+    const auth = { Authorization: "Bearer old-acc" };
+
+    const ok = await maybeRefreshAuthHeaders(RUNTIME, "px", auth);
+
+    expect(ok).toBe(false);
+    expect(auth.Authorization).toBe("Bearer old-acc");
+    expect(refresh.hit()).toBe(false);
+  });
+
+  test("skips platform session auth (no Authorization header)", async () => {
+    seedEntry("paired");
+    seedToken("old-acc", "ref");
+    const refresh = stubRefresh(true);
+    const auth = { "X-Session-Token": "sess" };
+
+    const ok = await maybeRefreshAuthHeaders(RUNTIME, "px", auth);
+
+    expect(ok).toBe(false);
+    expect(refresh.hit()).toBe(false);
+  });
+
+  test("skips an ephemeral token that does not match the store", async () => {
+    seedEntry("paired");
+    seedToken("stored-acc", "ref");
+    const refresh = stubRefresh(true);
+    const auth = { Authorization: "Bearer ephemeral-acc" };
+
+    const ok = await maybeRefreshAuthHeaders(RUNTIME, "px", auth);
+
+    expect(ok).toBe(false);
+    expect(auth.Authorization).toBe("Bearer ephemeral-acc");
+    expect(refresh.hit()).toBe(false);
+  });
+
+  test("skips an access-only token (no refresh credential)", async () => {
+    seedEntry("paired");
+    seedToken("old-acc", ""); // no refresh token
+    const refresh = stubRefresh(true);
+    const auth = { Authorization: "Bearer old-acc" };
+
+    const ok = await maybeRefreshAuthHeaders(RUNTIME, "px", auth);
+
+    expect(ok).toBe(false);
+    expect(refresh.hit()).toBe(false);
+  });
+
+  test("returns false and leaves auth unchanged when refresh fails", async () => {
+    seedEntry("paired");
+    seedToken("old-acc", "ref");
+    stubRefresh(false); // refresh endpoint returns non-ok
+    const auth = { Authorization: "Bearer old-acc" };
+
+    const ok = await maybeRefreshAuthHeaders(RUNTIME, "px", auth);
+
+    expect(ok).toBe(false);
+    expect(auth.Authorization).toBe("Bearer old-acc");
+  });
+});

package/src/__tests__/unpair.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Tests for `vellum unpair <name>`: forget a paired (cloud:"paired") assistant
+ * by removing its lockfile entry + guardian token. Refuses non-paired entries.
+ */
+import {
+  afterAll,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  spyOn,
+  test,
+} from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const testDir = mkdtempSync(join(tmpdir(), "unpair-test-"));
+const ORIGINAL_LOCKFILE_DIR = process.env.VELLUM_LOCKFILE_DIR;
+const ORIGINAL_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
+const ORIGINAL_ARGV = [...process.argv];
+
+import { unpair } from "../commands/unpair.js";
+import {
+  findAssistantByName,
+  saveAssistantEntry,
+} from "../lib/assistant-config.js";
+import {
+  deleteGuardianToken,
+  loadGuardianToken,
+  saveGuardianToken,
+} from "../lib/guardian-token.js";
+
+function seedToken(assistantId: string): void {
+  saveGuardianToken(assistantId, {
+    guardianPrincipalId: "imported",
+    accessToken: "acc",
+    accessTokenExpiresAt: Date.now() + 3_600_000,
+    refreshToken: "ref",
+    refreshTokenExpiresAt: Date.now() + 3_600_000,
+    refreshAfter: "",
+    isNew: false,
+    deviceId: "dev",
+    leasedAt: new Date().toISOString(),
+  });
+}
+
+/** Run unpair with console.error + process.exit spied. */
+async function runUnpair(): Promise<{ exited: boolean; errors: string }> {
+  const errors: string[] = [];
+  const logSpy = spyOn(console, "log").mockImplementation(() => {});
+  const errSpy = spyOn(console, "error").mockImplementation(
+    (...a: unknown[]) => {
+      errors.push(a.join(" "));
+    },
+  );
+  const exitSpy = spyOn(process, "exit").mockImplementation(((c?: number) => {
+    throw new Error(`exit:${c}`);
+  }) as never);
+  let exited = false;
+  try {
+    await unpair();
+  } catch (e) {
+    exited = (e as Error).message === "exit:1";
+  } finally {
+    logSpy.mockRestore();
+    errSpy.mockRestore();
+    exitSpy.mockRestore();
+  }
+  return { exited, errors: errors.join("\n") };
+}
+
+describe("vellum unpair", () => {
+  beforeEach(() => {
+    process.env.VELLUM_LOCKFILE_DIR = testDir;
+    process.env.XDG_CONFIG_HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.argv = [...ORIGINAL_ARGV];
+    if (ORIGINAL_LOCKFILE_DIR === undefined)
+      delete process.env.VELLUM_LOCKFILE_DIR;
+    else process.env.VELLUM_LOCKFILE_DIR = ORIGINAL_LOCKFILE_DIR;
+    if (ORIGINAL_CONFIG_HOME === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = ORIGINAL_CONFIG_HOME;
+  });
+
+  afterAll(() => {
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test("removes a paired entry's lockfile entry and guardian token", async () => {
+    saveAssistantEntry({
+      assistantId: "px",
+      name: "Paired Box",
+      runtimeUrl: "http://10.0.0.9:7830",
+      cloud: "paired",
+      paired: true,
+      species: "vellum",
+    });
+    seedToken("px");
+    expect(findAssistantByName("px")).not.toBeNull();
+    expect(loadGuardianToken("px")).not.toBeNull();
+
+    // Non-interactive test env → use --yes to bypass the confirmation prompt.
+    process.argv = ["bun", "vellum", "unpair", "px", "--yes"];
+    const { exited } = await runUnpair();
+
+    expect(exited).toBe(false);
+    expect(findAssistantByName("px")).toBeNull();
+    expect(loadGuardianToken("px")).toBeNull();
+  });
+
+  test("refuses to unpair without --yes in a non-interactive terminal", async () => {
+    saveAssistantEntry({
+      assistantId: "py",
+      name: "Paired Two",
+      runtimeUrl: "http://10.0.0.9:7830",
+      cloud: "paired",
+      paired: true,
+      species: "vellum",
+    });
+    seedToken("py");
+
+    process.argv = ["bun", "vellum", "unpair", "py"]; // no --yes
+    const { exited, errors } = await runUnpair();
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("--yes");
+    // Not removed — confirmation was required.
+    expect(findAssistantByName("py")).not.toBeNull();
+    expect(loadGuardianToken("py")).not.toBeNull();
+  });
+
+  test("refuses a non-paired (local) assistant and leaves it intact", async () => {
+    saveAssistantEntry({
+      assistantId: "desk",
+      name: "Desk",
+      runtimeUrl: "http://127.0.0.1:7830",
+      cloud: "local",
+      species: "vellum",
+    });
+
+    process.argv = ["bun", "vellum", "unpair", "desk"];
+    const { exited, errors } = await runUnpair();
+
+    expect(exited).toBe(true);
+    expect(errors).toContain("vellum retire");
+    expect(findAssistantByName("desk")).not.toBeNull(); // untouched
+  });
+
+  test("errors on an unknown name", async () => {
+    process.argv = ["bun", "vellum", "unpair", "nope"];
+    const { exited } = await runUnpair();
+    expect(exited).toBe(true);
+  });
+
+  test("deleteGuardianToken is a no-op when the token is absent", () => {
+    // No token seeded for this id; calling (twice) must not throw.
+    expect(() => deleteGuardianToken("ghost")).not.toThrow();
+    expect(() => deleteGuardianToken("ghost")).not.toThrow();
+  });
+});

package/src/commands/client.ts

@@ -17,7 +17,7 @@ import {
   GATEWAY_PORT,
   type Species,
 } from "../lib/constants";
-import { loadGuardianToken } from "../lib/guardian-token";
+import { loadGuardianToken, refreshGuardianToken } from "../lib/guardian-token";
 import { getLocalLanIPv4 } from "../lib/local";
 import {
   CLI_INTERFACE_ID,
@@ -32,6 +32,7 @@ import {
   runRetire,
   getGuardianAccessToken,
   parseGatewayUrl,
+  resolveGatewayProxyTarget,
   readAllowedGatewayPorts,
   isLoopbackAddr,
   resolveDevCliInvocation,
@@ -82,7 +83,8 @@ function readAssistantName(entry: AssistantEntry | null): string | undefined {
     : undefined;
 }
 
-function parseArgs(): ParsedArgs {
+// Exported for unit testing the arg/auth resolution without launching the TUI.
+export function parseArgs(): ParsedArgs {
   const args = process.argv.slice(3);
 
   const positionalName = parseAssistantTargetArg(args, [
@@ -92,6 +94,8 @@ function parseArgs(): ParsedArgs {
     "-a",
     "--interface",
     "-i",
+    "--token",
+    "-t",
   ]);
   const flagArgs: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -105,7 +109,9 @@ function parseArgs(): ParsedArgs {
         arg === "--assistant-id" ||
         arg === "-a" ||
         arg === "--interface" ||
-        arg === "-i") &&
+        arg === "-i" ||
+        arg === "--token" ||
+        arg === "-t") &&
       args[i + 1]
     ) {
       flagArgs.push(arg, args[++i]);
@@ -153,11 +159,31 @@ function parseArgs(): ParsedArgs {
   const cloud = entry?.cloud;
   const species: Species = (entry?.species as Species) ?? "vellum";
 
-  // Platform-hosted assistants use a session token; local assistants use a guardian JWT.
-  const platformToken =
-    cloud === "vellum" ? (readPlatformToken() ?? undefined) : undefined;
-  const bearerToken =
-    cloud === "vellum"
+  // Ephemeral auth: a handed-over token (e.g. from `vellum pair`) used for this
+  // session only. Resolve it BEFORE the credential lookup below so an ephemeral
+  // session never reads (or writes) the local token store.
+  let bearerTokenOverride: string | undefined;
+  for (let i = 0; i < flagArgs.length; i++) {
+    if (
+      (flagArgs[i] === "--token" || flagArgs[i] === "-t") &&
+      flagArgs[i + 1]
+    ) {
+      bearerTokenOverride = flagArgs[i + 1];
+    }
+  }
+
+  // Platform-hosted assistants (cloud "vellum") use a session token; every
+  // other topology — local, docker, and "paired" (a remote assistant paired
+  // from another machine) — uses a bearer guardian JWT. Both are skipped
+  // entirely when --token supplies the credential, so no saved creds are read.
+  const platformToken = bearerTokenOverride
+    ? undefined
+    : cloud === "vellum"
+      ? (readPlatformToken() ?? undefined)
+      : undefined;
+  const bearerToken = bearerTokenOverride
+    ? bearerTokenOverride
+    : cloud === "vellum"
       ? undefined
       : (loadGuardianToken(entry?.assistantId ?? "")?.accessToken ?? undefined);
 
@@ -247,6 +273,9 @@ ${ANSI.bold}ARGUMENTS:${ANSI.reset}
 
 ${ANSI.bold}OPTIONS:${ANSI.reset}
     -u, --url <url>            Runtime URL
+    -t, --token <jwt>          Bearer token to use for this session (e.g. from
+                              'vellum pair'). Overrides the stored token and is
+                              not persisted.
     -a, --assistant-id <id>    Assistant ID
     -i, --interface <id>       Interface identifier: cli (default) or web
     -h, --help                 Show this help message
@@ -260,6 +289,10 @@ ${ANSI.bold}EXAMPLES:${ANSI.reset}
     vellum client vellum-assistant-foo
     vellum client --url http://34.56.78.90:${GATEWAY_PORT}
     vellum client vellum-assistant-foo --url http://localhost:${GATEWAY_PORT}
+
+    # Ephemeral: connect to another machine's assistant with a paired token
+    # (no lockfile entry, nothing persisted):
+    vellum client --url http://10.0.0.196:${GATEWAY_PORT} --token <jwt>
 `);
 }
 
@@ -433,11 +466,16 @@ async function handleLocalEndpoints(
     if (req.method !== "POST") return new Response(null, { status: 405 });
 
     let species = "vellum";
+    let remote: string | undefined;
     const contentType = req.headers.get("content-type") ?? "";
     if (contentType.includes("json")) {
       try {
-        const body = (await req.json()) as { species?: string };
+        const body = (await req.json()) as {
+          species?: string;
+          remote?: string;
+        };
         if (body.species) species = body.species;
+        if (body.remote) remote = body.remote;
       } catch {
         return Response.json(
           { ok: false, error: "Invalid JSON body" },
@@ -456,7 +494,11 @@ async function handleLocalEndpoints(
       );
     }
 
-    const result = await runHatch(invocation, species);
+    const result = await runHatch(
+      invocation,
+      species,
+      remote ? { remote } : undefined,
+    );
     if (result.ok) {
       return Response.json({ ok: true, assistantId: result.assistantId });
     }
@@ -538,21 +580,21 @@ async function handleLocalEndpoints(
     return Response.json({ error: result.error }, { status: result.status });
   }
 
-  // Gateway proxy
-  const gatewayResult = parseGatewayUrl(pathname);
-  if (gatewayResult.match) {
-    if (!gatewayResult.valid) {
-      return new Response("Port must be between 1024 and 65535", {
-        status: 400,
-      });
-    }
-    const { target: gatewayTarget } = gatewayResult;
-    const allowedPorts = readAllowedGatewayPorts(lockfilePaths);
-    if (!allowedPorts.has(gatewayTarget.port)) {
-      return new Response("Gateway port is not active in lockfile", {
-        status: 403,
-      });
-    }
+  // Gateway proxy — same allowlist decision the web (Vite middleware) and
+  // Electron (`app://` handler) hosts use, so all three can't drift.
+  const gatewayDecision = resolveGatewayProxyTarget(pathname, () =>
+    readAllowedGatewayPorts(lockfilePaths),
+  );
+  if (gatewayDecision.kind === "invalid-port") {
+    return new Response("Port must be between 1024 and 65535", { status: 400 });
+  }
+  if (gatewayDecision.kind === "forbidden-port") {
+    return new Response("Gateway port is not active in lockfile", {
+      status: 403,
+    });
+  }
+  if (gatewayDecision.kind === "forward") {
+    const { target: gatewayTarget } = gatewayDecision;
     const targetUrl = `http://127.0.0.1:${gatewayTarget.port}${gatewayTarget.path}${url.search}`;
     const headers = new Headers(req.headers);
     headers.set("host", `127.0.0.1:${gatewayTarget.port}`);
@@ -779,6 +821,42 @@ async function runViteDevServer(webSourceDir: string): Promise<void> {
   });
 }
 
+/**
+ * Return a possibly-refreshed bearer token for the TUI's startup auth.
+ *
+ * Only a STORED guardian token is refreshable: platform session auth
+ * (`cloud === "vellum"`) and ephemeral `--token` overrides (whose token won't
+ * match the store) are left untouched, as is a token that's still fresh. When
+ * the stored token has passed its `refreshAfter` (or expiry) and a refresh
+ * token is available, refresh once via the concurrency-safe refreshGuardianToken
+ * and use the rotated access token. Falls back to the existing token if refresh
+ * isn't possible/fails — the session still starts (same as before).
+ */
+export async function resolveFreshBearerToken(
+  runtimeUrl: string,
+  assistantId: string,
+  bearerToken: string | undefined,
+  cloud: string | undefined,
+): Promise<string | undefined> {
+  if (cloud === "vellum" || !bearerToken || !assistantId) return bearerToken;
+
+  const stored = loadGuardianToken(assistantId);
+  // Refresh only the stored token (an ephemeral --token won't match), and only
+  // when a refresh credential is present.
+  if (!stored || stored.accessToken !== bearerToken || !stored.refreshToken) {
+    return bearerToken;
+  }
+
+  // new Date() handles both ISO strings and epoch-ms numbers; Date.parse of an
+  // epoch-ms string would be NaN.
+  const renewAtRaw = stored.refreshAfter || stored.accessTokenExpiresAt;
+  const renewAt = new Date(renewAtRaw).getTime();
+  if (!Number.isFinite(renewAt) || renewAt > Date.now()) return bearerToken;
+
+  const refreshed = await refreshGuardianToken(runtimeUrl, assistantId);
+  return refreshed?.accessToken ?? bearerToken;
+}
+
 export async function client(): Promise<void> {
   const {
     runtimeUrl,
@@ -826,8 +904,19 @@ export async function client(): Promise<void> {
       ...getClientRegistrationHeaders(interfaceId),
     };
   } else {
+    // Proactively refresh a stale STORED guardian token before opening the TUI,
+    // so launching after the access token expired renews transparently rather
+    // than erroring. (Mid-session expiry — the token dying while the TUI is
+    // already open — is a separate follow-up, since the TUI threads a static
+    // auth object through React.)
+    const token = await resolveFreshBearerToken(
+      runtimeUrl,
+      assistantId,
+      bearerToken,
+      cloud,
+    );
     auth = {
-      ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
       ...getClientRegistrationHeaders(interfaceId),
     };
   }