配布した自動化スクリプトが「自分自身を更新できない」問題の根治と、人手ゼロ復旧の3層設計

複数端末へ配った hook / 常駐スクリプト / CLI が、エラーも出さずに古いまま止まり続けるのを止めるための設計と点検手順。 「配布したのに誰にも届いていない」は、配布側からは成功に見えるため、気づくまで数か月かかる。

前提となる構成（読み替えて使う）

• <配布リポジトリ> … 公開 Git リポジトリ。tools/（スクリプト）、skills/（AIエージェント用の手順書）などを配る
• <HOME>/<配布リポジトリ名>/ … 各端末に置かれるリポジトリのコピー
• <HOME>/.<エージェント設定>/hooks/ … セッション開始時などに実行されるフックのコピー置き場
• <通知チャンネル> … 実行結果を投げる Webhook（Slack / Discord / Teams など）

---

1. 最大の罠: フックの「凍結コピー」

インストーラが repo/tools/sync.ps1 を <HOME>/.<エージェント設定>/hooks/sync.ps1 へコピーし、 設定ファイルにはそのコピーのパスを登録する、という構成は一般的だ。ここに致命的な穴がある。

セッション開始時に実行されるのはコピーの方なので、リポジトリ側の sync.ps1 をいくら改善しても、 そのコピー自身は誰も更新しない。インストールした日の版が永久に動き続ける。

実際に、7月にインストールした端末が2か月後も7月版のまま動いており、 その間に入れた改善（鍵の配布・新しい手順書の配布）が1つも届いていなかった。

対策: 同期に成功した直後、自分自身を置き換える

# 疑似コード（リポジトリ同期が成功した直後に実行する）
source = <repo>/tools/sync.ps1
target = <HOME>/.<エージェント設定>/hooks/sync.ps1
if exists(target) and hash(source) != hash(target):
    copy(source -> target)
    log("hook updated (effective from next session)")

• コピー先が存在しないときはコピーしない（その端末はコピー方式を使っていない。勝手に増やさない）
• 実行中に自分自身を上書きすることになるが、スクリプトは既に読み込み済みなので問題ない。次回起動から新版
• 失敗しても後続処理を止めない（try/catch でログだけ残す）

ただしこれは「次の凍結」を防ぐだけで、すでに凍結済みの端末は救えない（その版に自己更新処理が無いため）。 既存端末には下の第3層が要る。

---

2. 「実行シェルの違い」で片方の機能だけが静かに死ぬ

インストーラが shell = 新シェルがあれば新シェル、無ければ旧シェル のように分岐している場合、 旧シェルにしか無い制約で一部の処理だけが失敗する。しかも他の処理は生きているので症状が出ない。

実例（Windows）: 新しいシェルなら使える HTTP クライアントのクラスが、旧シェル（プリインストール版）では 既定でロードされておらず解決できない。結果、fetch failed → return となり、 「ルール文書の同期だけ」が全端末で止まっていた。リポジトリ同期は別の try 節にあったので生き延び、 誰も異常に気づかなかった。

対策

• ネットワーク取得は必ず代替経路を用意する（モダンAPIで試し、失敗したら旧シェルでも通る標準コマンドへフォールバック）
• 旧シェルでは TLS のバージョン指定が必要な場合がある（明示的に有効化する）
• 配布物のテストは「最も古い実行環境」で1回実走する。開発機の新シェルで通っても意味がない

---

3. 人手ゼロで直す3層設計

端末の壊れ具合は一様ではない。層を分けて、それぞれに届く経路を用意する。

端末の状態	届く経路	人の操作
スクリプト一式はあるが古い	層1: 中央コマンドキュー	なし
スクリプトが1本も無い（キューを読むツールすら無い）	層2: ルール文書に書いた自己修復手順	なし（普通に使うだけ）
上記が効いたか確認したい	層3: 生存digestの自動通知	なし（読むだけ）

層1: 中央コマンドキュー

リポジトリに1個の JSON を置き、各端末が定期実行時に取得して1回だけ実行する。

{
  "runId": "<毎回ユニークな文字列>",
  "task": "rules-resync",
  "targets": "all",
  "_allowed_tasks": ["verify-setup", "rules-resync", "report"]
}

• ホワイトリスト方式が絶対。task を任意コマンドとして実行してはいけない（リポジトリが改竄されたら全端末で任意実行になる）
• runId を端末側のファイルに記録して二重実行を防ぐ
• 注意: runId を「実行前」に記録すると、失敗しても再試行されない。成否も記録して再試行可否を決めるほうがよい
• 注意: タスクの実体を「凍結コピー側」のパスで書かない（層1が層1の問題を踏む）。 必ずリポジトリ側の最新スクリプトを優先し、無い場合だけフォールバックする

層2: ルール文書に自己修復手順を書く

壊れた端末に唯一届く経路はルール文書の同期であることが多い（それがフックの本来の仕事だから）。 そこでルール文書に、AIエージェント自身が実行する判定と復旧を書いておく。

### 自己点検（セッション開始時に1回）
次の3点を確認し、1つでも欠けていたら復旧コマンドを実行する（人には頼まない）。
1. <HOME>/.<エージェント設定>/skills/<必須skill>/SKILL.md が存在するか
2. <HOME>/<配布リポジトリ名>/tools/sync.mjs が存在し、最新版の目印となる関数名を含むか
3. 設定ファイルのセッション開始フックに sync.mjs が登録されているか

### 復旧（1コマンド。インストーラを取り直して実行する）
<インストーラを取得して実行する1行>

ここで踏みやすい罠:

• コマンド中に ~ を書かない。多くのシェルは引数の中の ~ を展開しないので、 node ~/repo/tools/x.mjs は必ずファイルが見つからずに落ちる。環境変数か、スクリプト内で os.homedir() を使う
• 個別ファイルを1本ずつ取り直さない。依存モジュールが芋づる式に足りず、その都度落ちる。 一式を入れ直すインストーラ経由が確実
• インストーラが rm -rf <repo> 相当で置き換える実装なら、 未コミットの変更がある作業ツリーは削除せず pull のみにするガードを入れる（開発機で実行すると作業が消える）

層3: 生存digestを毎朝1通

「直ったか」を人が目視で突き合わせる作業を残さない。

• 通知先の Webhook は書き込み専用なので、それを読み返して集計することはできない。 読み取り用の資格情報を新設する前に、すでに書き込んでいる先（表計算・DB）を読めるようにする方が安い
• 集計はスケジューラ（CI のスケジュール実行など）に置く。特定の1台の電源状態に依存させない
• 出力例:

🖥 生存digest (YYYY-MM-DD)
✅ 24h以内に報告: N台 — …
⚠️ 24〜72h: N台 — …
🚨 72h超/未報告: N台 — …

• 識別子だけを並べない。人が読める名前と機械ラベルを併記する（作業端末A(HOST-1234)）

---

4. 「緑なのに何も起きない」を必ず潰す

この種の仕組みは失敗を握り潰すと検知不能になる。実際に踏んだもの:

• スケジュール実行は success なのに通知が1通も来ていなかった。原因は取得のタイムアウトを catch して exit 0 していたこと。→ 失敗時は通知先にも失敗を投げ、終了コードを非ゼロにする
• CI の Secret に登録した Webhook が死んでいた（HTTP 404）。各端末のローカル設定にある Webhook は生きていた。 → 中央と端末で同じ秘匿値の生死がズレる。定期的に疎通確認し、生きている値から復元する
• 通知本文の要約を「特定の文字列を含む行だけ」で作ると、対象コマンドの出力形式が違うだけで本文が空になる。 空なら末尾数行をそのまま載せる等のフォールバックを入れる

5. 実装後に必ず実測すること（机上で終わらせない）

1. 偽の凍結コピー（中身が1行だけのファイル）を置いて同期を実行し、実サイズが最新版に置き換わることを確認する
2. 最も古い実行環境で1回実走し、生成物（同期されたルール文書など）が実際にできることを確認する
3. 空のホームディレクトリを作り、環境変数でそこを指して実行し、配布物が実際に配置されることを確認する （「配布しました」とログに出しても、対象ディレクトリの導出が違って1件も置かれないことがある）
4. 通知は投稿後にチャンネルを読み返す。API が 200 を返したことは、人が読める形で届いた証拠にはならない