CONTEXT + README: the failure ladder and the operator ruling (v0.220.x)

controller/README.md

@@ -571,6 +571,20 @@ Each app can define rich metadata in `.felhom.yml`:
     (they are the undo). The live recovery unit is still never overwritten, which is why the replay
     source is the scratch. Honesty surfaces (`OffsiteScratchPair`): dump age, an unstamped-pair
     warning, and the R-44 empty-dump sniff — all warn-level, none of them gates.
+  - **What happens when the database replay FAILS (v0.220.0–.2, R-379/R-380).** A ladder, and every
+    rung is observable: **replay → rollback → hold.** The pre-restore undo copy has always been
+    taken; since v0.220.0 it is also **put back** when the replay fails — the whole set for this run,
+    matched on the run's own stamp (never on the `pre-restore-` prefix, and never just the first
+    file), re-applied with the DB service still up and before any restart, into a **re-discovered**
+    container (the DB-only start re-creates it, so the captured id is dead by then — R-379,
+    v0.220.1). The app then starts and the message says both that the restore failed and that the
+    data is back. If the rollback ALSO fails the app is **held stopped** — the operator's ruling —
+    the hold is persisted in `Settings.RestoreHolds`, every start path refuses it (customer button,
+    app-stop `Recover()`, boot sweep, via `driveStartGate` **above** its driveless early return), the
+    app-stop marker is ended so nothing auto-restarts it, and the row goes red. Cleared with
+    `--clear-restore-hold <app>`, **which requires a controller restart**. `--single-transaction` on
+    the Postgres import is a belt only; MariaDB DDL is not transactional, which is why the rollback
+    is the fix.
   - **Where an off-site restore puts the data (v0.219.0, R-356).** `ReconstituteFromOffsite` and
     `PlaceOffsiteRestore` resolve the destination with `Manager.GetAppDrivePath` — **the same
     resolver `CaptureRecoveryUnit` wrote the snapshot with**: the app's `HDD_PATH` if it declares