@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.3

package/src/__tests__/user-plugin-loader.test.ts

@@ -93,6 +93,27 @@ describe("user plugin loader", () => {
     expect(initHooks).toHaveLength(1);
   });
 
+  test("loads a plugin via a standard plugin.json manifest", async () => {
+    const pluginDir = join(PLUGINS_DIR, "standard-plugin");
+    mkdirSync(join(pluginDir, "hooks"), { recursive: true });
+    writeFileSync(
+      join(pluginDir, "plugin.json"),
+      JSON.stringify({
+        $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+        name: "standard-plugin",
+        version: "1.0.0",
+      }),
+    );
+    writeFileSync(
+      join(pluginDir, "hooks", "init.ts"),
+      "export default async function init(_ctx: unknown): Promise<void> {}\n",
+    );
+
+    await loadUserPlugins();
+
+    expect(await getUserHooksFor("init")).toHaveLength(1);
+  });
+
   test("per-plugin failure is isolated: other plugins still load", async () => {
     // Plugin A has a malformed package.json; the loader must isolate the
     // failure and still load the healthy sibling.

package/src/acp/__tests__/acp-claude-oauth.test.ts

@@ -22,11 +22,38 @@ import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 // ---------------------------------------------------------------------------
 
 let storeReturn = true;
+let deleteReturn: "deleted" | "not-found" | "error" = "not-found";
 let getReturn: string | undefined = undefined;
-const setSecureKeyAsync = mock(
-  async (_account: string, _value: string) => storeReturn,
-);
-const getSecureKeyAsync = mock(async (_account: string) => getReturn);
+const vault = new Map<string, string>();
+const ACCESS_KEY = "credential/acp/claude_oauth_token";
+const REFRESH_KEY = "credential/acp/claude_oauth_refresh_token";
+const EXPIRES_KEY = "credential/acp/claude_oauth_expires_at";
+const DIGEST_KEY = "credential/acp/claude_oauth_access_digest";
+
+const setSecureKeyAsync = mock(async (account: string, value: string) => {
+  if (!storeReturn) {
+    return false;
+  }
+  vault.set(account, value);
+  return true;
+});
+const getSecureKeyAsync = mock(async (account: string) => {
+  if (vault.has(account)) {
+    return vault.get(account);
+  }
+  // Existing cases that only seed the access token keep using getReturn.
+  if (account === ACCESS_KEY) {
+    return getReturn;
+  }
+  return undefined;
+});
+const deleteSecureKeyAsync = mock(async (account: string) => {
+  if (deleteReturn === "error") {
+    return "error";
+  }
+  const existed = vault.delete(account);
+  return existed ? "deleted" : "not-found";
+});
 
 // Spread the real module rather than listing two exports. These cases reach
 // the marker tables, which pulls persistence into the graph, and anything in
@@ -37,6 +64,7 @@ mock.module("../../security/secure-keys.js", () => ({
   ...realSecureKeys,
   setSecureKeyAsync,
   getSecureKeyAsync,
+  deleteSecureKeyAsync,
 }));
 
 const { _setMetadataPath, getCredentialMetadata, upsertCredentialMetadata } =
@@ -69,6 +97,10 @@ const {
   parseManualClaudeCode,
   storeAcpClaudeToken,
   hasAcpClaudeToken,
+  persistRefreshedAcpClaudeTokens,
+  forgetAcpClaudeRenewalStateIfUnbound,
+  clearAcpClaudeRefreshToken,
+  isAcpClaudeTokenExpiring,
 } = await import("../acp-claude-oauth.js");
 
 /**
@@ -95,9 +127,12 @@ beforeEach(() => {
   mkdirSync(TEST_DIR, { recursive: true });
   _setMetadataPath(join(TEST_DIR, "metadata.json"));
   storeReturn = true;
+  deleteReturn = "not-found";
   getReturn = undefined;
+  vault.clear();
   setSecureKeyAsync.mockClear();
   getSecureKeyAsync.mockClear();
+  deleteSecureKeyAsync.mockClear();
 });
 
 afterEach(() => {
@@ -204,11 +239,43 @@ describe("storeAcpClaudeToken", () => {
   test("writes the token to the acp/claude_oauth_token vault field", async () => {
     await storeAcpClaudeToken("sk-ant-oat-token");
 
-    expect(setSecureKeyAsync).toHaveBeenCalledTimes(1);
     expect(setSecureKeyAsync).toHaveBeenCalledWith(
-      "credential/acp/claude_oauth_token",
+      ACCESS_KEY,
       "sk-ant-oat-token",
     );
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-token");
+  });
+
+  test("persists refresh token and expiry from a Connect exchange", async () => {
+    const before = Date.now();
+    await storeAcpClaudeToken({
+      accessToken: "sk-ant-oat-connected",
+      refreshToken: "refresh-from-exchange",
+      expiresIn: 28800,
+    });
+    const after = Date.now();
+
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-connected");
+    expect(vault.get(REFRESH_KEY)).toBe("refresh-from-exchange");
+    expect(vault.get(DIGEST_KEY)).toBe(
+      claudeTokenDigest("sk-ant-oat-connected"),
+    );
+    const expiresAt = Number(vault.get(EXPIRES_KEY));
+    expect(expiresAt).toBeGreaterThanOrEqual(before + 28800 * 1000);
+    expect(expiresAt).toBeLessThanOrEqual(after + 28800 * 1000);
+  });
+
+  test("clears companion fields when the exchange returns only an access token", async () => {
+    vault.set(REFRESH_KEY, "stale-refresh");
+    vault.set(EXPIRES_KEY, "1");
+    vault.set(DIGEST_KEY, "stale-digest");
+
+    await storeAcpClaudeToken({ accessToken: "sk-ant-oat-access-only" });
+
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-access-only");
+    expect(vault.has(REFRESH_KEY)).toBe(false);
+    expect(vault.has(EXPIRES_KEY)).toBe(false);
+    expect(vault.has(DIGEST_KEY)).toBe(false);
   });
 
   test("takes a domain-restricted credential from not-connected to connected", async () => {
@@ -309,6 +376,190 @@ describe("hasAcpClaudeToken", () => {
 
     expect(oauthMetadata()).toBeUndefined();
   });
+
+  test("reports true for an expired token that still has a refresh token", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-expired-renewable");
+    vault.set(REFRESH_KEY, "refresh-still-good");
+    vault.set(EXPIRES_KEY, String(Date.now() - 1000));
+
+    expect(await hasAcpClaudeToken()).toBe(true);
+  });
+
+  test("reports false for an expired token with no refresh token", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-expired-dead");
+    vault.set(EXPIRES_KEY, String(Date.now() - 1000));
+
+    expect(await hasAcpClaudeToken()).toBe(false);
+  });
+
+  test("reports true for a token with no recorded expiry (legacy access-token-only)", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-legacy");
+
+    expect(await hasAcpClaudeToken()).toBe(true);
+    expect(await isAcpClaudeTokenExpiring()).toBe(false);
+  });
+
+  test("reports false when only leftover refresh material remains", async () => {
+    vault.set(REFRESH_KEY, "refresh-leftover");
+    vault.set(EXPIRES_KEY, String(Date.now() - 1000));
+
+    expect(await hasAcpClaudeToken()).toBe(false);
+  });
+
+  test("reports true for a pasted token whose leftover expiry describes a previous token", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-pasted");
+    vault.set(REFRESH_KEY, "refresh-previous");
+    vault.set(EXPIRES_KEY, String(Date.now() - 1000));
+    vault.set(DIGEST_KEY, claudeTokenDigest("sk-ant-oat-previous"));
+
+    expect(await hasAcpClaudeToken()).toBe(true);
+  });
+});
+
+describe("persistRefreshedAcpClaudeTokens", () => {
+  test("writes a rotated refresh token and new expiry without touching policy", async () => {
+    upsertCredentialMetadata(ACP_SERVICE, OAUTH_FIELD, {
+      allowedTools: ["some_other_tool"],
+    });
+    vault.set(ACCESS_KEY, "sk-ant-oat-current");
+    vault.set(REFRESH_KEY, "refresh-expected");
+    vault.set(DIGEST_KEY, claudeTokenDigest("sk-ant-oat-current"));
+    const before = Date.now();
+
+    await persistRefreshedAcpClaudeTokens(
+      {
+        accessToken: "sk-ant-oat-refreshed",
+        refreshToken: "refresh-rotated",
+        expiresIn: 3600,
+      },
+      "refresh-expected",
+    );
+
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-refreshed");
+    expect(vault.get(REFRESH_KEY)).toBe("refresh-rotated");
+    expect(vault.get(DIGEST_KEY)).toBe(
+      claudeTokenDigest("sk-ant-oat-refreshed"),
+    );
+    const expiresAt = Number(vault.get(EXPIRES_KEY));
+    expect(expiresAt).toBeGreaterThanOrEqual(before + 3600 * 1000);
+    expect(oauthMetadata()?.allowedTools).toEqual(["some_other_tool"]);
+  });
+
+  test("keeps the stored refresh token when the response omits a new one", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-current");
+    vault.set(REFRESH_KEY, "refresh-kept");
+    vault.set(DIGEST_KEY, claudeTokenDigest("sk-ant-oat-current"));
+
+    await persistRefreshedAcpClaudeTokens(
+      {
+        accessToken: "sk-ant-oat-refreshed",
+        expiresIn: 3600,
+      },
+      "refresh-kept",
+    );
+
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-refreshed");
+    expect(vault.get(REFRESH_KEY)).toBe("refresh-kept");
+  });
+
+  test("refuses to persist when the stored refresh token no longer matches", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-current");
+    vault.set(REFRESH_KEY, "refresh-current");
+    vault.set(EXPIRES_KEY, "999");
+
+    const persisted = await persistRefreshedAcpClaudeTokens(
+      {
+        accessToken: "sk-ant-oat-stale",
+        refreshToken: "refresh-stale-rotated",
+        expiresIn: 3600,
+      },
+      "refresh-old",
+    );
+
+    expect(persisted).toBe(false);
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-current");
+    expect(vault.get(REFRESH_KEY)).toBe("refresh-current");
+    expect(vault.get(EXPIRES_KEY)).toBe("999");
+  });
+
+  test("refuses to persist when the access token is no longer stored", async () => {
+    vault.set(REFRESH_KEY, "refresh-leftover");
+    vault.set(EXPIRES_KEY, "111");
+
+    const persisted = await persistRefreshedAcpClaudeTokens(
+      {
+        accessToken: "sk-ant-oat-resurrected",
+        refreshToken: "refresh-rotated",
+        expiresIn: 3600,
+      },
+      "refresh-leftover",
+    );
+
+    expect(persisted).toBe(false);
+    expect(vault.has(ACCESS_KEY)).toBe(false);
+    expect(vault.get(REFRESH_KEY)).toBe("refresh-leftover");
+    expect(vault.get(EXPIRES_KEY)).toBe("111");
+  });
+
+  test("refuses to persist when the access token is not the one the refresh material was written with", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-pasted");
+    vault.set(REFRESH_KEY, "refresh-previous");
+    vault.set(EXPIRES_KEY, "111");
+    vault.set(DIGEST_KEY, claudeTokenDigest("sk-ant-oat-previous"));
+
+    const persisted = await persistRefreshedAcpClaudeTokens(
+      {
+        accessToken: "sk-ant-oat-overwritten",
+        refreshToken: "refresh-rotated",
+        expiresIn: 3600,
+      },
+      "refresh-previous",
+    );
+
+    expect(persisted).toBe(false);
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-pasted");
+    expect(vault.get(REFRESH_KEY)).toBe("refresh-previous");
+    expect(vault.get(EXPIRES_KEY)).toBe("111");
+  });
+});
+
+describe("clearAcpClaudeRefreshToken", () => {
+  test("leaves the stored refresh token when it no longer matches the rejected one", async () => {
+    vault.set(REFRESH_KEY, "refresh-current");
+
+    await clearAcpClaudeRefreshToken("refresh-old");
+
+    expect(vault.get(REFRESH_KEY)).toBe("refresh-current");
+  });
+});
+
+describe("forgetAcpClaudeRenewalStateIfUnbound", () => {
+  test("clears leftover renewal fields after the access token was replaced", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-pasted");
+    vault.set(REFRESH_KEY, "stale-refresh");
+    vault.set(EXPIRES_KEY, "111");
+    vault.set(DIGEST_KEY, claudeTokenDigest("sk-ant-oat-previous"));
+
+    await forgetAcpClaudeRenewalStateIfUnbound();
+
+    expect(vault.get(ACCESS_KEY)).toBe("sk-ant-oat-pasted");
+    expect(vault.has(REFRESH_KEY)).toBe(false);
+    expect(vault.has(EXPIRES_KEY)).toBe(false);
+    expect(vault.has(DIGEST_KEY)).toBe(false);
+  });
+
+  test("keeps renewal fields when they still describe the stored access token", async () => {
+    vault.set(ACCESS_KEY, "sk-ant-oat-current");
+    vault.set(REFRESH_KEY, "keep-refresh");
+    vault.set(EXPIRES_KEY, "222");
+    vault.set(DIGEST_KEY, claudeTokenDigest("sk-ant-oat-current"));
+
+    await forgetAcpClaudeRenewalStateIfUnbound();
+
+    expect(vault.get(REFRESH_KEY)).toBe("keep-refresh");
+    expect(vault.get(EXPIRES_KEY)).toBe("222");
+    expect(vault.get(DIGEST_KEY)).toBe(claudeTokenDigest("sk-ant-oat-current"));
+  });
 });
 
 describe("storeAcpClaudeToken: retiring the card registry", () => {

package/src/acp/__tests__/acp-credentials.test.ts

@@ -5,6 +5,9 @@
 import { describe, expect, test } from "bun:test";
 
 import {
+  ACP_OAUTH_ACCESS_DIGEST_FIELD,
+  ACP_OAUTH_EXPIRES_AT_FIELD,
+  ACP_OAUTH_REFRESH_TOKEN_FIELD,
   ACP_OAUTH_TOKEN_FIELD,
   ACP_SERVICE,
   AcpCredentialFormatError,
@@ -70,6 +73,9 @@ describe("constants", () => {
   test("expose the ACP service and OAuth field names", () => {
     expect(ACP_SERVICE).toBe("acp");
     expect(ACP_OAUTH_TOKEN_FIELD).toBe("claude_oauth_token");
+    expect(ACP_OAUTH_REFRESH_TOKEN_FIELD).toBe("claude_oauth_refresh_token");
+    expect(ACP_OAUTH_EXPIRES_AT_FIELD).toBe("claude_oauth_expires_at");
+    expect(ACP_OAUTH_ACCESS_DIGEST_FIELD).toBe("claude_oauth_access_digest");
   });
 });
 
@@ -81,6 +87,13 @@ describe("isAcpClaudeOauthField", () => {
   test("rejects other services and fields", () => {
     expect(isAcpClaudeOauthField("acp", "openai_api_key")).toBe(false);
     expect(isAcpClaudeOauthField("acp", "codex_api_key")).toBe(false);
+    expect(isAcpClaudeOauthField("acp", "claude_oauth_refresh_token")).toBe(
+      false,
+    );
+    expect(isAcpClaudeOauthField("acp", "claude_oauth_expires_at")).toBe(false);
+    expect(isAcpClaudeOauthField("acp", "claude_oauth_access_digest")).toBe(
+      false,
+    );
     expect(isAcpClaudeOauthField("sentry", "claude_oauth_token")).toBe(false);
     expect(isAcpClaudeOauthField("openai", "api_key")).toBe(false);
   });

package/src/acp/__tests__/claude-token-refresh.test.ts

@@ -0,0 +1,257 @@
+/**
+ * Tests for the Claude ACP OAuth renewal policy.
+ *
+ * Storage is mocked (it belongs to `acp-claude-oauth.ts`, tested separately) so
+ * these assert only the decisions this module owns: when to spend the refresh
+ * token, what to persist, and what to tear down when the provider rejects it.
+ *
+ * `isCredentialError` is deliberately not mocked. Whether a failure is
+ * permanent or transient is the hinge of the whole module, and asserting it
+ * against the real classifier is the only way these tests stay honest about
+ * which thrown errors clear a user's stored credential.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { OAuth2TokenResult } from "../../security/oauth2.js";
+
+// ---------------------------------------------------------------------------
+// Mocks: wired BEFORE importing the module via dynamic import.
+// ---------------------------------------------------------------------------
+
+let expiring = false;
+let storedAccessToken = true;
+let storedRefreshToken: string | null = null;
+let refreshImpl: () => Promise<OAuth2TokenResult> = async () => {
+  throw new Error("refreshOAuth2Token not stubbed for this test");
+};
+
+let spawnDenial: string | undefined = undefined;
+const isAcpClaudeTokenExpiring = mock(async () => expiring);
+const hasStoredAcpClaudeAccessToken = mock(async () => storedAccessToken);
+const forgetAcpClaudeRenewalStateIfUnbound = mock(async () => {});
+const readAcpClaudeRefreshToken = mock(async () => storedRefreshToken);
+const persistRefreshedAcpClaudeTokens = mock(
+  async (_tokens: unknown, _expectedRefreshToken: string) => true,
+);
+const clearAcpClaudeRefreshToken = mock(async () => {});
+const acpSpawnCredentialDenialReason = mock((_field: string) => spawnDenial);
+const refreshOAuth2Token = mock(async (..._args: unknown[]) => refreshImpl());
+
+mock.module("../acp-claude-oauth.js", () => ({
+  CLAUDE_OAUTH_CONFIG: {
+    tokenExchangeUrl: "https://platform.claude.com/v1/oauth/token",
+    clientId: "9d1c250a-e61b-44d9-88ed-5944d1962f5e",
+    tokenExchangeBodyFormat: "json",
+  },
+  isAcpClaudeTokenExpiring,
+  hasStoredAcpClaudeAccessToken,
+  forgetAcpClaudeRenewalStateIfUnbound,
+  readAcpClaudeRefreshToken,
+  persistRefreshedAcpClaudeTokens,
+  clearAcpClaudeRefreshToken,
+}));
+mock.module("../prepare-agent-env.js", () => ({
+  acpSpawnCredentialDenialReason,
+}));
+mock.module("../../security/oauth2.js", () => ({ refreshOAuth2Token }));
+
+const { ensureFreshAcpClaudeToken } =
+  await import("../claude-token-refresh.js");
+
+beforeEach(() => {
+  expiring = false;
+  storedAccessToken = true;
+  storedRefreshToken = null;
+  spawnDenial = undefined;
+  refreshImpl = async () => {
+    throw new Error("refreshOAuth2Token not stubbed for this test");
+  };
+  isAcpClaudeTokenExpiring.mockClear();
+  hasStoredAcpClaudeAccessToken.mockClear();
+  forgetAcpClaudeRenewalStateIfUnbound.mockClear();
+  readAcpClaudeRefreshToken.mockClear();
+  persistRefreshedAcpClaudeTokens.mockClear();
+  clearAcpClaudeRefreshToken.mockClear();
+  acpSpawnCredentialDenialReason.mockClear();
+  refreshOAuth2Token.mockClear();
+});
+
+describe("ensureFreshAcpClaudeToken: skip paths", () => {
+  test("does nothing while the token is still fresh", async () => {
+    expiring = false;
+    storedRefreshToken = "refresh-me";
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(refreshOAuth2Token).not.toHaveBeenCalled();
+    expect(persistRefreshedAcpClaudeTokens).not.toHaveBeenCalled();
+  });
+
+  test("does nothing when expiring with no refresh token stored", async () => {
+    expiring = true;
+    storedRefreshToken = null;
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(refreshOAuth2Token).not.toHaveBeenCalled();
+    expect(clearAcpClaudeRefreshToken).not.toHaveBeenCalled();
+  });
+
+  test("drops unbound leftover refresh material before deciding to renew", async () => {
+    expiring = false;
+    storedAccessToken = true;
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(forgetAcpClaudeRenewalStateIfUnbound).toHaveBeenCalledTimes(1);
+    expect(refreshOAuth2Token).not.toHaveBeenCalled();
+  });
+
+  test("does not mint a new access token after the stored one was deleted", async () => {
+    expiring = true;
+    storedAccessToken = false;
+    storedRefreshToken = "refresh-leftover";
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(refreshOAuth2Token).not.toHaveBeenCalled();
+    expect(persistRefreshedAcpClaudeTokens).not.toHaveBeenCalled();
+    expect(clearAcpClaudeRefreshToken).not.toHaveBeenCalled();
+  });
+});
+
+describe("ensureFreshAcpClaudeToken: renewal", () => {
+  test("refreshes against Claude's token endpoint and persists the rotated set", async () => {
+    expiring = true;
+    storedRefreshToken = "refresh-me";
+    refreshImpl = async () => ({
+      accessToken: "sk-ant-oat-new",
+      refreshToken: "refresh-rotated",
+      expiresIn: 3600,
+    });
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(refreshOAuth2Token).toHaveBeenCalledTimes(1);
+    const args = refreshOAuth2Token.mock.calls[0];
+    expect(args[0]).toBe("https://platform.claude.com/v1/oauth/token");
+    expect(args[1]).toBe("9d1c250a-e61b-44d9-88ed-5944d1962f5e");
+    expect(args[2]).toBe("refresh-me");
+    expect(args[3]).toBeUndefined();
+    expect(args[5]).toBe("json");
+
+    expect(persistRefreshedAcpClaudeTokens).toHaveBeenCalledWith(
+      {
+        accessToken: "sk-ant-oat-new",
+        refreshToken: "refresh-rotated",
+        expiresIn: 3600,
+      },
+      "refresh-me",
+    );
+  });
+
+  test("does not treat a skipped stale persist as a failure", async () => {
+    expiring = true;
+    storedRefreshToken = "refresh-me";
+    persistRefreshedAcpClaudeTokens.mockResolvedValueOnce(false);
+    refreshImpl = async () => ({
+      accessToken: "sk-ant-oat-stale",
+      refreshToken: "refresh-rotated",
+      expiresIn: 3600,
+    });
+
+    await expect(ensureFreshAcpClaudeToken()).resolves.toBeUndefined();
+    expect(clearAcpClaudeRefreshToken).not.toHaveBeenCalled();
+  });
+
+  test("runs one refresh for concurrent spawns", async () => {
+    expiring = true;
+    storedRefreshToken = "refresh-me";
+
+    let resolveRefresh!: (v: OAuth2TokenResult) => void;
+    const gate = new Promise<OAuth2TokenResult>((resolve) => {
+      resolveRefresh = resolve;
+    });
+    refreshImpl = () => gate;
+
+    const both = Promise.all([
+      ensureFreshAcpClaudeToken(),
+      ensureFreshAcpClaudeToken(),
+    ]);
+    for (let i = 0; i < 20; i++) {
+      await Promise.resolve();
+    }
+    resolveRefresh({ accessToken: "sk-ant-oat-new" });
+    await both;
+
+    expect(refreshOAuth2Token).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("ensureFreshAcpClaudeToken: policy", () => {
+  test("does not refresh when the spawn policy denies reading the credential", async () => {
+    expiring = true;
+    storedRefreshToken = "refresh-me";
+    spawnDenial = 'Tool "acp_spawn" is not allowed to use this credential';
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(refreshOAuth2Token).not.toHaveBeenCalled();
+    expect(persistRefreshedAcpClaudeTokens).not.toHaveBeenCalled();
+  });
+});
+
+describe("ensureFreshAcpClaudeToken: failures", () => {
+  test("clears refresh material when the provider rejects the refresh token", async () => {
+    expiring = true;
+    storedRefreshToken = "revoked";
+    refreshImpl = async () => {
+      throw new Error("OAuth2 token refresh failed (HTTP 400 invalid_grant)");
+    };
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(clearAcpClaudeRefreshToken).toHaveBeenCalledWith("revoked");
+    expect(persistRefreshedAcpClaudeTokens).not.toHaveBeenCalled();
+  });
+
+  test("clears refresh material when the refresh succeeds with no access token", async () => {
+    expiring = true;
+    storedRefreshToken = "refresh-me";
+    refreshImpl = async () =>
+      ({
+        accessToken: "",
+        refreshToken: "refresh-rotated",
+        expiresIn: 3600,
+      }) as OAuth2TokenResult;
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(clearAcpClaudeRefreshToken).toHaveBeenCalledWith("refresh-me");
+    expect(persistRefreshedAcpClaudeTokens).not.toHaveBeenCalled();
+  });
+
+  test("keeps refresh material on a transient failure", async () => {
+    expiring = true;
+    storedRefreshToken = "refresh-me";
+    refreshImpl = async () => {
+      throw new Error("fetch failed: ECONNREFUSED");
+    };
+
+    await ensureFreshAcpClaudeToken();
+
+    expect(clearAcpClaudeRefreshToken).not.toHaveBeenCalled();
+    expect(persistRefreshedAcpClaudeTokens).not.toHaveBeenCalled();
+  });
+
+  test("never throws, so a refresh outage cannot fail the spawn", async () => {
+    expiring = true;
+    storedRefreshToken = "refresh-me";
+    refreshImpl = async () => {
+      throw new Error("HTTP 401 unauthorized");
+    };
+
+    await expect(ensureFreshAcpClaudeToken()).resolves.toBeUndefined();
+  });
+});