gogcli-mcp 2.21.0 → 2.21.1

package/dist/lib.js

@@ -23018,6 +23018,21 @@ import { delimiter, join } from "node:path";
 function isGogFileArg(arg) {
   return typeof arg !== "string";
 }
+var RUNNER_TRANSPORT_BRAND = /* @__PURE__ */ Symbol.for("gogcli.RunnerTransportError");
+var RunnerTransportError = class extends Error {
+  kind;
+  status;
+  constructor(message, kind, status) {
+    super(message);
+    this.name = "RunnerTransportError";
+    this.kind = kind;
+    this.status = status;
+    Object.defineProperty(this, RUNNER_TRANSPORT_BRAND, { value: true });
+  }
+};
+function isRunnerTransportError(err) {
+  return err instanceof Error && err[RUNNER_TRANSPORT_BRAND] === true;
+}
 var runExecutor = new AsyncLocalStorage();
 var defaultExecutor;
 function setDefaultGogExecutor(executor) {
@@ -23027,7 +23042,7 @@ function activeExecutor() {
   return runExecutor.getStore() ?? defaultExecutor;
 }
 var TIMEOUT_MS = 3e4;
-var MIN_GOG_VERSION = "0.34.1";
+var MIN_GOG_VERSION = "0.35.0";
 function readonlyEnvEnabled() {
   return readEnvVar("GOG_READONLY") !== void 0 && parseBoolEnv("GOG_READONLY", { default: true });
 }
@@ -23199,7 +23214,11 @@ async function run(args, options = {}) {
     }
     return redact(output);
   } catch (err) {
-    throw new Error(redact(err instanceof Error ? err.message : String(err)));
+    const message = redact(err instanceof Error ? err.message : String(err));
+    if (isRunnerTransportError(err)) {
+      throw new RunnerTransportError(message, err.kind, err.status);
+    }
+    throw new Error(message);
   }
 }
 async function runBinary(args, options = {}) {
@@ -23473,7 +23492,7 @@ function registerRunTool(server, options) {
 function errorText(err) {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
-var DEFINITE_AUTH_PATTERN = /\b(401|unauthorized|invalid_grant)\b/i;
+var DEFINITE_AUTH_PATTERN = /\b(?:unauthorized|invalid_grant)\b|\b(?:error|status|code|http|responded|response)["']?[\s:=(,]{0,4}401\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;
@@ -23483,6 +23502,14 @@ var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-aut
 var INVALID_GRANT_HINT = '\n\nThe stored refresh token was rejected (invalid_grant): it has expired or been revoked, so the whole account is signed out and re-authorization is required. The most common cause is the 7-day refresh-token limit Google applies to OAuth apps whose consent screen is still in "Testing" mode. Re-authorize with gog_auth_add (opens a browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless). To stop this recurring, publish the OAuth consent screen to "In production" in the Google Cloud project that owns the OAuth client. Ask the user if they would like to re-authenticate.';
 var TRANSIENT_HINT = "\n\nThis error is often transient. Retry the same call before trying a different approach (do not fall back to smaller writes or row-by-row operations).";
 var GRID_LIMIT_HINT = "\n\nThe target range is outside the sheet's current grid. Add the missing rows or columns first with gog_sheets_insert (dimension: rows or cols), then retry the write.";
+var RUNNER_TRANSPORT_AUTH_HINT = "\n\nThis is the CONNECTOR's own transport auth failing, not your Google sign-in. The gog-runner backend rejected the bearer token this server sent, so the request never reached gog and no Google credential was checked \u2014 the Google account is not the problem and re-authorizing it cannot fix this. An operator must make the Worker secret GOG_RUNNER_KEY equal RUNNER_KEY on the Fly app (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY), then retry.";
+var RUNNER_TRANSPORT_HINTS = {
+  "transport-auth": RUNNER_TRANSPORT_AUTH_HINT,
+  // The request itself was malformed, so the runner will refuse it identically
+  // every time. Nothing to advise beyond the message the runner already gave.
+  "transport-request": "",
+  "transport-retryable": TRANSIENT_HINT
+};
 function formatAccountList(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -23495,11 +23522,12 @@ function formatAccountList(raw) {
 }
 async function diagnose(err) {
   const errText = errorText(err);
+  const transportHint = isRunnerTransportError(err) ? RUNNER_TRANSPORT_HINTS[err.kind] : void 0;
   const isInvalidGrant = INVALID_GRANT_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 : "";
+  const hint = transportHint ?? (isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "");
   try {
     const accounts = formatAccountList(await run(["auth", "list"]));
     return errorResult(`${errText}
@@ -24990,7 +25018,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.21.0" : "0.0.0";
+var VERSION = true ? "2.21.1" : "0.0.0";
 var BASE_TOOL_REGISTRARS = [
   registerApiTools,
   registerAuthTools,
@@ -25005,6 +25033,24 @@ var BASE_TOOL_REGISTRARS = [
   registerTasksTools
 ];
 
+// src/auth-log.ts
+var FAILURES = /* @__PURE__ */ new Set([
+  "token.mint-failed",
+  "grant.dead",
+  "replay.failed",
+  "runner.auth-failed"
+]);
+var PREFIX = "gog-auth ";
+var TAG_CHARS = 12;
+function credentialTag(cacheKeyHash) {
+  return cacheKeyHash.slice(0, TAG_CHARS);
+}
+function logAuthTransition(event, context) {
+  const record2 = JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), event, ...context });
+  const write = FAILURES.has(event) ? console.error : console.warn;
+  write(PREFIX + redactSecrets2(record2));
+}
+
 // src/google-token.ts
 var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
 var EXPIRY_MARGIN_MS = 12e4;
@@ -25030,22 +25076,73 @@ function makeAccessTokenSource(env) {
       );
     };
   }
-  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);
+  let keyPromise;
+  const key = () => keyPromise ??= cacheKey(refreshToken, clientId);
+  const logCacheHits = parseBoolEnv("GOG_AUTH_LOG_CACHE_HITS", { env });
+  const read = async () => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) {
+      if (logCacheHits) logAuthTransition("token.cache-hit", { credential: credentialTag(k) });
+      return hit.accessToken;
+    }
+    let pending = inFlight.get(k);
     if (!pending) {
       pending = exchange(refreshToken, clientId, clientSecret).then((minted2) => {
-        cache.set(key, minted2);
+        cache.set(k, minted2);
+        logAuthTransition("token.minted", {
+          credential: credentialTag(k),
+          reason: `valid for ${Math.round((minted2.expiresAt - Date.now()) / 1e3)}s`
+        });
         return minted2;
-      }).finally(() => inFlight.delete(key));
-      inFlight.set(key, pending);
+      }).catch((err) => {
+        logAuthTransition(err.grantDead ? "grant.dead" : "token.mint-failed", {
+          credential: credentialTag(k),
+          reason: err.message
+        });
+        throw err;
+      }).finally(() => inFlight.delete(k));
+      inFlight.set(k, pending);
     }
     const minted = await pending;
     return minted.accessToken;
   };
+  const invalidate = async (rejected) => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (!hit || hit.accessToken !== rejected) {
+      logAuthTransition("token.evict-noop", {
+        credential: credentialTag(k),
+        reason: hit ? "a concurrent caller had already replaced this credential\u2019s token" : "no token was cached for this credential"
+      });
+      return false;
+    }
+    cache.delete(k);
+    logAuthTransition("token.evicted", {
+      credential: credentialTag(k),
+      reason: "Google rejected this access token; the next read will mint a new one"
+    });
+    return true;
+  };
+  return Object.assign(read, {
+    invalidate,
+    credentialId: async () => credentialTag(await key())
+  });
 }
+var TokenExchangeError = class extends Error {
+  /**
+   * The REFRESH token is dead (Google's `invalid_grant`), not merely the access
+   * token. Carried as a flag rather than re-read from the message, because
+   * inferring the author of a failure from prose several authors can produce is
+   * precisely the mistake this branch exists to undo. `instanceof` is safe: the
+   * class is thrown and caught inside this one module.
+   */
+  grantDead;
+  constructor(message, grantDead) {
+    super(message);
+    this.grantDead = grantDead;
+  }
+};
 async function exchange(refreshToken, clientId, clientSecret) {
   let res;
   try {
@@ -25060,23 +25157,29 @@ async function exchange(refreshToken, clientId, clientSecret) {
       }).toString()
     });
   } catch (err) {
-    throw new Error(
-      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`
+    throw new TokenExchangeError(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+      false
     );
   }
   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 TokenExchangeError(
+        'the stored refresh token was rejected (invalid_grant): it 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.',
+        true
       );
     }
-    throw new Error(
-      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`
+    throw new TokenExchangeError(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`,
+      false
     );
   }
   if (!body.access_token) {
-    throw new Error("the access token could not be refreshed: Google returned no access_token");
+    throw new TokenExchangeError(
+      "the access token could not be refreshed: Google returned no access_token",
+      false
+    );
   }
   const expiresInMs = (body.expires_in ?? 3600) * 1e3;
   return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
@@ -25085,54 +25188,218 @@ async function exchange(refreshToken, clientId, clientSecret) {
 // src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
+var MIN_REPLAY_BUDGET_MS = 1e3;
 var RUNNER_GOG_FAILED = 422;
 var RUNNER_DRAINING = 503;
+var RUNNER_BAD_REQUEST = 400;
+var RUNNER_BAD_KEY = 401;
+var GogFailedError = class extends Error {
+  /** gog's stderr alone, with no echoed argv mixed in. */
+  stderr;
+  constructor(message, stderr) {
+    super(message);
+    this.stderr = stderr;
+  }
+};
+var GOOGLE_TOKEN_REJECTED_PATTERN = /Google API error \(401\b|invalid[ _]authentication[ _]credentials|\bACCESS_TOKEN_EXPIRED\b|\binvalid_token\b/i;
+var REFRESH_TOKEN_DEAD_PATTERN = /\binvalid_grant\b/i;
+var READ_ONLY_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "cat",
+  "describe",
+  "get",
+  "info",
+  "list",
+  "list-slides",
+  "ls",
+  "metadata",
+  "read-slide",
+  "search",
+  "services",
+  "status",
+  "structure"
+]);
+function gogTarget(args) {
+  const words = args.filter((arg) => typeof arg === "string");
+  let service;
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    if (word.startsWith("-")) {
+      if (word === "--account") i += 1;
+      continue;
+    }
+    if (service === void 0) {
+      service = word;
+      continue;
+    }
+    return { service, subcommand: word };
+  }
+  return { service };
+}
+async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt) {
+  if (!(err instanceof GogFailedError)) return void 0;
+  const grantDead = REFRESH_TOKEN_DEAD_PATTERN.test(err.stderr);
+  if (!grantDead && !GOOGLE_TOKEN_REJECTED_PATTERN.test(err.stderr)) return void 0;
+  const { service, subcommand } = gogTarget(args);
+  const credential = await readAccessToken?.credentialId?.();
+  const where = { credential, service };
+  if (grantDead) {
+    logAuthTransition("grant.dead", {
+      ...where,
+      reason: "gog reported invalid_grant: the stored refresh token is dead, so no token can be minted and this account must be re-authorized"
+    });
+    return void 0;
+  }
+  if (!used) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "no access token was supplied with the call, so gog acted as the backend volume\u2019s own identity"
+    });
+    return void 0;
+  }
+  if (!readAccessToken?.invalidate) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "this token source cannot mint a replacement, so a replay would resend the rejected token"
+    });
+    return void 0;
+  }
+  const evicted = await readAccessToken.invalidate(used);
+  if (subcommand === void 0 || !READ_ONLY_SUBCOMMANDS.has(subcommand)) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `not replayable: '${subcommand ?? "(none)"}' is not a known read-only subcommand and a write could double-apply`
+    });
+    return void 0;
+  }
+  if (!evicted) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the rejected token was already superseded, so the cache holds the token a replay would send"
+    });
+    return void 0;
+  }
+  const fresh = await readAccessToken();
+  if (!fresh) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the token source produced no token after eviction; replaying without one would act as the backend"
+    });
+    return void 0;
+  }
+  const budgetMs = deadlineAt - Date.now();
+  if (budgetMs < MIN_REPLAY_BUDGET_MS) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `only ${budgetMs}ms of the call\u2019s deadline remained, so a replay could only time out; the rejected token was evicted, so the next call mints a fresh one`
+    });
+    return void 0;
+  }
+  return { token: fresh, budgetMs, invalidate: readAccessToken.invalidate, ...where };
+}
 function makeFlyExecutor(endpoint, key, readAccessToken) {
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
     const accessToken = await readAccessToken?.();
-    let res;
+    const deadlineAt = Date.now() + deadlineMs;
     try {
-      res = await fetch(endpoint + "/run", {
-        method: "POST",
-        headers: {
-          Authorization: "Bearer " + key,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
-        signal: AbortSignal.timeout(deadlineMs)
-      });
+      return await attempt(endpoint, key, args, accessToken, deadlineMs);
     } catch (err) {
-      const name = err instanceof Error ? err.name : "";
-      if (name === "TimeoutError" || name === "AbortError") {
-        throw new Error(
-          `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`
-        );
+      const replay = await remintAfterGoogleRejection(
+        err,
+        accessToken,
+        args,
+        readAccessToken,
+        deadlineAt
+      );
+      if (replay === void 0) throw err;
+      const where = { credential: replay.credential, service: replay.service, endpoint };
+      logAuthTransition("replay.attempted", {
+        ...where,
+        reason: "Google rejected the access token; replaying this read once with a freshly minted one"
+      });
+      try {
+        const stdout = await attempt(endpoint, key, args, replay.token, replay.budgetMs);
+        logAuthTransition("replay.succeeded", where);
+        return stdout;
+      } catch (replayErr) {
+        logAuthTransition("replay.failed", { ...where, reason: String(replayErr) });
+        if (replayErr instanceof GogFailedError && GOOGLE_TOKEN_REJECTED_PATTERN.test(replayErr.stderr)) {
+          await replay.invalidate(replay.token);
+        }
+        throw replayErr;
       }
-      throw err;
     }
-    if (!res.ok) {
-      const body = await res.json().catch(() => null);
-      const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
+  };
+}
+async function attempt(endpoint, key, args, accessToken, deadlineMs) {
+  let res;
+  try {
+    res = await fetch(endpoint + "/run", {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer " + key,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
+      signal: AbortSignal.timeout(deadlineMs)
+    });
+  } catch (err) {
+    const name = err instanceof Error ? err.name : "";
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw new RunnerTransportError(
+        `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`,
+        "transport-retryable"
+      );
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
 ${body.stderr}` : body.error : "";
-      if (res.status === RUNNER_GOG_FAILED) {
-        throw new Error(detail || "gog failed on the runner (no detail supplied)");
-      }
-      if (res.status === RUNNER_DRAINING || body?.retryable === true) {
-        throw new Error(
-          `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`
-        );
-      }
-      if (detail) {
-        throw new Error(detail);
-      }
-      throw new Error(
-        `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`
+    if (res.status === RUNNER_GOG_FAILED) {
+      throw new GogFailedError(
+        detail || "gog failed on the runner (no detail supplied)",
+        typeof body?.stderr === "string" ? body.stderr : ""
       );
     }
-    const { stdout } = await res.json();
-    return stdout;
-  };
+    if (res.status === RUNNER_BAD_KEY) {
+      logAuthTransition("runner.auth-failed", {
+        service: gogTarget(args).service,
+        endpoint,
+        reason: "the gog-runner rejected the connector\u2019s bearer token, so gog never ran and no Google credential was read; GOG_RUNNER_KEY does not match the Fly app\u2019s RUNNER_KEY"
+      });
+      throw new RunnerTransportError(
+        "gog-runner rejected the connector's bearer token, so the request never reached gog and no Google credential was involved. The Worker secret GOG_RUNNER_KEY no longer matches RUNNER_KEY on the Fly app; set them to the same value (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY) and retry.",
+        "transport-auth",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_BAD_REQUEST) {
+      throw new RunnerTransportError(
+        detail || "gog-runner rejected the request (no detail supplied)",
+        "transport-request",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_DRAINING || body?.retryable === true) {
+      throw new RunnerTransportError(
+        `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`,
+        "transport-retryable",
+        res.status
+      );
+    }
+    if (detail) {
+      throw new Error(detail);
+    }
+    throw new RunnerTransportError(
+      `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`,
+      "transport-retryable",
+      res.status
+    );
+  }
+  const { stdout } = await res.json();
+  return stdout;
 }
 
 // src/remote-runner.ts

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.21.0",
+  "version": "2.21.1",
   "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.21.0",
+  "version": "2.21.1",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

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

package/src/auth-log.ts

@@ -0,0 +1,147 @@
+import { redactSecrets } from './runner.js';
+
+/**
+ * One line per auth-state transition, on the paths where a Google credential is
+ * minted, served, evicted, replaced or refused.
+ *
+ * ## Why this exists
+ *
+ * The incident that produced this branch could not be investigated. `gog`
+ * connectors told a user all session to re-authorize a Google account whose
+ * grant was healthy, and nothing anywhere had recorded a single auth-state
+ * transition: not the runner's transport 401, not a mint, not a cache hit, not
+ * a dead grant. `wrangler.jsonc` has set `observability.enabled = true` since
+ * the Worker shipped, so a Workers Logs sink was live the whole time with
+ * nothing writing to it.
+ *
+ * The other three fixes on this branch made those outcomes DISTINGUISHABLE —
+ * a transport 401 is now a typed RunnerTransportError, a rejected access token
+ * is evicted and re-minted, `invalid_grant` is separated from a token that
+ * merely expired. This one makes them VISIBLE, which is what turns "the user
+ * says it was broken yesterday" into a query.
+ *
+ * ## Why console, and why never console.log
+ *
+ * Workers Logs captures `console.*` and nothing else — there is no other sink
+ * available to a Worker without adding a dependency and a network hop to the
+ * request path.
+ *
+ * But this module also loads in the stdio servers (`useRemoteGogRunner` wires
+ * the same executor and the same token source into a plain Node process), and
+ * there STDOUT IS THE JSON-RPC CHANNEL. Node routes `console.log`, `.info`,
+ * `.debug` and `.trace` to fd 1, so any one of them would interleave a log line
+ * with the protocol frames and break the session. Only `.warn` and `.error` go
+ * to fd 2. That is the whole reason routine transitions are emitted at `warn`
+ * rather than at `info` where their severity belongs: `warn` is the least-severe
+ * console method that Node does not send down the wire. The record carries its
+ * own `event` name, so a log consumer classifies on that rather than on level.
+ *
+ * ## Why the whole line is redacted
+ *
+ * `reason` is built from text this layer did not author — gog's stderr, Google's
+ * error body, a rejected fetch's message — and any of those can quote a token
+ * verbatim. Redacting per-field would leave the next field someone adds
+ * unprotected, so the SERIALIZED record goes through the repo's existing
+ * `redactSecrets` (the shared mcp-utils redactor plus this repo's Google
+ * `ya29.…` / `1//…` shapes) as one string. A credential can therefore only
+ * appear in a log line if it survives the same redactor that guards every error
+ * this repo returns to a client.
+ *
+ * Credentials are never IDENTIFIED by value either: `credentialTag` derives the
+ * identifier from the SHA-256 that already keys the token cache, which is the
+ * hash-keying precedent google-token.ts set for exactly this reason.
+ */
+
+/**
+ * What changed. Named after the transition rather than after the code site, so
+ * a query reads as a story about a credential rather than about a call stack.
+ */
+export type AuthTransition =
+  /** A fresh access token was obtained from the refresh token. */
+  | 'token.minted'
+  /** An unexpired cached access token was served without contacting Google. */
+  | 'token.cache-hit'
+  /** The exchange failed for a reason that is not a dead grant. */
+  | 'token.mint-failed'
+  /** A rejected access token was dropped, so the next read mints a new one. */
+  | 'token.evicted'
+  /** Nothing was dropped: the credential holds no token, or a different one. */
+  | 'token.evict-noop'
+  /** The REFRESH token is gone. Nothing can be minted; a human must re-enrol. */
+  | 'grant.dead'
+  /** Google refused our token, but this call is not one we may replay. */
+  | 'replay.declined'
+  /** Replaying the call once with a freshly minted token. */
+  | 'replay.attempted'
+  /** The replay succeeded — the caller saw no error at all. */
+  | 'replay.succeeded'
+  /** The replay failed too; the original failure reaches the caller. */
+  | 'replay.failed'
+  /** The RUNNER rejected our bearer. gog never ran; no Google credential read. */
+  | 'runner.auth-failed';
+
+/**
+ * Which credential, which service, which backend, and why — every field
+ * optional because each call site honestly knows a different subset. A
+ * transport 401 has no credential to name; a mint has no service.
+ */
+export interface AuthContext {
+  /** `credentialTag` of the hash that keys the token cache. Never a token. */
+  credential?: string;
+  /** The `gog` service word (gmail, drive, sheets…), when there is one. */
+  service?: string;
+  /** The gog-runner base URL. Configuration, not a secret. */
+  endpoint?: string;
+  /** Prose. Redacted with everything else — see the module note. */
+  reason?: string;
+}
+
+/**
+ * Transitions that describe something going WRONG, routed to `console.error`.
+ * Everything else is routine and goes to `console.warn` (see the module note on
+ * why not `console.info`).
+ *
+ * `token.evicted` is deliberately NOT here: an eviction is the repair working.
+ * `replay.declined` is not either — declining is usually the correct, safe
+ * answer (a write, a superseded token), and only reads as a failure alongside
+ * the record that follows it.
+ */
+const FAILURES: ReadonlySet<AuthTransition> = new Set<AuthTransition>([
+  'token.mint-failed',
+  'grant.dead',
+  'replay.failed',
+  'runner.auth-failed',
+]);
+
+/** Marker so one `grep gog-auth` finds every record and nothing else. */
+const PREFIX = 'gog-auth ';
+
+/**
+ * How many hex characters of the cache key identify a credential in a log.
+ *
+ * 12 hex characters is 48 bits — far past collision risk for the handful of
+ * credentials one deployment holds, and short enough to read across lines. The
+ * input is already a SHA-256 of (clientId, refreshToken), so truncating it can
+ * only ever remove information.
+ */
+const TAG_CHARS = 12;
+
+/** The log-safe name for a credential, from the hash that already keys it. */
+export function credentialTag(cacheKeyHash: string): string {
+  return cacheKeyHash.slice(0, TAG_CHARS);
+}
+
+/**
+ * Emit one record. Deliberately synchronous, allocation-light and
+ * exception-free by construction: this sits on the request path, and an
+ * observability call that can fail or block would be worse than the silence it
+ * replaces.
+ */
+export function logAuthTransition(event: AuthTransition, context: AuthContext): void {
+  // `at` and `event` first so the line reads left to right; JSON.stringify
+  // drops the context keys whose value is undefined, which is why an absent
+  // credential produces no `"credential":null` noise.
+  const record = JSON.stringify({ at: new Date().toISOString(), event, ...context });
+  const write = FAILURES.has(event) ? console.error : console.warn;
+  write(PREFIX + redactSecrets(record));
+}