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

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__/recover.test.ts

@@ -0,0 +1,307 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  spyOn,
+  test,
+} from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { basename, join } from "node:path";
+
+import type { AssistantEntry } from "../lib/assistant-config.js";
+import * as localModule from "../lib/local.js";
+import * as stepRunnerModule from "../lib/step-runner.js";
+
+// Captured real exports — afterAll restores these so module mocks don't
+// leak into other test files in the same `bun test` run.
+const realLocal = {
+  generateLocalSigningKey: localModule.generateLocalSigningKey,
+  startLocalDaemon: localModule.startLocalDaemon,
+  startGateway: localModule.startGateway,
+};
+const realExec = stepRunnerModule.exec;
+
+// Prevent real daemon / gateway from starting
+const startLocalDaemonMock = mock(async () => {});
+const startGatewayMock = mock(async () => {});
+
+// Capture exec calls without running real tar
+const execMock = mock(async (_cmd: string, _args: string[]) => {});
+
+beforeAll(() => {
+  mock.module("../lib/local.js", () => ({
+    generateLocalSigningKey: () => "deadbeefdeadbeefdeadbeefdeadbeef",
+    startLocalDaemon: startLocalDaemonMock,
+    startGateway: startGatewayMock,
+  }));
+  mock.module("../lib/step-runner.js", () => ({ exec: execMock }));
+});
+
+afterAll(() => {
+  mock.module("../lib/local.js", () => realLocal);
+  mock.module("../lib/step-runner.js", () => ({ exec: realExec }));
+});
+
+import { recover } from "../commands/recover.js";
+
+// ── Test fixtures ─────────────────────────────────────────────────────────────
+
+const testDir = mkdtempSync(join(tmpdir(), "cli-recover-test-"));
+const originalArgv = [...process.argv];
+const originalLockfileDir = process.env.VELLUM_LOCKFILE_DIR;
+const originalXdgData = process.env.XDG_DATA_HOME;
+
+// Directories that getRetiredDir() will use when XDG_DATA_HOME is overridden
+const retiredDir = join(testDir, "vellum", "retired");
+
+function makeEntry(assistantId: string, instanceDir: string): AssistantEntry {
+  return {
+    assistantId,
+    runtimeUrl: "http://127.0.0.1:7831",
+    cloud: "local",
+    resources: {
+      instanceDir,
+      daemonPort: 7801,
+      gatewayPort: 7831,
+      qdrantPort: 6334,
+      cesPort: 7790,
+    },
+  };
+}
+
+function writeArchiveFixtures(
+  name: string,
+  entry: AssistantEntry,
+): {
+  archivePath: string;
+  metadataPath: string;
+  extractedPath: string;
+} {
+  mkdirSync(retiredDir, { recursive: true });
+  const archivePath = join(retiredDir, `${name}.tar.gz`);
+  const metadataPath = join(retiredDir, `${name}.json`);
+  // The staging dir is what tar extracts — <archive>.staging relative to retiredDir
+  const extractedPath = join(retiredDir, basename(archivePath) + ".staging");
+
+  // Write a placeholder archive file (exec is mocked; content doesn't matter)
+  writeFileSync(archivePath, "");
+  writeFileSync(metadataPath, JSON.stringify(entry, null, 2) + "\n");
+  // Create the staging dir that tar would have created
+  mkdirSync(extractedPath, { recursive: true });
+
+  return { archivePath, metadataPath, extractedPath };
+}
+
+let consoleLogSpy: ReturnType<typeof spyOn>;
+let consoleErrorSpy: ReturnType<typeof spyOn>;
+let exitSpy: ReturnType<typeof spyOn>;
+
+beforeEach(() => {
+  // Route lockfile and retired archives to the temp directory
+  process.env.VELLUM_LOCKFILE_DIR = testDir;
+  process.env.XDG_DATA_HOME = testDir;
+  // Write an empty lockfile so saveAssistantEntry has a dir to write to
+  mkdirSync(testDir, { recursive: true });
+  writeFileSync(
+    join(testDir, ".vellum.lock.json"),
+    JSON.stringify({ assistants: [] }) + "\n",
+  );
+
+  consoleLogSpy = spyOn(console, "log").mockImplementation(() => {});
+  consoleErrorSpy = spyOn(console, "error").mockImplementation(() => {});
+  exitSpy = spyOn(process, "exit").mockImplementation((_code?: number) => {
+    throw new Error(`process.exit(${_code})`);
+  });
+
+  execMock.mockClear();
+  startLocalDaemonMock.mockClear();
+  startGatewayMock.mockClear();
+});
+
+afterEach(() => {
+  process.argv = [...originalArgv];
+  process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+  process.env.XDG_DATA_HOME = originalXdgData;
+  consoleLogSpy.mockRestore();
+  consoleErrorSpy.mockRestore();
+  exitSpy.mockRestore();
+  // Clean up per-test artifacts inside testDir/vellum/
+  if (existsSync(join(testDir, "vellum"))) {
+    rmSync(join(testDir, "vellum"), { recursive: true, force: true });
+  }
+});
+
+// Runs after all tests finish
+afterAll(() => {
+  rmSync(testDir, { recursive: true, force: true });
+  process.argv = [...originalArgv];
+  if (originalLockfileDir !== undefined) {
+    process.env.VELLUM_LOCKFILE_DIR = originalLockfileDir;
+  } else {
+    delete process.env.VELLUM_LOCKFILE_DIR;
+  }
+  if (originalXdgData !== undefined) {
+    process.env.XDG_DATA_HOME = originalXdgData;
+  } else {
+    delete process.env.XDG_DATA_HOME;
+  }
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("recover --help", () => {
+  test("prints usage, description, and examples then exits 0", async () => {
+    process.argv = ["bun", "vellum", "recover", "--help"];
+    await expect(recover()).rejects.toThrow("process.exit(0)");
+    const output = consoleLogSpy.mock.calls.flat().join("\n");
+    expect(output).toContain("Usage: vellum recover <name>");
+    expect(output).toContain("Examples:");
+    expect(output).toContain("vellum recover");
+  });
+});
+
+describe("recover error cases", () => {
+  test("exits 1 when no name is given", async () => {
+    process.argv = ["bun", "vellum", "recover"];
+    await expect(recover()).rejects.toThrow("process.exit(1)");
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain("Usage:");
+  });
+
+  test("exits 1 when archive is missing", async () => {
+    process.argv = ["bun", "vellum", "recover", "ghost-assistant"];
+    await expect(recover()).rejects.toThrow("process.exit(1)");
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain(
+      "No retired archive found for 'ghost-assistant'",
+    );
+  });
+
+  test("throws when metadata has no resources", async () => {
+    const name = "no-resources";
+    mkdirSync(retiredDir, { recursive: true });
+    writeFileSync(join(retiredDir, `${name}.tar.gz`), "");
+    const entry: Partial<AssistantEntry> = {
+      assistantId: name,
+      runtimeUrl: "http://127.0.0.1:7831",
+      cloud: "local",
+      // resources intentionally omitted
+    };
+    writeFileSync(
+      join(retiredDir, `${name}.json`),
+      JSON.stringify(entry, null, 2) + "\n",
+    );
+    process.argv = ["bun", "vellum", "recover", name];
+    await expect(recover()).rejects.toThrow("missing resource configuration");
+  });
+
+  test("exits 1 when target .vellum/ already exists", async () => {
+    const name = "already-exists";
+    const instanceDir = join(testDir, name);
+    const entry = makeEntry(name, instanceDir);
+    writeArchiveFixtures(name, entry);
+    // Pre-create the collision path that recover checks
+    mkdirSync(join(instanceDir, ".vellum"), { recursive: true });
+    process.argv = ["bun", "vellum", "recover", name];
+    await expect(recover()).rejects.toThrow("process.exit(1)");
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain("already exists");
+  });
+});
+
+describe("recover extraction path — default instance (instanceDir === homedir())", () => {
+  test("extracts to retiredDir and renames staging dir to instanceDir/.vellum", async () => {
+    const name = "default-instance";
+    // Default instance: instanceDir is the real home directory
+    const entry = makeEntry(name, homedir());
+    const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
+
+    const expectedTargetDir = join(homedir(), ".vellum");
+
+    process.argv = ["bun", "vellum", "recover", name];
+    await recover();
+
+    // exec must have been called with -C retiredDir, NOT -C homedir()
+    expect(execMock).toHaveBeenCalledTimes(1);
+    const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
+    expect(cmd).toBe("tar");
+    expect(args).toContain("-C");
+    const cIndex = args.indexOf("-C");
+    expect(args[cIndex + 1]).toBe(retiredDir);
+    expect(args[cIndex + 1]).not.toBe(homedir());
+
+    // Staging dir was renamed to the correct target
+    expect(existsSync(extractedPath)).toBe(false);
+    expect(existsSync(expectedTargetDir)).toBe(true);
+
+    // Archive and metadata were cleaned up
+    expect(existsSync(archivePath)).toBe(false);
+
+    // Daemon and gateway were started
+    expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
+    expect(startGatewayMock).toHaveBeenCalledTimes(1);
+
+    // Clean up so we don't leave a .vellum dir in the real home dir
+    rmSync(expectedTargetDir, { recursive: true, force: true });
+  });
+});
+
+describe("recover extraction path — named instance (instanceDir !== homedir())", () => {
+  test("extracts to retiredDir and renames staging dir to instanceDir directly", async () => {
+    const name = "named-instance";
+    const instanceDir = join(testDir, "custom-location", name);
+    const entry = makeEntry(name, instanceDir);
+    const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
+
+    // Named instance: targetDir is instanceDir itself (not instanceDir/.vellum)
+    const expectedTargetDir = instanceDir;
+    // Parent dir must exist for renameSync
+    mkdirSync(join(testDir, "custom-location"), { recursive: true });
+
+    process.argv = ["bun", "vellum", "recover", name];
+    await recover();
+
+    // exec must have been called with -C retiredDir
+    expect(execMock).toHaveBeenCalledTimes(1);
+    const [cmd, args] = execMock.mock.calls[0] as [string, string[]];
+    expect(cmd).toBe("tar");
+    const cIndex = args.indexOf("-C");
+    expect(args[cIndex + 1]).toBe(retiredDir);
+
+    // Staging dir was renamed to instanceDir (not instanceDir/.vellum)
+    expect(existsSync(extractedPath)).toBe(false);
+    expect(existsSync(expectedTargetDir)).toBe(true);
+
+    // Archive cleaned up
+    expect(existsSync(archivePath)).toBe(false);
+
+    // Daemon and gateway were started
+    expect(startLocalDaemonMock).toHaveBeenCalledTimes(1);
+    expect(startGatewayMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("creates parent directories of instanceDir when they do not exist", async () => {
+    const name = "deep-nested-instance";
+    // Use a path whose parent directory does not yet exist
+    const instanceDir = join(testDir, "new-parent", "deeper", name);
+    const entry = makeEntry(name, instanceDir);
+    const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
+
+    process.argv = ["bun", "vellum", "recover", name];
+    await recover();
+
+    expect(existsSync(extractedPath)).toBe(false);
+    expect(existsSync(instanceDir)).toBe(true);
+    expect(existsSync(archivePath)).toBe(false);
+
+    rmSync(instanceDir, { recursive: true, force: true });
+  });
+});

package/src/__tests__/segments-to-plain-text.test.ts

@@ -0,0 +1,37 @@
+import { describe, test, expect } from "bun:test";
+import { segmentsToPlainText } from "../lib/segments-to-plain-text.js";
+
+describe("segmentsToPlainText", () => {
+  test("returns empty string for missing or empty segments", () => {
+    // GIVEN a message whose history payload carries no text segments
+    // WHEN deriving its flat body
+    // THEN it is the empty string (matching the daemon's old empty `content`)
+    expect(segmentsToPlainText(undefined)).toBe("");
+    expect(segmentsToPlainText([])).toBe("");
+  });
+
+  test("returns a single segment unchanged", () => {
+    // GIVEN a plain-text message with one segment
+    // WHEN deriving its flat body
+    // THEN the segment is returned verbatim
+    expect(segmentsToPlainText(["Real reply."])).toBe("Real reply.");
+  });
+
+  test("joins adjacent segments with a single inserted space", () => {
+    // GIVEN segments split at a tool_use boundary with no surrounding whitespace
+    // WHEN deriving the flat body
+    // THEN a single space is inserted between them
+    expect(segmentsToPlainText(["before", "after"])).toBe("before after");
+  });
+
+  test("does not double-space when either side already has whitespace", () => {
+    // GIVEN segments where one side already ends/starts with whitespace
+    // WHEN deriving the flat body
+    // THEN no extra space is inserted (mirrors daemon joinWithSpacing)
+    expect(segmentsToPlainText(["before ", "after"])).toBe("before after");
+    expect(segmentsToPlainText(["before", " after"])).toBe("before after");
+    expect(segmentsToPlainText(["line one\n", "line two"])).toBe(
+      "line one\nline two",
+    );
+  });
+});

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");
+  });
+});