gogcli-mcp 2.21.0 → 2.22.0

package/src/google-probe.ts

@@ -0,0 +1,113 @@
+/**
+ * How this side reads the runner's `GET /health/google` answer.
+ *
+ * ## Why this is a module and not two `if` statements
+ *
+ * There are two callers — the connect-time probe in `connector-auth.ts` and the
+ * post-refusal probe in `connector-runtime.ts` — and they used to make this
+ * judgement separately. That is exactly how the defect below survived review of
+ * both: each site branched on `body.ok === true` alone, so both inherited the
+ * same wrong reading, and fixing one would have left the other. The judgement
+ * now exists once; the call sites only translate a verdict into their own event
+ * names.
+ *
+ * ## The defect this deletes
+ *
+ * `ok` answers "is the Google layer healthy". It does NOT answer "did anything
+ * find out" — and `server.mjs` reports `ok:false` for causes that are facts
+ * about the PROBE rather than about Google: it timed out, it could not be run at
+ * all (no `gog` on PATH, no `credentials.json` on the volume), its output could
+ * not be parsed, or gog declined to state validity. Reading `ok !== true` as
+ * "Google refused" filed every one of those at error level under an event whose
+ * documented meaning is "Google was asked and **refused**". An operator grepping
+ * event names would conclude the refresh token was dead and close the incident
+ * on evidence that was never gathered — the original defect (status claiming
+ * health nothing measured) with the alarm merely inverted.
+ *
+ * So the runner now states `measured` explicitly, and this module reads it
+ * FIRST. `ok` is only consulted once a measurement is established.
+ *
+ * ## Which way "unknown" resolves
+ *
+ * Toward `unmeasured`, always. The two errors are not symmetrical: filing a real
+ * refusal as unmeasured under-claims, and the runner's own cause string still
+ * rides along on the same log line, so nothing is lost. Filing a non-measurement
+ * as a refusal invents evidence. A runner that does not say whether it measured
+ * therefore gets no verdict about Google extracted from it — including the
+ * incoherent `ok:true, measured:false` and the merely silent `ok:true`, neither
+ * of which can license a health claim.
+ *
+ * `ok:true` is worth spelling out, because it is where this rule is easiest to
+ * talk yourself out of: an affirmative-sounding field feels self-licensing, and
+ * the harm of believing it looks small. It is not. The GOOD verdict is what the
+ * refusal path compares Google's live 401 against, so a `kind:'ok'` built on
+ * silence becomes `refusal.google-ok` — the record documented as "the one
+ * record that means we cannot explain this", logged at error level, and the
+ * only evidence that could ever justify building automatic recovery on the
+ * hosted path. Raised from a measurement nobody took, it is precisely the
+ * defect this branch exists to delete: a health claim with nothing behind it.
+ */
+
+/** The verdict, in the three states the log's event names already distinguish. */
+export type GoogleProbeVerdict =
+  /** Measured, and the credential works. */
+  | { kind: 'ok'; reason?: undefined }
+  /** Measured, and it does not. `reason` is the runner's classification. */
+  | { kind: 'unhealthy'; reason: string }
+  /** Nothing was learned about Google. Not evidence of anything. */
+  | { kind: 'unmeasured'; reason: string };
+
+/** Read a field only if it really is a boolean — a proxy may put anything here. */
+const bool = (value: unknown): boolean | undefined =>
+  typeof value === 'boolean' ? value : undefined;
+
+/**
+ * The runner's cause, if it sent a usable one.
+ *
+ * Non-strings are dropped rather than stringified: this value reaches a log
+ * aggregator, and `[object Object]` is worse than the honest fallback sentence.
+ * Every legitimate value is a literal from `PROBE_CAUSES` in `server.mjs`.
+ */
+const cause = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.length > 0 ? value : undefined;
+
+/**
+ * Turn a `/health/google` body into a verdict. Total: every input, including a
+ * proxy's HTML page parsed into a string and a body of `null`, yields one of the
+ * three kinds and never throws.
+ */
+export function readGoogleProbe(body: unknown): GoogleProbeVerdict {
+  const record = (typeof body === 'object' && body !== null ? body : {}) as Record<string, unknown>;
+  const measured = bool(record.measured);
+  const reported = cause(record.error);
+
+  // FIRST, and before `ok` is consulted at all: a runner that says it could not
+  // measure has told us nothing about the credential, however alarming its cause
+  // string reads.
+  if (measured === false) {
+    return {
+      kind: 'unmeasured',
+      reason: reported ?? 'the runner reported it could not measure the Google layer',
+    };
+  }
+  // `ok` is read ONLY here, inside the established measurement. Health is a
+  // claim, not a fact that states itself: `ok:true` on its own is a runner
+  // asserting a verdict about a credential without saying anything asked.
+  if (measured === true) {
+    if (bool(record.ok) === true) return { kind: 'ok' };
+    return {
+      kind: 'unhealthy',
+      reason: reported ?? 'the runner reported the Google layer unhealthy with no cause',
+    };
+  }
+  // No `measured` field at all — whatever `ok` says. Silence is not a
+  // measurement, so no claim about the credential may be built on it, in either
+  // direction; but whatever the runner did say is carried through, because the
+  // operator reading this line needs it.
+  return {
+    kind: 'unmeasured',
+    reason: reported
+      ? `the runner did not report whether it measured the Google layer; it said: ${reported}`
+      : 'the runner did not report whether it measured the Google layer',
+  };
+}

package/src/google-token.ts

@@ -1,4 +1,5 @@
-import { readEnvVar } from '@chrischall/mcp-utils';
+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
@@ -85,8 +86,54 @@ async function cacheKey(refreshToken: string, clientId: string): Promise<string>
  * 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 type AccessTokenSource = () => Promise<string | undefined>;
+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;
@@ -106,6 +153,10 @@ export interface TokenEnv {
  * 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;
 
@@ -132,29 +183,109 @@ export function makeAccessTokenSource(env: TokenEnv): AccessTokenSource | undefi
     };
   }
 
-  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;
+  // 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(key);
+    let pending = inFlight.get(k);
     if (!pending) {
       pending = exchange(refreshToken, clientId, clientSecret)
         .then((minted) => {
-          cache.set(key, 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(key));
-      inFlight.set(key, pending);
+        .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()),
+  });
 }
 
 /**
@@ -168,6 +299,22 @@ export function makeAccessTokenSource(env: TokenEnv): AccessTokenSource | undefi
  * 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 {
@@ -182,8 +329,9 @@ async function exchange(refreshToken: string, clientId: string, clientSecret: st
       }).toString(),
     });
   } catch (err) {
-    throw new Error(
+    throw new TokenExchangeError(
       `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+      false,
     );
   }
 
@@ -199,23 +347,41 @@ async function exchange(refreshToken: string, clientId: string, clientSecret: st
     // 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 Error(
-        'the stored refresh token has expired or been revoked, so this account must be re-authorized ' +
+      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 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,
+    );
   }
 
   // Default to an hour if Google omits expires_in; the margin above covers the

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/timestamps.ts

@@ -149,6 +149,13 @@ const TIMESTAMP_KEYS = new Set([
   'date',              // gog gmail message/thread listings ("2026-07-28 03:36")
   'dateTime',          // Calendar event start/end
   'internalDate',      // Gmail, epoch milliseconds (authoritative)
+  // gog >= 0.35.0 Gmail message AND thread listings. Already offset-bearing
+  // (RFC3339 from internalDate), so it needs no offset repair — it is
+  // allowlisted purely to gain a Display sibling, and to be re-rendered in
+  // DISPLAY_TZ like every other instant. Separately sourced from the sibling
+  // `date`, which is a naive re-format of the sender's Date header; the two may
+  // legitimately disagree. See docs/timestamps.md.
+  'internalDateIso',
   'modifiedTime',      // Drive
   'createdTime',       // Drive
   'createTime',

package/src/tools/auth.ts

@@ -31,7 +31,10 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
   });
 
   server.registerTool('gog_auth_status', {
-    description: 'Show gogcli auth configuration: keyring backend, credential files, and auth setup.',
+    description:
+      'Show gogcli auth CONFIGURATION: keyring backend, credential files, and auth setup. Despite the ' +
+      'name this is not a health check — it reads local setup and does not contact Google, so it says ' +
+      'nothing about whether an account can still authenticate. Use gog_auth_health for that.',
     annotations: { readOnlyHint: true },
     inputSchema: {},
   }, async () => {
@@ -50,7 +53,10 @@ function registerAuthToolsWith(server: McpServer, defaultServices: string): void
       'service. Reports per account: whether the token is currently valid, the mapped cause when it is ' +
       'not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit ' +
       'that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to ' +
-      're-authorize on your own schedule instead of mid-task.',
+      're-authorize on your own schedule instead of mid-task. On the hosted connector this is the ONLY ' +
+      'check that measures Google: a connector showing "connected" or "refreshed" has verified the ' +
+      'connector key that reaches the gog machine, and nothing else — the Google credential lives on ' +
+      'that machine and can be dead while the connection looks perfectly healthy.',
     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.
@@ -137,7 +137,28 @@ export function errorText(err: unknown): string {
 
 // 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;
+// `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
@@ -188,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
@@ -217,6 +263,22 @@ 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);
 
   // Precedence, and the reason for it. Reporting needs-auth is EXPENSIVE to be
@@ -232,7 +294,10 @@ export async function diagnose(err: unknown): Promise<CallToolResult> {
   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
@@ -240,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}`);