From 7a29a11a2c78a7ec44ab89940d0fdaeee40ac753 Mon Sep 17 00:00:00 2001
From: Vince Speelman <vince.speelman@popstroke.com>
Date: Thu, 5 Nov 2026 21:27:32 -0500
Subject: [PATCH 1/4] feat(tools): add a Mac-side UBOOT rescue tool for a
 crash-looping BlackBox

tools/uboot_rescue.py waits for the pedal in its JieLi mask-ROM USB boot state (4C4A:8057),
loads the pinned wl82loader.bin into RAM, backs up the whole flash, checks the head against
the official package and, only with --write, rewrites the differing 4 KiB sectors in
[0x4000, end of image) with read-back. It is read-only by default, whitelists the loader
commands (no chip erase, no key burn), refuses a wrong chip key or flash size, and resumes
on rerun. libusb is called through ctypes; no pip packages.

Tested against a simulated UBOOT pedal (make rescue-check, part of make test); the protocol
has not yet been run on the real pedal beyond finding it and reading its descriptor.
---
 Makefile                   |   5 +-
 README.md                  |   2 +-
 docs/BUILDING.md           |   1 +
 docs/RESCUE.md             |  83 +++++
 tests/run_tests.sh         |   3 +
 tests/test_op.mjs          |   4 +
 tests/test_uboot_rescue.py | 255 ++++++++++++++++
 tests/uboot_sim.py         | 116 +++++++
 tools/op.mjs               |   7 +
 tools/pocketx_fw.py        |  20 +-
 tools/uboot_rescue.py      | 611 +++++++++++++++++++++++++++++++++++++
 11 files changed, 1099 insertions(+), 8 deletions(-)
 create mode 100644 docs/RESCUE.md
 create mode 100644 tests/test_uboot_rescue.py
 create mode 100644 tests/uboot_sim.py
 create mode 100644 tools/uboot_rescue.py

diff --git a/Makefile b/Makefile
index 591ee81..65eec47 100644
--- a/Makefile
+++ b/Makefile
@@ -10,9 +10,10 @@
 #   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-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-check
+doctor build test package clean shell image serve rescue-check:
 	@node tools/op.mjs $@
 render:
 	@node tools/op.mjs render "$(IN)" "$(OUT)" "$(PRESET)"
diff --git a/README.md b/README.md
index 5e58bde..6e23bb5 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ 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,
+used by Felucca, CLIPPER and SLOOP. A pedal that loops can also be restored from a Mac with no extra hardware (`docs/RESCUE.md`, `tools/uboot_rescue.py`). Keep the SD-card recovery at hand (`flash/`: fm1buddy on an ESP32-S3,
 `makeimage.bat`).
 
 **Without internet**: double-click `INSTALL-OFFLINE.bat` (Windows; nothing to install: a small PowerShell server,
diff --git a/docs/BUILDING.md b/docs/BUILDING.md
index de42e5f..c033441 100644
--- a/docs/BUILDING.md
+++ b/docs/BUILDING.md
@@ -35,6 +35,7 @@ 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-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..bb24baf
--- /dev/null
+++ b/docs/RESCUE.md
@@ -0,0 +1,83 @@
+# 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 two commands
+
+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.
+
+```
+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:
+
+```
+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: `--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.
+
+## 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/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..8dc54fc 100644
--- a/tests/test_op.mjs
+++ b/tests/test_op.mjs
@@ -117,6 +117,10 @@ 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");
 } 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..60879b7
--- /dev/null
+++ b/tests/test_uboot_rescue.py
@@ -0,0 +1,255 @@
+#!/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, 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())
+
+    # ---- 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..4d3481a 100644
--- a/tools/op.mjs
+++ b/tools/op.mjs
@@ -4,6 +4,7 @@
 // .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-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";
@@ -93,6 +94,12 @@ const commands = {
     if (r.error) fail("Python 3 is needed to serve the installer offline (python.org).");
     return r.status ?? 0;
   },
+  "rescue-check"() {
+    const py = process.platform === "win32" ? ["py", "-3"] : ["python3"];
+    const r = spawnSync(py[0], [...py.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..677cd3a
--- /dev/null
+++ b/tools/uboot_rescue.py
@@ -0,0 +1,611 @@
+#!/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
+MAX_GAP = 2.0  # the loader resets the chip after about 3 s without a command
+
+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
+        self.last = None
+        self.max_gap = 0.0
+
+    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):
+            now = self.clock()
+            if self.last is not None:
+                self.max_gap = max(self.max_gap, now - self.last)
+            try:
+                data = self.msc.execute(cdb, out, 16 if answer else in_len, timeout)
+            except DeviceGone:
+                raise
+            except ScsiError as e:
+                err = e
+                continue
+            finally:
+                self.last = self.clock()
+            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)
+        self.last = self.clock()
+        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:
+        return checked(Path(path).read_bytes(), 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 main(argv=None):
+    ap = argparse.ArgumentParser(description="Restore the official firmware of a crash-looping BlackBox from its UBOOT state.")
+    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)
+
+    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())

From 36f539f0738f512992d4d9dad76b5b6057b91dd4 Mon Sep 17 00:00:00 2001
From: Vince Speelman <vince.speelman@popstroke.com>
Date: Thu, 5 Nov 2026 21:28:56 -0500
Subject: [PATCH 2/4] no-mistakes(review): Report unreadable --loader file as
 RescueError

---
 tools/uboot_rescue.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/tools/uboot_rescue.py b/tools/uboot_rescue.py
index 677cd3a..c746606 100644
--- a/tools/uboot_rescue.py
+++ b/tools/uboot_rescue.py
@@ -376,7 +376,11 @@ def checked(blob, where):
             raise RescueError(f"{where} is not the pinned wl82loader.bin (SHA-256 {LOADER_SHA256}); not using it")
         return blob
     if path:
-        return checked(Path(path).read_bytes(), 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:

From bad4b3516eb1312ffdf5575bbb84b4eec177f201 Mon Sep 17 00:00:00 2001
From: Vince Speelman <vince.speelman@popstroke.com>
Date: Thu, 5 Nov 2026 21:37:59 -0500
Subject: [PATCH 3/4] feat(rescue): make the rescue a first-class command
 (op.mjs rescue, make rescue, make rescue-write)

node tools/op.mjs rescue [--write] runs tools/uboot_rescue.py through sudo, read-only unless
--write; make rescue and make rescue-write call it. op.mjs doctor now reports the rescue
prerequisites (libusb, official package, cached loader, root) through uboot_rescue.py --check.

docs/RESCUE.md records what the captain's first real run left behind (two identical pre-write
backups: BlackBox_936, head matching, 159 of 160 sectors differing) and marks the rest unknown.
The installer page and the README point a looping pedal at the Mac route first and the SD-card
route second. A new project skill, openpocket-rescue, tells an agent when and how to rescue,
the safety rules and who runs the sudo write. tests/test_op.mjs covers the op.mjs and Makefile
wiring and the doctor call; test_uboot_rescue.py covers --check.
---
 .claude/skills/openpocket-rescue/SKILL.md | 68 +++++++++++++++++++++++
 Makefile                                  |  8 ++-
 README.md                                 |  5 +-
 docs/BUILDING.md                          |  1 +
 docs/RESCUE.md                            | 29 ++++++++--
 docs/index.html                           |  2 +
 tests/test_op.mjs                         | 31 +++++++++++
 tests/test_uboot_rescue.py                | 10 +++-
 tools/op.mjs                              | 17 +++++-
 tools/uboot_rescue.py                     | 21 +++++++
 10 files changed, 181 insertions(+), 11 deletions(-)
 create mode 100644 .claude/skills/openpocket-rescue/SKILL.md

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 65eec47..c5146a2 100644
--- a/Makefile
+++ b/Makefile
@@ -10,12 +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 rescue-check
+.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 6e23bb5..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. A pedal that loops can also be restored from a Mac with no extra hardware (`docs/RESCUE.md`, `tools/uboot_rescue.py`). 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 c033441..14600c4 100644
--- a/docs/BUILDING.md
+++ b/docs/BUILDING.md
@@ -35,6 +35,7 @@ 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
diff --git a/docs/RESCUE.md b/docs/RESCUE.md
index bb24baf..971829e 100644
--- a/docs/RESCUE.md
+++ b/docs/RESCUE.md
@@ -20,7 +20,11 @@ That is all. The tool is one Python 3 file that calls libusb through `ctypes` (n
   `d41da6126760c9d66660bcc0cac8d27d221806c5e369a8036921efe68dca5376` on every run. It is not in this repository. `make clean`
   removes the cache; `--loader FILE` uses a copy you downloaded yourself.
 
-## The two commands
+## 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
@@ -29,7 +33,7 @@ it appears.
 1. **Read-only first.** Nothing is written to the pedal's flash; the loader goes to RAM only.
 
 ```
-sudo python3 tools/uboot_rescue.py
+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
@@ -40,7 +44,7 @@ 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:
 
 ```
-sudo python3 tools/uboot_rescue.py --write
+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
@@ -48,9 +52,26 @@ Same steps, then for every 4 KiB sector in `[0x4000, 0xA3000)` that differs: era
 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: `--package`, `--image`, `--loader`, `--backup-dir DIR`, `--attempts N` (UBOOT windows to try, default 10).
+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`.
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/test_op.mjs b/tests/test_op.mjs
index 8dc54fc..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 });
@@ -121,6 +145,13 @@ if (make.status === 0) {
   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
index 60879b7..1ac7a67 100644
--- a/tests/test_uboot_rescue.py
+++ b/tests/test_uboot_rescue.py
@@ -3,7 +3,7 @@
 """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, sys, tempfile, unittest
+import contextlib, io, os, random, subprocess, sys, tempfile, unittest
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
@@ -233,6 +233,14 @@ def test_image_checks_and_exit_codes(self):
             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):
diff --git a/tools/op.mjs b/tools/op.mjs
index 4d3481a..9bf3f91 100644
--- a/tools/op.mjs
+++ b/tools/op.mjs
@@ -4,6 +4,7 @@
 // .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";
@@ -14,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) {
@@ -68,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;
   },
@@ -89,14 +94,20 @@ 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 py = process.platform === "win32" ? ["py", "-3"] : ["python3"];
-    const r = spawnSync(py[0], [...py.slice(1), "tests/test_uboot_rescue.py"], { stdio: "inherit", cwd: root });
+    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;
   },
diff --git a/tools/uboot_rescue.py b/tools/uboot_rescue.py
index c746606..7326a77 100644
--- a/tools/uboot_rescue.py
+++ b/tools/uboot_rescue.py
@@ -568,8 +568,27 @@ def wait_for_pedal(usb, log):
         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)")
@@ -578,6 +597,8 @@ def main(argv=None):
     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)

From e254dfef3abe1cb012536c2500677d0db422ed98 Mon Sep 17 00:00:00 2001
From: Vince Speelman <vince.speelman@popstroke.com>
Date: Thu, 5 Nov 2026 21:40:53 -0500
Subject: [PATCH 4/4] no-mistakes(review): Remove unused rescue gap tracking

---
 tools/uboot_rescue.py | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/tools/uboot_rescue.py b/tools/uboot_rescue.py
index 7326a77..a7fa8a7 100644
--- a/tools/uboot_rescue.py
+++ b/tools/uboot_rescue.py
@@ -47,7 +47,6 @@
 IO = 512
 WRITE_FROM = 0x4000
 WRITE_LIMIT = 0xFF000
-MAX_GAP = 2.0  # the loader resets the chip after about 3 s without a command
 
 def user_home():
     """The home of the person who typed sudo, not root's."""
@@ -141,8 +140,6 @@ class Uboot:
 
     def __init__(self, msc, window=None, clock=time.monotonic):
         self.msc, self.window, self.clock = msc, window, clock
-        self.last = None
-        self.max_gap = 0.0
 
     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):
@@ -150,9 +147,6 @@ def _command(self, op, args, out=None, in_len=0, answer=False, tries=3, timeout=
         cdb = (op.to_bytes(2, "big") + args).ljust(16, b"\xff")
         err = None
         for _ in range(tries):
-            now = self.clock()
-            if self.last is not None:
-                self.max_gap = max(self.max_gap, now - self.last)
             try:
                 data = self.msc.execute(cdb, out, 16 if answer else in_len, timeout)
             except DeviceGone:
@@ -160,8 +154,6 @@ def _command(self, op, args, out=None, in_len=0, answer=False, tries=3, timeout=
             except ScsiError as e:
                 err = e
                 continue
-            finally:
-                self.last = self.clock()
             if answer and (len(data) != 16 or int.from_bytes(data[:2], "big") != op):
                 err = ScsiError(f"command {op:04X}: wrong answer")
                 continue
@@ -173,7 +165,6 @@ def _command(self, op, args, out=None, in_len=0, answer=False, tries=3, timeout=
 
     def inquiry(self):
         data = self.msc.execute(b"\x12\x00\x00\x00\x24\x00", None, 36, 1000)
-        self.last = self.clock()
         text = lambda a, b: data[a:b].decode("ascii", "replace").strip()
         return text(8, 16), text(16, 32), text(32, 36)