# 作業ツリーが汚れた端末にだけ配布が届かない — フォールバックの自家中毒まで含めて塞ぐ 複数端末へ `git pull` でツール群を配る運用で、**開発に使っている端末にだけ配布が永久に届かない**型の障害。 新規端末でも、きれいな端末でも再現しないため気付けない。さらに素朴に直すと **「1回目は直るが2回目から凍結する」二次不具合**を作り込む。実際に踏んで直した記録。 対象は、配布インストーラ／セッション開始フック／定期実行タスクで複数端末に同じツールを配っている運用者と、 その作業を代行する AI。 --- ## 1. 症状 - 新規端末・きれいな端末では新機能が動く - **開発に使っている端末（未コミットの変更がある／ブランチが分岐している）にだけ届かない** - 同期処理のログには「スキル配布 完了」「フック登録 完了」「設定ファイル更新」と**成功が並ぶ** - テストは全部 green、CI も緑 - 誰もエラーを見ていない（＝静かに何も起きない） ## 2. 原因の型（3つ） ### 2-1. フォールバックの発動条件が「リポジトリが無いこと」になっている よくある実装: ```js if (fs.existsSync(path.join(repoPath, '.git'))) { execFileSync('git', ['-C', repoPath, 'pull', '--ff-only']); // ← 失敗しうる } else { // アーカイブを落として tools/ を上書きコピー（フォールバック） } // ↑ 全体が try{}catch{} で囲まれ、失敗はログ1行で握り潰される ``` `.git` が**在る**のに `pull` が失敗する端末（作業ツリーが汚れている／分岐している）では、 フォールバックへ**行かない**。catch が飲むので tools/ は永久に古いまま。 **正しい条件は「リポジトリが無いこと」ではなく「取得できなかったこと」。** ### 2-2. フォールバックが人の作業を消す／消さないために何もしない アーカイブ展開はたいてい `リポジトリごと削除 → 展開物を移動` で実装される。 未コミットの作業を守るためこれを避けると、結局「汚れた端末を直す経路が一つも無い」状態になる。 **解**: リポジトリは削除せず、**配布対象ディレクトリのファイルだけ**を上書きし、 `git status --porcelain -z --untracked-files=all` に出たパスは**除外**する。 ```js // rename/copy は次の NUL 要素が旧パス。新旧どちらも除外する function parsePorcelainZ(output) { const entries = String(output).split('\0'); const changed = new Set(); for (let i = 0; i < entries.length; i++) { const e = entries[i]; if (!e) continue; const status = e.slice(0, 2); changed.add(e.slice(3).replaceAll('\\', '/')); if (/[RC]/.test(status) && entries[i + 1]) changed.add(entries[++i].replaceAll('\\', '/')); } return changed; } ``` `status` が取得できないときは**1ファイルも書かずに終える**。 黙って人の作業を消すより、届かないほうが安全。 ### 2-3.（本丸）フォールバックが自分の出力を「人の変更」と誤認して凍結する 2-2 を実装すると1回目は正しく直る。**2回目で壊れる。** フォールバックが書いたファイルは、その端末の git から見ると「変更あり」または「未追跡」になる （HEAD は古いコミットのままなので）。次回の実行は**自分が前回書いたファイルを保護対象と誤認**し、 除外リストが膨張して**その版で永久に凍結**する。 実測: 1回目の除外 2 件 → 2回目 **55 件**。届かないより質が悪い。 「更新できている」と表示されたまま古いまま止まる。 **解**: 書き込んだ内容のハッシュを記録し、**自分の出力と人の編集を区別**する。 ```js // 記録: { files: { "<リポジトリ相対パス>": "" }, updatedAt: "" } for (const rel of changedPaths) { const abs = path.join(repo, ...rel.split('/')); if (prev?.files?.[rel] && fs.existsSync(abs) && sha256(abs) === prev.files[rel]) { selfOutput.add(rel); // 前回の自分の出力 → 更新してよい } else { protectedPaths.add(rel); // 人がそのあと編集した → 保護する } } ``` 記録が読めない・壊れている場合は**全部保護**に倒す。 ## 3. 自己修復には循環がある 配布を直す道具そのもの（同期スクリプト）が、**更新できない端末には届かない**。 リポジトリ内のツールで自己修復させようとすると必ず詰む。 **循環を破れるのは「毎回リモートから取り直される要素」だけ**＝インストーラ、 または人が外から1ファイルだけ持ち込む操作。 そのため**インストーラ側にも同じ修復ロジックを入れる**こと。 インストーラだけは配布のたびに最新が取得されるので、唯一の救出経路になる。 応急処置（1回だけ・以後は自動化に戻る）: ``` # 同期スクリプト1本だけをリモートから上書きしてから走らせる /tools/sync.mjs → /tools/sync.mjs node /tools/sync.mjs --force ``` 依存モジュールを解決させるため、**リポジトリ内の元の位置に置いてから**実行する （1本だけ別の場所に置いて実行すると import が連鎖的に落ちる）。 ## 4. 定期タスクが見ているのは本当にそのリポジトリか 見落としやすい前提。**同じリポジトリのチェックアウトが2箇所ある**ことがある。 実例: 同期処理の対象は `/` にハードコードされているのに、 定期実行タスクは `/Downloads/` を指していた。後者は誰も更新しない。 結果、呼び出し側のスクリプトには新しい処理が入っているのに、 そこから呼ぶツールが存在せず「ファイルなし」で毎晩無言で空振りしていた。 ```powershell # 定期タスクが実際に叩くパスを読む。~/ だと決めつけない (Get-ScheduledTask -TaskName '').Actions | % { $_.Arguments } ``` ## 5. 失敗を必ず1行で出す 握り潰しをやめ、**3値**を必ず出力する。 ``` tools を更新しました (git pull) pull できないためアーカイブで更新しました (理由: …) / 人の変更を保護: n件 / 前回の自分の出力なので更新: m件 ⚠ tools を更新できませんでした (理由: …)。この端末は配布が届いていません ``` 「スキル配布 完了」だけが並ぶログは、**配布本体が死んでいても成功に見える**。 ## 6. 検証のしかた（ここを省くと必ず取り逃す） きれいな端末だけで確認して終わらせない。 1. **汚れた作業ツリーを実際に作る** — 古いコミットへ移動し、追跡ファイルを1つ改変、未追跡ファイルを1つ作る 2. **2回連続で実行する** — 1回目だけの確認では 2-3 の自家中毒を取り逃す 3. 毎回この4点をアサートする - 配布物が届いたか - 改変した追跡ファイルと未追跡ファイルが**両方とも無傷**か - 除外件数が**2回目に膨張していない**か - リポジトリ（`.git`）が消えていないか 4. **自分が書いたファイルを人が編集した**場合に保護へ再分類されるかも確認する ## 7. チェックリスト - [ ] フォールバックの条件は「リポジトリが無い」ではなく「取得できなかった」になっているか - [ ] フォールバックはリポジトリを削除していないか - [ ] 変更中・未追跡ファイルを除外しているか（rename の旧パスも） - [ ] 書き込んだ内容のハッシュを記録し、自分の出力と人の編集を区別しているか - [ ] 状態が取得できないとき、1ファイルも書かずに終えているか - [ ] インストーラ側にも同じ修復ロジックが入っているか（循環を破る唯一の経路） - [ ] 定期タスクが見ているパスを実際に読んだか - [ ] 成功・フォールバック・全滅の3値を必ず1行で出しているか - [ ] 汚れた作業ツリーで**2回連続**実行して検証したか ---