gogcli-mcp 2.20.0 → 2.21.1

package/src/google-token.ts

@@ -0,0 +1,391 @@
+import { parseBoolEnv, readEnvVar } from '@chrischall/mcp-utils';
+import { credentialTag, logAuthTransition } from './auth-log.js';
+
+/**
+ * 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.
+ *
+ * It also answers a second question, which is what makes a rejected token
+ * recoverable: `invalidate(rejected)` drops that token if it is still the one
+ * cached for this credential, and REPORTS whether it dropped anything.
+ *
+ * `true` means the next read mints something new, so a replay is worth making;
+ * `false` means a concurrent caller has already replaced the entry. Those are
+ * the only two answers, and a source with nothing to mint from gives neither —
+ * it omits the method entirely (see below).
+ */
+export interface AccessTokenSource {
+  (): Promise<string | undefined>;
+  /**
+   * Evict `rejected` if it is still this credential's cached token; answer
+   * whether anything was evicted.
+   *
+   * ABSENT exactly when this source holds nothing mintable — a directly-supplied
+   * GOG_ACCESS_TOKEN, or a refresh token with no OAuth client beside it. The
+   * absence has to be the signal, because an always-false return is not
+   * distinguishable from the false a real cache gives when a concurrent caller
+   * beat you to the refresh, and the connector records those as different
+   * causes: "nothing here can mint a replacement" is the one configuration
+   * where re-authorizing genuinely IS the repair, and it must not be logged as
+   * somebody else's concurrent write.
+   *
+   * Scoped to ONE credential on purpose. `clearAccessTokenCache()` drops every
+   * entry and exists only as a test seam — using it here would mean one
+   * caller's dead token forced a re-mint on every other caller sharing the
+   * isolate, which is the same shared-identity mistake this module is built
+   * around, wearing a different hat.
+   *
+   * Matched by VALUE, not just by key. A concurrent caller may already have
+   * replaced the entry while this call was in flight; evicting that fresh token
+   * would waste a mint and let two callers keep undoing each other's work.
+   */
+  invalidate?: (rejected: string) => Promise<boolean>;
+  /**
+   * The log-safe name of the credential behind this source, for correlating
+   * this module's records with the connector's (auth-log.ts).
+   *
+   * Optional, and absent exactly when there is no mintable credential to name.
+   * A directly-supplied GOG_ACCESS_TOKEN emits no records here at all — nothing
+   * is minted, cached or evicted — so a tag for it would identify a story that
+   * is never told. Answering `undefined` says that honestly rather than
+   * inventing an identifier for a credential this module does not hold.
+   */
+  credentialId?: () => Promise<string>;
+}
+
+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 {
+  // A token handed to us whole. Nothing minted it here, so nothing here can
+  // mint another — hence no `invalidate` at all, which is how the caller tells
+  // this apart from a cache that merely lost a race. When THIS is the token
+  // Google rejects, re-authorization really is the repair.
+  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.',
+      );
+    };
+  }
+
+  // Hashed ONCE per source rather than once per call. `read` and `invalidate`
+  // each used to recompute the SHA-256 on every invocation, which is work this
+  // module was already paying for on the request path; memoizing it also gives
+  // the log records a credential tag for free. Lazy rather than eager so a
+  // source that is never used never starts a promise nobody awaits.
+  let keyPromise: Promise<string> | undefined;
+  const key = (): Promise<string> => (keyPromise ??= cacheKey(refreshToken, clientId));
+
+  // Every other transition in the set is an EVENT; a cache hit is the absence
+  // of one. Narrating it writes a line per gog invocation — a Workers Logs line
+  // (and its cost) for every tool call in healthy operation on the Worker, and
+  // a stderr line per call in the MCP host's server log on stdio — which turns
+  // the `gog-auth` stream from a log of transitions into a request log.
+  //
+  // It stays available for the investigation that has to prove WHICH token a
+  // call was served (the shape the original incident took), behind a flag
+  // nobody sets in normal operation. Read once per source rather than per call:
+  // the env cannot change under a running process.
+  const logCacheHits = parseBoolEnv('GOG_AUTH_LOG_CACHE_HITS', { env });
+
+  const read = async (): Promise<string | undefined> => {
+    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;
+    }
+
+    // Join the exchange already running for this credential, or start the one
+    // everyone else will join.
+    let pending = inFlight.get(k);
+    if (!pending) {
+      pending = exchange(refreshToken, clientId, clientSecret)
+        .then((minted) => {
+          cache.set(k, minted);
+          logAuthTransition('token.minted', {
+            credential: credentialTag(k),
+            reason: `valid for ${Math.round((minted.expiresAt - Date.now()) / 1000)}s`,
+          });
+          return minted;
+        })
+        // Only the caller that STARTED the exchange records it, because only one
+        // exchange happened; the callers that joined it would otherwise turn one
+        // mint into a burst of identical lines.
+        //
+        // Typed as TokenExchangeError rather than `unknown`: `exchange` catches
+        // the fetch rejection and the JSON parse itself, so this is the only
+        // thing that can arrive here, and pretending otherwise would add an arm
+        // no test could ever reach.
+        .catch((err: TokenExchangeError): never => {
+          logAuthTransition(err.grantDead ? 'grant.dead' : 'token.mint-failed', {
+            credential: credentialTag(k),
+            reason: err.message,
+          });
+          throw err;
+        })
+        // 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(k));
+      inFlight.set(k, pending);
+    }
+    const minted = await pending;
+    return minted.accessToken;
+  };
+
+  /**
+   * Google rejected `rejected`; make sure the next read does not serve it again.
+   *
+   * The read guard above is purely about TIME, so without this a token Google
+   * has already answered 401 to is re-served until its nominal expiry — up to
+   * ~58 minutes of every call failing identically, which is exactly the incident
+   * this closes. `inFlight` is deliberately untouched: an exchange that is
+   * already running was started to produce a NEW token, and cancelling it would
+   * only make the callers waiting on it mint again.
+   */
+  const invalidate = async (rejected: string): Promise<boolean> => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (!hit || hit.accessToken !== rejected) {
+      // The two "nothing happened" cases are worth telling apart in a log: one
+      // says a concurrent caller has already repaired this credential, the
+      // other says the rejected token was never ours to begin with.
+      logAuthTransition('token.evict-noop', {
+        credential: credentialTag(k),
+        reason: hit
+          ? 'a concurrent caller had already replaced this credential’s 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()),
+  });
+}
+
+/**
+ * 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.
+ */
+class TokenExchangeError 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.
+   */
+  readonly grantDead: boolean;
+
+  constructor(message: string, grantDead: boolean) {
+    super(message);
+    this.grantDead = grantDead;
+  }
+}
+
+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 TokenExchangeError(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+      false,
+    );
+  }
+
+  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.
+    //
+    // The literal `invalid_grant` is in the message ON PURPOSE, and is load
+    // bearing rather than decoration. This mint is a first-class error surface
+    // — it propagates in place of gog's 401 (connector-runtime.ts) — and
+    // tools/utils.ts picks INVALID_GRANT_HINT, the one that names the 7-day
+    // Testing-mode cause and the gog_auth_add_url/gog_auth_add_complete pair,
+    // by matching that exact token. Prose alone does not qualify: the previous
+    // wording ("token has expired or been revoked") missed
+    // INVALID_GRANT_PATTERN's second alternative ("token has been expired or
+    // revoked") by one word, so a dead refresh token surfaced here earned only
+    // the generic "authentication may have expired" advice while the identical
+    // failure reported BY gog earned the specific guidance.
+    if (body.error === 'invalid_grant') {
+      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,
+      );
+    }
+    // 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 TokenExchangeError(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ''})`,
+      false,
+    );
+  }
+
+  if (!body.access_token) {
+    throw new TokenExchangeError(
+      'the access token could not be refreshed: Google returned no access_token',
+      false,
+    );
+  }
+
+  // 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/runner.ts

@@ -45,6 +45,62 @@ export type GogExecutor = (
   opts: { timeout?: number; interactive?: boolean },
 ) => Promise<string>;
 
+// Which layer authored a failure, when the layer was OURS and not gog's.
+//
+// A remote executor (the Fly/Worker path) can fail in two categorically
+// different ways, and every consumer downstream needs to tell them apart:
+//
+//   - `gog` ran on the backend and failed. The message is gog's — or Google's,
+//     relayed by gog — so it is PROSE, and the only way to classify it is to
+//     read it. That failure is NOT a RunnerTransportError; it stays a plain
+//     Error so tools/utils.ts keeps applying its patterns to it.
+//   - The request never got that far: the runner rejected our bearer token,
+//     refused the request shape, was draining, or never answered. Nothing was
+//     ever shown to Google, so no amount of re-authorizing a Google account can
+//     help — and the runner's own words ("unauthorized") are indistinguishable
+//     from Google's when read as prose. That is what this type exists for.
+//
+// The kinds, and what each one asks of the caller:
+//   transport-auth      the runner rejected OUR bearer (GOG_RUNNER_KEY on the
+//                       Worker vs RUNNER_KEY on the Fly app). An operator has
+//                       to fix a key; the end user's Google grant is fine.
+//   transport-request   the runner refused the request shape (oversized arg,
+//                       malformed JSON). Deterministic; retrying is pointless.
+//   transport-retryable the runner is draining, could not reach its disk, or
+//                       never answered. The same call can succeed shortly.
+export type RunnerFailureKind = 'transport-auth' | 'transport-request' | 'transport-retryable';
+
+// `Symbol.for`, not a private symbol or a bare `instanceof`: the class can be
+// evaluated more than once in one process (the stdio bundle and the Worker
+// bundle are separate builds of the same source, and vitest can load a module
+// twice across pools), and a second copy of the class would make `instanceof`
+// answer false for an error that IS one. The registry symbol is the same value
+// in every copy, so the brand survives.
+const RUNNER_TRANSPORT_BRAND = Symbol.for('gogcli.RunnerTransportError');
+
+/**
+ * A failure authored by the gog-runner itself (or by the hop to it) rather than
+ * by `gog`/Google. Carries the runner's HTTP status when there was one.
+ */
+export class RunnerTransportError extends Error {
+  readonly kind: RunnerFailureKind;
+  readonly status: number | undefined;
+
+  constructor(message: string, kind: RunnerFailureKind, status?: number) {
+    super(message);
+    this.name = 'RunnerTransportError';
+    this.kind = kind;
+    this.status = status;
+    // Non-enumerable so the brand never shows up in a serialized error body.
+    Object.defineProperty(this, RUNNER_TRANSPORT_BRAND, { value: true });
+  }
+}
+
+/** Structural check for the above — see RUNNER_TRANSPORT_BRAND on why not `instanceof`. */
+export function isRunnerTransportError(err: unknown): err is RunnerTransportError {
+  return err instanceof Error && (err as unknown as Record<symbol, unknown>)[RUNNER_TRANSPORT_BRAND] === true;
+}
+
 // Ambient override for the executor `run()` uses when no options.spawner is
 // given. The Worker/Fly path wraps request handling in
 // `runExecutor.run({ executor }, ...)`; unset, `run()` falls back to spawning.
@@ -111,7 +167,7 @@ const TIMEOUT_MS = 30_000;
 // so the requirement change is surfaced in the release notes (see
 // .github/release.yml). This is the single source of truth for the required
 // version; keep the README/CLAUDE.md mention in sync.
-export const MIN_GOG_VERSION = '0.34.1';
+export const MIN_GOG_VERSION = '0.35.0';
 
 // Interpret the GOG_READONLY kill-switch. `readEnvVar` already treats blank
 // values, 'undefined'/'null' sentinels, and unresolved .mcpb placeholders
@@ -377,7 +433,16 @@ export async function run(args: GogArg[], options: RunOptions = {}): Promise<str
     // A thrown non-Error would make `.message` undefined and redact() blow up
     // with a TypeError, masking the real failure. Same instanceof guard the
     // codebase already uses in errorText() (tools/utils.ts).
-    throw new Error(redact(err instanceof Error ? err.message : String(err)));
+    const message = redact(err instanceof Error ? err.message : String(err));
+    // Redaction must not cost the error its TYPE. `RunnerTransportError` is the
+    // structural claim "this failure was ours, not Google's"; flattening it to a
+    // bare Error here would put diagnose() straight back to guessing from prose,
+    // which is the bug this type exists to close. Rebuilt rather than mutated so
+    // the un-redacted message never survives anywhere.
+    if (isRunnerTransportError(err)) {
+      throw new RunnerTransportError(message, err.kind, err.status);
+    }
+    throw new Error(message);
   }
 }
 

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

@@ -2,8 +2,8 @@ import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { errorResult, rawTextResult } from '@chrischall/mcp-utils';
-import { run } from '../runner.js';
-import type { GogArg } from '../runner.js';
+import { run, isRunnerTransportError } from '../runner.js';
+import type { GogArg, RunnerFailureKind } from '../runner.js';
 import { normalizeTimestamps } from '../timestamps.js';
 
 // Byte size at or below which a payload stays on the plain inline flag.
@@ -135,7 +135,39 @@ 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.
+// `unauthorized` and `invalid_grant` are unambiguous words, but 401 is also
+// just an integer, and gog's output is full of integers that are row indices,
+// ranges and counts. A bare `\b401\b` classified "row 401 is outside the sheet
+// grid" — a pure Sheets range error — as a definite auth failure and sent the
+// caller off to re-authorize a healthy account. So a 401 has to look like a
+// STATUS: introduced by a status-ish word.
+//
+// THE SEPARATOR IS THE WHOLE DIFFICULTY (#246). The first attempt used
+// `\s*[:=]?\s*`, which cannot cross an opening paren or a JSON quote — so it
+// silently stopped matching the CANONICAL shape gog emits for a Google auth
+// failure, `Google API error (401 authError)`, and JSON bodies like
+// `{"code": 401}`. That regression is strictly worse than the false positive it
+// was fixing: a false positive costs a pointless re-auth, but a real dead
+// credential with no hint at all leaves the caller with nothing to act on.
+//
+// So the separator admits the punctuation those shapes actually use — quote,
+// paren, colon, equals, comma, space — and is CAPPED at 4 characters so a status
+// word cannot reach across prose to an unrelated integer ("error: could not
+// write row 401" must stay silent). `A401:B401` never matched anyway: there is
+// no word boundary after `A`.
+const DEFINITE_AUTH_PATTERN =
+  /\b(?:unauthorized|invalid_grant)\b|\b(?:error|status|code|http|responded|response)["']?[\s:=(,]{0,4}401\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
@@ -177,6 +209,31 @@ const 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.';
 
+// The hint for each RUNNER-authored failure kind (see RunnerTransportError in
+// runner.ts). These are chosen by the error's TYPE, never by reading its text.
+//
+// transport-auth is the one that motivated all of this. The runner answers a
+// bad bearer with the single word "unauthorized"; read as prose that is
+// indistinguishable from Google rejecting a credential, and the caller was
+// being told all session to re-authorize an account that had never been asked
+// for anything. So this hint names the real cause and says outright that
+// re-authorizing cannot help. It deliberately does NOT contain the literal
+// `gog_auth_add`, which is the token the rest of the auth guidance keys on.
+const 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 — 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.';
+
+const RUNNER_TRANSPORT_HINTS: Record<RunnerFailureKind, string> = {
+  '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,
+};
+
 // Reduce `gog auth list --json` output to just the configured email addresses.
 // The raw JSON also carries OAuth scopes, the Google subject id, and creation
 // timestamps — none of which belong in an error surfaced to the model, and
@@ -206,11 +263,41 @@ export function formatAccountList(raw: string): string {
 // keeps the same diagnostic quality as everywhere else.
 export async function diagnose(err: unknown): Promise<CallToolResult> {
   const errText = errorText(err);
+
+  // STRUCTURE BEFORE PROSE. A RunnerTransportError is this connector's own
+  // transport failing — its bearer, its request validation, its drain. Nothing
+  // was shown to Google, so none of the patterns below may be consulted for it:
+  // they exist to read gog's/Google's words, and the runner's words are not
+  // those. Read as prose, the runner's `unauthorized` matched
+  // DEFINITE_AUTH_PATTERN and produced AUTH_HINT — a human being told to
+  // re-authorize a healthy account over what was really a key mismatch.
+  //
+  // This short-circuits the ladder rather than joining it, so it is not a new
+  // rung in the precedence order documented below; that order still governs
+  // every error that genuinely came from gog.
+  const transportHint = isRunnerTransportError(err)
+    ? RUNNER_TRANSPORT_HINTS[err.kind]
+    : undefined;
+
   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
+  // `??`, not `||`: 'transport-request' maps to the empty string on purpose —
+  // "this failure is ours and there is nothing to advise" — and `||` would fall
+  // through to the prose ladder for exactly the errors that must never reach it.
+  const hint = transportHint ?? (isInvalidGrant
     ? INVALID_GRANT_HINT
     : isAuthError
       ? AUTH_HINT
@@ -218,7 +305,7 @@ export async function diagnose(err: unknown): Promise<CallToolResult> {
         ? TRANSIENT_HINT
         : isGridLimitError
           ? GRID_LIMIT_HINT
-          : '';
+          : '');
   try {
     const accounts = formatAccountList(await run(['auth', 'list']));
     return errorResult(`${errText}\n\nConfigured accounts:\n${accounts || '(none)'}${hint}`);