mercury-agent 0.8.10 → 0.8.11

package/docs/media/whatsapp.md

@@ -47,7 +47,13 @@ Saved to: {workspace}/inbox/{timestamp}-{type}.{ext}
 function detectWhatsAppMedia(message: proto.IMessage): WhatsAppMediaInfo | null
 ```
 
-Checks message for media fields in order:
+The message is first unwrapped with Baileys' `normalizeMessageContent()` —
+WhatsApp wraps some payloads in FutureProofMessage envelopes
+(`documentWithCaptionMessage` for documents sent with a caption,
+`ephemeralMessage` in disappearing chats, `viewOnceMessage`/`viewOnceMessageV2`,
+`editedMessage`). Without unwrapping, a captioned PDF is invisible.
+
+Then checks the unwrapped content for media fields in order:
 1. `audioMessage?.ptt` → voice note
 2. `audioMessage` → audio
 3. `imageMessage` → image
@@ -157,7 +163,7 @@ Unknown MIME types default to `.bin`.
 
 2. **No built-in transcription** — Voice notes are saved as audio files; pi cannot play them. Install the **voice-transcribe** extension (local Whisper or cloud OpenAI/Groq/Gemini) to prepend a text transcript — see [overview.md](overview.md#voice-transcription).
 
-3. **Reply context doesn't include file** — When replying to a media message, we include metadata but not the actual file path. The original attachment would need to be looked up.
+3. **Quoted media re-download is partial** — Replying to a voice/audio/document/image message re-downloads the quoted file into the inbox (so "read this" replies work even if the original send was missed). Quoted videos are not re-fetched — too large to download speculatively on every reply.
 
 4. **Ephemeral media** — WhatsApp media URLs expire. Download must happen immediately when the message arrives.
 

package/examples/extensions/napkin/index.ts

@@ -10,7 +10,7 @@ import {
 } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir, tmpdir } from "node:os";
-import { delimiter, dirname, join } from "node:path";
+import { delimiter, dirname, join, resolve } from "node:path";
 import {
   getPiAuthCredential,
   parseOAuthTokenEnv,
@@ -451,7 +451,13 @@ export default function (mercury: {
     }
 
     // 2. Fall back to Mercury's auth.json (OAuth token refresh)
-    const authPath = config.authPath ?? join(config.globalDir, "auth.json");
+    // Resolved, not raw: extensions receive `ctx.config` with `globalDir` still
+    // relative, while the container runner resolves it. Both spellings name the
+    // same file, and naming it the same way keeps the error strings below (and
+    // the refresh dedupe in getPiAuthCredential) consistent between the two.
+    const authPath = resolve(
+      config.authPath ?? join(config.globalDir, "auth.json"),
+    );
     const cred = await getPiAuthCredential({
       provider: config.modelProvider,
       authPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mercury-agent",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "description": "Personal AI assistant for chat platforms (WhatsApp, Slack, Discord, Telegram)",
   "license": "MIT",
   "author": "Avishai Tsabari",

package/src/adapters/whatsapp-media.ts

@@ -10,6 +10,7 @@ import fs from "node:fs";
 import path from "node:path";
 import {
   downloadMediaMessage,
+  normalizeMessageContent,
   type proto,
   type WAMessage,
   type WASocket,
@@ -64,8 +65,11 @@ export interface MediaDownloadOptions {
  * Returns null if the message has no media.
  */
 export function detectWhatsAppMedia(
-  message: proto.IMessage | null | undefined,
+  rawMessage: proto.IMessage | null | undefined,
 ): WhatsAppMediaInfo | null {
+  // Captioned documents (and ephemeral/view-once media) arrive wrapped in a
+  // FutureProofMessage envelope, e.g. documentWithCaptionMessage.message.
+  const message = normalizeMessageContent(rawMessage ?? undefined);
   if (!message) return null;
 
   // Voice note (push-to-talk)
@@ -238,9 +242,18 @@ export async function downloadWhatsAppMedia(
   }
 }
 
+/** Media types worth re-fetching when someone replies to the message. */
+const QUOTED_DOWNLOAD_TYPES: ReadonlySet<MediaType> = new Set([
+  "voice",
+  "audio",
+  "document",
+  "image",
+]);
+
 /**
- * Download audio from a quoted (replied-to) WhatsApp message.
- * Only downloads voice/audio types — other media types are skipped.
+ * Download media from a quoted (replied-to) WhatsApp message.
+ * Downloads voice/audio/document/image — video is skipped (too large to
+ * re-fetch speculatively on every reply).
  */
 export async function downloadQuotedMedia(
   contextInfo: proto.IContextInfo,
@@ -253,7 +266,7 @@ export async function downloadQuotedMedia(
   const mediaInfo = detectWhatsAppMedia(quotedMessage);
   if (!mediaInfo) return null;
 
-  if (mediaInfo.type !== "voice" && mediaInfo.type !== "audio") return null;
+  if (!QUOTED_DOWNLOAD_TYPES.has(mediaInfo.type)) return null;
 
   const syntheticMsg: WAMessage = {
     key: {
@@ -310,7 +323,12 @@ export async function downloadQuotedMedia(
     fs.mkdirSync(mediaDir, { recursive: true });
 
     const ext = mimeToExt(mediaInfo.mimeType);
-    const filename = `${Date.now()}-${mediaInfo.type}.${ext}`;
+    const safeName = mediaInfo.filename
+      ? path.basename(mediaInfo.filename).replace(/[^a-zA-Z0-9._-]/g, "_")
+      : undefined;
+    const filename = safeName
+      ? `${Date.now()}-${safeName}`
+      : `${Date.now()}-${mediaInfo.type}.${ext}`;
     const filePath = path.join(mediaDir, filename);
 
     fs.writeFileSync(filePath, buffer);
@@ -327,6 +345,7 @@ export async function downloadQuotedMedia(
       path: filePath,
       type: mediaInfo.type,
       mimeType: mediaInfo.mimeType,
+      filename: mediaInfo.filename,
       sizeBytes: buffer.length,
     };
   } catch (error) {

package/src/adapters/whatsapp.ts

@@ -6,6 +6,7 @@ import makeWASocket, {
   fetchLatestWaWebVersion,
   jidDecode,
   makeCacheableSignalKeyStore,
+  normalizeMessageContent,
   type proto,
   useMultiFileAuthState,
   type WAMessage,
@@ -45,7 +46,11 @@ type WhatsAppThreadId = {
   threadJid: string;
 };
 
-function extractText(message?: proto.IMessage | null): string {
+function extractText(rawMessage?: proto.IMessage | null): string {
+  // Unwrap FutureProofMessage envelopes (documentWithCaptionMessage,
+  // ephemeralMessage, viewOnceMessage, …) — a document sent with a caption
+  // arrives as documentWithCaptionMessage.message.documentMessage.
+  const message = normalizeMessageContent(rawMessage ?? undefined);
   if (!message) return "";
   return (
     message.conversation ||
@@ -58,8 +63,9 @@ function extractText(message?: proto.IMessage | null): string {
 }
 
 function getContextInfo(
-  message?: proto.IMessage | null,
+  rawMessage?: proto.IMessage | null,
 ): proto.IContextInfo | undefined {
+  const message = normalizeMessageContent(rawMessage ?? undefined);
   if (!message) return undefined;
   const contextInfo =
     message.extendedTextMessage?.contextInfo ||
@@ -601,7 +607,16 @@ export class WhatsAppBaileysAdapter
     }
 
     const text = [baseText, replyContext].filter(Boolean).join("\n\n").trim();
-    if (!text && !hasMedia) return;
+    if (!text && !hasMedia) {
+      // Neither text nor media extracted — an unrecognized message shape would
+      // otherwise vanish silently (this is how captioned documents got lost
+      // before documentWithCaptionMessage unwrapping was added).
+      logger.debug("WhatsApp message dropped: no text or media extracted", {
+        remoteJid: chatJid,
+        messageKeys: Object.keys(msg.message ?? {}),
+      });
+      return;
+    }
 
     const threadId = this.encodeThreadId({
       chatJid,

package/src/agent/container-entry.ts

@@ -723,6 +723,18 @@ function buildPrompt(payload: Payload): string {
   return parts.join("\n");
 }
 
+/** Read-only bwrap binds for each resource entry the host mounted into pi's agent dir. */
+function piAgentRoBindArgs(): string[] {
+  const agentDir = "/home/mercury/.pi/agent";
+  if (!existsSync(agentDir)) return [];
+  const args: string[] = [];
+  for (const entry of readdirSync(agentDir)) {
+    const p = `${agentDir}/${entry}`;
+    args.push("--ro-bind", p, p);
+  }
+  return args;
+}
+
 /**
  * Build bwrap args for sandboxing the agent process.
  * Uses bubblewrap for defense-in-depth: Docker isolates from host, bwrap restricts within container.
@@ -762,9 +774,11 @@ function buildBwrapArgs(
     "--bind",
     "/home/mercury",
     "/home/mercury",
-    "--ro-bind",
-    "/home/mercury/.pi/agent",
-    "/home/mercury/.pi/agent",
+    // The host mounts the global resource dir entry by entry (auth.json stays
+    // on the host), so `.pi/agent` is a plain dir holding N read-only submounts
+    // rather than a single one. Re-bind each entry explicitly instead of relying
+    // on a recursive bind of the parent to carry the read-only flag down.
+    ...piAgentRoBindArgs(),
     "--proc",
     "/proc",
     "--dev",
@@ -836,11 +850,14 @@ function invokePiOnce(
       "--mode",
       "json",
       // Skip pi's project-trust store entirely. The store lives in
-      // /home/mercury/.pi/agent (mounted :ro) and even a read locks it via
-      // proper-lockfile (mkdir trust.json.lock → EROFS). Workspaces with
-      // trust-requiring resources already resolved to "untrusted" in
-      // non-interactive mode, and without such resources nothing trust-gated
-      // loads — so --no-approve preserves behavior either way.
+      // /home/mercury/.pi/agent, whose resource entries are read-only bind
+      // mounts, and even a read locks it via proper-lockfile (mkdir
+      // trust.json.lock). Workspaces with trust-requiring resources already
+      // resolved to "untrusted" in non-interactive mode, and without such
+      // resources nothing trust-gated loads — so --no-approve preserves
+      // behavior either way (the agent dir itself is now a Docker-created
+      // mount parent owned by root, so writing the trust file there would fail
+      // with EACCES rather than EROFS — still a failure, still skipped).
       "--no-approve",
       ...sessionArgs,
       "--provider",

package/src/agent/container-runner.ts

@@ -8,7 +8,12 @@ import { mintCallerToken } from "../core/caller-token.js";
 import { scanOutbox } from "../core/outbox.js";
 import type { ExtImageBuildState } from "../extensions/image-builder.js";
 import { type Logger, logger } from "../logger.js";
-import { getPiAuthCredential } from "../storage/pi-auth.js";
+import { ensurePiResourceDir } from "../storage/memory.js";
+import {
+  getPiAuthCredential,
+  hasOAuthEntry,
+  providerCredentialEnvVar,
+} from "../storage/pi-auth.js";
 import type {
   ContainerResult,
   MessageAttachment,
@@ -34,6 +39,60 @@ import { ContainerError } from "./container-error.js";
  */
 const INNER_IO_DIR = "/run/mercury-io";
 
+/** Where pi looks for global agent resources inside the inner container (PI_CODING_AGENT_DIR). */
+const INNER_PI_AGENT_DIR = "/home/mercury/.pi/agent";
+
+/**
+ * Entries of the host global dir that are mounted into `INNER_PI_AGENT_DIR`.
+ * Everything pi loads as a resource — and nothing else. `auth.json` (and the
+ * `.tmp` siblings an interrupted rotation can leave next to it) is deliberately
+ * absent: it carries the OAuth refresh token, and the container only ever needs
+ * the short-lived access token handed to it via ANTHROPIC_OAUTH_TOKEN.
+ *
+ * A superset of what Mercury itself writes (`.pi/`, `AGENTS.md`, `skills/`) —
+ * the remaining entries are pi resource kinds a user may drop in by hand, none
+ * of which can hold a credential.
+ */
+const PI_AGENT_RESOURCE_ENTRIES = [
+  ".pi",
+  "AGENTS.md",
+  "skills",
+  "agents",
+  "commands",
+  "prompts",
+  "extensions",
+] as const;
+
+/**
+ * Docker `-v` args exposing the global dir's resource entries at
+ * `INNER_PI_AGENT_DIR`, one mount per entry rather than one mount of the
+ * directory itself. Binding the directory would carry `auth.json` — and the
+ * `auth.json.<pid>.tmp` siblings an interrupted rotation can leave next to it
+ * (see `writeAuthFile` in storage/pi-auth.ts) — into the least-trusted part of
+ * the system, handing it the long-lived refresh token when all it needs is the
+ * access token injected as ANTHROPIC_OAUTH_TOKEN. The allowlist fails closed:
+ * anything new that lands in the global dir must be opted in here.
+ *
+ * `hostGlobalDir` is the path this process can stat; `innerGlobalDir` is the
+ * path the Docker daemon resolves the bind source against (they differ under
+ * MERCURY_HOST_DATA_DIR). Absent entries are skipped — Docker would otherwise
+ * create the missing source as a directory, turning `AGENTS.md` into a folder.
+ */
+export function buildPiAgentMountArgs(
+  hostGlobalDir: string,
+  innerGlobalDir: string,
+): string[] {
+  const args: string[] = [];
+  for (const entry of PI_AGENT_RESOURCE_ENTRIES) {
+    if (!fs.existsSync(path.join(hostGlobalDir, entry))) continue;
+    args.push(
+      "-v",
+      `${path.join(innerGlobalDir, entry)}:${INNER_PI_AGENT_DIR}/${entry}:ro`,
+    );
+  }
+  return args;
+}
+
 /** Poll interval (ms) while waiting for the inner container's result file. */
 const RESULT_POLL_MS = 150;
 /** Run a `docker inspect` liveness probe every Nth poll (~2s) to fail fast on crash. */
@@ -647,6 +706,62 @@ export class AgentContainerRunner {
       : `mercury-${timestamp}-${id}`;
   }
 
+  /**
+   * Resolve each OAuth provider in the model chain from the host's auth.json
+   * and append its credential to `envPairs` as the env var pi reads it from.
+   *
+   * Only providers pi can be handed a token for are servable: `openai-codex`
+   * has no env var at all (see `providerCredentialEnvVar`), so a codex leg is
+   * dead on arrival and says so in the log rather than failing obscurely inside
+   * the container. Providers already carrying a credential through passthrough
+   * env are left alone — an explicit `MERCURY_*` value outranks the file.
+   *
+   * A leg that cannot be served is logged, not thrown: `MODEL_CHAIN` exists so
+   * a later leg can carry the turn when an earlier one fails, and refusing the
+   * whole spawn over one unusable leg would defeat that. The Anthropic
+   * fail-fast above is unaffected — it guards the primary provider.
+   */
+  private async injectChainOAuthCredentials(
+    envPairs: Array<{ key: string; value: string }>,
+    extraEnv: Record<string, string> | undefined,
+    authPath: string,
+    spaceId: string,
+    // Injected like `OAuthSpawnDeps` above, so a test can exercise the
+    // refresh-failure branch without a token endpoint.
+    resolveCredential: typeof getPiAuthCredential = getPiAuthCredential,
+  ): Promise<void> {
+    const providers = new Set(
+      (this.config.resolvedModelChain ?? []).map((leg) => leg.provider),
+    );
+    for (const provider of providers) {
+      const envVar = providerCredentialEnvVar(provider);
+      if (!envVar) {
+        if (hasOAuthEntry(authPath, provider)) {
+          logger.warn(
+            `Model chain leg "${provider}" has OAuth credentials in ${authPath}, but pi reads no env var for that provider — the credential cannot be passed to the container (auth.json stays on the host). This leg will fail; use a provider with an API key env var, or drop the leg.`,
+            { spaceId, provider },
+          );
+        }
+        continue;
+      }
+
+      const alreadySet =
+        envPairs.some((p) => p.key === envVar && p.value) ||
+        Boolean(extraEnv?.[envVar]);
+      if (alreadySet) continue;
+
+      const credential = await resolveCredential({ provider, authPath });
+      if (credential.status === "ok") {
+        envPairs.push({ key: envVar, value: credential.apiKey });
+      } else if (credential.status === "refresh-failed") {
+        logger.warn(
+          `OAuth refresh failed for model chain leg "${provider}" (${authPath}) — the container starts without that credential. Re-authenticate on the host with mercury auth login.`,
+          { spaceId, provider },
+        );
+      }
+    }
+  }
+
   async reply(input: {
     spaceId: string;
     spaceWorkspace: string;
@@ -664,7 +779,11 @@ export class AgentContainerRunner {
     const globalDir = path.resolve(this.config.globalDir);
     const spacesRoot = path.resolve(this.config.spacesDir);
 
-    fs.mkdirSync(globalDir, { recursive: true });
+    // Resource structure, not a bare mkdir: the global dir is mounted entry by
+    // entry (see PI_AGENT_RESOURCE_ENTRIES), so an empty dir would leave the
+    // container without PI_CODING_AGENT_DIR at all. Idempotent — the same helper
+    // runtime.ts calls at startup.
+    ensurePiResourceDir(globalDir);
     fs.mkdirSync(spacesRoot, { recursive: true });
     try {
       execFileSync("chown", ["-R", "1000:1000", globalDir], { stdio: "pipe" });
@@ -799,6 +918,17 @@ export class AgentContainerRunner {
       }
     }
 
+    // Every other OAuth provider in the resolved chain. The container used to
+    // read auth.json itself (the global dir was mounted wholesale); that file
+    // now stays on the host because it carries refresh tokens, so each leg's
+    // credential must be resolved here and handed over as env instead.
+    await this.injectChainOAuthCredentials(
+      passthroughEnvPairs,
+      input.extraEnv,
+      this.config.authPath ?? path.join(globalDir, "auth.json"),
+      input.spaceId,
+    );
+
     const envPairs = [
       // Internal vars (set by code, not from env)
       { key: "HOME", value: "/home/mercury" },
@@ -807,7 +937,7 @@ export class AgentContainerRunner {
         value:
           "/home/mercury/.local/bin:/home/mercury/.bun/bin:/usr/local/go/bin:/usr/local/bin:/usr/bin:/bin",
       },
-      { key: "PI_CODING_AGENT_DIR", value: "/home/mercury/.pi/agent" },
+      { key: "PI_CODING_AGENT_DIR", value: INNER_PI_AGENT_DIR },
       { key: "CALLER_ID", value: input.callerId },
       { key: "SPACE_ID", value: input.spaceId },
       {
@@ -957,8 +1087,6 @@ export class AgentContainerRunner {
       "-v",
       `${innerSpaceDir}:/spaces/${input.spaceId}`,
       "-v",
-      `${innerGlobalDir}:/home/mercury/.pi/agent:ro`,
-      "-v",
       `${readmePath}:/docs/mercury/README.md:ro`,
       "-v",
       `${docsDir}:/docs/mercury/docs:ro`,
@@ -968,6 +1096,8 @@ export class AgentContainerRunner {
       `IO_DIR=${INNER_IO_DIR}`,
     );
 
+    args.push(...buildPiAgentMountArgs(globalDir, innerGlobalDir));
+
     if (this.config.containerRuntime === "runsc") {
       // Mount the per-agent run dir so the inner container can reach the outer's
       // API unix socket (api-<hostname>.sock, created in main.ts). Mirrors the

package/src/bridges/whatsapp.ts

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
-import type { proto, WAMessage } from "@whiskeysockets/baileys";
+import {
+  normalizeMessageContent,
+  type proto,
+  type WAMessage,
+} from "@whiskeysockets/baileys";
 import type { Message } from "chat";
 import type { WhatsAppBaileysAdapter } from "../adapters/whatsapp.js";
 import {
@@ -79,13 +83,14 @@ export class WhatsAppBridge implements PlatformBridge {
       }
 
       if (attachments.length === 0) {
+        const content = normalizeMessageContent(rawMsg.message ?? undefined);
         const contextInfo =
-          rawMsg.message?.extendedTextMessage?.contextInfo ||
-          rawMsg.message?.audioMessage?.contextInfo ||
-          rawMsg.message?.imageMessage?.contextInfo ||
-          rawMsg.message?.videoMessage?.contextInfo ||
-          rawMsg.message?.documentMessage?.contextInfo ||
-          rawMsg.message?.stickerMessage?.contextInfo;
+          content?.extendedTextMessage?.contextInfo ||
+          content?.audioMessage?.contextInfo ||
+          content?.imageMessage?.contextInfo ||
+          content?.videoMessage?.contextInfo ||
+          content?.documentMessage?.contextInfo ||
+          content?.stickerMessage?.contextInfo;
         if (contextInfo?.quotedMessage) {
           if (await ctx.isOverQuota()) {
             logger.warn(

package/src/storage/pi-auth.ts

@@ -1,12 +1,48 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import {
   getOAuthApiKey,
+  getOAuthProvider,
   type OAuthCredentials,
   type OAuthProviderId,
 } from "@earendil-works/pi-ai/oauth";
 import { logger } from "../logger.js";
 
+/**
+ * Env var pi reads a provider's credential from, for the OAuth providers
+ * `mercury auth login` can write to auth.json. Mirrors `getApiKeyEnvVars` in
+ * `@earendil-works/pi-ai/dist/env-api-keys.js` (see its `anthropic` and
+ * `github-copilot` cases) — that mapping is not exported, so it is restated
+ * here rather than reached into.
+ *
+ * `openai-codex` is deliberately absent: pi has no env var for it, so a codex
+ * credential can only travel in auth.json — which Mercury no longer mounts into
+ * the container (it carries the refresh token). A codex leg is unservable.
+ */
+const PROVIDER_CREDENTIAL_ENV_VAR: Record<string, string> = {
+  anthropic: "ANTHROPIC_OAUTH_TOKEN",
+  "github-copilot": "COPILOT_GITHUB_TOKEN",
+};
+
+/**
+ * The env var that carries this provider's credential into the agent container,
+ * or undefined when pi has no env var for it (the credential cannot be passed).
+ */
+export function providerCredentialEnvVar(provider: string): string | undefined {
+  return PROVIDER_CREDENTIAL_ENV_VAR[provider];
+}
+
+/**
+ * Whether auth.json holds an OAuth entry for this provider — asked before
+ * resolving one, so a credential that could never be passed on (no env var for
+ * it) is reported without spending a single-use refresh token to find out.
+ */
+export function hasOAuthEntry(authPath: string, provider: string): boolean {
+  const entry = readAuthFile(path.resolve(authPath))[provider];
+  return Boolean(entry && typeof entry === "object" && entry.type === "oauth");
+}
+
 type AuthEntry =
   | ({ type: "oauth" } & OAuthCredentials)
   | { type: "api_key"; key: string }
@@ -27,10 +63,55 @@ function readAuthFile(authPath: string): AuthFile {
   }
 }
 
+/**
+ * Persist the auth file atomically: write a sibling temp file, then rename over
+ * the target. A torn or partially-written auth.json is unrecoverable — Anthropic
+ * rotates refresh tokens on every refresh, so the copy on disk is the only
+ * record of the current link in the chain.
+ *
+ * The rename is retried because on Windows a concurrent reader holding a handle
+ * makes `renameSync` fail with EPERM/EBUSY; the operation succeeds moments later.
+ */
 function writeAuthFile(authPath: string, auth: AuthFile): void {
   fs.mkdirSync(path.dirname(authPath), { recursive: true });
-  fs.writeFileSync(authPath, JSON.stringify(auth, null, 2), "utf8");
-  fs.chmodSync(authPath, 0o600);
+  const tmpPath = `${authPath}.${process.pid}.tmp`;
+  fs.writeFileSync(tmpPath, JSON.stringify(auth, null, 2), "utf8");
+  try {
+    fs.chmodSync(tmpPath, 0o600);
+  } catch {
+    // chmod is best-effort (no-op on some Windows setups); never fail the
+    // persist over file permissions when a credential is waiting to be saved.
+  }
+
+  let lastError: unknown;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      fs.renameSync(tmpPath, authPath);
+      return;
+    } catch (err) {
+      lastError = err;
+      // Busy-wait briefly: this path is rare (~3x/day) and must stay sync so
+      // callers cannot observe a half-persisted credential.
+      const until = Date.now() + 20;
+      while (Date.now() < until) {
+        /* spin */
+      }
+    }
+  }
+  try {
+    fs.rmSync(tmpPath, { force: true });
+  } catch {
+    // Leaving a stray temp file is preferable to masking the rename error.
+  }
+  throw lastError;
+}
+
+/**
+ * Short, non-reversible fingerprint of a secret, safe to log. Used to make token
+ * rotations identifiable after the fact without ever recording the token.
+ */
+function fingerprint(secret: string): string {
+  return crypto.createHash("sha256").update(secret).digest("hex").slice(0, 12);
 }
 
 export type OAuthTokenEnvValue =
@@ -61,6 +142,15 @@ export function parseOAuthTokenEnv(raw: string): OAuthTokenEnvValue {
   return { status: "corrupt-blob" };
 }
 
+/** Whether the environment names an Anthropic credential that can actually be used. */
+function hasAnthropicEnvOverride(): boolean {
+  if (process.env.MERCURY_ANTHROPIC_API_KEY) return true;
+  const raw = process.env.MERCURY_ANTHROPIC_OAUTH_TOKEN;
+  if (!raw) return false;
+  const parsed = parseOAuthTokenEnv(raw);
+  return parsed.status === "token" || parsed.status === "blob";
+}
+
 export type PiAuthCredential =
   | { status: "ok"; apiKey: string }
   /** No usable oauth entry (or an env override takes precedence). */
@@ -76,24 +166,47 @@ export async function getPiAuthCredential(options: {
   provider: string;
   authPath: string;
 }): Promise<PiAuthCredential> {
-  if (
-    process.env.MERCURY_ANTHROPIC_API_KEY ||
-    process.env.MERCURY_ANTHROPIC_OAUTH_TOKEN
-  ) {
+  // Anthropic-only override: a *usable* MERCURY_ANTHROPIC_* value is the
+  // operator naming the credential to use, so the file is not consulted. No
+  // other provider has such a variable — theirs arrive as ordinary passthrough
+  // env, which the caller checks before asking us.
+  //
+  // A corrupt blob is not an override: it names nothing, and treating its mere
+  // presence as one would suppress the file fallback that is the only remaining
+  // way to authenticate.
+  if (options.provider === "anthropic" && hasAnthropicEnvOverride()) {
     return { status: "none" };
   }
 
-  if (options.provider !== "anthropic") {
+  // Only providers pi can refresh an OAuth token for. Anything else in the file
+  // (a hand-written api_key entry, a provider from a newer pi) is not ours to
+  // interpret, and getOAuthApiKey would throw on an unknown id.
+  if (!getOAuthProvider(options.provider)) {
     return { status: "none" };
   }
 
   // Coalesce concurrent refreshes for the same auth file so only one
-  // token-endpoint call is made; the rest share its result.
-  const key = options.authPath;
+  // token-endpoint call is made; the rest share its result. Keyed per provider
+  // as well as per file: one auth.json holds an entry per provider, and a
+  // shared promise would hand a copilot caller the anthropic token.
+  //
+  // The key must be canonical, not the caller's spelling: callers reach this
+  // function with the same file written different ways (a relative
+  // `.mercury/global/auth.json` from an extension, an absolute path from the
+  // container runner). Relative paths already resolve against `process.cwd()`
+  // inside `fs`, so `path.resolve` names the exact same file the raw spelling
+  // would have opened — it only removes the caller's freedom to defeat the
+  // dedupe by spelling. The resolved path is also what gets read, written and
+  // logged, so one file never appears under two names in the logs. (The map is
+  // process-local; coalescing across processes would need a lock file.)
+  const authPath = path.resolve(options.authPath);
+  // "|" is not legal in a Windows path and never appears in a provider id,
+  // so the two halves can never run together into a colliding key.
+  const key = `${authPath}|${options.provider}`;
   const existing = inflightRefresh.get(key);
   if (existing) return existing;
 
-  const promise = doGetPiAuthCredential(options);
+  const promise = doGetPiAuthCredential({ ...options, authPath });
   inflightRefresh.set(key, promise);
   try {
     return await promise;
@@ -107,9 +220,10 @@ async function doGetPiAuthCredential(options: {
   authPath: string;
 }): Promise<PiAuthCredential> {
   const authPath = options.authPath;
+  const provider = options.provider;
   const auth = readAuthFile(authPath);
 
-  const entry = auth.anthropic;
+  const entry = auth[provider];
   if (!entry || typeof entry !== "object" || entry.type !== "oauth") {
     return { status: "none" };
   }
@@ -121,33 +235,23 @@ async function doGetPiAuthCredential(options: {
     return { status: "none" };
   }
 
+  // Step 1 — obtain a usable key. getOAuthApiKey only contacts the token
+  // endpoint when the access token has expired; otherwise it returns the
+  // existing credentials untouched. A throw here means the refresh itself was
+  // rejected, which is a genuine credential failure.
+  let result: Awaited<ReturnType<typeof getOAuthApiKey>>;
   try {
-    const result = await getOAuthApiKey("anthropic" satisfies OAuthProviderId, {
-      anthropic: {
+    result = await getOAuthApiKey(provider as OAuthProviderId, {
+      [provider]: {
+        ...entry,
         access,
         refresh,
         expires,
       },
     });
-
-    if (!result) return { status: "refresh-failed" };
-
-    const nextAuth = {
-      ...auth,
-      anthropic: {
-        type: "oauth" as const,
-        ...result.newCredentials,
-      },
-    };
-
-    writeAuthFile(authPath, nextAuth);
-    logger.debug("Loaded anthropic oauth token from pi auth.json", {
-      authPath,
-    });
-    return { status: "ok", apiKey: result.apiKey };
   } catch (error) {
     logger.warn(
-      `Failed to load anthropic oauth token from pi auth.json at ${authPath}`,
+      `Failed to load ${provider} oauth token from pi auth.json at ${authPath}`,
       error instanceof Error ? error : undefined,
     );
     return {
@@ -155,6 +259,66 @@ async function doGetPiAuthCredential(options: {
       error: error instanceof Error ? error : undefined,
     };
   }
+
+  if (!result) return { status: "refresh-failed" };
+
+  // Step 2 — persist, in its own scope. Providers rotate the refresh token on
+  // every refresh (the old one is consumed server-side), so when a rotation has
+  // happened the value in memory is the ONLY copy of the current chain link.
+  // A failure to save it is therefore unrecoverable — but it is emphatically not
+  // a refresh failure, and must not be reported as one: the key we hold is
+  // valid, and failing the call here would break the chain instead of preserving
+  // the one chance to use and re-save it.
+  const nextCredentials = result.newCredentials;
+  const rotated =
+    typeof nextCredentials.refresh === "string" &&
+    nextCredentials.refresh !== refresh;
+
+  try {
+    // Re-read immediately before merging: another provider's refresh may have
+    // rewritten the file since this call read it, and a stale snapshot would
+    // drop that provider's rotation on the floor.
+    writeAuthFile(authPath, {
+      ...readAuthFile(authPath),
+      [provider]: {
+        type: "oauth" as const,
+        ...nextCredentials,
+      },
+    });
+    if (rotated) {
+      // The single log line that makes a broken chain diagnosable after the
+      // fact: which link was replaced by which, without recording either token.
+      logger.info(`Rotated ${provider} oauth refresh token`, {
+        authPath,
+        previousRefresh: fingerprint(refresh),
+        newRefresh: fingerprint(nextCredentials.refresh as string),
+      });
+    }
+  } catch (error) {
+    if (rotated) {
+      logger.error(
+        `CRITICAL: ${provider} OAuth credential was rotated but could NOT be saved to ${authPath} — the previous refresh token is already consumed server-side, so this space will fail to authenticate once the current access token expires. Re-run mercury auth login from the project directory that owns this file.`,
+        {
+          authPath,
+          previousRefresh: fingerprint(refresh),
+          unsavedRefresh: fingerprint(nextCredentials.refresh as string),
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+    } else {
+      // No rotation occurred, so the on-disk copy is still current and nothing
+      // was lost — the rewrite was a no-op carrying identical content.
+      logger.warn(
+        `Could not rewrite pi auth.json at ${authPath} (no rotation occurred, stored credential is unchanged)`,
+        error instanceof Error ? error : undefined,
+      );
+    }
+  }
+
+  logger.debug(`Loaded ${provider} oauth token from pi auth.json`, {
+    authPath,
+  });
+  return { status: "ok", apiKey: result.apiKey };
 }
 
 /** Back-compat wrapper: returns the key on success, undefined otherwise. */