gogcli-mcp-docs 2.21.0 → 2.22.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
-    "version": "2.21.0"
+    "version": "2.22.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Docs)",
       "source": "./",
       "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
-      "version": "2.21.0",
+      "version": "2.22.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-docs",
   "displayName": "gogcli (Docs)",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -62,7 +62,7 @@ Plus 5 auth tools and 7 base Docs tools (info, cat, create, write, find-replace,
 | `gog_docs_sed` | Stream-edit with sed-like regex expressions |
 | `gog_docs_trash` | Move a doc to Drive trash |
 | `gog_docs_update` | Update document content at a specific position |
-| `gog_docs_comments_list` | List comments (open or resolved) |
+| `gog_docs_comments_list` | List comments (open or resolved), optionally with each comment's tab and index ranges |
 | `gog_docs_comments_get` | Get a comment with its replies |
 | `gog_docs_comments_add` | Add a comment with optional quoted text |
 | `gog_docs_comments_reply` | Reply to a comment |

package/SKILL.md

@@ -46,7 +46,7 @@ Extended Google Docs MCP server via [gogcli](https://github.com/openclaw/gogcli)
 | `gog_docs_sed` | Stream-edit with sed-like regex |
 | `gog_docs_trash` | Move a doc to Drive trash |
 | `gog_docs_update` | Update content at a specific position |
-| `gog_docs_comments_list` | List comments (open or resolved) |
+| `gog_docs_comments_list` | List comments (open or resolved), optionally with each comment's tab and index ranges |
 | `gog_docs_comments_get` | Get a comment with replies |
 | `gog_docs_comments_add` | Add a comment with optional quoted text |
 | `gog_docs_comments_reply` | Reply to a comment |

package/dist/index.js

@@ -31140,6 +31140,21 @@ import { delimiter, join } from "node:path";
 function isGogFileArg(arg) {
   return typeof arg !== "string";
 }
+var RUNNER_TRANSPORT_BRAND = /* @__PURE__ */ Symbol.for("gogcli.RunnerTransportError");
+var RunnerTransportError = class extends Error {
+  kind;
+  status;
+  constructor(message, kind, status) {
+    super(message);
+    this.name = "RunnerTransportError";
+    this.kind = kind;
+    this.status = status;
+    Object.defineProperty(this, RUNNER_TRANSPORT_BRAND, { value: true });
+  }
+};
+function isRunnerTransportError(err) {
+  return err instanceof Error && err[RUNNER_TRANSPORT_BRAND] === true;
+}
 var runExecutor = new AsyncLocalStorage();
 var defaultExecutor;
 function setDefaultGogExecutor(executor) {
@@ -31320,7 +31335,11 @@ async function run(args, options = {}) {
     }
     return redact(output);
   } catch (err) {
-    throw new Error(redact(err instanceof Error ? err.message : String(err)));
+    const message = redact(err instanceof Error ? err.message : String(err));
+    if (isRunnerTransportError(err)) {
+      throw new RunnerTransportError(message, err.kind, err.status);
+    }
+    throw new Error(message);
   }
 }
 
@@ -31411,6 +31430,13 @@ var TIMESTAMP_KEYS = /* @__PURE__ */ new Set([
   // 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",
@@ -31584,7 +31610,7 @@ function registerRunTool(server, options) {
 function errorText(err) {
   return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
-var DEFINITE_AUTH_PATTERN = /\b(401|unauthorized|invalid_grant)\b/i;
+var DEFINITE_AUTH_PATTERN = /\b(?:unauthorized|invalid_grant)\b|\b(?:error|status|code|http|responded|response)["']?[\s:=(,]{0,4}401\b/i;
 var STALE_TOKEN_PATTERN = /\b(?:access[ _-]?)?token\b[^.;\n]{0,40}\b(?:has\s+)?(?:been\s+)?(?:expired|revoked)\b|\b(?:expired|revoked)\s+(?:access[ _-]?)?token\b/i;
 var AUTH_ERROR_PATTERN = new RegExp(`${DEFINITE_AUTH_PATTERN.source}|${STALE_TOKEN_PATTERN.source}`, "i");
 var INVALID_GRANT_PATTERN = /invalid_grant|token has been expired or revoked/i;
@@ -31594,6 +31620,14 @@ var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-aut
 var INVALID_GRANT_HINT = '\n\nThe stored refresh token was rejected (invalid_grant): it has expired or been revoked, so the whole account is signed out and re-authorization is required. The most common cause is the 7-day refresh-token limit Google applies to OAuth apps whose consent screen is still in "Testing" mode. Re-authorize with gog_auth_add (opens a browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless). To stop this recurring, publish the OAuth consent screen to "In production" in the Google Cloud project that owns the OAuth client. Ask the user if they would like to re-authenticate.';
 var TRANSIENT_HINT = "\n\nThis error is often transient. Retry the same call before trying a different approach (do not fall back to smaller writes or row-by-row operations).";
 var GRID_LIMIT_HINT = "\n\nThe target range is outside the sheet's current grid. Add the missing rows or columns first with gog_sheets_insert (dimension: rows or cols), then retry the write.";
+var RUNNER_TRANSPORT_AUTH_HINT = "\n\nThis is the CONNECTOR's own transport auth failing, not your Google sign-in. The gog-runner backend rejected the bearer token this server sent, so the request never reached gog and no Google credential was checked \u2014 the Google account is not the problem and re-authorizing it cannot fix this. An operator must make the Worker secret GOG_RUNNER_KEY equal RUNNER_KEY on the Fly app (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY), then retry.";
+var RUNNER_TRANSPORT_HINTS = {
+  "transport-auth": RUNNER_TRANSPORT_AUTH_HINT,
+  // The request itself was malformed, so the runner will refuse it identically
+  // every time. Nothing to advise beyond the message the runner already gave.
+  "transport-request": "",
+  "transport-retryable": TRANSIENT_HINT
+};
 function formatAccountList(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -31606,11 +31640,12 @@ function formatAccountList(raw) {
 }
 async function diagnose(err) {
   const errText = errorText(err);
+  const transportHint = isRunnerTransportError(err) ? RUNNER_TRANSPORT_HINTS[err.kind] : void 0;
   const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
   const isTransientError = !DEFINITE_AUTH_PATTERN.test(errText) && TRANSIENT_ERROR_PATTERN.test(errText);
   const isAuthError = !isTransientError && AUTH_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
-  const hint = isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
+  const hint = transportHint ?? (isInvalidGrant ? INVALID_GRANT_HINT : isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "");
   try {
     const accounts = formatAccountList(await run(["auth", "list"]));
     return errorResult(`${errText}
@@ -31643,8 +31678,8 @@ function formatOneAccountHealth(a, now) {
   const age = ageInDays(a.created_at, now);
   const ageStr = age === null ? "" : ` Authorized ${age.toFixed(1)} day(s) ago.`;
   if (a.valid === false) {
-    const cause = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
-    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
+    const cause2 = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
+    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause2}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
   }
   if (a.valid === true) {
     let line = `\u2713 ${email3}: token valid.${ageStr}`;
@@ -31686,7 +31721,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   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 \u2014 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 () => {
@@ -31697,7 +31732,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   server.registerTool("gog_auth_health", {
-    description: 'Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens \u2014 the account-wide sign-out that blocks every 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.',
+    description: 'Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens \u2014 the account-wide sign-out that blocks every 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. 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 \u2014 the Google credential lives on that machine and can be dead while the connection looks perfectly healthy.',
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -31904,7 +31939,40 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.21.0" : "0.0.0";
+var VERSION = true ? "2.22.0" : "0.0.0";
+
+// ../gogcli-mcp/src/auth-log.ts
+var FAILURES = /* @__PURE__ */ new Set([
+  "token.mint-failed",
+  "grant.dead",
+  "replay.failed",
+  "runner.auth-failed",
+  "connect.key-rejected",
+  // An enrolment that could not proceed is a failure even though nobody is at
+  // fault: it is the only trace a half-enrolled connector leaves behind, and
+  // the absence of exactly this record is why DEFECT 4 could not be explained.
+  "connect.runner-unreachable",
+  "connect.google-unhealthy",
+  "refusal.google-unhealthy",
+  // The loudest record on this branch, and the only one that means "we cannot
+  // explain this". Google refused a real call while a live check of the same
+  // credential, taken seconds later, succeeded — so neither the 7-day cliff nor
+  // a revoked grant accounts for it. It is filed as a failure precisely because
+  // it is the record nobody may scroll past: it is the only evidence that could
+  // ever justify building something on the hosted path, and its absence over
+  // time is what retires that theory for good.
+  "refusal.google-ok"
+]);
+var PREFIX = "gog-auth ";
+var TAG_CHARS = 12;
+function credentialTag(cacheKeyHash) {
+  return cacheKeyHash.slice(0, TAG_CHARS);
+}
+function logAuthTransition(event, context) {
+  const record2 = JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), event, ...context });
+  const write = FAILURES.has(event) ? console.error : console.warn;
+  write(PREFIX + redactSecrets2(record2));
+}
 
 // ../gogcli-mcp/src/google-token.ts
 var TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
@@ -31931,22 +31999,73 @@ function makeAccessTokenSource(env) {
       );
     };
   }
-  return async () => {
-    const key = await cacheKey(refreshToken, clientId);
-    const hit = cache.get(key);
-    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return hit.accessToken;
-    let pending = inFlight.get(key);
+  let keyPromise;
+  const key = () => keyPromise ??= cacheKey(refreshToken, clientId);
+  const logCacheHits = parseBoolEnv("GOG_AUTH_LOG_CACHE_HITS", { env });
+  const read = async () => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (hit && hit.expiresAt - EXPIRY_MARGIN_MS > Date.now()) {
+      if (logCacheHits) logAuthTransition("token.cache-hit", { credential: credentialTag(k) });
+      return hit.accessToken;
+    }
+    let pending = inFlight.get(k);
     if (!pending) {
       pending = exchange(refreshToken, clientId, clientSecret).then((minted2) => {
-        cache.set(key, minted2);
+        cache.set(k, minted2);
+        logAuthTransition("token.minted", {
+          credential: credentialTag(k),
+          reason: `valid for ${Math.round((minted2.expiresAt - Date.now()) / 1e3)}s`
+        });
         return minted2;
-      }).finally(() => inFlight.delete(key));
-      inFlight.set(key, pending);
+      }).catch((err) => {
+        logAuthTransition(err.grantDead ? "grant.dead" : "token.mint-failed", {
+          credential: credentialTag(k),
+          reason: err.message
+        });
+        throw err;
+      }).finally(() => inFlight.delete(k));
+      inFlight.set(k, pending);
     }
     const minted = await pending;
     return minted.accessToken;
   };
+  const invalidate = async (rejected) => {
+    const k = await key();
+    const hit = cache.get(k);
+    if (!hit || hit.accessToken !== rejected) {
+      logAuthTransition("token.evict-noop", {
+        credential: credentialTag(k),
+        reason: hit ? "a concurrent caller had already replaced this credential\u2019s token" : "no token was cached for this credential"
+      });
+      return false;
+    }
+    cache.delete(k);
+    logAuthTransition("token.evicted", {
+      credential: credentialTag(k),
+      reason: "Google rejected this access token; the next read will mint a new one"
+    });
+    return true;
+  };
+  return Object.assign(read, {
+    invalidate,
+    credentialId: async () => credentialTag(await key())
+  });
 }
+var TokenExchangeError = class extends Error {
+  /**
+   * The REFRESH token is dead (Google's `invalid_grant`), not merely the access
+   * token. Carried as a flag rather than re-read from the message, because
+   * inferring the author of a failure from prose several authors can produce is
+   * precisely the mistake this branch exists to undo. `instanceof` is safe: the
+   * class is thrown and caught inside this one module.
+   */
+  grantDead;
+  constructor(message, grantDead) {
+    super(message);
+    this.grantDead = grantDead;
+  }
+};
 async function exchange(refreshToken, clientId, clientSecret) {
   let res;
   try {
@@ -31961,79 +32080,338 @@ async function exchange(refreshToken, clientId, clientSecret) {
       }).toString()
     });
   } catch (err) {
-    throw new Error(
-      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`
+    throw new TokenExchangeError(
+      `the Google token exchange could not be reached: ${err instanceof Error ? err.message : String(err)}`,
+      false
     );
   }
   const body = await res.json().catch(() => ({}));
   if (!res.ok) {
     if (body.error === "invalid_grant") {
-      throw new Error(
-        'the stored refresh token has expired or been revoked, so this account must be re-authorized (commonly the 7-day limit on OAuth consent screens still in "Testing" mode). Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.'
+      throw new TokenExchangeError(
+        'the stored refresh token was rejected (invalid_grant): it has expired or been revoked, so this account must be re-authorized (commonly the 7-day limit on OAuth consent screens still in "Testing" mode). Re-enrol with gog_auth_add_url + gog_auth_add_complete and store the new refresh token.',
+        true
       );
     }
-    throw new Error(
-      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`
+    throw new TokenExchangeError(
+      `the access token could not be refreshed (HTTP ${res.status}${body.error ? `, ${body.error}` : ""})`,
+      false
     );
   }
   if (!body.access_token) {
-    throw new Error("the access token could not be refreshed: Google returned no access_token");
+    throw new TokenExchangeError(
+      "the access token could not be refreshed: Google returned no access_token",
+      false
+    );
   }
   const expiresInMs = (body.expires_in ?? 3600) * 1e3;
   return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
 }
 
+// ../gogcli-mcp/src/google-probe.ts
+var bool = (value) => typeof value === "boolean" ? value : void 0;
+var cause = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+function readGoogleProbe(body) {
+  const record2 = typeof body === "object" && body !== null ? body : {};
+  const measured = bool(record2.measured);
+  const reported = cause(record2.error);
+  if (measured === false) {
+    return {
+      kind: "unmeasured",
+      reason: reported ?? "the runner reported it could not measure the Google layer"
+    };
+  }
+  if (measured === true) {
+    if (bool(record2.ok) === true) return { kind: "ok" };
+    return {
+      kind: "unhealthy",
+      reason: reported ?? "the runner reported the Google layer unhealthy with no cause"
+    };
+  }
+  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"
+  };
+}
+
 // ../gogcli-mcp/src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
+var MIN_REPLAY_BUDGET_MS = 1e3;
+var REFUSAL_PROBE_TIMEOUT_MS = 4e3;
+var MIN_PROBE_BUDGET_MS = 1e3;
+var PROBE_INTERVAL_MS = 6e4;
 var RUNNER_GOG_FAILED = 422;
 var RUNNER_DRAINING = 503;
+var RUNNER_BAD_REQUEST = 400;
+var RUNNER_BAD_KEY = 401;
+var GogFailedError = class extends Error {
+  /** gog's stderr alone, with no echoed argv mixed in. */
+  stderr;
+  constructor(message, stderr) {
+    super(message);
+    this.stderr = stderr;
+  }
+};
+var GOOGLE_TOKEN_REJECTED_PATTERN = /Google API error \(401\b|invalid[ _]authentication[ _]credentials|\bACCESS_TOKEN_EXPIRED\b|\binvalid_token\b/i;
+var REFRESH_TOKEN_DEAD_PATTERN = /\binvalid_grant\b/i;
+var READ_ONLY_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "cat",
+  "describe",
+  "get",
+  "info",
+  "list",
+  "list-slides",
+  "ls",
+  "metadata",
+  "read-slide",
+  "search",
+  "services",
+  "status",
+  "structure"
+]);
+function gogTarget(args) {
+  const words = args.filter((arg) => typeof arg === "string");
+  let service;
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    if (word.startsWith("-")) {
+      if (word === "--account") i += 1;
+      continue;
+    }
+    if (service === void 0) {
+      service = word;
+      continue;
+    }
+    return { service, subcommand: word };
+  }
+  return { service };
+}
+async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt, probeGoogle) {
+  if (!(err instanceof GogFailedError)) return void 0;
+  const grantDead = REFRESH_TOKEN_DEAD_PATTERN.test(err.stderr);
+  if (!grantDead && !GOOGLE_TOKEN_REJECTED_PATTERN.test(err.stderr)) return void 0;
+  const { service, subcommand } = gogTarget(args);
+  const credential = await readAccessToken?.credentialId?.();
+  const where = { credential, service };
+  if (grantDead) {
+    logAuthTransition("grant.dead", {
+      ...where,
+      reason: "gog reported invalid_grant: the stored refresh token is dead, so no token can be minted and this account must be re-authorized"
+    });
+    return void 0;
+  }
+  if (!used) {
+    await probeGoogle(where);
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "no access token was supplied with the call, so gog acted as the backend volume\u2019s own identity"
+    });
+    return void 0;
+  }
+  if (!readAccessToken?.invalidate) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "this token source cannot mint a replacement, so a replay would resend the rejected token"
+    });
+    return void 0;
+  }
+  const evicted = await readAccessToken.invalidate(used);
+  if (subcommand === void 0 || !READ_ONLY_SUBCOMMANDS.has(subcommand)) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `not replayable: '${subcommand ?? "(none)"}' is not a known read-only subcommand and a write could double-apply`
+    });
+    return void 0;
+  }
+  if (!evicted) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the rejected token was already superseded, so the cache holds the token a replay would send"
+    });
+    return void 0;
+  }
+  const fresh = await readAccessToken();
+  if (!fresh) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: "the token source produced no token after eviction; replaying without one would act as the backend"
+    });
+    return void 0;
+  }
+  const budgetMs = deadlineAt - Date.now();
+  if (budgetMs < MIN_REPLAY_BUDGET_MS) {
+    logAuthTransition("replay.declined", {
+      ...where,
+      reason: `only ${budgetMs}ms of the call\u2019s deadline remained, so a replay could only time out; the rejected token was evicted, so the next call mints a fresh one`
+    });
+    return void 0;
+  }
+  return { token: fresh, budgetMs, invalidate: readAccessToken.invalidate, ...where };
+}
 function makeFlyExecutor(endpoint, key, readAccessToken) {
+  let lastProbeAt = Number.NEGATIVE_INFINITY;
+  const probeGoogleAfterRefusal = async (where, deadlineAt) => {
+    const record2 = { ...where, endpoint };
+    const now = Date.now();
+    const remainingMs = deadlineAt - now;
+    if (remainingMs < MIN_PROBE_BUDGET_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        reason: `only ${remainingMs}ms of the call\u2019s deadline remained, so the Google layer was not measured rather than delay the caller\u2019s own error`
+      });
+      return;
+    }
+    if (now - lastProbeAt < PROBE_INTERVAL_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        // "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\u2019s exclusive lock"
+      });
+      return;
+    }
+    lastProbeAt = now;
+    let event;
+    let reason;
+    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) {
+        event = "refusal.google-unmeasured";
+        reason = `the runner did not answer the Google probe (HTTP ${res.status})`;
+      } else {
+        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 \u2014 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) {
+      event = "refusal.google-unmeasured";
+      reason = err instanceof Error ? err.message : String(err);
+    }
+    logAuthTransition(event, { ...record2, reason });
+  };
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
     const accessToken = await readAccessToken?.();
-    let res;
+    const deadlineAt = Date.now() + deadlineMs;
     try {
-      res = await fetch(endpoint + "/run", {
-        method: "POST",
-        headers: {
-          Authorization: "Bearer " + key,
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
-        signal: AbortSignal.timeout(deadlineMs)
-      });
+      return await attempt(endpoint, key, args, accessToken, deadlineMs);
     } catch (err) {
-      const name = err instanceof Error ? err.name : "";
-      if (name === "TimeoutError" || name === "AbortError") {
-        throw new Error(
-          `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`
-        );
+      const replay = await remintAfterGoogleRejection(
+        err,
+        accessToken,
+        args,
+        readAccessToken,
+        deadlineAt,
+        (where2) => probeGoogleAfterRefusal(where2, deadlineAt)
+      );
+      if (replay === void 0) throw err;
+      const where = { credential: replay.credential, service: replay.service, endpoint };
+      logAuthTransition("replay.attempted", {
+        ...where,
+        reason: "Google rejected the access token; replaying this read once with a freshly minted one"
+      });
+      try {
+        const stdout = await attempt(endpoint, key, args, replay.token, replay.budgetMs);
+        logAuthTransition("replay.succeeded", where);
+        return stdout;
+      } catch (replayErr) {
+        logAuthTransition("replay.failed", { ...where, reason: String(replayErr) });
+        if (replayErr instanceof GogFailedError && GOOGLE_TOKEN_REJECTED_PATTERN.test(replayErr.stderr)) {
+          await replay.invalidate(replay.token);
+        }
+        throw replayErr;
       }
-      throw err;
     }
-    if (!res.ok) {
-      const body = await res.json().catch(() => null);
-      const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
+  };
+}
+async function attempt(endpoint, key, args, accessToken, deadlineMs) {
+  let res;
+  try {
+    res = await fetch(endpoint + "/run", {
+      method: "POST",
+      headers: {
+        Authorization: "Bearer " + key,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(accessToken ? { args, accessToken } : { args }),
+      signal: AbortSignal.timeout(deadlineMs)
+    });
+  } catch (err) {
+    const name = err instanceof Error ? err.name : "";
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw new RunnerTransportError(
+        `gog-runner did not respond within ${deadlineMs}ms (${endpoint}) \u2014 the Fly backend may be cold or wedged`,
+        "transport-retryable"
+      );
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    const detail = body && typeof body.error === "string" ? body.stderr && body.stderr.trim() && body.stderr.trim() !== body.error.trim() ? `${body.error}
 ${body.stderr}` : body.error : "";
-      if (res.status === RUNNER_GOG_FAILED) {
-        throw new Error(detail || "gog failed on the runner (no detail supplied)");
-      }
-      if (res.status === RUNNER_DRAINING || body?.retryable === true) {
-        throw new Error(
-          `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`
-        );
-      }
-      if (detail) {
-        throw new Error(detail);
-      }
-      throw new Error(
-        `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`
+    if (res.status === RUNNER_GOG_FAILED) {
+      throw new GogFailedError(
+        detail || "gog failed on the runner (no detail supplied)",
+        typeof body?.stderr === "string" ? body.stderr : ""
       );
     }
-    const { stdout } = await res.json();
-    return stdout;
-  };
+    if (res.status === RUNNER_BAD_KEY) {
+      logAuthTransition("runner.auth-failed", {
+        service: gogTarget(args).service,
+        endpoint,
+        reason: "the gog-runner rejected the connector\u2019s bearer token, so gog never ran and no Google credential was read; GOG_RUNNER_KEY does not match the Fly app\u2019s RUNNER_KEY"
+      });
+      throw new RunnerTransportError(
+        "gog-runner rejected the connector's bearer token, so the request never reached gog and no Google credential was involved. The Worker secret GOG_RUNNER_KEY no longer matches RUNNER_KEY on the Fly app; set them to the same value (wrangler secret put GOG_RUNNER_KEY / fly secrets set RUNNER_KEY) and retry.",
+        "transport-auth",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_BAD_REQUEST) {
+      throw new RunnerTransportError(
+        detail || "gog-runner rejected the request (no detail supplied)",
+        "transport-request",
+        res.status
+      );
+    }
+    if (res.status === RUNNER_DRAINING || body?.retryable === true) {
+      throw new RunnerTransportError(
+        `gog-runner is restarting; retry this call.${detail ? ` ${detail}` : ""}`,
+        "transport-retryable",
+        res.status
+      );
+    }
+    if (detail) {
+      throw new Error(detail);
+    }
+    throw new RunnerTransportError(
+      `gog-runner HTTP ${res.status}: the response did not come from the runner, so the request never reached gog. The backend Machine was most likely starting or shutting down \u2014 this is transient, retry the same call.`,
+      "transport-retryable",
+      res.status
+    );
+  }
+  const { stdout } = await res.json();
+  return stdout;
 }
 
 // ../gogcli-mcp/src/remote-runner.ts
@@ -32292,7 +32670,7 @@ function registerExtraDocsTools(server) {
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       text: external_exports.string().optional().describe("Text content to append"),
-      file: external_exports.string().optional().describe('Path to a text file to append (use "-" for stdin)'),
+      file: external_exports.string().optional().describe(`Path to a text file to append, read on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       markdown: external_exports.boolean().optional().describe("Convert markdown to Google Docs formatting (headings, bold, lists, etc.). See the tool description for known upstream limitations around tables."),
       tab: external_exports.string().optional().describe("Target tab title or ID (for multi-tab docs)"),
       account: accountParam
@@ -32374,19 +32752,23 @@ function registerExtraDocsTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_docs_comments_list", {
-    description: "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments.",
+    description: "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments. Set locate=true (or pass tab) to attach each comment's tab and Docs index ranges as location.matches[] plus location.orphaned \u2014 that costs one extra document fetch, but only one for the whole listing, where gog_docs_comments_locate costs one per comment. Either flag additionally requires the Docs scope; the plain listing needs only Drive. matches[] always spans every tab, so a quote appearing in two tabs is visible as an ambiguity rather than silently resolved. tab keeps only comments with a match in that tab, which drops orphaned comments and comments that quote nothing.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       includeResolved: external_exports.boolean().optional().describe("Include resolved comments (default: false, open only)"),
       since: external_exports.string().optional().describe("Only return comments modified at or after this RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z)"),
+      locate: external_exports.boolean().optional().describe("Attach each comment's tab and Docs index ranges (location.matches[] + location.orphaned) using one extra document fetch shared across the whole listing"),
+      tab: external_exports.string().optional().describe("Only return comments whose quoted text resolves inside this tab (title or ID). Implies locate, and drops orphaned and unquoted comments."),
       ...paginationParams,
       account: accountParam
     }
-  }, async ({ docId, includeResolved, since, max, page, all, account }) => {
+  }, async ({ docId, includeResolved, since, locate, tab, max, page, all, account }) => {
     const args = ["docs", "comments", "list", docId];
     if (includeResolved) args.push("--include-resolved");
     if (since) args.push(`--since=${since}`);
+    if (locate) args.push("--locate");
+    if (tab) args.push(`--tab=${tab}`);
     pushPaginationFlags(args, { max, page, all });
     return runOrDiagnose(args, { account });
   });
@@ -33119,7 +33501,7 @@ function registerExtraDocsTools(server) {
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       text: external_exports.string().optional().describe("Footnote text"),
-      file: external_exports.string().optional().describe('Read footnote text from a file ("-" for stdin)'),
+      file: external_exports.string().optional().describe(`Read footnote text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       index: external_exports.number().int().optional().describe("Character index to place the reference mark at (1 = beginning). Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Target end-of-doc/tab (mutually exclusive with index and at)"),
       at: external_exports.string().optional().describe("Anchor by literal text and place the reference mark at the start of the matched range"),
@@ -33238,7 +33620,7 @@ function registerExtraDocsTools(server) {
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       text: external_exports.string().optional().describe("Initial header text"),
-      file: external_exports.string().optional().describe('Read initial header text from a file ("-" for stdin)'),
+      file: external_exports.string().optional().describe(`Read initial header text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       index: external_exports.number().int().optional().describe("Character index identifying the section the header belongs to (1 = beginning). Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Target end-of-doc/tab (mutually exclusive with index and at)"),
       at: external_exports.string().optional().describe("Anchor by literal text and target the section at the start of the matched range"),
@@ -33292,7 +33674,7 @@ function registerExtraDocsTools(server) {
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       text: external_exports.string().optional().describe("Initial footer text"),
-      file: external_exports.string().optional().describe('Read initial footer text from a file ("-" for stdin)'),
+      file: external_exports.string().optional().describe(`Read initial footer text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out.`),
       index: external_exports.number().int().optional().describe("Character index identifying the section the footer belongs to (1 = beginning). Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Target end-of-doc/tab (mutually exclusive with index and at)"),
       at: external_exports.string().optional().describe("Anchor by literal text and target the section at the start of the matched range"),

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -165,7 +165,7 @@
     },
     {
       "name": "gog_docs_comments_list",
-      "description": "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments."
+      "description": "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments, or locate/tab to attach each comment's tab and index ranges in one extra fetch."
     },
     {
       "name": "gog_docs_comments_get",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-docs",
   "description": "Extended Google Docs MCP server via gogcli — all base tools plus full Docs support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

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

package/src/tools/docs-extra.ts

@@ -284,7 +284,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       text: z.string().optional().describe('Text content to append'),
-      file: z.string().optional().describe('Path to a text file to append (use "-" for stdin)'),
+      file: z.string().optional().describe('Path to a text file to append, read on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       markdown: z.boolean().optional().describe('Convert markdown to Google Docs formatting (headings, bold, lists, etc.). See the tool description for known upstream limitations around tables.'),
       tab: z.string().optional().describe('Target tab title or ID (for multi-tab docs)'),
       account: accountParam,
@@ -372,19 +372,28 @@ export function registerExtraDocsTools(server: McpServer): void {
   // Comment-thread tools
   server.registerTool('gog_docs_comments_list', {
     description:
-      'List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments.',
+      'List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments. ' +
+      'Set locate=true (or pass tab) to attach each comment\'s tab and Docs index ranges as location.matches[] plus location.orphaned — ' +
+      'that costs one extra document fetch, but only one for the whole listing, where gog_docs_comments_locate costs one per comment. ' +
+      'Either flag additionally requires the Docs scope; the plain listing needs only Drive. ' +
+      'matches[] always spans every tab, so a quote appearing in two tabs is visible as an ambiguity rather than silently resolved. ' +
+      'tab keeps only comments with a match in that tab, which drops orphaned comments and comments that quote nothing.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       includeResolved: z.boolean().optional().describe('Include resolved comments (default: false, open only)'),
       since: z.string().optional().describe('Only return comments modified at or after this RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z)'),
+      locate: z.boolean().optional().describe('Attach each comment\'s tab and Docs index ranges (location.matches[] + location.orphaned) using one extra document fetch shared across the whole listing'),
+      tab: z.string().optional().describe('Only return comments whose quoted text resolves inside this tab (title or ID). Implies locate, and drops orphaned and unquoted comments.'),
       ...paginationParams,
       account: accountParam,
     },
-  }, async ({ docId, includeResolved, since, max, page, all, account }) => {
+  }, async ({ docId, includeResolved, since, locate, tab, max, page, all, account }) => {
     const args = ['docs', 'comments', 'list', docId];
     if (includeResolved) args.push('--include-resolved');
     if (since) args.push(`--since=${since}`);
+    if (locate) args.push('--locate');
+    if (tab) args.push(`--tab=${tab}`);
     pushPaginationFlags(args, { max, page, all });
     return runOrDiagnose(args, { account });
   });
@@ -1177,7 +1186,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       text: z.string().optional().describe('Footnote text'),
-      file: z.string().optional().describe('Read footnote text from a file ("-" for stdin)'),
+      file: z.string().optional().describe('Read footnote text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       index: z.number().int().optional().describe('Character index to place the reference mark at (1 = beginning). Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Target end-of-doc/tab (mutually exclusive with index and at)'),
       at: z.string().optional().describe('Anchor by literal text and place the reference mark at the start of the matched range'),
@@ -1304,7 +1313,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       text: z.string().optional().describe('Initial header text'),
-      file: z.string().optional().describe('Read initial header text from a file ("-" for stdin)'),
+      file: z.string().optional().describe('Read initial header text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       index: z.number().int().optional().describe('Character index identifying the section the header belongs to (1 = beginning). Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Target end-of-doc/tab (mutually exclusive with index and at)'),
       at: z.string().optional().describe('Anchor by literal text and target the section at the start of the matched range'),
@@ -1361,7 +1370,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       text: z.string().optional().describe('Initial footer text'),
-      file: z.string().optional().describe('Read initial footer text from a file ("-" for stdin)'),
+      file: z.string().optional().describe('Read initial footer text from a file on the gog server. gog also accepts "-" for stdin, but this server never writes to gog\'s stdin, so "-" would hang until the call times out.'),
       index: z.number().int().optional().describe('Character index identifying the section the footer belongs to (1 = beginning). Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Target end-of-doc/tab (mutually exclusive with index and at)'),
       at: z.string().optional().describe('Anchor by literal text and target the section at the start of the matched range'),

package/tests/tools/docs-extra.test.ts

@@ -503,6 +503,82 @@ describe('gog_docs_comments_list', () => {
       { account: undefined },
     );
   });
+
+  // gog 0.35.0 (openclaw/gogcli#965) adds --locate/--tab, which share ONE
+  // documents.get(includeTabsContent=true) across every comment on the page.
+  // The pre-0.35.0 way to answer "which tab is this comment in?" was one
+  // `docs comments locate` per comment — 30 fetches for a 30-comment doc.
+  it('includes --locate when requested', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', locate: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'comments', 'list', 'abc', '--locate'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --locate when false', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', locate: false });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+  });
+
+  it('includes --tab, which gog treats as implying --locate', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', tab: 'Notes' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'comments', 'list', 'abc', '--tab=Notes'],
+      { account: undefined },
+    );
+  });
+
+  // gog rejects an explicitly empty --tab (`--tab requires a non-empty tab
+  // title or ID`), so an empty string must never reach the arg array.
+  it('never emits an empty --tab', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', { docId: 'abc', tab: '' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+  });
+
+  it('combines --locate and --tab with the existing filters and pagination', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_docs_comments_list', {
+      docId: 'abc', includeResolved: true, since: '2026-06-01T00:00:00Z',
+      locate: true, tab: 'Notes', max: 10, page: 'tok', all: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'docs', 'comments', 'list', 'abc',
+        '--include-resolved',
+        '--since=2026-06-01T00:00:00Z',
+        '--locate',
+        '--tab=Notes',
+        '--max=10', '--page=tok', '--all',
+      ],
+      { account: undefined },
+    );
+  });
+
+  it('description states the extra fetch, the Docs scope, and that --tab drops orphans', async () => {
+    const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    const configs = new Map<string, { description?: string }>();
+    vi.spyOn(server, 'registerTool').mockImplementation((name, config) => {
+      configs.set(name, config as { description?: string });
+      return undefined as never;
+    });
+    const { registerExtraDocsTools } = await import('../../src/tools/docs-extra.js');
+    registerExtraDocsTools(server);
+    const desc = configs.get('gog_docs_comments_list')?.description ?? '';
+    expect(desc).toMatch(/one extra/i);
+    expect(desc).toMatch(/Docs scope/);
+    expect(desc).toMatch(/orphan/i);
+  });
 });
 
 describe('gog_docs_table_column_width', () => {
@@ -2156,3 +2232,35 @@ describe('gog_docs_format spacingMode', () => {
     );
   });
 });
+
+// Same trap the gmail package documents: gog resolves a "-" path through
+// io.ReadAll(stdinReader(ctx)) (docs_helpers.go resolveContentInput:26 and
+// readTextInput:83 at upstream-v0.35.0 — os.Stdin, unaffected by --no-input),
+// but runner.ts spawns with default stdio and never writes to or ends
+// child.stdin, so the call blocks until the 30s timeout fires. Reproduced
+// against a live gog v0.35.0: the child was still running with zero output
+// after 5s. These descriptions must warn, not offer.
+describe('server-side file params never advertise stdin as usable', () => {
+  const STDIN_PARAMS: Array<[tool: string, param: string]> = [
+    ['gog_docs_append', 'file'],
+    ['gog_docs_insert_footnote', 'file'],
+    ['gog_docs_header_create', 'file'],
+    ['gog_docs_footer_create', 'file'],
+  ];
+
+  it.each(STDIN_PARAMS)('%s.%s warns that stdin hangs instead of offering it', async (tool, param) => {
+    const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    const schemas = new Map<string, Record<string, { description?: string }>>();
+    vi.spyOn(server, 'registerTool').mockImplementation((name, config) => {
+      schemas.set(name, (config as { inputSchema: Record<string, { description?: string }> }).inputSchema);
+      return undefined as never;
+    });
+    registerExtraDocsTools(server);
+    const desc = schemas.get(tool)?.[param]?.description ?? '';
+    expect(desc).not.toBe('');
+    expect(desc).not.toMatch(/(?:use|or)\s+"?-"?\s*(?:for|to read)/i);
+    expect(desc).toMatch(/stdin/i);
+    expect(desc).toMatch(/hang|never writes/i);
+  });
+});