docs: release does not reach a running client until the local npx process restarts

[liplus-lin-lay]

目的

リリースの配送鎖が npm publish で終わっていると誤認しやすい。実際にはその先に 利用側プロセスの再起動 という段があり、これがどこにも書かれていない。v0.11.9 のリリース直後に実測で踏んだため記録する。

観測（2026-08-03、v0.11.9 リリース直後）

mark_processed のバッチ形（#245）は MCP proxy の静的スキーマ変更を伴うため、npm 再公開が必要と #245 本文に明記されていた。v0.11.9 で CD の npm-publish ジョブが success となり、registry の latest は 0.11.9 になった。

しかしこの時点で 利用側にはまだ何も届いていない。同一マシンで確認した事実:

観測点	値
registry latest（--prefer-online）	0.11.9
npx キャッシュ内の実体（3 ディレクトリすべて）	0.11.8
再起動後の npx キャッシュ	当該 spec のキャッシュディレクトリがその場で 0.11.9 に更新され、server/index.js に event_ids が存在（新規ディレクトリは作られていない）

claude_desktop_config.json の起動指定は npx -y github-webhook-mcp@latest。@latest を指定していても、すでに起動しているプロセスは 0.11.8 を保持したままであり、registry がどう変わろうと差し替わらない。

加えてリリース作業中、CD が green になった後の npm view github-webhook-mcp version が 0.11.8 を返した。--prefer-online を付けると 0.11.9 が返る。npm CLI 側のメタデータキャッシュであり publish 失敗ではなかったが、「registry を確認した」だけでは配送の確認にならないことを示している。

配送鎖の実態

merge → gh release create → CD (npm-publish) → registry latest 更新
      → 【未記載】利用側 Claude Desktop の再起動 → npx が新版を解決 → 利用側に到達

最後の 2 段は CD の外側にあり、リポジトリ側からは実行できない。

影響

• リリース完了報告が「registry が新版を返す」で締められると、利用側に届いていない状態を「届いた」と報告することになる。今回の enhancement: mark_processed accepts one event per call, so consuming a PR's own events costs N round trips #245 は proxy スキーマ変更そのものが目的だったため、この誤認は成果の有無を取り違える。
• --prefer-online 無しの npm view を確認手段に使うと、publish 直後は古い値を返しうる。

検討の材料

• README.md / mcp-server/README.md の導線に「新版の反映には Claude Desktop の再起動が要る」旨を追記する
• リリース手順側（docs/）に配送鎖の最終段として再起動を明記する
• 確認コマンドとして npm view --prefer-online を推奨する（キャッシュ由来の誤読を防ぐ）

制約

• npx キャッシュの解決挙動そのものはこのリポジトリの管理外。書けるのは「再起動が要る」という事実と確認手段まで。

受け入れ条件

• 配送鎖の最終段（利用側再起動）がドキュメントに書かれている
• リリース完了の判定基準が「registry 更新」で止まらないことが読み取れる

[liplus-lin-lay]

訂正と実地検証（2026-08-03、Desktop 再起動後）

訂正: 初版の観測表に「稼働中の MCP proxy が広告する mark_processed スキーマ = event_id のみ」という行があったが、これは誤りだった。実際にはその時点でツールスキーマに event_ids が載っていた。確認せず予測で書いた行であり、本文から削除した。

登録済みの他の観測（registry が 0.11.9 を返す一方 npx キャッシュは 0.11.8、--prefer-online 無しの npm view が publish 直後に旧版を返す）は実測であり、そのまま維持する。

再起動後の実測:

観測点	値
npx キャッシュ	当該 spec のキャッシュディレクトリがその場で 0.11.9 に更新（mtime = 再起動時刻）。server/index.js に event_ids あり
他の 2 ディレクトリ	0.11.8 のまま（event_ids 0 hits）。mtime は 7 月のままで、再起動では触られていない
バッチ形の動作	pending 12 件を 1 呼び出しで消費、marked: 12 / failed: 0

配送鎖の最終段に再起動が要るという本文の主旨は、再起動前後のキャッシュ差分で裏付けられた。#245 のバッチ形もこれで実地確認済み。

追記(同日): 上表の初版は「新規ディレクトリに取得」と書いていたが誤り。再起動前後でディレクトリ集合は同一であり、当該 spec の 1 本がその場で更新されただけだった。この誤りは #248 の docs 草稿にそのまま伝播していたため、そちらでも修正済み。