diff --git a/.claude/skills/openpocket-rescue/SKILL.md b/.claude/skills/openpocket-rescue/SKILL.md
new file mode 100644
index 0000000..b86d027
--- /dev/null
+++ b/.claude/skills/openpocket-rescue/SKILL.md
@@ -0,0 +1,68 @@
+---
+name: openpocket-rescue
+description: Rescue a Donner Pocket X / M-VAVE BlackBox that restarts in a loop or no longer boots, from a Mac with no extra hardware (make rescue, tools/uboot_rescue.py, over the chip's USB UBOOT boot state). Use when the installer's rescue mode cannot finish, the pedal loops after a bad image, or a flash left the app area broken. Covers when to use it, the safety rules, who runs the sudo write, and how to read the result.
+---
+
+# Rescue a looping or bricked pedal
+
+The pedal's mask ROM always enters the USB boot state ("UBOOT": USB `4C4A:8057`, shown as `WL80UBOOT1.00`) when the app is bad,
+and it cannot be damaged. `tools/uboot_rescue.py` waits for that state, loads JieLi's RAM loader and rewrites the app area from
+the official package. Full walkthrough and the record of the first real run: `docs/RESCUE.md`.
+
+## When to use it
+
+- The pedal restarts in a loop and the installer page's rescue mode (or `node tools/op.mjs flash`) cannot finish. Try those first:
+  they need no root.
+- The pedal stays in the boot state (no loop, no sound) after an interrupted flash: the rescue finishes the job.
+- Not for Bluetooth or firmware behaviour questions, and not on a pedal that works.
+
+## Rules (read first)
+
+1. **Read-only first.** `make rescue` writes nothing to the flash (the loader goes to RAM only) and saves a backup of the whole flash
+   to `~/OpenPocket-rescue`. Read its output before anything else.
+2. **The captain runs the write.** `make rescue-write` and every `sudo` command need the captain's password and instruction. An
+   agent runs neither: prepare the exact command and give it with the `!` prefix.
+3. The write range is only whole 4 KiB sectors in `[0x4000, end of the package)`, `[0x4000, 0xA3000)` for BlackBox. Never write
+   the head `[0, 0x4000)` or anything above the package. The tool refuses; do not work around it.
+4. Never chip erase (`FB02`) and never burn a key (`FC12`). The tool cannot send them; do not add them.
+5. Stop on any `REFUSED` (wrong device, chip key not `0x980F`, flash not 1 MiB, head differs from the package). Nothing was written;
+   report the message.
+6. Keep the first backup. Never commit or publish a backup or a package: they hold the official firmware.
+7. After a restore, do not reinstall the Bluetooth test image until the cause of the loop is known.
+
+## How
+
+```
+brew install libusb          # once
+make doctor                  # rescue lines: libusb, official package, loader, root
+make rescue                  # read-only: INQUIRY, loader to RAM, key, flash id, backup, head check, sectors that differ
+make rescue-write            # only on the captain's instruction, after the read-only run passed
+```
+
+Options go after `ARGS=` (`make rescue ARGS="--package FILE.fwsc"`; `--image flash.bin`, `--loader FILE`, `--backup-dir DIR`,
+`--attempts N`). Plug the pedal straight into the Mac (no hub). Start the command first; it waits for the pedal and starts by
+itself the moment it appears (the pedal is in UBOOT about 44 s of every 70 s while it loops). Needs the official BlackBox package
+(default `~/Documents/BlackBox (2).fwsc`) and Python 3.
+
+## Reading the result
+
+| Output | Meaning |
+| --- | --- |
+| `INQUIRY: WL82 UBOOT1.00 1.00` | the right device |
+| `loader running: chip key 0x980f, flash id ...  (1024 KiB)` | the checks passed; record the flash id |
+| `backup saved: ...dump.bin` | the rollback copy is complete on disk |
+| `head [0, 0x4000) matches the image` | the package fits this pedal |
+| `N of 160 sectors ... differ` | what a write would do; a rerun after a partial write shows fewer |
+| `Read-only run finished, nothing was written` | exit 0, the read-only run is done |
+| `Done: N sectors written and verified` | exit 0 after `--write`; power-cycle the pedal |
+| `the pedal went away ... waiting for it again` | the window closed; it resumes by itself |
+| exit 1 `ERROR` | setup: libusb, `sudo`, missing package; the message names the fix |
+| exit 2 `REFUSED` | a safety check stopped it, nothing written |
+| `LIBUSB_ERROR_ACCESS` | run with `sudo` (`make rescue` does); if it persists as root, report it |
+
+Save the output of a real run (`make rescue 2>&1 | tee rescue.log`) and add its numbers to `docs/RESCUE.md`.
+
+## Tests
+
+`make rescue-check` runs the tool against a simulated UBOOT pedal (protocol, guards, resume, no hardware); it is part of
+`make test`. Hardware behaviour is not covered by any test.
diff --git a/Makefile b/Makefile
index 591ee81..c5146a2 100644
--- a/Makefile
+++ b/Makefile
@@ -10,11 +10,18 @@
 #   make serve      the installer and editor on http://localhost:8765/ (offline install)
 #   make render IN=guitar.wav [OUT=out.wav] [PRESET=1]   a WAV through the engine
 #   make appimage [DUMP=fm1-1.bin]   fm1-300.bin for the SD-card recovery
+#   make rescue [ARGS=..]   restore a looping BlackBox from its UBOOT state, read-only (needs sudo and libusb: docs/RESCUE.md)
+#   make rescue-write [ARGS=..]   the same, writing the official firmware back (run `make rescue` first)
+#   make rescue-check   the UBOOT rescue tool (tools/uboot_rescue.py) against a simulated pedal; needs only Python 3
 # `make NATIVE=1 build` skips Docker (toolchain installed with firmware/setup.sh).
-.PHONY: doctor build test package clean shell image serve render appimage
-doctor build test package clean shell image serve:
+.PHONY: doctor build test package clean shell image serve render appimage rescue rescue-write rescue-check
+doctor build test package clean shell image serve rescue-check:
 	@node tools/op.mjs $@
 render:
 	@node tools/op.mjs render "$(IN)" "$(OUT)" "$(PRESET)"
 appimage:
 	@node tools/op.mjs appimage "$(DUMP)"
+rescue:
+	@node tools/op.mjs rescue $(ARGS)
+rescue-write:
+	@node tools/op.mjs rescue --write $(ARGS)
diff --git a/README.md b/README.md
index 5e58bde..4025bdf 100644
--- a/README.md
+++ b/README.md
@@ -60,8 +60,9 @@ setting was still the official firmware's (it survives a warm reset), so the ped
 the DSP slower and crackle, so v33 leaves them as the boot loader does again.) Being tested on the BlackBox. For a pedal that
 restarts in a loop, the page has a **rescue mode** (step 2): tick it, press Connect, plug the pedal in; the install
 starts the moment the pedal answers and halts its DSP at once. A BlackBox can always go back to its official firmware from the page (step 3). It is the same JieLi update system as the M-VAVE FM-1, where this method is
-used by Felucca, CLIPPER and SLOOP. Keep the SD-card recovery at hand (`flash/`: fm1buddy on an ESP32-S3,
-`makeimage.bat`).
+used by Felucca, CLIPPER and SLOOP. If the pedal still loops, restore it from a Mac with no extra hardware: `make rescue` (read-only check and backup), then
+`make rescue-write` (`docs/RESCUE.md`; it needs `brew install libusb`, sudo and the official BlackBox file). The second route is the
+SD-card recovery (`flash/`: fm1buddy on an ESP32-S3, `makeimage.bat`).
 
 **Without internet**: double-click `INSTALL-OFFLINE.bat` (Windows; nothing to install: a small PowerShell server,
 `tools/serve_offline.ps1`) or run `make serve` (macOS, Linux; `tools/serve.py`, needs Python 3). It serves the installer
diff --git a/docs/BUILDING.md b/docs/BUILDING.md
index de42e5f..14600c4 100644
--- a/docs/BUILDING.md
+++ b/docs/BUILDING.md
@@ -35,6 +35,8 @@ Apple silicon and other ARM machines Docker emulates it (Rosetta or QEMU); you c
 | `make serve` | the installer and editor on `http://localhost:8765/` (offline install; needs Python 3 on the host) |
 | `make render IN=guitar.wav [OUT=..] [PRESET=1]` | a DI recording through the engine |
 | `make appimage DUMP=fm1-1.bin` | `fm1-300.bin` for the SD-card recovery |
+| `make rescue` / `make rescue-write` | restore a looping BlackBox from its UBOOT state from a Mac (read-only first; asks for sudo; `ARGS="--package FILE"` for options): `docs/RESCUE.md` |
+| `make rescue-check` | the UBOOT rescue tool (`tools/uboot_rescue.py`, see `docs/RESCUE.md`) against a simulated pedal; needs only Python 3 |
 
 `make NATIVE=1 build` skips Docker and uses a toolchain installed on the machine (`sh firmware/setup.sh` installs it in
 `~/.jieli`; Linux x86-64 only). `tests/run_tests.sh` also runs directly on macOS and Linux with only a C compiler, Node and
diff --git a/docs/RESCUE.md b/docs/RESCUE.md
new file mode 100644
index 0000000..971829e
--- /dev/null
+++ b/docs/RESCUE.md
@@ -0,0 +1,104 @@
+# Rescuing a crash-looping BlackBox from a Mac (no extra hardware)
+
+Use this when the pedal restarts in a loop and the installer's rescue mode cannot finish. Between crashes the pedal sits
+about 44 seconds in the JieLi mask-ROM USB boot state ("UBOOT": USB 4C4A:8057, shown by macOS as `WL80UBOOT1.00`). The
+mask ROM is chip ROM, so it cannot be damaged. `tools/uboot_rescue.py` waits for that state, loads JieLi's RAM loader and
+rewrites the app area of the flash from the official package, then restarts the pedal.
+
+## One-time setup (macOS)
+
+```
+brew install libusb
+```
+
+That is all. The tool is one Python 3 file that calls libusb through `ctypes` (no `pip install`). It needs two files:
+
+- The official package, `~/Documents/BlackBox (2).fwsc` (BlackBox_016) by default, or `--package FILE.fwsc`, or a raw flash
+  image with `--image flash.bin`. Every CRC of a package is checked before it is used.
+- JieLi's `wl82loader.bin`, downloaded once into the git-ignored `build/cache/` from kagaimiq/jl-uboot-tool (commit
+  `c32b28e`, the same pin as `flash/installer-fm1buddy-pocketx.bat`) and checked against SHA-256
+  `d41da6126760c9d66660bcc0cac8d27d221806c5e369a8036921efe68dca5376` on every run. It is not in this repository. `make clean`
+  removes the cache; `--loader FILE` uses a copy you downloaded yourself.
+
+## The commands
+
+`make rescue` and `make rescue-write` (or `node tools/op.mjs rescue [--write]`, the entry point next to `flash`) run the tool with
+`sudo` for you and pass options on (`make rescue ARGS="--package FILE.fwsc"`). `make doctor` shows whether libusb, the package and
+the loader are in place. The `sudo python3 tools/uboot_rescue.py` lines below are the same thing written out.
+
+macOS keeps its own mass-storage driver on the pedal in this state, and libusb needs root to take the interface from it.
+Plug the pedal straight into the Mac (no hub), start the command, and it waits for the pedal and starts by itself the moment
+it appears.
+
+1. **Read-only first.** Nothing is written to the pedal's flash; the loader goes to RAM only.
+
+```
+make rescue                              # = sudo python3 tools/uboot_rescue.py
+```
+
+It checks that the pedal answers INQUIRY as `WL82 UBOOT1.00`, loads the loader, reads the chip key (must be `0x980F`) and
+the flash id (must be a 1 MiB flash), saves a backup of the whole flash to `~/OpenPocket-rescue/blackbox-<time>.dump.bin`,
+compares the pedal's head `[0, 0x4000)` with the image's, reports how many sectors differ, and sends run-app. Keep this
+backup: it is the only copy of what the pedal held before the rescue.
+
+2. **The rescue**, only after the read-only run has passed:
+
+```
+make rescue-write                        # = sudo python3 tools/uboot_rescue.py --write
+```
+
+Same steps, then for every 4 KiB sector in `[0x4000, 0xA3000)` that differs: erase, write, read back, compare. When it prints
+`Done`, power-cycle the pedal. If the pedal drops out of UBOOT in the middle (it reboots into the crashing app and comes
+back), the tool waits and starts again by itself; running it again later also resumes. Only the sectors that still differ are
+written, so a rerun is short.
+
+Options (after `ARGS=` with make): `--check` (prerequisites only), `--package`, `--image`, `--loader`, `--backup-dir DIR`, `--attempts N` (UBOOT windows to try, default 10).
+Exit codes: 0 done, 1 setup problem (libusb, root, files), 2 refused by a safety check, 130 stopped by Ctrl-C.
+
+## What the first real run showed
+
+The first run on a real, looping BlackBox was done by the captain, who reported that the rescue worked ("the rescue worked!").
+Only the files the tool left behind are recorded here; the captain's terminal output was not kept.
+
+| Item | What the files show |
+| --- | --- |
+| Backups | Two, in `~/OpenPocket-rescue`: `blackbox-20261105-213039.dump.bin` and `blackbox-20261105-213135.dump.bin`, 1,048,576 bytes each (a 1 MiB flash), written 56 s apart. They are byte for byte identical (same SHA-256), so both hold the flash from before any write. |
+| What the pedal held | Application `BlackBox_936`, the Bluetooth test image that caused the loop. Its app area passes the package's own CRC checks. |
+| Head `[0, 0x4000)` | Identical to the head of the official BlackBox_016 `flash.bin`, so the head check passes. |
+| Sectors to write | 159 of the 160 sectors in `[0x4000, 0xA3000)` differed from BlackBox_016 (first `0x4000`, last `0xA2000`). |
+| Restored package | BlackBox_016 (`BlackBox (2).fwsc`, the tool's default image). |
+| Chip key, flash id | Unknown: they are printed, not saved. The tool's checks (key `0x980F`, 1 MiB flash) passed, because it went on to write. |
+| Length of the UBOOT window, sectors written, time taken | Unknown: not saved. A later run should keep its output (`make rescue 2>&1 \| tee rescue.log`). |
+
+The two backups' times are consistent with a read-only run followed by the `--write` run, but no file records which was which.
+
+## Safety rules
+
+- The default is read-only. Writing needs `--write`.
+- Writes are limited to whole 4 KiB sectors in `[0x4000, end of the image)`; for the BlackBox package that is
+  `[0x4000, 0xA3000)`. The end comes from the package and can never be above `0xFF000`. The head `[0, 0x4000)` (header,
+  second-stage boot loader, chip key) and everything above the image (Bluetooth trims, user data) are never touched.
+- Only a fixed list of loader commands can be sent. Chip erase (`FB02`) and key burn (`FC12`) are not on it. In a read-only
+  run the erase and write commands are not on it either.
+- It stops without writing when the device is not `WL82 UBOOT1.00`, the chip key is not `0x980F`, the flash is not 1 MiB, or
+  the pedal's head differs from the image's head (a package for another layout).
+- The backup is complete on disk before the first erase.
+- After a restore, do not reinstall the Bluetooth test image until the cause of the crash loop is understood: the loop came
+  from that image.
+
+## If it does not work
+
+| Symptom | Cause and next step |
+| --- | --- |
+| `libusb not found` | `brew install libusb` (or set `LIBUSB_PATH`). |
+| `cannot take the interface from macOS (LIBUSB_ERROR_ACCESS)` | Run the command with `sudo`. |
+| Waits forever | The pedal is not in UBOOT right now. It is there about 44 s out of every 70 s while it loops; check `ioreg -p IOUSB` for `WL80UBOOT1.00`, a data cable and a direct port. |
+| `REFUSED` | A safety check stopped it; the message names which. Nothing was written. |
+| `gave up after N tries` | The pedal kept leaving UBOOT before the run could finish. Rerun: it resumes. |
+| Still nothing | The SD-card recovery in `flash/` (fm1buddy on an ESP32-S3) is the other route. |
+
+## Credits
+
+The USB boot protocol is documented by [kagaimiq/jl-uboot-tool](https://github.com/kagaimiq/jl-uboot-tool) (MIT) and
+[konsumer/fm1buddy](https://github.com/konsumer/fm1buddy) (GPL-3.0); `tools/uboot_rescue.py` is a new implementation of the
+same commands for macOS. Tests: `make rescue-check` runs it against a simulated pedal (`tests/uboot_sim.py`), with no hardware.
diff --git a/docs/index.html b/docs/index.html
index fdc946d..025b614 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -108,6 +108,7 @@ <h2><b>3</b><span data-t="s3"></span></h2>
     <details>
       <summary data-t="rescue"></summary>
       <p class="note" data-t="rescuenote"></p>
+      <p class="note" data-t="rescuemac"></p>
       <div class="row"><button class="alt" id="uboot" disabled data-t="uboot"></button></div>
     </details>
     <details>
@@ -144,6 +145,7 @@ <h2><b>3</b><span data-t="s3"></span></h2>
     unknownok: "I understand: this file has not been tested with this page. Install it anyway.",
     rescue: "Rescue and advanced options",
     rescuenote: "If the pedal stays in update mode, reconnect it: the Resume button appears. The button below puts a pedal running OpenPocket into the chip's UBOOT mode, for a recovery from the SD card (fm1buddy).",
+    rescuemac: "A pedal that restarts in a loop and cannot be reached by this page can be restored from a Mac, with no extra hardware: download the official BlackBox file (M-VAVE), then run `make rescue` in the OpenPocket folder (read-only check), and `make rescue-write` to restore it. The steps are in docs/RESCUE.md; the SD-card route (fm1buddy, flash/) is the second choice.",
     uboot: "Enter UBOOT mode", logt: "Log",
     foot1: "OpenPocket is an independent project, not affiliated with Donner or M-VAVE. Install at your own risk. Source code: GPL-3.0.",
     foot2: "Update protocol and loader from Felucca and felucca-bsp (Hügelton Instruments, GPL-3.0 / MPL-2.0). JieLi AC79 SDK files: Apache-2.0. Inter typeface: SIL OFL 1.1.",
diff --git a/tests/run_tests.sh b/tests/run_tests.sh
index ff82108..fca0f5c 100755
--- a/tests/run_tests.sh
+++ b/tests/run_tests.sh
@@ -6,6 +6,7 @@
 #  - preset store: save / reload / power cut at every step of a save (firmware/px_store.h on a simulated flash)
 #  - packages: tools/pxpkg.py rebuilds the official PocketX_016 app area byte for byte (needs the official file)
 #  - installer: docs/pxota.js + docs/pxpkg.js against a simulated pedal running the real update code (ota.c, ldr_core.c)
+#  - rescue: tools/uboot_rescue.py (protocol, guards, resume) against a simulated UBOOT pedal, tests/uboot_sim.py
 #  - page: docs/index.html in headless Chromium (needs Playwright: npm i playwright && npx playwright install chromium)
 set -e
 cd "$(dirname "$0")/.."
@@ -25,6 +26,8 @@ echo "== installer"
 node tests/test_installer.mjs "$1"
 echo "== build entry point (tools/op.mjs)"
 node tests/test_op.mjs
+echo "== rescue tool (tools/uboot_rescue.py on a simulated UBOOT pedal)"
+python3 tests/test_uboot_rescue.py $1
 echo "== editor"
 $CC -O1 -Wall -Wno-unused-function -o build/edsim tests/edsim.c engine/px_dsp.c firmware/px_math.c -lm
 node tests/test_editor.mjs
diff --git a/tests/test_op.mjs b/tests/test_op.mjs
index 50598cf..5525242 100644
--- a/tests/test_op.mjs
+++ b/tests/test_op.mjs
@@ -107,6 +107,30 @@ for (const p of ["build", "firmware/build", "firmware/openpocket.bin", "docs/fir
 }
 for (const p of ["docs/firmware/README.md", "engine/px_dsp.c", "guitar.wav"]) assert.ok(existsSync(join(root, p)), `${p} kept`);
 
+// rescue: sudo + python3 tools/uboot_rescue.py, read-only unless --write (fake sudo and python3 record their argv)
+const rescuebin = join(tmp, "rescuebin");
+mkdirSync(rescuebin);
+const rlog = join(tmp, "rescue.log");
+for (const name of ["sudo", "python3"]) writeFileSync(join(rescuebin, name), `#!/bin/sh\n{ printf '${name}'; for a in "$@"; do printf '\\t%s' "$a"; done; printf '\\n'; } >> "${rlog}"\nexit 0\n`, { mode: 0o755 });
+const rescueCalls = (args, env = {}) => {
+  rmSync(rlog, { force: true });
+  const r = op(args, { env, path: rescuebin });
+  return { status: r.status, calls: existsSync(rlog) ? readFileSync(rlog, "utf8").trim().split("\n").map((l) => l.split("\t")) : [] };
+};
+const asRoot = typeof process.getuid === "function" && process.getuid() === 0;
+const viaSudo = asRoot ? [] : ["sudo"];
+let rc = rescueCalls(["rescue"]);
+assert.equal(rc.status, 0);
+assert.deepEqual(rc.calls.at(-1), [...viaSudo, "python3", "tools/uboot_rescue.py"], "rescue is read-only by default and runs as root via sudo");
+rc = rescueCalls(["rescue", "--write", "--package", "x.fwsc"]);
+assert.deepEqual(rc.calls.at(-1).slice(-4), ["tools/uboot_rescue.py", "--write", "--package", "x.fwsc"], "--write and options reach the tool");
+rc = rescueCalls(["rescue", "--check"]);
+assert.equal(rc.calls.at(-1)[0], "python3", "--check needs no sudo");
+assert.ok(rc.calls.every((c) => c[0] !== "sudo"));
+rmSync(rlog, { force: true });
+op(["doctor"], { path: `${fakebin}:${rescuebin}` });
+assert.deepEqual(readFileSync(rlog, "utf8").trim().split("\n").at(-1).split("\t"), ["python3", "tools/uboot_rescue.py", "--check"], "doctor checks the rescue prerequisites");
+
 const make = spawnSync("make", ["--version"], { encoding: "utf8" });
 if (make.status === 0) {
   rmSync(log, { force: true });
@@ -117,6 +141,17 @@ if (make.status === 0) {
   const calls = readFileSync(log, "utf8").trim().split("\n").map((l) => l.split("\t"));
   assert.equal(calls.at(-1)[2], "-it", "make shell goes through op.mjs");
   assert.ok(calls.at(-1).includes("openpocket-build") && calls.at(-1).at(-1) === "bash");
+  rmSync(log, { force: true });
+  const rc = spawnSync("make", ["-C", repo, "rescue-check"], { env, encoding: "utf8" });
+  assert.equal(rc.status, 0, rc.stdout + rc.stderr);
+  assert.ok(!existsSync(log), "make rescue-check needs no docker");
+  for (const [target, write] of [["rescue", false], ["rescue-write", true]]) {
+    rmSync(rlog, { force: true });
+    const mr = spawnSync("make", ["-C", repo, target, "ARGS=--attempts 3"], { env: { ...env, PATH: `${rescuebin}:${process.env.PATH}`, FAKE_DOCKER_LOG: log }, encoding: "utf8" });
+    assert.equal(mr.status, 0, mr.stderr);
+    const last = readFileSync(rlog, "utf8").trim().split("\n").at(-1).split("\t");
+    assert.deepEqual(last.slice(-(write ? 4 : 3)), write ? ["tools/uboot_rescue.py", "--write", "--attempts", "3"] : ["tools/uboot_rescue.py", "--attempts", "3"], `make ${target}`);
+  }
 } else {
   console.log("(make not installed: Makefile delegation skipped)");
 }
diff --git a/tests/test_uboot_rescue.py b/tests/test_uboot_rescue.py
new file mode 100644
index 0000000..1ac7a67
--- /dev/null
+++ b/tests/test_uboot_rescue.py
@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-3.0-only
+"""tools/uboot_rescue.py against a simulated UBOOT pedal (tests/uboot_sim.py): protocol layer, guards, resume. No hardware.
+  python3 tests/test_uboot_rescue.py [official-BlackBox.fwsc]   (the package tests are skipped without the official file)
+"""
+import contextlib, io, os, random, subprocess, sys, tempfile, unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import uboot_sim
+import uboot_rescue as ur
+from uboot_rescue import DeviceGone, GuardError, RescueError, ScsiError, Uboot, Window
+
+PACKAGE = Path(sys.argv.pop(1)) if len(sys.argv) > 1 and sys.argv[1].endswith(".fwsc") else ur.DEFAULT_PACKAGE
+SECTOR, HI = ur.SECTOR, 0xA3000
+FORBIDDEN = (0xFC12, 0xFB02, 0xFB00, 0xFB03)
+
+
+def noise(seed, n):
+    return random.Random(seed).randbytes(n)
+
+
+LOADER = noise(1, ur.LOADER_SIZE)
+IMAGE = noise(2, HI)
+
+
+def crashed_flash(same_sectors=(0x10, 0x11, 0x50)):
+    """What the looping pedal holds: the official head, other app bytes (a few sectors already right), other data above."""
+    flash = bytearray(noise(3, ur.FLASH_SIZE))
+    flash[:0x4000] = IMAGE[:0x4000]
+    for s in same_sectors:
+        flash[s * SECTOR:(s + 1) * SECTOR] = IMAGE[s * SECTOR:(s + 1) * SECTOR]
+    return flash
+
+
+def differing(flash):
+    return sum(flash[a:a + SECTOR] != IMAGE[a:a + SECTOR] for a in range(0x4000, HI, SECTOR))
+
+
+class Rescue(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.backups = Path(self.tmp.name)
+        self.logs = []
+
+    def pedal(self, flash=None, **kw):
+        sim = uboot_sim.SimPedal(flash if flash is not None else crashed_flash(), LOADER, **kw)
+        self.opened = 0
+
+        def open_device():
+            self.opened += 1
+            return sim if self.opened == 1 else sim.reenumerate()
+        return sim, open_device
+
+    def run_rescue(self, open_device, sim, write, attempts=10, image=IMAGE):
+        return ur.rescue(open_device, LOADER, image, write, self.backups, attempts, self.logs.append, sim.clock)
+
+    # ---- the read-only mode
+    def test_read_only_never_writes_and_backs_up(self):
+        flash = crashed_flash()
+        before = bytes(flash)
+        sim, open_device = self.pedal(flash)
+        n, saved = self.run_rescue(open_device, sim, write=False)
+        self.assertEqual(n, differing(before))
+        self.assertEqual(bytes(sim.flash), before)
+        self.assertFalse(sim.writes() or sim.erases())
+        self.assertEqual(sim.seen[-1][0], ur.RUN_APP)
+        self.assertEqual(saved[0].read_bytes(), before)
+        self.assertTrue(saved[0].name.endswith(".dump.bin"))
+
+    def test_read_only_uboot_cannot_erase_or_write(self):
+        sim, _ = self.pedal()
+        dev = Uboot(sim, None, sim.clock)
+        for call in (lambda: dev.erase_sector(0x5000), lambda: dev.flash_write(0x5000, b"x" * 512)):
+            self.assertRaises(GuardError, call)
+        self.assertEqual(sim.seen, [])
+
+    # ---- the rescue
+    def test_write_restores_only_the_window(self):
+        flash = crashed_flash()
+        before = bytes(flash)
+        sim, open_device = self.pedal(flash)
+        sim.on_first_write = lambda: self.assertTrue(list(self.backups.glob("*.dump.bin")), "backup before the first write")
+        n, saved = self.run_rescue(open_device, sim, write=True)
+        self.assertEqual(n, differing(before))
+        self.assertEqual(bytes(sim.flash[:HI]), IMAGE)
+        self.assertEqual(bytes(sim.flash[HI:]), before[HI:], "everything above the image is untouched")
+        self.assertEqual(sim.erases(), sorted(sim.erases()))
+        self.assertEqual(len(sim.erases()), n, "sectors that already match are not erased")
+        self.assertTrue(all(0x4000 <= a < HI for a in sim.erases() + sim.writes()))
+        self.assertFalse(any(op in FORBIDDEN for op, _ in sim.seen))
+        self.assertEqual(sim.seen[-1][0], ur.RUN_APP)
+        self.assertEqual(saved[0].read_bytes(), before)
+        self.assertEqual(self.opened, 1, "the loader's watchdog never fired: a command is always sent in time")
+
+    def test_rerun_after_success_writes_nothing(self):
+        sim, open_device = self.pedal()
+        self.run_rescue(open_device, sim, write=True)
+        sim.seen.clear()
+        n, _ = self.run_rescue(open_device, sim, write=True)
+        self.assertEqual(n, 0)
+        self.assertFalse(sim.writes() or sim.erases())
+
+    def test_resume_after_the_pedal_drops_off(self):
+        original = bytes(crashed_flash())
+        for drop in (3, 60, 200, 700, 1500, 2600):
+            with self.subTest(drop_after_commands=drop):
+                self.backups = Path(tempfile.mkdtemp(dir=self.tmp.name))
+                sim, open_device = self.pedal()
+                sim.drop_at = drop
+                n, saved = self.run_rescue(open_device, sim, write=True)
+                self.assertGreater(self.opened, 1)
+                self.assertEqual(bytes(sim.flash[:HI]), IMAGE)
+                self.assertEqual(bytes(sim.flash[HI:]), original[HI:])
+                self.assertLessEqual(len(sim.erases()), differing(original) + 1, "only the interrupted sector is done twice")
+                self.assertEqual(len(list(self.backups.glob("*.dump.bin"))), 1)
+                self.assertEqual(saved[0].read_bytes(), original, "the backup is the flash before anything was written")
+
+    def test_the_loader_watchdog_is_simulated(self):
+        sim, open_device = self.pedal()
+        dev = Uboot(sim, None, sim.clock)
+        ur.attach(dev, LOADER, self.logs.append)
+        sim.clock.t += 4
+        self.assertRaises(DeviceGone, dev.keepalive)
+
+    def test_gives_up_after_the_attempts(self):
+        sim, open_device = self.pedal()
+        flaky = lambda: (sim.reenumerate(), setattr(sim, "drop_at", 5))[0]
+        with self.assertRaises(RescueError):
+            self.run_rescue(flaky, sim, write=True, attempts=3)
+
+    # ---- the refusals
+    def refused(self, sim, open_device, write=True):
+        with self.assertRaises(GuardError) as cm:
+            self.run_rescue(open_device, sim, write=write)
+        self.assertFalse(sim.writes() or sim.erases(), "nothing was erased or written")
+        return str(cm.exception)
+
+    def test_refuses_another_device(self):
+        sim, open_device = self.pedal(vendor="UDISK")
+        self.assertIn("not the WL82 UBOOT1.00", self.refused(sim, open_device))
+        self.assertEqual(sim.seen, [], "not even the loader was sent")
+
+    def test_refuses_another_chip_key(self):
+        sim, open_device = self.pedal(key=0x1234)
+        self.assertIn("chip key 0x1234", self.refused(sim, open_device))
+
+    def test_refuses_another_flash_size(self):
+        sim, open_device = self.pedal(flash_id=0xEB6015)
+        self.assertIn("1 MiB", self.refused(sim, open_device))
+
+    def test_refuses_a_package_with_another_head(self):
+        flash = crashed_flash()
+        flash[0x100] ^= 0xFF
+        sim, open_device = self.pedal(flash)
+        self.assertIn("head", self.refused(sim, open_device))
+        self.assertEqual(len(list(self.backups.glob("*.dump.bin"))), 1, "the backup was made before the head check")
+
+    def test_loader_commands_are_a_whitelist(self):
+        sim, _ = self.pedal()
+        dev = Uboot(sim, Window.for_image(HI), sim.clock)
+        for op in FORBIDDEN + (0xFC13, 0xFB31):
+            with self.subTest(op=hex(op)):
+                self.assertRaises(GuardError, dev._command, op, b"")
+        self.assertEqual(sim.seen, [])
+
+    def test_write_window(self):
+        sim, _ = self.pedal()
+        dev = Uboot(sim, Window.for_image(HI), sim.clock)
+        for addr in (0, 0x3000, 0x3FFF, HI, HI + SECTOR, 0xFF000, 0x5001):
+            with self.subTest(erase=hex(addr)):
+                self.assertRaises(GuardError, dev.erase_sector, addr)
+        for addr, n in ((0, 512), (0x3E00, 512), (HI, 512), (HI - 256, 512), (0x4F00, 512), (0x4000, 0)):
+            with self.subTest(write=(hex(addr), n)):
+                self.assertRaises(GuardError, dev.flash_write, addr, b"x" * n)
+        self.assertRaises(GuardError, dev.mem_write, 0x1C00000, b"x" * 512)
+        self.assertRaises(GuardError, dev.mem_write, ur.LOADER_AT + ur.LOADER_SIZE - 100, b"x" * 512)
+        self.assertEqual(sim.seen, [])
+
+    def test_window_comes_from_the_image_and_never_exceeds_0xff000(self):
+        self.assertEqual(Window.for_image(HI), Window(0x4000, HI))
+        self.assertEqual(Window.for_image(0xFF000), Window(0x4000, 0xFF000))
+        for size in (0x4000, 0x100000, 0xFF800, HI + 1, 0):
+            with self.subTest(size=hex(size)):
+                self.assertRaises(GuardError, Window.for_image, size)
+
+    # ---- pieces
+    def test_cipher_and_magic(self):
+        self.assertEqual(ur.MAGIC, "孟黎我爱你，玉林".encode("gb2312"))
+
+        def bit_crc(data, crc):
+            for b in data:
+                crc ^= b << 8
+                for _ in range(8):
+                    crc = ((crc << 1) ^ 0x1021 if crc & 0x8000 else crc << 1) & 0xFFFF
+            return crc
+        crc, ks = bit_crc(b"\xff\xff", 0xFFFF), []
+        for i in range(40):
+            crc = bit_crc(ur.MAGIC[i % 16:i % 16 + 1], crc)
+            ks.append(crc & 0xFF)
+        self.assertEqual(ur.cipher(bytes(40)), bytes(ks))
+        self.assertEqual(ur.cipher(ur.cipher(b"abc")), b"abc")
+
+    def test_bulk_only_framing(self):
+        w = ur.cbw(7, b"\x12\0\0\0\x24\0", 36, True)
+        self.assertEqual((len(w), w[:4], w[12], w[14]), (31, b"USBC", 0x80, 6))
+        self.assertEqual(ur.parse_csw(b"USBS" + (7).to_bytes(4, "little") + bytes(5), 7), (0, 0))
+        self.assertRaises(ScsiError, ur.parse_csw, b"USBS" + (8).to_bytes(4, "little") + bytes(5), 7)
+        self.assertRaises(ScsiError, ur.parse_csw, b"XXXX" + (7).to_bytes(4, "little") + bytes(5), 7)
+
+    def test_finds_the_bulk_only_interface(self):
+        cfg = bytes.fromhex("0902200001010080c80904000002080650000705810240000107050102400001")  # read from the real pedal
+        self.assertEqual(ur.mass_storage_endpoints(cfg), (0, 0x81, 0x01))
+        hid = bytes.fromhex("0902190001010080320904000001030100000705810340000a")
+        self.assertRaises(RescueError, ur.mass_storage_endpoints, hid)
+
+    def test_loader_must_match_the_pin(self):
+        bad = Path(self.tmp.name) / "wl82loader.bin"
+        bad.write_bytes(LOADER)
+        self.assertRaises(RescueError, ur.get_loader, str(bad))
+        sha, ur.LOADER_SHA256 = ur.LOADER_SHA256, __import__("hashlib").sha256(LOADER).hexdigest()
+        self.addCleanup(setattr, ur, "LOADER_SHA256", sha)
+        self.assertEqual(ur.get_loader(str(bad)), LOADER)
+
+    def test_image_checks_and_exit_codes(self):
+        small = Path(self.tmp.name) / "short.bin"
+        small.write_bytes(b"x" * 1000)
+        err = io.StringIO()
+        with contextlib.redirect_stderr(err):
+            self.assertEqual(ur.main(["--image", str(small)]), 2)
+            self.assertEqual(ur.main(["--image", str(small) + ".missing"]), 1)
+            self.assertEqual(ur.main(["--package", str(small) + ".missing"]), 1)
+        self.assertIn("REFUSED", err.getvalue())
+
+    def test_check_reports_the_prerequisites(self):
+        r = subprocess.run([sys.executable, str(Path(ur.__file__)), "--check", "--package", str(Path(self.tmp.name) / "none.fwsc")],
+                           capture_output=True, text=True)
+        lines = r.stdout.splitlines()
+        self.assertTrue(any("libusb" in l for l in lines), r.stdout)
+        self.assertTrue(any(l.startswith("note official package not found") for l in lines), r.stdout)
+        self.assertEqual(r.returncode, 1 if any(l.startswith("FAIL") for l in lines) else 0)
+
+    # ---- the official package
+    @unittest.skipUnless(PACKAGE.exists(), "official BlackBox package not found")
+    def test_official_package(self):
+        image = ur.load_image(package=PACKAGE)
+        self.assertEqual(len(image), HI)
+        self.assertEqual(Window.for_image(len(image)), Window(0x4000, HI))
+        flash = bytearray(noise(4, ur.FLASH_SIZE))
+        flash[:0x4000] = image[:0x4000]
+        sim = uboot_sim.SimPedal(flash, LOADER)
+        n, _ = ur.rescue(lambda: sim, LOADER, image, True, self.backups, 1, self.logs.append, sim.clock)
+        self.assertEqual(bytes(sim.flash[:HI]), image)
+        broken = Path(self.tmp.name) / "broken.fwsc"
+        raw = bytearray(PACKAGE.read_bytes())
+        raw[len(raw) // 2] ^= 1
+        broken.write_bytes(raw)
+        self.assertRaises(RescueError, ur.load_image, package=broken)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=1)
diff --git a/tests/uboot_sim.py b/tests/uboot_sim.py
new file mode 100644
index 0000000..95b2fae
--- /dev/null
+++ b/tests/uboot_sim.py
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: GPL-3.0-only
+"""A simulated pedal in the JieLi UBOOT state, for tests/test_uboot_rescue.py (no hardware).
+
+It answers the mass-storage commands of the mask ROM and of the RAM loader the way the open tools document them, with a
+NOR flash (a write can only clear bits, an erase sets a 4 KiB sector to 0xFF), the loader's 3 s watchdog on a fake clock,
+and a switch that makes the pedal drop off the bus after N commands (to test resume). It keeps every command it saw.
+"""
+import struct
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "tools"))
+import uboot_rescue as ur
+from uboot_rescue import DeviceGone, ScsiError, crc16
+
+WATCHDOG = 3.0
+
+
+class FakeClock:
+    def __init__(self):
+        self.t = 100.0
+
+    def __call__(self):
+        return self.t
+
+
+class SimPedal:
+    def __init__(self, flash, loader, clock=None, key=0x980F, flash_id=0xEB6014, vendor="WL82", buffer=0x8000):
+        self.flash = bytearray(flash)
+        self.loader, self.key, self.flash_id, self.vendor, self.buffer = loader, key, flash_id, vendor, buffer
+        self.clock = clock or FakeClock()
+        self.seen = []            # (opcode, addr) of every command that reached the device
+        self.ram = bytearray(ur.LOADER_SIZE)
+        self.running = False      # the RAM loader is up
+        self.last = None
+        self.drop_at = None       # drop off the bus when this many commands have been seen in all
+        self.present = True
+        self.on_first_write = None
+        self._wrote = False
+
+    def reenumerate(self):
+        """The pedal rebooted and is in UBOOT again: the ROM only, the loader gone, the flash as it was left."""
+        self.running, self.ram, self.last, self.present, self.drop_at = False, bytearray(ur.LOADER_SIZE), None, True, None
+        return self
+
+    def close(self):
+        pass
+
+    def writes(self):
+        return [a for op, a in self.seen if op == ur.WRITE_FLASH]
+
+    def erases(self):
+        return [a for op, a in self.seen if op == ur.ERASE_SECTOR]
+
+    def execute(self, cdb, out, in_len, timeout=2000):
+        if not self.present:
+            raise DeviceGone("gone")
+        if self.drop_at is not None and len(self.seen) >= self.drop_at:
+            self.present = False
+            raise DeviceGone("gone")
+        self.clock.t += 0.002
+        if self.running and self.last is not None and self.clock.t - self.last > WATCHDOG:
+            self.running = False  # the loader reset the chip
+            self.present = False
+            raise DeviceGone("watchdog")
+        self.last = self.clock.t
+        if cdb[0] == 0x12:
+            return (b"\0\0\0\0\x1f\0\0\0" + self.vendor.encode().ljust(8) + b"UBOOT1.00".ljust(16) + b"1.00")[:in_len]
+        op = int.from_bytes(cdb[:2], "big")
+        self.seen.append((op, int.from_bytes(cdb[2:6], "big")))
+        a = cdb[2:]
+        reply = lambda body=b"": (cdb[:2] + body).ljust(16, b"\0")
+        if op == ur.WRITE_MEMORY:
+            addr, n = struct.unpack(">IH", a[:6])
+            off = addr - ur.LOADER_AT
+            if len(out) != n or crc16(out) != int.from_bytes(a[7:9], "little") or not 0 <= off <= len(self.ram) - n:
+                raise ScsiError("bad data")
+            self.ram[off:off + n] = out
+            return b""
+        if op == ur.JUMP:
+            addr = struct.unpack(">I", a[:4])[0]
+            self.running = addr == ur.LOADER_AT and bytes(self.ram[:len(self.loader)]) == self.loader
+            return reply()
+        if not self.running:
+            raise ScsiError("the loader is not running")
+        if op == ur.READ_KEY:
+            ks = ur.cipher(b"\0\0")
+            return reply(bytes([0, 0, 0, 0, (self.key >> 8) ^ ks[1], (self.key & 0xFF) ^ ks[0]]))
+        if op == ur.ONLINE_DEVICE:
+            return reply(bytes([3, 0]) + self.flash_id.to_bytes(4, "little"))
+        if op == ur.USB_BUFFER:
+            return reply(self.buffer.to_bytes(4, "big"))
+        if op == ur.READ_FLASH:
+            addr, n = struct.unpack(">IH", a[:6])
+            if n > self.buffer or addr + n > len(self.flash):
+                raise ScsiError("bad read")
+            return bytes(self.flash[addr:addr + n])
+        if op == ur.ERASE_SECTOR:
+            addr = struct.unpack(">I", a[:4])[0]
+            assert addr % ur.SECTOR == 0
+            self.flash[addr:addr + ur.SECTOR] = b"\xff" * ur.SECTOR
+            return reply()
+        if op == ur.WRITE_FLASH:
+            if not self._wrote and self.on_first_write:
+                self.on_first_write()
+            self._wrote = True
+            addr, n = struct.unpack(">IH", a[:6])
+            if len(out) != n or crc16(out) != int.from_bytes(a[7:9], "little"):
+                raise ScsiError("bad data")
+            for i, b in enumerate(out):
+                self.flash[addr + i] &= b
+            return b""
+        if op == ur.RUN_APP:
+            self.running, self.present = False, False
+            return reply()
+        raise ScsiError(f"unknown command {op:04X}")
diff --git a/tools/op.mjs b/tools/op.mjs
index 5159b78..9bf3f91 100644
--- a/tools/op.mjs
+++ b/tools/op.mjs
@@ -4,6 +4,8 @@
 // .bat files only call this. Every Docker command line lives here.
 //   node tools/op.mjs doctor | build | test | package | clean | shell | image | serve [editor|build]
 //   node tools/op.mjs render in.wav [out.wav] [preset]   |   node tools/op.mjs appimage [fm1-1.bin]
+//   node tools/op.mjs rescue [--write] [options]   (restore a looping BlackBox from its UBOOT state; read-only without --write; docs/RESCUE.md)
+//   node tools/op.mjs rescue-check   (the UBOOT rescue tool against a simulated pedal: Python 3 only, no Docker)
 // NATIVE=1 runs the commands on this machine (toolchain from firmware/setup.sh) instead of in the container.
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, rmSync } from "node:fs";
@@ -13,6 +15,7 @@ import { fileURLToPath } from "node:url";
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const IMAGE = "openpocket-build";
 const native = Boolean(process.env.NATIVE || process.env.OP_IN_CONTAINER);
+const python = process.platform === "win32" ? ["py", "-3"] : ["python3"];
 const OUTS = "firmware/openpocket.bin docs/firmware/*.fwsc docs/firmware/manifest.json";
 
 function fail(message) {
@@ -67,6 +70,9 @@ const commands = {
       const img = spawnSync("docker", ["image", "inspect", IMAGE], { stdio: "ignore" });
       console.log(img.status === 0 ? `ok   image ${IMAGE} is built` : `note image ${IMAGE} is not built yet: the first build or \`image\` makes it (about 1 minute)`);
     }
+    const rescue = spawnSync(python[0], [...python.slice(1), "tools/uboot_rescue.py", "--check"], { cwd: root, encoding: "utf8" });
+    if (rescue.error) console.log("note rescue (looping pedal): Python 3 not found, `make rescue` is unavailable");
+    else for (const l of rescue.stdout.split("\n").filter(Boolean)) console.log(l.startsWith("FAIL") ? `note rescue: ${l.slice(5)}` : `${l.slice(0, 4)} rescue: ${l.slice(5)}`);
     if (process.arch === "arm64") console.log("note ARM machine: the linux/amd64 toolchain runs under emulation (a `test` takes about 1 minute)");
     return bad;
   },
@@ -88,11 +94,23 @@ const commands = {
       const built = commands.build();
       if (built !== 0) return built;
     }
-    const py = process.platform === "win32" ? ["py", "-3"] : ["python3"];
+    const py = python;
     const r = spawnSync(py[0], [...py.slice(1), "tools/serve.py", arg === "editor" ? "editor.html" : "index.html"], { stdio: "inherit", cwd: root });
     if (r.error) fail("Python 3 is needed to serve the installer offline (python.org).");
     return r.status ?? 0;
   },
+  rescue(args) {                               // read-only unless --write; macOS needs root to take the pedal from its own driver
+    if (process.platform === "win32") fail("the rescue runs on macOS or Linux (it needs libusb and root). See docs/RESCUE.md.");
+    const root_ = typeof process.getuid === "function" && process.getuid() === 0;
+    const cmd = root_ || args.includes("--check") ? python : ["sudo", ...python];
+    if (cmd[0] === "sudo") console.log(`rescue: ${args.includes("--write") ? "WRITE" : "read-only"} run; sudo asks for your password, then the tool waits for the pedal in its UBOOT state`);
+    return exec(cmd[0], [...cmd.slice(1), "tools/uboot_rescue.py", ...args]);
+  },
+  "rescue-check"() {
+    const r = spawnSync(python[0], [...python.slice(1), "tests/test_uboot_rescue.py"], { stdio: "inherit", cwd: root });
+    if (r.error) fail("Python 3 is needed for the rescue tool tests (python.org).");
+    return r.status ?? 1;
+  },
   render([input, output, preset]) {
     if (!input) fail("usage: render in.wav [out.wav] [preset 1..52]");
     const rel = inside(input);
diff --git a/tools/pocketx_fw.py b/tools/pocketx_fw.py
index cb1b52e..948452a 100644
--- a/tools/pocketx_fw.py
+++ b/tools/pocketx_fw.py
@@ -155,30 +155,40 @@ def load(path):
     return raw, L, tag, u
 
 
+def package_checks(L, u):
+    """Every CRC of a package (UFW header and list, flash.bin and its JLFS entries, ota.bin, tail.bin) as {name: ok}."""
+    ok = ufw_checks(L, u)
+    for e in u["ents"]:
+        d = L[e["off"]:e["off"] + e["len"]]
+        if e["name"] == "flash.bin":
+            ok["flash.bin crc"] = crc16(d) == e["crc"]
+            dec = flash_decrypt(d)
+            ok.update(flash_checks(dec, flash_parse(dec)))
+        if e["name"] in ("ota.bin", "tail.bin"):
+            ok[f"{e['name']} crc"] = crc16(d) == e["crc"]
+    return ok
+
+
 def cmd_info(a):
     raw, L, tag, u = load(a.pkg)
     print(f"{a.pkg}: {len(raw)} B, identity {tag!r}, sha256 {hashlib.sha256(raw).hexdigest()[:16]}")
     print(f"UFW: chip {u['hdr'][16:22].decode()}, total {u['total']:#x}, {u['count']} entries")
-    ok = ufw_checks(L, u)
     for e in u["ents"]:
         d = L[e["off"]:e["off"] + e["len"]]
         print(f"  {e['name']:15s} type {e['type']:#06x} off {e['off']:#08x} len {e['len']:#08x} crc {e['crc']:04x}")
         if e["name"] == "flash.bin":
-            ok["flash.bin crc"] = crc16(d) == e["crc"]
             dec = flash_decrypt(d)
             fe = flash_parse(dec)
             for f in fe:
                 print(f"      {f['name']:15s} addr {f['addr']:#010x} len {f['len']:#08x} attr {f['attr']:#04x}")
-            ok.update(flash_checks(dec, fe))
             app = fe[1]
             a_ = dec[0x4000 + app["addr"]:0x4000 + app["addr"] + app["len"]]
             import re
             ver = [m.group().decode() for m in re.finditer(rb"[A-Za-z]+X?_\d{3}\b", a_)][:3]
             print(f"      app version strings: {ver}")
-        if e["name"] in ("ota.bin", "tail.bin"):
-            ok[f"{e['name']} crc"] = crc16(d) == e["crc"]
         if e["name"] == "script.ver":
             print(f"      -> {sfc(d, e['off']).decode('latin1')!r}")
+    ok = package_checks(L, u)
     bad = [k for k, v in ok.items() if not v]
     for k, v in ok.items():
         print(f"  [{'OK' if v else 'FAIL'}] {k}")
diff --git a/tools/uboot_rescue.py b/tools/uboot_rescue.py
new file mode 100644
index 0000000..a7fa8a7
--- /dev/null
+++ b/tools/uboot_rescue.py
@@ -0,0 +1,627 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-3.0-only
+"""uboot_rescue.py - restore the official firmware of a crash-looping M-VAVE BlackBox from a Mac, with no extra hardware.
+
+Between crashes the pedal sits about 44 s in the JieLi mask-ROM USB boot state (USB 4C4A:8057, "WL80UBOOT1.00"): a USB
+Mass Storage device with vendor SCSI commands. This tool waits for it, loads JieLi's RAM loader (wl82loader.bin) and
+rewrites the app area of the flash from the official package. See docs/RESCUE.md for the full walkthrough.
+
+  tools/uboot_rescue.py                      read-only: steps 1 to 4 below, nothing is ever written to the flash
+  tools/uboot_rescue.py --write              the rescue (needs the read-only run to have passed)
+  options: --package FILE.fwsc (default ~/Documents/BlackBox (2).fwsc, BlackBox_016)  |  --image flash.bin
+           --loader FILE  --backup-dir DIR (default ~/OpenPocket-rescue)  --attempts N (default 10)
+
+One-time install (macOS): `brew install libusb`. Nothing else: Python 3 and its standard library only (libusb is called
+through ctypes; no pip packages). macOS keeps its own mass-storage driver on the pedal, so libusb needs root to take the
+interface: start the tool with `sudo` (it waits for the pedal by itself, start it BEFORE the pedal reaches UBOOT).
+
+Steps, in this order (a rerun starts again at step 1 and resumes: only the sectors that still differ are written):
+  1 wait for 4C4A:8057 and start the moment it appears; SCSI INQUIRY must answer WL82 / UBOOT1.00
+  2 upload the pinned wl82loader.bin to RAM (SHA-256 checked) and run it; read the chip key (0x980F) and the flash id
+  3 back up the whole flash to a file, before anything is written
+  4 check that the pedal's flash [0, 0x4000) is the head of the image
+  5 --write only: for each 4 KiB sector in [0x4000, end of the image) that differs: erase, write, read back, compare
+  6 run-app: the pedal restarts into its firmware
+Guards that cannot be switched off: no write outside [0x4000, end of the image) with the end never above 0xFF000; a
+whitelist of loader commands (no chip erase FB02, no key burn FC12); the chip key and the flash size must match.
+"""
+import argparse, ctypes, ctypes.util, hashlib, os, pwd, struct, sys, time, urllib.request
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import pocketx_fw
+from pocketx_fw import crc16
+
+VID, PID = 0x4C4A, 0x8057
+LOADER_URL = ("https://raw.githubusercontent.com/kagaimiq/jl-uboot-tool/"
+              "c32b28e7a04f873f526ba929cb1bae9f05442fe9/data/loaderblobs/usb/wl82loader.bin")
+LOADER_SHA256 = "d41da6126760c9d66660bcc0cac8d27d221806c5e369a8036921efe68dca5376"
+LOADER_SIZE = 24064
+LOADER_AT = 0x1C02000
+CHIP_KEY = pocketx_fw.CHIPKEY
+FLASH_SIZE = 1 << 20
+SECTOR = 0x1000
+IO = 512
+WRITE_FROM = 0x4000
+WRITE_LIMIT = 0xFF000
+
+def user_home():
+    """The home of the person who typed sudo, not root's."""
+    name = os.environ.get("SUDO_USER")
+    return Path(pwd.getpwnam(name).pw_dir) if os.geteuid() == 0 and name else Path.home()
+
+
+def hand_back(path):
+    """Under sudo, give a file or folder we create back to the person who typed it."""
+    uid, gid = os.environ.get("SUDO_UID"), os.environ.get("SUDO_GID")
+    if os.geteuid() == 0 and uid and gid:
+        os.chown(path, int(uid), int(gid))
+
+
+def make_dir(path):
+    missing = [p for p in reversed(path.parents) if not p.exists()] + ([path] if not path.exists() else [])
+    path.mkdir(parents=True, exist_ok=True)
+    for p in missing:
+        hand_back(p)
+
+
+DEFAULT_PACKAGE = user_home() / "Documents" / "BlackBox (2).fwsc"
+DEFAULT_BACKUPS = user_home() / "OpenPocket-rescue"
+LOADER_CACHE = ROOT / "build" / "cache" / "wl82loader.bin"
+
+# the commands of the mask ROM and of the RAM loader (kagaimiq/jl-uboot-tool docs, fm1buddy), and the only ones this
+# tool can send
+WRITE_MEMORY, JUMP = 0xFB06, 0xFB08
+READ_KEY, ONLINE_DEVICE, USB_BUFFER, READ_FLASH, RUN_APP = 0xFC09, 0xFC0A, 0xFC14, 0xFD05, 0xFC0C
+ERASE_SECTOR, WRITE_FLASH = 0xFB01, 0xFB04
+READ_ONLY_OPS = frozenset({WRITE_MEMORY, JUMP, READ_KEY, ONLINE_DEVICE, USB_BUFFER, READ_FLASH, RUN_APP})
+WRITE_OPS = frozenset({ERASE_SECTOR, WRITE_FLASH})
+
+# JieLi "CrcDecode" cipher of the chip key answer (key 0xFFFFFFFF); the magic is "孟黎我爱你，玉林" in GB2312
+MAGIC = bytes.fromhex("c3cfc0e8ced2b0aec4e3a3acd3f1c1d6")
+
+
+class RescueError(Exception):
+    """Setup problem (no libusb, no access, no image): fix it and rerun."""
+
+
+class GuardError(Exception):
+    """A safety check refused to go on. Nothing more is sent to the pedal."""
+
+
+class ScsiError(Exception):
+    """A command failed; the pedal may be back after a reset."""
+
+
+class DeviceGone(ScsiError):
+    """The pedal left the bus (it rebooted)."""
+
+
+def cipher(data):
+    crc = crc16(b"\xff\xff", 0xFFFF)
+    out = bytearray(data)
+    for i in range(len(out)):
+        crc = crc16(MAGIC[i % 16:i % 16 + 1], crc)
+        out[i] ^= crc & 0xFF
+    return bytes(out)
+
+
+@dataclass(frozen=True)
+class Window:
+    """The only flash range this run may erase or write."""
+    lo: int
+    hi: int
+
+    @staticmethod
+    def for_image(size):
+        if size % SECTOR or not WRITE_FROM < size <= WRITE_LIMIT:
+            raise GuardError(f"the image is {size:#x} bytes: it must be whole 4 KiB sectors and end in "
+                             f"({WRITE_FROM:#x}, {WRITE_LIMIT:#x}]")
+        return Window(WRITE_FROM, size)
+
+    def holds(self, addr, n):
+        return self.lo <= addr and addr + n <= self.hi
+
+
+@dataclass
+class Chip:
+    key: int
+    flash_id: int
+    size: int
+    io: int
+
+
+class Uboot:
+    """The mask ROM / loader protocol over a mass-storage transport: msc.execute(cdb, out, in_len, timeout_ms) -> bytes.
+    Without a window nothing can be erased or written."""
+
+    def __init__(self, msc, window=None, clock=time.monotonic):
+        self.msc, self.window, self.clock = msc, window, clock
+
+    def _command(self, op, args, out=None, in_len=0, answer=False, tries=3, timeout=2000):
+        if op not in READ_ONLY_OPS and not (self.window and op in WRITE_OPS):
+            raise GuardError(f"command {op:04X} is not allowed in this run")
+        cdb = (op.to_bytes(2, "big") + args).ljust(16, b"\xff")
+        err = None
+        for _ in range(tries):
+            try:
+                data = self.msc.execute(cdb, out, 16 if answer else in_len, timeout)
+            except DeviceGone:
+                raise
+            except ScsiError as e:
+                err = e
+                continue
+            if answer and (len(data) != 16 or int.from_bytes(data[:2], "big") != op):
+                err = ScsiError(f"command {op:04X}: wrong answer")
+                continue
+            if not answer and len(data) != in_len:
+                err = ScsiError(f"command {op:04X}: {len(data)} of {in_len} bytes")
+                continue
+            return data[2:] if answer else data
+        raise err
+
+    def inquiry(self):
+        data = self.msc.execute(b"\x12\x00\x00\x00\x24\x00", None, 36, 1000)
+        text = lambda a, b: data[a:b].decode("ascii", "replace").strip()
+        return text(8, 16), text(16, 32), text(32, 36)
+
+    def mem_write(self, addr, data):
+        if not (LOADER_AT <= addr and addr + len(data) <= LOADER_AT + LOADER_SIZE):
+            raise GuardError(f"memory write at {addr:#x}: only the loader's RAM may be written")
+        crc = crc16(data)
+        self._command(WRITE_MEMORY, struct.pack(">IHB", addr, len(data), 0) + crc.to_bytes(2, "little"), out=data)
+
+    def jump(self):
+        try:  # the answer may be lost; the loader runs when READ_KEY answers
+            self._command(JUMP, struct.pack(">IH", LOADER_AT, 1), answer=True, tries=1)
+        except ScsiError:
+            pass
+
+    def chip_key(self):
+        a = self._command(READ_KEY, struct.pack(">I", 0xAC6900), answer=True)
+        k = cipher(bytes([a[5], a[4]]))
+        return k[0] | k[1] << 8
+
+    def online_device(self):
+        return int.from_bytes(self._command(ONLINE_DEVICE, b"", answer=True)[2:6], "little")
+
+    def usb_buffer(self):
+        return int.from_bytes(self._command(USB_BUFFER, b"", answer=True, tries=2, timeout=1000)[:4], "big")
+
+    keepalive = online_device
+
+    def flash_read(self, addr, n):
+        return self._command(READ_FLASH, struct.pack(">IH", addr, n), in_len=n)
+
+    def erase_sector(self, addr):
+        if self.window is None or addr % SECTOR or not self.window.holds(addr, SECTOR):
+            raise GuardError(f"erase at {addr:#x} refused")
+        self._command(ERASE_SECTOR, struct.pack(">I", addr), answer=True, timeout=5000)
+
+    def flash_write(self, addr, data):
+        if self.window is None or not data or (addr % SECTOR) + len(data) > SECTOR or not self.window.holds(addr, len(data)):
+            raise GuardError(f"write at {addr:#x} refused")
+        self._command(WRITE_FLASH, struct.pack(">IHB", addr, len(data), 0) + crc16(data).to_bytes(2, "little"), out=data)
+
+    def run_app(self):
+        try:  # it may restart before it answers
+            self._command(RUN_APP, struct.pack(">I", 1), answer=True, tries=1, timeout=500)
+        except ScsiError:
+            pass
+
+    def read_range(self, addr, n, io):
+        out = bytearray()
+        for a in range(addr, addr + n, io):
+            out += self.flash_read(a, min(io, addr + n - a))
+        return bytes(out)
+
+    def write_sector(self, addr, data):
+        """Erase, write in 512-byte pieces, read back and compare. NOR flash: a failed attempt is simply repeated."""
+        for attempt in range(3):
+            self.erase_sector(addr)
+            for off in range(0, SECTOR, IO):
+                self.flash_write(addr + off, data[off:off + IO])
+            if self.read_range(addr, SECTOR, IO) == data:
+                return
+        raise GuardError(f"sector {addr:#x} reads back differently after 3 attempts")
+
+
+def attach(dev, loader, log):
+    """Steps 1 and 2: INQUIRY, loader into RAM, run it, chip key and flash id. Refuses the wrong device, key or size."""
+    for _ in range(50):
+        try:
+            vendor, product, rev = dev.inquiry()
+            break
+        except DeviceGone:
+            raise
+        except ScsiError:
+            time.sleep(0.2)
+    else:
+        raise ScsiError("the pedal does not answer INQUIRY")
+    log(f"INQUIRY: {vendor} {product} {rev}")
+    if vendor != "WL82" or not product.startswith("UBOOT1.00"):
+        raise GuardError(f"this is not the WL82 UBOOT1.00 boot state ({vendor!r} {product!r})")
+    for off in range(0, len(loader), IO):
+        dev.mem_write(LOADER_AT + off, loader[off:off + IO])
+    key = None
+    for _ in range(3):
+        dev.jump()
+        try:
+            key = dev.chip_key()
+            break
+        except DeviceGone:
+            raise
+        except ScsiError:
+            pass
+    if key is None:
+        raise ScsiError("the loader did not start")
+    flash_id = dev.online_device()
+    size = 1 << (flash_id & 0xFF) if 0x10 <= flash_id & 0xFF <= 0x18 else 0
+    log(f"loader running: chip key {key:#06x}, flash id {flash_id:#08x} ({size // 1024} KiB)")
+    if key != CHIP_KEY:
+        raise GuardError(f"chip key {key:#06x} is not {CHIP_KEY:#06x}: this is not a BlackBox, nothing was written")
+    if size != FLASH_SIZE:
+        raise GuardError(f"flash id {flash_id:#08x} is not a 1 MiB flash: nothing was written")
+    io = IO
+    try:  # as big as the loader's USB buffer allows (fm1buddy: two readings of 1 MiB at 512 B took 8 s)
+        top = min(dev.usb_buffer(), 0x8000) // IO * IO
+    except ScsiError:
+        top = IO
+    while top > IO:
+        try:
+            if len(dev.flash_read(0, top)) == top:
+                io = top
+                break
+        except DeviceGone:
+            raise
+        except ScsiError:
+            pass
+        top //= 2
+    return Chip(key, flash_id, size, io)
+
+
+def rescue_pass(dev, loader, image, write, save_backup, log):
+    """One try at steps 1 to 6 on an open device. Returns the number of sectors that differ (and were written)."""
+    chip = attach(dev, loader, log)
+    flash = dev.read_range(0, chip.size, chip.io)
+    log(f"flash read: {len(flash) // 1024} KiB")
+    save_backup(flash)
+    dev.keepalive()
+    if flash[:WRITE_FROM] != image[:WRITE_FROM]:
+        raise GuardError("the flash head [0, 0x4000) is not the image's head: this package belongs to another layout; "
+                         "nothing was written")
+    log("head [0, 0x4000) matches the image")
+    window = dev.window or Window.for_image(len(image))
+    todo = [a for a in range(window.lo, window.hi, SECTOR) if flash[a:a + SECTOR] != image[a:a + SECTOR]]
+    log(f"{len(todo)} of {(window.hi - window.lo) // SECTOR} sectors in [{window.lo:#x}, {window.hi:#x}) differ")
+    if write:
+        for n, addr in enumerate(todo, 1):
+            dev.write_sector(addr, image[addr:addr + SECTOR])
+            if n % 16 == 0 or n == len(todo):
+                log(f"  written {n}/{len(todo)}")
+    dev.run_app()
+    log("run-app sent: the pedal restarts")
+    return len(todo)
+
+
+def rescue(open_device, loader, image, write, backup_dir, attempts, log, clock=time.monotonic):
+    """Run the passes until one completes (each pass is safe to repeat: only differing sectors are written)."""
+    saved = []
+
+    def save_backup(flash):
+        if saved:
+            return
+        make_dir(backup_dir)
+        path = backup_dir / f"blackbox-{datetime.now():%Y%m%d-%H%M%S}.dump.bin"
+        with open(path, "wb") as f:
+            f.write(flash)
+            f.flush()
+            os.fsync(f.fileno())
+        hand_back(path)
+        if path.stat().st_size != len(flash):
+            raise RescueError(f"the backup {path} is incomplete")
+        saved.append(path)
+        log(f"backup saved: {path}")
+
+    window = Window.for_image(len(image)) if write else None
+    for attempt in range(1, attempts + 1):
+        msc = open_device()
+        try:
+            return rescue_pass(Uboot(msc, window, clock), loader, image, write, save_backup, log), saved
+        except ScsiError as e:
+            log(f"the pedal went away or stopped answering ({e}); waiting for it again ({attempt}/{attempts})")
+        finally:
+            msc.close()
+    raise RescueError(f"gave up after {attempts} tries; rerun the command, it resumes where it stopped")
+
+
+# ---------------------------------------------------------------- the image and the loader
+def load_image(package=None, image=None):
+    """flash.bin of the official package (every CRC verified first) or a raw flash image."""
+    if image:
+        try:
+            data = Path(image).read_bytes()
+        except OSError as e:
+            raise RescueError(f"cannot read {image}: {e.strerror}")
+    else:
+        path = Path(package or DEFAULT_PACKAGE).expanduser()
+        if not path.exists():
+            raise RescueError(f"{path} not found: pass --package FILE.fwsc (the official BlackBox package) or --image flash.bin")
+        _, L, _, u = pocketx_fw.load(path)
+        bad = [k for k, v in pocketx_fw.package_checks(L, u).items() if not v]
+        if bad:
+            raise RescueError(f"{path}: CRC check failed ({', '.join(bad)}); not using it")
+        entry = next(e for e in u["ents"] if e["name"] == "flash.bin")
+        data = L[entry["off"]:entry["off"] + entry["len"]]
+    Window.for_image(len(data))
+    return data
+
+
+def get_loader(path=None):
+    """The pinned wl82loader.bin: --loader FILE, else the git-ignored cache, else downloaded; SHA-256 checked each time."""
+    def checked(blob, where):
+        if hashlib.sha256(blob).hexdigest() != LOADER_SHA256 or len(blob) != LOADER_SIZE:
+            raise RescueError(f"{where} is not the pinned wl82loader.bin (SHA-256 {LOADER_SHA256}); not using it")
+        return blob
+    if path:
+        try:
+            blob = Path(path).read_bytes()
+        except OSError as e:
+            raise RescueError(f"cannot read {path}: {e.strerror}")
+        return checked(blob, path)
+    if LOADER_CACHE.exists() and hashlib.sha256(LOADER_CACHE.read_bytes()).hexdigest() == LOADER_SHA256:
+        return LOADER_CACHE.read_bytes()
+    try:
+        with urllib.request.urlopen(LOADER_URL, timeout=30) as r:
+            blob = r.read()
+    except OSError as e:
+        raise RescueError(f"could not download the loader ({e}); download {LOADER_URL} and pass --loader FILE")
+    checked(blob, LOADER_URL)
+    make_dir(LOADER_CACHE.parent)
+    LOADER_CACHE.write_bytes(blob)
+    hand_back(LOADER_CACHE)
+    return blob
+
+
+# ---------------------------------------------------------------- USB: libusb through ctypes, Bulk-Only transport
+def cbw(tag, cdb, data_len, data_in):
+    return struct.pack("<4sIIBBB16s", b"USBC", tag, data_len, 0x80 if data_in else 0, 0, len(cdb), cdb.ljust(16, b"\0"))
+
+
+def parse_csw(raw, tag):
+    sig, rtag, residue, status = struct.unpack("<4sIIB", raw)
+    if sig != b"USBS" or rtag != tag:
+        raise ScsiError("bad status wrapper")
+    return residue, status
+
+
+def mass_storage_endpoints(config):
+    """(interface, bulk in, bulk out) of the Mass Storage / SCSI / Bulk-Only interface in a raw configuration descriptor."""
+    iface = None
+    eps = {}
+    i = 0
+    while i + 2 <= len(config) and config[i]:
+        kind = config[i + 1]
+        if kind == 4:
+            iface = config[i + 2] if config[i + 5:i + 8] == bytes([8, 6, 0x50]) else None
+        elif kind == 5 and iface is not None and config[i + 3] & 3 == 2:
+            eps["in" if config[i + 2] & 0x80 else "out"] = config[i + 2]
+        i += config[i]
+    if iface is None or len(eps) != 2:
+        raise RescueError("no Mass Storage Bulk-Only interface found on the device")
+    return iface, eps["in"], eps["out"]
+
+
+class DevDesc(ctypes.Structure):
+    _fields_ = [("bLength", ctypes.c_uint8), ("bDescriptorType", ctypes.c_uint8), ("bcdUSB", ctypes.c_uint16),
+                ("bDeviceClass", ctypes.c_uint8), ("bDeviceSubClass", ctypes.c_uint8), ("bDeviceProtocol", ctypes.c_uint8),
+                ("bMaxPacketSize0", ctypes.c_uint8), ("idVendor", ctypes.c_uint16), ("idProduct", ctypes.c_uint16),
+                ("bcdDevice", ctypes.c_uint16), ("iManufacturer", ctypes.c_uint8), ("iProduct", ctypes.c_uint8),
+                ("iSerialNumber", ctypes.c_uint8), ("bNumConfigurations", ctypes.c_uint8)]
+
+
+E_ACCESS, E_NO_DEVICE, E_BUSY, E_TIMEOUT, E_PIPE, E_NOT_SUPPORTED = -3, -4, -6, -7, -9, -12
+SUDO_HINT = ("macOS keeps its mass-storage driver on the pedal and libusb needs root to take the interface: run the "
+             "command again with sudo in front of it (docs/RESCUE.md)")
+ROOT_HINT = ("macOS did not let go of the pedal even for root. Nothing was sent to it; send this output to whoever helps "
+             "you (the other routes are in docs/RESCUE.md)")
+
+
+class Libusb:
+    def __init__(self):
+        self.lib = self._load()
+        v, p, i, u8, u16 = ctypes.c_void_p, ctypes.POINTER, ctypes.c_int, ctypes.c_uint8, ctypes.c_uint16
+        sig = {"libusb_init": ([p(v)], i), "libusb_exit": ([v], None), "libusb_get_device_list": ([v, p(p(v))], ctypes.c_ssize_t),
+               "libusb_free_device_list": ([p(v), i], None), "libusb_get_device_descriptor": ([v, p(DevDesc)], i),
+               "libusb_open": ([v, p(v)], i), "libusb_close": ([v], None), "libusb_detach_kernel_driver": ([v, i], i),
+               "libusb_claim_interface": ([v, i], i), "libusb_release_interface": ([v, i], i),
+               "libusb_clear_halt": ([v, u8], i), "libusb_error_name": ([i], ctypes.c_char_p),
+               "libusb_control_transfer": ([v, u8, u8, u16, u16, v, u16, ctypes.c_uint], i),
+               "libusb_bulk_transfer": ([v, u8, v, i, p(i), ctypes.c_uint], i)}
+        for name, (args, res) in sig.items():
+            f = getattr(self.lib, name)
+            f.argtypes, f.restype = args, res
+        self.ctx = ctypes.c_void_p()
+        self.check(self.lib.libusb_init(ctypes.byref(self.ctx)), "libusb_init")
+
+    @staticmethod
+    def _load():
+        for path in [os.environ.get("LIBUSB_PATH"), "/opt/homebrew/lib/libusb-1.0.dylib", "/usr/local/lib/libusb-1.0.dylib"]:
+            if path and os.path.exists(path):
+                return ctypes.CDLL(path)
+        if ctypes.util.find_library("usb-1.0"):
+            return ctypes.CDLL(ctypes.util.find_library("usb-1.0"))
+        raise RescueError("libusb not found: run `brew install libusb` once (or set LIBUSB_PATH)")
+
+    def name(self, code):
+        return self.lib.libusb_error_name(code).decode()
+
+    def check(self, code, what):
+        if code < 0:
+            raise RescueError(f"{what}: {self.name(code)}")
+        return code
+
+    def open_pedal(self):
+        """A claimed Bulk-Only transport to the pedal, or None when it is not on the bus (yet)."""
+        devs = ctypes.POINTER(ctypes.c_void_p)()
+        n = self.lib.libusb_get_device_list(self.ctx, ctypes.byref(devs))
+        try:
+            for i in range(max(n, 0)):
+                desc = DevDesc()
+                if self.lib.libusb_get_device_descriptor(devs[i], ctypes.byref(desc)) == 0 and (desc.idVendor, desc.idProduct) == (VID, PID):
+                    return self._claim(devs[i])
+        finally:
+            self.lib.libusb_free_device_list(devs, 1)
+        return None
+
+    def _claim(self, dev):
+        handle = ctypes.c_void_p()
+        code = self.lib.libusb_open(dev, ctypes.byref(handle))
+        if code in (E_ACCESS, E_BUSY, E_NOT_SUPPORTED):
+            raise RescueError(f"cannot open the pedal ({self.name(code)}). {ROOT_HINT if os.geteuid() == 0 else SUDO_HINT}")
+        if code < 0:
+            return None
+        buf = ctypes.create_string_buffer(512)
+        got = self.lib.libusb_control_transfer(handle, 0x80, 6, 2 << 8, 0, buf, 512, 1000)
+        if got < 9:
+            self.lib.libusb_close(handle)
+            return None
+        iface, ep_in, ep_out = mass_storage_endpoints(buf.raw[:got])
+        self.lib.libusb_detach_kernel_driver(handle, iface)  # macOS: root (or an entitlement); other codes are fine here
+        code = self.lib.libusb_claim_interface(handle, iface)
+        if code in (E_ACCESS, E_BUSY, E_NOT_SUPPORTED):
+            self.lib.libusb_close(handle)
+            raise RescueError(f"cannot take the interface from macOS ({self.name(code)}). {ROOT_HINT if os.geteuid() == 0 else SUDO_HINT}")
+        if code < 0:
+            self.lib.libusb_close(handle)
+            return None
+        return LibusbMsc(self, handle, iface, ep_in, ep_out)
+
+
+class LibusbMsc:
+    def __init__(self, usb, handle, iface, ep_in, ep_out):
+        self.usb, self.lib, self.handle, self.iface, self.ep_in, self.ep_out = usb, usb.lib, handle, iface, ep_in, ep_out
+        self.tag = 0
+
+    def close(self):
+        self.lib.libusb_release_interface(self.handle, self.iface)
+        self.lib.libusb_close(self.handle)
+
+    def _bulk(self, ep, data, n, timeout):
+        buf = ctypes.create_string_buffer(data, n) if data is not None else ctypes.create_string_buffer(n)
+        done = ctypes.c_int()
+        code = self.lib.libusb_bulk_transfer(self.handle, ep, buf, n, ctypes.byref(done), timeout)
+        if code == E_NO_DEVICE:
+            raise DeviceGone("the pedal left the bus")
+        if code == E_PIPE:
+            self.lib.libusb_clear_halt(self.handle, ep)
+        if code < 0:
+            raise ScsiError(f"USB transfer: {self.usb.name(code)}")
+        return buf.raw[:done.value]
+
+    def execute(self, cdb, out, in_len, timeout=2000):
+        self.tag += 1
+        data_len = len(out) if out is not None else in_len
+        self._bulk(self.ep_out, cbw(self.tag, cdb, data_len, out is None and in_len > 0), 31, timeout)
+        data = b""
+        stalled = False
+        try:
+            if out is not None:
+                self._bulk(self.ep_out, out, len(out), timeout)
+            elif in_len:
+                data = self._bulk(self.ep_in, None, in_len, timeout)
+        except DeviceGone:
+            raise
+        except ScsiError:
+            stalled = True
+        try:
+            _, status = parse_csw(self._bulk(self.ep_in, None, 13, timeout), self.tag)
+        except ScsiError:
+            raise ScsiError("no status after the command")
+        if status or stalled:
+            raise ScsiError("command failed")
+        return data
+
+
+def wait_for_pedal(usb, log):
+    """Poll until 4C4A:8057 is on the bus; claim it at once (the UBOOT window is only about 44 s)."""
+    announced = False
+    while True:
+        msc = usb.open_pedal()
+        if msc:
+            return msc
+        if not announced:
+            log("waiting for the pedal in its UBOOT state (USB 4C4A:8057; plug it straight into this Mac)")
+            announced = True
+        time.sleep(0.05)
+
+
+def check(a):
+    """Prerequisites, one line each, for `op.mjs doctor`; exit 1 only when the tool cannot run at all."""
+    bad = 0
+    try:
+        Libusb()
+        print("ok   libusb found")
+    except RescueError as e:
+        print(f"FAIL {e}")
+        bad = 1
+    package = Path(a.package or DEFAULT_PACKAGE).expanduser()
+    print(f"ok   official package {package}" if a.image or package.exists() else
+          f"note official package not found at {package}: pass --package FILE.fwsc (the BlackBox package from M-VAVE)")
+    print("ok   wl82loader.bin cached" if LOADER_CACHE.exists() else "note wl82loader.bin is downloaded on the first run (SHA-256 checked)")
+    if os.geteuid() != 0:
+        print("note the rescue needs root to take the pedal from macOS's mass-storage driver: `make rescue` asks for your password (sudo)")
+    return bad
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="Restore the official firmware of a crash-looping BlackBox from its UBOOT state.")
+    ap.add_argument("--check", action="store_true", help="only check the prerequisites (libusb, package, loader, root) and exit")
+    ap.add_argument("--write", action="store_true", help="really write the flash (default: read-only, steps 1 to 4)")
+    src = ap.add_mutually_exclusive_group()
+    src.add_argument("--package", help="official .fwsc package (default ~/Documents/BlackBox (2).fwsc)")
+    src.add_argument("--image", help="raw flash image (flash.bin) instead of a package")
+    ap.add_argument("--loader", help="wl82loader.bin (default: download once into build/cache/)")
+    ap.add_argument("--backup-dir", default=str(DEFAULT_BACKUPS), help="where the flash backup goes (default ~/OpenPocket-rescue)")
+    ap.add_argument("--attempts", type=int, default=10, help="UBOOT windows to try before giving up (default 10)")
+    a = ap.parse_args(argv)
+    if a.check:
+        return check(a)
+
+    t0 = [time.monotonic()]
+    log = lambda m: print(f"[{time.monotonic() - t0[0]:6.1f}s] {m}", flush=True)
+    try:
+        image = load_image(a.package, a.image)
+        loader = get_loader(a.loader)
+        log(f"image {len(image):#x} bytes, loader {LOADER_SHA256[:8]}... verified; "
+            + ("WRITE mode" if a.write else "read-only mode: nothing will be written"))
+        usb = Libusb()
+
+        def open_device():
+            msc = wait_for_pedal(usb, log)
+            t0[0] = time.monotonic()
+            log("pedal found")
+            return msc
+
+        n, saved = rescue(open_device, loader, image, a.write, Path(a.backup_dir).expanduser(), a.attempts, log)
+    except GuardError as e:
+        print(f"\nREFUSED: {e}", file=sys.stderr)
+        return 2
+    except RescueError as e:
+        print(f"\nERROR: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\nstopped; rerunning resumes where it stopped", file=sys.stderr)
+        return 130
+    if a.write:
+        print(f"\nDone: {n} sectors written and verified. Power-cycle the pedal. Backup: {saved[0]}")
+    else:
+        print(f"\nRead-only run finished, nothing was written. {n} sectors differ from the image. Backup: {saved[0]}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())