gogcli-mcp 2.20.0 → 2.21.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-    "version": "2.20.0"
+    "version": "2.21.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli",
       "source": "./",
       "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-      "version": "2.20.0",
+      "version": "2.21.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp",
   "displayName": "gogcli",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/dist/index.js

@@ -4264,8 +4264,8 @@ var require_core = __commonJS({
             return this;
           }
           case "object": {
-            const cacheKey = schemaKeyRef;
-            this._cache.delete(cacheKey);
+            const cacheKey2 = schemaKeyRef;
+            this._cache.delete(cacheKey2);
             let id = schemaKeyRef[this.opts.schemaId];
             if (id) {
               id = (0, resolve_1.normalizeId)(id);
@@ -23068,17 +23068,33 @@ function normalizeObjectSchema(schema) {
   }
   return void 0;
 }
+function getDotPath(path) {
+  if (path.length === 0) {
+    return "object root";
+  }
+  return path.reduce((acc, seg, index) => {
+    if (index === 0) {
+      return String(seg);
+    }
+    if (typeof seg === "number") {
+      return `${acc}[${seg}]`;
+    }
+    return `${acc}.${seg}`;
+  }, "");
+}
 function getParseErrorMessage(error51) {
   if (error51 && typeof error51 === "object") {
+    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
+      return error51.issues.map((i) => {
+        if (!i.path?.length) {
+          return i.message;
+        }
+        return `${i.message} at ${getDotPath(i.path)}`;
+      }).join("\n");
+    }
     if ("message" in error51 && typeof error51.message === "string") {
       return error51.message;
     }
-    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
-      const firstIssue = error51.issues[0];
-      if (firstIssue && typeof firstIssue === "object" && "message" in firstIssue) {
-        return String(firstIssue.message);
-      }
-    }
     try {
       return JSON.stringify(error51);
     } catch {
@@ -29693,16 +29709,7 @@ var Server = class extends Protocol {
     if (!methodSchema) {
       throw new Error("Schema is missing a method literal");
     }
-    let methodValue;
-    if (isZ4Schema(methodSchema)) {
-      const v4Schema = methodSchema;
-      const v4Def = v4Schema._zod?.def;
-      methodValue = v4Def?.value ?? v4Schema.value;
-    } else {
-      const v3Schema = methodSchema;
-      const legacyDef = v3Schema._def;
-      methodValue = legacyDef?.value ?? v3Schema.value;
-    }
+    const methodValue = getLiteralValue(methodSchema);
     if (typeof methodValue !== "string") {
       throw new Error("Schema method literal must be a string");
     }
@@ -30890,8 +30897,17 @@ var EMPTY_COMPLETION_RESULT = {
 import process3 from "node:process";
 
 // ../../node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 var ReadBuffer = class {
+  constructor(options) {
+    this._maxBufferSize = options?.maxBufferSize ?? STDIO_DEFAULT_MAX_BUFFER_SIZE;
+  }
   append(chunk) {
+    const newSize = (this._buffer?.length ?? 0) + chunk.length;
+    if (newSize > this._maxBufferSize) {
+      this.clear();
+      throw new Error(`ReadBuffer exceeded maximum size of ${this._maxBufferSize} bytes`);
+    }
     this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
   }
   readMessage() {
@@ -30919,18 +30935,24 @@ function serializeMessage(message) {
 
 // ../../node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 var StdioServerTransport = class {
-  constructor(_stdin = process3.stdin, _stdout = process3.stdout) {
+  constructor(_stdin = process3.stdin, _stdout = process3.stdout, options) {
     this._stdin = _stdin;
     this._stdout = _stdout;
-    this._readBuffer = new ReadBuffer();
     this._started = false;
     this._ondata = (chunk) => {
-      this._readBuffer.append(chunk);
-      this.processReadBuffer();
+      try {
+        this._readBuffer.append(chunk);
+        this.processReadBuffer();
+      } catch (error51) {
+        this.onerror?.(error51);
+        this.close().catch(() => {
+        });
+      }
     };
     this._onerror = (error51) => {
       this.onerror?.(error51);
     };
+    this._readBuffer = new ReadBuffer({ maxBufferSize: options?.maxBufferSize });
   }
   /**
    * Starts listening for messages on stdin.
@@ -31567,7 +31589,9 @@ function registerRunTool(server, options) {
 function errorText(err) {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
-var AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
+var DEFINITE_AUTH_PATTERN = /\b(401|unauthorized|invalid_grant)\b/i;
+var STALE_TOKEN_PATTERN = /\b(?:access[ _-]?)?token\b[^.;\n]{0,40}\b(?:has\s+)?(?:been\s+)?(?:expired|revoked)\b|\b(?:expired|revoked)\s+(?:access[ _-]?)?token\b/i;
+var AUTH_ERROR_PATTERN = new RegExp(`${DEFINITE_AUTH_PATTERN.source}|${STALE_TOKEN_PATTERN.source}`, "i");
 var INVALID_GRANT_PATTERN = /invalid_grant|token has been expired or revoked/i;
 var TRANSIENT_ERROR_PATTERN = /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
 var GRID_LIMIT_ERROR_PATTERN = /exceeds grid limits/i;
@@ -31588,8 +31612,8 @@ function formatAccountList(raw) {
 async function diagnose(err) {
   const errText = errorText(err);
   const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
-  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isTransientError = !DEFINITE_AUTH_PATTERN.test(errText) && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isAuthError = !isTransientError && AUTH_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
   const hint = isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
   try {
@@ -31710,7 +31734,7 @@ function registerApiTools(server) {
 function registerAuthToolsWith(server, defaultServices) {
   const servicesDescribe = `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "${defaultServices}". Prefer the narrowest set you need \u2014 requesting a service whose Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request with invalid_scope.`;
   server.registerTool("gog_auth_list", {
-    description: "List all Google accounts stored in gogcli. Use this to check which accounts are configured and available.",
+    description: "List the Google accounts stored in gogcli, with their scopes. This reads local configuration only \u2014 it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.",
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -33079,7 +33103,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.20.0" : "0.0.0";
+var VERSION = true ? "2.21.0" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,
@@ -33094,6 +33118,83 @@ var BASE_TOOL_REGISTRARS = [
   registerTasksTools
 ];
 
+// src/google-token.ts
+var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+var EXPIRY_MARGIN_MS = 12e4;
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+async function cacheKey(refreshToken, clientId) {
+  const data = new TextEncoder().encode(`${clientId}\0${refreshToken}`);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function makeAccessTokenSource(env) {
+  const direct = readEnvVar("GOG_ACCESS_TOKEN", { env });
+  if (direct) return async () => direct;
+  const refreshToken = readEnvVar("GOG_REFRESH_TOKEN", { env });
+  if (!refreshToken) return void 0;
+  const clientId = readEnvVar("GOG_CLIENT_ID", { env });
+  const clientSecret = readEnvVar("GOG_CLIENT_SECRET", { env });
+  if (!clientId || !clientSecret) {
+    const missing = [!clientId && "GOG_CLIENT_ID", !clientSecret && "GOG_CLIENT_SECRET"].filter(Boolean).join(" and ");
+    return async () => {
+      throw new Error(
+        `GOG_REFRESH_TOKEN is set but ${missing} is not, so no access token can be minted. Set the OAuth client alongside the refresh token, or unset GOG_REFRESH_TOKEN to use the backend\u2019s own identity.`
+      );
+    };
+  }
+  return async () => {
+    const key = await cacheKey(refreshToken, clientId);
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return hit.accessToken;
+    let pending = inFlight.get(key);
+    if (!pending) {
+      pending = exchange(refreshToken, clientId, clientSecret).then((minted2) => {
+        cache.set(key, minted2);
+        return minted2;
+      }).finally(() => inFlight.delete(key));
+      inFlight.set(key, pending);
+    }
+    const minted = await pending;
+    return minted.accessToken;
+  };
+}
+async function exchange(refreshToken, clientId, clientSecret) {
+  let res;
+  try {
+    res = await fetch(TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: clientId,
+        client_secret: clientSecret
+      }).toString()
+    });
+  } catch (err) {
+    throw new Error(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    if (body.error === "invalid_grant") {
+      throw new Error(
+        'the stored refresh token has expired or been revoked, so this account must be re-authorized (commonly the 7-day limit on OAuth consent screens still in "Testing" mode). Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.'
+      );
+    }
+    throw new Error(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`
+    );
+  }
+  if (!body.access_token) {
+    throw new Error("the access token could not be refreshed: Google returned no access_token");
+  }
+  const expiresInMs = (body.expires_in ?? 3600) * 1e3;
+  return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
+}
+
 // src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
@@ -33102,7 +33203,7 @@ var RUNNER_DRAINING = 503;
 function makeFlyExecutor(endpoint, key, readAccessToken) {
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
-    const accessToken = readAccessToken?.();
+    const accessToken = await readAccessToken?.();
     let res;
     try {
       res = await fetch(endpoint + "/run", {
@@ -33153,7 +33254,7 @@ function useRemoteGogRunner(env = process.env) {
   const key = readEnvVar("GOG_RUNNER_KEY", { env });
   if (!endpoint || !key) return false;
   setDefaultGogExecutor(
-    makeFlyExecutor(endpoint.replace(/\/+$/, ""), key, () => readEnvVar("GOG_ACCESS_TOKEN", { env }))
+    makeFlyExecutor(endpoint.replace(/\/+$/, ""), key, makeAccessTokenSource(env))
   );
   return true;
 }

package/dist/lib.js

@@ -4263,8 +4263,8 @@ var require_core = __commonJS({
             return this;
           }
           case "object": {
-            const cacheKey = schemaKeyRef;
-            this._cache.delete(cacheKey);
+            const cacheKey2 = schemaKeyRef;
+            this._cache.delete(cacheKey2);
             let id = schemaKeyRef[this.opts.schemaId];
             if (id) {
               id = (0, resolve_1.normalizeId)(id);
@@ -22922,6 +22922,9 @@ var McpZodTypeKind;
   McpZodTypeKind2["Completable"] = "McpCompletable";
 })(McpZodTypeKind || (McpZodTypeKind = {}));
 
+// ../../node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
+
 // ../../node_modules/@chrischall/mcp-utils/dist/errors/index.js
 var BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
 var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
@@ -23470,7 +23473,9 @@ function registerRunTool(server, options) {
 function errorText(err) {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
-var AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
+var DEFINITE_AUTH_PATTERN = /\b(401|unauthorized|invalid_grant)\b/i;
+var STALE_TOKEN_PATTERN = /\b(?:access[ _-]?)?token\b[^.;\n]{0,40}\b(?:has\s+)?(?:been\s+)?(?:expired|revoked)\b|\b(?:expired|revoked)\s+(?:access[ _-]?)?token\b/i;
+var AUTH_ERROR_PATTERN = new RegExp(`${DEFINITE_AUTH_PATTERN.source}|${STALE_TOKEN_PATTERN.source}`, "i");
 var INVALID_GRANT_PATTERN = /invalid_grant|token has been expired or revoked/i;
 var TRANSIENT_ERROR_PATTERN = /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
 var GRID_LIMIT_ERROR_PATTERN = /exceeds grid limits/i;
@@ -23491,8 +23496,8 @@ function formatAccountList(raw) {
 async function diagnose(err) {
   const errText = errorText(err);
   const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
-  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isTransientError = !DEFINITE_AUTH_PATTERN.test(errText) && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isAuthError = !isTransientError && AUTH_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
   const hint = isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
   try {
@@ -23613,7 +23618,7 @@ function registerApiTools(server) {
 function registerAuthToolsWith(server, defaultServices) {
   const servicesDescribe = `Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "${defaultServices}". Prefer the narrowest set you need \u2014 requesting a service whose Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request with invalid_scope.`;
   server.registerTool("gog_auth_list", {
-    description: "List all Google accounts stored in gogcli. Use this to check which accounts are configured and available.",
+    description: "List the Google accounts stored in gogcli, with their scopes. This reads local configuration only \u2014 it does not contact Google and does NOT tell you whether an account still works: a signed-out account whose refresh token expired or was revoked is listed here exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account can actually authenticate.",
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -24985,7 +24990,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.20.0" : "0.0.0";
+var VERSION = true ? "2.21.0" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,
@@ -25000,6 +25005,83 @@ var BASE_TOOL_REGISTRARS = [
   registerTasksTools
 ];
 
+// src/google-token.ts
+var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+var EXPIRY_MARGIN_MS = 12e4;
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+async function cacheKey(refreshToken, clientId) {
+  const data = new TextEncoder().encode(`${clientId}\0${refreshToken}`);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function makeAccessTokenSource(env) {
+  const direct = readEnvVar("GOG_ACCESS_TOKEN", { env });
+  if (direct) return async () => direct;
+  const refreshToken = readEnvVar("GOG_REFRESH_TOKEN", { env });
+  if (!refreshToken) return void 0;
+  const clientId = readEnvVar("GOG_CLIENT_ID", { env });
+  const clientSecret = readEnvVar("GOG_CLIENT_SECRET", { env });
+  if (!clientId || !clientSecret) {
+    const missing = [!clientId && "GOG_CLIENT_ID", !clientSecret && "GOG_CLIENT_SECRET"].filter(Boolean).join(" and ");
+    return async () => {
+      throw new Error(
+        `GOG_REFRESH_TOKEN is set but ${missing} is not, so no access token can be minted. Set the OAuth client alongside the refresh token, or unset GOG_REFRESH_TOKEN to use the backend\u2019s own identity.`
+      );
+    };
+  }
+  return async () => {
+    const key = await cacheKey(refreshToken, clientId);
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return hit.accessToken;
+    let pending = inFlight.get(key);
+    if (!pending) {
+      pending = exchange(refreshToken, clientId, clientSecret).then((minted2) => {
+        cache.set(key, minted2);
+        return minted2;
+      }).finally(() => inFlight.delete(key));
+      inFlight.set(key, pending);
+    }
+    const minted = await pending;
+    return minted.accessToken;
+  };
+}
+async function exchange(refreshToken, clientId, clientSecret) {
+  let res;
+  try {
+    res = await fetch(TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: clientId,
+        client_secret: clientSecret
+      }).toString()
+    });
+  } catch (err) {
+    throw new Error(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    if (body.error === "invalid_grant") {
+      throw new Error(
+        'the stored refresh token has expired or been revoked, so this account must be re-authorized (commonly the 7-day limit on OAuth consent screens still in "Testing" mode). Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.'
+      );
+    }
+    throw new Error(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`
+    );
+  }
+  if (!body.access_token) {
+    throw new Error("the access token could not be refreshed: Google returned no access_token");
+  }
+  const expiresInMs = (body.expires_in ?? 3600) * 1e3;
+  return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
+}
+
 // src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
@@ -25008,7 +25090,7 @@ var RUNNER_DRAINING = 503;
 function makeFlyExecutor(endpoint, key, readAccessToken) {
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
-    const accessToken = readAccessToken?.();
+    const accessToken = await readAccessToken?.();
     let res;
     try {
       res = await fetch(endpoint + "/run", {
@@ -25059,7 +25141,7 @@ function useRemoteGogRunner(env = process.env) {
   const key = readEnvVar("GOG_RUNNER_KEY", { env });
   if (!endpoint || !key) return false;
   setDefaultGogExecutor(
-    makeFlyExecutor(endpoint.replace(/\/+$/, ""), key, () => readEnvVar("GOG_ACCESS_TOKEN", { env }))
+    makeFlyExecutor(endpoint.replace(/\/+$/, ""), key, makeAccessTokenSource(env))
   );
   return true;
 }

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -41,8 +41,8 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.13.3",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@chrischall/mcp-utils": "^0.14.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "2.20.0",
+  "version": "2.21.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "2.20.0",
+      "version": "2.21.0",
       "transport": {
         "type": "stdio"
       },

package/src/connector-runtime.ts

@@ -78,11 +78,16 @@ const RUNNER_DRAINING = 503;
 export function makeFlyExecutor(
   endpoint: string,
   key: string,
-  readAccessToken?: () => string | undefined,
+  readAccessToken?: () => string | undefined | Promise<string | undefined>,
 ): GogExecutor {
   return async (args: GogArg[], opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
-    const accessToken = readAccessToken?.();
+    // Awaited, because the token may have to be MINTED (#241): a refresh token
+    // is what a registration stores, and the access token it yields lives about
+    // an hour. Deliberately NOT caught here — if the source throws, the call
+    // fails, because the alternative is running it as the backend's identity
+    // and handing this caller someone else's account.
+    const accessToken = await readAccessToken?.();
     let res: Response;
     try {
       res = await fetch(endpoint + '/run', {

package/src/google-token.ts

@@ -0,0 +1,225 @@
+import { readEnvVar } from '@chrischall/mcp-utils';
+
+/**
+ * Mint short-lived Google access tokens from a long-lived refresh token, so a
+ * hosted gog's identity belongs to the REGISTRATION rather than to the machine
+ * the binary runs on (#241).
+ *
+ * The shape of the problem: `gog` reads credentials from a keyring at
+ * `GOG_HOME`, on the box where it executes — which is why one Fly volume ended
+ * up being every registration's identity. But `gog --access-token` bypasses the
+ * keyring entirely, and #235 already carries such a token to the box per
+ * request. The only missing piece was that an access token lives about an hour,
+ * so it cannot be the thing you STORE. A refresh token can.
+ *
+ * So the refresh token stays here, in the child's environment, and only a
+ * one-hour access token ever crosses the wire. That is strictly better than the
+ * arrangement it replaces, where a permanent credential sat on a shared volume.
+ */
+
+const TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+
+/**
+ * Replace a token this long before it actually expires. A token that dies
+ * mid-flight is a failure the caller can do nothing about, and the exchange is
+ * cheap next to a failed tool call.
+ */
+const EXPIRY_MARGIN_MS = 120_000;
+
+interface CachedToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+/**
+ * Keyed by the CREDENTIAL, never a single "current token".
+ *
+ * A module-level current-token would be correct for one stdio process and
+ * silently wrong everywhere else: a Worker isolate serves many callers, so the
+ * first caller's identity would be handed to everyone after them. That is the
+ * same failure as the captured executor in #235 and the ambient store in #233 —
+ * three bugs, one shape, which is why this one is keyed from the start.
+ *
+ * The key is a hash rather than the token itself so that nothing which dumps or
+ * iterates this map (a heap snapshot, a debugger, a future logging line) puts a
+ * live credential in front of someone.
+ */
+const cache = new Map<string, CachedToken>();
+
+/**
+ * Exchanges currently in flight, so concurrent callers share ONE of them.
+ *
+ * Without this, `get` → `await exchange` → `set` has an await between the miss
+ * and the fill: every caller that arrives during that window also misses, and
+ * they all hit Google's token endpoint together. One process per caller hides
+ * it, but a Worker isolate serving many callers — or simply several tool calls
+ * in flight — turns a single refresh into a stampede, and being rate-limited
+ * for it produces exactly the intermittent auth failures this was meant to end.
+ *
+ * Keyed identically to `cache`, so two different credentials never wait on each
+ * other's exchange.
+ */
+const inFlight = new Map<string, Promise<CachedToken>>();
+
+/** Test seam: both maps are process-wide, so they do not unwind between tests. */
+export function clearAccessTokenCache(): void {
+  cache.clear();
+  inFlight.clear();
+}
+
+/**
+ * WebCrypto rather than `node:crypto`: this module is reachable from the Worker
+ * build, which has no node builtins. Both runtimes expose `crypto.subtle`.
+ */
+async function cacheKey(refreshToken: string, clientId: string): Promise<string> {
+  // NUL-separated, spelled as an escape so this source file stays text: it
+  // keeps a (clientId, refreshToken) pair from colliding with a different
+  // pair whose concatenation happens to match. Neither value can contain a
+  // NUL, which is what makes the boundary unambiguous.
+  const data = new TextEncoder().encode(`${clientId}\u0000${refreshToken}`);
+  const digest = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * What a token source is: something that answers "who is this call acting as",
+ * or throws trying. It never answers `undefined` after being configured —
+ * see the failure note below.
+ */
+export type AccessTokenSource = () => Promise<string | undefined>;
+
+export interface TokenEnv {
+  GOG_ACCESS_TOKEN?: string;
+  GOG_REFRESH_TOKEN?: string;
+  GOG_CLIENT_ID?: string;
+  GOG_CLIENT_SECRET?: string;
+  [key: string]: string | undefined;
+}
+
+/**
+ * Build the token source for this environment, or `undefined` when nothing is
+ * configured — which leaves the backend acting as itself, exactly as every
+ * registration did before this existed.
+ *
+ * Precedence puts a directly-supplied `GOG_ACCESS_TOKEN` first: someone who
+ * already holds a token should not need an OAuth client to use it, and it keeps
+ * the #230 path working untouched.
+ */
+export function makeAccessTokenSource(env: TokenEnv): AccessTokenSource | undefined {
+  const direct = readEnvVar('GOG_ACCESS_TOKEN', { env });
+  if (direct) return async () => direct;
+
+  const refreshToken = readEnvVar('GOG_REFRESH_TOKEN', { env });
+  if (!refreshToken) return undefined;
+
+  const clientId = readEnvVar('GOG_CLIENT_ID', { env });
+  const clientSecret = readEnvVar('GOG_CLIENT_SECRET', { env });
+
+  // A refresh token with no OAuth client cannot mint anything, and the WRONG
+  // repair is to treat it as unconfigured: that falls back to the backend's own
+  // identity, which is the precise confusion this feature exists to remove. So
+  // the source exists and throws when used — `tools/list` still works, the
+  // server still starts, and the first tool call says what is missing.
+  if (!clientId || !clientSecret) {
+    const missing = [!clientId && 'GOG_CLIENT_ID', !clientSecret && 'GOG_CLIENT_SECRET']
+      .filter(Boolean)
+      .join(' and ');
+    return async () => {
+      throw new Error(
+        `GOG_REFRESH_TOKEN is set but ${missing} is not, so no access token can be minted. ` +
+          'Set the OAuth client alongside the refresh token, or unset GOG_REFRESH_TOKEN to use the backend’s own identity.',
+      );
+    };
+  }
+
+  return async () => {
+    const key = await cacheKey(refreshToken, clientId);
+    const hit = cache.get(key);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return hit.accessToken;
+
+    // Join the exchange already running for this credential, or start the one
+    // everyone else will join.
+    let pending = inFlight.get(key);
+    if (!pending) {
+      pending = exchange(refreshToken, clientId, clientSecret)
+        .then((minted) => {
+          cache.set(key, minted);
+          return minted;
+        })
+        // Dropped whether it resolved OR threw. Keeping a rejected promise here
+        // would make one transient failure permanent for every later caller —
+        // the opposite of the "failures are not cached" rule above.
+        .finally(() => inFlight.delete(key));
+      inFlight.set(key, pending);
+    }
+    const minted = await pending;
+    return minted.accessToken;
+  };
+}
+
+/**
+ * Exchange refresh -> access.
+ *
+ * THROWS on every failure, and never returns `undefined`. Returning nothing
+ * would let the call proceed as the backend's identity, and the caller would
+ * read someone else's mailbox while everything looked like success — the same
+ * reasoning that made a malformed token a 400 rather than an ignore in #235.
+ *
+ * Nothing here is cached on failure either, so a transient Google outage does
+ * not become a sticky one.
+ */
+async function exchange(refreshToken: string, clientId: string, clientSecret: string): Promise<CachedToken> {
+  let res: Response;
+  try {
+    res = await fetch(TOKEN_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        refresh_token: refreshToken,
+        client_id: clientId,
+        client_secret: clientSecret,
+      }).toString(),
+    });
+  } catch (err) {
+    throw new Error(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const body = (await res.json().catch(() => ({}))) as {
+    access_token?: string;
+    expires_in?: number;
+    error?: string;
+    error_description?: string;
+  };
+
+  if (!res.ok) {
+    // invalid_grant is the one worth naming, because it is not a bug and not
+    // transient: the credential is gone and a human has to enrol again. Google
+    // expires refresh tokens after 7 days while a consent screen is still in
+    // "Testing" mode, which is how this fleet has usually met it.
+    if (body.error === 'invalid_grant') {
+      throw new Error(
+        'the stored refresh token has expired or been revoked, so this account must be re-authorized ' +
+          '(commonly the 7-day limit on OAuth consent screens still in "Testing" mode). ' +
+          'Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.',
+      );
+    }
+    // The refresh token is deliberately absent from this message — it is a
+    // long-lived credential and an error string travels into logs and model
+    // context.
+    throw new Error(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ''})`,
+    );
+  }
+
+  if (!body.access_token) {
+    throw new Error('the access token could not be refreshed: Google returned no access_token');
+  }
+
+  // Default to an hour if Google omits expires_in; the margin above covers the
+  // difference between that guess and reality.
+  const expiresInMs = (body.expires_in ?? 3600) * 1000;
+  return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
+}

package/src/remote-runner.ts

@@ -1,5 +1,6 @@
 import { readEnvVar } from '@chrischall/mcp-utils';
 import { setDefaultGogExecutor } from './runner.js';
+import { makeAccessTokenSource } from './google-token.js';
 import { makeFlyExecutor } from './connector-runtime.js';
 
 /**
@@ -63,8 +64,14 @@ export function useRemoteGogRunner(env: NodeJS.ProcessEnv = process.env): boolea
   // Read per call rather than captured here, because the executor outlives any
   // one request and the claim being made is about a request. Absent when unset,
   // which is every registration that predates per-caller auth.
+  //
+  // The source also covers the case where the registration stores a REFRESH
+  // token instead (#241) — the identity then belongs to the registration rather
+  // than to the backend's volume, and the short-lived token it mints is the
+  // only thing that crosses the wire. `undefined` when neither is configured,
+  // which leaves the backend acting as itself exactly as before.
   setDefaultGogExecutor(
-    makeFlyExecutor(endpoint.replace(/\/+$/, ''), key, () => readEnvVar('GOG_ACCESS_TOKEN', { env })),
+    makeFlyExecutor(endpoint.replace(/\/+$/, ''), key, makeAccessTokenSource(env)),
   );
   return true;
 }

package/src/tools/auth.ts

@@ -14,7 +14,12 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
     `Google API is not enabled on the OAuth client's project makes Google reject the WHOLE request ` +
     `with invalid_scope.`;
   server.registerTool('gog_auth_list', {
-    description: 'List all Google accounts stored in gogcli. Use this to check which accounts are configured and available.',
+    description:
+      'List the Google accounts stored in gogcli, with their scopes. This reads local ' +
+      'configuration only — it does not contact Google and does NOT tell you whether an account ' +
+      'still works: a signed-out account whose refresh token expired or was revoked is listed here ' +
+      'exactly like a healthy one, scopes and all. Use gog_auth_health to check whether an account ' +
+      'can actually authenticate.',
     annotations: { readOnlyHint: true },
     inputSchema: {},
   }, async () => {

package/src/tools/utils.ts

@@ -135,7 +135,18 @@ export function errorText(err: unknown): string {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
 
-const AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
+// Google saying "not authenticated" in its own words. Definitive: a retry
+// cannot turn a 401 into a success, so this outranks the transient signal below.
+const DEFINITE_AUTH_PATTERN = /\b(401|unauthorized|invalid_grant)\b/i;
+
+// A message that TALKS about an expired token. Suggestive, not definitive — and
+// it used to be `/token.*(expired|revoked)/`, whose greedy `.*` matched a token
+// mentioned anywhere and an expiry mentioned anywhere later in the same line
+// ("page token accepted; the export link has expired"). Now the two words must
+// actually be about each other.
+const STALE_TOKEN_PATTERN = /\b(?:access[ _-]?)?token\b[^.;\n]{0,40}\b(?:has\s+)?(?:been\s+)?(?:expired|revoked)\b|\b(?:expired|revoked)\s+(?:access[ _-]?)?token\b/i;
+
+const AUTH_ERROR_PATTERN = new RegExp(`${DEFINITE_AUTH_PATTERN.source}|${STALE_TOKEN_PATTERN.source}`, 'i');
 
 // A DEAD refresh token — the whole account is signed out, not just a stale
 // access token that would refresh silently. This is the recurring account-wide
@@ -207,8 +218,19 @@ export function formatAccountList(raw: string): string {
 export async function diagnose(err: unknown): Promise<CallToolResult> {
   const errText = errorText(err);
   const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
-  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+
+  // Precedence, and the reason for it. Reporting needs-auth is EXPENSIVE to be
+  // wrong about: re-authorization is a manual, human step, and it does not fix
+  // a 429. So a transient signal beats a merely SUGGESTIVE auth signal (a
+  // message that mentions an expired token) — the reported bug was servers
+  // flapping into needs-auth and working again seconds later, which is what
+  // being told to re-auth over a rate-limit looks like.
+  //
+  // It does NOT beat a definitive one. A literal 401 or invalid_grant is Google
+  // saying the credential will not work, and calling that "retry" would loop a
+  // caller forever against a request that can never succeed.
+  const isTransientError = !DEFINITE_AUTH_PATTERN.test(errText) && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isAuthError = !isTransientError && AUTH_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
   const hint = isInvalidGrant
     ? INVALID_GRANT_HINT

package/src/worker.ts

@@ -38,7 +38,7 @@ import { gogAuth, type GogProps } from './connector-auth.js';
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.20.0'; // x-release-please-version
+const VERSION = '2.21.0'; // x-release-please-version
 
 // Build an McpAgent subclass whose init() registers `registrars` onto its server,
 // each handler wrapped in the ALS scope carrying the per-session Fly executor.

package/tests/google-token.test.ts

@@ -0,0 +1,304 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { makeAccessTokenSource, clearAccessTokenCache } from '../src/google-token.js';
+
+/**
+ * Minting a short-lived access token from a long-lived refresh token is what
+ * lets a hosted gog's identity belong to the REGISTRATION instead of to the Fly
+ * box's volume (#241). The access token is what crosses the wire; the refresh
+ * token never leaves this process.
+ *
+ * Two properties carry the whole design, and both are about NOT quietly doing
+ * the wrong thing:
+ *
+ *   1. One caller's token must never be served to another. The cache is keyed
+ *      by the credential, not held as a single "current token" — a Worker
+ *      isolate serves many callers, and a global would hand the first caller's
+ *      identity to everyone after them.
+ *   2. A failure must fail the CALL. Returning nothing would run the command as
+ *      the box's identity, and the caller would read someone else's mailbox
+ *      while everything looked like success.
+ */
+
+const CLIENT = { GOG_CLIENT_ID: 'cid.apps.googleusercontent.com', GOG_CLIENT_SECRET: 'cs' };
+
+function tokenResponse(accessToken: string, expiresIn = 3600) {
+  return new Response(JSON.stringify({ access_token: accessToken, expires_in: expiresIn }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+beforeEach(() => clearAccessTokenCache());
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe('makeAccessTokenSource', () => {
+  it('is absent when nothing is configured, so the box keeps acting as itself', () => {
+    expect(makeAccessTokenSource({})).toBeUndefined();
+  });
+
+  it('passes through a directly-supplied access token without contacting Google', async () => {
+    // The #230 path. Still supported: a caller who already holds a token should
+    // not need an OAuth client to use it.
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ GOG_ACCESS_TOKEN: 'ya29.direct' })!;
+    expect(await source()).toBe('ya29.direct');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('mints an access token from the refresh token, then serves it from cache', async () => {
+    const fetchMock = vi.fn(async () => tokenResponse('ya29.minted'));
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+
+    expect(await source()).toBe('ya29.minted');
+    expect(await source()).toBe('ya29.minted');
+    // A token exchange per tool call would be both slow and a good way to get
+    // rate-limited by Google.
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://oauth2.googleapis.com/token');
+    const sent = new URLSearchParams(init.body as string);
+    expect(sent.get('grant_type')).toBe('refresh_token');
+    expect(sent.get('refresh_token')).toBe('rt-1');
+    expect(sent.get('client_id')).toBe(CLIENT.GOG_CLIENT_ID);
+  });
+
+  it('never serves one credential holder the other one’s token', async () => {
+    // THE one that matters. A module-level "current access token" passes every
+    // other test in this file and fails this one — and on the Worker path,
+    // where a single isolate serves many callers, that is a cross-account leak
+    // rather than a bug.
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(tokenResponse('ya29.alice'))
+      .mockResolvedValueOnce(tokenResponse('ya29.bob'));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const alice = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-alice' })!;
+    const bob = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-bob' })!;
+
+    expect(await alice()).toBe('ya29.alice');
+    expect(await bob()).toBe('ya29.bob');
+    // And each keeps its own on a second read.
+    expect(await alice()).toBe('ya29.alice');
+    expect(await bob()).toBe('ya29.bob');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('re-mints once the token is close to expiring', async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(tokenResponse('ya29.first', 3600))
+      .mockResolvedValueOnce(tokenResponse('ya29.second', 3600));
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+
+    expect(await source()).toBe('ya29.first');
+    // Just inside the safety margin: a token that expires mid-flight is a
+    // failure the caller cannot do anything about, so it is replaced early.
+    vi.advanceTimersByTime((3600 - 60) * 1000);
+    expect(await source()).toBe('ya29.second');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('THROWS when the exchange fails, rather than returning nothing', async () => {
+    // Returning undefined here would run the command as the box's identity.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ error: 'server_error' }), { status: 500 })),
+    );
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+    await expect(source()).rejects.toThrow(/could not be refreshed|token exchange/i);
+  });
+
+  it('explains an invalid_grant instead of surfacing a bare OAuth error', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ error: 'invalid_grant', error_description: 'Token has been expired or revoked.' }), {
+            status: 400,
+          }),
+      ),
+    );
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-dead' })!;
+    await expect(source()).rejects.toThrow(/expired or been revoked|re-?enrol|re-?authoriz/i);
+  });
+
+  it('does not cache a failure, so a transient outage is not sticky', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response('{}', { status: 503 }))
+      .mockResolvedValueOnce(tokenResponse('ya29.recovered'));
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+
+    await expect(source()).rejects.toThrow();
+    expect(await source()).toBe('ya29.recovered');
+  });
+
+  it('fails loudly on a half-configured credential instead of acting as the box', async () => {
+    // A refresh token with no OAuth client cannot mint anything. Treating it as
+    // "unconfigured" would silently fall back to the box's identity, which is
+    // the exact confusion this feature exists to remove — so the source exists
+    // and throws when used, leaving tools/list working and the reason visible.
+    for (const partial of [
+      { GOG_REFRESH_TOKEN: 'rt-1' },
+      { GOG_REFRESH_TOKEN: 'rt-1', GOG_CLIENT_ID: 'cid' },
+      { GOG_REFRESH_TOKEN: 'rt-1', GOG_CLIENT_SECRET: 'cs' },
+    ]) {
+      const source = makeAccessTokenSource(partial);
+      expect(source).toBeTypeOf('function');
+      await expect(source!()).rejects.toThrow(/GOG_CLIENT_ID|GOG_CLIENT_SECRET/);
+    }
+  });
+
+  it('says the exchange was unreachable when the network itself fails', async () => {
+    // Distinct from a rejection BY Google: nothing was evaluated, so the
+    // credential may be perfectly good and the right response is to retry, not
+    // to tell the owner to re-enrol.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        throw new TypeError('fetch failed');
+      }),
+    );
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+    await expect(source()).rejects.toThrow(/could not be reached.*fetch failed/i);
+  });
+
+  it('survives a thrown non-Error without masking it with a TypeError', async () => {
+    // `err.message` on a thrown string is undefined, and the template would
+    // then hide the real failure behind a crash inside the error path.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => {
+        throw 'socket closed';
+      }),
+    );
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+    await expect(source()).rejects.toThrow(/could not be reached.*socket closed/i);
+  });
+
+  it('refuses a 200 that carries no access_token', async () => {
+    // A success status with nothing usable in it would otherwise cache
+    // `undefined` and send no token at all — a silent downgrade to the
+    // backend's identity, wearing a 200.
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ expires_in: 3600 }), { status: 200 })));
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+    await expect(source()).rejects.toThrow(/no access_token/i);
+  });
+
+  it('assumes an hour when Google omits expires_in', async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn(async () => new Response(JSON.stringify({ access_token: 'ya29.nolife' }), { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+
+    expect(await source()).toBe('ya29.nolife');
+    // Still cached half an hour later — i.e. it did not treat "no expiry" as
+    // "already expired" and re-mint on every single call.
+    vi.advanceTimersByTime(1800 * 1000);
+    expect(await source()).toBe('ya29.nolife');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports the status when the body is not JSON at all', async () => {
+    // An edge proxy answering a 502 with an HTML error page is the realistic
+    // case. Parsing that would throw inside the error path and bury the status,
+    // which is the only useful thing such a response carries.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response('<html>502 Bad Gateway</html>', { status: 502 })),
+    );
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+    await expect(source()).rejects.toThrow(/could not be refreshed \(HTTP 502/);
+  });
+
+  it('coalesces concurrent callers into ONE token exchange', async () => {
+    // The reported bug was several per-service servers flapping into needs-auth
+    // independently. This is the version of that failure that lives in OUR
+    // code: `get` → `await exchange` → `set` has an await between the miss and
+    // the fill, so N calls arriving together all miss and all exchange.
+    //
+    // One process per caller hides it; a Worker isolate serving many callers,
+    // or simply several tool calls in flight at once, turns one refresh into N
+    // simultaneous hits on Google's token endpoint — which is a good way to be
+    // rate-limited into exactly the intermittent auth errors being debugged.
+    let inFlight = 0;
+    let maxConcurrent = 0;
+    const fetchMock = vi.fn(async () => {
+      inFlight += 1;
+      maxConcurrent = Math.max(maxConcurrent, inFlight);
+      await new Promise((r) => setTimeout(r, 5));
+      inFlight -= 1;
+      return tokenResponse('ya29.shared');
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+    const results = await Promise.all(Array.from({ length: 8 }, () => source()));
+
+    expect(results).toEqual(Array(8).fill('ya29.shared'));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(maxConcurrent).toBe(1);
+  });
+
+  it('lets a later caller retry after a concurrent exchange failed', async () => {
+    // Coalescing must not make one failure permanent for everyone: the shared
+    // attempt is dropped when it settles, so the next call starts a fresh one.
+    // The failure has to take a tick. An exchange that rejects instantly can
+    // finish and clear itself before the second caller even looks, so that
+    // caller correctly starts its own attempt — which would make this test pass
+    // without any sharing having happened. A real exchange is a network round
+    // trip, so the shared-failure case is the one worth pinning.
+    const fetchMock = vi
+      .fn()
+      .mockImplementationOnce(async () => {
+        await new Promise((r) => setTimeout(r, 5));
+        throw new Error('boom');
+      })
+      .mockResolvedValueOnce(tokenResponse('ya29.after'));
+    vi.stubGlobal('fetch', fetchMock);
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-1' })!;
+
+    const settled = await Promise.allSettled([source(), source()]);
+    expect(settled.every((s) => s.status === 'rejected')).toBe(true);
+    // Both shared ONE failed exchange rather than each making their own...
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    // ...and the failure was not cached, so the next caller recovers.
+    expect(await source()).toBe('ya29.after');
+  });
+
+  it('does not let two different credentials share one in-flight exchange', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(tokenResponse('ya29.alice'))
+      .mockResolvedValueOnce(tokenResponse('ya29.bob'));
+    vi.stubGlobal('fetch', fetchMock);
+    const alice = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-alice' })!;
+    const bob = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-bob' })!;
+
+    const [a, b] = await Promise.all([alice(), bob()]);
+    expect(a).toBe('ya29.alice');
+    expect(b).toBe('ya29.bob');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('never puts the refresh token in the error it throws', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ error: 'invalid_grant' }), { status: 400 })),
+    );
+    const source = makeAccessTokenSource({ ...CLIENT, GOG_REFRESH_TOKEN: 'rt-super-secret-value' })!;
+    await expect(source()).rejects.toThrow(
+      expect.not.stringContaining('rt-super-secret-value') as unknown as string,
+    );
+  });
+});

package/tests/sdk-single-copy.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import { createRequire } from 'node:module';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// Guards the invariant that broke dependabot #220: the whole monorepo must
+// resolve ONE copy of @modelcontextprotocol/sdk.
+//
+// `McpServer` carries a `private _serverInfo`, so TypeScript compares it
+// NOMINALLY, not structurally. Two installed copies therefore become two
+// mutually-unassignable classes, and every `ToolRegistrar` in server.ts fails
+// with TS2322 — with no API change and no source change anywhere. #220 split
+// the tree exactly that way: `agents` (a root devDependency, the Worker
+// connector's McpAgent) exact-pins the SDK to 1.29.0 and so takes the hoisted
+// root slot that `@chrischall/mcp-utils` resolves its peer from, while the
+// workspaces asking for ^1.30.0 each nested their own copy.
+//
+// This asserts resolution identity rather than a version string: the failure is
+// "two copies", not "the wrong version", and pinning a version here would just
+// have to be edited on every future bump.
+describe('@modelcontextprotocol/sdk is installed exactly once', () => {
+  const here = createRequire(import.meta.url);
+
+  // An exported subpath — the SDK's `exports` map does not expose package.json.
+  const SDK_SUBPATH = '@modelcontextprotocol/sdk/server/mcp.js';
+
+  // `import.meta.resolve`, not `require.resolve`, to reach the dependency's own
+  // entry: these packages are ESM-only, so their `exports` maps carry no
+  // `require` condition and CJS resolution of the bare specifier throws.
+  const resolveFrom = (specifier: string): string =>
+    realpathSync(
+      createRequire(fileURLToPath(import.meta.resolve(specifier))).resolve(SDK_SUBPATH),
+    );
+
+  it('resolves to the same file for this package and for @chrischall/mcp-utils', () => {
+    // mcp-utils declares the SDK as a peer and hands our registrars the
+    // McpServer it built, so its copy is the one they must be typed against.
+    expect(resolveFrom('@chrischall/mcp-utils')).toBe(
+      realpathSync(here.resolve(SDK_SUBPATH)),
+    );
+  });
+
+  it('resolves to the same file for `agents`, which exact-pins the SDK', () => {
+    // The Worker connector builds its McpServer via McpAgent from `agents`.
+    // An exact pin there is what captured the root hoist slot in #220.
+    expect(resolveFrom('agents')).toBe(realpathSync(here.resolve(SDK_SUBPATH)));
+  });
+});

package/tests/tools/auth.test.ts

@@ -25,6 +25,27 @@ describe('gog_auth_list', () => {
     expect(result.content[0].text).toBe('Error: No accounts configured');
   });
 
+  it('does not advertise itself as proof the account still works', async () => {
+    // `gog auth list` reads the keyring. No network, no validation — it lists a
+    // full scope set for an account whose refresh token died days ago.
+    //
+    // This description used to say "check which accounts are configured and
+    // available", and "available" is exactly the wrong word: it was read as a
+    // liveness check while per-service servers were flapping into needs-auth,
+    // which pointed a whole debugging session away from an expired grant.
+    // gog_auth_health is the tool that actually probes Google.
+    const harness = await setupHandlers();
+    const { tools } = await harness.client.listTools();
+    const desc = tools.find((t) => t.name === 'gog_auth_list')!.description!;
+
+    expect(desc).not.toMatch(/\bavailable\b/i);
+    // It must say what it does NOT do, and where to go instead — a reader who
+    // wants liveness has to be sent somewhere, or they will use this anyway.
+    expect(desc).toMatch(/does not|without/i);
+    expect(desc).toContain('gog_auth_health');
+    await harness.close();
+  });
+
   it('handles non-Error rejection', async () => {
     vi.mocked(runner.run).mockRejectedValue('something went wrong');
     const harness = await setupHandlers();

package/tests/tools/utils.test.ts

@@ -190,6 +190,50 @@ describe('runOrDiagnose', () => {
     expect(result.content[0].text).toContain('gog_auth_add');
   });
 
+  it('calls a rate-limited failure transient even though it says "token expired"', async () => {
+    // The reported symptom was servers flapping into a needs-auth state and
+    // then working seconds later. Telling someone to re-authorize an account
+    // whose credential is fine is the expensive kind of wrong: re-auth is
+    // manual, and it does not fix a 429.
+    //
+    // `invalid_grant` is exempt from this and stays auth (below) — it is the
+    // one signal that definitively means the refresh token is dead.
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('429 rateLimitExceeded: the access token expired mid-request, retry'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['sheets', 'get', 'A1'], {});
+    const text = result.content[0].text as string;
+    expect(text).toContain('often transient');
+    expect(text).not.toContain('gog_auth_add');
+  });
+
+  it('still calls an explicit 401 an auth error even alongside a transient signal', async () => {
+    // The exemption above is for the LOOSE match only. A literal 401 is Google
+    // saying "not authenticated", and downgrading that to "retry" would loop a
+    // caller forever against a request that can never succeed.
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('401 unauthorized (quota project unset)'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['sheets', 'get', 'A1'], {});
+    expect(result.content[0].text).toContain('gog_auth_add');
+  });
+
+  it('does not read "token" and "expired" as auth when they are unrelated sentences', async () => {
+    // The pattern was /token.*(expired|revoked)/ with a greedy `.*`, so any
+    // message mentioning a token anywhere and an expiry anywhere later — across
+    // whole paragraphs — was reported as an auth failure.
+    vi.mocked(runner.run)
+      // Deliberately ONE line: `.` does not cross newlines, so a multi-line
+      // message would pass this test without the greedy match ever being
+      // exercised — and gog's real errors are frequently one long line.
+      .mockRejectedValueOnce(
+        new Error('page token accepted; the requested export link has expired and must be regenerated'),
+      )
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['drive', 'export', 'abc'], {});
+    expect(result.content[0].text).not.toContain('gog_auth_add');
+  });
+
   it('gives invalid_grant a richer hint than a plain 401: cause + durable fix + both re-auth paths', async () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('oauth2: "invalid_grant" "Token has been expired or revoked."'))