gogcli-mcp 2.21.0 → 2.21.1

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/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}`);

package/src/worker.ts

@@ -38,7 +38,7 @@ import { gogAuth, type GogProps } from './connector-auth.js';
 // connector with all ~360 tools at once. Add whichever paths you want as separate
 // connectors in claude.ai (each authorizes with the same connector key).
 
-const VERSION = '2.21.0'; // x-release-please-version
+const VERSION = '2.21.1'; // x-release-please-version
 
 // Build an McpAgent subclass whose init() registers `registrars` onto its server,
 // each handler wrapped in the ALS scope carrying the per-session Fly executor.
@@ -48,6 +48,17 @@ function makeAgent(registrars: ToolRegistrar[]): typeof McpAgent {
   class GogAgent extends McpAgent<unknown, unknown, GogProps> {
     server = new McpServer({ name: 'gogcli-mcp', version: VERSION });
     async init() {
+      // NO third argument, deliberately: the hosted connector supplies no
+      // per-caller access token, so `gog` runs as the Fly volume's own identity
+      // and refreshes from its own keyring. That is what makes the eviction +
+      // replay machinery in connector-runtime.ts INERT here — with no token
+      // source there is no module-level cache that can go stale, so a Google
+      // 401 on this path stops at the `no access token was supplied` guard and
+      // logs `replay.declined`. That record is the expected outcome for a
+      // hosted connector, not a bug; the transport-failure classification and
+      // the auth log itself do apply here. (docs/DEPLOY-CONNECTOR.md,
+      // "Reading the auth log", says the same thing for whoever is reading logs
+      // rather than code.)
       const executor = makeFlyExecutor((this.env as { FLY_ENDPOINT: string }).FLY_ENDPOINT, this.props.key);
       const wrapped = wrapServer(this.server, executor);
       for (const register of registrars) register(wrapped);