gogcli-mcp-gmail 2.21.0 → 2.22.0

package/dist/index.js

@@ -31145,6 +31145,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) {
@@ -31325,7 +31340,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);
   }
 }
 
@@ -31416,6 +31435,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 () => {
@@ -31861,7 +31896,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";
@@ -31888,22 +31956,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 {
@@ -31918,79 +32037,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
@@ -32047,6 +32425,7 @@ function trimThread(result, latestN, snippetsOnly) {
     return result;
   }
 }
+var GOG_DEFAULT_INLINE_MAX_BYTES = 3145728;
 var MIME_BY_EXT = {
   pdf: "application/pdf",
   png: "image/png",
@@ -32108,13 +32487,29 @@ async function resolveBySize(messageId, sizeBytes, account) {
     return void 0;
   }
 }
+async function resolveByIndex(messageId, index, account) {
+  try {
+    const parsed = JSON.parse(
+      await run(["gmail", "get", messageId, "--use-indexed-attachment-ids"], { account })
+    );
+    const attachments = parsed.attachments;
+    if (!attachments) return void 0;
+    const declared = attachments.find((a) => a.attachmentIndex === index);
+    if (declared) return declared;
+    if (attachments.every((a) => a.attachmentIndex === void 0)) return attachments[index];
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
 function defaultOutPath(messageId, filename) {
   return `/tmp/gog-attachments/${messageId}/${filename}`;
 }
 function sanitizeAttachmentError(err, messageId, attachmentId) {
   let msg = err instanceof Error ? err.message : String(err);
   msg = msg.replace(/^Command failed:.*(\n|$)/, "");
-  msg = msg.split(attachmentId).join("<attachment>").split(messageId).join("<message>");
+  if (attachmentId) msg = msg.split(attachmentId).join("<attachment>");
+  msg = msg.split(messageId).join("<message>");
   return msg.trim() || "the download failed on the server";
 }
 function inlineImageResult(summary, base643, mimeType) {
@@ -32178,21 +32573,35 @@ function registerExtraGmailTools(server) {
     return runOrDiagnose(args, { account, lossless: true });
   });
   server.registerTool("gog_gmail_attachment", {
-    description: `Download a Gmail attachment and deliver its contents so you can actually read them. The real filename and MIME type are resolved from the message part metadata, so the saved file and response are named correctly (e.g. Guest_Copy.pdf), never a generic *.bin. deliver="auto" (default) is transport-aware: images always come back as a native image block; anything else is delivered by the channel that works on your transport \u2014 a readable server-side file PATH on local (stdio) clients that share the filesystem, or a Google Drive link on the remote connector (whose backend filesystem you can't read, and which rejects inline PDF/binary blobs). deliver="inline" forces the bytes inline as an image or embedded resource blob (use only if your client consumes resource blobs; errors if over gog's 3 MiB cap). deliver="drive" always uploads to Drive; deliver="off" writes the file server-side and returns {path, fileName, mimeType, bytes}. Drive delivery creates a file in your Drive (blocked when GOG_READONLY is set).`,
+    description: `Download a Gmail attachment and deliver its contents so you can actually read them. Identify the attachment by attachmentIndex (preferred: the 0-based position from a listing fetched with useIndexedAttachmentIds \u2014 stable, and it resolves the real name before the download) or by the legacy opaque attachmentId. The real filename and MIME type are resolved from the message part metadata, so the saved file and response are named correctly (e.g. Guest_Copy.pdf), never a generic *.bin. deliver="auto" (default) is transport-aware: images always come back as a native image block; anything else is delivered by the channel that works on your transport \u2014 a readable server-side file PATH on local (stdio) clients that share the filesystem, or a Google Drive link on the remote connector (whose backend filesystem you can't read, and which rejects inline PDF/binary blobs). deliver="inline" forces the bytes inline as an image or embedded resource blob (use only if your client consumes resource blobs; errors if over gog's 3 MiB cap). deliver="drive" always uploads to Drive; deliver="off" writes the file server-side and returns {path, fileName, mimeType, bytes}. Drive delivery creates a file in your Drive (blocked when GOG_READONLY is set).`,
     inputSchema: {
       messageId: external_exports.string().describe("Gmail message ID"),
-      attachmentId: external_exports.string().describe("Attachment ID (from the message payload)"),
+      attachmentId: external_exports.string().optional().describe("The opaque attachment ID from a listing. Legacy addressing: Gmail re-issues a DIFFERENT id for the same part on every API call, so an id copied from an older listing can be stale. Prefer attachmentIndex. Exactly one of attachmentId / attachmentIndex is required."),
+      attachmentIndex: external_exports.number().int().nonnegative().optional().describe("The attachment's 0-based position in its message \u2014 the `attachmentIndex` field of a listing fetched with useIndexedAttachmentIds. Stable (a message's MIME structure does not change), so this is the reliable way to name an attachment. Exactly one of attachmentId / attachmentIndex is required. NOTE: it is per-MESSAGE \u2014 in gog_gmail_thread_attachments the array is flattened across the whole thread, so use each row's messageId + attachmentIndex, never its position in that flat list."),
+      inlineMaxBytes: external_exports.number().int().nonnegative().optional().describe("Byte ceiling under which gog embeds the attachment bytes rather than only writing the file. Defaults to gog's own 3145728, which this server pins explicitly on every call so an ambient GOG_GMAIL_INLINE_MAX_BYTES cannot change the answer. Raise it to inline something larger, lower it to force the file/Drive path."),
       deliver: external_exports.enum(["auto", "inline", "drive", "off"]).optional().describe("How to return the contents: auto (image inline; else a local file path or a Drive link, per transport), inline (force bytes as image/resource blob), drive (always a Drive link), or off (server-side download only). Default: auto."),
       out: external_exports.string().optional().describe("Server-side path where gog writes the file. NOTE: this resolves on the CONNECTOR/gog server's filesystem, not your machine \u2014 on the remote connector it is ignored (you can't read it; you get a Drive link instead). Locally it is honored. Omit it to use an ephemeral temp path."),
       name: external_exports.string().optional().describe("Filename override. Defaults to the attachment's real filename from the message metadata; pass this to skip that lookup or force a name."),
       driveFolder: external_exports.string().optional().describe("Destination Google Drive folder ID for the uploaded copy (drive/auto delivery on the remote connector, or oversized attachments)."),
       account: accountParam
     }
-  }, async ({ messageId, attachmentId, deliver = "auto", out, name, driveFolder, account }) => {
+  }, async ({ messageId, attachmentId, attachmentIndex, deliver = "auto", out, name, inlineMaxBytes, driveFolder, account }) => {
+    if (attachmentId === void 0 === (attachmentIndex === void 0)) {
+      return errorResult(
+        "Pass exactly one of attachmentId or attachmentIndex. Prefer attachmentIndex \u2014 the 0-based `attachmentIndex` from a listing fetched with useIndexedAttachmentIds \u2014 because Gmail's opaque attachmentId is not stable across API calls and a copied one may no longer resolve."
+      );
+    }
+    const indexed = attachmentIndex !== void 0;
+    const attachmentRef = indexed ? String(attachmentIndex) : attachmentId;
     const remote = runExecutor.getStore() !== void 0;
     try {
       let filename = name ? sanitizeFilename(name) : void 0;
       let mimeType = filename ? MIME_BY_EXT[extOf(filename)] : void 0;
+      if (indexed && !filename) {
+        const meta3 = await resolveByIndex(messageId, attachmentIndex, account);
+        if (meta3?.filename) filename = sanitizeFilename(meta3.filename);
+        if (meta3?.mimeType) mimeType = meta3.mimeType;
+      }
       const notes = [];
       let outPath = out;
       if (out && remote) {
@@ -32207,12 +32616,16 @@ function registerExtraGmailTools(server) {
       if (!mimeType && (deliver === "auto" || deliver === "inline")) {
         needInline = true;
       }
-      const args = ["gmail", "attachment", messageId, attachmentId];
+      const args = ["gmail", "attachment", messageId, attachmentRef];
+      args.push(indexed ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
       if (needInline) args.push("--inline");
+      args.push(`--inline-max-bytes=${inlineMaxBytes ?? GOG_DEFAULT_INLINE_MAX_BYTES}`);
       args.push(`--out=${outPath}`, `--name=${filename ?? "attachment"}`);
       const info = JSON.parse(await run(args, { account }));
       const path = info.path ?? outPath;
-      if (!filename) {
+      if (!filename && info.filename) filename = sanitizeFilename(info.filename);
+      if (!mimeType && info.mimeType) mimeType = info.mimeType;
+      if (!filename && !indexed) {
         const meta3 = await resolveBySize(messageId, info.bytes, account);
         if (meta3?.filename) filename = sanitizeFilename(meta3.filename);
         if (!mimeType && meta3?.mimeType) mimeType = meta3.mimeType;
@@ -32236,7 +32649,7 @@ function registerExtraGmailTools(server) {
           return withNote(isImage ? inlineImageResult(summary, info.contentBase64, mimeType) : inlineResourceResult(messageId, filename, summary, info.contentBase64, mimeType), notes);
         }
         return errorResult(
-          `Attachment is too large to return inline (${info.reason ?? "exceeds gog's 3 MiB inline limit"}). Use deliver="auto" or deliver="drive" to receive it as a Google Drive link.`
+          `Attachment is too large to return inline (${info.reason ?? "exceeds gog's inline size limit, 3 MiB by default \u2014 raise inlineMaxBytes"}). Use deliver="auto" or deliver="drive" to receive it as a Google Drive link.`
         );
       }
       if (isImage && info.contentBase64) {
@@ -32378,15 +32791,17 @@ function registerExtraGmailTools(server) {
       sanitizeContent: external_exports.boolean().optional().describe("Strip HTML, remove URLs, omit raw payloads from JSON (largest payload-size reduction)"),
       latestN: external_exports.number().int().positive().optional().describe("Return only the most recent N messages in the thread (wrapper-side trim; avoids overflowing context on long threads)"),
       snippetsOnly: external_exports.boolean().optional().describe("Reduce each message to its id, labels, snippet, and key headers (From/To/Cc/Subject/Date), dropping full bodies"),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` within its message instead of an opaque `attachmentId`. The index is stable across calls (a message's MIME structure does not change) while the id is not, so this is what you want before calling gog_gmail_attachment."),
       outDir: external_exports.string().optional().describe("Directory to write attachments to (default: current directory)"),
       account: accountParam
     }
-  }, async ({ threadId, download, full, sanitizeContent, latestN, snippetsOnly, outDir, account }) => {
+  }, async ({ threadId, download, full, sanitizeContent, latestN, snippetsOnly, useIndexedAttachmentIds, outDir, account }) => {
     const args = ["gmail", "thread", "get", threadId];
     if (download) args.push("--download");
     if (full) args.push("--full");
     if (sanitizeContent) args.push("--sanitize-content");
     if (outDir) args.push(`--out-dir=${outDir}`);
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     const result = await runOrDiagnose(args, { account });
     if (latestN === void 0 && !snippetsOnly) return result;
     return trimThread(result, latestN, snippetsOnly);
@@ -32412,13 +32827,15 @@ function registerExtraGmailTools(server) {
     inputSchema: {
       threadId: external_exports.string().describe("Gmail thread ID"),
       download: external_exports.boolean().optional().describe("Download all attachments to the SERVER filesystem (see the note above; on the remote connector the files aren't reachable \u2014 fetch individually with gog_gmail_attachment instead)."),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` instead of an opaque `attachmentId`. Set this before calling gog_gmail_attachment: the index is stable across calls, the id is not. The index counts WITHIN each message, and this listing flattens every message's attachments into one array \u2014 so pair each row's `messageId` with its own `attachmentIndex`; a row's position in the flat array is NOT the index."),
       outDir: external_exports.string().optional().describe("Directory to write attachments to, resolved on the gog SERVER's filesystem (default: current directory). Not your local machine on the remote connector."),
       account: accountParam
     }
-  }, async ({ threadId, download, outDir, account }) => {
+  }, async ({ threadId, download, useIndexedAttachmentIds, outDir, account }) => {
     const args = ["gmail", "thread", "attachments", threadId];
     if (download) args.push("--download");
     if (outDir) args.push(`--out-dir=${outDir}`);
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_labels_list", {
@@ -32507,11 +32924,13 @@ function registerExtraGmailTools(server) {
     inputSchema: {
       draftId: external_exports.string().describe("Draft ID"),
       download: external_exports.boolean().optional().describe("Download draft attachments"),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` instead of an opaque `attachmentId` (stable across calls, unlike the id)."),
       account: accountParam
     }
-  }, async ({ draftId, download, account }) => {
+  }, async ({ draftId, download, useIndexedAttachmentIds, account }) => {
     const args = ["gmail", "drafts", "get", draftId];
     if (download) args.push("--download");
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     return runOrDiagnose(args, { account });
   });
   const draftWriteSchema = {
@@ -32521,7 +32940,7 @@ function registerExtraGmailTools(server) {
     subject: external_exports.string().describe("Subject"),
     body: external_exports.string().describe("Body (plain text). Any size \u2014 a large body is written to a temp file on the gog server rather than inlined into the command line. Note gog strips trailing newlines from a file-delivered body."),
     bodyHtml: external_exports.string().optional().describe("Body (HTML; optional). Pass the HTML itself at any size \u2014 a large body is written to a temp file on the gog server rather than inlined into the command line. Mutually exclusive with bodyHtmlFile."),
-    bodyHtmlFile: external_exports.string().optional().describe('Path to an HTML file that ALREADY EXISTS on the gog server to use as the HTML body, or "-" to read from stdin. Mutually exclusive with bodyHtml \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.'),
+    bodyHtmlFile: external_exports.string().optional().describe(`Path to an HTML file that ALREADY EXISTS on the gog server to use as the HTML body. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out. Mutually exclusive with bodyHtml \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.`),
     replyToMessageId: external_exports.string().optional().describe("Reply to a specific Gmail MESSAGE id \u2014 the short hex `id` field from gog_gmail_get / _search / _thread_get (e.g. 19e7593d77fd9636), NOT a thread id and NOT the RFC822 `<\u2026@host>` Message-Id header. Anchors In-Reply-To/References to that exact message. To reply to a thread when you don't know the latest message, use replyToThreadId instead. If both are given, replyToMessageId wins."),
     replyToThreadId: external_exports.string().optional().describe(`Reply to a Gmail THREAD id \u2014 passed to gog as --thread-id, which threads the draft using the thread's latest-message headers (In-Reply-To/References). This is what "reply to this thread" almost always means. Mutually exclusive with replyToMessageId (which wins if both are set). Thread ids and message ids are both 16-hex strings and easy to confuse \u2014 use this param, not replyToMessageId, when the id came from a thread.`),
     replyTo: external_exports.string().optional().describe("Reply-To header address"),
@@ -32529,6 +32948,7 @@ function registerExtraGmailTools(server) {
     replyAll: external_exports.boolean().optional().describe("Auto-populate recipients from the original message (reply-all), inferring To/Cc from it. Requires replyToMessageId or replyToThreadId. Explicit to/cc/bcc still apply on top; omitRecipients still suppresses them."),
     attach: external_exports.array(external_exports.string()).optional().describe("Local file paths to attach (repeatable). Read on the gog server, base64-encoded with a MIME type inferred from the extension. The JSON result echoes attached filenames and byte sizes \u2014 check it to confirm the files were found and embedded. On gog_gmail_drafts_update, supplying attach REPLACES the draft's existing attachments; omitting it preserves them (use clearAttachments to remove all)."),
     from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
+    autoFromAddressedAlias: external_exports.boolean().optional().describe("When from is omitted, send from the verified send-as alias the original message was addressed TO, instead of the account's primary address \u2014 so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set."),
     omitRecipients: external_exports.boolean().optional().describe("Create the draft with no recipients even if to/cc/bcc are supplied \u2014 an accidental-send guard. Populate recipients in a later update before sending."),
     returnFull: external_exports.boolean().optional().describe("After writing, re-fetch and return the full stored draft (subject, body, recipients) instead of just the write acknowledgement. Costs one extra read."),
     account: accountParam
@@ -32551,6 +32971,7 @@ function registerExtraGmailTools(server) {
     if (f.quote) args.push("--quote");
     if (f.attach) for (const path of f.attach) args.push(`--attach=${path}`);
     if (f.from) args.push(`--from=${f.from}`);
+    args.push(f.autoFromAddressedAlias ? "--auto-from-addressed-alias" : "--auto-from-addressed-alias=false");
   }
   async function writeDraft(args, account, returnFull, knownDraftId) {
     const result = await runOrDiagnose(args, { account });
@@ -32563,7 +32984,7 @@ function registerExtraGmailTools(server) {
     }
     const draftId = knownDraftId ?? parsed.draftId;
     if (!draftId) return result;
-    return runOrDiagnose(["gmail", "drafts", "get", draftId], { account });
+    return runOrDiagnose(["gmail", "drafts", "get", draftId, "--use-indexed-attachment-ids=false"], { account });
   }
   server.registerTool("gog_gmail_drafts_create", {
     description: "Create a new Gmail draft. Recipients (to/cc/bcc) are optional; omit them (or set omitRecipients) to create a recipient-less draft as an accidental-send guard. For replies, prefer replyToThreadId (anchors to the thread's latest message) or replyToMessageId (a specific message) \u2014 don't pass a thread id into replyToMessageId, which mis-threads silently.",
@@ -32574,17 +32995,19 @@ function registerExtraGmailTools(server) {
     return writeDraft(args, account, returnFull);
   });
   server.registerTool("gog_gmail_drafts_update", {
-    description: "Update an existing Gmail draft. For replies, prefer replyToThreadId (threads off the thread's latest message) or replyToMessageId (a specific message) over passing a thread id into replyToMessageId. Attachment semantics: supplying attach REPLACES the draft's existing attachments; omitting it preserves them; set clearAttachments to remove all.",
+    description: "Update an existing Gmail draft. For replies, prefer replyToThreadId (threads off the thread's latest message) or replyToMessageId (a specific message) over passing a thread id into replyToMessageId. An update preserves the draft's existing reply context (In-Reply-To/References) and its threadId; it never invents reply headers for a draft that is not a reply. The result reports the effective inReplyTo/references so you can verify threading without a raw-header fetch. Attachment semantics: supplying attach REPLACES the draft's existing attachments; omitting it preserves them; set clearAttachments to remove all.",
     annotations: { destructiveHint: true },
     inputSchema: {
       draftId: external_exports.string().describe("Draft ID"),
       ...draftWriteSchema,
-      clearAttachments: external_exports.boolean().optional().describe("Remove all attachments from the draft. By default, omitting attach preserves the draft's existing attachments; this intentionally clears them. Ignored if attach is also supplied (attach replaces).")
+      clearAttachments: external_exports.boolean().optional().describe("Remove all attachments from the draft. By default, omitting attach preserves the draft's existing attachments; this intentionally clears them. Ignored if attach is also supplied (attach replaces)."),
+      clearReplyContext: external_exports.boolean().optional().describe("Strip In-Reply-To/References from the draft, turning a reply back into a standalone message while keeping the same draft id and threadId. Use this to repair a mis-threaded draft in place instead of deleting and recreating it. Mutually exclusive with replyToMessageId, replyToThreadId and quote \u2014 gog rejects the call if any of them is combined with this.")
     }
-  }, async ({ draftId, account, returnFull, clearAttachments, ...flags }) => {
+  }, async ({ draftId, account, returnFull, clearAttachments, clearReplyContext, ...flags }) => {
     const args = ["gmail", "drafts", "update", draftId];
     appendDraftFlags(args, flags);
     if (clearAttachments) args.push("--clear-attachments");
+    if (clearReplyContext) args.push("--clear-reply-context");
     return writeDraft(args, account, returnFull, draftId);
   });
   server.registerTool("gog_gmail_drafts_delete", {
@@ -32610,6 +33033,24 @@ function registerExtraGmailTools(server) {
   }, async ({ draftId, account }) => {
     return runOrDiagnose(["gmail", "drafts", "send", draftId], { account });
   });
+  server.registerTool("gog_gmail_import", {
+    description: "Import an existing RFC822/EML message INTO the mailbox. This is Gmail's import path, not a send: nothing leaves the account, and the message keeps its own From/Date/Message-Id headers so it files where it belongs chronologically. Use it to restore an exported message or to file a .eml under a label; to actually send mail use gog_gmail_send, and to stage one use gog_gmail_drafts_create. The file is read on the gog SERVER, not your machine.",
+    inputSchema: {
+      file: external_exports.string().describe(`Path to an RFC822/EML file that ALREADY EXISTS 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.`),
+      labels: external_exports.array(external_exports.string()).optional().describe(`Labels to apply to the imported message (repeatable). Each may be a label ID or a label name \u2014 names are resolved server-side. A name containing a COMMA cannot be passed here: gog declares --label as a Kong slice with no separator override, so Kong splits each value on commas and "Clients, Inc" is looked up as two labels ("Clients" and "Inc") and fails. Use that label's ID instead \u2014 ids never contain a comma; gog_gmail_labels_list gives you one.`),
+      internalDateSource: external_exports.enum(["dateHeader", "receivedTime"]).optional().describe("Which clock sets Gmail's internal date: dateHeader (gog default \u2014 the message's own Date header, so it sorts into the mailbox at its original time) or receivedTime (now)."),
+      neverMarkSpam: external_exports.boolean().optional().describe("Never classify the imported message as spam."),
+      processForCalendar: external_exports.boolean().optional().describe("Process calendar invitations inside the imported message \u2014 this can ADD EVENTS to your calendar."),
+      account: accountParam
+    }
+  }, async ({ file: file2, labels, internalDateSource, neverMarkSpam, processForCalendar, account }) => {
+    const args = ["gmail", "import", file2];
+    if (labels) for (const label of labels) args.push(`--label=${label}`);
+    if (internalDateSource) args.push(`--internal-date-source=${internalDateSource}`);
+    if (neverMarkSpam) args.push("--never-mark-spam");
+    if (processForCalendar) args.push("--process-for-calendar");
+    return runOrDiagnose(args, { account });
+  });
   server.registerTool("gog_gmail_forward", {
     description: "Forward an existing Gmail message to new recipients.",
     annotations: { destructiveHint: true },
@@ -32636,7 +33077,7 @@ function registerExtraGmailTools(server) {
     messageId: external_exports.string().describe("Gmail message ID to reply to \u2014 the short hex `id` from gog_gmail_get / _search / _messages_search (NOT the threadId, NOT the RFC822 `<\u2026@host>` Message-Id header)."),
     body: external_exports.string().optional().describe("Reply body (plain text; required unless bodyHtml or bodyHtmlFile is set). Any size \u2014 a large body is written to a temp file on the gog server rather than inlined into the command line. Note gog strips trailing newlines from a file-delivered body."),
     bodyHtml: external_exports.string().optional().describe("Reply body (HTML; optional). Pass the HTML itself at any size \u2014 a large body is written to a temp file on the gog server rather than inlined into the command line. Mutually exclusive with bodyHtmlFile."),
-    bodyHtmlFile: external_exports.string().optional().describe('Path to an HTML file that ALREADY EXISTS on the gog server for the reply body, or "-" for stdin. Mutually exclusive with bodyHtml \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.'),
+    bodyHtmlFile: external_exports.string().optional().describe(`Path to an HTML file that ALREADY EXISTS on the gog server for the reply body. gog also accepts "-" for stdin, but this server never writes to gog's stdin, so "-" would hang until the call times out. Mutually exclusive with bodyHtml \u2014 supplying both is rejected. You rarely need this: bodyHtml handles large bodies on its own.`),
     to: external_exports.array(external_exports.string()).optional().describe("Add or move recipients to To (repeatable). Added on top of the recipients inherited from the original message."),
     cc: external_exports.array(external_exports.string()).optional().describe("Add or move recipients to Cc (repeatable)"),
     bcc: external_exports.array(external_exports.string()).optional().describe("Add or move recipients to Bcc (repeatable)"),
@@ -32645,6 +33086,7 @@ function registerExtraGmailTools(server) {
     noQuote: external_exports.boolean().optional().describe("Do not include the original message quoted below the reply (default: the original is quoted)"),
     attach: external_exports.array(external_exports.string()).optional().describe("Local file paths to attach (repeatable). Read on the gog server, base64-encoded with a MIME type inferred from the extension."),
     from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
+    autoFromAddressedAlias: external_exports.boolean().optional().describe("When from is omitted, send from the verified send-as alias the original message was addressed TO, instead of the account's primary address \u2014 so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set."),
     signature: external_exports.boolean().optional().describe("Append the Gmail signature from the active send-as address"),
     signatureFrom: external_exports.string().optional().describe("Append the Gmail signature from this send-as email address"),
     signatureFile: external_exports.string().optional().describe("Append a local signature file (plain text or HTML), read on the gog server"),
@@ -32666,6 +33108,7 @@ function registerExtraGmailTools(server) {
     if (f.signature) args.push("--signature");
     if (f.signatureFrom) args.push(`--signature-from=${f.signatureFrom}`);
     if (f.signatureFile) args.push(`--signature-file=${f.signatureFile}`);
+    args.push(f.autoFromAddressedAlias ? "--auto-from-addressed-alias" : "--auto-from-addressed-alias=false");
   }
   server.registerTool("gog_gmail_reply", {
     description: 'Reply to a Gmail message (sends to the original sender only). Threads off the message and inherits a "Re:" subject and the quoted original by default. For replying to every participant use gog_gmail_reply_all; to reply across many messages matching a query use gog_gmail_autoreply; to stage a reply without sending use gog_gmail_drafts_create.',
@@ -32729,9 +33172,11 @@ function registerExtraGmailTools(server) {
       includeBody: external_exports.boolean().optional().describe("Include the decoded message body in each result"),
       full: external_exports.boolean().optional().describe("Show full message bodies without truncation (implies includeBody)"),
       bodyFormat: external_exports.enum(["text", "html"]).optional().describe("Body format preference when includeBody is set"),
+      includeAttachments: external_exports.boolean().optional().describe("Include each message's attachment metadata (filename, size, mimeType, id or index). NOT a cheap add-on: like includeBody it makes gog fetch every matching message at format=full, so it costs a full per-message read \u2014 narrow the query or lower max before turning it on."),
+      useIndexedAttachmentIds: external_exports.boolean().optional().describe("Report each attachment as a 0-based `attachmentIndex` within its message instead of an opaque `attachmentId` (stable across calls, unlike the id). Only has an effect alongside includeAttachments or includeBody."),
       account: accountParam
     }
-  }, async ({ query, max, page, all, includeBody, full, bodyFormat, account }) => {
+  }, async ({ query, max, page, all, includeBody, full, bodyFormat, includeAttachments, useIndexedAttachmentIds, account }) => {
     const args = ["gmail", "messages", "search", query];
     if (max !== void 0) args.push(`--max=${max}`);
     if (page) args.push(`--page=${page}`);
@@ -32739,6 +33184,8 @@ function registerExtraGmailTools(server) {
     if (includeBody) args.push("--include-body");
     if (full) args.push("--full");
     if (bodyFormat) args.push(`--body-format=${bodyFormat}`);
+    args.push(includeAttachments ? "--include-attachments" : "--include-attachments=false");
+    args.push(useIndexedAttachmentIds ? "--use-indexed-attachment-ids" : "--use-indexed-attachment-ids=false");
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_gmail_labels_style", {