feat(upgrade): summarize checks and resume snapshot-backed safe fixes

docs/cli.md

@@ -22,7 +22,7 @@ terminal).
 - `hack exec <service> -- <cmd...>` — command in an already-running service container
 - `hack session` — persistent project workspaces (tmux-first)
 - `hack doctor` / `hack doctor --fix` — validate and repair local setup
-- `hack upgrade check` — read-only upgrade check of this machine and every registered project, ending in an ordered plan and the next command; `hack upgrade snapshot` and `hack upgrade rollback --rollback-manifest <manifest>` keep and restore the files the upgrade changes
+- `hack upgrade check` — read-only upgrade check of this machine and every registered project: a one-screen summary, the projects with findings (worktrees folded; `--verbose` for every checkout), and a plan with one step per kind of change, then the next command; `hack upgrade apply [--only <fix>] [--project <name>] [--dry-run]` runs the plan's apply steps (`.hack/.gitignore` refresh, stale agent files) for every checkout after keeping a snapshot and a journal; `hack upgrade snapshot` and `hack upgrade rollback --rollback-manifest <manifest>` keep and restore the files the upgrade changes
 - `hack daemon` — optional local daemon for faster JSON project status; `hack daemon install` starts it at login (launchd on macOS, a systemd user unit on Linux). On Linux without linger it still stops at your last logout and does not start at boot; `loginctl enable-linger` changes that
 
 Candidate `hack-next doctor` and `hack-v5 doctor` report a missing hackd as optional

docs/reference/cli.md

@@ -1869,7 +1869,7 @@ Notes:
 
 ## `hack upgrade`
 
-Guided upgrade: check, snapshot and roll back
+Guided upgrade: check, apply, snapshot and roll back
 
 ### Usage
 
@@ -1882,6 +1882,7 @@ hack upgrade <subcommand> [options]
 | Command | Summary |
 | --- | --- |
 | `hack upgrade check` | Check this machine and every registered project for the upgrade (read-only) |
+| `hack upgrade apply` | Run the plan's apply steps for every checkout (snapshot and journal first) |
 | `hack upgrade snapshot` | Keep a private copy of the files the upgrade changes |
 | `hack upgrade rollback` | Put back the files kept by an upgrade snapshot |
 
@@ -1906,13 +1907,50 @@ hack upgrade check [options]
 Reads the installed versions, the daemon's service, the projects registry (dead entries apart
 from unreadable ones), Hack's global services, proxy ports and DNS, the global secret store, and
 for each live project its env format and key, tracked files, ignore rules, agent integrations
-and (Apple Silicon) native preflight. Ends with an ordered plan and the next command. Changes
-nothing and prints no value. Exits 1 when something blocks the upgrade, naming it.
+and (Apple Silicon) native preflight. Prints a one-screen summary, the projects with findings
+(worktrees folded under their project) and a plan with one step per kind of change, then the
+next command. Changes nothing and prints no value. Exits 1 when something blocks the upgrade.
 
 ### Options
 
 | Option | Description |
 | --- | --- |
+| `--verbose` | Also list every checkout's findings and the dead registry entries (--json always has everything) |
+| `--all` | Same as --verbose |
+| `--json` | Output JSON (machine-readable) |
+| `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
+| `--help, -h` | Show help |
+| `--version, -v` | Show version |
+
+## `hack upgrade apply`
+
+Run the plan's apply steps for every checkout (snapshot and journal first)
+
+### Usage
+
+```bash
+hack upgrade apply [options]
+```
+
+Checks first, then runs the plan steps marked (apply) for every checkout they cover: refreshing
+outdated .hack/.gitignore files and removing stale standalone agent files the hack plugin replaces
+(each removal covered by the same snapshot). Before changing anything it keeps an upgrade
+snapshot and writes a journal beside it with the snapshot's coverage and gaps and each checkout's
+outcome. Checkouts with a blocker or a check that could not run are skipped. Prints the rollback
+command. --dry-run lists what would change. Exits 1 when anything selected was not done.
+After interruption, --resume <manifest> reuses that run's selection and snapshot; unexpected edits refuse.
+Other-volume checkouts are skipped before writing. Select one project with --snapshot-root on its volume
+to keep recovery bytes in an explicit private directory outside every Git working tree.
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--only <fix>` | Run only this plan step: ignore-rules or agent-integrations (comma-separated for both) |
+| `--project <name>` | Target a registered project by name (from ~/.hack/projects.json) |
+| `--dry-run` | List what would change and change nothing |
+| `--resume <manifest>` | Resume the apply journal beside this explicit snapshot manifest |
+| `--snapshot-root <directory>` | Keep recovery bytes in this private directory outside Git, on the selected targets' filesystem |
 | `--json` | Output JSON (machine-readable) |
 | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) |
 | `--help, -h` | Show help |

docs/reference/upgrade-apply.mmd

@@ -0,0 +1,22 @@
+stateDiagram-v2
+  direction TB
+  [*] --> checked: fresh check
+  checked --> planned: same filesystem admitted
+  checked --> skipped: other filesystem
+  skipped --> checked: explicit snapshot root
+  planned --> started: journal target start
+  started --> applied: record output then outcome
+  started --> failed: closed failure
+  started --> interrupted: process lost
+  interrupted --> checked: explicit resume manifest
+  applied --> restored: guarded rollback
+  failed --> checked: explicit resume manifest
+  restored --> [*]
+  note right of planned
+    Coverage and gaps persisted
+    before target writes
+  end note
+  note right of interrupted
+    Unexpected edits refuse resume
+    No implicit run selection
+  end note