@vellumai/cli 0.8.10 → 0.8.11-dev.202606112147.04177ac

package/AGENTS.md

@@ -63,6 +63,8 @@ The CLI must **never** read from or write to the `.vellum/` directory (e.g. `~/.
 
 For example, the signing key used for JWT auth between the daemon and gateway is persisted in the lockfile (`resources.signingKey`) so that client actor tokens survive daemon/gateway restarts. On first start (or when the key is missing), the CLI generates a new key via `generateLocalSigningKey()` in `lib/local.ts`, saves it to the lockfile entry, and passes it to both `startLocalDaemon` and `startGateway` as the `ACTOR_TOKEN_SIGNING_KEY` env var. The CLI does **not** read or write to the `.vellum/` directory for signing keys — it uses the lockfile instead.
 
+**Exception: `~/.vellum/device.json`.** That file is the machine-wide shared device-identity file, co-owned by the Swift clients, the Electron main process, the host-mode assistant, and the CLI (see `clients/shared/App/Auth/DeviceIdStore.swift` and `apps/macos/src/main/device-id.ts`). The boundary rule covers daemon/gateway-internal state (e.g. `~/.vellum/protected/`, instance dirs), not this file.
+
 ## Process liveness
 
 Use `resolveProcessState()` from `lib/process.ts` when checking whether a daemon or gateway should be (re)started. It combines PID existence with an HTTP `/healthz` probe, a readiness grace period, and a [`isVellumProcess()`](https://man7.org/linux/man-pages/man1/ps.1.html) guard against PID reuse — see the function's JSDoc for the full flow.

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/node_modules/@vellumai/local-mode/src/lockfile-contract.test.ts

@@ -10,10 +10,11 @@ describe("parseLockfile", () => {
         {
           assistantId: "asst_1",
           name: "Alice",
-          cloud: "local",
+          cloud: "vellum",
           runtimeUrl: "http://127.0.0.1:7777",
           species: "vellum",
           hatchedAt: "2026-01-01T00:00:00.000Z",
+          organizationId: "org_1",
           resources: { gatewayPort: 7777, daemonPort: 7778 },
         },
       ],
@@ -150,6 +151,24 @@ describe("parseLockfile", () => {
     expect(parseLockfile(raw).assistants).toEqual([]);
   });
 
+  test("keeps organizationId on platform entries and drops it when mistyped", () => {
+    // Platform assistants carry their owning org so the host proxy can scope
+    // requests without guessing; local entries simply omit it.
+    const raw = {
+      assistants: [
+        { assistantId: "asst_1", cloud: "vellum", organizationId: "org_1" },
+        { assistantId: "asst_2", cloud: "vellum", organizationId: 7 }, // mistyped
+        { assistantId: "asst_3", cloud: "local" }, // local, no org
+      ],
+      activeAssistant: null,
+    };
+    expect(parseLockfile(raw).assistants).toEqual([
+      { assistantId: "asst_1", cloud: "vellum", organizationId: "org_1" },
+      { assistantId: "asst_2", cloud: "vellum" },
+      { assistantId: "asst_3", cloud: "local" },
+    ]);
+  });
+
   test("drops a resources object missing its numeric ports", () => {
     const raw = {
       assistants: [

package/node_modules/@vellumai/local-mode/src/lockfile-contract.ts

@@ -42,6 +42,8 @@ export interface LockfileAssistant {
   runtimeUrl?: string;
   species?: string;
   hatchedAt?: string;
+  /** Owning org for platform assistants; absent for local ones. */
+  organizationId?: string;
   resources?: LocalAssistantResources;
 }
 
@@ -87,6 +89,7 @@ function parseAssistant(value: unknown): LockfileAssistant | null {
   if (typeof value.runtimeUrl === "string") assistant.runtimeUrl = value.runtimeUrl;
   if (typeof value.species === "string") assistant.species = value.species;
   if (typeof value.hatchedAt === "string") assistant.hatchedAt = value.hatchedAt;
+  if (typeof value.organizationId === "string") assistant.organizationId = value.organizationId;
   const resources = parseResources(value.resources);
   if (resources) assistant.resources = resources;
   return assistant;

package/node_modules/@vellumai/local-mode/src/lockfile.test.ts

@@ -207,6 +207,175 @@ describe("replacePlatformAssistants", () => {
     expect(ids).toEqual(["asst_local", "asst_new_platform"]);
   });
 
+  test("a sync scoped to one org preserves another org's platform entries", () => {
+    writeOnDisk({
+      activeAssistant: null,
+      assistants: [
+        {
+          assistantId: "asst_org_a",
+          cloud: "vellum",
+          organizationId: "org_a",
+          runtimeUrl: "http://a",
+        },
+        {
+          assistantId: "asst_org_b_old",
+          cloud: "vellum",
+          organizationId: "org_b",
+          runtimeUrl: "http://bo",
+        },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_org_b_new",
+          cloud: "vellum",
+          organizationId: "org_b",
+          runtimeUrl: "http://bn",
+        },
+      ],
+      "org_b",
+    );
+
+    const ids = (readOnDisk().assistants as Array<Record<string, unknown>>).map(
+      (a) => a.assistantId,
+    );
+    // Org A survives; Org B's stale entry is replaced by the new one.
+    expect(ids).toEqual(["asst_org_a", "asst_org_b_new"]);
+  });
+
+  test("de-duplicates a legacy no-org entry that shares an id with the new list", () => {
+    writeOnDisk({
+      activeAssistant: null,
+      assistants: [
+        // Legacy platform entry with no organizationId, same id as the sync.
+        { assistantId: "asst_dup", cloud: "vellum", runtimeUrl: "http://old" },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_dup",
+          cloud: "vellum",
+          organizationId: "org_a",
+          runtimeUrl: "http://new",
+        },
+      ],
+      "org_a",
+    );
+
+    const assistants = readOnDisk().assistants as Array<Record<string, unknown>>;
+    expect(assistants).toHaveLength(1);
+    expect(assistants[0]).toMatchObject({
+      assistantId: "asst_dup",
+      organizationId: "org_a",
+      runtimeUrl: "http://new",
+    });
+  });
+
+  test("full-replaces all platform entries when no org is given (legacy)", () => {
+    writeOnDisk({
+      activeAssistant: null,
+      assistants: [
+        {
+          assistantId: "asst_org_a",
+          cloud: "vellum",
+          organizationId: "org_a",
+          runtimeUrl: "http://a",
+        },
+        {
+          assistantId: "asst_org_b",
+          cloud: "vellum",
+          organizationId: "org_b",
+          runtimeUrl: "http://b",
+        },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_new",
+          cloud: "vellum",
+          runtimeUrl: "http://np",
+        },
+      ],
+    );
+
+    const ids = (readOnDisk().assistants as Array<Record<string, unknown>>).map(
+      (a) => a.assistantId,
+    );
+    expect(ids).toEqual(["asst_new"]);
+  });
+
+  test("local entries always survive an org-scoped sync", () => {
+    writeOnDisk({
+      activeAssistant: null,
+      assistants: [
+        { assistantId: "asst_local", cloud: "local", runtimeUrl: "http://l" },
+        {
+          assistantId: "asst_org_a",
+          cloud: "vellum",
+          organizationId: "org_a",
+          runtimeUrl: "http://a",
+        },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_org_a_new",
+          cloud: "vellum",
+          organizationId: "org_a",
+          runtimeUrl: "http://an",
+        },
+      ],
+      "org_a",
+    );
+
+    const ids = (readOnDisk().assistants as Array<Record<string, unknown>>).map(
+      (a) => a.assistantId,
+    );
+    expect(ids).toEqual(["asst_local", "asst_org_a_new"]);
+  });
+
+  test("keeps activeAssistant when it still resolves after an org-scoped sync", () => {
+    writeOnDisk({
+      activeAssistant: "asst_org_b_old",
+      assistants: [
+        {
+          assistantId: "asst_org_b_old",
+          cloud: "vellum",
+          organizationId: "org_b",
+          runtimeUrl: "http://bo",
+        },
+      ],
+    });
+
+    replacePlatformAssistants(
+      [lockfilePath],
+      [
+        {
+          assistantId: "asst_org_a",
+          cloud: "vellum",
+          organizationId: "org_a",
+          runtimeUrl: "http://a",
+        },
+      ],
+      "org_a",
+    );
+
+    // Org B's entry (and the active id pointing at it) survives the org-A sync.
+    expect(readOnDisk().activeAssistant).toBe("asst_org_b_old");
+  });
+
   test("clears activeAssistant when the active id no longer exists", () => {
     writeOnDisk({
       activeAssistant: "asst_old_platform",

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

@@ -106,6 +106,7 @@ export function isActiveAssistant(
 export function replacePlatformAssistants(
   lockfilePaths: string[],
   platformAssistants: Array<Record<string, unknown>>,
+  organizationId?: string,
 ): WriteResult {
   let lockfile: Record<string, unknown> = { assistants: [], activeAssistant: null };
   for (const candidate of lockfilePaths) {
@@ -118,10 +119,14 @@ export function replacePlatformAssistants(
   }
 
   const existing = Array.isArray(lockfile.assistants) ? lockfile.assistants : [];
-  const local = existing.filter(
-    (a: Record<string, unknown>) => a?.cloud !== "vellum",
-  );
-  lockfile.assistants = [...local, ...platformAssistants];
+  const syncedIds = new Set(platformAssistants.map((a) => a.assistantId));
+  // Org-scoped sync preserves other orgs' platform entries; no org full-replaces.
+  const preserved = existing.filter((a: Record<string, unknown>) => {
+    if (a?.cloud !== "vellum") return true;
+    if (syncedIds.has(a.assistantId)) return false;
+    return organizationId != null && a.organizationId !== organizationId;
+  });
+  lockfile.assistants = [...preserved, ...platformAssistants];
 
   const active = lockfile.activeAssistant as string | null;
   if (active) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.10",
+  "version": "0.8.11-dev.202606112147.04177ac",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/confirm.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test";
+
+import { parseConfirmArgs } from "../commands/confirm.js";
+
+describe("parseConfirmArgs", () => {
+  test("parses a request id with the active assistant and defaults to allow", () => {
+    const r = parseConfirmArgs(["--request-id", "req-1"]);
+    expect(r).toEqual({
+      ok: true,
+      value: {
+        assistantId: undefined,
+        requestId: "req-1",
+        decision: "allow",
+        jsonOutput: false,
+      },
+    });
+  });
+
+  test("parses an explicit assistant plus request id", () => {
+    const r = parseConfirmArgs(["my-assistant", "--request-id", "req-1"]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.assistantId).toBe("my-assistant");
+    expect(r.value.requestId).toBe("req-1");
+  });
+
+  test("honors an explicit deny decision", () => {
+    const r = parseConfirmArgs(["--request-id", "req-1", "--decision", "deny"]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.decision).toBe("deny");
+  });
+
+  test("requires a request id", () => {
+    const r = parseConfirmArgs([]);
+    expect(r).toEqual({ ok: false, error: "--request-id is required." });
+  });
+
+  test("rejects an unknown decision", () => {
+    const r = parseConfirmArgs([
+      "--request-id",
+      "req-1",
+      "--decision",
+      "maybe",
+    ]);
+    expect(r).toEqual({
+      ok: false,
+      error: '--decision must be "allow" or "deny" (got "maybe").',
+    });
+  });
+
+  test("rejects a value-less --decision instead of defaulting to allow", () => {
+    // A trailing `--decision` with no value (e.g. an empty shell expansion)
+    // must not silently approve via the "allow" default.
+    const r = parseConfirmArgs(["--request-id", "req-1", "--decision"]);
+    expect(r).toEqual({
+      ok: false,
+      error: '--decision requires a value ("allow" or "deny").',
+    });
+  });
+
+  test("rejects an empty-string --decision value", () => {
+    const r = parseConfirmArgs(["--request-id", "req-1", "--decision", ""]);
+    expect(r).toEqual({
+      ok: false,
+      error: '--decision must be "allow" or "deny" (got "").',
+    });
+  });
+
+  test("rejects a value-less --request-id", () => {
+    const r = parseConfirmArgs(["--request-id"]);
+    expect(r).toEqual({
+      ok: false,
+      error: "--request-id requires a value.",
+    });
+  });
+
+  test("preserves --json alongside the request id", () => {
+    const r = parseConfirmArgs(["--json", "--request-id", "req-1"]);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.jsonOutput).toBe(true);
+    expect(r.value.requestId).toBe("req-1");
+  });
+});

package/src/__tests__/device-id.test.ts

@@ -0,0 +1,167 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+// Bun's os.homedir() ignores runtime HOME changes, so mock it (same pattern
+// as multi-local.test.ts) to keep production-path tests off the real ~/.vellum.
+let fakeHome: string | undefined;
+const realOs = await import("node:os");
+const osMock = () => ({
+  ...realOs,
+  homedir: () => fakeHome ?? realOs.homedir(),
+});
+mock.module("node:os", osMock);
+mock.module("os", osMock);
+
+import {
+  getOrCreateHostDeviceId,
+  resetHostDeviceIdCache,
+} from "../lib/device-id.js";
+import { snapshotEnv } from "./helpers/env.js";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+const restoreEnv = snapshotEnv([
+  "XDG_CONFIG_HOME",
+  "VELLUM_ENVIRONMENT",
+  "VELLUM_DEVICE_ID",
+]);
+
+describe("getOrCreateHostDeviceId", () => {
+  let tempHome: string;
+  let deviceFile: string;
+
+  beforeEach(() => {
+    delete process.env.VELLUM_DEVICE_ID;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-device-id-test-"));
+    process.env.XDG_CONFIG_HOME = tempHome;
+    // Non-prod so the resolver targets $XDG_CONFIG_HOME/vellum-dev/
+    // instead of the real ~/.config/vellum/.
+    process.env.VELLUM_ENVIRONMENT = "dev";
+    deviceFile = join(tempHome, "vellum-dev", "device.json");
+    resetHostDeviceIdCache();
+  });
+
+  afterEach(() => {
+    restoreEnv();
+    rmSync(tempHome, { recursive: true, force: true });
+    resetHostDeviceIdCache();
+  });
+
+  test("creates device.json with a UUID when missing", () => {
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    expect(existsSync(deviceFile)).toBe(true);
+    const parsed = JSON.parse(readFileSync(deviceFile, "utf-8"));
+    expect(parsed.deviceId).toBe(id);
+    expect(readFileSync(deviceFile, "utf-8").endsWith("\n")).toBe(true);
+  });
+
+  test("returns the existing deviceId without rewriting the file", () => {
+    mkdirSync(join(tempHome, "vellum-dev"), { recursive: true });
+    writeFileSync(deviceFile, JSON.stringify({ deviceId: "existing-id" }));
+    const before = statSync(deviceFile).mtimeMs;
+
+    expect(getOrCreateHostDeviceId()).toBe("existing-id");
+    expect(statSync(deviceFile).mtimeMs).toBe(before);
+    expect(readFileSync(deviceFile, "utf-8")).toBe(
+      JSON.stringify({ deviceId: "existing-id" }),
+    );
+  });
+
+  test("caches the resolved id until reset", () => {
+    const first = getOrCreateHostDeviceId();
+    rmSync(deviceFile);
+
+    expect(getOrCreateHostDeviceId()).toBe(first);
+
+    resetHostDeviceIdCache();
+    const second = getOrCreateHostDeviceId();
+    expect(second).toMatch(UUID_RE);
+    expect(second).not.toBe(first);
+  });
+
+  test("preserves unrelated fields when adding deviceId", () => {
+    mkdirSync(join(tempHome, "vellum-dev"), { recursive: true });
+    writeFileSync(deviceFile, JSON.stringify({ other: "kept", deviceId: "" }));
+
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    const parsed = JSON.parse(readFileSync(deviceFile, "utf-8"));
+    expect(parsed.other).toBe("kept");
+    expect(parsed.deviceId).toBe(id);
+  });
+
+  test("VELLUM_DEVICE_ID env var wins and skips file access", () => {
+    process.env.VELLUM_DEVICE_ID = "env-device-id";
+
+    expect(getOrCreateHostDeviceId()).toBe("env-device-id");
+    expect(existsSync(deviceFile)).toBe(false);
+  });
+
+  test("malformed JSON regenerates without throwing", () => {
+    mkdirSync(join(tempHome, "vellum-dev"), { recursive: true });
+    writeFileSync(deviceFile, "{not json");
+
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    const parsed = JSON.parse(readFileSync(deviceFile, "utf-8"));
+    expect(parsed).toEqual({ deviceId: id });
+  });
+});
+
+describe("getOrCreateHostDeviceId (production)", () => {
+  let tempHome: string;
+  let deviceFile: string;
+
+  beforeEach(() => {
+    delete process.env.VELLUM_DEVICE_ID;
+    tempHome = mkdtempSync(join(tmpdir(), "cli-device-id-prod-test-"));
+    fakeHome = tempHome;
+    process.env.XDG_CONFIG_HOME = join(tempHome, ".config");
+    process.env.VELLUM_ENVIRONMENT = "production";
+    deviceFile = join(tempHome, ".vellum", "device.json");
+    resetHostDeviceIdCache();
+  });
+
+  afterEach(() => {
+    fakeHome = undefined;
+    restoreEnv();
+    rmSync(tempHome, { recursive: true, force: true });
+    resetHostDeviceIdCache();
+  });
+
+  test("creates device.json in the shared ~/.vellum dir", () => {
+    const id = getOrCreateHostDeviceId();
+
+    expect(id).toMatch(UUID_RE);
+    expect(existsSync(deviceFile)).toBe(true);
+    expect(JSON.parse(readFileSync(deviceFile, "utf-8")).deviceId).toBe(id);
+  });
+
+  test("reuses an existing ~/.vellum/device.json", () => {
+    mkdirSync(join(tempHome, ".vellum"), { recursive: true });
+    writeFileSync(
+      deviceFile,
+      JSON.stringify({ deviceId: "shared-prod-id" }),
+    );
+
+    expect(getOrCreateHostDeviceId()).toBe("shared-prod-id");
+    expect(readFileSync(deviceFile, "utf-8")).toBe(
+      JSON.stringify({ deviceId: "shared-prod-id" }),
+    );
+  });
+});

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