fix(oauth): wait for delayed token rotation within shared refresh recovery #258

目的

ローカル MCP ブリッジで、別プロセスの refresh rotation が成功してから共有 tokens file に届くまでの短い遅延によって、不必要な再認証へ進む競合を修正する。

前提

現行 main は 9244a28。mcp-server/server/index.js:466-480 の tryRefreshViaDiskReread は一度だけファイルを読み、旧 refresh_token のままなら即座に null を返す。getAccessToken と getAccessTokenForToolCall はその後、全面認証または背景認証へ進む。#242 の調査コメントに合成データによる遅延更新の再現が記録されている。

また、同ファイルの両呼び出し経路では _refreshLock が最初の refresh promise だけを共有し、invalid_grant 後の recovery は各 caller が個別に実行する。同一プロセスの並行 caller が recovery を重ねることを防ぐ必要がある。

#242 の過去の障害原因は未確定であり、この修正で確定したとは扱わない。#242 は観測用として開いたままにする。#257 のブラウザ認証多重起動は別の対象。

制約と要求

• invalid_grant 後に、共有ファイルの新しい refresh_token が到着するのを有界に再読込する。待機予算と間隔を明示し、実トークンやネットワークを使わずに検証できること。
• 最初の refresh と recovery を同じプロセス内の共有 promise に含め、両 access-token 取得経路の並行 caller が同じ recovery を待つこと。失敗後もロックを解放し、後続の呼び出しが回復できること。
• 新世代が期間内に届けば再認証を始めずに回復する。届かない場合・ファイルがない場合・本物の失効・別種の refresh エラーでは、無限待ちせず既存の認証 fallback を保つこと。
• recovery 自体の refresh 試行も有界とし、ファイルが更新され続ける場合でも際限なく回さないこと。
• 正常な refresh や有効なキャッシュには追加の待機を加えない。
• JS と TS の同等実装および要件書を同期する。
• 実際の認証設定、secret、ユーザーの tokens file、稼働中の MCP プロセス、Worker の認証実装に触れない。プロセス間の file lock とブラウザ認証の共有化は対象外。
• 回帰テストは遅延した更新、並行 caller、更新なしの時間切れ、別種のエラー、ロック解放後の回復を実関数で検証し、実ブラウザ・本番 API・実トークンを使わない。

対象ファイル

• mcp-server/server/index.js
• local-mcp/src/index.ts
• mcp-server/test/ の認証回帰テスト
• mcp-server/package.json / mcp-server/package-lock.json（サポート対象 Node >=18 で TS の実関数もテストするための開発用 TypeScript 依存。実行時依存は変更しない）
• docs/0-requirements.md / docs/0-requirements.ja.md の該当要件

関連: #242、#257。

— Codex Luna