From 61d3eb38816cad69de95b99db359c45420e787f4 Mon Sep 17 00:00:00 2001
From: gotomts <mh.goto.web@gmail.com>
Date: Sun, 30 Aug 2026 00:38:58 +0900
Subject: [PATCH] =?UTF-8?q?fix(setup):=20cutover=20=E3=81=AE=20skip=20?=
 =?UTF-8?q?=E5=88=A4=E5=AE=9A=E3=81=AB=E5=AE=A3=E8=A8=80=E5=85=A5=E5=8A=9B?=
 =?UTF-8?q?=E3=81=AE=20fingerprint=20=E3=82=92=E5=8A=A0=E3=81=88=E3=82=8B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

migrate は cutover の manifest success を「必須バイナリが実在するか」だけで
再検証していたため、別端末で main を pull して Homebrew 宣言が変わっても
skip され、`sudo zsh setup/migrate.zsh --apply` が新しいアプリを適用しなかった。
必須バイナリは前回の switch のまま残っているので postcondition は満たされ続ける。

直近 success 時の desired-input fingerprint を manifest の detail に記録し、
現在値と一致するときだけ skip するようにした。fingerprint は nix/ 配下の構成
(ファイル内容と symlink の readlink 値) と flake.lock、/etc/dotfiles-role、
~/.config/dotfiles/homebrew.local.nix の内容/不在を材料にする。記録する値は
switch を起動する直前に確定させ、switch 実行中に宣言が変わった場合はその変更を
適用済みとして取りこぼさない。fingerprint の記録が無い旧 manifest は安全側に
1 度だけ再実行し、その実行で記録して以降は通常の skip に戻る。

宣言変更で cutover が日常的に走るようになるため、PAM の扱いも 2 点締める。
cutover 直前に退避した Touch ID ファイル (<target>.before-restore.<timestamp>) は
switch 後の pam 再適用が success し、かつ内容が再適用後の pam.d/sudo_local と
byte-for-byte 一致するときだけ削除する。cutover / pam の失敗時と、手書き追加ルール等で
内容が一致しない場合はその内容の唯一の控えなので残す。削除はこの実行が作った 1 パスだけを
追跡して行い、別の実行が残した退避ファイルには触れない。
また <target> が pristine でないのに .before-setup が無い場合は、pristine が何だったかの
記録が無いまま上書きすることになるため switch 前に停止する (fail-closed)。
<target> 自体が無い真の初回はこれまでどおり通す。

既存の必須バイナリ postcondition と PAM の fail-closed 保証はそのまま維持する。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 setup/README.md          |  12 +-
 setup/migrate.zsh        | 248 +++++++++++++++++--
 setup/tests/migrate.bats | 505 ++++++++++++++++++++++++++++++++++++---
 3 files changed, 710 insertions(+), 55 deletions(-)

diff --git a/setup/README.md b/setup/README.md
index e25aa56..e0fbc60 100644
--- a/setup/README.md
+++ b/setup/README.md
@@ -39,6 +39,15 @@ success したステップは再実行しない（idempotent）。全ステッ
 非ゼロ終了コードを返し続ける（部分適用を健全な状態として扱わない）。`SUDO_USER` が特定できない
 環境（sudo を介さない直接 root ログイン等）では非 root ステップは blocked のまま止まる。
 
+例外は `cutover`（`darwin-rebuild switch`）で、manifest の success だけでは skip しない。
+必須 Homebrew バイナリ（mise/starship）の実在に加え、直近 success 時に記録した
+desired-input fingerprint — `nix/` 配下の構成と `flake.lock`、`/etc/dotfiles-role`、
+`~/.config/dotfiles/homebrew.local.nix` — が現在値と一致するかを毎回検証し、変わっていれば
+同じ `--apply` の中で再実行する。`git pull` で Homebrew 宣言が変わった端末で `--apply` が
+「全部 success 済み」と判断して何も適用しない、という取りこぼしを防ぐため。fingerprint の記録が
+無い古い manifest は安全側に 1 度だけ再実行する（その実行で記録され、以降は通常どおり skip
+に戻る）。何が再実行されるかは `--dry-run` で事前に確認できる。
+
 個別スクリプトの直接実行はメンテナンス目的（単体テスト・特定ステップだけをデバッグしたい場合等）
 でのみ行う:
 
@@ -101,7 +110,8 @@ symlink 越しに即座に反映される。再実行が必要なのは「`setup
   `claude-sync`/`codex-sync`/`herdr-sync`)。`languages.zsh` 自身が「mise は darwin-switch で事前導入
   済みが前提」と明記しているため、cutover を languages より先に置く。各ステップの結果は
   `~/.dotfiles-migrate/manifest.log` に永続化し、success 済みステップは再実行しない
-  （idempotent な部分適用検出・再開）。権限不足なステップは blocked として記録し、その
+  （idempotent な部分適用検出・再開）。ただし `cutover` だけは、必須バイナリの実在と
+  desired-input fingerprint の一致（宣言側が変わっていないこと）も満たすときにのみ skip する。権限不足なステップは blocked として記録し、その
   Phase 内の残りは試行を続けるが次の Phase へは進まない（Phase 境界は厳格）。実失敗は
   即座に全体を停止する（fail-closed）。`rollback.zsh` は一切呼ばない（no-automatic-rollback、
   常に人間の明示判断）。全ステップ success 後も、manifest の自己申告を信用せず各ステップの
diff --git a/setup/migrate.zsh b/setup/migrate.zsh
index 0ba03c5..b9aeb5b 100755
--- a/setup/migrate.zsh
+++ b/setup/migrate.zsh
@@ -47,12 +47,19 @@
 #     残りステップだけ試行を続け、Phase 境界は厳格に守る（次の Phase には進まない）
 #   - 冪等検知: manifest に success の記録があるステップは再実行せず skip する。
 #     これにより「部分適用済みの実機」を安全に検出・再開できる。ただし cutover は
-#     manifest の success だけでは skip 可としない: postcondition（mise/starship 等、
-#     desired Homebrew set の必須バイナリが実在すること）も満たしているか都度再検証する
-#     （migrate::skippable）。desired set が switch 後に変わった場合（例: starship を
-#     後から追加）、古い success はもう postcondition を保証しないため、その場合は
-#     manifest に `postcondition-unmet` を記録したうえで同じ --apply 内で cutover を
-#     再実行する（実機インシデント、2026-08-22）
+#     manifest の success だけでは skip 可としない。次の 2 つを都度再検証し、どちらかが
+#     崩れていれば manifest に `postcondition-unmet` を記録したうえで同じ --apply 内で
+#     cutover を再実行する（migrate::skippable / migrate::cutover_rerun_reason）:
+#       1. postcondition（mise/starship 等、desired Homebrew set の必須バイナリが実在
+#          すること）。desired set が switch 後に変わった場合（例: starship を後から
+#          追加）、古い success はもう postcondition を保証しない（実機インシデント、
+#          2026-08-22）
+#       2. 直近 success 時に記録した desired-input fingerprint（nix/ 配下の構成と
+#          flake.lock、/etc/dotfiles-role、~/.config/dotfiles/homebrew.local.nix）が
+#          現在値と一致すること。1 だけでは「main を pull して宣言にアプリが増えた」
+#          ケースを検出できない（必須バイナリは前回の switch のまま残っているので
+#          skip され、増えたアプリが適用されない）。fingerprint の記録が無い旧 manifest
+#          は安全側に 1 度だけ再実行する
 #   - PAM/cutover の所有権結合: nix-darwin の activation は pam.d/sudo_local を
 #     「macOS 純正デフォルトへの symlink であること」以外一切許容しない（許容ハッシュが
 #     常に空）。setup/pam.zsh が Touch ID 内容へ書き換え済みの状態で switch すると
@@ -64,7 +71,11 @@
 #     再実行されるたびに同じ手順を踏む（実機インシデント、2026-08-22）。復元自体は
 #     既存の宛先へ直接 mv せず、nix-darwin 自身の /etc 置換手順と同じ「新規パスへ退避
 #     してから空いたパスへ置く」形を取る（既存宛先への直接 mv は macOS 側が
-#     "Operation not permitted" を返した実機インシデントあり、2026-08-23）
+#     "Operation not permitted" を返した実機インシデントあり、2026-08-23）。退避した
+#     ファイルは、switch 後の pam 再適用が success し、かつ内容が再適用後の pam.d/sudo_local
+#     と byte-for-byte 一致するときだけ削除する（複製にすぎないと確認できた場合のみ）。
+#     cutover か pam が失敗した場合、および手書き追加ルール等で内容が一致しない場合は
+#     その内容の唯一の控えなので残す（migrate::pam_discard_vacated）
 #   - 部分適用は健全な状態として扱わない: 全ステップが success になるまで
 #     --apply は終了コード 1 を返し続ける。「動いているように見える」ことは
 #     完了の根拠にしない（health check で実ファイル/実状態を確認する）
@@ -91,6 +102,10 @@ PHASE1_STEPS=(link)
 PHASE2_STEPS=(cutover pam)
 PHASE3_STEPS=(languages defaults claude-sync codex-sync herdr-sync)
 
+# この --apply の中で cutover 直前に退避した Touch ID ファイルのパス（
+# migrate::pam_restore_pristine_if_safe が設定し、migrate::pam_discard_vacated が使う）。
+MIGRATE_PAM_VACATED_PATH=""
+
 migrate::script_for() {
     echo "${SETUP_DIR}/${1}.zsh"
 }
@@ -255,6 +270,86 @@ migrate::command_available() {
     PATH="${homebrew_paths}:${PATH}" command -v "${name}" &>/dev/null
 }
 
+# migrate::nix_dir  fingerprint の対象にする nix 宣言ディレクトリ。テストでは
+#   MIGRATE_NIX_DIR_OVERRIDE で差し替える（このリポジトリ自身の nix/ を書き換えずに
+#   「宣言が変わった」状況を再現するため）。
+migrate::nix_dir() {
+    echo "${MIGRATE_NIX_DIR_OVERRIDE:-${SETUP_DIR:h}/nix}"
+}
+
+# migrate::fingerprint_entry <label> <path>
+#   fingerprint 材料の 1 行を出力する。ファイルの内容だけでなく「不在」も明示的に
+#   区別する（不在 -> 在、在 -> 不在のどちらも desired set を変えるため）。
+#   変数名に `path` を使わないこと: zsh の `path` は PATH に結び付いた特殊配列で、
+#   `local path=...` はこの関数の中だけ PATH を壊し、shasum すら解決できなくなる。
+migrate::fingerprint_entry() {
+    local label="${1}" entry_path="${2}"
+    if [[ -f "${entry_path}" ]]; then
+        printf '%s\tpresent\t%s\n' "${label}" "$(shasum -a 256 "${entry_path}" | awk '{print $1}')"
+    else
+        printf '%s\tabsent\n' "${label}"
+    fi
+}
+
+# migrate::cutover_fingerprint  「次の switch の desired set を決める入力」の要約を返す。
+#   材料:
+#     - nix/ 配下の全ファイル（相対パス + 内容ハッシュ）。flake.lock・homebrew.nix・
+#       role 分岐・plist/rb などの実データを一括で覆う。ファイルの追加・削除も
+#       相対パスの一覧ごとハッシュするため検出できる
+#     - nix/ 配下の symlink（相対パス + readlink 値）。リンク先を辿って内容を読むと、
+#       リンクの張り替え自体（同じ内容の別ファイルへ向け直す等）を取りこぼすうえ、
+#       dangling link で毎回 fingerprint が揺れる。リンクそのものを材料にする
+#     - /etc/dotfiles-role の内容/不在（flake.nix が role を読んで desired set を切り替える）
+#     - ~/.config/dotfiles/homebrew.local.nix の内容/不在（homebrew.nix が絶対パスで
+#       import する、リポジトリ外の PC ローカル overlay）
+#   nix/ 配下は「switch の結果に効かないファイル」（README 等）も含めて丸ごと覆う。
+#   実際に効く入力だけを allowlist すると、宣言側の構造が変わったときに allowlist だけが
+#   古くなり「変更を検知できない」死角が生まれる。余分な再実行（switch は冪等）より
+#   検知漏れの方が高くつくため、安全側に倒している。
+#   パスは nix ディレクトリからの相対で組むので、チェックアウト位置（~/.dotfiles か
+#   worktree か）が変わっても fingerprint は変わらない。
+migrate::cutover_fingerprint() {
+    local nix_dir role_file home_dir
+    nix_dir="$(migrate::nix_dir)"
+    role_file="${DOTFILES_ROLE_FILE:-/etc/dotfiles-role}"
+    home_dir="$(migrate::effective_home)"
+
+    {
+        if [[ -d "${nix_dir}" ]]; then
+            # `result`/`result-*` は nix build の成果物 symlink（nix/.gitignore 済み）で
+            # 宣言ではないため除外する。
+            ( cd "${nix_dir}" && \
+              find . \( -name 'result' -o -name 'result-*' \) -prune -o -type f -print \
+              | LC_ALL=C sort \
+              | while IFS= read -r f; do
+                    printf 'nix\t%s\t%s\n' "${f}" "$(shasum -a 256 "${f}" | awk '{print $1}')"
+                done )
+            ( cd "${nix_dir}" && \
+              find . \( -name 'result' -o -name 'result-*' \) -prune -o -type l -print \
+              | LC_ALL=C sort \
+              | while IFS= read -r l; do
+                    printf 'nix-link\t%s\t%s\n' "${l}" "$(readlink "${l}")"
+                done )
+        else
+            printf 'nix\tabsent\n'
+        fi
+        migrate::fingerprint_entry "role" "${role_file}"
+        migrate::fingerprint_entry "homebrew-local" "${home_dir}/.config/dotfiles/homebrew.local.nix"
+    } | shasum -a 256 | awk '{print $1}'
+}
+
+# migrate::recorded_cutover_fingerprint
+#   manifest 上の cutover の最新の終端イベントに記録された fingerprint を返す。
+#   fingerprint の概念が無かった頃の manifest（legacy）では detail が空なので、
+#   空文字列を返す = 「記録なし」として呼び出し側が安全側に倒す。
+migrate::recorded_cutover_fingerprint() {
+    [[ -f "${MANIFEST}" ]] || { echo ""; return 0; }
+    awk -F'\t' \
+        '$2=="cutover" && ($3=="success"||$3=="fail"||$3=="blocked"||$3=="invalidated") {line=$4}
+         END{ if (line ~ /^fingerprint=/) { sub(/^fingerprint=/, "", line); print line } }' \
+        "${MANIFEST}"
+}
+
 # migrate::cutover_missing_bins  cutover の postcondition として必須の Homebrew バイナリの
 #   うち、現在見つからないものを空白区切りで返す（空文字列なら全部揃っている）。mise は
 #   languages.zsh が、starship は ~/.zshrc の prompt 初期化が直接依存する。homebrew.nix の
@@ -270,17 +365,51 @@ migrate::cutover_missing_bins() {
     echo "${missing[@]}"
 }
 
+# migrate::cutover_rerun_reason
+#   manifest 上 cutover が success のときに、それでも再実行すべき理由を 1 行で返す
+#   （空文字列なら skip 可）。cutover の postcondition は 2 つある:
+#     1. 必須 Homebrew バイナリが実在すること（switch の効果が残っているか）
+#     2. 直近 success 時に記録した desired-input fingerprint が現在値と一致すること
+#        （宣言側が変わっていないか）
+#   1 だけでは「main を pull して homebrew.nix にアプリが増えた」ケースを検出できない。
+#   必須バイナリは前回の switch で入ったまま残っているので、宣言が変わっても skip され、
+#   新しいアプリが永遠に適用されない。2 はその死角を塞ぐ。
+#   fingerprint の記録が無い legacy manifest は「一致しない」扱いにして安全側に 1 度だけ
+#   再実行する（その再実行で fingerprint が記録され、以降は通常どおり skip に戻る）。
+migrate::cutover_rerun_reason() {
+    local missing recorded current
+    missing="$(migrate::cutover_missing_bins)"
+    if [[ -n "${missing}" ]]; then
+        echo "missing: ${missing}"
+        return 0
+    fi
+
+    recorded="$(migrate::recorded_cutover_fingerprint)"
+    if [[ -z "${recorded}" ]]; then
+        echo "fingerprint: 前回 success に宣言入力の記録がありません（旧 manifest のため安全側に 1 度だけ再実行します）"
+        return 0
+    fi
+
+    current="$(migrate::cutover_fingerprint)"
+    if [[ "${recorded}" != "${current}" ]]; then
+        echo "fingerprint: 宣言入力が変わりました（記録: ${recorded[1,12]} / 現在: ${current[1,12]}）"
+        return 0
+    fi
+
+    echo ""
+}
+
 # migrate::skippable <step>  そのステップを「manifest 上 success だから skip してよい」と
-#   判定してよいか。cutover は manifest の自己申告だけでなく、postcondition（必須 Homebrew
-#   バイナリの実在）も満たしているときのみ skip 可とする。desired Homebrew set が switch 後に
-#   変わった場合（例: starship を追加）、古い success はもう postcondition を保証しない。
+#   判定してよいか。cutover は manifest の自己申告だけでなく、postcondition
+#   （migrate::cutover_rerun_reason 参照: 必須 Homebrew バイナリの実在 + desired-input
+#   fingerprint の一致）も満たしているときのみ skip 可とする。
 #   health check（apply 完了後の独立検証）と同じ「manifest の自己申告を信用しない」方針を
 #   skip 判定そのものにも適用する（実機インシデント、2026-08-22）。
 migrate::skippable() {
     local step="${1}"
     [[ "$(migrate::latest_status "${step}")" == "success" ]] || return 1
     if [[ "${step}" == "cutover" ]]; then
-        [[ -z "$(migrate::cutover_missing_bins)" ]] || return 1
+        [[ -z "$(migrate::cutover_rerun_reason)" ]] || return 1
     fi
     return 0
 }
@@ -331,10 +460,12 @@ migrate::pam_static_default() {
 #   （<target>.before-restore.<timestamp>）へ退避し、それが完了してから
 #   <backup> を <target> へ移す（こちらも「空になったパスへ mv」であり置換ではない）。
 #
-#   バックアップが存在しない（真の初回、pam.zsh がまだ一度も走っていない）場合や、
-#   <target> が既に pristine（想定どおりの symlink）な場合は何もせず 0 を返す。
+#   <target> が既に pristine（想定どおりの symlink）な場合、および <target> と
+#   バックアップの両方が存在しない（真の初回、pam.zsh がまだ一度も走っていない）場合は
+#   何もせず 0 を返す。<target> が存在して pristine でないのにバックアップが無い場合は、
+#   pristine が何だったかの記録が無いまま上書きすることになるため fail-closed で 1 を返す。
 #   バックアップが存在するのに symlink でない、リンク先が想定と異なる、または
-#   退避先パスが既に存在する（想定外の残骸の可能性）場合は fail-closed で 1 を返し、
+#   退避先パスが既に存在する（想定外の残骸の可能性）場合も fail-closed で 1 を返し、
 #   呼び出し側は switch を実行してはならない（不明な状態を盲信して復元しない）。
 #   退避先の時刻部分はテストでは MIGRATE_PAM_VACATE_SUFFIX_OVERRIDE で固定できる
 #   （秒境界をまたぐ flaky なテストを避けるため）。
@@ -351,7 +482,17 @@ migrate::pam_restore_pristine_if_safe() {
     fi
 
     if [[ ! -e "${backup}" && ! -L "${backup}" ]]; then
-        return 0
+        # バックアップが無いケースは 2 つあり、扱いが正反対になる。
+        #   <target> も無い: 真の初回（pam.zsh がまだ一度も走っていない）。restore する
+        #     ものも守るものも無く、nix-darwin から見ても既に pristine なので通す。
+        #   <target> はある: pam.zsh か人が書いた非 pristine な内容が居座っているのに、
+        #     pristine が何だったかの記録が無い。ここで内容を推測して上書きすると、
+        #     その内容を記録している唯一のファイルを壊す。switch 前に停止する。
+        if [[ ! -e "${target}" && ! -L "${target}" ]]; then
+            return 0
+        fi
+        util::error "pam: ${target} は pristine ではないのに ${backup} がありません（pristine の記録が無いため内容を推測して復元しません）"
+        return 1
     fi
 
     if [[ ! -L "${backup}" ]]; then
@@ -375,6 +516,7 @@ migrate::pam_restore_pristine_if_safe() {
         fi
         util::action "pam: cutover 実行前に ${target} を ${vacate_name} へ退避します（既存宛先への直接 mv はしない）"
         /bin/mv "${target}" "${vacate_name}"
+        MIGRATE_PAM_VACATED_PATH="${vacate_name}"
         migrate::log_event "pam" "vacated" "${target} moved to ${vacate_name} pending switch"
     fi
 
@@ -382,6 +524,54 @@ migrate::pam_restore_pristine_if_safe() {
     /bin/mv "${backup}" "${target}"
 }
 
+# migrate::pam_discard_vacated
+#   同じ --apply の中で cutover 直前に退避した Touch ID ファイル（
+#   migrate::pam_restore_pristine_if_safe が作った <target>.before-restore.<timestamp>）を
+#   後始末する。呼ぶのは「switch 後の pam 再適用が success した直後」だけ。その時点で
+#   pam.zsh が Touch ID 内容を書き直しているので、退避ファイルはその複製にすぎない。
+#
+#   宣言側の変更で cutover が日常的に走るようになったため、掃除しないと switch のたびに
+#   <target>.before-restore.<timestamp> が /etc/pam.d に増え続ける。一方で cutover か pam の
+#   どちらかが失敗した場合、この退避ファイルは Touch ID 内容の唯一の控えなので絶対に
+#   消さない（失敗時はこの関数に到達しない）。
+#
+#   削除対象はこの実行が自分で作った 1 パスだけを追跡して指す。glob で
+#   <target>.before-restore.* をまとめて消すことはしない（別の実行が残した、まだ復旧に
+#   使うかもしれない退避ファイルを巻き込むため）。
+#
+#   さらに「通常ファイルであること」だけでは削除の根拠にしない: 退避ファイルの内容が
+#   再適用後の <target> と byte-for-byte 一致することまで確認する。pam.zsh は自前の
+#   固定テンプレートで <target> を書き直すので、この PC で手書き追加したルール
+#   （pam_reattach 行など）は退避コピーの側にしか残らない。一致しないものを消すと、
+#   その内容の唯一の控えを破壊することになる。一致しなければ削除せず警告を残すが、
+#   pam ステップ自体は success のまま扱う（掃除の見送りは失敗ではない）。
+migrate::pam_discard_vacated() {
+    local vacated="${MIGRATE_PAM_VACATED_PATH}"
+    [[ -n "${vacated}" ]] || return 0
+    MIGRATE_PAM_VACATED_PATH=""
+
+    if [[ ! -f "${vacated}" || -L "${vacated}" ]]; then
+        util::warning "pam: 退避ファイル ${vacated} が想定外の形のため削除しません（手動で確認してください）"
+        migrate::log_event "pam" "vacated-kept" "${vacated} left in place (unexpected shape)"
+        return 0
+    fi
+
+    # `cmp` の非ゼロ終了（内容不一致=1 / 読めない等のエラー=2）で set -e に
+    # 巻き込まれないよう、|| で受けてから判定する。
+    local target="${SUDO_LOCAL_PATH:-/etc/pam.d/sudo_local}"
+    local cmp_rc=0
+    cmp -s "${vacated}" "${target}" || cmp_rc=$?
+    if (( cmp_rc != 0 )); then
+        util::warning "pam: 退避ファイル ${vacated} の内容が現在の ${target} と一致しないため削除しません（この PC 固有の手書き設定が含まれている可能性があります）"
+        migrate::log_event "pam" "vacated-kept" "${vacated} differs from ${target}; left in place"
+        return 0
+    fi
+
+    util::action "pam: 再適用後の ${target} と同内容のため退避ファイル ${vacated} を削除します"
+    /bin/rm -f "${vacated}"
+    migrate::log_event "pam" "vacated-discarded" "${vacated} removed after pam reapplied"
+}
+
 # migrate::run_as_original_user <user> <script>
 #   非 root ステップを root 起動から元ユーザーへ委譲実行する。`-H` で HOME も元ユーザーの
 #   ものに補正する（sudo の env_reset で $HOME が /var/root 化する事故を避けるため）。
@@ -422,15 +612,20 @@ migrate::run_step() {
         # skippable が false なのに manifest は success = postcondition 不一致
         # （現状 cutover のみ該当）。success のまま黙って再実行はせず、manifest に
         # 理由を残してから通常の実行フローに合流する。
-        local missing
-        missing="$(migrate::cutover_missing_bins)"
-        util::warning "${step}: 既に success ですが postcondition 未達成のため再実行します (missing: ${missing})"
-        migrate::log_event "${step}" "postcondition-unmet" "missing: ${missing}"
+        local reason
+        reason="$(migrate::cutover_rerun_reason)"
+        util::warning "${step}: 既に success ですが postcondition 未達成のため再実行します (${reason})"
+        migrate::log_event "${step}" "postcondition-unmet" "${reason}"
     fi
 
     local script euid_val rc
     script="$(migrate::script_for "${step}")"
     euid_val="$(migrate::euid)"
+    # cutover の success に記録する fingerprint は、switch を起動する直前に確定させる
+    # （下の cutover 分岐を参照）。switch 完了後に取ると、switch 実行中に宣言が変わった
+    # 場合（switch の最中に git pull が着地する等）その変更を「適用済み」として記録して
+    # しまい、次回以降 skip され続けて永遠に適用されない。
+    local cutover_fingerprint=""
 
     util::action "${step}: 実行開始 (${script})"
     migrate::log_event "${step}" "start"
@@ -444,6 +639,7 @@ migrate::run_step() {
             # 先（元ユーザーの実ホーム）と食い違う場所を見に行ってしまう。
             local pam_target="${SUDO_LOCAL_PATH:-/etc/pam.d/sudo_local}"
             if migrate::pam_restore_pristine_if_safe "${pam_target}"; then
+                cutover_fingerprint="$(migrate::cutover_fingerprint)"
                 if USER="$(migrate::original_user)" HOME="$(migrate::effective_home)" zsh "${script}"; then
                     rc=0
                     # switch は pam.d/sudo_local を pristine でないと受け付けないため
@@ -475,7 +671,17 @@ migrate::run_step() {
 
     if (( rc == 0 )); then
         util::info "${step}: success"
-        migrate::log_event "${step}" "success"
+        # cutover の success には、その switch が実際に読んだ desired-input fingerprint
+        # （switch 起動直前に確定させた値）を併記する。次回以降の skip 判定はこの記録と
+        # 現在値の一致で行う（migrate::cutover_rerun_reason）。
+        local success_detail=""
+        if [[ "${step}" == "cutover" ]]; then
+            success_detail="fingerprint=${cutover_fingerprint}"
+        fi
+        migrate::log_event "${step}" "success" "${success_detail}"
+        if [[ "${step}" == "pam" ]]; then
+            migrate::pam_discard_vacated
+        fi
         return 0
     else
         util::error "${step}: 失敗しました"
@@ -626,7 +832,7 @@ migrate::dry_run() {
             elif ! migrate::privilege_ok "${step}"; then
                 echo "  [BLOCKED] ${step}: $(migrate::privilege_hint "${step}")"
             elif [[ "$(migrate::latest_status "${step}")" == "success" ]]; then
-                echo "  [WOULD RUN] ${step}: postcondition 未達成のため再実行 (missing: $(migrate::cutover_missing_bins))"
+                echo "  [WOULD RUN] ${step}: postcondition 未達成のため再実行 ($(migrate::cutover_rerun_reason))"
             else
                 echo "  [WOULD RUN] ${step}: $(migrate::script_for "${step}")"
             fi
diff --git a/setup/tests/migrate.bats b/setup/tests/migrate.bats
index eceb47c..24783ac 100644
--- a/setup/tests/migrate.bats
+++ b/setup/tests/migrate.bats
@@ -108,7 +108,7 @@ EOF
 setup() {
     export HOME="${BATS_TEST_TMPDIR}/home"
     mkdir -p "${HOME}"
-    unset MIGRATE_STATE_DIR MIGRATE_EUID_OVERRIDE MIGRATE_UNAME_OVERRIDE MIGRATE_SUDO_USER_OVERRIDE SUDO_USER
+    unset MIGRATE_STATE_DIR MIGRATE_EUID_OVERRIDE MIGRATE_UNAME_OVERRIDE MIGRATE_SUDO_USER_OVERRIDE MIGRATE_NIX_DIR_OVERRIDE SUDO_USER
     # The sandbox has no real second user for dscl to resolve "testuser"
     # against. Since the sandbox also has no real privilege separation
     # (root and the "original user" are the same process either way), point
@@ -116,6 +116,15 @@ setup() {
     export MIGRATE_HOME_FOR_USER_OVERRIDE="${HOME}"
     export DOTFILES_ROLE_FILE="${BATS_TEST_TMPDIR}/no-such-role-file"
     export SUDO_LOCAL_PATH="${BATS_TEST_TMPDIR}/sudo_local"
+    # Model a real machine's starting shape: nix-darwin owns /etc/pam.d/sudo_local
+    # and leaves it as a symlink to the macOS static default until setup/pam.zsh
+    # customizes it. Starting from a nonexistent target instead would make
+    # pam.zsh skip its backup step entirely, so no cutover rerun could ever
+    # restore pristine state -- a state this sandbox should not be modelling as
+    # the norm.
+    export SUDO_LOCAL_STATIC_DEFAULT="${BATS_TEST_TMPDIR}/etc-static-sudo_local"
+    : > "${SUDO_LOCAL_STATIC_DEFAULT}"
+    ln -s "${SUDO_LOCAL_STATIC_DEFAULT}" "${SUDO_LOCAL_PATH}"
 
     STUB_BIN="${BATS_TEST_TMPDIR}/stub-bin"
     NODE_BIN_DIR="${BATS_TEST_TMPDIR}/mise-node-bin"
@@ -242,7 +251,9 @@ setup() {
     [ -L "${HOME}/.zshrc" ]
 
     # Phase 2 (root-only) never attempted.
-    [ ! -f "${SUDO_LOCAL_PATH}" ]
+    run cat "${SUDO_LOCAL_PATH}"
+    [[ "${output}" != *"pam_tid.so"* ]]
+    [ ! -e "${SUDO_LOCAL_PATH}.before-setup" ]
     run cat "${DARWIN_REBUILD_LOG}"
     [ -z "${output}" ]
 
@@ -338,7 +349,9 @@ EOF
     # cutover failed before switch; pam (later in the same phase) never ran.
     run cat "${DARWIN_REBUILD_LOG}"
     [[ "${output}" != *"switch"* ]]
-    [ ! -f "${SUDO_LOCAL_PATH}" ]
+    run cat "${SUDO_LOCAL_PATH}"
+    [[ "${output}" != *"pam_tid.so"* ]]
+    [ ! -e "${SUDO_LOCAL_PATH}.before-setup" ]
 
     run cat "${HOME}/.dotfiles-migrate/manifest.log"
     [[ "${output}" == *$'\t'"cutover"$'\t'"fail"* ]]
@@ -391,14 +404,6 @@ EOF
 }
 
 @test "apply: cutover rerun safely restores pristine PAM state before switch and force-reapplies pam after (PAM ownership fix, 2026-08-22 real-machine incident)" {
-    # Model production: /etc/pam.d/sudo_local starts as a symlink to the
-    # macOS static default, exactly like a real un-migrated machine, so
-    # setup/pam.zsh's own (real, unstubbed) backup-and-customize logic runs
-    # for real here rather than being short-circuited by a nonexistent target.
-    export SUDO_LOCAL_STATIC_DEFAULT="${BATS_TEST_TMPDIR}/etc-static-sudo_local"
-    : > "${SUDO_LOCAL_STATIC_DEFAULT}"
-    ln -s "${SUDO_LOCAL_STATIC_DEFAULT}" "${SUDO_LOCAL_PATH}"
-
     # First single-invocation run reaches full success, including pam.zsh's
     # real first-time backup (creates ${SUDO_LOCAL_PATH}.before-setup
     # pointing at the static default) and Touch ID write.
@@ -415,8 +420,6 @@ EOF
     # pam.d/sudo_local unless it's put back to pristine first.
     rm -f "${STUB_BIN}/starship"
     export MIGRATE_PAM_VACATE_SUFFIX_OVERRIDE="rerun1"
-    local touch_id_content_before
-    touch_id_content_before="$(cat "${SUDO_LOCAL_PATH}")"
 
     MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
         run zsh "${SETUP_DIR}/migrate.zsh" --apply
@@ -426,18 +429,18 @@ EOF
 
     # The exact vacate->restore sequence, verifiable via the audit trail this
     # leaves behind: the live Touch ID file was moved aside (not replaced
-    # in-place) to a fresh, never-before-used path, still holding its
-    # pre-switch content untouched.
-    [ -e "${SUDO_LOCAL_PATH}.before-restore.rerun1" ]
-    [ ! -L "${SUDO_LOCAL_PATH}.before-restore.rerun1" ]
-    run cat "${SUDO_LOCAL_PATH}.before-restore.rerun1"
-    [ "${output}" = "${touch_id_content_before}" ]
+    # in-place) to a fresh, never-before-used path. Since pam then reapplied
+    # successfully, that one vacate file is cleaned up again (its content is
+    # a duplicate of what pam.zsh just rewrote) -- see the dedicated
+    # preservation tests for what happens when cutover or pam fails.
+    [ ! -e "${SUDO_LOCAL_PATH}.before-restore.rerun1" ]
 
     # pam's manifest shows the vacate event, an explicit invalidation, then a
-    # fresh start+success -- not a silent skip.
+    # fresh start+success, then the cleanup -- not a silent skip.
     run cat "${HOME}/.dotfiles-migrate/manifest.log"
-    [[ "${output}" == *$'\t'"pam"$'\t'"vacated"* ]]
+    [[ "${output}" == *$'\t'"pam"$'\t'"vacated"$'\t'*"${SUDO_LOCAL_PATH}.before-restore.rerun1"* ]]
     [[ "${output}" == *$'\t'"pam"$'\t'"invalidated"* ]]
+    [[ "${output}" == *$'\t'"pam"$'\t'"vacated-discarded"$'\t'*"${SUDO_LOCAL_PATH}.before-restore.rerun1"* ]]
     [ "$(grep -c $'\t'pam$'\t'success "${HOME}/.dotfiles-migrate/manifest.log")" -eq 2 ]
 
     # After the whole run, pam's Touch ID content is back (pam.zsh's own
@@ -452,10 +455,6 @@ EOF
 }
 
 @test "apply: cutover rerun refuses (fail-closed) when the PAM vacate destination already exists" {
-    export SUDO_LOCAL_STATIC_DEFAULT="${BATS_TEST_TMPDIR}/etc-static-sudo_local"
-    : > "${SUDO_LOCAL_STATIC_DEFAULT}"
-    ln -s "${SUDO_LOCAL_STATIC_DEFAULT}" "${SUDO_LOCAL_PATH}"
-
     MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
         run zsh "${SETUP_DIR}/migrate.zsh" --apply
     [ "${status}" -eq 0 ]
@@ -487,10 +486,6 @@ EOF
 }
 
 @test "apply: cutover rerun refuses (fail-closed) when the PAM backup isn't a symlink" {
-    export SUDO_LOCAL_STATIC_DEFAULT="${BATS_TEST_TMPDIR}/etc-static-sudo_local"
-    : > "${SUDO_LOCAL_STATIC_DEFAULT}"
-    ln -s "${SUDO_LOCAL_STATIC_DEFAULT}" "${SUDO_LOCAL_PATH}"
-
     MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
         run zsh "${SETUP_DIR}/migrate.zsh" --apply
     [ "${status}" -eq 0 ]
@@ -517,10 +512,6 @@ EOF
 }
 
 @test "apply: cutover rerun refuses (fail-closed) when the PAM backup points at an unexpected target" {
-    export SUDO_LOCAL_STATIC_DEFAULT="${BATS_TEST_TMPDIR}/etc-static-sudo_local"
-    : > "${SUDO_LOCAL_STATIC_DEFAULT}"
-    ln -s "${SUDO_LOCAL_STATIC_DEFAULT}" "${SUDO_LOCAL_PATH}"
-
     MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
         run zsh "${SETUP_DIR}/migrate.zsh" --apply
     [ "${status}" -eq 0 ]
@@ -605,3 +596,451 @@ EOF
     [[ "${output}" == *"health check 失敗"* ]]
     [[ "${output}" == *"claude-sync:"* ]]
 }
+
+# ---------------------------------------------------------------------------
+# desired-input fingerprint（宣言側の変更を cutover の skip 判定に反映する）
+# ---------------------------------------------------------------------------
+
+# Blank out the fingerprint detail recorded on cutover's success line, leaving
+# the line otherwise intact. This is exactly the shape of a manifest written by
+# an older migrate.zsh that had no fingerprint concept at all.
+_strip_cutover_fingerprint() {
+    local manifest="${HOME}/.dotfiles-migrate/manifest.log"
+    awk -F'\t' -v OFS='\t' '$2=="cutover" && $3=="success" {$4=""} {print}' \
+        "${manifest}" > "${manifest}.legacy"
+    mv "${manifest}.legacy" "${manifest}"
+}
+
+_darwin_calls() { wc -l < "${DARWIN_REBUILD_LOG}" | tr -d ' '; }
+_manifest_lines() { wc -l < "${HOME}/.dotfiles-migrate/manifest.log" | tr -d ' '; }
+
+# Use a private, writable copy of nix/ so a test can mutate the declaration
+# without touching this repository's real checkout.
+_use_private_nix_dir() {
+    export MIGRATE_NIX_DIR_OVERRIDE="${BATS_TEST_TMPDIR}/nix"
+    cp -R "${REPO_ROOT}/nix" "${MIGRATE_NIX_DIR_OVERRIDE}"
+}
+
+@test "apply: a legacy cutover success without a recorded fingerprint re-runs cutover exactly once (safe side)" {
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    _strip_cutover_fingerprint
+    local calls_before manifest_before
+    calls_before="$(_darwin_calls)"
+    manifest_before="$(_manifest_lines)"
+
+    # dry-run must surface it as a re-run, and stay side-effect free.
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --dry-run
+    [ "${status}" -eq 0 ]
+    [[ "${output}" == *"[WOULD RUN] cutover:"* ]]
+    [[ "${output}" == *"fingerprint"* ]]
+    [[ "${output}" != *"[SKIP] cutover:"* ]]
+    [ "$(_darwin_calls)" -eq "${calls_before}" ]
+    [ "$(_manifest_lines)" -eq "${manifest_before}" ]
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    run cat "${HOME}/.dotfiles-migrate/manifest.log"
+    [[ "${output}" == *$'\t'"cutover"$'\t'"postcondition-unmet"* ]]
+
+    # Exactly once: the re-run records a fingerprint, so the next apply skips
+    # again instead of switching on every invocation forever.
+    local calls_after
+    calls_after="$(_darwin_calls)"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -eq "${calls_after}" ]
+}
+
+@test "dry-run: cutover shows SKIP while the recorded fingerprint still matches the current declaration" {
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --dry-run
+    [ "${status}" -eq 0 ]
+    [[ "${output}" == *"[SKIP] cutover:"* ]]
+    [[ "${output}" != *"[WOULD RUN] cutover:"* ]]
+}
+
+@test "apply: a changed nix declaration re-runs cutover even though every required binary is present" {
+    _use_private_nix_dir
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ -x "${STUB_BIN}/starship" ]
+
+    # Model "pulled main on another machine": the Homebrew declaration changed,
+    # nothing about the local binaries did.
+    echo '# a newly declared cask' >> "${MIGRATE_NIX_DIR_OVERRIDE}/modules/darwin/homebrew.nix"
+
+    local calls_before
+    calls_before="$(_darwin_calls)"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [[ "${output}" == *"再実行"* ]]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # A newly added file (not just edited content) counts as a changed input too.
+    calls_before="$(_darwin_calls)"
+    echo '{ }' > "${MIGRATE_NIX_DIR_OVERRIDE}/modules/darwin/extra.nix"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # And a lock bump, which changes nothing else about the tree.
+    calls_before="$(_darwin_calls)"
+    echo '' >> "${MIGRATE_NIX_DIR_OVERRIDE}/flake.lock"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+}
+
+@test "apply: the role file appearing or changing re-runs cutover (role selects a different desired set)" {
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    # absent -> present
+    local calls_before
+    calls_before="$(_darwin_calls)"
+    echo "sub-1" > "${DOTFILES_ROLE_FILE}"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # content change (sub-1 -> default selects the defaultOnly* sets)
+    calls_before="$(_darwin_calls)"
+    echo "default" > "${DOTFILES_ROLE_FILE}"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # unchanged -> skip again
+    calls_before="$(_darwin_calls)"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -eq "${calls_before}" ]
+}
+
+@test "apply: the machine-local homebrew overlay appearing or changing re-runs cutover" {
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    local overlay="${HOME}/.config/dotfiles/homebrew.local.nix"
+    mkdir -p "$(dirname "${overlay}")"
+
+    # absent -> present
+    local calls_before
+    calls_before="$(_darwin_calls)"
+    echo '{ casks = [ "some-local-app" ]; }' > "${overlay}"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # content change
+    calls_before="$(_darwin_calls)"
+    echo '{ casks = [ "another-local-app" ]; }' > "${overlay}"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # removal counts as a change as well (zap would take the cask back out)
+    calls_before="$(_darwin_calls)"
+    rm -f "${overlay}"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+}
+
+@test "apply: cutover records the fingerprint the switch actually read, not the tree as it looks afterwards" {
+    _use_private_nix_dir
+
+    # Model a switch that races with the declaration changing underneath it
+    # (e.g. a `git pull` landing while darwin-rebuild is still running). If
+    # the fingerprint were taken after the switch, the change this switch
+    # never saw would be recorded as already applied and silently lost.
+    cat > "${STUB_BIN}/darwin-rebuild" <<'EOF'
+#!/bin/bash
+echo "$*" >> "${DARWIN_REBUILD_LOG}"
+if [[ "$1" == "--list-generations" ]]; then
+    echo "42 2026-08-20 10:00:00 (current)"
+elif [[ "$1" == "switch" ]]; then
+    printf '#!/bin/bash\nexit 0\n' > "$(dirname "$0")/starship"
+    chmod +x "$(dirname "$0")/starship"
+    echo '# landed mid-switch' >> "${MIGRATE_NIX_DIR_OVERRIDE}/modules/darwin/homebrew.nix"
+fi
+exit "${DARWIN_REBUILD_EXIT:-0}"
+EOF
+    chmod +x "${STUB_BIN}/darwin-rebuild"
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    # The very next apply must pick the change up instead of treating it as
+    # already switched in.
+    local calls_before
+    calls_before="$(_darwin_calls)"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --dry-run
+    [ "${status}" -eq 0 ]
+    [[ "${output}" == *"[WOULD RUN] cutover:"* ]]
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+}
+
+@test "apply: a new symlink under nix/ re-runs cutover (link target is fingerprint material, not silently followed)" {
+    _use_private_nix_dir
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    local calls_before
+    calls_before="$(_darwin_calls)"
+    ln -s ../../shared/overlay.nix "${MIGRATE_NIX_DIR_OVERRIDE}/modules/darwin/overlay.nix"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # Repointing an existing symlink is a declaration change too, even though
+    # neither the link's path nor any regular file's content moved.
+    calls_before="$(_darwin_calls)"
+    rm -f "${MIGRATE_NIX_DIR_OVERRIDE}/modules/darwin/overlay.nix"
+    ln -s ../../shared/other.nix "${MIGRATE_NIX_DIR_OVERRIDE}/modules/darwin/overlay.nix"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+
+    # Unchanged -> back to skipping (a dangling link must not make every
+    # single apply switch forever).
+    calls_before="$(_darwin_calls)"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ "$(_darwin_calls)" -eq "${calls_before}" ]
+}
+
+# Reach the state every PAM-cleanup test starts from: a machine already fully
+# migrated, with pam.zsh's real backup in place and cutover about to re-run.
+_reach_pam_rerun_state() {
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+    [ -L "${SUDO_LOCAL_PATH}.before-setup" ]
+
+    rm -f "${STUB_BIN}/starship"
+}
+
+@test "apply: PAM vacate cleanup removes only the file this run created, leaving older debris alone" {
+    _reach_pam_rerun_state
+
+    # Debris from some earlier, unrelated attempt. Cleanup must be scoped to
+    # the one path this apply computed, never a glob over every vacate file.
+    echo "older debris" > "${SUDO_LOCAL_PATH}.before-restore.20260101T000000Z"
+
+    export MIGRATE_PAM_VACATE_SUFFIX_OVERRIDE="cleanup1"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    [ ! -e "${SUDO_LOCAL_PATH}.before-restore.cleanup1" ]
+    run cat "${SUDO_LOCAL_PATH}.before-restore.20260101T000000Z"
+    [ "${output}" = "older debris" ]
+
+    # The Touch ID content the vacate file held is not lost: pam.zsh rewrote
+    # it, which is the whole reason the duplicate is safe to drop.
+    run cat "${SUDO_LOCAL_PATH}"
+    [[ "${output}" == *"pam_tid.so"* ]]
+
+    run cat "${HOME}/.dotfiles-migrate/manifest.log"
+    [[ "${output}" == *$'\t'"pam"$'\t'"vacated-discarded"* ]]
+}
+
+@test "apply: the PAM vacate file is preserved when cutover fails after vacating" {
+    _reach_pam_rerun_state
+
+    local touch_id_content_before
+    touch_id_content_before="$(cat "${SUDO_LOCAL_PATH}")"
+    export MIGRATE_PAM_VACATE_SUFFIX_OVERRIDE="cutoverfail"
+
+    # cutover.zsh's pre-flight `nix build` fails, so the switch never runs --
+    # but the vacate already happened, and it holds the only copy of the live
+    # Touch ID file at that moment.
+    cat > "${STUB_BIN}/nix" <<'EOF'
+#!/bin/bash
+echo "$*" >> "${NIX_LOG}"
+exit 1
+EOF
+    chmod +x "${STUB_BIN}/nix"
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 1 ]
+
+    [ -f "${SUDO_LOCAL_PATH}.before-restore.cutoverfail" ]
+    run cat "${SUDO_LOCAL_PATH}.before-restore.cutoverfail"
+    [ "${output}" = "${touch_id_content_before}" ]
+
+    run cat "${HOME}/.dotfiles-migrate/manifest.log"
+    [[ "${output}" == *$'\t'"cutover"$'\t'"fail"* ]]
+    [[ "${output}" != *"vacated-discarded"* ]]
+}
+
+@test "apply: the PAM vacate file is preserved when pam fails to reapply after the switch" {
+    _reach_pam_rerun_state
+
+    local touch_id_content_before
+    touch_id_content_before="$(cat "${SUDO_LOCAL_PATH}")"
+    export MIGRATE_PAM_VACATE_SUFFIX_OVERRIDE="pamfail"
+
+    # Model activation leaving stray state in /etc: a leftover .before-setup
+    # is exactly what pam.zsh refuses to overwrite (its own fail-closed
+    # guard), so pam fails after the switch already happened.
+    cat > "${STUB_BIN}/darwin-rebuild" <<'EOF'
+#!/bin/bash
+echo "$*" >> "${DARWIN_REBUILD_LOG}"
+if [[ "$1" == "--list-generations" ]]; then
+    echo "42 2026-08-20 10:00:00 (current)"
+elif [[ "$1" == "switch" ]]; then
+    printf '#!/bin/bash\nexit 0\n' > "$(dirname "$0")/starship"
+    chmod +x "$(dirname "$0")/starship"
+    echo "stray leftover" > "${SUDO_LOCAL_PATH}.before-setup"
+fi
+exit 0
+EOF
+    chmod +x "${STUB_BIN}/darwin-rebuild"
+
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 1 ]
+
+    # pam never reapplied, so the vacate file is the only remaining copy of
+    # the Touch ID content and must survive untouched.
+    [ -f "${SUDO_LOCAL_PATH}.before-restore.pamfail" ]
+    run cat "${SUDO_LOCAL_PATH}.before-restore.pamfail"
+    [ "${output}" = "${touch_id_content_before}" ]
+
+    run cat "${HOME}/.dotfiles-migrate/manifest.log"
+    [[ "${output}" == *$'\t'"pam"$'\t'"fail"* ]]
+    [[ "${output}" != *"vacated-discarded"* ]]
+}
+
+@test "apply: PAM vacate cleanup keeps a vacate file whose content differs from the reapplied target (hand-added rules survive)" {
+    _reach_pam_rerun_state
+
+    # A rule added by hand on this machine, on top of what pam.zsh writes.
+    # pam.zsh rewrites the file from its own fixed template, so this line only
+    # ever exists in the vacate copy after a cutover rerun -- deleting that
+    # copy just because it is a regular file would destroy it.
+    printf 'auth       sufficient     pam_reattach.so\n' >> "${SUDO_LOCAL_PATH}"
+    local target_content_before
+    target_content_before="$(cat "${SUDO_LOCAL_PATH}")"
+
+    export MIGRATE_PAM_VACATE_SUFFIX_OVERRIDE="handwritten"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    [ -f "${SUDO_LOCAL_PATH}.before-restore.handwritten" ]
+    run cat "${SUDO_LOCAL_PATH}.before-restore.handwritten"
+    [ "${output}" = "${target_content_before}" ]
+    [[ "${output}" == *"pam_reattach.so"* ]]
+
+    # Kept, not discarded -- and keeping it is not reported as a failure.
+    run cat "${HOME}/.dotfiles-migrate/manifest.log"
+    [[ "${output}" == *$'\t'"pam"$'\t'"vacated-kept"* ]]
+    [[ "${output}" != *"vacated-discarded"* ]]
+    [[ "${output}" == *$'\t'"pam"$'\t'"success"* ]]
+
+    # Once the live file matches what pam.zsh writes again, the next rerun's
+    # vacate copy is a true duplicate and is cleaned up as usual.
+    rm -f "${STUB_BIN}/starship"
+    export MIGRATE_PAM_VACATE_SUFFIX_OVERRIDE="duplicate"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    [ ! -e "${SUDO_LOCAL_PATH}.before-restore.duplicate" ]
+    [ -f "${SUDO_LOCAL_PATH}.before-restore.handwritten" ]
+    run cat "${HOME}/.dotfiles-migrate/manifest.log"
+    [[ "${output}" == *$'\t'"pam"$'\t'"vacated-discarded"$'\t'*"${SUDO_LOCAL_PATH}.before-restore.duplicate"* ]]
+}
+
+@test "apply: cutover rerun proceeds when neither the PAM target nor its backup exists (true first-time shape)" {
+    _reach_pam_rerun_state
+
+    # Nothing to restore and nothing to protect: no sudo_local at all is the
+    # genuine pre-pam.zsh shape, and it is already pristine as far as
+    # nix-darwin is concerned.
+    rm -f "${SUDO_LOCAL_PATH}" "${SUDO_LOCAL_PATH}.before-setup"
+
+    local calls_before
+    calls_before="$(_darwin_calls)"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 0 ]
+
+    [ "$(_darwin_calls)" -gt "${calls_before}" ]
+    run cat "${DARWIN_REBUILD_LOG}"
+    [[ "${output}" == *"switch --flake"* ]]
+
+    # pam reapplied on top of the empty slate.
+    run cat "${SUDO_LOCAL_PATH}"
+    [[ "${output}" == *"pam_tid.so"* ]]
+}
+
+@test "apply: cutover rerun refuses (fail-closed) when the PAM target is customized but its backup is gone" {
+    _reach_pam_rerun_state
+
+    # The backup is the only record of what pristine looked like. Without it,
+    # the customized target cannot be restored, and guessing its pristine form
+    # would mean overwriting a file whose content nothing else records.
+    rm -f "${SUDO_LOCAL_PATH}.before-setup"
+    [ -f "${SUDO_LOCAL_PATH}" ]
+    [ ! -L "${SUDO_LOCAL_PATH}" ]
+    local target_content_before
+    target_content_before="$(cat "${SUDO_LOCAL_PATH}")"
+
+    local calls_before
+    calls_before="$(_darwin_calls)"
+    MIGRATE_EUID_OVERRIDE=0 MIGRATE_SUDO_USER_OVERRIDE=testuser \
+        run zsh "${SETUP_DIR}/migrate.zsh" --apply
+    [ "${status}" -eq 1 ]
+    [[ "${output}" == *"復元しません"* ]]
+
+    # Stopped before cutover ever shelled out, and the live file is byte-identical.
+    [ "$(_darwin_calls)" -eq "${calls_before}" ]
+    run cat "${SUDO_LOCAL_PATH}"
+    [ "${output}" = "${target_content_before}" ]
+    [ ! -e "${SUDO_LOCAL_PATH}.before-setup" ]
+
+    run cat "${HOME}/.dotfiles-migrate/manifest.log"
+    [[ "${output}" == *$'\t'"cutover"$'\t'"fail"* ]]
+    [[ "${output}" != *$'\t'"pam"$'\t'"vacated"* ]]
+}