# 配布した自動化スクリプトが「自分自身を更新できない」問題の根治と、人手ゼロ復旧の3層設計 複数端末へ配った hook / 常駐スクリプト / CLI が、**エラーも出さずに古いまま止まり続ける**のを止めるための設計と点検手順。 「配布したのに誰にも届いていない」は、配布側からは成功に見えるため、気づくまで数か月かかる。 ## 前提となる構成（読み替えて使う） - `<配布リポジトリ>` … 公開 Git リポジトリ。`tools/`（スクリプト）、`skills/`（AIエージェント用の手順書）などを配る - `/<配布リポジトリ名>/` … 各端末に置かれるリポジトリのコピー - `/.<エージェント設定>/hooks/` … セッション開始時などに実行される**フックのコピー置き場** - `<通知チャンネル>` … 実行結果を投げる Webhook（Slack / Discord / Teams など） --- ## 1. 最大の罠: フックの「凍結コピー」 インストーラが `repo/tools/sync.ps1` を `/.<エージェント設定>/hooks/sync.ps1` へ**コピー**し、 設定ファイルにはそのコピーのパスを登録する、という構成は一般的だ。ここに致命的な穴がある。 > **セッション開始時に実行されるのはコピーの方**なので、リポジトリ側の `sync.ps1` をいくら改善しても、 > **そのコピー自身は誰も更新しない**。インストールした日の版が永久に動き続ける。 実際に、7月にインストールした端末が2か月後も7月版のまま動いており、 その間に入れた改善（鍵の配布・新しい手順書の配布）が**1つも届いていなかった**。 ### 対策: 同期に成功した直後、自分自身を置き換える ``` # 疑似コード（リポジトリ同期が成功した直後に実行する） source = /tools/sync.ps1 target = /.<エージェント設定>/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回だけ**実行する。 ```json { "runId": "<毎回ユニークな文字列>", "task": "rules-resync", "targets": "all", "_allowed_tasks": ["verify-setup", "rules-resync", "report"] } ``` - **ホワイトリスト方式が絶対**。`task` を任意コマンドとして実行してはいけない（リポジトリが改竄されたら全端末で任意実行になる） - `runId` を端末側のファイルに記録して二重実行を防ぐ - **注意**: `runId` を「実行前」に記録すると、失敗しても再試行されない。成否も記録して再試行可否を決めるほうがよい - **注意**: タスクの実体を「凍結コピー側」のパスで書かない（層1が層1の問題を踏む）。 必ず**リポジトリ側の最新スクリプト**を優先し、無い場合だけフォールバックする ### 層2: ルール文書に自己修復手順を書く 壊れた端末に**唯一届く経路はルール文書の同期**であることが多い（それがフックの本来の仕事だから）。 そこでルール文書に、AIエージェント自身が実行する判定と復旧を書いておく。 ```markdown ### 自己点検（セッション開始時に1回） 次の3点を確認し、1つでも欠けていたら復旧コマンドを実行する（人には頼まない）。 1. /.<エージェント設定>/skills/<必須skill>/SKILL.md が存在するか 2. /<配布リポジトリ名>/tools/sync.mjs が存在し、最新版の目印となる関数名を含むか 3. 設定ファイルのセッション開始フックに sync.mjs が登録されているか ### 復旧（1コマンド。インストーラを取り直して実行する） <インストーラを取得して実行する1行> ``` **ここで踏みやすい罠**: - **コマンド中に `~` を書かない**。多くのシェルは**引数の中の `~` を展開しない**ので、 `node ~/repo/tools/x.mjs` は必ずファイルが見つからずに落ちる。環境変数か、スクリプト内で `os.homedir()` を使う - **個別ファイルを1本ずつ取り直さない**。依存モジュールが芋づる式に足りず、その都度落ちる。 **一式を入れ直すインストーラ経由が確実** - インストーラが `rm -rf ` 相当で置き換える実装なら、 **未コミットの変更がある作業ツリーは削除せず 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 を返したことは、人が読める形で届いた証拠にはならない ---