配布した 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 を使うことが多い。

// 壊れている例
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 で自然終了させる。

// 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) 構造テスト: 危険な書き方をソース文字列で機械的に禁止する

真因が「特定の書き方」なら、その書き方の存在自体をテストで禁止するのが最も安い。

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 がイベントループを止めるため スタブが応答できずデッドロックする）ので、この方法が最も素直。

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 が数分間 旧版を返すことがある。配布側で吸収してから「配布可」と言う）