gogcli-mcp 2.21.1 → 2.22.0

package/src/connector-auth.ts

@@ -1,4 +1,7 @@
 import type { ConnectorAuth } from '@chrischall/mcp-connector';
+import { logAuthTransition, type AuthTransition } from './auth-log.js';
+import { readGoogleProbe } from './google-probe.js';
+import { redactSecrets } from './runner.js';
 
 /**
  * OAuth props stored per user by the Cloudflare connector's OAuth provider.
@@ -22,13 +25,265 @@ export interface GogProps {
   [k: string]: unknown;
 }
 
+/**
+ * How long the connect-time Google probe may take before it is abandoned.
+ *
+ * This sits inside the user's `/authorize` POST, so it is latency the human is
+ * watching and claude.ai is timing. The probe is diagnostic, never a gate, so
+ * the correct trade is unambiguous: give up early and record "not measured"
+ * rather than hold up a login that was already decided. The runner's own budget
+ * for the same probe (`GOOGLE_PROBE_TIMEOUT_MS` in server.mjs) is longer, so an
+ * abort here is this side declining to wait, not the runner failing.
+ */
+export const GOOGLE_PROBE_TIMEOUT_MS = 4_000;
+
+/**
+ * How long ONE key check may take before it is abandoned and (once) retried.
+ *
+ * `/health` runs no gog, so a healthy runner answers in milliseconds; anything
+ * near this bound means the Machine is booting or the proxy is holding the
+ * connection, which is precisely the case the retry exists for.
+ */
+export const LOGIN_ATTEMPT_TIMEOUT_MS = 5_000;
+
+/**
+ * The pause between the two key-check attempts.
+ *
+ * Sized against what it is waiting out — a Fly proxy handing a request to a
+ * Machine that is still coming up, or a runner a few hundred milliseconds from
+ * the end of its drain — and against what it is spending: latency inside the
+ * user's `/authorize` POST. One short pause is worth an enrolment; a backoff
+ * ladder would not be.
+ */
+export const LOGIN_RETRY_DELAY_MS = 250;
+
+/** How the failing status is named to the user. */
+function describeStatus(status: unknown): string {
+  return typeof status === 'number' ? `HTTP ${status}` : 'no HTTP status';
+}
+
+const describeCause = (err: unknown) => (err instanceof Error ? err.message : String(err));
+
+/**
+ * Everything after the specific cause. It leads with the sentence that matters:
+ * the user's key was never judged, so the correct action is to wait, not to go
+ * looking for a different key.
+ */
+const UNREACHABLE_ADVICE =
+  'Your connector key was NOT rejected — the backend never answered, so the key ' +
+  'was never checked. The runner answers 503 for the whole of its drain window ' +
+  '(i.e. during every deploy) and Fly answers 502 while a stopped Machine boots, ' +
+  'so this is usually momentary. Wait a few seconds and try again.';
+
+/**
+ * Verify the connector key against the runner's `/health`, distinguishing the
+ * two ways that can fail. Returns on success; throws otherwise.
+ *
+ * ## The bug this replaces (DEFECT 4)
+ *
+ * The previous body was `if (!res.ok) throw new Error('Invalid connector key
+ * (backend rejected it)')`. Every non-2xx produced that sentence, and a rejected
+ * `fetch` produced no sentence at all — it escaped `login()` uncaught.
+ *
+ * But `/health` returns non-2xx for reasons that have nothing to do with the
+ * key. `server.mjs` answers **503 `{retryable:true}` to every request once a
+ * shutdown signal lands**, which is the whole of every deploy, and Fly's proxy
+ * answers 502 while a stopped Machine boots. A user enrolling in either window
+ * was told, flatly, that their key was wrong. The reasonable response to that is
+ * to stop and go find a better key — which leaves a connector stuck at
+ * `authenticate` / `complete_authentication`, exactly the state `gog_docs`,
+ * `gog_sheets` and `gog_drive` were observed in.
+ *
+ * ## The two rules
+ *
+ * **Only 401 and 403 mean "wrong key."** Those are the runner actually judging
+ * the bearer (`bearerMatches` → `{ error: 'unauthorized' }`). Everything else —
+ * every other status, an unparseable answer, a dead socket, our own timeout — is
+ * the backend failing to answer, and is reported as such.
+ *
+ * **Unknown resolves toward "try again."** The two errors are not symmetrical:
+ * telling a user with a good key that it is invalid ends the enrolment, while
+ * telling a user with a bad key to retry costs one more attempt and then tells
+ * them the truth. So anything unrecognised (including a response with no status
+ * at all) takes the transient branch.
+ *
+ * ## Why retry rather than merely report
+ *
+ * The dominant transient case is self-inflicted and self-clearing: we deploy,
+ * the runner drains, it returns 503 for a moment. Reporting that accurately
+ * still costs the user an enrolment attempt they did nothing to deserve. One
+ * retry absorbs it entirely. It is bounded at two attempts and one short delay
+ * because this runs inside the `/authorize` POST the human is watching.
+ *
+ * Note the direction: this can only turn a refusal into a success. It cannot
+ * strand anyone, which is what separates it from any check on the Google layer.
+ */
+async function verifyConnectorKey(endpoint: string, key: string): Promise<void> {
+  let cause = '';
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    if (attempt > 0) {
+      await new Promise((resolve) => setTimeout(resolve, LOGIN_RETRY_DELAY_MS));
+    }
+    let res: Response;
+    try {
+      res = await fetch(`${endpoint}/health`, {
+        headers: { Authorization: `Bearer ${key}` },
+        signal: AbortSignal.timeout(LOGIN_ATTEMPT_TIMEOUT_MS),
+      });
+    } catch (err) {
+      cause = `could not reach the gog backend (${describeCause(err)})`;
+      continue;
+    }
+    if (res.ok) return;
+    if (res.status === 401 || res.status === 403) {
+      logAuthTransition('connect.key-rejected', {
+        endpoint,
+        reason: `the runner refused the connector key (HTTP ${res.status})`,
+      });
+      throw new Error('Invalid connector key (backend rejected it)');
+    }
+    cause = `the gog backend did not answer the key check (${describeStatus(res.status)})`;
+  }
+  logAuthTransition('connect.runner-unreachable', { endpoint, reason: cause });
+  // `cause` can quote text this layer did not author — a proxy's error body, a
+  // socket error that echoed the outgoing Authorization header — so the sentence
+  // shown on the login page goes through the same redactor as every other error
+  // this repo hands back.
+  throw new Error(redactSecrets(`${cause}. ${UNREACHABLE_ADVICE}`));
+}
+
+
+/**
+ * The MCP `instructions` every hosted agent advertises (see `worker.ts`).
+ *
+ * ## Why a connector needs to say this at all
+ *
+ * There are two independent credentials behind these tools and the client UI
+ * shows only the first:
+ *
+ *   Layer 1  claude.ai → this Worker → the Fly runner, authenticated by the
+ *            user's connector key (the runner's RUNNER_KEY), stored in OAUTH_KV.
+ *   Layer 2  `gog` on the Fly machine → Google, authenticated by a refresh token
+ *            in gog's file keyring on the /data volume. The connector never
+ *            sees it, cannot refresh it, and is not told when it dies.
+ *
+ * "Connected" is a layer-1 fact. "Refreshed" is smaller still: `ConnectorAuth`
+ * exposes only a `login` hook — no `validate`, no `refresh` — so a refresh is an
+ * OAuth exchange inside OAUTH_KV that contacts neither Fly nor Google. Both
+ * words are outside this repo's control, and both get read as "your Google
+ * access works". They were, right up until the next Gmail call returned a Google
+ * 401.
+ *
+ * So the boundary we DO own says it plainly, to the one reader who can act on it
+ * before the user hits the error: the model holding these tools.
+ */
+export const CONNECTOR_INSTRUCTIONS = [
+  'These tools reach Google through a `gog` install on the user\'s own Fly.io machine.',
+  '',
+  'There are TWO credentials, and this connector holds only the first:',
+  '  1. the connector key, which authorizes this Worker to call that machine;',
+  '  2. a Google refresh token in gog\'s keyring ON that machine, which the connector',
+  '     never sees and cannot refresh.',
+  '',
+  'A "connected" or "refreshed" connector therefore proves only (1). It does NOT mean',
+  'Google still accepts (2): a refresh token that expired or was revoked leaves the',
+  'connector looking perfectly healthy until the first real call returns a Google 401.',
+  'Nothing in the connection status measures Google — gog_auth_health is the only tool',
+  'that does, because it performs a real token refresh against Google.',
+  '',
+  'When a call fails with a Google 401 or invalid_grant, do not retry it and do not',
+  'assume the connector is broken. Run gog_auth_health to confirm, then re-authorize',
+  'with gog_auth_add_url followed by gog_auth_add_complete (the browser-based',
+  'gog_auth_add cannot work here — there is no browser on the Fly machine).',
+  '',
+  'If the OAuth client\'s consent screen is still in "Testing" mode, Google expires its',
+  'refresh tokens exactly 7 days after issue, so this can recur weekly until the app is',
+  'published. gog_auth_health reports how long ago each account was authorized.',
+].join('\n');
+
+/**
+ * Ask the runner whether Google still accepts the credential on its volume, and
+ * record the answer. Resolves in every case; it can neither throw nor return a
+ * value, because nothing may make a decision out of what it finds.
+ *
+ * ## Why measuring here is worth doing, and why refusing here is not
+ *
+ * `login()` verifies the connector key against the runner's `/health`, an
+ * endpoint whose own comment says it "does not depend on gog". So a successful
+ * login has always been a layer-1 statement, presented to the user as if it
+ * settled both layers. This makes the connect path measure the layer it was
+ * silently vouching for.
+ *
+ * It must never gate the login. The tools that repair a dead Google credential
+ * (`gog_auth_add_url`, `gog_auth_add_complete`) are MCP tools, reachable only
+ * once the connector is connected — so refusing to connect on a dead credential
+ * would lock the user out of the only path that fixes it. The goal is that
+ * status never claims health it did not measure, NOT that a bad measurement
+ * refuses the connection.
+ *
+ * ## What it is honestly able to say
+ *
+ * Only what was true AT CONNECT TIME, and only on the connect path: claude.ai's
+ * later "refreshed" never reaches this code (there is no `refresh` hook to run
+ * it from), so the record is a fixed point in the past, not a live status. Its
+ * value is that the incident log finally contains what the Google layer was
+ * doing at the moment the UI said "connected" — which is exactly the correlation
+ * that could not be made when this was first reported.
+ */
+async function recordGoogleLayerAtConnect(endpoint: string, key: string): Promise<void> {
+  let event: AuthTransition;
+  let reason: string | undefined;
+  try {
+    const res = await fetch(`${endpoint}/health/google`, {
+      headers: { Authorization: `Bearer ${key}` },
+      signal: AbortSignal.timeout(GOOGLE_PROBE_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      // Includes the 404 from a runner deployed before the probe endpoint
+      // existed. "I could not ask" is never reported as "Google said no".
+      event = 'connect.google-unmeasured';
+      reason = `the runner did not answer the Google probe (HTTP ${res.status})`;
+    } else {
+      // `readGoogleProbe` is the ONE place that judges a probe body, shared with
+      // the post-refusal probe in connector-runtime.ts. It reads the runner's
+      // `measured` field before its `ok` field, which is what keeps a probe that
+      // TIMED OUT or could not be RUN out of `-unhealthy` — an event whose
+      // documented meaning is "Google was asked and refused". The reason string
+      // it returns comes from the runner's closed vocabulary (PROBE_CAUSES), so
+      // it carries a classification and never gog's own output.
+      const verdict = readGoogleProbe(await res.json());
+      event =
+        verdict.kind === 'ok'
+          ? 'connect.google-ok'
+          : verdict.kind === 'unhealthy'
+            ? 'connect.google-unhealthy'
+            : 'connect.google-unmeasured';
+      reason = verdict.reason;
+    }
+  } catch (err) {
+    // A rejected fetch, an abort at GOOGLE_PROBE_TIMEOUT_MS, or a body that is
+    // not JSON (a proxy's HTML error page). None of them are facts about Google.
+    event = 'connect.google-unmeasured';
+    reason = err instanceof Error ? err.message : String(err);
+  }
+  // `reason` can quote text this layer did not author, so the record goes
+  // through the same redactor as every other auth log line.
+  logAuthTransition(event, { endpoint, reason });
+}
+
 /**
  * `ConnectorAuth` for the gogcli remote connector: the login page collects the
  * user's connector key, verifies it by hitting the Fly backend's `/health`
- * endpoint with the key as a bearer token (a bad key makes the backend answer
- * non-2xx, which surfaces back on the login page), and stores `{ key }` as the
- * OAuth props that `worker.ts`'s `buildClient` turns into a per-session Fly
- * executor.
+ * endpoint with the key as a bearer token, and stores `{ key }` as the OAuth
+ * props that `worker.ts`'s `buildClient` turns into a per-session Fly executor.
+ *
+ * Only the runner judging the bearer (401/403) refuses the login; a backend that
+ * does not answer is retried once and then reported as unreachable, never as a
+ * bad key — see `verifyConnectorKey`.
+ *
+ * After the key is accepted it also measures the SECOND credential — the Google
+ * grant on the Fly volume — and records what it found. That measurement changes
+ * nothing about whether the login succeeds; see `recordGoogleLayerAtConnect`.
  */
 export const gogAuth: ConnectorAuth<GogProps> = {
   service: 'gogcli (Google Workspace)',
@@ -37,10 +292,12 @@ export const gogAuth: ConnectorAuth<GogProps> = {
     'Your connector key is stored encrypted and used only to reach your own gog backend.',
   fields: [{ name: 'key', label: 'gogcli connector key', type: 'password' }],
   async login(fields, env) {
-    const res = await fetch(`${(env as any).FLY_ENDPOINT}/health`, {
-      headers: { Authorization: `Bearer ${fields.key}` },
-    });
-    if (!res.ok) throw new Error('Invalid connector key (backend rejected it)');
+    const endpoint = (env as any).FLY_ENDPOINT;
+    // Layer 1. Throws — and only this may refuse the login.
+    await verifyConnectorKey(endpoint, fields.key);
+    // Layer 2. Records; never refuses. Deliberately after the key check, so a
+    // login that never happened says nothing at all about Google.
+    await recordGoogleLayerAtConnect(endpoint, fields.key);
     return { key: fields.key };
   },
 };

package/src/connector-runtime.ts

@@ -1,6 +1,7 @@
 import { runExecutor, RunnerTransportError } from './runner.js';
 import type { GogArg, GogExecutor } from './runner.js';
-import { logAuthTransition } from './auth-log.js';
+import { logAuthTransition, type AuthTransition } from './auth-log.js';
+import { readGoogleProbe } from './google-probe.js';
 
 // Re-exported so the runner-transport error type reads as part of THIS module's
 // surface — this is the layer that authors these failures. It is DEFINED in
@@ -52,6 +53,61 @@ const DEADLINE_GRACE_MS = 5_000;
 // own next call mints a fresh token.
 const MIN_REPLAY_BUDGET_MS = 1_000;
 
+// --- The Google-layer measurement taken when a hosted call is refused --------
+//
+// DEFECT 3 was "the hosted path has no automatic recovery, by design", and the
+// instinct was to build one. It should not be built. `gog` is spawned fresh per
+// `/run` and re-reads the keyring every time, so there is no cross-spawn
+// in-memory token that could go stale: a Google 401 on this path means the
+// STORED credential was refused, and no retry can repair that. What was missing
+// was never a retry — it was an answer to the question nobody could answer after
+// the incident: at the moment Google refused that call, was the refresh token on
+// the volume alive or dead? `replay.declined` records only that WE did nothing.
+//
+// So this asks, once, using the probe the runner now exposes, and writes down
+// what it heard. It never decides anything, never alters the caller's error and
+// never throws.
+
+/**
+ * How long the refusal probe may take.
+ *
+ * Deliberately much shorter than the runner's own budget for the same probe
+ * (`GOOGLE_PROBE_TIMEOUT_MS` in server.mjs): the caller is already holding a
+ * failed tool call, and every millisecond spent here delays the error they
+ * actually need. Timing out is a fine outcome — it records "not measured".
+ */
+const REFUSAL_PROBE_TIMEOUT_MS = 4_000;
+
+/**
+ * The smallest slice of the call's REMAINING deadline worth spending on a
+ * diagnostic. Mirrors MIN_REPLAY_BUDGET_MS and for the same reason: below this
+ * the probe can only abort, so it would buy nothing and cost the caller's error
+ * a delay. Skipping is recorded, not silent.
+ */
+const MIN_PROBE_BUDGET_MS = 1_000;
+
+/**
+ * How rarely one executor will re-measure the same backend.
+ *
+ * `/health/google` spawns a real `gog auth list --check`, which costs a Google
+ * API call and takes the keyring's EXCLUSIVE flock. That adjective was
+ * challenged in review as read-only rhetoric, so it is sourced: `auth list`
+ * reaches the keyring through `listAuthTokensWithFallback` →
+ * `store.ListTokens()` (gogcli `internal/cmd/auth_list_helpers.go`), and
+ * `ListTokens` wraps its read in `withWriteLock`, not `withReadLock`
+ * (`internal/secrets/token.go`) → `withFileLock(true, …)` →
+ * `unix.LOCK_EX | LOCK_NB` (`internal/secrets/keyring_lock_unix.go`). Verified
+ * against v0.34.1, the tag this deployment's Dockerfile pins. The shared lock
+ * exists but is taken by `Keys()`, which `auth list` reaches only on the
+ * fallback path after `ListTokens` has already failed.
+ *
+ * A model retrying a call against a genuinely refused credential would
+ * otherwise turn one diagnostic into a queue of them, on the box that is
+ * already failing. One measurement a minute is plenty: the fact being measured
+ * changes on the order of days.
+ */
+const PROBE_INTERVAL_MS = 60_000;
+
 // Status codes the Fly runner uses to classify its OWN failures. These must stay
 // in sync with fly-gog-runner/server.mjs — they are the contract that lets this
 // side tell "gog ran and failed" apart from "the request never arrived", without
@@ -246,6 +302,11 @@ async function remintAfterGoogleRejection(
   args: GogArg[],
   readAccessToken: FlyAccessTokenSource | undefined,
   deadlineAt: number,
+  // Take a live reading of the Google layer. Supplied by `makeFlyExecutor` so
+  // this function keeps knowing nothing about the endpoint, the bearer or how
+  // often measuring is affordable — it decides only WHEN a reading is worth
+  // taking, which is the one part of it that belongs to the replay ladder.
+  probeGoogle: (where: { credential?: string; service?: string }) => Promise<void>,
 ): Promise<Replay | undefined> {
   // Only a failure gog itself authored can carry Google's verdict. A runner
   // transport failure never reached Google, and the runner's own 401 is about
@@ -290,6 +351,22 @@ async function remintAfterGoogleRejection(
   // whatever identity the backend volume holds and only an operator can change
   // that.
   if (!used) {
+    // THE HOSTED PATH, and the only place a reading is worth paying for.
+    //
+    // We are here because Google refused a call that `gog` made as the BACKEND
+    // VOLUME's own identity — the shape `worker.ts` produces on every hosted
+    // connector. Nothing above this line can say whether the credential behind
+    // that identity is dead or alive, and that is precisely the fact the
+    // incident needed and did not have. So measure first, then record the
+    // decision: the pair reads as "here is what Google said, here is why we did
+    // nothing about it".
+    //
+    // Ordered before the `replay.declined` line rather than after it so the log
+    // tells the story in the order it happened. Awaited rather than fired and
+    // forgotten because a Worker may cancel unawaited work at the end of the
+    // request — an unawaited probe is one that silently does not happen, which
+    // is the failure mode this whole branch exists to delete.
+    await probeGoogle(where);
     logAuthTransition('replay.declined', {
       ...where,
       reason:
@@ -424,6 +501,113 @@ export function makeFlyExecutor(
   key: string,
   readAccessToken?: FlyAccessTokenSource,
 ): GogExecutor {
+  // Throttle state for the refusal probe, held PER EXECUTOR rather than in a
+  // module-level map.
+  //
+  // That is the scope the thing being throttled actually has: on the Worker one
+  // executor is built per agent session (`worker.ts` `init()`), on stdio one per
+  // process (`remote-runner.ts`). So a session that is hammering a refused
+  // credential rate-limits itself without a second, unrelated session's probe
+  // being suppressed by it — a module global would let one caller's retry loop
+  // silence everybody else's first and only measurement. It also means the state
+  // dies with the session instead of accumulating endpoints for the isolate's
+  // lifetime.
+  let lastProbeAt = Number.NEGATIVE_INFINITY;
+
+  /**
+   * Ask the runner whether Google still accepts the credential on its volume,
+   * and record the answer. Resolves in EVERY case: it can neither throw nor
+   * return a value, because nothing may make a decision out of what it finds.
+   * The caller's error is already decided by the time this runs.
+   */
+  const probeGoogleAfterRefusal = async (
+    where: { credential?: string; service?: string },
+    deadlineAt: number,
+  ): Promise<void> => {
+    const record = { ...where, endpoint };
+
+    // ONE reading of the clock for both budget and throttle, so the two
+    // decisions cannot disagree about what time it is.
+    const now = Date.now();
+    const remainingMs = deadlineAt - now;
+    if (remainingMs < MIN_PROBE_BUDGET_MS) {
+      logAuthTransition('refusal.google-unmeasured', {
+        ...record,
+        reason:
+          `only ${remainingMs}ms of the call’s deadline remained, so the Google layer was not ` +
+          'measured rather than delay the caller’s own error',
+      });
+      return;
+    }
+    if (now - lastProbeAt < PROBE_INTERVAL_MS) {
+      logAuthTransition('refusal.google-unmeasured', {
+        ...record,
+        // "attempted", not "measured". `lastProbeAt` is stamped before the
+        // fetch and is deliberately NOT reset when the probe comes back with no
+        // verdict (a 404 from a runner too old to have the endpoint, a timeout,
+        // a dead socket) — the backend cost this throttle exists to bound was
+        // paid either way, and resetting it would let a retry loop storm a
+        // runner that is already unwell. So the timestamp stays and the sentence
+        // has to be the true one: on this branch a log line may not assert a
+        // measurement that never happened, and the previous probe may well have
+        // measured nothing at all.
+        reason:
+          'a Google probe was attempted recently, so another was not sent: this probe spawns ' +
+          'gog on the backend and takes the keyring’s exclusive lock',
+      });
+      return;
+    }
+    // Claimed BEFORE the await, so two overlapping refusals cannot both get
+    // past the check and spawn a probe apiece.
+    lastProbeAt = now;
+
+    let event: AuthTransition;
+    let reason: string;
+    try {
+      const res = await fetch(`${endpoint}/health/google`, {
+        headers: { Authorization: `Bearer ${key}` },
+        // Never more than the probe's own budget, never more than the call has
+        // left. `Math.min` rather than a plain constant because the second
+        // bound is the caller's, and it outranks ours.
+        signal: AbortSignal.timeout(Math.min(REFUSAL_PROBE_TIMEOUT_MS, remainingMs)),
+      });
+      if (!res.ok) {
+        // Includes the 404 from a runner deployed before `/health/google`
+        // existed. "I could not ask" is never filed as "Google said no" — that
+        // is the defect this branch exists to delete, with the alarm inverted.
+        event = 'refusal.google-unmeasured';
+        reason = `the runner did not answer the Google probe (HTTP ${res.status})`;
+      } else {
+        // `readGoogleProbe` is the ONE place that judges a probe body, shared
+        // with the connect-time probe in connector-auth.ts. It reads the
+        // runner's `measured` field BEFORE its `ok` field, which is what keeps a
+        // probe that timed out or could not be run from being filed as
+        // `-unhealthy` — the record an operator reads as "the live check agrees
+        // the credential is refused". Its reason strings come from the runner's
+        // CLOSED vocabulary of causes (PROBE_CAUSES in server.mjs), so they
+        // carry a classification and never gog's own output.
+        const verdict = readGoogleProbe(await res.json());
+        if (verdict.kind === 'ok') {
+          event = 'refusal.google-ok';
+          reason =
+            'Google refused this call, yet a live token check on the same volume succeeded — ' +
+            'so a dead or expired refresh token does not explain this refusal';
+        } else {
+          event = verdict.kind === 'unhealthy' ? 'refusal.google-unhealthy' : 'refusal.google-unmeasured';
+          reason = verdict.reason;
+        }
+      }
+    } catch (err) {
+      // A rejected fetch, an abort at the budget, or a body that is not JSON (a
+      // proxy's HTML error page). None of them are facts about Google.
+      event = 'refusal.google-unmeasured';
+      reason = err instanceof Error ? err.message : String(err);
+    }
+    // `reason` can quote text this layer did not author, so the record goes
+    // through the same redactor as every other auth log line.
+    logAuthTransition(event, { ...record, reason });
+  };
+
   return async (args: GogArg[], opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
     // Awaited, because the token may have to be MINTED (#241): a refresh token
@@ -455,6 +639,7 @@ export function makeFlyExecutor(
         args,
         readAccessToken,
         deadlineAt,
+        (where) => probeGoogleAfterRefusal(where, deadlineAt),
       );
       if (replay === undefined) throw err;
 

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/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',