# 配布した hook が Windows で「静かに死ぬ」のを塞ぐ AI コーディングエージェント（Claude Code など）の hook を複数台へ配布して運用する時、 **エラーも出さず、機能だけが消える**壊れ方をする。動いて見えるので誰も気づかない。 このMDは、実際に踏んだ1件の真因と、二度と踏まないための検証手順・回帰テストの型をまとめたもの。 ## 症状 `UserPromptSubmit` hook（依頼文を見て参考情報を注入するスクリプト）が、 **24時間に1回だけ**動かない。それ以外は正常に動く。 Windows / Node v24 で実行すると: ``` Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 76 ``` 終了コードは 127（環境により -1073740791）。 ## 真因: top-level await の中で process.exit を呼んでいた hook スクリプトは stdin を読むため top-level await を使うことが多い。 ```js // 壊れている例 let raw = ''; for await (const chunk of process.stdin) raw += chunk; try { if (!raw) process.exit(0); const data = await fetch(API).then((r) => r.json()); // ← 非同期ハンドルが開く console.log(JSON.stringify({ hookSpecificOutput: { ... } })); } catch {} process.exit(0); // ← ここで落ちる ``` `process.exit()` は**イベントループを待たずに即殺す**。top-level await の評価中に呼ぶと、 HTTP クライアントのソケット（libuv の async handle）が閉じかけの状態で強制終了され、 libuv の内部 assertion を踏む。 **24時間に1回だけ落ちた理由**: このスクリプトは取得結果を24時間キャッシュしていた。 キャッシュが生きている間は `fetch` が走らない＝開いたハンドルが無いので落ちない。 **ネットワークI/Oを伴う経路だけが落ちる。** だから普段は完璧に動いて見える。 ## なぜ「静かに」死ぬのか（ここが一番重要） hook は **stdout に JSON を書き、終了コード0で正常終了**して初めて採用される。 - stdout には注入内容が**ちゃんと書けていた**（実測 1243 バイト） - しかし終了コードが 0 でないため、ホスト側は hook 失敗として扱い、**出力を丸ごと捨てる** つまり「出力は正しいのに反映されない」。ログにも成果物にも痕跡が残らない。 **exit code が出力の採用可否を決める**タイプの連携では、 クラッシュは「機能が静かに無効化される」という形で現れる。 ## 修正 `process.exit()` を全廃し、`async function main()` + 早期 `return` で自然終了させる。 ```js // process.exit を絶対に呼ばない: top-level await の評価中に呼ぶと Windows の Node が // libuv の assertion で異常終了する。exit!=0 だとホストが hook 失敗として出力を捨てるため、 // 非同期I/Oを伴う経路だけが静かに死ぬ。早期リターンで自然終了させる。 async function main() { let raw = ''; for await (const chunk of process.stdin) raw += chunk; try { if (!raw) return; const data = await fetch(API).then((r) => r.json()); console.log(JSON.stringify({ hookSpecificOutput: { ... } })); } catch {} } await main().catch(() => {}); ``` **懸念と実測**: `process.exit` を外すと、HTTP クライアントの keep-alive が イベントループを掴んで hook がハングしないか。→ 実測 600〜700ms で自然終了した （hook の timeout は 6 秒）。**ハングを恐れて exit を残すのは逆効果。必ず実測で確かめる。** ## 回帰テストの型（ネットワークに依存させない） 外部APIを叩くスクリプトのテストを素直に書くとネットワーク依存になり、 「落ちる日と落ちない日がある」テストになって信用されなくなる。次の2層に分ける。 ### 1) 構造テスト: 危険な書き方をソース文字列で機械的に禁止する 真因が「特定の書き方」なら、**その書き方の存在自体をテストで禁止する**のが最も安い。 ```js test('hook: process.exit を使わない', () => { const source = fs.readFileSync(hookPath, 'utf8'); assert(!/process\.exit\s*\(/.test(source), 'process.exit が残っている'); assert(/await main\(\)/.test(source), 'main() を await していない'); }); ``` 注意: この判定はコメントも引っかける。理由をコメントで残す時は `process.exit(` という**括弧付きの文字列を書かない**（実際に自分のコメントで落とした）。 逆にコメントを除外する実装にすると判定が緩むので、文言側を調整するほうが安全。 ### 2) 挙動テスト: 外部依存はキャッシュを事前投入して切る 取得結果をキャッシュする設計なら、**テストが先にキャッシュを書いておけば fetch は走らない**。 モックサーバは不要。同期的に子プロセスを起動するテスト（`spawnSync`）と 自前のHTTPスタブは**同一プロセスでは併用できない**（spawnSync がイベントループを止めるため スタブが応答できずデッドロックする）ので、この方法が最も素直。 ```js function seedCache(prefix, items) { const home = fs.mkdtempSync(path.join(os.tmpdir(), prefix)); // 本物の設定を壊さない fs.mkdirSync(path.join(home, '.config'), { recursive: true }); fs.writeFileSync(path.join(home, '.config', 'cache.json'), JSON.stringify({ __catalog__: { at: new Date().toISOString(), items } })); return home; } ``` **テストは必ずホームディレクトリを一時ディレクトリへ差し替える** （`HOME` を直接上書きせず、`APP_HOME` のような専用の環境変数を実装側に用意しておく）。 本番の設定・キャッシュ・認証情報を書き換えるテストは、一度事故ると原因究明に何倍もかかる。 ### 3) テストが本当に効いているか（変異テスト） 追加したテストは、**わざと壊して FAIL することを確認**するまで信用しない。 - 修正を元に戻す（`process.exit` を復活させる）→ 該当テストが FAIL するか - 必須リストから項目を消す → 該当テストが FAIL するか 「全部PASS」だけを見て満足すると、何も検査していない空テストが残る。 ## Windows / Linux の両方で通すこと この不具合は **Windows でしか出ない**。 コード生成をコンテナや Linux 上のエージェントに任せている場合、 **生成側は原因となる挙動を一度も観測できない**。 - 実装を委譲しても、**OS依存の検証は必ず手元の実機で行う** - テストは Windows と Linux の両方で走らせる（`node --version` が違えば結果も変わり得る） - 外部CLIを呼ぶ時はシェル経由の引用符に依存しない（`execFileSync` の配列渡しにする） ## 配布物にありがちな「静かに死ぬ」経路（同種のチェックリスト） 1. **起動判定の文字列比較**: `import.meta.url` と `process.argv[1]` の素の比較は、 配布パスが symlink / junction だと外れて `main()` が一度も呼ばれない（出力ゼロ・exit 0）。 realpath で解決し、Windows では大文字小文字を無視して比較する。 2. **設定ファイルの BOM**: UTF-8 BOM 付きで保存された `.env` は、素朴なパーサだと 先頭のキー名が `\uFEFFKEY` になり「未設定」と判定される。全APIキーが黙って無効化される。 パーサを1本に統一し、BOM を自動除去する。 3. **取得失敗の巻き添え**: `pull → 配布 → 登録` を1つの try に入れると、 取得が1回失敗した端末は以後ずっと配布も登録もされない。取得だけ独立した try/catch にする。 4. **新機能を「必須リスト」に載せ忘れる**: 自己修復の仕組みがあっても、 必須リストに入っていない項目は修復されない。**登録処理と必須リストの両方**に載せる。 これもテストで縛れる（必須リストから外すと FAIL するテストを書く）。 5. **hook の timeout**: 重い処理は timeout で毎回殺されるが、 ホスト側が黙って続行するため気づかない。実測で所要時間を測り、 長い処理は切り離して非同期に投げる。 ## 完了の判定基準 次の全部を**実行した結果**で言えるようになるまで「動いた」と言わない。 - [ ] 通常経路・キャッシュ切れ経路・空入力・壊れた入力・上限到達の**全経路で exit 0** - [ ] 各経路の所要時間を計測し、timeout の内側に収まっている - [ ] Windows と Linux の両方でテストが通る - [ ] 追加したテストを意図的に壊して FAIL することを確認した - [ ] 本番の設定ファイル・キャッシュ・認証情報が**変更されていない**ことを確認した - [ ] 配布経路（各端末が実際に取得するURL）を取得し直し、新しい版が返ることを確認した （CDN が数分間 旧版を返すことがある。配布側で吸収してから「配布可」と言う） ---