@vellumai/assistant 0.11.7-dev.202608281503.cbafd6c → 0.11.7-dev.202608282003.8ce5421

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -66,6 +66,13 @@ export function isChannelId(value: unknown): value is ChannelId {
  * That irregularity is why this is stated rather than derived from the key,
  * and it is stated here because this file already owns what a channel is.
  *
+ * Both senses can hold a user token, which is the sharpest edge. The `slack`
+ * integration's persisted token *is* the installer's user token, held on its
+ * OAuth connection. `slack_channel` holds an optional `user_token` in the
+ * credential store, beside its bot and app tokens. Same words, different
+ * homes, and only the second is a credential-store key: a pasted token is
+ * always the channel's, because the integration's never leaves the exchange.
+ *
  * Deliberately only the key. What fields each credential requires is declared
  * once already, per service, in the gateway's credential specs; restating it
  * here would be a second copy of a different fact.

package/node_modules/@vellumai/environments/package.json

@@ -7,7 +7,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./seeds": "./src/seeds.ts",
-    "./shell": "./src/shell.ts"
+    "./shell": "./src/shell.ts",
+    "./test-path-guard": "./src/test-path-guard.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/environments/src/__tests__/test-path-guard.test.ts

@@ -0,0 +1,89 @@
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  assertTestPathIsEphemeral,
+  canonicalizePathThroughExistingParent,
+  isBunTestProcess,
+} from "../test-path-guard.js";
+
+const OPTIONS = {
+  allowEnvVar: "TEST_PATH_GUARD_ALLOW",
+  runHint: "Run tests from the package root.",
+};
+
+describe("isBunTestProcess", () => {
+  test("detects this bun test run", () => {
+    expect(isBunTestProcess()).toBe(true);
+  });
+});
+
+describe("canonicalizePathThroughExistingParent", () => {
+  test("resolves symlinks on the deepest existing ancestor", () => {
+    const root = mkdtempSync(join(tmpdir(), "test-path-guard-"));
+    try {
+      const target = join(root, "target");
+      mkdirSync(target);
+      const link = join(root, "link");
+      symlinkSync(target, link, "dir");
+      expect(
+        canonicalizePathThroughExistingParent(join(link, "missing", "leaf")),
+      ).toBe(
+        join(canonicalizePathThroughExistingParent(target), "missing", "leaf"),
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test("returns the input path when no ancestor exists", () => {
+    expect(canonicalizePathThroughExistingParent("/nonexistent-root-x/y")).toBe(
+      "/nonexistent-root-x/y",
+    );
+  });
+});
+
+describe("assertTestPathIsEphemeral", () => {
+  test("allows paths under tmpdir, existing or not", () => {
+    expect(() =>
+      assertTestPathIsEphemeral(join(tmpdir(), "guard-missing", "x"), OPTIONS),
+    ).not.toThrow();
+  });
+
+  test("refuses paths outside tmpdir, naming the escape hatch and hint", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const dir = join(homedir(), "test-path-guard-live");
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use[\s\S]*package root[\s\S]*TEST_PATH_GUARD_ALLOW/,
+    );
+  });
+
+  test("refuses a tmpdir symlink that resolves outside tmpdir", () => {
+    delete process.env[OPTIONS.allowEnvVar];
+    const link = join(tmpdir(), `test-path-guard-escape-${process.pid}`);
+    rmSync(link, { force: true });
+    symlinkSync(homedir(), link);
+    try {
+      expect(() => assertTestPathIsEphemeral(link, OPTIONS)).toThrow(
+        /Refusing to use/,
+      );
+    } finally {
+      rmSync(link, { force: true });
+    }
+  });
+
+  test("the allow env var bypasses the guard, per call", () => {
+    const dir = join(homedir(), "test-path-guard-optout");
+    process.env[OPTIONS.allowEnvVar] = "1";
+    try {
+      expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).not.toThrow();
+    } finally {
+      delete process.env[OPTIONS.allowEnvVar];
+    }
+    expect(() => assertTestPathIsEphemeral(dir, OPTIONS)).toThrow(
+      /Refusing to use/,
+    );
+  });
+});

package/node_modules/@vellumai/environments/src/test-path-guard.ts

@@ -0,0 +1,113 @@
+/**
+ * Live-path guard for test processes, shared by every service that resolves
+ * install-layout paths (the assistant daemon's workspace/root, the gateway's
+ * workspace and security dirs).
+ *
+ * A test process must never resolve one of those paths to a real, non-temp
+ * directory: production code exercised by a test would then read and
+ * destructively write live state. The tmpdir redirection normally comes from
+ * each package's bunfig.toml test preload, but bun only loads bunfig from
+ * the cwd, so `bun test` run from any other directory skips the preload and
+ * inherits the ambient env (or a ~/.vellum fallback). The containment
+ * assertion therefore lives in production code, where it fires no matter how
+ * the test process was launched.
+ *
+ * assistant/src/__tests__/assert-not-live-db.ts keeps its own containment
+ * check: test machinery must not import production dependencies.
+ */
+
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+
+/**
+ * Resolve symlinks in the deepest existing ancestor of `path`, then
+ * re-append the not-yet-created tail. This keeps containment checks honest
+ * both for paths under a symlinked temp root (macOS /var/folders) and for
+ * symlinks that point outside it, whether or not the leaf exists yet.
+ */
+export function canonicalizePathThroughExistingParent(path: string): string {
+  const resolvedPath = resolve(path);
+  const pendingSegments: string[] = [];
+  let currentPath = resolvedPath;
+
+  while (true) {
+    try {
+      return resolve(realpathSync(currentPath), ...pendingSegments.reverse());
+    } catch {
+      const parentPath = dirname(currentPath);
+      if (parentPath === currentPath) {
+        return resolvedPath;
+      }
+      pendingSegments.push(basename(currentPath));
+      currentPath = parentPath;
+    }
+  }
+}
+
+/** Lazily computed: is this process a `bun test` run? */
+let isTestProcess: boolean | undefined;
+
+/**
+ * True when this process is a `bun test` run. Computed once and cached for
+ * the process lifetime, so a runtime flip of NODE_ENV or BUN_TEST does not
+ * change the answer. Test-mode behavior toggles that must observe such
+ * flips read the env directly instead of calling this.
+ */
+export function isBunTestProcess(): boolean {
+  isTestProcess ??=
+    process.env.NODE_ENV === "test" ||
+    process.env.BUN_TEST === "1" ||
+    // `bun test` sets NODE_ENV=test only when unset; Bun.main being the test
+    // file itself is the backstop signal that survives a preset NODE_ENV.
+    (typeof Bun !== "undefined" &&
+      /\.(test|spec)\.[cm]?[jt]sx?$/.test(Bun.main));
+  return isTestProcess;
+}
+
+export interface EphemeralTestPathOptions {
+  /**
+   * Escape hatch for the rare intentional run against real state: setting
+   * this env var to "1" bypasses the guard. Callers reuse the variable their
+   * DB-open guard already honors. Deliberately not forwarded into
+   * agent-spawned shells (assistant/src/tools/terminal/safe-env.ts), so a
+   * daemon-level opt-out cannot disarm the guard for tests run from there.
+   */
+  allowEnvVar: string;
+  /** Package-specific line telling the reader where to run tests from. */
+  runHint: string;
+}
+
+/**
+ * Throws when called in a bun-test process and `dir` does not resolve under
+ * `os.tmpdir()`. Inert outside test processes. Canonicalizes on every call
+ * (no memo): a previously validated path could later be replaced by a
+ * symlink, and the guard only runs in test processes anyway.
+ */
+export function assertTestPathIsEphemeral(
+  dir: string,
+  options: EphemeralTestPathOptions,
+): void {
+  if (!isBunTestProcess()) {
+    return;
+  }
+  if (process.env[options.allowEnvVar] === "1") {
+    return;
+  }
+  const tmpRoot = canonicalizePathThroughExistingParent(tmpdir());
+  const resolved = canonicalizePathThroughExistingParent(dir);
+  if (resolved !== tmpRoot && !resolved.startsWith(tmpRoot + sep)) {
+    throw new Error(
+      [
+        `Refusing to use ${dir} (resolves to ${resolved}) in a test process: it is not under the temp directory (${tmpRoot}).`,
+        "",
+        "Tests must only touch ephemeral state; a real directory would expose",
+        "live install state to destructive test fixtures. This usually means",
+        "`bun test` ran from a cwd without the package's bunfig.toml, so the",
+        "test preload that redirects paths to a tmpdir never loaded.",
+        options.runHint,
+        `Set ${options.allowEnvVar}=1 to bypass deliberately.`,
+      ].join("\n"),
+    );
+  }
+}

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -66,6 +66,13 @@ export function isChannelId(value: unknown): value is ChannelId {
  * That irregularity is why this is stated rather than derived from the key,
  * and it is stated here because this file already owns what a channel is.
  *
+ * Both senses can hold a user token, which is the sharpest edge. The `slack`
+ * integration's persisted token *is* the installer's user token, held on its
+ * OAuth connection. `slack_channel` holds an optional `user_token` in the
+ * credential store, beside its bot and app tokens. Same words, different
+ * homes, and only the second is a credential-store key: a pasted token is
+ * always the channel's, because the integration's never leaves the exchange.
+ *
  * Deliberately only the key. What fields each credential requires is declared
  * once already, per service, in the gateway's credential specs; restating it
  * here would be a second copy of a different fact.

package/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -66,6 +66,13 @@ export function isChannelId(value: unknown): value is ChannelId {
  * That irregularity is why this is stated rather than derived from the key,
  * and it is stated here because this file already owns what a channel is.
  *
+ * Both senses can hold a user token, which is the sharpest edge. The `slack`
+ * integration's persisted token *is* the installer's user token, held on its
+ * OAuth connection. `slack_channel` holds an optional `user_token` in the
+ * credential store, beside its bot and app tokens. Same words, different
+ * homes, and only the second is a credential-store key: a pasted token is
+ * always the channel's, because the integration's never leaves the exchange.
+ *
  * Deliberately only the key. What fields each credential requires is declared
  * once already, per service, in the gateway's credential specs; restating it
  * here would be a second copy of a different fact.

package/openapi.yaml

@@ -16253,14 +16253,14 @@ paths:
               type: object
               properties:
                 botToken:
-                  type: string
                   description: Slack bot token
-                appToken:
                   type: string
+                appToken:
                   description: Slack app-level token
-              required:
-                - botToken
-                - appToken
+                  type: string
+                userToken:
+                  description: Slack user token, for reading channels the bot is not in
+                  type: string
       responses:
         "200":
           description: Successful response

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.7-dev.202608281503.cbafd6c",
+  "version": "0.11.7-dev.202608282003.8ce5421",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/credential-health-service.test.ts

@@ -12,6 +12,8 @@ let mockProviders: Array<{
   pingMethod: string | null;
   pingHeaders: string | null;
   pingBody: string | null;
+  authorizeParams: string | null;
+  scopeSeparator: string | null;
   managedServiceConfigKey?: string;
 }> = [];
 
@@ -191,11 +193,16 @@ function addProvider(
     pingUrl?: string | null;
     pingMethod?: string | null;
     managedServiceConfigKey?: string;
+    authorizeParams?: Record<string, string>;
   },
 ) {
   mockProviders.push({
     provider,
     defaultScopes: JSON.stringify(opts?.defaultScopes ?? []),
+    authorizeParams: opts?.authorizeParams
+      ? JSON.stringify(opts.authorizeParams)
+      : null,
+    scopeSeparator: " ",
     pingUrl: opts?.pingUrl ?? null,
     pingMethod: opts?.pingMethod ?? null,
     pingHeaders: null,
@@ -443,6 +450,44 @@ describe("credential-health-service", () => {
     expect(report.results[0]!.canAutoRecover).toBe(false);
   });
 
+  test("measures a user-token grant against user_scope, not the bot scopes", async () => {
+    // Slack issues two grants from one authorization and the stored token is
+    // the user one, so its grant is compared against `user_scope`. Measuring
+    // it against the bot `scope` parameter reports scopes that grant can never
+    // hold: `channels:join` is bot-only and is never requested for the user.
+    addProvider("slack", {
+      defaultScopes: ["channels:join", "chat:write", "search:read"],
+      authorizeParams: { user_scope: "chat:write,search:read" },
+    });
+    addConnection("slack", "conn-1", {
+      grantedScopes: ["chat:write", "search:read"],
+      expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000,
+    });
+    setToken("conn-1");
+
+    const report = await checkAllCredentials();
+    expect(report.results[0]!.status).not.toBe("missing_scopes");
+    expect(report.results[0]!.missingScopes).toEqual([]);
+  });
+
+  test("still reports a user scope the installer did not grant", async () => {
+    // Sensitivity check for the test above: comparing against `user_scope`
+    // must keep catching a genuinely declined user scope, not pass everything.
+    addProvider("slack", {
+      defaultScopes: ["channels:join", "chat:write", "search:read"],
+      authorizeParams: { user_scope: "chat:write,search:read" },
+    });
+    addConnection("slack", "conn-1", {
+      grantedScopes: ["chat:write"],
+      expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000,
+    });
+    setToken("conn-1");
+
+    const report = await checkAllCredentials();
+    expect(report.results[0]!.status).toBe("missing_scopes");
+    expect(report.results[0]!.missingScopes).toEqual(["search:read"]);
+  });
+
   test("returns revoked when ping returns 401", async () => {
     mockFetchResponse = { ok: false, status: 401 };
     addProvider("google", {

package/src/__tests__/db-conversation-fork-lineage-migration.test.ts

@@ -3,8 +3,6 @@ import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
-const originalBunTest = process.env.BUN_TEST;
-
 import { getSqliteFrom } from "../persistence/db-connection.js";
 import { migrateConversationForkLineage } from "../persistence/migrations/183-add-conversation-fork-lineage.js";
 import * as schema from "../persistence/schema/index.js";
@@ -62,12 +60,10 @@ function resetMigrationTestDb(): void {
 
 describe("conversation fork lineage migration", () => {
   beforeEach(() => {
-    process.env.BUN_TEST = "0";
     resetMigrationTestDb();
   });
 
   afterAll(() => {
-    process.env.BUN_TEST = originalBunTest;
     resetMigrationTestDb();
   });
 

package/src/__tests__/db-conversation-inference-profile-migration.test.ts

@@ -3,8 +3,6 @@ import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
-const originalBunTest = process.env.BUN_TEST;
-
 import { _resetDisplayOrderMigrationForTests } from "../persistence/conversation-display-order-migration.js";
 import { _resetGroupMigrationForTests } from "../persistence/conversation-group-migration.js";
 import { getSqliteFrom } from "../persistence/db-connection.js";
@@ -68,12 +66,10 @@ function resetMigrationTestDb(): void {
 
 describe("conversation inference profile migration", () => {
   beforeEach(() => {
-    process.env.BUN_TEST = "0";
     resetMigrationTestDb();
   });
 
   afterAll(() => {
-    process.env.BUN_TEST = originalBunTest;
     resetMigrationTestDb();
   });
 

package/src/__tests__/db-llm-request-log-provider-migration.test.ts

@@ -10,8 +10,6 @@ import {
 
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
-const originalBunTest = process.env.BUN_TEST;
-
 import { getSqliteFrom } from "../persistence/db-connection.js";
 import { migrateLlmRequestLogProvider } from "../persistence/migrations/184-llm-request-log-provider.js";
 import * as schema from "../persistence/schema/index.js";
@@ -48,7 +46,6 @@ function bootstrapPreProviderLlmRequestLogs(raw: Database): void {
 
 describe("llm_request_logs provider migration", () => {
   beforeEach(() => {
-    process.env.BUN_TEST = "0";
     resetDbForTesting();
   });
 
@@ -57,11 +54,6 @@ describe("llm_request_logs provider migration", () => {
   });
 
   afterAll(() => {
-    if (originalBunTest === undefined) {
-      delete process.env.BUN_TEST;
-    } else {
-      process.env.BUN_TEST = originalBunTest;
-    }
     resetDbForTesting();
   });
 

package/src/__tests__/guardian-gateway-sim.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+
+import { createGuardianGatewaySim } from "./guardian-gateway-sim.js";
+
+import "./test-preload.js";
+
+/**
+ * Pins the simulator to the gateway's authorization-lifecycle contract.
+ * Fifteen assistant suites prove behavior against this sim, so a sim whose
+ * semantics drift from the gateway's lets them pass against a production
+ * shape that does not exist.
+ */
+describe("guardian gateway sim: boot expiry contract", () => {
+  test("expires only interaction-bound kinds, never persistent kinds", async () => {
+    const sim = createGuardianGatewaySim();
+    const past = Date.now() - 60_000;
+    sim.seedRequest({ id: "ta", kind: "tool_approval", status: "pending" });
+    sim.seedRequest({
+      id: "pq",
+      kind: "pending_question",
+      status: "pending",
+    });
+    // Past-deadline persistent rows stay pending for the sweep, which owns
+    // the card-withdrawal and requester-notice fan-out; boot must not
+    // pre-empt it (the gateway contract this sim mirrors).
+    sim.seedRequest({
+      id: "ar",
+      kind: "access_request",
+      status: "pending",
+      expiresAt: past,
+    });
+    sim.seedRequest({
+      id: "tg",
+      kind: "tool_grant_request",
+      status: "pending",
+      expiresAt: past,
+    });
+
+    const expired = await sim.module.expireInteractionBoundGuardianRequests();
+
+    expect(expired).toBe(2);
+    expect(sim.getRequest("ta")?.status).toBe("expired");
+    expect(sim.getRequest("pq")?.status).toBe("expired");
+    expect(sim.getRequest("ar")?.status).toBe("pending");
+    expect(sim.getRequest("tg")?.status).toBe("pending");
+  });
+});

package/src/__tests__/guardian-gateway-sim.ts

@@ -364,9 +364,13 @@ export function createGuardianGatewaySim() {
       if (row.status !== "pending") {
         continue;
       }
+      // Mirrors the gateway contract: only the kinds that die with the
+      // daemon's in-memory pendingInteractions map expire at boot.
+      // Persistent kinds stay pending, whatever their deadline; their
+      // expiry belongs to the sweep, which owns the fan-out.
       const interactionBound =
         row.kind === "tool_approval" || row.kind === "pending_question";
-      if (interactionBound || isGuardianRequestExpired(row, now)) {
+      if (interactionBound) {
         row.status = "expired";
         row.updatedAt = now;
         expired += 1;

package/src/__tests__/non-member-access-request.test.ts

@@ -318,6 +318,18 @@ describe("non-member access request notification", () => {
       kind: "access_request",
     });
     expect(pending.length).toBe(1);
+
+    // A pending row past its deadline never dedupes: it can sit pending
+    // until the sweep expires it, it is already undecidable, and absorbing
+    // the fresh attempt would silently drop the new guardian notification.
+    pending[0].expiresAt = Date.now() - 1000;
+    const req3 = buildInboundRequest({
+      externalMessageId: `msg-third-${Date.now()}`,
+      content: "Still hoping to get access.",
+    });
+    await handleChannelInbound(req3, undefined, TEST_BEARER_TOKEN);
+
+    expect(emitSignalCalls.length).toBe(2);
   });
 
   // A bare guardian deny (a `denied` request with no durable contact seeded)

package/src/channels/gateway-guardian-requests.ts

@@ -210,9 +210,10 @@ export async function expireGuardianRequest(id: string): Promise<void> {
 
 /**
  * Daemon-boot expiry: interaction-bound kinds die with the daemon's
- * in-memory pendingInteractions map, plus persistent kinds already past
- * `expiresAt`. Returns the expired count. Throws on any failure
- * (fail-closed).
+ * in-memory pendingInteractions map. Persistent kinds are never touched
+ * here, whatever their deadline; their expiry belongs to the sweep, which
+ * owns the card-withdrawal and requester-notice fan-out. Returns the
+ * expired count. Throws on any failure (fail-closed).
  */
 export async function expireInteractionBoundGuardianRequests(): Promise<number> {
   const response = await callGateway(

package/src/cli/commands/__tests__/browser.test.ts

@@ -536,9 +536,7 @@ describe("--json output", () => {
 });
 
 describe("formatBrowserStatusLines", () => {
-  test("prints userActions including the Chrome Web Store install URL", () => {
-    const installUrl =
-      "https://chromewebstore.google.com/detail/vellum-assistant-browser/hphbdmpffeigpcdjkckleobjmhhokpne";
+  test("prints userActions for a disconnected extension", () => {
     const lines = formatBrowserStatusLines(
       JSON.stringify({
         requestedMode: "auto",
@@ -552,8 +550,8 @@ describe("formatBrowserStatusLines", () => {
             summary:
               "Extension mode is unavailable: no Chrome Extension is connected.",
             userActions: [
-              `Install the Vellum Assistant Chrome extension from the Chrome Web Store: ${installUrl}`,
-              "Open the extension and pair with your assistant.",
+              "Install the Vellum Assistant Chrome extension from the Chrome Web Store: https://chromewebstore.google.com/detail/vellum-assistant-browser/hphbdmpffeigpcdjkckleobjmhhokpne",
+              "Tell the user to make sure a browser is open with the Vellum Chrome extension on.",
             ],
           },
         ],
@@ -564,8 +562,12 @@ describe("formatBrowserStatusLines", () => {
     const rendered = lines!.join("\n");
     expect(rendered).toContain("Requested mode: auto");
     expect(rendered).toContain("✗ extension (auto-candidate)");
-    expect(rendered).toContain(installUrl);
-    expect(rendered).toContain("Open the extension and pair with your assistant.");
+    expect(rendered).toContain(
+      "Install the Vellum Assistant Chrome extension from the Chrome Web Store:",
+    );
+    expect(rendered).toContain(
+      "Tell the user to make sure a browser is open with the Vellum Chrome extension on.",
+    );
   });
 
   test("omits userActions when the mode is ready", () => {

package/src/credential-health/credential-health-service.ts

@@ -4,9 +4,19 @@
  * Enumerates all active OAuth connections and validates each one for:
  * - Token presence in secure storage
  * - Token expiry (expired or expiring within the warning window)
- * - Scope coverage (grantedScopes vs provider defaultScopes)
+ * - Scope coverage (grantedScopes vs the request that produced the token)
  * - Liveness ping (for providers with a pingUrl)
  *
+ * Scope coverage asks whether a connection carries the scopes the provider
+ * currently requests for the token it stores, which is how a newly required
+ * scope reaches an existing install and prompts a re-authorization. It applies
+ * only where an authorization makes a request. A manual-token provider (a bot
+ * token pasted in, e.g. `slack_channel`) has no request and carries empty
+ * scope lists here; it is still checked for token presence and liveness. What
+ * its token actually carries is read live from the `x-oauth-scopes` response
+ * header by `runtime/channel-readiness-service.ts`, which is the only source
+ * of truth available for a credential this service never negotiated.
+ *
  * Designed to run during the heartbeat cycle. The BYO liveness ping is
  * routed through `withValidToken`, so a stale-but-refreshable access token
  * is refreshed transparently before the ping fires — this prevents the
@@ -24,7 +34,10 @@ import {
   type OAuthConnectionRow,
   type OAuthProviderRow,
 } from "../oauth/oauth-store.js";
-import { scopeDifference } from "../oauth/scope-utils.js";
+import {
+  expectedScopesForStoredToken,
+  scopeDifference,
+} from "../oauth/scope-utils.js";
 import {
   TokenExpiredError,
   withValidToken,
@@ -182,6 +195,8 @@ interface CheckConnectionOpts {
   hasRefreshToken: boolean;
   grantedScopesRaw: string;
   defaultScopesRaw: string;
+  authorizeParamsRaw: string | null;
+  scopeSeparator: string | null;
   pingUrl: string | null;
   pingMethod: string | null;
   pingHeaders: string | null;
@@ -199,6 +214,8 @@ async function checkConnection(
     hasRefreshToken,
     grantedScopesRaw,
     defaultScopesRaw,
+    authorizeParamsRaw,
+    scopeSeparator,
     pingUrl,
     pingMethod,
     pingHeaders,
@@ -268,11 +285,21 @@ async function checkConnection(
     // Has refresh token — not an issue, auto-refresh will handle it
   }
 
-  // 3. Check scope coverage
+  // 3. Check scope coverage, against the request that produced the stored
+  // token rather than the provider's bot-side `scope` parameter. A provider
+  // asking for user scopes as well stores the user token and records that
+  // token's grant, so the bot request names scopes that grant can never hold.
   const grantedScopes = safeJsonParse<string[]>(grantedScopesRaw, []);
-  const defaultScopes = safeJsonParse<string[]>(defaultScopesRaw, []);
-  if (defaultScopes.length > 0 && grantedScopes.length > 0) {
-    const missing = scopeDifference(defaultScopes, grantedScopes);
+  const expectedScopes = expectedScopesForStoredToken(
+    safeJsonParse<string[]>(defaultScopesRaw, []),
+    safeJsonParse<Record<string, string> | undefined>(
+      authorizeParamsRaw,
+      undefined,
+    ),
+    scopeSeparator ?? undefined,
+  );
+  if (expectedScopes.length > 0 && grantedScopes.length > 0) {
+    const missing = scopeDifference(expectedScopes, grantedScopes);
     if (missing.length > 0) {
       return {
         ...base,
@@ -637,6 +664,8 @@ export async function checkAllCredentials(): Promise<CredentialHealthReport> {
           hasRefreshToken: !!conn.hasRefreshToken,
           grantedScopesRaw: conn.grantedScopes,
           defaultScopesRaw: providerRow.defaultScopes,
+          authorizeParamsRaw: providerRow.authorizeParams,
+          scopeSeparator: providerRow.scopeSeparator,
           pingUrl: providerRow.pingUrl,
           pingMethod: providerRow.pingMethod,
           pingHeaders: providerRow.pingHeaders,
@@ -750,6 +779,8 @@ export async function checkCredentialForProvider(
       hasRefreshToken: !!conn.hasRefreshToken,
       grantedScopesRaw: conn.grantedScopes,
       defaultScopesRaw: providerRow.defaultScopes,
+      authorizeParamsRaw: providerRow.authorizeParams,
+      scopeSeparator: providerRow.scopeSeparator,
       pingUrl: providerRow.pingUrl,
       pingMethod: providerRow.pingMethod,
       pingHeaders: providerRow.pingHeaders,