# 同期で巻き戻る設定を「固定時刻の貼り直し」で守ろうとして失敗する — 状態の検出で駆動する収束に変える 配布物（zip / パッケージ / 設定の同期）で上書きされるディレクトリに、自前のパッチを当て続けたい。 定番の対処は「同期の直後の時刻に貼り直しジョブを置く」。**これは高い確率で失敗する。** 本書はその診断手順と、時刻に依存しない直し方、そして直したことを検定する方法を示す。 ## 症状 - 貼り直しジョブは**ログ上は成功している**（「適用済み」と出る）。 - なのに、ある時刻を境にパッチが消えている。 - 貼り直しの時刻をずらしても再発する。 ## 1. まず「上書きする側」を特定して、発火の契機と頻度を測る 「いつ走るか」ではなく **「何をきっかけに走るか」** を測る。ここを飛ばすと、ずっと時刻を動かし続けることになる。 ```bash # 配布ディレクトリの実ファイルが最後に書かれた時刻 ls -la --time-style=full-iso <配布ディレクトリ>/<対象ファイル> # 定時ジョブの一覧と最終実行（Windows。cron なら crontab -l と実行ログ） # 名前・トリガ・最終実行・終了コードを一覧化する ``` そのうえで、**上書きする実体のコードを読む**。典型的な作りはこうなっている。 ```js // 同期スクリプトの中核 function syncRepository() { const previous = loadState(); // 例: ~/.config/<配布物>/sync-state.json if (now - previous.last < 24 * 3600 * 1000) return; // ← N時間ガード saveState(now); downloadArchive(); extractAndCopy(); // ← ここで無条件コピー } ``` **このガードが犯人**。「24時間経ってから、最初にイベントが起きた瞬間」に走るので、 壁時計の時刻が**毎日ずれていく**。実測例では前日 03:20、翌日 14:06（34時間47分後）に落ちた。 **固定時刻の貼り直しをどこへ動かしても追いつけない。** ### ついでに確認する: 人の変更を守る保護が効いているか 配布物の同期には「ローカルで変更されたファイルは上書きしない」保護が付いていることがあるが、 **前提が崩れていると丸ごとスキップされる**ことがある。 ```js const hasGit = fs.existsSync(path.join(targetDir, '.git')); // hasGit が false だと、以降の「ローカル変更を除外する」判定が全部飛ぶ ``` 配布先が clone ではなくアーカイブの展開先だと `.git` が無いので、保護は**一度も働かない**。 「保護があるはずなのに消える」ときはここを疑う。 ## 2. 「同期の後段に置く」で解こうとする前に、順序が保証されるか確かめる イベントフック（セッション開始フック等）で同期が走っている場合、 **同一イベントのフックは並列起動する実装が多い**。配列の後ろに置いても後に走る保証は無い。 `async` / `sync` の区別以前の問題なので、まずここを確認する。順序で解けないなら次へ。 ## 3. 直し方: 時刻でなく「当たっているか」で駆動する **推測しない。直接見て、当たっていなければ当てる。** 冪等なら短い間隔で回してよい。 貼り直しツールに「書かずに未適用件数だけ返す」モード（`--check` 等）が既にあるなら、それを再利用するのが最短。 ```js if (ifNeeded && !check) { const probe = run({ check: true }); // 書かない if (probe.pending === 0) { console.log('変更不要（未適用 0 件）'); // 出力は1行だけ process.exitCode = 0; // ← 既知の警告を混ぜない（下記） } else { // ASCII の目印を先頭に置く（呼び出し側の .bat/.cmd が findstr で拾うため） console.log(`REPAIRED 巻き戻りを検出（未適用 ${probe.pending} 件） 同期の最終実行=${syncedAt() ?? '不明'}`); const applied = run({ check: false }); printResult(applied, false); process.exitCode = applied.stale.length ? 3 : (applied.ok ? 0 : 2); } } ``` ### 設計上ゆずれない3点 1. **no-op は静かにする。** 30分おきに回すなら、何もしなかった時は**出力1行・ログ0バイト・exit 0**。 毎回フル出力を吐くと1年で数万行になり、本当に直した回が埋もれる。 2. **no-op の終了コードに「既知の警告」を混ぜない。** 「もう二度と当たらないパッチが N 件ある」といった恒常的な警告で exit 3 を返す作りだと、 スケジューラの最終結果が**常時3**になり、本物の異常を見分けられなくなる。 恒常警告は「1日1回のフル実行」側だけで報告し、収束ジョブは黙らせる。 3. **状態ファイルの読み取りで落ちない。** 同期時刻を証拠として添えるのは有用だが、**それが読めないことを理由に貼り直しを止めない**。 ```js export function syncedAt(stateFile = defaultStatePath) { try { const raw = JSON.parse(fs.readFileSync(stateFile, 'utf8')); return typeof raw.last === 'string' ? raw.last : null; } catch { return null; } // 無い・壊れている・型違い のどれでも null } ``` ### 運用: 「毎日1回のフル実行」と「短間隔の収束」を分ける | ジョブ | 間隔 | 役割 | |---|---|---| | フル実行 | 1日1回 | 心拍。全項目の適用結果と恒常警告を必ずログに残す | | 収束（`--if-needed`） | 30分 | 巻き戻りを検出した時だけ動く。平常時は無音 | ## 4. 検定: 本番を触らずに、対照群で確かめる ### (a) 対象ディレクトリを環境変数で差し替えられるようにする ```js export const TARGET_DIR = path.join(process.env.<ツール名>_ROOT || defaultRoot, 'tools'); ``` 本番の複製に対してだけ走らせれば、実環境を1バイトも変えずに検定できる。 ```bash cp -r <配布ディレクトリ> "$TMP/fake" <ツール名>_ROOT="$TMP/fake" node repair.mjs --if-needed # 1回目: REPAIRED が出て当たる <ツール名>_ROOT="$TMP/fake" node repair.mjs --if-needed # 2回目: 変更不要・exit 0・ログ増分 0 ``` ### (b) 旧版と新版を同じ複製に当てて出力を突き合わせる 既存モードの互換を壊していないことは、**旧版を実際に走らせて diff を取る**まで分からない。 ```bash git show HEAD:tools/repair.mjs > "$OLD/repair.mjs" # ← ファイル名を変えないこと（後述） <ツール名>_ROOT="$FAKE" node "$OLD/repair.mjs" --check > old.txt 2>&1 <ツール名>_ROOT="$FAKE" node tools/repair.mjs --check > new.txt 2>&1 diff old.txt new.txt && echo "出力は新旧で完全一致" ``` 🔴 **落とし穴**: CLI の起動条件が `path.basename(process.argv[1]) === 'repair.mjs'` のような 自己名判定になっていると、**別名で保存した旧版は何も出力せず無言で終わる**。 対照群が「0行 vs 49行」になって偽の不一致が出る。**旧版は同じファイル名でディレクトリを分けて置く。** ## 5. おまけ: `.bat` / `.cmd` で `exit=%RC%>>` がログに書かれない Windows のラッパでよくある事故。 ```bat rem 壊れている: 数字の直後の >> がストリーム番号として解釈され、行が消える echo [%DATE% %TIME%] exit=%RC%>> "%LOG%" rem 正しい: 括弧で囲んで数字と >> を離す (echo [%DATE% %TIME%] exit=%RC%)>> "%LOG%" ``` `%RC%` が `0` なら `exit=0>>` となり、cmd はこれを「ハンドル0（標準入力）のリダイレクト」と読む。 echo はコンソールへ出て、**ログには1行も残らない**。 ログに `exit=` 行が1つも見当たらないときは、ジョブが動いていないのではなくこれを疑う。 なお `.bat` / `.cmd` は ANSI コードページで読まれるため、**UTF-8 の非ASCIIコメントを書かない**。 化けた断片がコマンドとして実行される。先頭でコードページを変えても手遅れ。 ## 6. 収束ジョブのラッパ（動いた時だけログを書く） ```bat @echo off rem Runs every 30 minutes. Only log when something was actually repaired. rem ASCII only. set LOGDIR=%USERPROFILE%\<ログ置き場> if not exist "%LOGDIR%" mkdir "%LOGDIR%" set TMPOUT=%TEMP%\repair-guard.out "" "%~dp0repair.mjs" --if-needed > "%TMPOUT%" 2>&1 set RC=%ERRORLEVEL% findstr /B /C:"REPAIRED" "%TMPOUT%" > nul if %ERRORLEVEL% equ 0 ( echo [%DATE% %TIME%] repair-guard>> "%LOGDIR%\repair.log" type "%TMPOUT%" >> "%LOGDIR%\repair.log" (echo [%DATE% %TIME%] exit=%RC%)>> "%LOGDIR%\repair.log" ) del "%TMPOUT%" 2> nul exit /b %RC% ``` 判定に使う目印は**必ず ASCII**にする。`findstr` に非ASCIIを渡すとコードページで壊れる。 ## 7. 効果の検定は「次に上書きが起きた後」でしかできない 貼り直した直後にパッチが在るのは当たり前で、**上書きがまだ起きていないだけ**かもしれない。 合格を宣言する前に、**上書きジョブが1回走った後**の状態を見る。 上書きの時刻が漂うなら、状態ファイル（同期の `last`）が更新されたことを確認してから判定する。 ## チェックリスト - [ ] 上書きする実体のコードを読み、**発火の契機**（時刻ではなく）を特定した - [ ] ガード（N時間・状態ファイル）の有無を確認し、壁時計時刻が漂うかを判定した - [ ] 「ローカル変更を守る保護」が前提崩れでスキップされていないか確認した - [ ] 同一イベントのフックが並列か逐次かを確認した（並列なら「後段に置く」は捨てる） - [ ] 貼り直しを `--if-needed`（状態検出）に変え、no-op を無音・exit 0 にした - [ ] no-op の終了コードに恒常警告を混ぜていない - [ ] 対象ディレクトリを環境変数で差し替え、**本番の複製**で1回目/2回目を実測した - [ ] 旧版を**同じファイル名**で別ディレクトリに置き、既存モードの出力一致を diff で確認した - [ ] ラッパの `exit=` 行が実際にログに出ることを目視した - [ ] 上書きが1回起きた**後**に、パッチが生存していることを確認した ---